How agent-bouncer works

Stop your computer from freezing when many agents run builds at once. agent-bouncer lets in only the jobs the machine has room for. The rest wait in line.

1The problem and the idea

Agents send jobs to agent-bouncer, which predicts what each needs, checks the machine has room, then runs or queues it

No daemon, only file locks. Agents call agent-bouncer run -- <command> instead of running the command directly.

2The life of one job

1 Ask an agent runs run -- cargo test command + folder 2 Predict peak RAM and cores it will need (next section) 3 Line up take a numbered place; only the head is checked 4 Check room RAM, cores, load, CPU, ramp-up (section 4) 5 Run own process group; RAM and CPU sampled every 2 s 6 Finish log the real peaks, stop leftovers (dev servers, browsers) does not fit yet: stay at the head and re-check twice a second the real peaks go into the history that the next prediction reads events.jsonl: every enqueue, admit, finish with wait time, peak RAM, peak cores, exit code

3How it predicts what a job needs

The same command can use 400 MB in one folder and 5 GB in another, so a fixed cost table fails. Instead a cheap model (Gemini Flash Lite, about a second, a fraction of a cent) reads measured evidence and answers with the job's peak RAM and peak cores. Because that is nearly free, it is asked about every new kind of job.

new jobcommand + folder new measurement since? model down or no key? ask the modelabout 1 second use the cachenone yet: reuse (24 h max) fall backpast runs alone sanity limitsclamp to what is possible history floorsame folder: 75th pct predictionsaved to cache What the model sees - command, folder, script body - repo size, machine, load - 15 closest past runs: peak RAM, peak cores, seconds - running jobs, agent's guess Fallback numbers seen this command before: 90th percentile of its peaks never seen it: 1.5 GB and 2 cores no key: same, nothing is sent startyesnoyesno

Cache: an answer is reused until a job of that kind finishes and gives a new measurement, so a burst of the same command costs one call. Floor: past runs of the same command in the same folder set a minimum; elsewhere only the lowest quarter does, so the model can be right that this run is small. A failed call marks the model down for a minute. The key goes to curl on stdin, not the process list.

What it is shown, in order of trust. See your own with agent-bouncer predict --show -- <command>.

ClueWhy the model gets it
similar_past_runsMeasured peak RAM, peak cores and seconds of the 15 closest runs, with folder, exit code and age. The strongest evidence.
script_body, script_fileWhat bun run ship expands to in package.json, and the first lines of a wrapper script it runs (secret-looking lines removed), so a new script is judged by what it does.
git_tracked_filesA 24k-file repo means bigger type-checks and bundles than a 200-file one.
machine, running_nowCores, free RAM, load, and what is already running and still growing.
requester_estimateOptional: the agent's own guess (--expect-ram 4gb --expect-secs 3m). One clue, below measurements.

4How it decides: does it fit?

The head of the line is re-checked every half second. All must pass:

RAM headroomfree RAM after everyjob reaches its peakstays above 3 GB Core budgetexpected cores of allrunning jobs plus thisone fit the machine Load guard1-minute load under1.5 per core, if othersare already running Ramp-up pause2 s after the last bigstart (jobs under300 MB skip it) CPU not saturatedmeasured now, over0.3 s, below 90 percent

The RAM check, with numbers

A running job often has not reached its peak yet. One at 50 MB that peaks at 5 GB keeps 5 GB reserved.

Fits: 16 GB free 5.9 GB reserved: running jobs still growing 5.0 GB: the new job's peak 5.1 GB left 3 GB must stay free: OK Waits: 9 GB free 5.9 GB reserved new job 5.0 GB: 1.9 GB short 9 - 5.9 - 5.0 is below zero, far under the 3 GB floor, so it stays in line until a running job ends. With nothing running, only the floor applies, so a big job can never wait forever.

"Free RAM" counts only free, purgeable and file-cache memory. Inactive app memory does not count as room, because reusing it means compressing or swapping it, which is what makes a Mac feel laggy.

Cores work the same way: each running job holds the cores it is expected to use, and a job that would push the total past the machine's core count waits.

5Where it is weak

There is no server: processes share a small folder of lock files, so a crashed job never leaks its place. Peak RAM is sampled every 2 seconds, so it misses short spikes and anything outside the job's process group (Docker, VMs). Peak cores need about 4 seconds of runtime. Early predictions are only as good as the history, and tools that skip the bouncer still load the machine. agentview shows the queue above its input by reading agent-bouncer status --json, read-only.

Settings and the privacy note are in the README.