Skip to main content
Agent skill

Orca Pi Connect

Connect the foreman's session to a builder in an Orca pane, Pi or Claude Code (any Claude model), and PROVE the link (a pane the foreman opened itself (or one the owner confirmed) + assigned session id, two-round handshake, Stop-log and session-file evidence), then send work-order pointers and wait on the builder's real turn-end signal. Use for /orca-pi-connect, "connect to pi", "connect to the claude builder", "set up the builder pane", or before a Topping Out job whose repo profile says builder delivery = pane link. Orca only (another pane host: hand-carry the pointers). Proves and uses the channel; never decides or approves anything for the owner. Also answers to its old name, /pi.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Orca Pi Connect when an AI agent needs a reusable SKILL.md workflow for this job: Connect the foreman's session to a builder in an Orca pane, Pi or Claude Code (any Claude model), and PROVE the link (a pane the foreman opened itself (or one the owner confirmed) + assigned session id, two-round handshake, Stop-log and session-file evidence), then send work-order pointers and wait on the builder's real turn-end signal. Use for /orca-pi-connect, "connect to pi", "connect to the claude builder", "set up the builder pane", or before a Topping Out job whose repo profile says builder delivery = pane link. Orca only (another pane host: hand-carry the pointers). Proves and uses the channel; never decides or approves anything for the owner. Also answers to its old name, /pi.

When not to use it

Skip Orca Pi Connect when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/orca-pi-connect
# Save SKILL.md to ~/.claude/skills/orca-pi-connect/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/orca-pi-connect/SKILL.md. For a shared project, commit the folder at .claude/skills/orca-pi-connect/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Orca Pi Connect skill for this task: Use Orca Pi Connect when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

69/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
52/100
Source signals
72/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# orca-pi-connect: the foreman ↔ a Pi builder, over Orca

The pane link for a repo whose builder runs in **Orca** (repo profile: builder delivery = pane link). It is the one bundled pane link: the Pi pieces it needs (the stop extension and `stop-watch.mjs`) live in this folder. Proven with pi 0.87 to 1.0 and orca 1.4.

Evidence, not vibes. Every claim is proven by an observable (a Stop-log line, a file on disk, a reply), never by a quiet pane.

``` 1 binding the foreman opened the pane itself (exactly one new pane, on its right, fresh SID, or the old SID in a §1b resume), or the owner confirmed the handle + SID 2 pane Orca can target that binding and submit prompts 3 hook Pi's global agent_settled extension logs ONCE per genuine turn end 4 replies Pi answers, runs tools, and the reply is readable 5 session the on-disk session file records the turn under the bound id ```

## A Claude Code builder (any Claude model)

The repo profile's "Builder delivery" row says which harness the pane runs: `pane link (pi)`, the default, or `pane link (claude-code)`. Everything in this skill holds for both; with Claude Code, read these in place of the Pi parts. Proven with Claude Code 2.1.325 and orca 1.4 (a real pane: both handshake rounds, one line per turn, a resume).

- **One-time setup, by the owner** (it names the model, so it lives outside every repo): `node .claude/skills/orca-pi-connect/claude-code/claude-builder.mjs --model <model> [--permission-mode <mode>]`. It writes `~/.claude/foreman-builder/settings.json` (the model, the permission mode, the Stop hook) and a copy of the hook beside it. Any Claude model works, by name or alias (`claude-haiku-5-5`, `sonnet`, `opus`). Run it again to change the model. **Permission mode:** `auto` (the default: routine actions run, risky ones are refused) suits a builder; `acceptEdits` asks before shell commands, so an unattended run stalls; `bypassPermissions` asks nothing. **MCP servers:** a repo's `.mcp.json` makes Claude Code ask "New MCP server found" in every new folder, and each job's worktree is new, so an unattended builder stops there. `--mcp all`, the default, loads the repo's servers without asking; `--mcp none` loads none. Running the setup again without `--mcp` keeps the earlier choice. A setup made before this option reads MISSING until it is run again. - **Trust, once:** Claude Code asks "Do you trust this folder?" in a folder it hasn't seen, and the answer covers every folder inside it. Each job's worktree is new, so the owner trusts the folder the worktrees live in once (Orca's: `~/orca/workspaces/<repo>`): start `claude` there and answer yes. If the prompt, or an MCP prompt, shows in the builder pane anyway, surface it to the owner; never answer it with keystrokes. - **The wake signal:** the hook (`claude-code/foreman-stop.mjs`) runs on Claude Code's `Stop` event, once per finished turn of the builder (a subagent's end is `SubagentStop`, which it doesn't hear). Same line format, its own log: `LOG="$HOME/.claude/foreman-stops.log"`. Only a session started with `--settings <that file>` loads it, never the foreman. If another Stop hook of the owner's can block a stop, a line can come before the turn really ends: the report-file rule (§6 step 4) catches it. - **§0 preconditions:** `claude --version`, then `node .claude/skills/orca-pi-connect/claude-code/claude-builder.mjs --check` (READY, with the model and mode; MISSING: stop and ask the owner to run the setup), in place of the `pi` and extension checks. - **§1 split command:** take the settings path from `--check`, never from `$HOME` (in Git Bash `$HOME` is `/c/Users/...`, which the pane's shell and Claude Code can't read): `CHK=$(node .claude/skills/orca-pi-connect/claude-code/claude-builder.mjs --check); SET=$(printf '%s\n' "$CHK" | sed -n 's/^settings: //p'); FLAGS=$(printf '%s\n' "$CHK" | sed -n 's/^flags: //p')`, then `--command "cd '$WT'; claude --settings '$SET' $FLAGS --session-id $SID"` (`FLAGS` is `--strict-mcp-config` under `--mcp none`, otherwise empty). No `--approve`: trust and the permission mode cover it. - **§1b resume:** `claude --settings '$SET' $FLAGS --resume <old SID>`: the session and its lines keep the old `SID`. - **§3 model check:** the pane's banner names the model under the version line (`Haiku 5.5 · …`); it must be the one `--check` printed. - **§5 session file:** `ls -l ~/.claude/projects/*/"$SID".jsonl`. - **§6 step 7:** close the pane the same way; `/exit` alone leaves an empty shell. - **Usage:** a Claude builder draws on the owner's Claude plan, the same limit as a Claude foreman. Its first job is an audition (`BUILDER-PROFILES.md`). - **What it loads:** the worktree's own `CLAUDE.md`, `.claude/settings.json`, skills and agents, and the owner's user settings. The work order is still the whole instruction (`METHOD.md` §12): it never asks the builder to run a Topping Out skill or agent.

## The wake signal

- Extension: `~/.pi/agent/extensions/foreman-stop.ts`, Topping Out's own. It's global, binds `agent_settled`, fails open, and guards against child agents (`FOREMAN_PI_STOP_OWNED`). The source is bundled at `.claude/skills/orca-pi-connect/pi-extension/foreman-stop.ts`. On a new machine, copy it to `~/.pi/agent/extensions/` and restart Pi. - Log: `~/.pi/agent/foreman-stops.log`. Lines look like `STOP tag=<cwd folder> session=<id>`; filter by `session=<id>`. - Watcher: `.claude/skills/orca-pi-connect/stop-watch.mjs`. Exit 0 = turn end, 2 = timeout, 3 = bad args. - Proved: one headless Pi turn (`pi -p --session-id <uuid>`) wrote exactly one line, and the watcher returned exit 0. Other global stop extensions log to their own files and don't interfere.

```bash LOG="$HOME/.pi/agent/foreman-stops.log" WATCH=".claude/skills/orca-pi-connect/stop-watch.mjs" ```

## Halt

- A pane read with a missing or wrong handle can hit **this** session. That's a targeting halt, not builder evidence. - Dim composer ghosts or predicted "next message" text aren't the builder speaking. - The TUI can swallow a paste. If the prompt is sitting in the composer, send Enter only; don't resend. - **Never infer a finished turn from a quiet pane or `orca terminal wait --for tui-idle`.** A long tool call looks identical. The Stop log is the only completion signal. - **`Timed out waiting for split pane handle` does not mean no pane was created.** Orca timed out waiting for the *handle*; the pane is often already open on the right. A split error is UNKNOWN until §1's wait-and-count says otherwise. - Pi shows a trust or tool-approval prompt: surface it to the owner. Never blind-approve with keystrokes. (Starting Pi with `--approve` in §1 is the deliberate, up-front trust for the job's own worktree; it is not a keystroke approval.)

## 0. Preconditions

```bash orca worktree current --json # must be inside an Orca worktree echo "$ORCA_WORKTREE_ID" # set in every Orca pane pi --version grep -c "agent_settled" ~/.pi/agent/extensions/foreman-stop.ts # >= 1; missing file -> install it (see "The wake signal") grep -n "pi.on(" ~/.pi/agent/extensions/foreman-stop.ts # must be agent_settled, never agent_end test -f .claude/skills/orca-pi-connect/stop-watch.mjs # missing -> re-run SETUP §1's install (an older install kept it elsewhere) ```

`orca agent hooks status` reports Orca's own `orca-agent-status.ts`, which is a different extension and says nothing about the Stop signal.

## 1. Bind pane + session

**Assign the session id; don't discover it.** The builder goes in a pane **on the right of the foreman, in the same tab**, running **in the job's worktree**. Split the foreman's own pane: a split inherits the foreman's worktree (the main checkout) and takes no worktree flag, so the startup command changes folder first:

```bash WT="<job worktree, absolute>" # cut by the foreman before work order 1 (METHOD §4) orca terminal show --terminal "$ORCA_TERMINAL_HANDLE" --json # note the foreman's tabId orca terminal list --include-visual-layouts --json # BEFORE: count the panes in that tab SID=$(node -e "console.log(crypto.randomUUID())") # a FRESH id for every split attempt (one exception: §1b) orca terminal split --terminal "$ORCA_TERMINAL_HANDLE" --direction vertical --command "cd '$WT'; pi --approve --session-id $SID" --json orca terminal list --include-visual-layouts --json # AFTER: exactly one new pane, on the right, in the foreman's tab ```

**The split is confirmed by the count, not by the command's reply:** - **A split error is UNKNOWN, never a failure** (the timeout above, or any other error). List the panes again a few times over about 10 seconds (`orca terminal list --include-visual-layouts --json`), counting the panes in the foreman's tab. A new pane there means the split worked: take its handle from the list. Only an unchanged count after those checks means it failed. One immediate look proves nothing: a pane can register a few seconds late (the same rule as rule 12 of the Foreman rules in `RULES.md`, an empty read is not "nothing yet"). - **Never split a second time on your own.** If the wait shows no new pane, **stop and ask the owner to look** at the foreman's tab: the pane list can lag, and the owner can see the screen. Split again (with a new `SID`) only after the owner says there is no new pane. (Learned in job 08: two splits, both "unconfirmed" by the list, both opened a pane.) - **No fallback outside the foreman's tab.** Never `orca terminal create` (it opens a separate tab), and never start the builder in a terminal that already exists in another tab (the new worktree's own startup terminal included). If the split can't be confirmed in the foreman's tab, stop and tell the owner; never call another layout "a minor deviation". - **Duplicates** (two or more builder panes): keep **one** pane on the right in the foreman's tab, close the rest, and redo the kept pane's handshake (§3–§5) if any other pane shared its `SID`. The layout rule wins over handshake evidence: a handshake costs a minute to redo. After closing the duplicates, the kept pane still needs the owner's yes (§1: the count was off). - Orca files the new pane under the foreman's worktree (its `worktreePath` is the main checkout). That's expected. **Pi's own working directory is the proof**, checked in handshake round 1 (§3).

- `--direction vertical` puts the pane on the **right**. Orca's own guide states this backwards. - `--approve` (Pi 1.0+) trusts the project's own files for this run, so a new worktree doesn't block on "Trust project folder?" and an autonomous run never waits on the owner's Enter. Only for a worktree of the owner's own repo. If the prompt appears anyway (an older Pi), read the pane and surface it to the owner. - The session file only appears after the first turn: `~/.pi/agent/sessions/<cwd-slug>/<timestamp>_<SID>.jsonl`. - For a pane the owner started by hand, resolve the id from `ls -t ~/.pi/agent/sessions/<cwd-slug>/` and a fresh Stop-log line. **Never ask Pi for its own session id.**

**A pane you opened yourself binds without asking:** the split ran in this session with a fresh `SID` (or, for a §1b resume, the old `SID` whose session file exists), the count went up by exactly one, and the new pane is on your right in your tab. Say which handle and `SID` you bound, in one line, and go straight to the handshake (§3), which proves the pane is Pi in the job's worktree. **Ask the owner only** for a pane you didn't open (one the owner started by hand), when two panes share a worktree, or when the count or placement is off: then put the handle + `SID` to the owner and get an explicit yes.

## 1b. Resume after the host slept or restarted

The builder pane died with the host, but its Pi session file exists (`~/.pi/agent/sessions/<cwd-slug>/<timestamp>_<SID>.jsonl`): split a new pane exactly as in §1, **with the old `SID`** (`pi --approve --session-id <old SID>`), which resumes its context. Redo both handshake rounds (§3, §4) and confirm the session file grew; the Stop-log count carries on from the old `SEEN` (the log is global, but counted by `session=<SID>`, so the old count still holds). Record the resume in the job file. This is the only reuse of a `SID`: a failed or duplicate split always takes a fresh one.

## 2. Revalidate, then snapshot

Right before every send:

```bash orca terminal show --terminal <handle> --json # worktreePath, branch, tabId, incarnationId unchanged since binding SEEN=$(node "$WATCH" --session "$SID" --count --log "$LOG") # never `grep -c … || echo 0`: on a log with no line for this session grep prints 0 AND exits 1, so the fallback adds a second 0 and the waiter exits 3 ```

If anything moved, go back to §1. Count only the bound session's lines, because the log is global.

## 3. Handshake round 1: identity (no tools)

```bash orca terminal read --terminal <handle> --limit 1 --json # keep result.terminal.nextCursor orca terminal send --terminal <handle> --enter --json --text "Handshake check from the Foreman controller. Reply with exactly two lines: (1) your working directory, (2) the word READY. Do not run any tools or commands." node "$WATCH" --session "$SID" --seen "$SEEN" --log "$LOG" # run as a BACKGROUND command so its exit wakes you orca terminal read --terminal <handle> --cursor <nextCursor> --limit 80 --json ```

Check all of these: - The reply contains the job worktree's absolute path and READY. Strip ANSI and match the string. - The bound session's count grew by at least 1, and the new line's `session=` equals `SID`. - The pane footer shows the model the job expects. Ctrl+P silently cycles models; a changed footer means a changed builder.

## 4. Handshake round 2: tool loop

```bash orca terminal send --terminal <handle> --enter --json --text "Run three SEPARATE bash commands, one at a time: echo one, then echo two, then echo three. Then print the value of ORCA_TERMINAL_HANDLE, and reply DONE." node "$WATCH" --session "$SID" --seen <count after round 1> --log "$LOG" ```

Check all of these: - There were three separate tool calls and `DONE`. - The printed `ORCA_TERMINAL_HANDLE` equals the prompted handle. - **The count grew by exactly 1**, not 3. One line per real turn end. If it's more, the wrong event is bound, and every `--seen` downstream is wrong.

## 5. Session file

```bash ls -l ~/.pi/agent/sessions/<cwd-slug>/*"$SID"*.jsonl # exists, mtime inside the handshake window ```

The reply, the Stop log and the session file are three witnesses to the same turn.

## 6. Using the link in a Topping Out job (METHOD §7e)

For each work order: 1. Revalidate (§2) and take `SEEN`. 2. Send **only the one-line pointer** to the work-order file, never the pasted text. Mark the file header *"Sent by the foreman as a one-line pointer."* 3. Arm `stop-watch.mjs` as a **background** command right after the send. A foreman that only checks the log during its own turns misses stops made while it's idle. **If the host kills the watcher** (memory pressure), don't restart it in the background unasked; say so in the reply and wait in the **foreground, repeated**: `node "$WATCH" --session "$SID" --seen "$SEEN" --log "$LOG" --timeout-seconds 540`, reading the log before each wait. **At the start of your next turn, read the Stop log yourself** (`node "$WATCH" --session "$SID" --count --log "$LOG"` against `SEEN`) and act on any new STOP: a reaped watcher must not hide one. 4. On exit 0: **disk check first** (commits, captures, files), then read the builder's report file. The pane text isn't the report. **A Stop counts as the work order's end only when its named report file exists:** a Stop with no report (a tool-call timeout mid work order, say) is not done; read the pane and wait again. 5. On exit 2 (timeout): check `orca terminal show` for `connected: true` and an unchanged `incarnationId`. Never restart the builder on a quiet read. 6. **Any other exit** (1, 3), or a Stop log you can't read: tell the owner the link is down and go hand-carried (METHOD §7e). Never go quiet. 7. **At the end game**, before removing the job's worktrees (METHOD §10 step 4), close the builder **pane**, not just Pi: `orca terminal close --terminal <builder handle> --json`. Pi runs inside the pane's shell, so stopping Pi (or Pi exiting) leaves an empty shell pane behind. Then **check it's gone**: `orca terminal list --include-visual-layouts --json` shows your tab with only your own pane. A pane still there (a bare shell prompt): close it by its handle again; never leave it.

The owner keeps every word `RULES.md` reserves (merge, push, deletions). The link only carries pointers.

## 7. Report

Say whether the link is proven. Include the bound handle and `SID` (assigned; and whether you opened the pane or the owner confirmed it), both rounds, the Stop-log counts before and after, the session file, the model in the footer, and any findings. Don't start builder work without the owner's go.

## Failure handling

- **The log didn't grow after a finished turn:** the wake signal is dead. Check the extension file, its `agent_settled` binding, and Pi's startup output for a load error. Don't proceed, and don't substitute `tui-idle`. - **The log grew by more than 1 in one turn:** wrong event, or the PID guard (`FOREMAN_PI_STOP_OWNED`) was removed. Fix it before trusting any count. - **The prompt produced no visible change:** read the pane before resending. It may be mid-turn, or blocked on a trust or approval prompt. - **Pi's working directory in round 1 isn't the job worktree** (the `cd` failed or was skipped): close that pane and split again with the `cd`. Never use it anyway, and never fall back to `orca terminal create` (a separate tab). - **The handle printed in round 2 differs, or `incarnationId` changed:** the pane was replaced. Rebind: a pane you open again yourself binds as in §1; any other pane needs the owner's confirmation. - **Pi never starts:** the pane is a live shell, so read the actual error (PATH, bad `--session-id`, missing provider credentials). - **The split returned an error or timed out:** it's unknown, not failed. Do §1's wait-and-count before anything else; if still unconfirmed, ask the owner to look; never retry on your own, fall back to another tab, or reuse the `SID`. - **More than one builder pane exists:** keep one, on the right, in the foreman's tab; close the others; redo its handshake if they shared a `SID`. Record the false start in the job file.

Intended uses

  • Use Orca Pi Connect when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.