Worker Adapters
Skep supervises workers through the local worker contract. The default worker is
the in-repo coding worker, but you can point a run or server at a different
worker with --worker-cmd or SKEP_WORKER_CMD.
Current Adapter Status
| Worker | Status | Notes |
|---|---|---|
| In-repo coding worker | Supported | skep's own worker: it plans with the configured model and runs each step through the capability layer. A deterministic hello-world path remains only as the no-provider fallback. |
| Claude Code | Supported | Thin adapter around the local claude CLI. |
| Generic shell worker | Supported | Prompt wrapper for local CLI agents configured with SKEP_SHELL_WORKER_CMD. |
| Custom contract worker | Supported | Any command that reads Skep task JSON and writes Skep result JSON. |
| Codex | Supported | Thin AdapterSpec on the shared CLI adapter (v33): python -m skep.workers.codex. |
| Aider | Supported | Thin AdapterSpec on the shared CLI adapter (v33): python -m skep.workers.aider. |
| pi | Supported | Thin AdapterSpec on the shared CLI adapter: python -m skep.workers.pi (headless -p). |
| Ollama coding worker | Supported | First-party planner over a local Ollama model (v33): python -m skep.workers.ollama. |
Claude Code
The Claude Code adapter runs the local claude CLI in the task worktree, then
captures the resulting patch as normal Skep evidence.
uv run skep project setup /path/to/repo --engine claude_code --verify-command "uv run pytest"
uv run skep run /path/to/repo "Fix the failing test" --execution-mode sandbox
Claude Code runs only inside skep's sandbox (operator decision D36): its
commands skip the capability layer, so the sandbox is its only wall. The
adapter refuses to start outside it, and a --worker-cmd naming it runs as
the claude_code engine: sandbox mode, auth env and pinned verify_command. The sandbox masks the keychain, so it authenticates from
CLAUDE_CODE_OAUTH_TOKEN (claude setup-token) or ANTHROPIC_API_KEY.
The adapter expects claude to be on PATH. If your executable is elsewhere,
set SKEP_CLAUDE_CODE_CMD and explicitly allow that variable through Skep's
worker environment boundary:
SKEP_CLAUDE_CODE_CMD="/path/to/claude" \
uv run skep run \
--execution-mode sandbox \
--env-allow SKEP_CLAUDE_CODE_CMD \
/path/to/repo \
"Add input validation"
What the adapter does:
- Calls
claude --print "<instructions>"with the task worktree ascwd. - Captures
git diff --binaryas the patch artifact. - Runs
git diff --checkas the baseline verification gate. - Writes the standard Skep result JSON and event log.
What it does not do yet:
- Parse task-specific verification commands.
- Intercept Claude Code tool calls directly.
The adapter is intentionally thin: Claude Code edits the disposable worktree, while Skep owns sandboxing, evidence capture, re-verification, patch approval, approval memory, and learned templates.
Generic Shell Worker
The generic shell worker is a prompt wrapper for local CLI agents that do not
need a bespoke Skep adapter yet. Set SKEP_SHELL_WORKER_CMD to the command that
should receive the task instructions as its final argv item:
SKEP_SHELL_WORKER_CMD="my-agent --prompt" \
uv run skep run \
--execution-mode sandbox \
--worker-cmd "python -m skep.workers.shell_worker" \
--env-allow SKEP_SHELL_WORKER_CMD \
/path/to/repo \
"Fix the failing test"
The configured command's own actions skip skep's capability layer, so the
shell worker runs only inside skep's sandbox: it refuses to start outside it,
and a run naming it is forced into sandbox mode. The configured command runs
with the task worktree as cwd, edits files there, and exits. Skep captures the resulting git diff --binary, runs
git diff --check, writes the event log/result JSON, and keeps approvals and
audit evidence in the supervisor layer.
That whitespace check proves nothing about the work, so, like an external
engine, a run using the shell worker requires the project's pinned
verify_command — the command G10 re-runs before the patch can land. Without
one the run is refused before it starts; pin it first with
skep project setup <repo> --verify-command "<command>".
Use a custom contract worker instead when the underlying agent needs richer state, structured progress events, or task-specific verification beyond this single prompt-call shape.
The caste roster (v101, ADR 0049)
src/skep/supervisor/castes.py is the one place a caste is registered. The
contract owns the names (KNOWN_WORKER_KINDS); this registry owns routing and
description, and every operator surface reads it rather than keeping a copy.
| caste | lands a patch | calls the LLM | fetches | what it does |
|---|---|---|---|---|
coding |
yes | yes | no | Writes code against a repo and produces a patch for approval. |
audit |
yes | no | no | Bumps unsafe dependency pins and re-runs the suite. Deterministic. |
curator |
no | no | no | Turns an inbox of notes into a proposals.json artifact. Nothing ingests it (v126-F7); kept because the contract names the caste. |
document |
no | yes | no | Drafts and summaries. No web, no code, nothing lands. |
researcher |
no | no | yes | Answers from allow-listed sources only, with evidence per source. |
script |
no | no | no | One inline script, sandboxed, deny-all egress. Output, never a patch. |
verifier |
no | no | no | Runs the project's PINNED verify_command and reports the verdict. |
reviewer |
no | yes | no | Reads the diff against the startup baseline and reports findings + a verdict. |
coding is the default and the only caste with an empty argv: it defers to
config.command_for, which is what SKEP_WORKER_CMD, --worker-cmd and the
coding-engine adapters override.
The registry covers the contract exactly: a caste added to KNOWN_WORKER_KINDS
without a registry entry fails the gates, and an unknown caste is refused by
name rather than silently running a coding worker.
verifier (v101-F2) runs the command the SUPERVISOR pinned, handed down in the
task envelope (contract 0.3.4) — never one it chose or read out of its
instructions. A worker deciding what "verified" means is what v88-F4 removed
from G10, and a caste called verifier is the last place to put it back. With
no pin it refuses and names the verb that sets one.
reviewer (v101-F3) diffs the worktree against the same startup baseline
git.diff uses, asks the provider for findings, and writes
.artifacts/review.md. It produces no patch, so a review never lands — the
operator reads it and decides. An empty diff completes without calling the
provider, and a finding naming a file the diff does not touch fails the run
rather than shipping.
Worker Contract Stability
The launch build ships worker contract 0.3.8. Check the exact package and contract versions with:
skep --version
Minor bumps are additive: new optional fields, event types, or capability metadata may appear without breaking existing workers. Major bumps are breaking: removing fields, renaming fields, changing required semantics, or changing the task/result/event JSON shape requires adapter updates.
Contract 0.2.1 (v19) added optional, additive fields only — commands on the
approval.requested event payload and on ApprovalVerdict (batch shell
approvals), plus the supervisor-assigned superseded task state that workers
never emit — so the claude adapter's >=0.1,<0.3 range still holds.
Contract 0.2.2 (v13) added one optional, additive field — memory on the task
envelope, a list of curated memory items the supervisor injects as context, not
authority. Workers that ignore it behave exactly as before.
Contract 0.3.8 (operator decision D6, 2026-11-13) adds one optional, additive
field on permissions — loopback_ports (integers): the loopback ports the
project policy opens to the run. Loopback is otherwise closed to a sandboxed
worker, except a local model provider's own port; serve's port never opens. A
task persisted before 0.3.8 has none (= []).
Contract 0.3.7 (ADR 0059 D3, V7) adds two optional, additive fields on
permissions — network_ask (bare hosts) and shell_ask (argv prefixes): the
grants a delegated run's chain made an ask instead of dropping them. The builtin
coding worker cards each one with the chain's name ("worker@builder asks
network.connect X — delegated by queen@builder, which would itself ask"); the
approval is approve-once for that run, and Allow & remember is refused for it.
Neither field is egress. Only the supervisor fills them, and only when a human
can answer the card; a task persisted before 0.3.7 has neither (= []). A
worker that ignores them treats the hosts and prefixes as absent — exactly the
pre-0.3.7 drop.
Contract 0.3.6 (ADR 0059 D3, V6a) adds one optional, additive field —
provider_hosts on permissions: skep's own LLM endpoint(s) as host:port,
filled by the supervisor from its configured provider (or an external engine's
own API host) and held apart from network, so the delegation narrowing never
drops it. The egress proxy admits each entry on that one port only. A task
persisted before 0.3.6 has no field (= []) and still carries its provider
host in network; first-party workers accept either. A worker that ignores the
field and checks only network before calling the provider will refuse its
own provider on a 0.3.6 task.
Contract 0.3.5 (v101-F3) registers the reviewer caste — read-only diff
review; nothing lands. An older worker rejects the name with the existing
doctor-style error.
Contract 0.3.4 (v101-F2) adds one optional, additive field — verify_command
on the task envelope: the project's PINNED verification command, the one G10
re-runs (v88-F4). The verifier caste runs exactly this and never nominates its
own. Workers that ignore it behave exactly as before.
Contract 0.3.3 (v69, ADR 0040) adds one optional, additive field —
planning_protocol on the task envelope ("plan" default, "react" for the
bounded act–observe loop). Workers that ignore it plan exactly as before.
Contract 0.3.2 (v51) registers the script caste — sandboxed inline code
runs dispatched by the Queen's run_code. Contract 0.3.1 (v40) adds the
optional decided_by audit field; 0.3.0 (v17)
is an additive minor bump: it registers the researcher,
verifier, and document worker castes. v0.2 tasks still parse unchanged; a
worker that does not implement a caste rejects it with a doctor-style error. All
first-party workers and the claude adapter widened their supported range to
>=0.1,<0.4 in the same change.
Custom Contract Workers
--worker-cmd is not a raw prompt wrapper. The command must speak Skep's worker
contract: read the task JSON path passed by the supervisor, write a result JSON
file, and emit artifacts/events that Skep can audit. The --out path sits in a
directory of the run's own (results/<task_id>/result.json), the only result
directory a sandboxed run may write; an envelope whose task_id is not the
run's is rejected and the rejection recorded on the run.
Use this shape for an internal adapter:
uv run skep run \
--execution-mode workspace \
--worker-cmd "/path/to/your-skep-worker" \
/path/to/repo \
"Fix the failing test"
The adapter can call any underlying CLI agent, but Skep only trusts the contract files it receives back from the adapter.
Codex, Aider, and Ollama (v33)
Codex and Aider ship as thin AdapterSpec declarations over the shared CLI
adapter body (src/skep/workers/cli_adapter.py) — same contract, same
sandbox, same gates as Claude Code. The Ollama coding worker is a
first-party planner that reuses the saved assistant LLM credentials by
default. Select any of them with --worker-cmd or SKEP_WORKER_CMD.
An external engine's own sandbox is turned off, because skep's sandbox is
its wall (ADR 0047) and a sandbox cannot nest inside skep's (Landlock
refuses a nested bubblewrap; Seatbelt refuses a nested sandbox-exec):
Codex runs exec --sandbox danger-full-access, Claude Code gets
--settings '{"sandbox": {"enabled": false}}'. Aider and pi start none.
External engines always run in sandbox mode (v94-F4), and the codex, aider
and pi workers refuse to start outside skep's sandbox. See sandboxing.md, Landlock.
What skep records for an external engine: the evidence for every run — the
command it launched, the patch, the sandbox profile and the G10 re-verify of
the project's pinned check. Not each decision: the agent's own commands never
reach skep's capability layer, so they write no decision-log rows (ADR 0047).
Inside the sandbox, reads outside the workspace are open except the masked
paths sandboxing.md lists; other runs' worktrees are readable.