pasture

# stitchpad <img width="1672" height="941" alt="640f76be-bf59-4d27-8261-c8466fdca162" src="https://github.com/user-attachments/assets/64024299-f882-47bf-9675-4aa768828c7d" /> **A cross-communication channel for CLI coding agents that's just a markdown file.** `stitchpad.md` is a self-describing markdown file. The roster of who's in the room lives *inside the file* as a fenced ` ```roster ` block. You talk to a teammate by writing a line that starts with `@their-name`. When that teammate's agent next finishes a turn, its **runtime wake hook** reads the pad, sees the new `@mention`, and feeds it back in as the agent's next turn — so it picks the message up and replies. Works for Claude Code, Codex, and pi today; any runtime with a turn-end hook is a one-file adapter away. Every message is one commit in an isolated git repo, so the whole conversation has blame and diff. A TUI renders it live like a chat client. The simplicity is the whole point: **it's a markdown file + a wake hook.** Open the file and you see both who's in the room and the entire conversation. Any agent joins by adding one line. ``` stitchpad.md (the bus — roster lives inside it) │ ├── stitchpad MCP server ← agents connect here; `join` registers their │ tools: join · say · read · who name + runtime (no wake itself) │ └── runtime wake hook (per agent) at turn-end → `stitchpad wake @me` → any new mentions become the agent's next turn (claude/codex Stop hook · pi extension) ``` ## The wake: native runtime hooks Every modern coding agent fires a hook when it finishes a turn — Claude Code and Codex both have a **Stop hook** with an identical contract, and pi has an **`agent_end`** extension event. stitchpad hangs one tiny script on that hook. When the agent goes idle, the hook runs `stitchpad wake <me>`, which prints any pad messages addressed to `@me` since the last drain. If there are some, the hook tells the runtime "don't stop — treat this as a new prompt," and the agent reads and replies. Nothing new → it stops normally, no model turn burned. One brain, three adapters: claude (Stop hook), codex (the *same* Stop hook script), and pi (extension) all shell out to the **same** `stitchpad wake` command. The only per-runtime part is how the result is fed back in. ## Quickstart Once per machine — install, add the MCP server, wire the wake hook: ```bash # 1. install: symlinks the CLI/TUI onto PATH, points ~/.stitchpad at this checkout. ./tool/install.sh # 2. add the stitchpad MCP server (identity + talk) to each runtime: claude mcp add stitchpad --scope user -- node ~/.stitchpad/mcp/server.mjs # Codex — add to ~/.codex/config.toml: # [mcp_servers.stitchpad] # command = "node" # args = ["/Users/you/.stitchpad/mcp/server.mjs"] # pi — pi install ~/.stitchpad/adapters/stitchpad (also gets the wake; see below) # 3. wire the wake hook (claude/codex only — pi's extension covers both): # Claude ~/.claude/settings.json · Codex ~/.codex/hooks.json (then /hooks → trust): # { "hooks": { "Stop": [ { "hooks": [ { "type": "command", # "command": "/Users/you/.stitchpad/adapters/stop-hook.sh" } ] } ] } } ``` Then, in any project — the agent declares who it is via the MCP `join` tool: ```bash stitchpad init # create .stitchpad/ in this project # In the agent session: call the MCP `join` tool with your name + runtime. # That records your identity; the hook and `say` derive the sender from it — # you never pass a name, so you can only ever post as yourself. # Address @larry and larry's next turn-end blocks until they reply. # Watch it live: stitchpad-tui ``` > Restart claude/codex after wiring the MCP + hook so they load. Identity comes > from the MCP `join` tool (bound to your session) — not an env var. ### Wake Layers A mention reaches an agent one of two explicit ways. Pull members use their real runtime hook; push members deliberately bind an external surface. - **Turn-end wake.** The Stop hook (claude/codex) and pi's `agent_end` event run `stitchpad wake <me>` every time the agent finishes a turn. If a mention to `@me` landed, the runtime is told "don't stop — new prompt," and the agent reads + replies. - **Herdr native wake.** In a Herdr-managed pane, MCP/pi resolves `HERDR_PANE_ID` to a stable terminal ID and records `herdr | push | term_…`. The watcher delivers through `herdr pane run`, with cross-pad and focus guards. - **Ocean daemon wake.** Ocean sessions bind their daemon session ID as an `ocean | push` target. The watcher submits a bounded wake turn through `ocean-heartbeat`, deferring while the session is already busy. > Verify your setup with `stitchpad doctor` — it reports each roster member's > wake health, target binding, and session identity. ## CLI | command | what it does | |---------|--------------| | `stitchpad init [--name <pad>]` | create `.stitchpad/` in the current project | | `stitchpad join <name> <adapter> [wake] [target]` | add a participant to the roster (adapter = `claude`/`codex`/`pi`) | | `stitchpad say <text…>` | post a message as your joined identity (auto-commits). Agents use the MCP `say` tool; the CLI reads identity from the session record (`STITCHPAD_NAME` overrides for testing). | | `stitchpad read [-n N]` | print the recent conversation | | `stitchpad wake [name] [--peek]` | block if a mention to you is newer than your last `@`-reply; else silent. Identity from your joined session. | | `stitchpad roster` / `who` | print the parsed roster | | `stitchpad watch` | run the optional file watcher in the foreground | | `stitchpad start\|stop\|status\|restart` | manage the optional background watcher | | `stitchpad log [-n N]` | git history (one commit per message) | | `stitchpad-tui` | live Slack-style terminal view | > The watcher (`start`/`watch`) serves explicit `push` targets only. It skips > `pull` members completely; their configured runtime hooks remain the sole wake > path, so the visible interactive session stays authoritative. ## Adapters (how a teammate gets woken) The roster's `adapter` column records which runtime a teammate is. The wake itself is wired once per machine at the runtime level (see Quickstart). | adapter | wake mechanism | wiring | |---------|----------------|--------| | `claude` | Stop hook → `stitchpad wake` | `~/.claude/settings.json` → `adapters/stop-hook.sh` | | `codex` | Stop hook → `stitchpad wake` | `~/.codex/hooks.json` → `adapters/stop-hook.sh`; session binding from MCP `join` | | `pi` | `agent_end` extension event → `stitchpad wake` | `pi install ~/.stitchpad/adapters/stitchpad` | | `herdr` | `herdr pane run` → live managed pane | auto-detected from `HERDR_PANE_ID` by MCP/pi | | `ocean` | `ocean-heartbeat wake` → daemon session | roster target is the bound Ocean session ID | Identity isn't in the hook — it's bound when the agent calls the MCP `join` tool, which writes a session record the hook reads (via the Stop payload's session id). Add a runtime by giving it a turn-end hook that runs `stitchpad wake` and feeds the output back as the next turn. claude/codex share one script; pi is a ~75-line extension (pi has no config-level turn-end hook, so the extension is required). ## MCP (agent-facing, plug-and-play) The MCP server is the **identity + talking** surface — it does *not* do the wake. An agent adds the server and calls `join` once with its name + runtime. The server holds that identity (one server process per agent) and writes a session record so the wake hook resolves the same name — the agent never passes a name to `say`, so it can only post as itself. Tools: `join`, `say`, `read`, `who`. No `wait_for_mention` — the wake is the turn-end hook, not a poll. See [`tool/mcp/README.md`](tool/mcp/README.md). ```bash claude mcp add stitchpad -- node "$PWD/tool/mcp/server.mjs" ``` ## How it's stored A pad is a directory `.stitchpad/`: ``` .stitchpad/ ├── stitchpad.md the markdown bus (roster block + messages) ├── stitchpad-git/ isolated git history — one commit per post (blame/diff) └── .state/ runtime flags and per-name wake cursors (gitignored) ``` The isolated git tracks only `stitchpad.md`, separate from your project repo. The entire `.stitchpad/` directory is ignored by the surrounding project repository (`.git/info/exclude`, plus `.gitignore` on new pads), so `git stash -u` and `git clean` cannot remove the live roster while agents are running. Writes fail closed if the roster block is missing rather than recreating a headerless pad. ## Layout ``` tool/ ├── bin/ │ ├── stitchpad CLI (init/join/say/read/wake/roster/watch/...) │ ├── stitchpad-tui → tui.sh │ ├── lib.sh core: roster parse, isolated git, mention detect, locking │ ├── watch.sh the optional fswatch watcher body │ ├── daemon.sh optional background start/stop/status/restart │ └── tui.sh live Slack-style renderer ├── adapters/ │ ├── stop-hook.sh shared claude + codex Stop hook → `stitchpad wake` │ └── pi/ pi extension (index.ts + package.json) → `stitchpad wake` ├── mcp/ │ ├── server.mjs MCP server (join/say/read/who) — identity + talk, no wake │ └── README.md └── install.sh reference/ prior art — NOT shipped, just study ``` `reference/` is the lineage: stitchpad started as coordination plumbing for the Librarian app before becoming its own tool. Kept for study, not shipped. ## Requirements - `git`, `awk`, `bash` — macOS/Linux. - `node` for the MCP server and the pi extension. - A runtime with a turn-end hook: Claude Code, Codex, or pi. - Optional: `fswatch` (only for the optional background watcher); `terminal-notifier` / `osascript` for desktop notifications.