Files
pipelines/docs/harnesses.md
T
alan 108c29f9eb One harness setup path: pipelines harness setup <claude|codex|opencode|pi>
Checks the CLI on the server's PATH (install command when missing), signs in
with the harness's own login only when needed (--login forces it), keeps the
OpenCode/Pi model pickers, and verifies with the server's check. Works on
native and Docker installs (Docker delegates to the container setup); --host
is a hidden compatibility alias. harness list shows all four harnesses'
installed/signed-in/configured/default status. ./install --opencode|--pi now
point to the command; ./install ends with the next-step hint.
2026-11-02 16:11:04 +00:00

269 lines
12 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 | no | yes | yes, delivered into the running turn | no |
| Codex | no | yes | yes, via `turn/steer` | no |
Stage configs accept only `harness=opencode` or `harness=pi`.
## 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`).
**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
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:** the server starts its own loopback `opencode serve` for chat
and for stage sessions, using your normal OpenCode configuration and login.
A server started with `-opencode-endpoint URL` (or
`PIPELINES_OPENCODE_ENDPOINT`) attaches chat to that service instead; the
native installer does not set this.
**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 only.
**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.
**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.
## Codex
**Used for:** chat only.
**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.
## 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.
## 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.