Files
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

430 lines
20 KiB
Markdown

# 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):
```sh
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:
````markdown
```configs
provider=PROVIDER
model=MODEL
harness=opencode
reasoning_effort=high
```
````
`harness` defaults to `opencode`. `reasoning_effort` is optional; see
[harnesses and control](harnesses-and-control.md). 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:
````markdown
```configs
harness=claude
provider=anthropic
model=claude-haiku-5-5
```
````
See [Claude Code stages](#claude-code-stages) for what such a stage can do.
**Per run**, without changing the definition:
```sh
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.
```sh
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
```sh
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](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:**
```sh
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](#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:
```sh
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](#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](#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:
```sh
# ~/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
```sh
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.