A multi-agent orchestration harness for tmux. A pi-based auditor owns the work ledger and verification gates; a Claude Code PM owns the worker fleet; workers run in their official harnesses and are routed by task temperament. Worker completion travels through a private, file-based status ledger rather than status chatter.
Outcome first, intent first. The definition of done lives in a work ledger as observable criteria. A worker brief communicates the intended outcome and contract, not line-by-line implementation instructions. The model owns the path; the ledger owns the destination.
Judgment to models; observation, loops, and gates to code. Agents cannot mark their own criteria as passed or declare the overall task complete. verify executes checks, and the settle gate remains active until every criterion passes and the user receives a QA package. Status-ledger polling is forbidden; the harness injects worker state changes.
| tier | owns |
|---|---|
| auditor | ledger, criteria, verification, escalation, and the user-facing result |
| PM | decomposition, contracts, worker selection, pane lifecycle, and integration |
| workers | execution within a bounded contract |
A PM is not mandatory for a small task. Add the tier when parallel work, repeated experiments, handoffs, shared external resources, or accumulating runtime evidence make direct orchestration unsafe or expensive.
simply supports two routing profiles:
- max (default): Claude Fable for the PM and Claude Opus for general Claude workers.
- low-cost (
--low-cost): Claude Code Router for non-frontend work. Route PM and judgment work to Kimi K3, context/research/exploration to Gemini 3.7 Flash 1M, and implementation contracts to Kimi K2.7 Coding. Frontend visual work remains on Antigravity Gemini 3.7 Flash High.
The two Kimi backends expose 256K contexts. Configure their Claude Code profiles to compact conservatively at 200K; do not advertise them as 1M profiles or add a [1m] suffix to Kimi aliases. Routing mode changes capacity and backend selection, not the ledger, verification, semantic review, or QA standard.
Install the repository, set SIMPLY_HOME to its absolute path, put bin/ on PATH, and run inside tmux:
export SIMPLY_HOME=/path/to/simply
export PATH="$SIMPLY_HOME/bin:$PATH"
simply /path/to/project
simply --low-cost /path/to/project
simply --max-quality /path/to/project
simply --unsafe-workers /path/to/project
simply --destructive-rails /path/to/projectState a goal. The auditor confirms the outcome, writes .simply/LEDGER.md, registers machine-checkable criteria, delegates work, receives status-ledger events, runs verify, and presents a criterion-by-criterion QA package.
All project state is private to the project under .simply/. Runtime directories are created with mode 0700; ledgers, briefs, plans, status files, and node registries use 0600. Existing state is repaired to those modes when opened. Symlinked state roots and sensitive state files are rejected rather than followed.
The default worker mode does not enable Codex danger-full-access, Claude or Antigravity permission bypasses, or pre-approve Claude, Codex, Antigravity, or tmux-bridge trust stores. A first visit may therefore require approval in the worker pane.
Use --unsafe-workers or SIMPLY_UNSAFE_WORKERS=1 only for a run whose unattended permissions and trust changes have been explicitly accepted. This does not change model routing. Auditor project approval (pi --approve) is a separate decision.
The improvement rail can run Git snapshot, acceptance, and rollback operations (git add, commit, reset --hard, and clean -fd). Those operations require the independent --destructive-rails or SIMPLY_DESTRUCTIVE_RAILS=1 opt-in. Enabling unsafe workers never enables destructive rails, and vice versa.
Low-cost mode requires a locally installed Claude Code Router with its hardened lifecycle launcher. Set its location explicitly; a portable XDG-style installation is recommended:
export SIMPLY_ROUTER_HOME="${XDG_DATA_HOME:-$HOME/.local/share}/claude-codex-router"
export ROUTER_SECRET_FILE="$SIMPLY_ROUTER_HOME/.router-secret"
# Optional; defaults are loopback port 4141.
export SIMPLY_ROUTER_URL=http://127.0.0.1:4141The lifecycle is deliberately strict:
- simply validates a path-free loopback HTTP endpoint. Configure it with
SIMPLY_ROUTER_URL, or withROUTER_HOST(127.0.0.1or::1) andROUTER_PORT. If both forms are supplied, they must agree. - It reads only an owner-owned, non-symlink, regular secret file with mode
0600and performs an authenticated/healthrequest. - If authenticated health is unavailable, it runs
${SIMPLY_ROUTER_HOME}/scripts/start-background.sh. The Router launcher alone creates or repairs the secret and owns PID, log, readiness-proof permissions, authenticated readiness, and failed-start cleanup. - simply reloads the secret and requires authenticated health after startup. A PID file alone is never accepted as readiness.
- The secret is passed to health checks through curl stdin configuration, never command arguments. It is then appended to Claude Code's supported
ANTHROPIC_CUSTOM_HEADERSasx-claude-codex-router-secretand inherited by the auditor, PM, and Claude workers.
Existing custom headers are preserved in newline form. A pre-existing Router header is rejected as ambiguous. Never print the secret, copy it into a brief or ledger, include it in a command line, or replace the inherited header environment. The Router package is not bundled here; install and audit it separately before selecting low-cost mode.
Claude Stop hooks and Codex notify hooks append leaf stopped events. A PM stopping at the end of a delegation turn is not completion; only its explicit ready_for_verify event requests auditor verification. Antigravity's internal-tools transport has no equivalent Stop hook: intermediate tool results and an idle process are not completion. The PM treats only Antigravity's terminal final_response as the end of that turn, records the corresponding state transition, and still reserves ready_for_verify for completion of the PM's whole contract.
Worker registration uses both a tmux-bridge stable four-character key and a pane-local UUID spawn token. Native tmux pane IDs can be reused and are never sufficient identity. Registration is lock-protected and atomically replaced; injection, resume, cleanup, and resource release require the recorded stable identity. Legacy entries without both identity fields require manual inspection and replacement.
Prefer resuming a suitable stopped session over spawning a new one so project context survives. Never resume when the recorded pane is still alive. A resumed worker receives the actual assignment immediately; a new worker receives orientation first and the assignment after its first stopped signal. An exclusive external resource may have only one live owner. Transfer or release it before another worker is assigned the same resource.
LEDGER.md- this repository's own work ledgerroster.md- hierarchy, routing, and fleet doctrine injected into the auditorextension/simply.ts- ledger residency, status watch, worker tools, verification, and settle gateshooks/- Claude Stop and Codex notify adaptersskills/simply-pm/- PM fleet and signal protocolpi-skills/improve/- opt-in measurable-improvement railbin/simply- launcherdocs/pi-reference.md- pi harness-engineering referencedocs/improvement-loops.md- improvement-loop design
| tool | role | bundled? |
|---|---|---|
| tmux | pane lifecycle | no |
| pi | auditor harness | no |
| Claude Code | PM and Claude-compatible workers | no |
ccv |
Claude Code wrapper | yes, in bin/ |
ccx |
Codex CLI wrapper | yes, in bin/ |
agy |
optional Antigravity frontend worker | no |
tmux-bridge (smux) |
cross-pane messaging and stable pane keys | no |
simply-pm skill |
PM authority and protocol | yes |
tmux-bridge is provided by ShawnPana's smux project. If it is unavailable, plain tmux can carry messages, but stable identity and the registration protocol must be replaced with an equally strong mechanism rather than silently weakened.
- Set
SIMPLY_HOME; do not edit documentation or skills to embed a machine-specific repository path. - Refer to shipped hooks as
$SIMPLY_HOME/hooks/worker-settings.jsonand$SIMPLY_HOME/hooks/codex-notify.sh. - Configure external binaries and settings through their supported environment variables or XDG configuration roots.
- Link
skills/simply-pminto the Claude Code skills directory used by your installation. - Treat optional orchestration skills and model names as configurable dependencies; verify names against each installed harness instead of guessing.
MIT