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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
docs: clarify CLI contribution guidelines and add technical requirements for new multiplexer implementations
0xken157bae05f6d697
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 toend 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 fromoutside. Silence is not an option; that rule is the reason the suite is trustworthy.-## Code+## Provider code (`provider/`)```bashcd reference-provider && npm install && npm run typecheck && npm test