Local supervisor for coding agents · v1.6.0
Unattended coding agents you don't have to trust.
Hand Claude Code or Codex a task and walk away. skep runs it inside an OS sandbox, re-runs your project's own test command on a clean checkout, and holds the patch on a branch for your approval. Your main branch never moves without you.
$ pipx install skep skep run ~/code/skep-demo "add a /health route" --execution-mode sandbox
task 01a1f0f8-11e8-7e3d-933f-58b406b184a9
1The worker's claim
- state:
- completed
- verification:
- passed (git diff --check passed)
- summary:
- claude-code produced a verified patch.
2skep re-runs your command
- re-ran
- ['python -m unittest discover -s tests'] → exit [0]
- re-verify:
- passed [] (G10): re-ran clean: all exit 0 [command from the project's pinned verify_command]
3Held for youawaiting approval
next: skep review <task_id> --approve # applies the patch on branch skep/<task_id>
main untouched
-
5 engines a task can run on -
4 outcomes a re-verification can record -
3 sandbox backends -
13 design invariants -
58 architecture decision records
Counted from the repository when this page was built
What holds on every run
Each one is enforced by skep before the agent starts or after it stops. None of them is a request to the agent.
Always inside the sandbox
Your command, re-run by skep
main moves when you confirm
skep/*.
What a refusal looks like. It was run for this page against a throwaway home with no engine credentials in the environment.
skep run ~/.cache/skep-site-demo/notes "add a line to notes.txt" --execution-mode sandbox error: coding_engine 'claude_code' is an external agent whose built-in verification is `git diff --check` (whitespace only), so G10 would re-run a check that cannot fail. Pin the command that actually proves the work: `skep project setup <repo> --verify-command "<command>"` (chat: setup_project verify_command=...).
The refusal with no auth in the environment, and the others a first run can meet
Mechanism
Four steps. Each is shown with the thing it does not do.
-
1Sandbox
Before the agent starts, skep builds an OS sandbox around a disposable git worktree: bubblewrap with Landlock on Linux, Seatbelt on macOS, podman if you opt in. The agent process is started inside it, so the wall is up before the first model call. Claude Code, Codex, Aider and pi are forced into sandbox mode whatever the request says, and when no backend is usable the dispatch is refused instead of run unconfined.
-
2Run
The agent works in the worktree with nobody to ask. It authenticates only from the environment variables its engine declares, because keychain and file logins are masked inside the sandbox. It cannot push, pull or fetch: for skep's own worker those are hard denies that no grant lifts, and for an external agent the sandbox does the job with no network beyond its allowlist, masked credentials and a git protocol pin.
-
3Re-verify
When the agent says it is done, skep applies its patch to a clean worktree and re-runs the project's pinned
verify_commandthere; for a sandboxed run the re-run is sandboxed too. The result is one of four outcomes: passed, failed, unavailable or not_applicable. A run is printed[confirmed]only when the worker reported passed and skep's re-run passed too. The record names the command that ran and where it came from. -
4Approve
The patch waits.
skep review <task_id>shows the evidence and the diff;--approveapplies it onskep/<task_id>or a branch you name, and--propens a pull request from that branch. Your default branch is refused as a landing target, and a run with no re-verification record cannot be approved.
Engines
Choose the engine per project, or per run with --engine. Four external agents and skep's own worker ship today.
skep run ~/code/your-app "fix the failing test" --execution-mode sandbox
--engine
-
claude_codeClaude Code, headless -
codexCodex CLI, headless -
aiderAider, with its auto-commit switched off -
pipi, headless -
builtinskep's own worker
Ollama is a model provider for skep's own worker, not an engine. The Codex ChatGPT plan login hands the run a copy that holds the access token and no refresh token.
Landing
What the agent produced is a patch against the commit the task started from. Your checkout did not change while it ran.
An example patch: the app.py half of a git diff, made by hand on a copy
of examples/skep-demo. The other half adds its test. No agent wrote it.
diff --git a/app.py b/app.pyindex 5cb88fa..79aea50 100644--- a/app.py+++ b/app.py@@ -4,4 +4,6 @@ from __future__ import annotations def route(path: str) -> tuple[int, dict[str, str]]: if path == "/": return 200, {"message": "hello from skep-demo"}+ if path == "/health":+ return 200, {"status": "ok"} return 404, {"error": "not found"}
Outside a skep run
Two smaller tools apply the same policy to an agent that is not running under skep. Neither is a sandbox.
The Claude Code hook
skep policy hook is a PreToolUse hook for Claude Code. Claude Code asks skep before
Bash, file writes, WebFetch and WebSearch, enforces the allow, ask or deny that comes back, and skep
records each verdict.
Limit It judges the text of a command and does not confine what the command then does. Every other tool falls through to Claude Code's own permissions, and the hook runs only if you installed it.
The ACP governor
skep acp govern sits between an ACP client, such as an editor, and the agent. It
answers the agent's permission requests from your policy, forwards what it cannot decide to you, and
records both.
Limit
It does not sandbox the agent. An agent in a mode that never asks is only observed after the fact;
skep acp doctor warns about those modes.
Quickstart
The unattended path with Claude Code, on Linux or macOS. Swap the engine and its key for Codex.
$ pipx install skep # Linux: bubblewrap. macOS: nothing to install.
$ sudo apt install bubblewrap
$ skep doctor $ claude setup-token
$ export CLAUDE_CODE_OAUTH_TOKEN=<token>
# Codex: export OPENAI_API_KEY=<key> $ skep project setup ~/code/your-app \
--strategy trusted_local_dev \
--engine claude_code \
--verify-command "uv run pytest" $ skep run ~/code/your-app "fix the failing test" \
--execution-mode sandbox $ skep review <task_id>
$ skep review <task_id> --approve --pr
Setup also seeds a weekly maintain schedule, which fires only under skep serve or
skep tick; pass --no-seed-schedules to skip it. The sandbox masks keychain and
file logins, so a logged-in claude or codex on your machine is not enough by
itself.
Honest limits
Read these before you rely on it.
Why skep
How skep compares, by mechanism, with four other ways to run a coding agent.