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.

The engine registry
EngineWhat runsSigns in from Execution modeIts 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
pin an engine for a project
# 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"
or choose it for one run
$ 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 --minimal run, or a template with no project, skips project policy and this check with it: there re-verification can only re-run git diff --check.
  • skep doctor looks 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-cmd or SKEP_WORKER_CMD) is treated as that engine: sandbox, sign-in and pinned verify command included. A project pinned to an external engine refuses --worker-cmd unless 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: engines
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)
captured: skep doctor on a fresh throwaway home, 2026-11-18; paths shortened

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

sign-in variables
# 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 a serve.env file in the skep home, which skep serve loads at startup.
  • skep passes these variables to the agent by name. A serve.env file is one you write and protect yourself.
  • Without one, the run is refused before anything starts.
refused: no sign-in variable
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
captured: skep run on a project pinned to claude_code with no auth variable set, throwaway HOME shown as ~, 2026-11-18

Codex on a ChatGPT plan

opt in, per project
$ 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_KEY is 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.com where a key-based run talks to api.openai.com.
  • skep doctor shows whether a Codex login exists. --no-codex-chatgpt-login turns it off again.

How the plan login is handled

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_responses and bedrock.
  • skep provider presets lists the built-in catalog. Each row says where prompts go.
  • "Local" holds only with a local Ollama daemon. The ollama-cloud preset, with its default model, sends every prompt to ollama.com. With any hosted model, prompts, including your code, go to that provider.
  • The openai-codex preset 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-cmd value). It uses the assistant's provider unless both SKEP_OLLAMA_URL and SKEP_OLLAMA_MODEL are set for it; the model variable alone is ignored.

Choosing the assistant model

skep provider presets
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
captured: skep provider presets, 2026-11-18; two of the catalog's rows

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>.ndjson in its workspace, and writes one result JSON whose status says how it ended and whose artifacts list the patch.
  • skep trusts only those files, and re-verifies the claimed result itself.

Worker adapters and the custom contract worker

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.

~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write|MultiEdit|NotebookEdit|WebFetch|WebSearch",
        "hooks": [{ "type": "command", "command": "skep policy hook" }]
      }
    ]
  }
}
How a tool call is judged
Claude Code toolDecided as
Bashshell.run, on the command
Edit, Write, MultiEdit, NotebookEditfilesystem.write: the workspace, or the literal path when it is outside
WebFetchnetwork.fetch, on the host
WebSearchnetwork.search
Read, Glob, Grep and the restNo opinion: Claude Code's own permissions decide
What skep's verdict becomes
skep saysClaude Code does
allowRuns the call
denyRefuses the call and names the rule or the floor
askAsks 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.

set it up
$ 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 doctor prints the agent's modes and warns when its default mode never asks.

The ACP governor doc

skep acp install-hint
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
captured: skep acp install-hint after onboarding, 2026-11-18; home directory renamed

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
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
captured: skep agents with four Claude Code sessions open that skep did not start, 2026-11-18

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.