Running ten coding agents without freezing your machine
Ten agents can each start a build, a test suite or a headless browser at the same moment. The machine runs out of RAM and everything slows down.
The problem
One agent running cargo test is fine. Ten agents each running a build, a test suite or a Playwright run are not. Each job may need several gigabytes. When free RAM runs out, macOS starts compressing memory and writing it to swap. Your editor lags, and the agents slow down too.
The agents do not know about each other. Each one thinks it has the machine to itself.
What agent-bouncer does
agent-bouncer is a small command I wrote for this. Agents call it in front of a heavy command:
agent-bouncer run --wait -- cargo test
agent-bouncer run --wait -- pnpm playwright test
It lets a job start only when the machine has room for it. Other jobs wait in line, first come, first served. A job that waits is not a failed job. It starts as soon as there is room.
It decides in three steps.
- It predicts what the job will need. A cheap model (Gemini Flash Lite through OpenRouter, about a second per call) reads the command, the folder and the measured peak RAM and cores of the 15 closest past runs. With no key set, it uses past runs alone.
- It checks that the job fits. Free RAM must stay above 3 GB after every running job reaches its peak. The expected cores of all running jobs must fit the machine. The one-minute load must be under 1.5 per core, and CPU must be under 90 percent.
- It runs the job in its own process group, measures the real peaks every 2 seconds, and stops leftover dev servers and headless browsers when the job ends.
It never kills a running job. When the machine is full, it stops letting new jobs in and does nothing else.
A real queue
$ agent-bouncer status
2 running cores 10/18 expected free RAM 9.4 GB swap 3.7 GB CPU 41%
running
4m12s 2.1 GB of ~2.4 GB 3.0 cores cargo test ~/Code/agentview
48s 1.1 GB of ~5.3 GB 7.0 cores pnpm playwright test ~/Code/arca
waiting
1. 0m31s cargo build --release ~/Code/agentview (the running jobs are already expected to use all the CPU cores)
There is no daemon. The processes share a small folder of lock files, so a crashed job cannot leak its place in line.
Seeing the line in agentview
A queue you cannot see is hard to trust. When agent-bouncer is installed, BetterAgentView reads agent-bouncer status --json every couple of seconds and shows a panel above the input. It lists the running and waiting jobs, how long each has been at it, and when the queue should clear. A session whose own run is stuck in line says so on its row, for example #1 in line for lint + typecheck · all slots in use.
BetterAgentView only reads the queue. It never starts, stops or reorders jobs.
Set it up
curl -fsSL https://raw.githubusercontent.com/moritzWa/agent-bouncer/main/install.sh | bash
It works on macOS and Linux. Then tell your agents to put it in front of heavy commands. A line in your AGENTS.md or CLAUDE.md is enough: "Run builds, test suites and browser tests as agent-bouncer run --wait -- <command>."
Run agent-bouncer doctor to test the model and key. If you do not want anything to leave your machine, set AGENT_BOUNCER_MODEL=off. With a key set, each job sends its command line, directory, the package.json script it runs, machine load and a few similar past runs to OpenRouter. agent-bouncer predict --show -- <command> prints exactly what would be sent.
Where it falls short
- Peak RAM is sampled every 2 seconds, so it misses short spikes.
- It does not see memory used outside the job's process group, such as Docker or virtual machines.
- Early predictions are only as good as the history. Tools that skip the bouncer still load the machine.
- It only helps with jobs that go through it. The agents themselves, and the model calls they make, are not limited.
How other tools handle load
Claude Code's agent view stops idle sessions when memory is low. The Codex app caps spawned-agent threads per session. Xum, Coder's agent app, sets a CPU and memory limit for all local agent commands through Linux cgroups, which does not apply on macOS. cmux and Paradev show CPU and memory per workspace. I compared them in the full comparison.
agent-bouncer is MIT licensed. The how-it-works page has the diagrams.