The run lifecycle

The agent writes code. Skep owns everything else.

Skep is a local supervisor around a coding agent. It controls where the agent runs, what it can reach, what evidence it must produce, and how the final patch lands.

Get started Read the docs
LIFECYCLE skep run 
skep run
  -> create isolated worktree
  -> write task contract
  -> start worker in workspace or sandbox mode
  -> collect events, logs, patch, evidence
  -> re-verify the patch on a clean worktree
  -> wait for review and approval
  -> apply the patch on skep/<task_id>

The worker never edits your current checkout and never lands changes on main.

Six checkpoints, in order

Each stage produces an artifact the next stage can be checked against.

1
Worktree
A disposable Git worktree at your baseline ref.
2
Contract
Task JSON: repo, instructions, permissions, budget.
3
Sandbox
Seatbelt or bubblewrap constrain the worker process.
4
Approvals
The run stops at a gate when more permission is needed.
5
Re-verify
Replay the patch on a fresh baseline and re-run the checks.
6
Approve
You land the patch on a review branch. Skep never pushes.
1 — Isolated worktree

The agent never sees your checkout.

Skep records the source repo and baseline ref, then creates a separate worktree for the worker. The worker changes files there without touching your active branch.

At the end of the run, Skep captures a binary-safe git patch from that worktree. That patch is the unit you review, approve, merge, or discard.

terminal 
$ skep run /path/to/repo \
    "fix the failing test" \
    --execution-mode workspace

baseline: main@a19c4f2
worktree: ~/.skep/worktrees/7d31f9c2
patch:    ~/.skep/artifacts/7d31f9c2.patch
2 — The worker contract

Skep does not need to be the coding agent.

It launches a worker process that speaks one local task/result contract (v0.3.5 today). The in-repo worker, the Claude Code adapter, Codex, Aider, and Ollama all fit behind the same boundary — the adapter can be thin because Skep owns supervision, not code generation.

TASK JSON IN

Everything the worker is allowed to know and do, up front.

repo · worktreeinstructionspermissions · budgetresume state
EVENT STREAM OUT

NDJSON, written as the run happens — not reconstructed after.

progresscommandsapprovalsverification · artifacts
RESULT JSON OUT

The claim — which Skep then checks for itself.

final statesummarypatch pathevidence paths
3 — Sandbox boundary

Defense in depth, not a substitute for review.

In sandbox mode, Skep asks the host OS to constrain the worker process. If sandbox mode is requested but no backend can be applied, the worker does not start unsandboxed — the run fails instead.

The full security model
PLATFORM
BACKEND
STATUS
macOS
sandbox-exec
Supported when the host allows profiles
Linux
bwrap
Supported when bubblewrap probes clean
Other
none
Unavailable — sandbox runs refuse to start
NETWORK MODES
[ ]Empty list — deny all outbound.
[ * ]Allow all outbound.
[ domains ]Only those domains, via the loopback filtering proxy.
4 — Approvals

The run stops and asks, in your terminal.

Approving once resumes only the current run. Approving with remember records the permission in the durable ledger — and a successful resumed run can save a learned template for similar future tasks.

aResume this run only.
bResume and record the permission for template learning.
dDeny the request.
sLeave it pending for skep review later.
approval needed: shell.run
  reason:  shell.run requires approval for
           command: python -m pytest

  [a] approve once   [b] approve + remember
  [d] deny           [s] skip
> b

recorded in ledger:
  repo    /path/to/repo
  action  shell.run
  actor   operator
  outcome resumed → completed
5 — Re-verification

Skep replays the patch on a clean copy, itself.

The replay uses only PATH and HOME from the supervisor environment. When the sandbox is available, it runs with deny-all network and writes confined to the clean worktree.

01Create a fresh worktree at the original baseline.
02Apply the worker's patch artifact.
03Pick the check: the project's pinned verify_command, or the worker's recorded verify.result commands when no pin exists.
04Re-run those commands from the clean worktree.
05Record the outcome, exit codes, and detail message.
passed

Patch applied and every recorded command exited 0.

failed

The patch did not apply, a command timed out, or one exited non-zero. Auto-approval is blocked.

unavailable

Skep could not honestly re-run the check — no patch, no recorded command, or the tool is missing.

A run is confirmed only when the worker reported passed and Skep's replay is also passed.
6 — Patch approval

Approval lands a branch. You do the rest.

The branch is named skep/<task_id>. Skep does not push it. You keep the normal Git decision: inspect, merge, edit, or delete.

CLI reference 
$ skep review 7d31f9c2

task 7d31f9c2
  state:        completed
  verification: passed (worker says tests passed)
  re-verify:    passed [confirmed] (G10)
                re-ran ['uv run pytest'] -> exit [0]

$ skep review 7d31f9c2 --approve
  applied on branch skep/7d31f9c2
Beyond the terminal

Same gates, wherever you are.

Operate Skep from Telegram, Slack, or Discord. An allow-listed message runs the same turn, with the same approval gates, as the web composer. Shell commands, policy changes, and landings are never confirmable from a messenger.

Web dashboard
skep serve on 127.0.0.1, token-gated.
Terminal chat
skep chat — same store, same cards.
Messengers
Telegram, Slack, Discord — low-risk actions only.
Schedules
skep tick dispatches due runs from cron.

Run one supervised task and see the evidence yourself.

Five minutes from install to an approved patch on a review branch.

Install skep Documentation