Architecture
Multi-agent coordination
How OperationKit distributes work across parallel Claude sessions — and the constraints that keep those sessions from interfering with each other.
Delegator / strategy pattern
OperationKit coordinates agents through a pattern that will be recognizable to engineers who have worked with the Strategy design pattern or with OS process supervision: a persistent top-level session (the delegator) holds strategy while short-lived worker sessions hold execution. The delegator never writes code itself; workers never decide what to build next.
The delegator is not a framework or a message bus. It is a Claude session reading SQLite rows and issuing shell commands. Its loop is simple:
loop:
children = SELECT * FROM objectives WHERE parent_id = :me AND status = 'complete'
for child in children:
artifact = read(child.objective_memory_dir + '/ARTIFACT.md')
decide:
- spawn next dependent worker
- mark milestone done
- escalate to human
wait for [child-complete] eventWorkers are tmux sessions. Each is a Claude Code process started by the Command Center's session manager, given a spawn prompt that identifies the objective, the parent, and the acceptance criteria. The worker runs phases 4–6 of the pipeline (Execute → Verify → Deliver) and exits. Phases 1–3 are already resolved in the spawn prompt, so the worker never re-discovers or re-plans.
The delegator re-wakes on a [child-complete] event — a webhook posted by the session manager when a worker's objective transitions to complete or blocked. It reads the child's ARTIFACT.md (the deliverable record, not the scratch notes) and decides the next step. This is entirely synchronous from the delegator's perspective: it sleeps between events, reads one artifact, and either continues or escalates.
A worker must not build objective Y's feature inside objective X's thread. This is the multi-agent analog of the single-responsibility principle. A worker that discovers an adjacent improvement should write it to its NOTES.md and surface it in ARTIFACT.md — the delegator then decides whether to spawn a new objective or defer. Scope bleed is the most common reason a worker's PR fails code review: the reviewer finds changes that were not in the acceptance criteria.
This pattern is independently described in multi-agent research literature. Wu et al. (2023) in AutoGen model it as a GroupChat with a manager agent that routes turns among specialists — the key insight being that a coordinator who only routes is more reliable than one that also executes, because its state is small and its decisions are auditable. Hong et al. (2023) in MetaGPT go further, encoding the coordinator's decisions as structured role assignments with explicit message routing graphs, preventing the ad-hoc tool-call chains that cause cascading errors in naive multi-agent systems.
Worktree isolation and sibling read edges
When two workers modify the same repository concurrently, the naive approach — clone, branch, and merge — produces conflicts that neither worker can resolve because each lacks context about the other's changes. OperationKit avoids this by giving each worker a dedicated git worktree: a lightweight checkout of a unique branch, sharing the object store but not the working tree.
# Session manager creates an isolated branch per worker
git worktree add /tmp/cc-wt-<objective-id> -b obj/<objective-id>
# Worker operates entirely inside its worktree
cd /tmp/cc-wt-<objective-id>
# ... builds, tests, commits ...
# On completion, opens PR from obj/<objective-id> → mainThis means two workers building features in the same repository never touch each other's working trees. A git clean in one worktree cannot delete untracked files in another. A failing build in one worktree does not affect the other's .next cache. The isolation is enforced by the filesystem, not by convention.
Sibling read edges
Workers are not entirely isolated from each other — they sometimes need to know what a sibling delivered before they can proceed. OperationKit exposes a narrow, explicit read API for this: the /siblings endpoint, which returns a sibling objective's allowlisted fields only.
| Field | Accessible to siblings |
|---|---|
id |
Yes — for stable reference |
title |
Yes — to identify what was built |
status |
Yes — to gate on complete before reading artifacts |
ai_review_verdict |
Yes — to decide whether to depend on the sibling's output |
last_session_summary |
Yes — high-level summary only |
updated_at |
Yes — for freshness checks |
| Brief / spawn prompt | No — contains context that would bias the worker |
| Session logs / scratch notes | No — internal working state, not a deliverable |
The restriction on brief and session logs is deliberate. A worker that reads another worker's scratch notes may anchor on intermediate conclusions that the other worker later discarded. The allowlist forces workers to reason from outcomes (what was delivered, what status it reached) rather than from process (what the sibling was thinking while it worked).
The ARTIFACT.md file in a completed worker's objective-memory directory is the one exception: another session may read it directly if the delegator explicitly passes the path. But this must be delegator-mediated — workers do not browse each other's memory directories unilaterally.
Autonomous reviewer as independent quality agent
After every working session completes, OperationKit spawns an autonomous reviewer — a separate Claude session whose only job is to grade the working session's output against the acceptance criteria. This is not self-evaluation. The reviewer has a different session context, a different system prompt, and no access to the working session's scratch notes.
The independence property matters for a specific reason: a model that evaluates its own output is susceptible to the same reasoning patterns that produced the error. If a working session convinced itself that a particular edge case was out of scope, it will likely reach the same conclusion when reviewing its own work. An independent session — one that never saw that rationalization — is more likely to catch it.
When a reviewer can access the working session's internal deliberation, it tends to validate the working session's conclusions rather than challenge them. This is the multi-agent analog of confirmation bias. OperationKit enforces independence by design: the reviewer's spawn prompt contains only the objective brief and the acceptance criteria — never NOTES.md.
The reviewer issues a binary verdict: pass or fail. On fail, the objective reverts to working and the reviewer's findings are injected into the next session's context automatically. The working session doesn't need to remember its failure — the harness guarantees the failure is visible.
This loop is a structural implementation of what Snell et al. (2024) call test-time compute scaling through verification: rather than spending more compute on a single long chain-of-thought, you spend it on multiple independent attempts and a judge. Their empirical result is that verifier-gated multi-attempt generation consistently outperforms single-attempt generation, especially on tasks with clear right/wrong criteria. OperationKit's reviewer loop is this pattern applied to software delivery: the "verifier" is an independent agent session, and the "attempts" are successive working sessions.
Qian et al. (2023) in ChatDev demonstrate the same principle in software engineering specifically: a multi-role pipeline where a "reviewer" role challenges a "programmer" role's output catches significantly more defects than single-agent generation, because the roles create adversarial pressure that a single agent lacks against its own output.
Double-spawn failure modes and mitigations
Multi-agent systems introduce a class of failure that single-agent systems never encounter: the same objective being worked by two agents simultaneously. In OperationKit, this happens when the delegator spawns a worker, the event delivery is delayed or duplicated, and a second worker is spawned before the first has registered its presence. The result is two agents writing to the same branch — or to two branches that both create the same new file.
Both workers pick up the objective, both open PRs. One merges cleanly; the other now conflicts against a main that already contains its changes. The second merge either double-applies logic or silently reverts the first worker's fixes.
?parent_id= before spawningBefore spawning a worker for objective X, the delegator queries GET /objectives?parent_id=<X>&status=working. If a worker is already in flight, it waits for completion rather than spawning a duplicate.
Worker A and Worker B both create src/components/Modal.tsx independently. Neither conflicts with the other at merge time if they write to the file in sequence — but the result is a file that concatenates both workers' implementations, with duplicate component definitions that break the TypeScript compiler only at build time, not at type-check time.
git log before creating new filesBefore creating any new file, a worker runs git log --all -- <path>. If the path exists in any branch tracked by the remote, the worker reads it instead of creating it, and raises a scope conflict if the contents are incompatible.
Both workers check out obj/<X> and begin committing. Each git push from Worker A forces Worker B to rebase, potentially losing changes. In a non-interactive session, the rebase may auto-resolve in ways that silently drop commits.
A worker that detects a sibling's commits on its branch runs git log origin/obj/<X>..HEAD. If the remote is ahead, it pulls and reconciles rather than force-pushing. If the sibling's work already meets the acceptance criteria, it stops and reports — it does not re-execute work that is already done.
The double-spawn check must happen at spawn time, not at session start. By the time a worker's session starts, it may already be too late to detect the collision — both workers will be past the point of early exit.
Minsky (1986) in The Society of Mind observed that intelligence built from many specialized limited agents requires an arbitration mechanism: agents that operate on overlapping territory without coordination produce contradictions, not solutions. The failure modes above are exactly Minsky's prediction applied to LLM agents: two agents that each believe they are the sole author of a shared artifact will produce an incoherent result. The mitigations are the arbitration mechanism.
Account rotation for concurrency
Claude Code imposes a per-account session limit. Running five workers in parallel under a single account will exhaust that limit and queue the fifth worker until an earlier one exits. For workloads that benefit from genuine parallelism — ten feature branches in flight simultaneously, for example — this is a binding constraint.
OperationKit addresses it through account rotation: a pool of dedicated agent accounts (ccuser-0 through ccuser-4), each allocated up to five concurrent sessions, giving a system-wide ceiling of twenty-five concurrent agent sessions.
The session manager allocates accounts using a least-loaded strategy: before spawning a new worker, it queries the current session count per account and assigns the worker to the account with the most headroom. This is not round-robin — it concentrates workers on fewer accounts when load is low, keeping unused accounts available for burst capacity.
-- Find the least-loaded account with capacity
SELECT account_id, COUNT(*) as active_sessions
FROM agent_sessions
WHERE status = 'running'
GROUP BY account_id
HAVING COUNT(*) < 5
ORDER BY active_sessions ASC
LIMIT 1;Each account is a distinct Claude Code subscription with its own OAuth credential and its own git author identity (GIT_AUTHOR_EMAIL, GIT_AUTHOR_NAME). Workers spawned under different accounts produce commits attributed to their account — which means a git log on a multi-worker branch will show different authors for different commits, giving a readable audit trail of which session did what.
True parallelism requires distributing across accounts, not just goroutines. Spawning five workers under the same account queues the fifth. Spawning them across five accounts starts all five immediately. The bottleneck is the per-account session limit, not the server's ability to run concurrent processes.
This concurrency model scales in the same direction as the test-time compute literature. Snell et al. (2024) show that scaling inference-time compute — running more parallel attempts and selecting the best — consistently improves output quality on verifiable tasks. Account rotation is what makes parallel attempts financially and technically feasible: each additional account adds five more concurrent slots, so the system can scale horizontally in increments of five without hitting a single-account ceiling.
References
The coordination patterns above are grounded in published multi-agent and inference-scaling research. The citations below point to the specific papers that informed each design choice.
-
AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation
Why it matters here: Introduces the manager/specialist decomposition that underpins OperationKit's delegator pattern. AutoGen's core insight — that a coordinator who only routes is more reliable than one that also executes — directly motivates keeping strategy in the delegator and execution in workers. Also documents the conversational message-passing primitives that OperationKit replaces with SQLite rows and filesystem artifacts for durability.
arxiv.org/abs/2308.08155 ↗ -
MetaGPT: Meta Programming for Multi-Agent Collaborative Framework
Why it matters here: MetaGPT encodes role assignments as structured message routing graphs with explicit handoff contracts — preventing the ad-hoc tool-call chains that cascade into errors in naive multi-agent systems. This directly informs the allowlisted sibling read API: workers communicate through structured, schema-validated fields rather than reading each other's raw session state.
arxiv.org/abs/2308.00352 ↗ -
ChatDev: Communicative Agents for Software Development
Why it matters here: ChatDev demonstrates that a dedicated reviewer role — one that challenges the programmer's output rather than continuing from it — catches significantly more defects than a single-agent pipeline. This is the empirical foundation for OperationKit's autonomous reviewer: the reviewer's independence is not a process nicety but a measurable quality lever. ChatDev's software-engineering domain makes the findings directly applicable to OperationKit's working sessions.
arxiv.org/abs/2307.07924 ↗ -
The Society of Mind
Why it matters here: Minsky's central claim — that intelligence emerges from the interaction of many specialized, individually limited agents — is the theoretical premise behind all of the multi-agent systems above. More specifically for OperationKit: Minsky's prediction that agents operating on overlapping territory without arbitration produce contradictions (not solutions) is exactly what the double-spawn mitigations guard against. The delegator/strategy pattern is the arbitration mechanism Minsky said was required.
-
Scaling LLM Test-Time Compute Optimally
Why it matters here: Provides the empirical argument for the reviewer loop and for account-rotation-enabled parallelism. Snell et al. show that verifier-gated multi-attempt generation consistently outperforms single-attempt generation on verifiable tasks — that spending test-time compute on parallel attempts plus a judge is more efficient than spending it on a longer single chain-of-thought. OperationKit's reviewer loop is this pattern at the session level; account rotation is what makes parallel attempts feasible at scale.
arxiv.org/abs/2408.03314 ↗