Files
pipelines/docs/harnesses.md
T
alan bd07abcde8 Run pipeline stages on Claude Code (harness=claude)
A model stage with harness=claude, provider=anthropic and a Claude model id
runs one claude -p process per visit with the server user's Claude sign-in.
Only the declared tools exist (--tools) and nothing else is approved
(--permission-mode dontAsk); edits are approved only below the run directory
and the stage's artifacts directory. A permissions block, run write paths,
delivery=true and reasoning_effort none/minimal are refused, not widened.

Usage comes from the CLI's final result and counts toward budgets. Failures
are fixed text; billing, quota and rate-limit refusals map to
ErrProviderQuota. The redacted stream is the session export and evidence.
provider-check --harness claude and model overrides are covered.
2026-11-11 10:30:37 +00:00

20 KiB

Harnesses

A harness is the agent program Pipelines drives. Pipelines never installs or upgrades a harness; it uses the copy you install on the server machine and the harness's own login, which pipelines harness setup <name> opens for you.

Harness Pipeline stages Chat Mid-turn messages Authoring/debug sessions
OpenCode yes (default) yes (default) queued until the turn ends yes
Pi yes (harness=pi) no n/a yes
Claude Code yes (harness=claude) yes yes, delivered into the running turn no
Codex no yes yes, via turn/steer no

Stage configs accept harness=opencode, harness=pi or harness=claude.

Set up harnesses

After ./install (native or --docker), set up each harness with one command. It works the same on native and Docker installations (the mode is detected from the installation):

pipelines harness setup opencode   # stages + chat: sign in, pick the two default models
pipelines harness setup pi         # stages: sign in via /login, pick the two default models
pipelines harness setup claude     # chat: claude auth login if needed, verify
pipelines harness setup codex      # chat: codex login if needed, verify the App Server socket
pipelines harness list             # installed / signed in / configured / default, all four

Each run:

  1. Checks the CLI is installed where the server finds it (the PATH recorded by ./install, plus the locations listed per harness below). If it is missing, it prints the install command and stops:

    Harness Install command
    OpenCode curl -fsSL https://opencode.ai/install | bash
    Pi npm install --global @earendil-works/pi-coding-agent
    Claude Code curl -fsSL https://claude.ai/install.sh | bash
    Codex npm install --global @openai/codex
  2. Signs in with the harness's own login only when it is not signed in (opencode auth login, Pi's /login, claude auth login, codex login). --login forces it.

  3. Models. OpenCode and Pi: fuzzy-pick the interactive model and the new-pipeline model (or pass --model P/M --pipeline-model P/M; --default makes the harness the default). Claude Code and Codex: nothing to pick; models are chosen per chat in the app.

  4. Verifies with the server's own check and prints one success line: OpenCode/Pi list both models from a signed-in provider (no inference); Claude Code claude auth status; Codex the App Server socket. No restart is needed: new runs read OpenCode/Pi profiles when they start, and the server looks for Claude Code and Codex every 10 seconds. (After a first OpenCode sign-in to a new provider, run pipelines restart if the app's chat does not offer it yet.)

OpenCode is required: ./install stops without it, because it is the default stage and chat harness, and configures its profile itself. Claude Code and Codex are chat-only and need a native installation.

Choosing models

Pipeline stages. Each model stage pins its own model in its configs block:

```configs
provider=PROVIDER
model=MODEL
harness=opencode
reasoning_effort=high
```

harness defaults to opencode. reasoning_effort is optional; see harnesses and control. Use the exact IDs your harness lists (opencode models, pi --list-models).

A stage on Claude Code uses the server user's Claude sign-in and a Claude model ID, for example a cheaper model for a small change:

```configs
harness=claude
provider=anthropic
model=claude-haiku-5-5
```

See Claude Code stages for what such a stage can do.

Per run, without changing the definition:

pipelines run "my pipeline" "task" --model PROVIDER/MODEL
pipelines run "my pipeline" "task" --stage-model review=PROVIDER/MODEL

Precedence: --stage-model > --model > the model pinned in the stage. Unknown stage keys and malformed models are refused before the run starts.

Defaults for new pipelines and interactive sessions come from harness profiles in ~/.config/pipelines/harnesses.json (override with PIPELINES_HARNESS_CONFIG). Each profile has an executable, a model (interactive authoring/debug sessions) and a pipeline_model (stages in new drafts and starters). Published versions are never rewritten.

pipelines harness setup opencode                       # fuzzy-pick both models
pipelines harness setup pi --login                     # sign in to Pi again, then pick models
pipelines harness setup opencode --model P/M --pipeline-model P/M
pipelines harness default pi                           # default harness for new/edit/debug
pipelines harness list --json                          # profiles, launch mode and status

./install writes the OpenCode profile itself (from --model, the saved profile, or OpenCode's own default) and keeps an existing valid Pi profile; it never adds a Pi profile on its own.

Chat models are chosen in the chat's model picker; each harness supplies its own catalog.

Verifying

pipelines doctor                                 # health + OpenCode API discovery, no inference
pipelines provider-check --model P/M             # one tiny tool-free generation (may cost)
pipelines provider-check --harness pi --model P/M
pipelines provider-check --harness claude --model anthropic/claude-haiku-5-5
python3 scripts/check-pi-rpc.py                  # Pi RPC and policy, no inference

pipelines restart and pipelines doctor print the server's startup report. Its Chat row lists the chat harnesses the server found (for example claude, codex, opencode), and the Harnesses rows list the profiles. Then start a chat with each harness in the app.

OpenCode

Used for: default stage harness, default chat harness, and pipelines new, edit and debug sessions.

Found by: PIPELINES_OPENCODE, then PATH, then /opt/homebrew/bin, /usr/local/bin, /usr/bin, ~/.local/bin. ./install requires opencode on PATH and records its absolute path.

Launched as: chat uses the OpenCode service the server attached to (an endpoint from -opencode-endpoint URL / PIPELINES_OPENCODE_ENDPOINT, or a loopback opencode serve the server spawns). Stage sessions run on a separate Pipelines-owned loopback opencode serve, the stage service, which uses your normal OpenCode configuration, login and session database but adds the stage tool-output and compaction limits. See "OpenCode limits for stages and chats" in harnesses-and-control.md.

Install and sign in: pipelines harness setup opencode (runs opencode auth login when no provider is connected). Pipelines reads the default model with opencode api get /api/model/default.

Mid-turn messages: not supported by the harness. A message sent while a turn runs is stored in the server's durable queue (up to 8 per chat) and sent in order when the turn ends, also after a server restart.

Pi

Used for: pipeline stages with harness=pi, and new/edit/debug with --harness pi. Not a chat harness.

Found by: the executable in the pi profile. A run with a Pi stage is refused unless that profile exists on the server.

Launched as: pi --mode rpc --provider P --model M --session-dir <run dir> --no-approve --no-extensions --no-skills --no-context-files --no-prompt-templates --no-themes --extension policy.js. The policy extension enforces the stage's tool and edit permissions. reasoning_effort maps to Pi's thinking level and is verified before the task is sent.

Install and sign in:

pipelines harness setup pi

When Pi lists no models (or with --login) setup opens a bare Pi session; run /login there, finish the provider sign-in, and exit with Ctrl+C or Ctrl+D to return to model selection.

Claude Code

Used for: chat, and pipeline stages with harness=claude (see Claude Code stages).

Found by: PIPELINES_CLAUDE, then PATH, then ~/.local/bin/claude, /opt/homebrew/bin/claude, /usr/local/bin/claude. The server checks again every 10 seconds, so installing it later needs no restart.

Launched as: one claude -p process per active chat with stream-json input and output and --permission-prompt-tool=stdio (at most 8 live at once). Idle chats are resumed with --resume <id>. Approvals and AskUserQuestion appear as cards in the app.

Sign in: pipelines harness setup claude runs claude auth login when claude auth status (with the server's PATH and the fallbacks below) is not signed in. A background service can see a stale keychain entry; when the default login check fails, the server retries with the login file in ~/.claude. For a login that does not depend on either, create a long-lived token and store it privately:

claude setup-token
# save the printed token:
install -m 600 /dev/null ~/.config/pipelines/claude-token
$EDITOR ~/.config/pipelines/claude-token

PIPELINES_CLAUDE_TOKEN_FILE names another file. The file must be a regular, owner-only file. The startup report shows Claude service token present when it is read. An ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN or CLAUDE_CONFIG_DIR in the server's environment takes precedence, and a chat directory that chooses its own account wins over all of these (see Per-directory accounts and environment).

Models: the catalog comes from the CLI; switching applies live and is kept for the next turn.

Mid-turn messages: yes. The message is written to the running CLI's stdin and read at its next step. Model changes apply from the next turn.

Claude Code stages

A model stage with harness=claude, provider=anthropic and model=<Claude model ID> runs one claude -p process per visit in the run directory, signed in as the server user (the same sign-in the chats use; a run directory that chooses its own account keeps it).

  • Tools. Only the tools in the stage's tools block exist for the session (read, glob, grep, edit, shell, webfetch, websearch). Nothing else is approved: the CLI runs with --permission-mode dontAsk, and file edits are approved only below the run directory and the stage's artifacts directory. An undeclared tool or an edit elsewhere is refused by the CLI.
  • Not supported; the stage or run is refused, never widened: a permissions block, a run launched with --write-path, delivery=true (landing stays on OpenCode), and reasoning_effort none or minimal.
  • Isolation. User, project and local Claude Code settings, hooks, MCP servers, plugins and slash commands are not loaded. A CLAUDE.md in the run directory is still read by the CLI.
  • Usage. Cost and tokens come from the CLI's final result and count toward stage and run budgets; a result without usage fails a budgeted stage.
  • Failures. Diagnostics are fixed text. A billing, quota or rate-limit refusal stops the run without retries; a missing sign-in says so. The CLI's redacted stream is kept as the session export and evidence.
  • Recovery. A server restart during a Claude Code stage stops that process and fails the visit; it is not reattached.
  • Overrides. --model and --stage-model must give an anthropic/<model> for these stages; the launch is refused otherwise.

Codex

Used for: chat, and pipeline stages with harness=claude (see Claude Code stages).

Found by: the Codex App Server control socket at $CODEX_HOME/app-server-control/app-server-control.sock (default ~/.codex/...). The Codex app provides it while it runs. The server checks for it every 10 seconds and attaches when it appears. Pipelines never starts a Codex daemon or changes Codex settings.

Sign in: pipelines harness setup codex runs codex login when codex login status fails, then checks for the socket. Threads created from Pipelines are ordinary Codex threads and also show in the Codex app.

Behavior: new threads use the workspace-write sandbox and Codex's own approval policy; command, file-change and permission requests appear as approval cards.

Mid-turn messages: yes, with turn/steer pinned to the running turn. If the turn already ended, the message is queued for the next turn instead.

Per-directory accounts and environment

A chat runs in the directory you choose for it. For Claude Code the server also applies that directory's own environment, so the chat behaves as if you had opened a terminal there and started claude:

  • Working directory. The claude process starts in the chat directory with PWD set to it. Codex threads are started with that cwd and OpenCode sessions with that location, so every harness runs tools there.
  • Git identity. includeIf "gitdir:..." rules in your git config apply automatically: git resolves them from the working directory of a repository under the chosen directory.
  • direnv. When direnv is installed (the service's PATH, then /opt/homebrew/bin, /usr/local/bin, ~/.local/bin, ~/.nix-profile/bin) the server runs direnv export json in the chat directory, so an .envrc there or in a parent applies. Only an .envrc you already allowed is used; the server never runs direnv allow. A blocked .envrc is logged and shown in the chat as a "Directory environment" notice, and nothing from it is applied.
  • mise. When mise is installed the server merges mise env --json (untrusted config is reported the same way). When both set a variable, direnv wins.
  • A plain .env file is not read on its own; use an .envrc (dotenv loads one) so the allow check applies.

The result is merged onto the server's environment and cached per directory; editing an .envrc, a mise config, a file direnv watches, or allowing or denying an .envrc makes the next chat process read it again. Set PIPELINES_DIRECTORY_ENV=off in the server's environment to turn this off.

Choosing the Claude account per directory. When the directory's environment sets or unsets any of CLAUDE_CONFIG_DIR, CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_SECURESTORAGE_CONFIG_DIR, CLAUDE_CODE_USE_BEDROCK or CLAUDE_CODE_USE_VERTEX, that directory owns the account: the service token and the ~/.claude login-file fallback are not added, and inherited server credentials (CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN) are dropped unless the directory sets them. Transcripts kept in a directory's CLAUDE_CONFIG_DIR are found for history and resume, also after a restart. For example:

# ~/work/.envrc  (then run `direnv allow ~/work`)
export CLAUDE_CONFIG_DIR="$HOME/work/.claude-profile"
export GH_CONFIG_DIR="$HOME/work/.gh"

Sign that profile in once from a terminal in that directory (claude, then /login). Shell functions or aliases in ~/.zshrc that switch accounts by $PWD are not seen by the server, which does not run your shell; move them into an .envrc.

Codex and OpenCode chats share one App Server or opencode serve process across directories, so only the working directory applies to them; their account is the one that process uses.

Pipeline runs. A run resolves its workspace's environment the same way (direnv in the workspace, so a parent .envrc applies to a worktree below it; mise; the same account rule) when it starts, and again when it resumes after a decision or a restart. Everything the server starts for the run gets it:

  • Pi stage processes (PWD is the workspace).
  • OpenCode stages: the server runs one Pipelines-owned stage service per distinct environment (keyed by a hash of the change, registration opencode-stage-service-env-<key>.json beside the original opencode-stage-service.json), started with that environment, so the agent's shell commands, gcloud, and any claude it launches use the directory's accounts. Runs with the same environment share the service; a workspace without its own environment keeps the original service. An idle per-environment service is stopped after PIPELINES_OPENCODE_STAGE_IDLE_TIMEOUT (default 30m, off keeps it until shutdown); its registration stays, so a retained session revives on the same endpoint with the directory's current environment. With PIPELINES_OPENCODE_STAGE_SERVICE=shared stages run on the CLI-managed service and the directory environment does not reach their tools.
  • Delivery-gate checks (sh -c) and the gate's merge commands, the opencode CLI calls of plain model stages, and the git reads behind file-change captures.

When the directory chooses the Claude account (for example its .envrc sets CLAUDE_CONFIG_DIR), inherited CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN and CLAUDE_SECURESTORAGE_CONFIG_DIR are removed for all of these, as for chats.

The run detail (pipelines inspect <run> --json, field environment) records what applied: the directory, the .envrc files, the sources, the names of the variables set and unset, the dropped credential names, and the service key, never a value. A blocked .envrc or untrusted mise config is listed in the run's warnings (and printed by pipelines inspect); the run continues with the server's environment.

Adopting existing sessions

pipelines chat-adopt <session-id> [--harness opencode|claude|codex] [--title TEXT]

Without --harness, each available harness is asked. Stop using the session elsewhere once you continue it in Pipelines.

Continuing or exporting a chat

A chat's id is the harness's own session id (Claude Code session UUID, Codex thread id, OpenCode ses_…). The app's chat information sheet shows it with the harness and directory, and copies a command that continues the session in a terminal on the server machine:

Harness Resume command
Claude Code cd <dir> && claude --resume <id>
Codex cd <dir> && codex resume <id>
OpenCode cd <dir> && opencode --session <id>

Each chat_sessions row carries this as resume_command. Stop the turn in Pipelines before continuing the session elsewhere.

chat_export ({"chat_export": {"session_id", "format"}}) returns chat_export_file (name, mime, content, messages, truncated): markdown is a transcript of user and assistant messages and agent reports with timestamps and one line per tool call; json is the same as data. Reasoning and full tool output are left out, and an export is bounded at 8 MiB (older pages are dropped and truncated is set). native returns Claude Code's own JSONL transcript, offered when a row has native_export. Only operator chats are exported.

Limits

  • Stage session exports: the native session read is capped at 8 MiB and the rendered session.html at 8 MiB. A session over the read cap cannot be exported by retrying; the stage reports it.
  • Claude Code chat history: a transcript over 64 MiB is reported as exceeding the history limit instead of being truncated.
  • Codex tool detail in history is truncated at 64 KiB and marked as such.
  • Losing the Codex App Server connection drops pending approvals; they are reported as an error, not shown as still actionable.
  • Queued chat messages: at most 8 per chat while a turn runs.

Troubleshooting

  • Harness works in a terminal but not from the service. The login service does not read your shell profile. It uses the PATH recorded when you ran ./install (prefixed with <prefix>/bin). Rerun ./install from a shell where the harness is on PATH (setup tells you when this is the case). For OpenCode/Pi you can instead set an absolute executable with pipelines harness setup <name> --executable /path/to/bin.
  • Claude Code not listed under Chat. Run pipelines harness setup claude.
  • Codex not listed under Chat. Run pipelines harness setup codex; open the Codex app and confirm the socket exists under ~/.codex/app-server-control/. The installer does not record a custom CODEX_HOME for the service, so the default ~/.codex is used.
  • "Pi is not configured on this execution server". Run pipelines harness setup pi on the server machine.
  • "invalid provider/model identifier". Use the exact IDs from the harness's model list; placeholders such as default/default are refused.