I’m on file 8 of 15. Building a fullstack feature for ShipWithAI — a toolkit page with custom schema, overview layout, detail pages, seed content, and config updates. Claude Code has been doing great work, file by file, sequentially.
Then I notice it. The component on file 8 uses a completely different naming convention than what we decided on file 2. I re-explain the convention. Claude Code apologizes, fixes it. We continue. File 11 — the import paths contradict the folder structure from file 4. Re-explain. Fix. File 13 — it generates a type that conflicts with the schema from file 1.
I’m not coding WITH AI. I’m babysitting it.
This isn’t a rant about Claude Code. It’s the moment I realized single-agent AI coding has a structural ceiling — and started looking for a way around it.
The single-agent ceiling
Here’s the thing nobody talks about in the “AI will 10x your productivity” posts: one agent, one context window, one thread. That works beautifully for tasks that fit in a single mental model. Refactor this function. Write this test. Fix this bug. Claude Code is genuinely magical at these.
But the moment your task spans 10+ files with interconnected decisions — schema choices that ripple into components, API contracts that determine frontend behavior, config that affects routing — you hit the wall.
It’s not Claude Code’s fault. It’s physics. Even with a massive context window, real codebases have branching decisions that compound. By the time the agent reaches file 8, the decisions from file 1 have been pushed out of active attention. It’s not “forgetting” in the human sense — it’s context degradation. The signal from early decisions gets diluted by the noise of everything that came after.
What happens in practice:
- Sequential bottleneck: File A → B → C → D… each one waits for the last. A 15-file feature takes hours.
- Context degradation: Decisions from early files get lost or contradicted in later files.
- You become the orchestrator: Splitting tasks manually, running multiple sessions, merging outputs, catching conflicts. The AI does the typing, but YOU do the thinking about coordination.
The result: you’re a project manager babysitting a talented but forgetful developer. And it’s exhausting.
What multi-agent actually means
Forget the buzzword. Here’s the analogy that clicked for me.
Single-agent = one senior developer doing everything alone. Talented, but on a big project they’re slow and start making inconsistencies by the afternoon.
Multi-agent = one tech lead (the orchestrator) + a team of specialists. Tech lead decomposes the work, assigns pieces to the right people, reviews the results. Each specialist focuses on a narrow scope where they excel.
Oh My Claude Code (OMC) is that orchestration layer. It doesn’t replace Claude Code — it coordinates multiple instances of it, each with a focused scope. An architect agent designs the approach. Executor agents implement pieces in parallel. A reviewer checks the results. A verifier confirms everything works.
The key insight: multi-agent doesn’t solve the context window limitation — it works around it. Each agent still has limited context. But if its task is small enough, limited context is sufficient. The orchestrator’s job is decomposition: breaking big problems into pieces small enough that a single agent can hold the full context.
Here’s how the modes map to real situations:
- Autopilot: Senior dev working solo. Full autonomy, sequential. Good for clear, well-scoped tasks.
- Team: Tech lead delegates to a coordinated team. Staged pipeline with verification at each stage.
- Ultrapilot: Tech lead delegates to 5 devs working in parallel. Each gets non-overlapping files. 3-5x faster.
- Pipeline: Assembly line. Design → implement → review → test. Output from each stage feeds the next.
- Ecomode: Smart staffing. Simple tasks go to junior devs (Haiku — cheaper), complex ones to senior (Opus).
What actually changed in my workflow
I’ve been using OMC daily across multiple repos for months. Here’s the honest report — wins and fails both.
Win: Ultrapilot on the toolkit feature
The same 15-file feature that took a full day of babysitting? I described it to ultrapilot. OMC split the work: one worker on schema, one on overview page, one on detail page, one on seed content. They ran in parallel with non-overlapping files.
Was it perfect? No. I still reviewed the output and made some manual fixes — a couple of naming inconsistencies across workers, one import path that needed adjusting. But the bulk of the work was done significantly faster than sequential single-agent mode. And crucially, each worker had focused context on its piece instead of trying to hold 15 files in one brain.
Win: Team mode for batch bug fixes
ShipWithAI had 5 independent style bugs — light theme issues across different pages. Instead of feeding them to Claude Code one by one, I used team mode. Three executor agents, each claimed bugs from the pool, all running simultaneously. Five bugs fixed in one pass instead of five sequential sessions.
Win: Planning interview saves rework
Before building the toolkit feature, I used plan mode. OMC’s planner asked clarifying questions: “Static or dynamic content?” “How many tools initially?” “What’s your content schema?” “Category taxonomy?” About 8 questions total.
Five minutes of upfront clarification saved significant rework. Without it, the agents would have made assumptions — and three of those assumptions would have been wrong.
Fail: Ralph mode gone wrong
This one burned me. I used ralph mode on an ambiguous refactoring task: “clean up the auth module.” No clear definition of done. No specific acceptance criteria.
Ralph is a persistence mode — it keeps iterating until the architect agent verifies the work is complete. Without clear criteria, “complete” is undefined. Ralph kept looping for about 45 minutes. Each cycle made marginal improvements. “Not verified clean yet.” Another cycle. More minor tweaks. “Still not perfect.” Another cycle.
I burned a lot of tokens on increasingly pointless improvements before I manually cancelled.
Lesson learned: Ralph needs a finish line. “All tests pass, zero type errors, no unused imports” works. “Clean up the code” does not.
Key learning: CLAUDE.md is the shared brain
This was the biggest insight. Multi-agent without shared context is chaos.
Early on, I ran OMC on a repo without a CLAUDE.md. Two agents edited the same domain — one used camelCase, the other used snake_case. One created helper functions inline, the other extracted to utilities. They literally contradicted each other.
After writing a solid CLAUDE.md — conventions, patterns, folder structure, naming rules — every agent read it before starting work. Consistency jumped dramatically. CLAUDE.md becomes the “team agreement” that all agents follow. It’s not optional — it’s the foundation that makes multi-agent work.
When to use what
After months of daily usage, here’s my decision framework:
| Your situation | Use this | Why |
|---|---|---|
| Clear single task, well-scoped | autopilot | Sequential is fine when scope is narrow |
| Fullstack feature, many files | ultrapilot or /team | Parallelism shines on independent pieces |
| Batch of independent items | /team N:executor | Agents claim tasks from a shared pool |
| Sequential workflow (analyze → code → test) | pipeline | Output from each stage feeds the next |
| Mixed-complexity batch work | eco | Routes simple tasks to cheaper models |
| Vague requirements | plan first | Clarify before building |
| Must be done right, has clear done criteria | ralph | Persists until verified — but DEFINE “done” |
| Small task, 1-2 files | Vanilla Claude Code | OMC overhead exceeds benefit |
The important insight: the orchestrator’s job is decomposition, not magic. If you decompose well, each agent gets a focused task with sufficient context. If you decompose poorly, agents conflict and you spend more time fixing coordination issues than you saved.
The honest bottom line
OMC doesn’t turn AI into a senior developer. It turns YOU into a tech lead of an AI team. And like any tech lead, you still review code, handle escalations, and clean up messes. But throughput increases significantly when you know how to delegate.
Is it perfect? No. Ralph mode will burn your tokens if you don’t give it clear criteria. Agents will conflict if your CLAUDE.md is weak. Debugging is harder when output comes from 5 parallel agents instead of one sequential session. And you still need to understand every line of code that ships.
But for the first time, I’m not the bottleneck on multi-file features. The wall is still there — each agent still has a context window. But instead of one agent slamming into it repeatedly, I have a team of focused agents that each work within their limits. And that changes everything.
For install instructions and a detailed feature breakdown, see our Oh My Claude Code toolkit review. For a deep dive into multi-agent architecture, check out Module 7.3: Multi-Agent Architecture.