Ray's Knowledge Base

Run many coding agents on one Rust repository without overloading the machine

RecipeVerified 28 Sep 2026Holds anywhere
Recipe. When to use it, the steps, and what showed that they work.

When to use#

You fan out several coding agents (Claude Code Agent with worktree isolation, or similar) on one Rust repository. Each worktree has its own target/ folder, so each agent runs its own full cargo build and cargo test. Agents also start their own helper agents and forks unless told not to. In one session 6 agents grew to 19, with about 40 cargo/rustc/test processes, 18 leftover git daemon test servers and several test gpg-agents, and the user's machine slowed down badly.

Steps#

  1. Put a turn lock around cargo. On macOS /usr/bin/lockf exists and flock does not. Write a wrapper in a scratch folder:

    #!/bin/sh
# One cargo at a time across all agents: wait for the shared lock, then run.
exec /usr/bin/lockf -k "$SCRATCH/cargo.lock" cargo "$@"

  2. In every agent prompt, write these rules:

    • Run every cargo build, test and clippy through the wrapper. cargo fmt may run directly.
    • Do not start helper agents or forks.
    • Run targeted tests (--test <file>, a name filter) while iterating; run the full suite only before a commit.

  3. Send the rules to agents that are already running, including their helpers. A message to an agent that already finished wakes it up again; it only acknowledges, but expect the extra notices.

  4. To stop the load at once, kill only processes that belong to the repository's worktrees and tests, never the user's own daemons:

    pkill -f "<repo>/.claude/worktrees/.*/target/"
pkill -x cargo; pkill -x rustc
pkill -f "lockf -k <scratch>/cargo.lock"
pkill -f "git-daemon.*<test temp folder pattern>"
pkill -f "homedir /var/folders/.*/T/<test gpg home pattern>"

    Check the process list first; agents that are still alive start new builds right away, and with the lock only one runs.

  5. Keep fan-out small: about 6 main agents was acceptable once the lock was in place.

Evidence#

rgit, 2026-09-27/28: after the lock and rules were sent, ps showed exactly one lockf ... cargo build -q with one rustc, and the other agents waited for their turn. Before that, 19 agents were listed by ListAgents and the user reported "it slow down a lot".