Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

docs: clarify CLI contribution guidelines and add technical requirements for new multiplexer implementations

0xken157bae05f6d697
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2f9eb7e6a..2b59a7d24 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,13 +2,14 @@
Two kinds of contribution land here, and they have different bars.
-**Adding an agent framework** is the code path, and it is welcome — see
-[`cli/src/engines/README.md`](cli/src/engines/README.md) for the whole job in dependency order. Open
-an issue first with a recorded session from the real binary; that recording decides most of the
-design, and it is the difference between an engine that works and one that fails silently.
+**The CLI** is the code path — a new agent framework, or a second terminal multiplexer — and it is
+welcome. What to run and what the bar is: [The CLI](#the-cli-cli--engines-and-multiplexers) below.
+Open an issue first; for an engine, bring a recorded session from the real binary, because that
+recording decides most of the design and is the difference between an engine that works and one that
+fails silently.
-**Everything about the provider spec** is below, where the most useful contributions are usually not
-code at all.
+**Everything about the provider spec** is after that, where the most useful contributions are usually
+not code at all.
## Conventions across this repository
@@ -19,6 +20,60 @@ code at all.
- **Reference implementations carry no runtime dependencies.** You should be able to read one end to
end and know what your own implementation has to do, without installing anything to understand it.
+## The CLI (`cli/`) — engines and multiplexers
+
+```bash
+cd cli && npm install && npm run typecheck && npm test
+```
+
+That is the bar for every pull request that touches `cli/`. Two further suites exist and are
+**opt-in**, because they need software the machine may not have — they skip themselves rather than
+fail, which is also why forgetting them is easy:
+
+```bash
+npm run test:tmux-real # RUN_REAL_TMUX_DISCOVERY=1 — drives a real tmux server
+npm run test:cursor-e2e # RUN_CURSOR_E2E=1 — needs a real cursor-agent CLI
+```
+
+If your change touches how agents are discovered or driven, run `test:tmux-real` and say in the pull
+request that you did. It is the one suite that can tell you whether you broke everybody else's setup.
+
+### Adding an engine
+
+[`cli/src/engines/README.md`](cli/src/engines/README.md) is the whole job in dependency order. The
+rule that matters more than the rest: **every tool name, field name and event name must be read off a
+real recorded session from the real binary.** Names inferred by analogy from another engine have
+failed silently three times — an empty checklist, a missing sub-agent row, a question card rendered
+into the tool feed — and each one passed its unit tests first.
+
+### Adding a multiplexer
+
+Harness drives agents inside tmux today. A second multiplexer is welcome, on one condition: it is
+**added alongside tmux, not swapped in for it.** Every user's `registry.json` keys its agents by tmux
+pane id, so replacing the multiplexer orphans every running agent on upgrade. tmux stays the default,
+yours becomes a second implementation behind the same interface, and the one after that becomes a
+third instead of a third rewrite.
+
+Three things decide how much work this is, and the first one is not in this repository at all:
+
+1. **Can a process running inside a pane tell which pane it is in?** tmux exports `$TMUX_PANE`, and
+ every engine's discovery hangs off it: the shell hooks in `cli/hook/notify.mjs` and the in-process
+ plugins and extensions generated in `cli/src/lib/hooks.ts` all read it, and stay deliberately inert
+ without it. If your multiplexer exports no per-pane identifier into the child environment, no
+ abstraction on our side can rescue discovery. **Check this before writing anything else.**
+2. **Pane ids are validated.** `PANE_RE` in `cli/src/lib/registry.ts` accepts tmux's `%N` and nothing
+ else. It has to widen without letting two multiplexers' ids ever collide.
+3. **The recap workers scrub the pane variable.** `cli/src/lib/oneshot.ts` deletes it before spawning
+ an ephemeral summary run, so that run cannot register itself as an agent. Miss the equivalent for
+ yours and every recap spawns a phantom agent — silent, and thoroughly unpleasant to trace.
+
+The command surface itself is small: list panes with their pid and working directory, send keys,
+capture the pane, display a message, create and kill sessions. Note that reading the conversation
+does **not** go through the multiplexer — each engine tails its own store on disk — so the scope is
+narrower than it first looks. What decides the difficulty is how well your multiplexer answers "read
+this pane" and "send keys to this pane", because that is what the question dialogs and the model
+pickers are driven with.
+
## Found a gap in the spec?
Say so. The profile is written against one product's needs, and the first partners to implement it
@@ -45,7 +100,7 @@ Every normative statement gets a stable `HP-xxx` id, and a new one needs a match
`reference-provider/src/conformance.ts` — or an explicit SKIP saying why it cannot be verified from
outside. Silence is not an option; that rule is the reason the suite is trustworthy.
-## Code
+## Provider code (`provider/`)
```bash
cd reference-provider && npm install && npm run typecheck && npm test