Agents
Agents and engines
skep runs a coding task with one of five engines: its own worker, or Claude Code, Codex, Aider or pi. The four external agents always run inside skep's sandbox, and skep re-runs your project's verify command itself.
Engines
The five engines
An engine is the agent that does the work. The names in the first column are what the command line takes.
| Engine | What runs | Signs in from | Execution mode | Its actions pass skep's capability layer |
|---|---|---|---|---|
builtin | skep's own worker. It plans with the model the assistant is configured with and runs each step through the capability layer. | The configured model provider | sandbox or workspace | yes |
claude_code | Claude Code, headless (claude --print) | CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY | always sandbox | no |
codex | Codex CLI, headless (codex exec) | OPENAI_API_KEY, or the opt-in ChatGPT-plan login | always sandbox | no |
aider | Aider, with --no-auto-commit | Your Aider configuration; skep names no variable for it. Its model calls go to the provider endpoints skep is configured with; it has no API host of its own | always sandbox | no |
pi | pi, headless (-p) | Whichever of ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY its model needs. Its model calls go to the provider endpoints skep is configured with; it has no API host of its own | always sandbox | no |
# a repository that is already a project
$ skep project setup /path/to/repo --engine claude_code --verify-command "uv run pytest"
# a repository skep has not seen yet: name a strategy the first time
$ skep project setup /path/to/repo --strategy trusted_local_dev \
--engine codex --verify-command "uv run pytest" $ skep run /path/to/repo "fix the failing test" --engine codex --execution-mode sandbox - An external engine needs a pinned verify command. Its own check is
git diff --check, which looks for whitespace errors and says nothing about whether the work is right. Without a pin a project run is refused. A--minimalrun, or a template with no project, skips project policy and this check with it: there re-verification can only re-rungit diff --check. skep doctorlooks for each agent's binary on your PATH and says whether its sign-in variable is set.- A worker command that names an external agent's module (
--worker-cmdorSKEP_WORKER_CMD) is treated as that engine: sandbox, sign-in and pinned verify command included. A project pinned to an external engine refuses--worker-cmdunless you also pass--engine builtin. - The generic shell worker, which wraps any other command-line agent, gets the same treatment as an external engine.
- With no model configured, skep's own worker falls back to a fixed routine that handles one Python hello-world task and fails anything else.
skep doctor # excerpt: the engine lines - engine aider: MISSING — 'aider' not on PATH (sandbox-confined; needs verify_command) - engine builtin: ok — …/bin/python (skep's own worker) - engine claude_code: NO AUTH ENV — set one of CLAUDE_CODE_OAUTH_TOKEN/ANTHROPIC_API_KEY — …/bin/claude (sandbox-confined; needs verify_command) - engine codex: NO AUTH ENV — set one of OPENAI_API_KEY — …/bin/codex (sandbox-confined; needs verify_command) ChatGPT login: none (no Codex login on this machine (`codex login`)) - engine pi: MISSING — 'pi' not on PATH (sandbox-confined; needs verify_command)
Signing in
How each agent authenticates
Inside the sandbox the keychain and the agents' own login files are hidden, so an external agent signs in from an environment variable.
With a token or an API key
# Claude Code: prints a long-lived token
$ claude setup-token
# or ANTHROPIC_API_KEY
$ export CLAUDE_CODE_OAUTH_TOKEN=...
# Codex
$ export OPENAI_API_KEY=...
# each engine line now shows its sign-in state
$ skep doctor - The variable must be set where the worker is started: your shell for
skep run, and for the daemon either its own environment or aserve.envfile in the skep home, whichskep serveloads at startup. - skep passes these variables to the agent by name. A
serve.envfile is one you write and protect yourself. - Without one, the run is refused before anything starts.
skep run ~/other "fix the failing test" --execution-mode sandbox dispatching task against ~/other 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
Codex on a ChatGPT plan
$ codex login
$ skep project setup /path/to/repo --codex-chatgpt-login - For someone with a ChatGPT plan and no API key. It is off unless the project opts in, and it is used only when
OPENAI_API_KEYis not set. - Each run gets a copy of the login that holds the access token only, never the refresh token.
- Such a run talks to
chatgpt.comwhere a key-based run talks toapi.openai.com. skep doctorshows whether a Codex login exists.--no-codex-chatgpt-loginturns it off again.
External agents
What skep does to an external agent
Claude Code, Codex, Aider and pi run their own commands, which skep's capability layer never sees. The sandbox is the wall around them.
- Always in the sandbox. The run is forced into sandbox mode whatever the flag says, the adapters refuse to start outside it, and when no backend can be applied the run does not start.
- The patch still waits for you. skep captures the agent's changes as a diff, re-runs the pinned verify command on a clean checkout, and holds the patch for approval.
- Landing. Approval is needed by default. One opt-in lane lands a re-verified patch without a click, and only on a
skep/*branch: the verified-patch lane, which is on for a project in the maintain phase or set--unlocked, and needs a pinned verify command. Your default branch moves only through actions you confirm.
Models
Ollama is a model provider, not an engine
skep's own worker and the assistant use one configured model provider. Which agent does the work and which model answers are two separate choices.
- Five protocols:
ollama,openai_compat,anthropic,openai_responsesandbedrock. skep provider presetslists the built-in catalog. Each row says where prompts go.- "Local" holds only with a local Ollama daemon. The
ollama-cloudpreset, with its default model, sends every prompt to ollama.com. With any hosted model, prompts, including your code, go to that provider. - The
openai-codexpreset runs the assistant on a ChatGPT plan through the Codex login. Workers never use it. - There is also an Ollama planner worker (
python -m skep.workers.ollama, a--worker-cmdvalue). It uses the assistant's provider unless bothSKEP_OLLAMA_URLandSKEP_OLLAMA_MODELare set for it; the model variable alone is ignored.
skep provider presets preset protocol key env default model # excerpt: two of the rows ollama-cloud ollama OLLAMA_API_KEY glm-5.2 CLOUD (Ollama Cloud) — every assistant/worker prompt leaves this machine for ollama.com anthropic anthropic ANTHROPIC_API_KEY claude-sonnet-4-5 CLOUD (Anthropic) — every assistant/worker prompt leaves this machine for api.anthropic.com
Your own worker
The worker contract
Anything that reads skep's task file and writes its result file can be a worker. The contract is at version 0.3.8.
- skep starts the worker with
--headless --task-file <path> --out <path>. The task is a JSON file, not standard input. - The worker appends events, one JSON object per line, to
.events/<task_id>.ndjsonin its workspace, and writes one result JSON whosestatussays how it ended and whoseartifactslist the patch. - skep trusts only those files, and re-verifies the claimed result itself.
Govern an agent you run elsewhere
The Claude Code hook
skep policy hook is a Claude Code PreToolUse hook. Claude Code asks skep before a gated tool call, and the answer comes from the same policy a skep run is held to.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash|Edit|Write|MultiEdit|NotebookEdit|WebFetch|WebSearch",
"hooks": [{ "type": "command", "command": "skep policy hook" }]
}
]
}
} | Claude Code tool | Decided as |
|---|---|
| Bash | shell.run, on the command |
| Edit, Write, MultiEdit, NotebookEdit | filesystem.write: the workspace, or the literal path when it is outside |
| WebFetch | network.fetch, on the host |
| WebSearch | network.search |
| Read, Glob, Grep and the rest | No opinion: Claude Code's own permissions decide |
| skep says | Claude Code does |
|---|---|
| allow | Runs the call |
| deny | Refuses the call and names the rule or the floor |
| ask | Asks you. Also the answer when no rule matched, when skep could not decide, and on a home with no approved baseline |
Every answer is a line in the decision log. The hook reads the skep home directly, so the daemon need not be running. The policy hook doc
Govern an agent you run elsewhere
The ACP governor
skep acp govern is a process an ACP client, such as T3 Code or Zed, starts in place of the agent. It passes every message through except the agent's permission request, which it answers from policy.
$ pipx install skep && skep onboard --template builder --yes
$ skep acp doctor -- npx -y @agentclientprotocol/claude-agent-acp
$ skep acp install-hint
# afterwards: what the agent asked and did
$ skep policy decisions --actor 'acp:*' - An allow or a deny is answered before the client sees it. What skep cannot decide is forwarded to you in the client.
- Every verdict, every tool call the agent ran without asking, and every answer you gave is recorded.
skep acp doctorprints the agent's modes and warns when its default mode never asks.
skep acp install-hint baseline: builder approved 2026-11-19T00:23:26Z sha256 01db10ac4fc3 Local ACP command — claude-agent-acp executable: /home/you/.local/share/uv/tools/skep/bin/skep arguments, one row each (B3-F1: a single row is one literal argument): acp govern -- npx -y @agentclientprotocol/claude-agent-acp # cut here: the same block for codex-acp
See what is running
skep agents
One view of the coding agents running on this machine right now, and whether skep governs each.
skep agents 4 agent(s) running: 0 governed by skep, 4 not 938790 claude idle ungoverned 946438 claude idle ungoverned 948000 claude idle ungoverned 949679 claude idle ungoverned blocked is read from output, which skep has only for processes it started; other agents show working/idle by CPU
Agents are matched by process name. An agent counts as governed when it runs under a
skep worker. blocked is read from output, which skep has only for
processes it started.