Pane Handoff —
File-Based Routing

Four commands cover 95% of day-to-day usage. Read once, memorise, refer back when something doesn’t paste.

Mental model — two independent switches

Reading the examples

Every command below has a pane tag showing where to run it:

IMPL the pane where Claude implements AUDIT the pane where Claude reviews ANY file-only, anywhere MAC plain Mac Terminal outside Claude

One installer covers everything: dependencies, file placement, launchd registration, and arming. Idempotent — safe to re-run after edits.

The user-facing API lives in shell functions. Append the block, source ~/.zshrc, you’re done.

You now have these commands available in every pane:

Example uses scope name myapp. Substitute your project name (lowercase, no spaces).

iTerm assigns a new session UUID every time a pane opens. Yesterday’s *.id bindings point at UUIDs that no longer exist. You only need to re-claim.

Watcher health check (only if something looks off)

Two directions, two scoped filenames, one delivery contract: write a file, the watcher pastes it.

HALT is scoped. A halt in myapp does not block any other project.

This writes ~/.claude/handoff/HALT.$HANDOFF_SCOPE. Equivalent explicit form:

Effect

• Watcher echoes ⛔ HALT scope=myapp + contents to /tmp/handoff.log
• macOS notification fires (Basso sound) tagged with the scope
• AUDIT and IMPL pre-flight in that scope see the sentinel and stop
• Other scopes are unaffected — they continue to send/receive normally

Resume (after a human resolves the issue)

Common failure modes and how to diagnose them from /tmp/handoff.log.

“Inbox file shows 0 bytes — is that a failure?” (FAQ)

How to tell success from failure (since the file looks the same in both cases):

“Delivery failed — file NOT truncated”

Three causes, in order of likelihood:

1. Stale binding (most common after reboot): the bound pane no longer exists. Re-claim from the live pane (§4).
2. No binding for that scope: you wrote to-impl.foo.txt but impl-target.foo.id doesn’t exist. Run handoff-claim-impl with HANDOFF_SCOPE=foo from the intended pane.
3. iTerm AppleScript permission denied: macOS → Settings → Privacy & Security → Automation → grant access to iTerm/osascript.

Watcher not running — check + recover

Force-restart the watcher

The watcher does NOT hot-reload. After editing ~/.claude/hooks/pane-handoff.sh, restart:

Routing disarmed (no log lines at all)

Why does pgrep show 2 pane-handoff.sh processes?

That’s correct. The watcher uses fswatch | while ..., which forks a subshell. Steady state under launchd is 3 processes total: 2 × pane-handoff.sh (main + while-subshell) + 1 × fswatch. Anything more or fewer is a problem.

Pause routing globally without removing bindings

The clean way to deactivate the entire system while keeping pane bindings + scope + watcher process intact. Use it when you want to stop file→pane delivery temporarily (e.g. taking a break, swapping projects, debugging).

What handoff-off does NOT do:

• Does not stop the watcher process (it keeps running, just skips delivery)
• Does not remove pane bindings (your handoff-claim-* state survives)
• Does not delete HANDOFF_SCOPE in any pane

To fully deactivate everything (rare — usually only for OS troubleshooting):

Don’t put archives inside the watched dir

Every command, every path, every rule in one place.

Critical paths

Scope rules

• One scope per project. Lowercase, project-name-like (myapp, acme_api).
• The name meta is reserved for cross-project planning / orchestration.
• Unscoped sends (to-impl.txt with no .<scope>) are refused on purpose.
• HALT is per-scope: HALT.<scope> pauses only its scope. There is no global pause.

Five probes that prove two projects can run concurrently without cross-talk.

Pane choreography

• Window M — MAC terminal for tail -f /tmp/handoff.log and direct probe writes
• Window A — iTerm. Two panes: proj_a IMPL + AUDIT
• Window B — iTerm. One pane: meta IMPL

Probe 1 — Scoped delivery isolation

Pass: Window A IMPL shows only ping A …; Window B IMPL shows only ping META …; log shows two separate -> IMPL scope=… + delivered-marker pairs. No WARN.

Probe 2 — Unscoped writes refused

Pass: log shows WARN: refusing unscoped to-impl.txt; file drained; neither pane received the text.

Probe 3 — HALT isolation

Pass: log shows ⛔ HALT scope=proj_a AND meta delivery succeeds despite the HALT.

Probe 4 — Missing scope refused

Pass: shell prints the error; no file written; no log line generated.

Probe 5 — /start-audit cold-start sees only its own scope

Restart Claude in the AUDIT pane, run handoff-use proj_a + /start-audit. The slash command does NOT pre-flight read the inbox file (it is 0 bytes by design after delivery); it only checks the scoped HALT (HALT.proj_a — absent), and stops cleanly. No foreign-project content surfaces.

The actual flow under the hood — useful for debugging unfamiliar failure modes.

AUDIT pane                  Watcher                       IMPL pane
 (Claude)               (pane-handoff.sh)                  (Claude)
    |                          |                              |
    |  Bash tool:             |                              |
    |  cat > to-impl.myapp.txt |                              |
    |  ----------------------> |                              |
    |                    fswatch fires                       |
    |                    reads file                           |
    |                    wraps in bracketed-paste             |
    |                    osascript -> iTerm session id ------> |
    |                    <----- ok                           |
    |                    truncates file to 0 bytes            |
    |                    logs delivered-marker                |

Why bracketed paste?

Without it, multi-line content with blank lines or code blocks would submit on the first \n. Bracketed paste tells the terminal “this is paste content” — the receiving Claude sees it as a single fresh user message.

Why scope-keyed filenames?

So two projects run side-by-side. to-impl.proj_a.txt routes to impl-target.proj_a.id; to-impl.meta.txt routes to impl-target.meta.id. No cross-talk possible.

Why a Stop hook on IMPL?

Without it, the model can claim → handed back in chat without actually writing the file — leaving AUDIT idle and the loop silently broken. enforce-handback.py detects this exact failure mode and forces the model to either write the file or remove the marker.