Guide: hand Claude Code or Codex a task and walk away
This guide is for someone who wants to give an external coding agent one task, leave, and come back to a patch they can trust or reject. At the end you will have:
- a run of Claude Code or Codex that happened inside skep's OS sandbox,
- skep's own re-run of your project's test command on a clean checkout,
- the patch held for your approval, and after approval a branch named
skep/<task_id>(and a pull request if you ask for one).
Your default branch does not move at any point in this guide.
What you need first
- skep 1.4.2 or newer:
pipx install skep, thenskep --version. - macOS or Linux. On Linux the sandbox needs bubblewrap:
sudo dnf install bubblewraporsudo apt install bubblewrap. - The agent's own CLI on your
PATH:claude(Claude Code) orcodex. - A credential for that agent that you can put in an environment variable (step 2).
- A git repository with at least one commit, and a command that proves the
work: one that exits non-zero when the code is broken and that runs on a
clean checkout of the repository (
pytest,npm test,make test).
The examples use a repository at ~/code/calc whose test suite has one failing
test.
1. Check the sandbox and the engine
skep doctor
On a fresh home with nothing configured, the relevant lines are:
- engine claude_code: NO AUTH ENV — set one of CLAUDE_CODE_OAUTH_TOKEN/ANTHROPIC_API_KEY — /home/you/.local/bin/claude (sandbox-confined; needs verify_command)
- engine codex: NO AUTH ENV — set one of OPENAI_API_KEY — /home/you/.nvm/versions/node/v24.15.0/bin/codex (sandbox-confined; needs verify_command)
...
Runtime checks:
- sandbox: ready - bubblewrap backend is usable. Landlock ABI 10: a worker connects only to unix sockets in its own roots or ones it made itself.
Three things to read:
sandbox: ready. If it says anything else, stop here. An external agent runs only inside the sandbox, and skep refuses the run rather than start it unconfined. On Linux the usual cause is thatbwrapis not installed.- The engine line.
MISSINGmeans the agent's CLI is not onPATH.NO AUTH ENVis what step 2 fixes.(sandbox-confined; needs verify_command)is what step 3 fixes. Skep: blockedandprofile: blockedat the top are about the chat assistant's own model. The runs in this guide do not use it; every command below was run on a home where those lines were still showing.
2. Put the agent's credential in the environment
The agent's normal login (the keychain, ~/.claude/.credentials.json,
~/.codex/auth.json) is hidden from every sandboxed worker, so the credential
has to arrive as an environment variable in the shell you run skep from.
| Engine | Set one of | Where it comes from |
|---|---|---|
claude_code |
CLAUDE_CODE_OAUTH_TOKEN |
claude setup-token prints it (uses your Claude plan) |
claude_code |
ANTHROPIC_API_KEY |
an API key (billed per token) |
codex |
OPENAI_API_KEY |
an API key |
export CLAUDE_CODE_OAUTH_TOKEN=paste-the-token-here
Codex can instead use a ChatGPT plan login, which is a per-project opt-in:
see codex-chatgpt-login.md.
Run skep doctor again. The engine line should now start with ok.
3. Register the project with its engine and its verify command
An external agent needs a project that names the engine and pins the command that proves the work. Give the strategy in the same command. Without it, on a repository that is not yet a project, setup fails:
skep project setup ~/code/calc --engine claude_code
error: project setup requires a pack or strategy
The order that works is one command with --strategy:
skep project setup ~/code/calc --strategy trusted_local_dev \
--engine claude_code --verify-command "python -m pytest -q"
saved: calc (trusted_local_dev/build)
pack: -
bindings: repo_path=/home/you/code/calc
seeded templates: 0
seeded schedules: 1
calc-maintain-weekly
seeded shell commands: 2
uv run pytest
pytest
verify command: python -m pytest -q
coding engine: claude_code
loopback ports: closed (--loopback-port PORT opens one)
What this saved:
trusted_local_dev/build. The strategy for your own repository, in thebuildphase, where landing a patch needs your approval.verify command. The command skep itself re-runs after the agent finishes. Leave--verify-commandout and setup infers one from the repository (make test,uv run pytest,pytestornpm test); check the line says what you expect. More inguide-pin-verify-command.md.seeded schedules: 1. Setup also created a weekly maintenance schedule. It runs only if you runskep tickorskep serve. If you do not want it, pass--no-seed-schedulesto setup, or remove it:skep schedule remove calc-maintain-weekly.
Once the project exists, later changes need no --strategy:
skep project setup ~/code/calc --engine codex changes only the engine.
skep project show calc prints the saved policy.
4. Know what a home without a policy baseline does
skep policy baseline status
baseline: none approved
A home created by a fresh install answers ask to policy questions until you
approve a baseline. For this guide that matters less than it sounds:
-
A plain
skep run, as in step 5, is not held up. It was run on a home with no baseline for this guide and dispatched normally. -
A run with
--roleor--delegated-byis refused off a terminal, because nothing could answer its questions once it is going:error: this home has no approved policy baseline, so this run would ask about files.pythonhosted.org, proxy.golang.org, pypi.org, registry.npmjs.org and nothing could answer once it runs; name the hosts to answer for this run only in --answer-host HOST (repeatable), or approve a baseline (skep policy approve) -
skep project setup --unlockedis refused until a baseline is approved. -
skep policy why, the Claude Code hook, the ACP governor and the chat assistant all answeraskwith the reasonno_baseline.
To approve one, read a template and lock it:
skep policy explain builder
skep policy approve --template builder
approve prints the same table and waits for you to type yes
(--yes skips the prompt). Afterwards:
baseline: builder approved 2026-11-19T00:25:43Z sha256 01db10ac4fc3
skep onboard does the same as one of its five steps
(onboarding.md).
5. Run the task and leave
skep run ~/code/calc "make the failing test pass" --execution-mode sandbox
An external agent always runs in the sandbox: for a project that pins one,
--execution-mode workspace is turned into sandbox.
If the credential from step 2 is not in this shell, nothing starts:
error: coding_engine 'claude_code': NO AUTH ENV — set one of CLAUDE_CODE_OAUTH_TOKEN/ANTHROPIC_API_KEY in the environment the worker inherits (the daemon reads <home>/serve.env at startup; `skep run` uses your shell) — the line `skep doctor` prints for this engine
next: skep doctor # engines, auth env, sandbox
The exit code is 2 and no run was recorded. This is the furthest this guide's author could go without a credential. What follows is what the code prints once the credential is there.
While the agent works, skep prints one line per phase: the worker starting
(with the project, the dispatch decision and landing: require_approval), then
what the agent reported, then skep's own re-verification:
→ re-verify: passed [confirmed] worker passed re-ran clean: all exit 0 [command from the project's pinned verify_command] re-ran python -m pytest -q -> exit 0
and finally a summary block:
task <task_id>
state: completed (<seconds>s)
verification: confirmed by re-verify (G10) — re-ran python -m pytest -q → exit 0
worker claim: passed — <the agent's summary>
evidence: /home/you/.skep/supervisor/audit/<task_id>
next: skep review <task_id>
You do not have to watch. The run is bounded by its budget
(--budget-wall-clock SECONDS changes the wall-clock limit), and
--quiet drops the live lines and keeps the summary block. To start it from
cron instead of a terminal, see
guide-dispatch-from-cron.md.
Exit codes of skep run: 0 completed, 2 refused before starting, 3
failed, 4 waiting for an approval, 5 rejected, 6 timed out, 7 the
worker crashed. 0 means the agent finished, not that skep confirmed the
work: read the re-verify line.
6. Read the evidence
skep review <task_id>
review changes nothing. It prints the state, what the agent claimed
(verification:), the project and the dispatch and landing decisions,
re-verify: with the command skep re-ran and its exit code, the files changed,
and then the whole diff.
The line to read first is re-verify:.
| It says | Meaning |
|---|---|
passed [confirmed] |
The agent said its checks passed, and your pinned command passed when skep re-ran it on a clean checkout with the patch applied. |
failed [NOT CONFIRMED — DO NOT TRUST] |
Your pinned command failed on the clean checkout. The tail of its output is printed, and the full output is in reverify.output.txt. |
unavailable [NOT CONFIRMED — DO NOT TRUST] |
skep could not run the check (command not found, no sandbox, dependencies could not be installed). Nothing was proven either way. |
nothing to re-verify |
The run changed no files. |
The files behind it are in the evidence directory. A run that produced a patch leaves:
<task_id>.ndjson
<task_id>.patch
events.ndjson
result.json
reverify.profile.sb
sandbox.profile.sb
task.json
worker.log
task.json is the contract the agent was given (permissions, budget, the
dispatch decision). sandbox.profile.sb is the sandbox it ran in.
skep policy decisions prints the decision log. Know what is and is not in it:
an external agent's own tool calls happen inside the sandbox and are not logged
one by one. What skep records for such a run is the dispatch decision, the
events, the patch, the re-verification and the approval. A plain skep run
added no rows to the decision log when this guide was written; a refused
--role run added one row per question it would have asked.
7. Approve, and open the pull request
skep review <task_id> --approve
approved: task 01a1f131-513d-7650-873b-16247605c45b (by you)
patch applied on branch skep/01a1f131-513d-7650-873b-16247605c45b in /home/you/code/calc
next: git -C /home/you/code/calc switch skep/01a1f131-513d-7650-873b-16247605c45b
The patch is now one commit on a new local branch. main is where it was:
* main
skep/01a1f131-513d-7650-873b-16247605c45b
Variations:
--branch NAMElands on a branch you name. The repository's default branch is refused.--pralso pushes that branch tooriginand opens a pull request withgh, with the re-verification result in the body. It needs theghCLI logged in; without it skep printsnote: gh CLI not found — push the branch and open the PR manually.--pr-basesets the base branch (defaultmain).--denyrejects the patch.
Approving a run that was not confirmed is allowed, and skep says so. This was captured from a run whose pinned command failed:
approved: task 01a1f131-5eeb-7c0d-85ec-8a2239d4e924 (by you)
patch applied on branch skep/01a1f131-5eeb-7c0d-85ec-8a2239d4e924 in /home/you/code/calc
warning: re-verification RAN and FAILED (exit codes [1]): the patch does not pass the verify command — review it before relying on it
What goes wrong, and how to tell
| What you see | Cause | Fix |
|---|---|---|
error: project setup requires a pack or strategy |
--engine on a repository that is not yet a project |
add --strategy trusted_local_dev (step 3) |
NO AUTH ENV — set one of … |
the credential is not in the environment skep was started from |
step 2; under cron see the cron guide |
coding_engine 'claude_code' is not installed here ('claude' not on PATH) |
the agent's CLI is not on PATH |
install it, or fix PATH |
… built-in verification is \git diff --check` (whitespace only), so G10 would re-run a check that cannot fail. Pin the command …` |
the project has no verify command | skep project setup ~/code/calc --verify-command "<command>" |
execution mode 'sandbox' needs a usable sandbox backend and this host has none |
no bubblewrap (Linux), or the host forbids it | install bubblewrap; skep doctor names the reason |
re-verify: unavailable … verification command not found on the supervisor |
the pinned command is not installed where skep runs | install the tool, or pin a command that exists; then run the task again |
re-verify: failed [NOT CONFIRMED] |
the patch does not pass your command on a clean checkout | read reverify.output.txt; deny, or run again with clearer instructions |
The refusal for a missing verify command ends with
next: skep run <repo> "<instructions>" --execution-mode workspace. Ignore
that hint for an external agent: workspace mode does not apply to it, and the
fix is the verify command.
Limits to keep in mind
- The sandbox confines writes to the run's worktree. Reads outside it are
mostly open, apart from a list of credential paths that are hidden. The
agent can reach its model provider, and whatever hosts the policy's default
network lists (the
builderbaseline lists the package registries). Details:sandboxing.md. - skep switches the agent's own permission prompts off inside the sandbox, so the sandbox replaces that layer; it does not add to it.
- Re-verification is only as strong as the command you pinned.