# 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 ` 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 --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 `. 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=` 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/` 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-.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 --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 [--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 && claude --resume ` | | Codex | `cd && codex resume ` | | OpenCode | `cd && opencode --session ` | 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 `/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 --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.