Skip to content

Routing work: which agent, which model, how many at once

Who is this for? Someone orchestrating agents on a repository the checks already guard — deciding which model takes which work, when to fan out, and when to stop for review. When should I read it? When a single agent is no longer fast enough, or when an expensive model is doing cheap work. The collision rules for several agents live in More than one agent; when a rule is in the way, Adapting rules; running lanes in herdr panes and agent teams inside a lane, Agent teams and herdr.


The checks decide when work is finished. They say nothing about how fast it gets there, and a harness that is slow to work inside is a harness people route around. This page is the other half: how to spend models and parallelism so the checks stay green and the work moves.

Three roles

harnessimo init writes three agent definitions into .claude/agents/ — starting points to edit, not rules to obey. Each rule in them carries its why, so an agent can tell when one has stopped applying.

Role Model Gets Never
architect the strongest (opus) specs, ADRs, gate verdicts, cold review of risky diffs writes production code
implementer the workhorse (sonnet) one lane's code, task by task, checks quoted edits specs, spawns agents
scout the cheapest (haiku) read-only lookups: greps, brief, versions, logs writes anything

The rule underneath: pay for judgement where a mistake is expensive and invisible; pay for throughput everywhere else. A wrong lock order, a rounding rule, an idempotency key or a data migration is invisible in a green test run and expensive in production — that diff goes to the architect, with a fresh context, because the author's context is the one that hid the bug. A rename, a test, a doc fix is throughput.

Reasoning effort follows the same line: low for lookups and mechanical edits whose result checks itself, high for the one piece that needs more thought than the work around it.

The role's model reaches a pane agent as a launch flag

The model in a role file is read by Claude Code for a subagent. A lane agent that harnessimo herd up starts in a herdr pane is a top-level session, which never reads it, so up reads the role's file itself and starts the agent with --model <m> --effort <e> (implementer → sonnet, architect → opus, scout → haiku). Sonnet agents run at high effort unless the role's effort: or herd.roles says otherwise. Details, precedence and the fallbacks: Agent teams and herdr.

Never change a running agent's model with /model or /effort. Both save the choice as the user's global default in ~/.claude/settings.json, which changes every other session they have open. Stop the agent and start it with the flags instead.

The coordinator does the routine herdr work itself — opening panes, starting agents, sending prompts that are self-contained and use absolute paths, since a side worktree may not contain the coordination files. The owner is never handed a manual step for it. A tab holds at most four panes, the coordinator's included; herd up opens a new tab for the rest.

Fan out when streams are independent

Two tasks are independent when neither reads what the other writes. Those run in parallel, each in its own checkout:

harnessimo worktree add search     # ../<repo>-search on branch wt-search, install run
harnessimo worktree add billing
# … one implementer per worktree …
harnessimo worktree merge search   # --no-ff into the current branch
harnessimo worktree remove search  # refuses unmerged or uncommitted work

A fresh worktree runs the project's install step first (worktree.install, or the install command in coldStart.commands), because its first commit would otherwise fail the pre-commit hook far from the cause. Each lane still declares ## Owns, so two streams that turned out not to be independent fail harnessimo tracks instead of a merge.

The main checkout owns the shared state — PROGRESS.md, TRACKS.md, the handoffs. Side branches carry code and their own lane's files, which keeps the merges boring.

Chain tasks, batch reviews

  • An implementer may chain several tasks of one stream: commit each, go straight to the next, report once at the end. A stop after every task turns parallel streams back into a queue with extra steps.
  • [review] tasks get one batched review per stream instead of a stop after each. The gate is still the review — nothing merges on an unreviewed [review] task — but one cold read of a coherent diff finds more than five reads of fragments.

The orchestrator never idles

The session that hands out work does not wait for it. When an agent reports, the orchestrator in the same turn merges what is green, launches the next stream or the batched review, and updates the shared state. An idle orchestrator is the bottleneck a parallel run was meant to remove.

Speed comes from parallelism, not shortcuts

The checks stay. Speed comes from not running them more often than they can change:

  • the inner loop runs only what the edit touched; the full gate runs once per task;
  • a gate's output is captured whole with its exit code (cmd > log 2>&1; echo "exit=$?") — never piped through tail, whose exit code replaces the gate's;
  • tests bind port 0 and poll for state, the two usual sources of flakes in parallel runs;
  • background processes are stopped before reporting.

When a rule of the process — not a check — is what slows the work down, the answer is to adapt the process inside the bounds, never to bypass the check. How: Adapting rules.