Microservice architectures create a coordination problem that single-agent coding tools cannot solve. When a bug spans three repositories, you need to trace contracts across codebases, validate schema changes, and ensure PRs land in the right order. RepoOrch is an open-source Claude Code plugin that turns this into an agent team problem, with explicit work partitioning, peer-to-peer messaging, and hard read-only safety boundaries.
The coordination gap
A typical multi-repo workspace looks like this:
my-project/
├── auth-service/
├── payments/
├── notifications/
├── inventory/
└── shipping/A ticket arrives: “Users getting 401 errors after auth refactor.” The bug lives across repositories. Maybe auth-service changed JWT claim shape. Maybe payments expects the old shape. Maybe notifications never validated claims properly.
Single-agent tools fail here because:
- They lack context about which repos need changes
- They cannot coordinate state across repository boundaries
- They have no mechanism to validate cross-repo contracts before committing
- They cannot handle partial failure when one PR breaks CI
Agent Teams primitive
Claude Code introduced Agent Teams as a coordination layer above subagents. The key difference is the mailbox abstraction.
Subagents receive instructions, execute, return results. No peer communication.
Agent Teams get:
- Persistent mailboxes for async messaging
- Ability to query other agents’ state
- Explicit handoff protocols
- Shared context about workspace topology
RepoOrch uses this to implement a three-phase orchestration pattern:
- Triage: Coordinator agent reads the ticket, scans repository structure, identifies affected services
- Analysis: Specialist agents (one per repo) analyze their codebase, propose changes, publish findings to mailboxes
- Validation: Coordinator reads all proposals, checks for contract breaks, orders PRs by dependency graph
Architecture
RepoOrch assigns roles based on workspace topology:
| Role | Responsibility | Scope |
|---|---|---|
| Coordinator | Ticket intake, dependency ordering, final validation | Workspace-wide |
| Repo Specialist | Code analysis, change proposal, contract documentation | Single repository |
| Contract Validator | Schema diff, API compatibility check | Cross-repo interfaces |
Each agent gets:
- A mailbox (append-only message queue)
- Read access to all repos
- Write access to exactly zero repos (propose-only mode)
- A knowledge graph of workspace structure
Mailbox protocol
Agents communicate through structured messages:
{
"from": "auth-specialist",
"to": "coordinator",
"type": "proposal",
"payload": {
"repo": "auth-service",
"files": ["src/jwt.ts", "src/claims.ts"],
"changes": "Add `user_tier` claim to JWT payload",
"contracts_affected": ["payments", "notifications"],
"breaking": false
}
}The coordinator reads all proposals, builds a dependency graph, and determines merge order. If payments depends on the new JWT shape, auth-service PR must land first.
Knowledge graph optimization
On first run, RepoOrch builds a lightweight knowledge graph:
- Service boundaries (detected from
package.json,go.mod, etc.) - API contracts (OpenAPI specs, proto files, GraphQL schemas)
- Shared types (imported across repos)
- Database schemas (migrations, ORM models)
This graph cuts token cost by 60-80% on subsequent tickets. Instead of re-reading five codebases, agents query the graph for contract definitions and dependency edges.
Safety model
RepoOrch enforces propose-only mode at the platform layer, not through prompt engineering. Agents cannot:
- Commit code
- Push branches
- Open PRs
- Modify files outside their assigned repo
They can only:
- Read files
- Write proposals to mailboxes
- Query the knowledge graph
A human reviews all proposals before any code changes. This is not a trust issue. It is a correctness issue. Cross-repo changes have blast radius. Automated commits without human validation create more problems than they solve.
Failure modes
Scenario 1: One PR fails CI
Coordinator marks dependent PRs as blocked. Specialist agent for the failing repo gets error logs, proposes fix, resubmits. Other PRs remain in draft state until dependency resolves.
Scenario 2: Merge conflict
Agents do not resolve conflicts automatically. Coordinator detects overlapping file changes, flags conflict in proposal, hands off to human. Automated conflict resolution in multi-repo contexts is a trap.
Scenario 3: Contract break detected late
Contract Validator runs schema diffs before proposals leave mailboxes. If a breaking change is detected (e.g., removing a required field), coordinator rejects the proposal set and asks specialists to revise.
Scenario 4: Stale knowledge graph
Graph rebuilds on workspace structure change (new repo added, service renamed). Incremental updates happen on file watch. If graph is stale, agents fall back to full codebase read (slower but correct).
Implementation notes
RepoOrch is a Claude Code plugin, so it inherits the platform’s orchestration layer. Key integration points:
- Tool calls: Agents use
read_file,list_directory,search_codebasetools. No custom file I/O. - State management: Mailboxes persist in SQLite. Coordinator reads mailbox state on every decision.
- Observability: All agent messages logged to structured JSON. Easy to trace decision flow.
- Deployment: Runs locally in Claude Code. No server, no API keys beyond Claude itself.
The propose-only safety boundary is enforced by the plugin’s tool allowlist. Agents literally cannot call write_file or git_commit. This is better than prompt-based safety because it survives jailbreaks and context window overflow.
Technical verdict
RepoOrch solves a real coordination problem. If you regularly open five tabs to trace a single bug, this pattern cuts cognitive load. The mailbox abstraction is clean. The propose-only safety model is correct.
The knowledge graph optimization matters. Without it, token costs scale linearly with workspace size. With it, you pay once for structure and amortize over tickets.
The failure modes are honest. Agents do not resolve merge conflicts. They do not auto-commit. They do not guess at contract compatibility. This is the right trade-off for production systems.
Use this when:
- You have 3+ microservice repositories with frequent cross-repo changes
- Your team already uses Claude Code
- You need human review before commits (not full automation)
- Service boundaries are stable enough to graph
Avoid this when:
- You have a monorepo (single-agent tools work fine)
- You need fully automated commits without human approval
- Your workspace has more than 20 repos (knowledge graph becomes expensive)
- Contracts change too frequently to maintain a stable graph
The propose-only constraint is non-negotiable. If you want agents that auto-commit across repos, this is not the tool. If you want agents that help you coordinate complex changes safely, this is exactly the tool.
Source links
- RepoOrch on GitHub (MIT licensed, v0.3.0)
- Original article on Dev.to