System 4 of 4
Multi-agent orchestration platform and desktop app
Runs isolated Claude Code agents in parallel, one git worktree per task, from a desktop grid. A guardian hook intercepts every shell command against a fail-closed policy the agents cannot modify, a kill switch locks every domain to observe-only, and autonomy levels expand only after logged evidence.
In daily use, packaged macOS build
- Role
- Sole architect and engineer
- Stack
- Python supervisor, tmux, git worktrees; Electron, xterm.js, node-pty desktop app
- Size
- ~6,400 lines Python, ~1,600 lines Electron, 28 automated tests (pytest)
- Autonomy model
- Four levels: observe, suggest, act-and-report, autonomous
- Safety provenance
- Three production incidents converted into permanent controls
Problem
Running several coding agents at once fails in predictable ways. They collide in the same working tree. They run a destructive command because nothing stopped them. They are trusted up front instead of after a track record. I wanted parallelism with real isolation, a policy layer the agents cannot edit, records I could audit later, and an autonomy model with evidence behind every step up. The safety layer was in the repo on day one, not retrofitted.
Orchestration
- File-driven dispatchDispatch writes a task file. A supervisor watches for it. No sockets, no RPC, nothing that cannot be inspected with ls and cat.
- One git worktree per taskEach agent gets its own worktree, so parallel agents never share a working tree and cannot overwrite each other.
- Spawn and turn detectionThe supervisor spawns the agent inside tmux and detects turn completion by output activity, distinguishing in-progress from waiting-for-human.
- Harvest to branchFinished work is harvested onto a reviewable branch. Nothing is merged silently and nothing is silently destroyed.
- Durable job recordsEvery delegated job has a durable record with a full event timeline, so any outcome can be traced back to who asked for what and when.
Lane topology enforces boundaries: the coordinator never edits a lane's repository directly, and each lane is isolated from the others.
Desktop app
An Electron application presenting a resizable grid of live agents, each in its own worktree-backed terminal on the same terminal stack VS Code uses (xterm.js and node-pty). Lane sidebar, one-click agent launch into an auto-created worktree, auto-tiling, live status indicators, a finish action that keeps the branch or merges it, a kill action, and an integrated file browser and editor. Packaged as a macOS build.
Safety layer
- Guardian hook. A PreToolUse interceptor on every shell command an agent runs. It blocks forbidden patterns (raw calls to high-consequence APIs, credential reads, force pushes, recursive deletes, destructive SQL) under a domain-aware fail-closed policy. It protects itself: agents cannot modify the hook, its configuration, or the autonomy rules without explicit human approval.
- Integration gates. The only sanctioned paths to high-consequence third-party APIs such as marketing automation and helpdesk systems. Raw access is blocked at the hook layer.
- Kill switch. One command locks every domain to observe-only.
- Preflight validator. Checks paths, state freshness, autonomy consistency, integrations, and approaching deadlines before any significant work begins.
- Context handoff generator. Produces per-task hard constraints and an orientation document for each delegated job, carrying relevant past incidents forward as warnings.
- Incident learning loop. Structured records with root cause, impact, what would have prevented it, and mitigations. Each record feeds back into hooks, gates, and handoffs. Three production incidents have been converted into permanent, enforced controls this way.
Evidence-gated autonomy
Every agent action is logged with its autonomy level and reversibility. Graduation between levels requires evidence tracked in correction and action logs, for example ten or more accepted suggestions, zero corrections over 30 days, and confirmed reversibility.
- observeRead and report. No changes.
- suggestPropose changes for a human to apply. Suggestions and corrections are logged.
- act-and-reportApply reversible changes and report each one. Earned by an accepted-suggestion record with no corrections.
- autonomousAct without a per-action report, inside the guardian's policy, for a domain with a proven record. Revocable by the kill switch at any time.
Numbers
| Platform code | ~6,400 lines Python |
|---|---|
| Desktop app | ~1,600 lines Electron |
| Automated tests on the agent lifecycle | 28 |
| Autonomy levels | 4 |
| Production incidents converted into controls | 3 |
What it is for
This is the platform I build the other systems on this site with. Its output is not a demo. It is the code, tests, and reports behind the ads engine, the sales engine, and the attribution platform.