Scheduling Parallel Agent Sessions Across a Monorepo

Scheduling parallel agent sessions across a monorepo is primarily a dependency-mapping problem. Parallelism accelerates delivery only when task boundaries follow code cohesion, isolated environments contain each session, and shared-resource controls govern execution. Adding agents before those conditions hold multiplies coordination costs without increasing useful output.

Why parallel agents in a monorepo fail in ways that more concurrency cannot fix

More agents made things worse in the evaluations described by CoCoder. Assigning files to agents to work on in parallel raised API cost by 60% on CodeProjectEval, with only small gains in efficiency. In two benchmarks, Claude Code with Agent Teams fell below the sequential version in code quality. Those results expose a failure of orchestration.

The instinct to equate parallelism with throughput works for embarrassingly parallel tasks. Monorepo changes rarely fit that description because files import one another, call graphs are dense, and many tasks touch the same hub files. Uncoordinated agents collide on shared code structure, and more concurrency cannot repair those collisions.

How code dependency structure determines which tasks can safely run in parallel

CoCoder frames the governing constraint as a communication-to-computation trade-off. Splitting a task can shorten the critical path, but every dependency crossing an agent boundary requires context transfer. That transfer consumes tokens, expands prompts, and adds decoding time and cost. The computation saved must therefore outweigh the communication introduced.

In a repository, those dependencies have concrete forms, including imports, function calls, and shared writes. Import graphs show which files depend on definitions in other files, while call graphs show links that go beyond the file being edited. RepoOMP shows why checking only local code is not enough for parallelization: a loop that looks independent can reach a hidden shared write through non-local dependencies. The same engineering concern applies to agent assignment, where a separate file can still depend on changes outside its apparent scope.

Hub files make this constraint especially important. Project-wide utilities and top-level entry points link many parts of the repository, so a cut through a hub adds synchronization work that agents must do. Cohesion-aware decomposition keeps tightly coupled changes within one agent’s scope instead. That makes partitioning the primary design decision, rather than an optimization applied after arbitrary assignments.

How to partition a monorepo into agent-safe task boundaries using static analysis

The method starts with a weighted dependency graph built before agents get their tasks. CoCoder assigns per-file generation costs to vertices and context-transfer costs to directed edges. It then uses community detection through Infomap to find groups that keep costly dependencies within the group. The engineering output is a partition with weak connections between groups.

That partition need not serialize everything inside it. CoCoder uses post-processing to recover concurrency among tasks within a partition that have no mutual dependency. RepoOMP offers a complementary approach through its graph of attributes and performance at multiple granularities and Structured Transformation Context. RepoOMP shows agents the dependency facts they need and leaves out unrelated repository text, cutting agent-side token cost by 47–68% compared with an unstructured baseline.

For engineering teams, the natural cuts are package or module boundaries with narrow import surfaces. Enforced package boundaries and the absence of cross-cutting imports are therefore prerequisites for effective parallelism. The Cloudflare Workers SDK AGENTS.md example illustrates the rule behind that discipline in a pnpm-managed monorepo. Its instruction, “do not use npm or yarn”, protects package-boundary integrity and has a correspondingly large blast radius if ignored.

Why git worktrees are the right isolation primitive once partitions are defined

Once the partitions are sound, git worktrees give each agent a separate working directory and branch. The pattern is accessible through git worktree add ../agent-1 -b feature/agent-1 and git worktree add ../agent-2 -b feature/agent-2. Agents working in those directories cannot overwrite each other’s local edits because they are not editing the same working copy. Composio’s open-source Agent Orchestrator applies this pattern across a parallel fleet by assigning each agent its own worktree.

That physical separation solves a narrower problem than dependency mapping. Two isolated agents can still produce logically incompatible changes that become apparent only when their branches are merged. A worktree stops a filesystem collision while agents run, but it cannot tell whether their changes agree on a shared interface. The partition must establish that relationship first.

Worktrees are therefore an execution primitive for an already-correct assignment. They preserve separate working state while agents carry out their scopes. Treating them as a substitute for partitioning merely moves the collision from the working directory to integration.

How uncoordinated API access creates a second, independent failure mode at the infrastructure layer

Correct partitions and separate worktrees do not protect agents from contention at a shared, rate-limited API endpoint. HiveMind describes a workload in which staggering agents by a small fixed interval would have allowed all of them to succeed. The constraint was coordination rather than aggregate capacity. This failure is independent of the repository’s dependency graph and requires its own scheduler.

HiveMind addresses it through a transparent proxy that requires no changes to existing agent code. Its five primitives are admission control, provider-aware rate-limit tracking, AIMD backpressure with circuit breaking, per-agent token budgets, and priority queuing with dependency DAGs. Together, they treat API access as a shared resource rather than an unlimited service. HiveMind’s ablation finding identifies transparent retry as the most critical primitive, with retry and backoff recovering most of the reliability gain and the full combination performing best.

The proxy’s scope is equally important. HiveMind does not coordinate filesystem operations or tool calls, so it cannot prevent agents from writing incompatible code. Conversely, careful partitioning cannot stop uncoordinated requests from colliding at the provider. Production scheduling needs both a dependency-aware task layer and a coordinated API layer.

AGENTS.md as the coordination layer that connects partition boundaries to agent behavior

The orchestrator must pass its partition decisions to the agents. Package-scoped AGENTS.md files turn those decisions into instructions that agents read as they work. A root file has rules for the whole repository, including the package manager, commit format, and credential constraints. Files within package directories hold local rules, with agents reading the applicable chain on each run.

OpenAI’s Codex repository ships 88 AGENTS.md files across its directory tree, demonstrating the nesting pattern in a large repository. For organizations that need centralized control, Nx’s nx-ai-agents-config generates CLAUDE.md and AGENTS.md files through nx configure-ai-agents from a single source of truth. That approach treats agent configuration as a build artifact rather than a collection of independently maintained files. It applies the agents-as-code principle to the instructions governing execution.

Those instructions are also a security surface. An AGENTS.md change can alter future patches and deserves the same seriousness in code review as a CI configuration change. Review must check broad permissions, network instructions, how credentials are handled, and commands that fetch or run remote content. Those instructions can do more harm when agents have access to MCP servers, cloud credentials, or deployment systems.

Sandbox isolation and scoped credentials as the runtime governance requirement for parallel sessions

Instructions say how a session should behave, but runtime isolation limits what it can affect. Parallel agents may share access to cloud resources, package registries, and deployment systems even when their working directories are separate. Without per-session isolation, a failure or compromise can cross the code partition through those shared resources. A worktree is therefore not the complete security boundary.

The production model gives each session fresh credentials scoped to the resources its partition needs and revokes them on completion. Credentials that outlive the session or span multiple partitions create unnecessary shared-state risk. Per-session sandboxes complement that credential scope by isolating execution. Together, they contain the blast radius beyond the filesystem.

Singapore’s IMDA Model AI Governance Framework for Agentic AI (January 2026) recommends verifiable digital identities and an audit trail showing which agent acted under whose authorization. NIST’s National Cybersecurity Center of Excellence companion concept paper to the AI Agent Standards Initiative (February 2026) points to a gap in these controls. Agents are often treated as generic service accounts with no identity, authorization, or accountability controls of their own. Per-session identity and credential minting address that gap directly.

Budget controls that prevent parallel sessions from multiplying cost unpredictably

Running sessions in parallel multiplies usage that is already higher than expected in the chat era. Planning, tool calls, memory retrieval, and self-reflection add tokens throughout an agent’s run, while a single autonomous task can require dozens to hundreds of API calls. Cost control must therefore happen before each call. Each session needs its own limits that fit within budgets for each developer and time period.

The enforcement model places separate ceilings on tokens, model calls, tool calls, retries, and dollars, with checks at the run, step, and tool level. A central budget manager backed by a persistent store reserves spend before each call and reconciles actual usage afterward. It blocks over-budget actions. HiveMind’s per-agent token budgets do the same at the API proxy so that one session cannot use up the shared allowance.

As budget falls, routine work can move from a frontier model to a fallback, followed by context compression and tighter tool gating. The gating pattern disables web search before non-critical retrieval while preserving required database reads. Model routing and prompt caching reduce cost without reducing concurrency, with prompt caching typically achieving 50–90% savings on input tokens.

Observability across parallel sessions — what a complete audit trail requires and what most teams are missing

Most teams log prompts and completions but miss the record of governance. Those logs capture intent and response without necessarily showing tool calls, guardrail decisions, or the authorization under which a session acted. Parallel execution makes that omission harder to tolerate because several agents may be writing code, opening PRs, and calling tools at once. Every action must be attributable to a specific session, trigger, and person or system.

A complete session trace covers tool calls, retrieval sources, guardrail decisions, judge scores, and timing. Its span attributes carry model version, prompt version, policy version, user ID, and trigger. OpenTelemetry traces make this record queryable, while tamper-evident logging ties actions to the policies that governed them. Monitoring then connects sandbox enforcement to auditing.

The session itself must be preserved along with its commits, PRs, and CI output. Those engineering artifacts cannot reconstruct all the decisions that produced a change. EU AI Act Article 12 requires high-risk AI systems to have the technical means to record events automatically throughout the system’s lifetime. A completion log alone cannot explain which guardrail intervened or how, so output retention is not a sufficient audit design.

Putting it together: the scheduling architecture for parallel agents in a production monorepo

Layer 1 is partitioning, which builds the dependency graph, finds cohesive groups, and maps them to agent scopes before execution. CoCoder backs this order of work with higher pass rates, better wall-clock speed, and lower API cost than file-based parallel baselines, and the gains are largest on dependency-dense projects. This is the repository-specific foundation.

Layer 2 is isolation, which assigns worktrees and per-session sandboxes to those scopes. Fresh, narrowly scoped credentials extend the boundary from code edits to resource access.

Layer 3 is API scheduling, which routes sessions through coordinated admission, rate-limit tracking, backpressure, budgets, and priority queuing. HiveMind cuts failure rates to 0–18% and adds under 3ms to each request.

Layer 4 is configuration, which expresses repository-wide and package-specific behavior through reviewed AGENTS.md files. Layer 5 is governance, which enforces spend before calls and attributes tool use and diffs through complete session traces. Together, they make the execution both bounded and explainable.

Layer 1 is always custom work because safe partitions depend on the repository’s own structure. Layers 2–5 are infrastructure that a managed platform should handle. Parallelism becomes useful only when that infrastructure executes a sound dependency map.