Skip to content

Thread pool ​

Four agents each start a build, and the laptop stops answering. The pool is the fix: every heavy command, from every session, every project and every Claude Code config on the machine, asks one shared pool for threads first. When the pool has them, the command starts. When it has not, the command waits in a queue, in order, and starts the moment threads are free. The machine stays usable and nothing is lost, because a waiting command is a patient one.

The reference text (every flag, every rule of admission) is in Action states. This page is the picture.

Watch it ​

Below is the pool of a real window of hours, recorded by the pool's own log while the open-source anyparse project ran several pipelines at once. The strip is the whole window: threads held against the budget (the dashed line), and the amber band along the top is the number of commands that were waiting. The panel under it is the Pool tab of the plan pane, drawn by the mod's own code at the cursor. Press play, or drag the slider.

Loading the replay…

The log samples a pool once a minute while it has a lease or a waiter, and not at all while it is empty, so a flat stretch with nothing in it is an idle pool. A sample lists no holders: the log names a lease only on an overrun:, underuse: or backfill: line, and a name appears on the sample after that line, only when it is a slice or session of the replayed project. Every other lease is one row, "leases the log does not name (this project or another)", because a sample cannot say whose threads they are. The log keeps no priority and no age for a lease, so the rows here show none; the live tab shows both.

How it works ​

commands asktest suite · 6build · 2-8corpus · 4land · lockthe pool · budget 14lease · 6 threadslease · 4 threads2freeheld 12 of 14 threadsone holder per lockwaiting, in orderhigh · 4-8 threadsnormal · 2 threadslow · 6 threadsthe head may be passed by ashort job that ends first

Lease. A lease is a claim on some threads for as long as a command runs. The command is told how many it got (WF_THREADS) and is expected to use that many: make -j"$WF_THREADS". A lease is released when the command exits, or when its process is found dead.

Budget. The pool has a number of threads to give out, by default the performance cores minus two. Granted leases never add up to more than the budget, and beside a running lease, load that did not come through the pool (a video call, a browser) counts against the budget too, so the pool backs off when the machine is busy with something else.

Priority. A session has a level: low, normal (the default), high or urgent, set when it starts and inherited by its children. A project can set one level for all its tasks. The queue is ordered by priority, then by arrival. A waiter that has queued past starve_after (15 minutes by default) is marked STARVED everywhere it can be seen, so a stuck queue is never silent.

Locks. Some work is one at a time whatever the threads: a dev server on a fixed port, a simulator, the step that lands a change. A lease can ask for a named lock, and the pool grants threads and locks together or neither, so two tasks that want the same pair can never deadlock each other.

Backfill. When the first in line needs more threads than are free, the pool does not leave them idle. A later, smaller job starts ahead of it only if it is expected to finish before the head's threads would be free, so it can never delay the head. The estimates come from the command's own past runs. A job that runs past twice its estimate switches backfill off for that head.

Overrun. A lease counts threads, but a command can run more processes than that. The pool reads the process table and flags a lease whose tree runs well above its threads as OVERRUN (OVERRUN ~12 in the tab), and counts what the tree runs as the lease's own load, never as foreign load.

Underuse. The other way round is just as visible: a lease asks for threads the caller says it will use. A lease whose tree runs at least half its threads (and at least one cpu) below them for 30 seconds is logged as UNDERUSE in pool.log and marked (UNDERUSE) in wf-run --status, pool_status and the dashboard's Pool tab (an UNDERUSE ~N plaque). wf-run --status and pool_status also show what every measured lease runs against what it holds (holds 4 threads, runs ~3); the dashboard shows runs only in the OVERRUN and UNDERUSE plaques. The pool only reports it: the size of a lease is its caller's declaration, and the caller fixes it. wf-run --usage adds up the leases that ended, per label, so a project can right-size its own callers.

Using it ​

A workflow's exec state asks with resource: { threads: 6, priority: 0, wait_timeout: 900 } and the engine does the rest. Anywhere else, wf-run puts any command through the pool:

bash
wf-run --threads 2-8 --wait-full 60 --lock land --label "build" -- make -j"$WF_THREADS"
wf-run --status    # the pool: budget, load, every lease and waiter, in admission order
wf-run --usage --since 24h    # per label: leases, threads held and used, idle and overrun thread-minutes

Agents' own heavy Bash commands go through it too, without asking: the pool gate hook rewrites the commands a project marks heavy. See Pool gate.

The pool lives in ~/.claude/workflow-pool (WF_POOL_DIR), one directory for the machine. Its optional config.yaml takes three keys:

KeyMeaningDefault
budgetthreads to give outperformance cores minus 2
load_thresholdload below this is noise, not external work2
starve_afterseconds before a waiter is marked STARVED900

To look at it: the Pool tab of the plan pane (key 4) and the dashboard's Pool tab show the same rows as the panel above, live; wf-run --status and the pool_status tool print them as text; pool.log in the pool directory keeps the minute-by-minute samples this page replays.