How it works
One run, from dispatch to a branch you approve
You hand Claude Code or Codex a task and walk away. skep decides where the agent runs, re-runs your project's own test command on a clean checkout, and holds the patch until you approve it. This page follows one run, then the policy engine that answers every side effect.
- 1 Dispatch a project, an engine and a pinned verify command
- 2 Isolation a disposable worktree inside an OS sandbox
- 3 Work the agent edits; skep records
- 4 Evidence a patch and a directory of records
- 5 Re-verification your command, re-run on a clean worktree
- 6 Approval you read the patch and the verdict
- 7 Landing a commit on a skep/* branch
Step 1 · Dispatch
A project, an engine and a pinned command
A run is one task against a registered project. The project says which agent does the work and which command proves it.
skep project setup registers a repository and pins its verify_command. By default
it infers the command from the repository's own entry point; --verify-command sets it by hand. A
repository with no entry point skep can detect is pinned to nothing on purpose.
The engine is builtin (skep's own worker, the default) or an external agent:
claude_code, codex, aider or pi. Set it for the project
with skep project setup <repo> --engine claude_code, or for one run with
--engine.
An external engine is dispatched only when three things hold:
-
The project pins a verify command. The engine's built-in check is
git diff --check, and re-running a whitespace check proves nothing. -
Its auth env is set:
CLAUDE_CODE_OAUTH_TOKENorANTHROPIC_API_KEYfor Claude Code,OPENAI_API_KEYfor Codex. Its keychain and file logins are masked, so without the variable the dispatch stops withNO AUTH ENV. - A sandbox backend works. An external engine always runs in sandbox mode, whatever the request says.
Every run names its execution mode. sandbox puts the worker behind the OS wall.
workspace is for the built-in worker only: the same worktree and the same pipeline, with no OS
wall. With no mode on the request and none in policy, the dispatch is refused until one is chosen.
skep project setup ~/code/skep-demo --pack trusted_local_dev --no-seed-schedules --verify-command "python3 -m unittest discover -s tests" saved: skep-demo (trusted_local_dev/build) pack: trusted_local_dev@1 bindings: repo_path=~/code/skep-demo seeded templates: 1 skep-demo-trusted-maintenance seeded schedules: 0 seeded shell commands: 0 verify command: python3 -m unittest discover -s tests loopback ports: closed (--loopback-port PORT opens one)
skep run ~/code/skep-demo "create a Python hello world script" --execution-mode sandbox dispatching task against ~/code/skep-demo → worker started (vcoding-minimal-0.1.0) project: skep-demo (trusted_local_dev/build) dispatch: allow dispatch.allow.run_request_resolved landing: require_approval landing.require_approval.project_policy_disabled_auto_apply → plan: create hello.py → run: .venv/bin/python hello.py policy: allow capability.allow.shell_verify (.venv/bin/python hello.py) → exit 0: .venv/bin/python hello.py policy: allow capability.allow.shell_verify (.venv/bin/python hello.py) → verification: passed → terminal: completed → re-verify: passed [confirmed] worker passed re-ran clean: all exit 0 [command from the project's pinned verify_command] re-ran python3 -m unittest discover -s tests -> exit 0 task 01a1f147-656d-7a10-81a4-4b42ba08e7bc state: completed (1.6s) verification: confirmed by re-verify (G10) — re-ran python3 -m unittest discover -s tests → exit 0 worker claim: passed — created hello.py and verified it runs. evidence: $SKEP_HOME/supervisor/audit/01a1f147-656d-7a10-81a4-4b42ba08e7bc next: skep review 01a1f147-656d-7a10-81a4-4b42ba08e7bc
Steps 2 and 3 · Isolation and work
A disposable worktree inside an OS sandbox
The agent never edits your checkout. It works in a git worktree of its own, and in sandbox mode the operating system confines the process that runs there.
The worktree
Created at ~/.skep/supervisor/worktrees/<task_id> from the baseline ref
(--ref, else the current commit), and removed when the run ends. Your checkout, your branch
and your index are not touched.
The sandbox
Seatbelt on macOS, bubblewrap with Landlock on Linux, podman if you opt in. The root filesystem is read-only; the worktree, the run's result directory, its git metadata and a per-project cache are writable. If no backend can be applied, the worker does not start.
The contract
skep is not the coding agent. It starts a worker that speaks one contract (version
0.3.8): a task as JSON in, a stream of NDJSON events out, a result as JSON out. The
built-in worker and every adapter sit behind the same boundary.
Step 4 · Evidence
A patch and a directory of records
A finished run leaves a patch, not a commit. Everything skep recorded about the run is in one directory under the home.
ls -1 $SKEP_HOME/supervisor/audit/01a1f147-656d-7a10-81a4-4b42ba08e7bc 01a1f147-656d-7a10-81a4-4b42ba08e7bc.ndjson 01a1f147-656d-7a10-81a4-4b42ba08e7bc.patch events.ndjson result.json reverify.profile.sb sandbox.profile.sb task.json worker.log
With the default home the directory is ~/.skep/supervisor/audit/<task_id>/. Task ids are
UUIDv7, so they sort by time. Inside a worker's sandbox the whole audit directory is masked.
| File | Holds |
|---|---|
| task.json | The task as dispatched: instructions, permissions, budget, the pinned verify command, and the dispatch and landing decisions. |
| events.ndjson | The worker's event stream, one JSON object per line. A copy is kept under the task id. |
| result.json | Final status, summary, changed files, the commands that ran, the verification claim, usage and risk flags. |
| <task_id>.patch | The git patch against the baseline. This is the thing you approve. |
| sandbox.profile.sb | The sandbox the worker ran under. On Linux it is the bubblewrap argument list. |
| reverify.profile.sb | The sandbox the re-verification ran under. |
| worker.log | The worker process’s log, with skep’s own notes about starting and stopping it. |
Step 5 · Re-verification (G10)
skep re-runs your command on a clean worktree
The agent's own “tests passed” is a claim. skep checks it without the agent, with the command the project pinned.
- skep pins the baseline commit and creates a fresh worktree there.
-
In a uv project it primes the dependencies with
uv syncfrom the baseline, with the network, before the patch is applied. If the patch changes the lockfile it primes again afterwards. - It applies the patch.
-
It runs the project's pinned
verify_commandinside the sandbox with the network denied. The command gets onlyPATHandHOMEfrom skep's environment, and the project's loopback ports. - It records the outcome, the exit codes and which command it ran.
skep review 01a1f147-656d-7a10-81a4-4b42ba08e7bc task 01a1f147-656d-7a10-81a4-4b42ba08e7bc state: completed verification: passed (hello.py printed expected output) project: skep-demo (trusted_local_dev/build) binding: repo_path: ~/code/skep-demo dispatch: allow dispatch.allow.run_request_resolved landing: require_approval landing.require_approval.project_policy_disabled_auto_apply re-verify: passed [confirmed] (G10): re-ran clean: all exit 0 [command from the project's pinned verify_command] re-ran ['python3 -m unittest discover -s tests'] → exit [0] usage: 0 provider calls (G8) worker: coding-minimal-0.1.0 manifest 8ab5562abbb9… summary: created hello.py and verified it runs. evidence: $SKEP_HOME/supervisor/audit/01a1f147-656d-7a10-81a4-4b42ba08e7bc changed: hello.py commands: [0] .venv/bin/python hello.py # verify
| Outcome | Means |
|---|---|
| passed |
The patch applied and every command exited 0. Printed as [confirmed] when the worker also
reported that verification passed.
|
| failed |
The patch did not apply to the clean worktree, or a command exited non-zero or timed out. Printed as
NOT CONFIRMED — DO NOT TRUST. Auto-landing does not apply.
|
| unavailable |
skep could not honestly re-run the check: the sandbox could not be built (the command is never run
unconfined instead), the worker claimed changed files but left no patch, the uv sync prime
failed, or the command is not installed where skep runs. Never counted as confirmed.
|
| not_applicable |
The run changed no files or produced no patch, so there is nothing to re-verify. Printed as
nothing to re-verify, not as an alarm.
|
skep review --approve is refused for a run that has no re-verification record;
skep review --reverify runs the check for a run that never got one.
Steps 6 and 7 · Approval and landing
Approval turns the patch into a commit on a skep/* branch
Your default branch never moves by itself. Landing puts one commit on a separate branch, and what happens to that branch is your normal git decision.
@@ -0,0 +1 @@+print("Hello, world!")
skep review 01a1f147-656d-7a10-81a4-4b42ba08e7bc --approve --actor demo approved: task 01a1f147-656d-7a10-81a4-4b42ba08e7bc (by demo) patch applied on branch skep/01a1f147-656d-7a10-81a4-4b42ba08e7bc in ~/code/skep-demo next: git -C ~/code/skep-demo switch skep/01a1f147-656d-7a10-81a4-4b42ba08e7bc git -C ~/code/skep-demo branch -vv * main 389b911 skep-demo skep/01a1f147-656d-7a10-81a4-4b42ba08e7bc efa4344 Apply skep task 01a1f147-656d-7a10-81a4-4b42ba08e7bc skep review 01a1f147-656d-7a10-81a4-4b42ba08e7bc --approve --actor demo error: this task already landed on skep/01a1f147-656d-7a10-81a4-4b42ba08e7bc; a task lands once — dispatch a follow-up skep review 01a1f147-656d-7a10-81a4-4b42ba08e7bc --approve --branch main --actor demo error: refusing to land on the default branch 'main'; choose another name
-
skep review <task_id>shows the patch and the evidence.--approveapplies the patch as one commit onskep/<task_id>;--denyrejects it. The web UI's Inbox and the chat do the same thing through a card. -
--branch <name>lands on another branch. An existing branch gets the commit appended. The repository's default branch is refused, whatever its capitalisation, and so is a name that starts with a ref namespace or a remote. -
--pralso pushes that landing branch and opens a GitHub pull request withgh. The base branch moves only when the pull request is merged. - A task lands once. More work on it is a follow-up run.
One opt-in lane lands without a click
Landing needs your approval by default. One lane lands by itself once you switch it on. It lands only a patch
that re-verification confirmed, refuses to append past the commit that was re-verified, and records the
approval with the actor auto:verified-patch.
verified-patch
- Switched on by
-
Project policy
auto_apply_verified_patch: on by default in themaintainphase, and for a project set up with--unlocked. - Lands when
- The worker verified, re-verification confirmed with the pinned command, and there are no risk flags. Any diff.
- Branch
-
skep/maintainin the maintain phase: one integration branch, always underskep/. Otherwiseskep/<task_id>.
Still left for you
- A pin that is known-vacuous:
true,git diff --checkand the like. - A patch that touches the test setup or a file the pin runs.
- A run with risk flags, or one the worker did not report as passed.
--auto-approveis retired: it prints a note and lands nothing.
The lane can never land on the default branch.
A patch that cannot append cleanly to the integration branch goes back to a normal approval. From a messenger
only four low-risk action classes can be confirmed (dispatch_run,
scheduled_result_ack, read_url, start_research): shell commands, policy
changes and landings are confirmed in the web UI or the terminal.
The policy engine
One decision point: allow, ask or deny
Every side effect skep governs is one question: a scope, an action and a value. skep policy why answers it without running anything, and names the layer that decided.
Pick a command
skep policy why demo-repo shell run "git push origin main"
- floorremote git commands never run from chat — skep lands patches after approval; use push_branch/open_pr for the governed remote surfaceThe floor is read first. No rule, grant, role or approval lifts it.deny
- baselinebuilder approved 2026-11-19T00:51:49Z sha256 01db10ac4fc3The locked baseline matches its hash. Tampered or missing, every decision here would ask.locked
- rundecided_by: floor/floor.worker-git-hard-deniesA worker dispatched in this repo. considered: [] (no project rule was consulted).deny
- operatordecided_by: floor/floor.worker-git-hard-deniesThe Queen, from chat. The same floor binds it.deny
verdict"verdict": "deny"
A worker and the Queen get the same answer. skep itself pushes a landing branch only when you ask: skep review --approve --pr, skep pr open, or a push_branch card in chat.
skep policy why demo-repo shell run "npm i left-pad"
- floor(no floor key in the output)No floor rule matches this command, so the layers below decide.
- baselinebuilder approved 2026-11-19T00:51:49Z sha256 01db10ac4fc3The locked baseline matches its hash. Tampered or missing, every decision here would ask.locked
- rundecided_by: default/unmatchedA worker dispatched in this repo. considered: [] (no rule names this command).ask
- operatordecided_by: template:builder/shell-learnableThe Queen, from chat: the builder template's catch-all for shell commands.ask
verdict"verdict": "require_approval"
Unmatched means ask, so a person answers. Rules match the command as written: the builder template allows the prefix "npm install", and the same question for "npm install left-pad" printed allow on the run face, decided by template:builder/shell:npm install.
skep policy why demo-repo shell run "cat ~/.ssh/id_ed25519"
- floor~/.ssh/id_ed25519 is under ~/.ssh — credential files are never readable by the Queen or a worker (the secret floor; no rule, grant or card lifts it)The floor reads the paths a shell line names, not only file reads.deny
- baselinebuilder approved 2026-11-19T00:51:49Z sha256 01db10ac4fc3The locked baseline matches its hash. Tampered or missing, every decision here would ask.locked
- rundecided_by: floor/floor.secret-readsA worker dispatched in this repo. considered: [].deny
- operatordecided_by: floor/floor.secret-readsThe Queen, from chat.deny
verdict"verdict": "deny"
This is the policy answer to a command line. In a sandbox run the path is also masked on disk, which is what stops an external engine whose commands are never asked about.
How to read a trace
flooris printed only when a floor rule decided. The floor is read before any layer.baselineis the state of the locked baseline the layers sit on.runis the answer a worker dispatched in that repository gets.operatoris the answer the Queen (the chat assistant) gets for its own tools.-
The engine's word for ask is
require_approval; the tables and the cards print it asask.
$ skep policy why <repo> shell run "npm test"
$ skep policy explain builder
$ skep policy rsop <repo>
$ skep policy decisions --since 2026-11-18 The same engine, for an agent you run elsewhere
The Claude Code hook
skep policy hook is a PreToolUse hook. Claude Code enforces its verdict for Bash, file writes,
WebFetch and WebSearch, and every decision is recorded.
Limits: every other tool falls through to Claude Code's own permissions. It judges the command text, it is not a sandbox, and it runs only if you installed it.
The ACP governor
skep acp govern sits between an ACP client and its agent, answers the agent's permission
requests from policy and records them.
Limits: it does not sandbox, and an agent in a mode that never asks is only observed, after the fact.
Layers and precedence
Deny binds, unmatched asks, a role only tightens
Policy is layered, and every verdict names the layer and the rule that produced it.
| Step | What it does |
|---|---|
| 1. Floor | Hard denies that nothing lifts: remote git and branch switching, privilege escalation, credential reads. Outbound posts always ask. |
| 2. Baseline guard | On a fresh home with no approved baseline, or when the baseline no longer matches its lock, every decision asks and dispatch is refused. |
| 3. The lane’s rules | Inside a repository, the run policy: global, template, phase, group, project, session grants, dispatch. Elsewhere, the operator document. |
| 4. Operator roots | Only where the operator document matched nothing: the folders you registered answer allow. They never outrank a rule. |
| 5. Unmatched | No rule matched: ask. The one exception is a shell opened in a repository’s working directory, which is denied. |
| 6. Role | The role layer can make the answer stricter. It never grants. |
| 7. Delegation | A dispatched worker holds no more than whoever dispatched it. |
| 8. Taint | Last: in a chat that has read private data or taken in outside content, an allow becomes an ask. |
- Deny binds across layers. Inside one layer the most specific rule wins and deny wins
ties. Across layers any deny binds, then any named ask, then the most specific of the rest. A catch-all
*ask is a default: a more specific allow answers it. - Unmatched is ask. What nobody wrote a rule for goes to a person. It is not denied and it is not allowed.
- The locked baseline.
skep policy approve --template builder(oroperator,assistant) locks one template with a SHA-256. Every setting it sets is enforced: a project, a group or a dispatch that tries to change it is refused by name, andskep policy rsopshows the refusal. - A role only tightens. The stricter of the role and the baseline stands. One documented exception: a role's catch-all ask is a default, so a command you approved with “keep for this session” or “always” runs again in that role without a card. Its denies and named asks still bind.
- Session grants last until
skep serverestarts.skep policy grantslists every learned grant;skep policy revokeremoves one. - Taint never turns a deny into an ask and never grants.
/trustclears a chat's taint.
A verdict's decided_by starts with one of: floor/, baseline/,
global/, template:<name>/, role:<name>/,
phase:<p>/, group:<name>/, project:<id>/,
grant:session/, grant:global/, dispatch/,
delegation:<who>/, default/unmatched, taint/.
Roles and delegation
Authority only shrinks as it is handed down
A role is a prompt, a voice and a policy layer under the baseline. Delegation holds a dispatched worker to what its dispatcher holds.
Three roles ship: builder, operator and assistant, each bound to the
template of the same name. skep role list shows them, skep role show <name>
prints one as an allow, ask and deny table, and skep role use <name> sets the role new
chats open in.
A worker can take a role of its own (the --role flag of skep run), and
skep team --manager <role> fans one task list out to at most three member runs. When one
agent dispatches another, the dispatched one holds the intersection: its own role and what its delegator
holds. A rule the delegator does not have counts as not granted. Anything beyond is
exceeds_delegator, and the floor sits above every chain.
In the capture, the builder role allows npm test, but
queen@operator would itself have to ask, so the worker asks too.
skep policy why skep-demo shell run "npm test" --role builder --delegated-by queen@operator "delegation": { "chain": ["queen@operator"], "delegator": "queen@operator", "held": { "run": { "decided_by": "role:operator/shell-gated", "verdict": "require_approval" } }, "note": "delegated by queen@operator: the delegatee holds no more than queen@operator does — the stricter verdict stands; beyond it is exceeds_delegator" }, "role": { "decided_by": "role:builder/shell-npm-test", "layer": "role:builder", "verdict": "allow" }, "run": { "decided_by": "delegation:queen@operator/role:operator/shell-gated", "rule_id": "exceeds_delegator", "verdict": "require_approval" }
The record
Three records, not one ledger
What skep decided, what a run did and what you approved are kept in three places under the home.
The decision log
~/.skep/supervisor/audit/policy/decisions.jsonl
One row per decision made by the CLI, REST, the Claude Code hook, the ACP governor, the Queen's own tools
and dispatch. Read it with skep policy decisions.
The store
~/.skep/supervisor/supervisor.sqlite3
Runs, their events (the built-in worker's capability verdicts are here), re-verification results and approvals.
The audit files
~/.skep/supervisor/audit/<task_id>/
Per run: the task, the event stream, the result, the patch and the sandbox profiles.
- 00:48:14Z shell.run git push origin main actor cli · repo demo-repo · decided_by floor/floor.worker-git-hard-denies · v 1 deny
- 00:48:14Z shell.run npm i left-pad actor cli · repo demo-repo · decided_by default/unmatched · verdict require_approval · v 1 ask
- 00:48:15Z shell.run cat ~/.ssh/id_ed25519 actor cli · repo demo-repo · decided_by floor/floor.secret-reads · v 1 deny
Next