Agent Fleet Ops Kit — Run Multiple Coding Agents Without Collisions

Run four coding agents on one machine without them colliding.

If you run one agent, you do not need this. If you run three or four in parallel terminals — Claude Code, Codex, Aider — you already know the failure modes:

• Two sessions editing the same checkout, until the evidence starts contradicting itself: tests failing against code another session already fixed, a branch changing underneath you mid-task.

• A dev server nobody owns. An agent cannot reach :3000, starts another one on :3001, and now the app it is testing is not the app it is editing.

• MCP servers leaked from crashed sessions, reparented to init, quietly holding RAM and ports for weeks until the box is saturated and every tool call times out.

• An agent confidently reporting a service as "running" because a project doc said so months ago. Model memory is a cache with no invalidation.

This is the tooling and the operating procedures for that problem.

Three command-line tools

Zero dependencies — Node 18+ and bash, both of which you already have. No npm install, no daemons, nothing running in the background.

• fleet-doctor — diagnoses the fleet: worktree collisions, orphaned sessions, MCP servers with no live parent, dev-server sprawl, load and disk pressure, stale lane locks. Collapses process trees so one agent forking four children is reported as one session, not four. Human-readable or --json, and exits 0/1/2 so you can gate a script on it.

• fleet-lane — one git worktree per agent, with a liveness-checked lock so two sessions cannot claim the same lane. Claim, list, which, release, gc. Reclaims lanes whose holder died, because a lock nobody can clean up becomes a lock everybody ignores.

• fleet-reap — safely retires orphaned agent sessions and leaked MCP servers. Dry-run by default. It refuses to target anything attached to a terminal, anything with a live parent, and its own ancestors. SIGTERM first; only --force escalates. An allowlist protects brokers you daemonize on purpose.

Two Claude Code hooks

• SessionStart ground-truth — every session opens with a live snapshot of sessions, ports, MCP servers, load and disk, plus whatever fleet-doctor currently flags. The OS becomes the default answer to "what is running?", instead of whatever your docs claimed months ago.

• PreToolUse port guard — denies a command that would start a server on a port already in LISTEN state, and names the process holding it. Deliberately biased toward precision: explicit ports only, never guessed defaults, inspection commands never blocked.

Both hooks always exit 0. A hook that can break session start is a hook you disable within a week.

The operating procedures

SOP.md — ten rules covering ground truth, lanes, port ownership, reaping orphans, self-healing daemons that undo your cleanup, verifying artifacts instead of success messages, and handoff discipline. Each one is a mechanism, not advice. Plus a table of anti-patterns that look like good operations and are not.

Templates — session handoff and collision postmortem.

Works with the free tool

Pairs with whats-running-mcp — free, MIT, github.com/stcmain/whats-running-mcp — which exposes live machine state to your agent as MCP tools. That server answers what is running. This kit answers what is wrong with it, and gives you the procedures to keep it clean.

Neither requires the other. The free tool stays free, MIT, and complete — nothing has been held back from it to build this.

Chasing "done" claims that were never checked? The companion is the Agent Reliability Kit ($29). Both kits and all three free MIT servers are laid out at shifttheculture.media/agent-tools.

Details

• macOS first (ps/lsof/df). Linux works for the process, port, lane and hook features.

• Requires Node 18+, bash, and git 2.17+ for worktrees.

• Read-only by default. fleet-reap is the only tool that signals a process, and never without --kill.

• Delivered as a zip: 3 CLI tools, 2 hooks, SOP, 2 templates, install docs, license.

• Single-operator commercial license — use it on every machine you personally operate, modify it freely, keep everything you build with it.

Instant download (ZIP). Shift The Culture.