I built it in about eight hours instead — with three Claude Code agents, one per service, coordinating with each other in real time while a single human (me) held the brakes.

This is a build log of how that worked: the workflow that kept three parallel codebases coherent, the guardrails that kept three autonomous agents from stepping on each other, and, just as useful to the next person, where the friction showed up and why it stayed cheap to fix.

It’s also a sequel. A while back I built a way for Claude Code instances to talk to each other across machines — a proof-of-concept MCP-channel bridge I called claude-code-chat. That article ended on a toy demo: three agents building a counter app. Since then I’ve turned the prototype into a proper, installable Claude Code plugin, claude-chat — early still, but a real, reusable plugin rather than a one-off script. The honest open question the demo left was whether the pattern survives contact with real, production-shaped work. This is the answer — run on the plugin, not the prototype.

Scope note: this is a methodology record, not a feature design — a general way of working I now reach for, shown here on one real project. The feature happened to be optional 3D Secure (3DS — the “verify it’s really the cardholder” step on card payments), but the feature and its details belong to the project; what’s reusable, and all this article is really about, is how three agents built it together.

From “agents can talk” to “agents ship together”

The first article built the plumbing; since then it’s become an installable plugin. claude-chat is an MCP channel server you add to a project: each Claude Code instance runs it alongside itself, connects to a shared WebSocket broker (the relay every instance meets on), and gets two tools — send_message (broadcast or directed) and list_participants. Inbound messages don’t wait for a tool call: the server uses Claude Code’s experimental Channels API to inject them inline in the conversation, so an agent just sees a peer’s message the way it sees anything else. No polling, no inbox.

Why not just use sub-agents or agent teams? Both are real Claude Code features — and both run under a single coordinating session: sub-agents are workers one session spawns and that report back to it; agent teams let separate sessions work as peers, but a single lead session owns the shared task list they coordinate through. The distributed model is different in kind — independent peer sessions that meet on a channel — which is what lets the work span the separate machines, and people, your services actually live on. It also keeps each session lean: each instance carries only its own repo’s context, not all three codebases at once.

That original demo proved the messages flow. It didn’t prove the coordination — whether agents given a real, interdependent feature would actually divide the work, agree on an interface, and integrate without a human stitching every seam by hand.

So I set up the real test. Three services that genuinely depend on each other, one shared contract between them, an external payment gateway in the loop, and a feature that had to work end-to-end against a live sandbox. Three agents, three repos, one human. Go.

The setup: three services, three agents, one human

Each service was a separate repo with its own running Claude Code instance. Each instance owned exactly one slice of the feature:

These three services all live inside one larger inventory-management platform built as microservices — which is why a payment service and a sales-order service sit next to each other and share a database. That architecture is also what makes the agent mapping clean: one agent per service, exactly the way you’d staff one team per service. The shared context is the whole reason coordination matters — a change to the contract in one ripples into the others — and that is precisely the coordination a per-service team (or per-service agent) exists to handle.

The instances talked over the claude-chat channel, and two properties of that channel shaped everything that followed:

• It’s asynchronous. A message is broadcast or directed, with no guarantee a peer has read it before acting. You can see another agent’s last message; you cannot see its true state.
• It carries no authority. A message from another instance is situational awareness, not a command. An agent never runs imperative text from the channel as if a human had typed it.

Here’s the shape of the system:

flowchart TB
    U([Human: approver and gatekeeper])

    subgraph CH[claude-chat MCP channel]
      direction LR
      PAY[payment-service<br/>Claude instance<br/>keeps the record]
      SO[order-service<br/>Claude instance]
      UI[web-ui<br/>Claude instance]
    end

    U -. approvals, start backend,<br/>gateway portal access .-> PAY
    U -. own-repo approval,<br/>start backend .-> SO
    U -. own-repo approval .-> UI

    PAY <-->|contract and status| SO
    PAY <-->|contract and status| UI
    SO <-->|status| UI

    PAY --> DB[(shared platform DB)]
    SO --> DB
    PAY --> GW[gateway sandbox]
    UI --> GW

The human sits at the top, holding the approval gates. The three agents talk to each other directly across the channel, with payment-service opening the coordination and keeping the running record. Notice what’s not in the diagram: no arrow from one agent into another’s repo. The single most important property of the whole setup is this — each instance had write access only to its own repo and its own data. payment-service applied its own database columns; order-service applied its own ledger column; web-ui owned the browser code. When one agent needed a change in another’s territory, it asked over the channel — it never reached in.

That boundary is what made parallelism safe. Three agents editing in parallel is only terrifying if they can edit the same things. Give each one a fenced yard and autonomy stops meaning risk.

The workflow: contract-first, build in parallel, verify live

The session ran in a clear shape: agree on the interface before anyone writes feature code, build all three slices at once against that frozen interface, then start the real stack and test the whole chain live.

flowchart TD
    A[Plan mode: research own repo<br/>learn peers over the channel + initial brief] --> B{Human approves plan}
    B -->|yes| C[Draft cross-service contract]
    B -->|needs work| A
    C --> D[Ratify with consumers over claude-chat<br/>consumers review, web-ui runs an API spike]
    D --> E[[Freeze contract v1]]
    E --> F1[payment-service builds its slice]
    E --> F2[order-service builds its slice]
    E --> F3[web-ui builds its slice]
    F1 --> G{Human: start backend stack}
    F2 --> G
    F3 --> G
    G --> H[Live end-to-end test matrix vs gateway sandbox]
    H --> I{Defects?}
    I -->|yes| J[Fix in the owning repo<br/>re-verify against authority]
    J --> H
    I -->|no| K[Commit per repo on human approval]
    K --> L[Docs deferred until sign-off]

Walking the stages:

Plan, gated. The coordinator planned without ever reading the other repos. My initial prompt sketched the neighboring services, and it learned the rest by asking the other agents over the channel — what each service did and what it was capable of. From that it surfaced the genuine design forks to me, and only moved once I approved. Nothing got built on a guess about how the other services worked — and nothing required reaching into another team’s code to find out. The understanding arrived over the channel, exactly as it would if the three agents sat on three different machines.

Contract-first. Before a line of feature code, the coordinator drafted the cross-service contract — the shape of the data passing between services — and circulated it for ratification instead of declaring it.

Freeze. Once the consuming services agreed and the one external unknown was resolved, the contract was pinned as v1 and broadcast as the single reference.

Parallel build. Each instance implemented its slice against the frozen contract, independently and at the same time.

Integrate and verify. I started the backend stack; live tests ran against the real gateway sandbox — not mocks.

Fix loop. Defects were fixed in the owning repo and re-checked against an authoritative source, not against memory.

Commit, then docs. On my go-ahead, each repo landed its slice — web-ui and order-service as standard feature-branch PRs, payment-service handled differently. The narrative docs came last, after the behavior was proven.

The freeze point is the hinge. Everything before it is sequential and careful; everything after it runs in parallel. Get the contract right and the parallel phase mostly takes care of itself.

The contract was the load-bearing piece

The contract is the thing that let three codebases move at once without drifting apart. It held because of three habits.

It was ratified, not decreed. The first draft was a proposal. The consuming services pushed back before agreeing, and the contract got two concrete improvements out of it: a naming collision was caught and renamed (an inner field was shadowing the object that contained it), and a consumer asked for a stable, machine-detectable error marker — a 3DS_REQUIRED: prefix — so the frontend could react to that specific case instead of string-matching free-form error text. Both were folded in before the freeze. The interface got better precisely because it was negotiated rather than handed down.

One source of truth, additive shape. The flag lived in exactly one place — authoritative in the enforcing service, surfaced to the browser by extending a call that already existed. The pass-through data was optional everywhere, so when it was absent the existing flow stayed byte-for-byte unchanged. The feature was strictly additive and backward-compatible — which is a large part of why three services could adopt it without breaking each other.

One canonical freeze, broadcast to all. After ratification, the contract was pinned as v1 and broadcast with explicit ownership of each part. From that moment it did not shift under anyone mid-build.

Here is how that ratification actually played out across the channel:

sequenceDiagram
    autonumber
    participant PAY as payment-service (coordinator)
    participant SO as order-service
    participant UI as web-ui
    PAY->>SO: Draft contract (data shape, enforcement, echo-back)
    PAY->>UI: Draft contract + kick off an API spike
    SO-->>PAY: Review feedback (objections to the contract)
    UI-->>PAY: Spike result: needs a machine-detectable error marker (3DS_REQUIRED)
    PAY->>PAY: Fold feedback (rename collision,<br/>add 3DS_REQUIRED marker) into the contract
    PAY-->>SO: Broadcast FROZEN v1 (with ownership)
    PAY-->>UI: Broadcast FROZEN v1 (with ownership)
    Note over PAY,UI: Parallel build begins against v1<br/>contract does not shift under anyone

The coordinator drafts and sends to both consumers, kicking the frontend off on a parallel spike to de-risk the one external unknown. The consumers send feedback back up. The coordinator folds it in — once — and broadcasts the frozen version with ownership attached. Only then does parallel build begin. The negotiation is front-loaded so the build phase has nothing left to argue about.

The steering wheel kept moving

The surprise wasn’t that the agents coordinated — it was that none of them stayed in charge, payment-service included. It had opened the session and kept the record — coordinator in the clerical sense — but bookkeeping isn’t authority. Leadership followed the work: whoever owned the flow in play took the wheel, steered it, and handed it on — and the agents worked those handoffs out among themselves, announcing each one over the channel rather than asking permission.

• Build — payment-service drove. It opened the coordination, worked the 3DS server logic through with order-service, then turned to web-ui to help build the browser changes against the frozen contract.
• End-to-end UI testing — web-ui drove. Once the slices were ready, web-ui took the wheel and steered the live test runs. payment-service and order-service dropped into support — watching their own logs and fixing their own bugs as the tests flushed them out, while web-ui fixed its own.
• Negative testing — order-service drove. Then order-service took control and deliberately broke things: forcing failures inside its own service to see how the whole chain handled them. The others watched how the end-to-end flow degraded and patched what surfaced.

Two things held it together. payment-service, because it had started the session, kept the running record — each driver reported progress back to it, so there was one continuous account of what happened. And the handoffs were genuinely self-organized: the agents agreed among themselves who should own and steer each flow and posted the change to the channel, so I saw every handoff as it happened. I wasn’t approving who held the wheel — I was watching it move. My approval gates sat elsewhere, on the things you can’t cleanly undo: the plan, the commits, the external gateway. Nothing reassigned itself silently; every change was announced — just not gated.

That’s what “peer-to-peer” actually looked like — not three workers under one manager, but three peers passing a single steering wheel by agreement among themselves, with a human watching it move, not directing it.

sequenceDiagram
    autonumber
    participant HU as human (kept informed)
    participant PAY as payment-service
    participant SO as order-service
    participant UI as web-ui
    Note over PAY,UI: payment-service keeps the running record throughout

    rect rgb(240,244,253)
    Note over PAY,UI: Phase 1 — build · payment-service steers
    PAY->>SO: build 3DS server logic together
    PAY->>UI: help build the browser changes
    end

    UI->>PAY: agree — web-ui takes the wheel for UI tests
    PAY-->>HU: announce steering handoff (informational)
    rect rgb(240,250,244)
    Note over UI: Phase 2 — end-to-end UI tests · web-ui steers
    UI->>UI: run live tests, fix own bugs
    PAY->>PAY: watch logs, fix own bugs
    SO->>SO: watch logs, fix own bugs
    UI-->>PAY: report progress
    end

    SO->>PAY: agree — order-service takes the wheel for negative tests
    PAY-->>HU: announce steering handoff (informational)
    rect rgb(253,247,238)
    Note over SO: Phase 3 — negative testing · order-service steers
    SO->>SO: force failures, test the chain
    PAY->>PAY: observe end-to-end handling, fix
    UI->>UI: observe end-to-end handling, fix
    SO-->>PAY: report progress
    end

The wheel changed hands twice; I assigned it zero times.

(It all runs on one open-source plugin, claude-chat — the code’s there if you want to see how.)

The guardrails that made autonomy safe

Three autonomous agents with file-write and shell access is a lot of loaded guns in one room. What kept them from doing damage or quietly diverging was a small set of standing rules. Read these less as the exact set I happened to switch on and more as the levers the approach puts on the table — you dial each one up or down to match the stakes of the work.

Human gates on anything irreversible or outward-facing. Approving the plan, accessing the external gateway portal, and committing each repo were all human-gated. And because each agent ran in its own terminal, I could watch all three at once, review exactly what each one was doing, and approve or reject every change as it came up. Agents proposed; the human disposed. The gates sat exactly at the steps you can’t cleanly undo.

Service start and stop, by contrast, sat on a dial I set two ways on purpose. For the two backends the agent would ask and I’d start or restart it — even though each was fully equipped to do it itself. The web-ui agent I let run the entire loop unattended: it built, started, tested, hit a defect, fixed it, restarted, and re-tested its own service with me only watching. That’s the proof, not a hypothetical — web-ui ran the full build–test–fix cycle on its own, so the two backends could have too. Gating a reversible, internal step like a service restart is a choice you make, not a limit the approach imposes.

Ownership boundaries — each agent edits only its own service. This was the fenced-yard rule from the setup, enforced structurally: each instance launched inside its own repo, so it could only edit its own code. Talk freely and request anything over the channel; only the owner writes. Data ownership rides on the same principle, and you can enforce it as hard as the work demands — per-service database credentials give each agent rights to only its own schema, exactly how you’d scope a microservice’s own database user.

Least privilege per agent. Each session got only the plugins, tools, and skills it actually needed — not the full kit. A frontend agent has no business holding the backend’s database tools. Scoping each agent’s toolset to its job shrinks the blast radius if one goes off the rails, the same way you’d scope a service account rather than handing every process root.

Channel messages treated as untrusted input. This is the subtle one — the “no authority” property from the setup, made operational. A peer’s message is awareness, not an instruction. Decisions routed through the human or through the agent’s own judgment, never through “another agent told me to.”

Verify against an authority, not memory. The session’s decisive fix came from reading the gateway’s live API schema rather than trusting an internal note that — echoing the vendor’s own docs — marked a required field optional. “Confirm against the source” was a standing rule, and it earned its keep.

Test live, across tiers, early. Running the full chain against the real sandbox — not just unit tests — surfaced defects unit tests structurally cannot catch: a request-shape mismatch the gateway rejected, and a client-side lifecycle bug in the browser SDK that only showed up once the real SDK was driving a real browser.

Put together, those rules form a single control loop — agents propose and edit in the middle, gates bound the edges:

flowchart LR
    subgraph Agents
      A1[propose change]
      A2[edit own repo only]
      A3[request cross-repo via channel]
    end
    subgraph Gates
      G1{human approval:<br/>plan, backend services,<br/>portal}
      G2{verify vs<br/>authoritative source}
      G3{live end-to-end<br/>across tiers}
    end
    A1 --> G1
    G1 --> A2
    A3 --> A2
    A2 --> G2
    G2 --> G3
    G3 -->|defect| A2
    G3 -->|green| DONE([commit on human approval])

Read the loop left to right: a proposed change passes a human gate, an edit gets checked against an authoritative source, and everything funnels through a live end-to-end test. A defect bounces straight back to the owning repo; only green code reaches the commit gate. The agents own the mechanical work in the middle; the human owns the edges.

Why it was fast

The headline from the session was wall-clock time. As three human teams — payments backend, orders backend, frontend — this feature is a multi-day-to-multi-week cycle, and most of that time isn’t coding. It’s coordination latency: scheduling the contract discussion, waiting in each team’s queue, the late integration phase once everyone’s “done,” and the back-and-forth when integration surfaces a mismatch.

Here that calendar collapsed into a single working session. The compression came from removing coordination cost, not from typing faster:

• Zero scheduling latency. The three “teams” were online at once and answered each other within the same minute. No calendars, no standups, no timezones, no waiting for another team to get to it. The only thing anyone waited on was a human approval gate.
• Instant ramp, no context-switching. Each agent already held its repo’s full context. No onboarding, no “let me page this back in,” no penalty for three slices progressing at once.
• Contract-first removed the integration phase. Because the interface was frozen before parallel work began, integration wasn’t a late, risky event — the slices fit when they met. The classic “each part works alone but not together” week largely didn’t happen.
• Minutes-long feedback loops. When live testing surfaced a defect, it was diagnosed, fixed in the owning repo, rebuilt, and re-tested in the same session — not filed, triaged, and scheduled across teams.

One number to anchor this — and an honest breakdown of it. End to end, the session took about eight hours of wall-clock time. But the agents were only actively working for maybe two of those hours. The other six were mine, and they split in two. Part was first-run cost I won’t pay again: standing up the environment, wiring the per-agent access controls, testing the setup held together, and learning to drive three agents at once. The rest won’t go away — researching the problem, the high-level design, planning the approach, and the context and expectations I set for the agents up front. That work recurs on every project and scales with the problem’s complexity, not with the tooling; it’s the upfront human judgment any serious AI effort needs to get a result worth keeping, not overhead this approach adds.

Set the session against however long the same three-service feature would take if run as three separate teams in your own org, and you have your multiplier; for my baseline that runs to days, often weeks.

That breakdown is the whole point. What this is not is a claim that it ran unattended or instantly. The critical path was the human — the research, the design, the plan approval, starting the backend services, the live-test loop. (The agents’ two hours were the cheap part — which also kept the compute modest: three instances running for two hours, not eight.) The durable lesson is narrower and more useful than “AI is fast”: agent collaboration removes the inter-team latency that usually dominates a multi-service feature, which leaves your judgment, not the calendar, as the thing setting the pace.

The friction was ordinary — the recovery wasn’t

Every collaborative build has friction, whether the collaborators are people or agents. This session had its share. What’s worth noticing isn’t that the friction showed up — it always does — but how little it cost to clear. It’s the ordinary cost of any team building together, and in a few cases the approach absorbed it faster than a human team would.

A peer’s state got misjudged — and the structure caught it. At one point payment-service assumed web-ui had built its slice when it was still at design. This is inherent to anyone coordinating asynchronously: you see a peer’s last message, not its true state. Human teams hit this constantly, where it becomes the “I thought you were handling that” conflicts and blocked work that quietly eat a calendar. Here it cost almost nothing — the human coordinator exists for exactly this, and live end-to-end testing would have surfaced the mismatch regardless. It was caught and corrected in the same session. The working habit is simple: ask “is your slice done?” and confirm, rather than infer.

Planning happened alongside building — and a flawed plan self-corrected. The plan took a few rounds to settle, because planning and building ran together, the way a real team works rather than a waterfall handoff. You can trim those rounds with more planning up front. But the point that matters cuts the other way: even where the human’s initial plan was incomplete, the collaboration surfaced the gaps and resolved them mid-flow. The approach is resilient to planning mistakes, not brittle to them.

Agents followed the standard convention — I wanted a different one for one service. All three reached for the same correct move: work on a feature branch, then open a PR. For web-ui and order-service that’s exactly what I wanted, and that’s how their slices landed. payment-service reached for the same flow — but for that one service I wanted commits straight to the main branch instead of a PR, and I hadn’t said so up front. That’s not an agent error; it’s an unstated preference on my side. The lesson is about context-setting: when your house style departs from the default for a particular service, say so at the start, the same way you’d brief a new teammate.

A wrong schema guess got caught and fixed in one sitting — not over a week. This is the field-marked-optional miss from the guardrails above — and it’s the benefit, not the bug. Unit tests passed; the live sandbox rejected the request. In a three-team setup this is the classic integration failure: it surfaces late, gets filed as a ticket, bounces between teams while everyone argues whose mapping was wrong, and burns days. Here it surfaced during live end-to-end testing, was diagnosed, fixed in the owning service, and re-verified in the same session. Collaborative build plus live testing collapsed a multi-day integration-defect cycle into minutes.

The pattern across all four: the frictions are the ordinary ones of any team effort, but the recovery loop — a human coordinator at the helm, live testing across tiers, fixes in the owning service — kept each from becoming the multi-day, multi-team problem it usually is. The approach didn’t avoid being wrong; it made being wrong cheap to fix.

The pattern scales

This session used the smallest possible configuration: one person coordinating all three agents on one machine. That’s incidental. The same channel works identically whether the agents share a laptop or span three continents — so the other end of the range is one person per service, each steering their own agent from wherever they are, connected by the same async channel.

flowchart LR
    subgraph MIN["Minimum — one person"]
        direction TB
        H([Human])
        H --> PA[payment-service<br/>agent]
        H --> SA[order-service<br/>agent]
        H --> UA[web-ui<br/>agent]
    end

    CH(["async coordination channel<br/>(identical in both cases)"])

    subgraph MAX["Maximum — one person per service, any location"]
        direction TB
        HP([Human · location A]) --> PP[payment-service<br/>agent]
        HS([Human · location B]) --> SS[order-service<br/>agent]
        HU([Human · location C]) --> UU[web-ui<br/>agent]
    end

    PA <--> CH
    SA <--> CH
    UA <--> CH
    PP <--> CH
    SS <--> CH
    UU <--> CH

At the minimum, it’s one person doing the work of three teams. At the maximum, it looks indistinguishable from three separate teams — except the back-and-forth between them is close to zero. The channel doesn’t care which end of that range you’re at; co-location was a convenience, not a requirement.

What this proved

The first article asked whether Claude Code instances can talk to each other. This one asked whether that conversation is worth anything when the work is real. It is — with a caveat that’s actually the interesting part.

The mechanical coordination is the easy win. Contract-first parallelism, ownership boundaries, a frozen interface — give agents those and they divide a real feature, negotiate the seams, and build the slices in parallel about as well as you’d hope. That part nearly runs itself.

The hard part is the human’s. The gates, the peer-state discipline, the unstated conventions, the insistence on checking the source of truth — every one of those frictions lived there, not in the code. Which is the encouraging read, not the discouraging one: the agents handled the mechanical coordination that usually eats a team’s calendar, and handed the genuinely hard judgment back to the one place it belongs.

Personal insight: I wrote earlier that each Claude Code instance already behaves like a team — a lead coordinating specialized workers — and that a channel could connect those teams across machines. Watching three of them negotiate a contract, divide a real feature, and catch each other’s gaps turned that from a tidy diagram into something I could point at. The surprise wasn’t that it worked. It was where the work moved: off the calendar, off the inter-team back-and-forth, and squarely onto my judgment at a handful of gates. That’s not “AI replaces the team.” It’s the coordination tax disappearing and the judgment staying exactly where it was.

The pieces are early and the rough edges are real — the friction above isn’t a footnote, it’s the manual. But the direction is clear enough to act on: if you’ve got a feature spanning services and a backlog of coordination overhead to match, this is a pattern you can run today. The claude-chat plugin is open source and free — a research-preview build on that experimental Channels API — early enough that each instance launches behind a flag literally named --dangerously-load-development-channels — with a README that walks the whole setup end to end.

And you don’t need three services to feel it. The lowest-effort try is two terminals: stand up one broker (bunx claude-chat-broker — no checkout needed), add the plugin with /plugin marketplace add vikrantjain/claude-chat, then launch two Claude Code instances with the development-channels flag and watch them discover each other and talk. Once the channel clicks, the three-service version is just more of the same. It’s built for real, multi-service work, not a demo — but you can prove the idea to yourself in a single sitting.

The tool isn’t the variable. The category is.

I argued previously that AI productivity gains require organizational change, not just tool adoption. Several leaders pushed back: you’re proposing a solution without showing me the real problem. That’s fair. This article shows both — first the problem, then the solution.

The failure loop

I’ve watched this loop play out. An engineering organization rolls out costly AI licenses to every developer and keeps its existing process — product writes specs, architects design, work breaks down into sprint tickets, tickets get assigned to humans. Then it expects the AI to make those humans 3–5x faster inside that same machine.

A year later, deliveries are slower, total cost is higher, and bug counts are flat or worse. The leadership response is rarely to question the process. It’s to switch to a different AI tool. Six months later, same result.

They keep solving for the wrong variable.

A coding agent is not an IDE

The category mistake is hiding in the procurement spec. An IDE is an integrated development environment — editor, file tree, terminal, debugger, search — wrapped together for human eyes and hands. The “I” stands for integration, and integration is for humans.

A coding agent doesn’t have eyes. It calls discrete tools — read a file, run a command, edit a line — and reads back the response. It doesn’t need an integrated workspace because it doesn’t perceive a workspace; it perceives tool outputs in sequence. The IDE is what you use to watch the agent and steer it. For the agent, the IDE is a dashboard, not a workshop.

This sounds pedantic until you notice that almost every AI agent rollout in 2025–26 has been priced, distributed, and measured as if the agent were a smarter IDE. Per seat. Per developer. Per hour saved on autocomplete. That framing caps the gains at autocomplete-grade numbers — single-digit percentages on individual coding tasks. The 3–5x leaders were promised lives nowhere near that ceiling, because reaching it requires using the agent for what it actually is.

And the per-seat framing has a second cost that gets worse at scale. Each developer hands the agent only their own slice — the ticket they got assigned, the function they’re editing, the bug they’re chasing. The agent never sees the full system or the goal the organization is trying to reach. It works for the individual user, not for the system the organization is building. Bigger team, smaller per-developer slice, narrower agent view. Compute gets wasted rebuilding partial context, over and over. Implementations contradict each other across teams. Errors the agent could have caught with broader visibility slip through. The fix isn’t a better per-seat tool — it’s changing what the agent is being asked to be.

What the agent actually is

A coding agent takes on roles in the development process. Not slots — roles. Analyst, architect, implementer, reviewer, tester. Properly directed, one agent — or a coordinated set of them — can carry whole pieces of work from intent to merged code. The unit of agent value is the role, not the keystroke.

This is why “license per developer” misses. You’re not equipping a developer with a faster keyboard. You’re putting a whole team’s worth of capacity — junior, mid, and senior — inside a tool, and then asking your existing process to make use of it.

Which brings us to the actual problem.

Your organization is already an orchestration system

Modern engineering organizations are orchestration machines. Sprints, story points, work-breakdown structures, ticket assignment, standups, code-review queues, performance reviews — every one of these is scaffolding designed to coordinate, dispatch, and measure human labor. The humans are the orchestrated; managers and processes are the orchestrators.

When you drop an agent into this machine, you put it into a human-shaped slot: ticket-assigned, sprint-committed, standup-reported, reviewed at human cadence, evaluated against specs written for humans. The agent’s real strengths — iterating in under an hour, switching between roles, loading new context instantly — get slowed down to match the system around it.

Here’s what makes this hard to see: the developer-level gain is real. Tasks that used to take hours or days finish in minutes. Every pilot shows it. But the work then enters the same review queue, the same sprint cadence, the same chain of human handovers. So tasks finish in minutes and sit for days, waiting for the next human to pick them up. The gain shows up on the developer’s screen and disappears at the system layer above it.

The wait isn’t free either — context fades, goals drift, motivation slips. The developer who finished in twenty minutes spends the next two days waiting and re-explaining. Leaders see the local speedup, point at it as evidence the rollout is working, and miss that the system around it is absorbing the entire gain.

The result is the failure loop. The org didn’t fail at AI adoption; it ran exactly the system it was built to run — one that gets the most out of humans, and can’t get much out of agents. Switching tools doesn’t change that. Nothing about the tool is the bottleneck.

The two systems don’t share a shape — and they don’t fail the same way:

flowchart TB
    subgraph H["Human orchestration"]
        direction TB
        H_PM["Product manager"] ==> H_M["Manager + architect<br/>(conductor)"]
        H_M ==> H_TL["Tech lead"]
        H_TL ==> H_E1["Engineer A"]
        H_TL ==> H_E2["Engineer B"]
        H_E1 ==> H_QA["QA"]
        H_E2 ==> H_QA
        H_QA ==> H_TW["Tech writer"]
    end
    subgraph A["Agent orchestration"]
        direction TB
        A_PM["Product manager"] ==> A_C["Architect + lead engineer<br/>(conductor)"]
        A_C ==> A_M1["Manager agent"]
        A_C ==> A_M2["Manager agent"]
        A_M1 --> A_R1["Implementer agent"]
        A_M1 --> A_R2["Test agent"]
        A_M2 --> A_R3["Doc agent"]
        A_M2 --> A_R4["Reviewer agent"]
    end

Thick arrows mark context-handoff boundaries — places where one party has to re-explain or re-derive what the previous party intended. Thin arrows mark intra-agent flow, where context passes through without re-explanation.

In human orchestration, every arrow is thick. Every layer is a context handoff between two humans, each of which interprets the prior context through their own background, incentives, and bandwidth. Drift compounds. By the time intent reaches the engineer writing the code, the original requirement has been re-expressed three or four times, and each re-expression has shaved off some fidelity.

In agent orchestration, only the top is thick. PM to conductor and conductor to manager-agents — the agents that break down work and dispatch it to specialists — are the fragile handoffs. Both are human-to-something. Below that boundary, manager-agents pass scoped context to specialized agents directly; context flows agent-to-agent without re-explanation. That’s the structural difference: not parallelism, not speed — most of the layers where context goes to die have been eliminated. Drop an agent into a human-shaped slot and you’ve put it back inside the same chain of context loss you were trying to escape.

Two paths, neither easy

What does the answer look like? It depends on where you’re starting from.

Greenfield startups can build agent-first. A small team plus a senior engineer acting as conductor can move dramatically faster than a comparable human-only team. The conductor holds system design, decomposes intent into clear, scoped context, dispatches agents into roles, and integrates outputs. There’s no legacy process to fight. This is where the most impressive AI-native productivity stories are coming from, and it’s not because those teams have better tools.

Established organizations face a structurally harder problem. The whole orchestration apparatus — sprints, ticket flow, hiring ladders, performance reviews, budget categories — is built around humans. Rebuilding workflows to be agent-shaped cascades into hierarchy and role redefinition. What does a mid-level engineer’s career path look like when the people writing code are agents, and the human role is conductor? How do you do performance reviews of a conductor whose output is “the agents shipped this”? How do you categorize spend that’s substituting for headcount but sitting in the tools line item?

Most CTOs and VPs of Engineering don’t have unilateral authority to drive that kind of redesign. It needs CEO and board alignment. Which is exactly why “buy licenses for everyone” is so seductive — it’s the only path that fits inside one leader’s signoff. It’s not laziness; it’s the path of least political resistance. Real value requires real organizational change, which requires real political capital.

I’m proposing this model rather than reporting a working case study at scale. I’ve watched the failure pattern firsthand; I haven’t seen the success pattern at scale yet. What follows is what I think the answer has to look like, and why.

Three pillars that have to change together

For a pilot to actually work, three things change at once. Pick any two and you’re rebuilding the failure mode you were trying to escape.

The operating question for the redesign is the same across all three: for every existing process, ceremony, and role — sprint planning, standups, ticket assignment, review queues, perf cycles — ask why does this exist, and how does it help an agent do its job well? If the honest answer is “it doesn’t — it exists to coordinate humans,” that’s a redesign target. A useful side effect: teams that ask this question stop treating agents as tools and start treating them as collaborators. That shift alone materially changes how the humans show up to the work, and the human side of the output gets better too.

1. Workflow redesign. Pick one workflow — one product area, one outcome stream — and rebuild it agent-shaped. Senior engineer as conductor. Strip out the sprint ceremony for that workflow. The conductor decomposes intent into clear, scoped context, dispatches agents into roles, integrates and reviews their outputs.

What that actually looks like in a session, end to end:

Intent arrives: “Add rate limiting to the public webhook endpoint.” Conductor scopes context: current handler path, existing middleware chain, the Redis instance already in use, the service-level objective (SLO) this protects, the failure mode on rejection (429 vs. queue), the relevant architecture decision record (ADR) on idempotency. Agents dispatched into roles: one drafts the implementation against that context; a second writes the contract tests against the SLO; a third updates the runbook and the public API doc. Each runs in parallel against the same scoped context. Conductor integrates and reviews: checks the diff against the SLO intent, resolves any contradictions between the three outputs, merges.

The conductor never typed the implementation. They did the work that actually mattered — turning an unclear request into a context tight enough that three agents working in parallel produced consistent output. That translation is the job.

2. The visibility rule. Track work from agent artifacts — commits, PRs, runs, completion logs, defect data, cycle time — not from the conductor’s standup self-report. The conductor designs and integrates; they are not the dashboard, and they are not the unit of throughput.

There’s a structural reason for this rule: the conductor’s most important skill is context management — turning unclear requirements into clear, well-scoped instructions an agent can act on. Management cannot judge the context (no technical depth at scale, no time to review prompts and specs). Management can only judge outcomes. Visibility from agent artifacts isn’t a stylistic preference. It’s the only signal management is actually in a position to read.

3. System state that speaks for itself. Bad agent inputs guarantee bad agent outputs. If your code is opaque, your contracts implicit, your tests sparse, your docs stale — agents will produce confusion. Today’s documentation is created by humans for humans, narrative and gap-tolerant, perpetually losing to deadline pressure. This is why documentation has to be treated as an architecture practice, not a deliverable bolted on at the end.

The third pillar is system state that agents author, agents maintain, and machines can verify: schemas, ADRs in rigid templates, runbooks, tests-as-specs, code-grounded references that update on every PR. The conductor defines the shape; agents do the labor; humans review at gates. The agents that do the work also maintain the context the next agents will use.

Caveat: docs are a derivative of system state that agents can read, not a substitute. If the underlying code and contracts are confused, agent-authored docs about them will be too.

The three pillars are linked. Visibility from agent artifacts forces better system state, because human narration is no longer the backstop. Good system state is what makes agent context good enough to produce real results. Workflow redesign is what gives the conductor room to do the context-management work in the first place. The license-distribution model never closes any of these loops.

The pushback you’re going to hear

“But Copilot/Cursor are giving us measurable IC gains right now.” Yes — and those gains are real. They’re also the ceiling of the IDE-framing: single-digit percentages on individual coding tasks. That’s the autocomplete-grade number. The 3–5x lives above that ceiling, and reaching it requires the workflow + visibility + system-state shift. You can keep the autocomplete gains. Just don’t confuse them with the gains you were promised.

“We tried agents and they produced garbage.” Garbage in, garbage out. Agent quality is bounded by input quality — your code, your docs, your contracts, your tests. If that lives in tribal knowledge instead of in the system, no tool will fix it. That’s not the agent’s failure; it’s your documentation debt finally getting priced.

“We don’t have senior talent for the conductor model.” Your senior engineers already have the skill that matters most — the judgment to turn unclear requirements into precise context. The conductor model just changes where they apply it. You’re not hunting for new talent. You’re stopping the waste of the talent you already have — talent that today gets spent in scattered fragments across reviews, design discussions, and fire-fighting.

The forecast

You may be right that you can’t restructure your organization just for AI. That’s exactly why most established orgs won’t — and exactly why the few that do, plus the startups built agent-first from day one, will pull dramatically ahead over the next 3–5 years.

The competitive gap won’t be about who has the best AI tools. It will be about who reorganized to use them. License-distribution orgs will pilot, fail to scale, declare AI adoption “complete,” and underperform — all while spending more.

What to do Monday

Stop rolling out org-wide. Pick one workflow — one outcome stream, one product area — and rebuild it agent-shaped. Identify a senior engineer to act as conductor. Redesign visibility for that workflow: status from agent artifacts, not standup self-reports. Invest in agent-readable system state — schemas, ADRs, tests-as-specs — for the parts of the system that workflow touches. Run it for a quarter. Measure outcomes (shipped value), not activity (tickets closed). Then decide what to do org-wide based on what you actually learned.

And one accounting move that costs nothing and changes every conversation:

Move your AI tooling budget out of the “tools” line item and into the “labor capacity” line item.

That single reclassification forces every conversation about AI spend to be a conversation about org design — which is the conversation you should have been having all along.

Instead, I watched it spend $1.42 and nearly 19 minutes thrashing through 103 tool calls — trying npm before Node.js was installed, asking me for help, attempting apt-get without root access, downloading the wrong Node.js version, writing all tests in vitest then rewriting them in node:test, and cycling through 33 tool calls just to get tests passing. I had to intervene twice to keep it on track.

Then I profiled that session. I could see exactly where every dollar went: 46% of the total cost ($0.66) was triggered by a single user correction — “why don’t you install nodejs.” That one prompt cascaded into 66 LLM calls covering environment setup, code generation, test framework migration, and debugging — all in one massive interaction where context grew from 49K to 97K tokens.

Armed with that data, I applied three targeted fixes. The next run of the same task, same model, clean directory: $0.58, 6.6 minutes, 44 tool calls, zero user intervention.

This isn’t about switching to a better model. Both runs used Claude Haiku (the profiler itself ran on Opus). Even with well-written prompts and good project context, there is always room to optimize — especially when working with costly models or doing repetitive, similar tasks.

Profiling builds your understanding of how agents actually work from the inside, and that understanding compounds. Iterative build tools can get you to a working system, but they burn tokens getting there. Profiling shows you where those tokens go, so you can engineer the waste out before scaling up.

The Observability Gap

When you use an AI coding agent, you see two things: the prompt you typed and the output you got back. Between those two points, the agent might have made 107 API requests, spawned 3 subagents, failed 16 Bash commands, switched test frameworks mid-stream, and burned through millions of tokens — and you’d never know unless you were watching the terminal scroll by.

This is the observability gap. In traditional software, we solved this decades ago with APM tools, distributed tracing, and structured logging. We don’t ship services without Datadog or Grafana dashboards telling us where latency lives and where errors cluster.

AI coding agents have no equivalent. You get a cost number at the end of the session and a vague sense of whether it went well. If the session was expensive, you don’t know why. If the agent struggled, you can’t see where. And critically, you can’t systematically improve the next run because you have no data to act on.

That’s what I set out to fix.

The Setup: Telemetry for Claude Code

Claude Code supports OpenTelemetry — the same observability standard used across the software industry. When enabled, it exports traces, metrics, and logs covering every aspect of a session: API requests, tool calls (with command details and file paths), token usage by type, cost, duration, user prompts, and permission decisions.

The core requirement is a ClickHouse database — the same database Anthropic uses internally for their own Claude observability — with any OTEL-compatible collector that can write to it. The profiler queries ClickHouse directly. For this setup, I used ClickStack (ClickHouse + OTEL collector + HyperDX dashboard bundled together) for ease of setup, and ran everything in Docker containers to ensure clean, reproducible environments:

graph LR
    subgraph Docker Network
        CS["ClickStack<br/>(ClickHouse + OTEL Collector<br/>+ HyperDX Dashboard)"]
        B["Baseline Container<br/>(Claude Code + Haiku)"]
        P["Profiler Container<br/>(Claude Code + Opus<br/>+ Profiler Plugin)"]
        O["Optimized Container<br/>(Claude Code + Haiku)"]
    end

    B -->|OTEL telemetry| CS
    O -->|OTEL telemetry| CS
    P -->|queries ClickHouse| CS

    style CS fill:#f59e0b,stroke:#d97706,color:#000
    style B fill:#818cf8,stroke:#6366f1,color:#fff
    style P fill:#6366f1,stroke:#4f46e5,color:#fff
    style O fill:#10b981,stroke:#059669,color:#fff

Baseline and Optimized containers each run Claude Code with Haiku and export OTEL telemetry to ClickStack. The Profiler container runs Claude Code with Opus and the profiler plugin; instead of exporting telemetry, it queries ClickHouse directly to analyze the baseline session and produce optimization artifacts. Each container mounts a shared demo/ directory that carries configuration files forward across phases — but application code is ephemeral, so each run builds from scratch.

The key environment variables that unlock detailed telemetry:

CLAUDE_CODE_ENABLE_TELEMETRY=1
OTEL_LOG_TOOL_DETAILS=1
OTEL_LOG_USER_PROMPTS=1
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1

With these enabled, every tool call, every prompt, every permission decision, and every token is captured in queryable ClickHouse tables: otel_traces, otel_logs, and otel_metrics_sum.

Note: All tools used in this setup (monitoring stack, profiler plugin, container image) are linked at the end of this article.

The Baseline: Watching an Agent Struggle

The baseline prompt pointed to a requirements.md file that was deliberately lean — requirements only, no tech stack, no environment hints:

Build a task manager REST API in the /demo-app/ directory. It should support creating, reading, updating, and deleting tasks. Each task should have a title, description, due date, priority level, and category. Include a test suite and verify all features work by running the tests.

Here’s what the agent actually did, reconstructed from telemetry and the session recording:

Phase 1 — Discovery and planning false starts. The agent spawned 3 subagents sequentially: one to explore the directory (which didn’t exist yet — wasted), and two Plan subagents because the first plan proposed a non-Node.js stack, which I rejected. Two full planning cycles before a single line of code was written.

Phase 2 — The environment struggle. This was the most expensive phase. The agent tried npm init — failed, no Node.js. Tried python3 — not found. Asked me what to do via AskUserQuestion. I said “why don’t you install nodejs.” It tried apt-get install nodejs — permission denied (not root). Tried the NodeSource setup script — failed. Downloaded Node.js v20 as a tarball — wrong version. Downloaded v22 — finally worked. 14 Bash calls just to get a runtime installed.

Phase 3 — Code generation. Created 16 source files one at a time — db.js, config, schemas, middleware, services, controllers, routes, app.js, server.js, plus 5 test files and a helper. Each file was a separate Write call, each requiring its own LLM round. The profiler later calculated this pattern caused ~840K tokens of redundant cache reads.

Phase 4 — The test-fix death spiral. Ran tests — failures. Node v20 didn’t support the test syntax. Switched to v22. Still failed. Reinstalled node_modules. Switched from vitest to Node’s built-in test runner. Rewrote all 5 test files. Still had failures. Edited service code, middleware, and schemas. Ran the server manually with curl to debug. Wrote a standalone Zod test script to isolate a validation issue. Eventually reached 29 tests passing after 33 tool calls in this cycle alone.

Phase 5 — Verification and polish. A third user prompt was needed — “Anybody should be able to setup and use the project after going through README.MD” — because the agent hadn’t created one. More tool calls, more time, more cost.

The final tally: $1.42, 103 tool calls, 107 API requests, 4 user prompts (2 of them corrective interventions).

The Profiler: Cracking Open the Black Box

This is where the observability payoff kicks in. I ran the claude-session-profiler plugin — it connected to ClickHouse, queried the baseline session’s telemetry, and produced a detailed analysis.

One of the most revealing outputs was the session flow diagram — reconstructed entirely from OTEL traces, not from source code or documentation. This is the agent’s real internal behavior as observed through telemetry:

sequenceDiagram
    participant User
    participant Agent
    participant Tools
    participant Subagent

    Note over User,Tools: Prompt 1 — "Implement requirements.md" ($0.54, 8.5 min)
    User ->> Agent: Can you implement the requirement documented in @requirements.md
    Agent ->> Subagent: Explore /demo-app (directory doesn't exist — wasted)
    Subagent -->> Agent: Nothing found
    Agent ->> Subagent: Plan #1 — design REST API
    Subagent -->> Agent: Plan proposed (non-Node.js stack)
    Note over Agent,Tools: ❌ User rejects plan
    Agent ->> Subagent: Plan #2 — design Node.js REST API
    Subagent -->> Agent: Plan accepted
    Agent ->> Tools: Bash x7 (mkdir, npm init — 4 failures, no Node.js)
    Agent ->> Tools: AskUserQuestion — "Node.js not available"

    Note over User,Tools: Prompt 2 — "why don't you install nodejs" ($0.66, 7.6 min)
    User ->> Agent: why don't you install nodejs
    Agent ->> Tools: Bash (NodeSource setup — failed)
    Agent ->> Tools: Bash (curl node v20 .tar.xz — wrong format)
    Agent ->> Tools: Bash (curl node v20 .tar.gz — success)
    Agent ->> Tools: Bash (npm install — 18.5s)
    Agent ->> Tools: Write x14 (all source files, one per LLM round)
    Agent ->> Tools: Bash (npm test — failed, Node v20 too old)
    Agent ->> Tools: Bash (install Node v22)
    Agent ->> Tools: Bash (npm test — failed, vitest incompatible)
    Note over Agent,Tools: ❌ Switches framework: vitest → node:test
    Agent ->> Tools: Write x5 (rewrite ALL test files)
    Agent ->> Tools: Bash (npm test — still failing) x3
    Agent ->> Tools: Edit x3 (fix service, middleware, schema bugs)
    Agent ->> Tools: Bash (npm test — 29 tests pass) ✓

    Note over User,Tools: Prompt 3 — "Setup via README.MD" ($0.21, 2.3 min)
    User ->> Agent: Anybody should be able to setup and use the project after going through README.MD
    Agent ->> Tools: Read + Edit README x3

    Note over User,Tools: Prompt 4 — "Thanks." ($0.01)
    User ->> Agent: Thanks.

You don’t need to read source code to understand how an AI agent works internally. Point the profiler at any session and get a diagram like this — the agent’s real execution flow for your specific task. This one shows three subagents spawned sequentially, a rejected plan, 14 files written one at a time, a full test framework migration mid-stream, and a debug spiral — all triggered by a five-word user correction.

The profiler’s per-prompt cost breakdown quantifies the damage:

Prompt 2 — a five-word user correction — consumed 46% of the entire session cost. It triggered 66 LLM calls because the agent interpreted it as a green light to do everything: install Node.js, write all code, set up tests, debug failures, and verify — all within a single interaction where context grew from 49K to 97K tokens.

Beyond the per-prompt breakdown, the profiler surfaced specific patterns:

33% Bash failure rate. 16 out of 48 Bash calls failed — 6 from environment probing (trying commands that didn’t exist), 2 from wrong Node.js archive format, 6 from test runner failures, 2 miscellaneous. Each failure added error output to context and triggered at least one additional LLM call to diagnose and retry.

2.7 minutes of permission wait time. The user approved 47 out of 48 Bash calls (one was auto-allowed). At ~3.4 seconds average per approval, that’s 2.7 minutes of a human clicking “Yes” repeatedly for commands that were always going to be approved.

The vitest-to-node:test rewrite. The agent chose vitest as the test framework, then discovered it didn’t work in the container environment. It uninstalled vitest and rewrote all 5 test files using node:test — approximately 12 LLM rounds and ~10K output tokens of completely duplicated work.

Three Targeted Fixes

The profiler didn’t just identify problems — it produced three artifacts that encode the fixes directly into the project. Each targets a specific waste pattern: permission delays, environment and tech stack guessing, and prompt ambiguity.

1. Permission allow rules (settings.local.json)

{
  "permissions": {
    "allow": [
      "Bash(npm *)", "Bash(node *)", "Bash(curl:*)",
      "Bash(mkdir *)", "Bash(ls *)", "Bash(find *)",
      "Bash(cat *)", "Bash(export PATH=*)"
    ]
  }
}

Auto-approves standard development commands. Eliminates ~2.7 minutes of permission prompts per session.

2. CLAUDE.md project context (22 lines)

# Project: demo-app (Task Manager REST API)

## Environment
- Node.js is NOT pre-installed. Download a binary release from
  https://nodejs.org (linux-x64 .tar.gz) to /home/claude/, extract it,
  and add its bin/ directory to PATH before running any node/npm commands.
- No apt-get/sudo access. Do not attempt package manager installs.

## Tech Stack
- Runtime: Node.js (v22+)
- Framework: Express
- Database: better-sqlite3 (SQLite)
- Validation: Zod
- Test runner: Node built-in (node:test + node:assert)
  -- do NOT use vitest, jest, or mocha

## Workflow Guidance
- For greenfield projects, skip Explore subagents
- Batch multiple file writes into a single LLM response

Three lessons encoded: (a) how to install Node.js without probing failures, (b) which tech stack to use without guessing, (c) workflow patterns to avoid the one-file-per-call overhead.

3. Refined requirements.md (from 1 line to structured)

Before:

Build a task manager REST API in the /demo-app/ directory. It should support creating, reading, updating, and deleting tasks. Each task should have a title, description, due date, priority level, and category. Include a test suite and verify all features work by running the tests.

After:

Build a task manager REST API in the /demo-app/ directory.

## Requirements
- CRUD operations for tasks
- Each task has: title, description, due date, priority level, and category
- Include a test suite and verify all features pass

## Implementation
- Node.js (v22+) with Express, better-sqlite3, and Zod for validation
- Use Node's built-in test runner (node:test + node:assert) with supertest
- Node.js is NOT pre-installed -- download the linux-x64 binary from
  nodejs.org to /home/claude/ and add to PATH
- Create a README.md with setup instructions

Every ambiguity that caused thrashing in the baseline is now resolved upfront. The profiler predicted this combination would cut cost roughly in half (~$0.65-0.75) and finish in 8-10 minutes.

The Optimized Run: Same Task, Same Model, Different Result

Clean directory — no pre-existing code. Same model. Same prompt structure. The only differences: the three artifacts above.

The contrast was immediate. One planning cycle instead of two — CLAUDE.md told it to skip Explore for greenfield projects. Node.js installed in one download — though the model chose v24.14.1 instead of the recommended v22, it knew to use a tarball and had the PATH instructions ready. No apt-get attempts, no AskUserQuestion, no user intervention.

Code generation was leaner: 8 source files with a flatter architecture (validators, routes, db, app, server, tests, README) versus the baseline’s 16 files with separate config, schemas, middleware, services, and controllers layers.

The one surprise: npm install failed because better-sqlite3 had no prebuilt binary for Node v24.14.1, and the container lacked compilation tools (no node-gyp, python3, make, or g++). The agent recognized the root cause in one attempt, pivoted to sql.js (a pure JavaScript/WASM SQLite implementation requiring zero native dependencies), created a db-wrapper.js abstraction layer, adapted 5 files, and had all 26 tests passing. The entire test-fix cycle took 15 tool calls — compared to the baseline’s 33.

This is worth noting: the profiler recommended better-sqlite3 based on what the baseline used, but the model’s choice of a newer Node.js version created an incompatibility the profiler couldn’t have predicted. The model handled this gracefully — it diagnosed the failure, chose a pragmatic alternative, and adapted in one focused pass rather than thrashing.

Final output: “I’ve successfully implemented the Task Manager REST API.” Server boots cleanly. All tests pass. README with setup instructions included. Zero user intervention.

The Numbers

The profiler predicted ~$0.65-0.75 cost and 8-10 minutes. Actual: $0.58 and 6.6 minutes. The cost prediction was within range; the time prediction was conservative. This validates the telemetry-based analysis as a useful forecasting tool, not just a post-hoc report.

The tool usage shift tells the structural story:

Fewer Bash calls because the agent wasn’t probing a mystery environment. Fewer Writes because it created 8 files instead of 16. Fewer subagents because it didn’t need to re-plan. Zero user questions because CLAUDE.md answered them before they were asked.

What This Means in Practice

The 60% cost reduction on a $1.42 Haiku session saves $0.84. That’s not going to change anyone’s budget. But the pattern scales — the waste patterns the profiler found (environment probing, framework guessing, one-file-per-call overhead) aren’t specific to this task. They’re the agent’s default behavior when it lacks context, and they repeat across every session until you fix them. A well-crafted CLAUDE.md eliminates entire categories of waste on every subsequent run.

More importantly, the profiling reveals structural inefficiencies that compound with model capability and task complexity. A 33% Bash failure rate on a simple CRUD task means the same failure rate on a multi-service migration — but with 10x more tool calls, the cost of each wasted retry multiplies. The patterns are the same; the stakes are not.

The profiler’s real value isn’t the cost number. It’s the visibility. When you can see that 46% of your cost came from a single corrective prompt, or that 33% of Bash calls failed, or that the agent rewrote all test files because it guessed the wrong framework — you know exactly what to fix. Without that data, you’re optimizing blind.

Closing Thoughts

AI coding agents are powerful, but they’re opaque by default. You interact with a prompt-and-response interface while the agent makes hundreds of internal decisions — tool choices, error recovery strategies, architecture patterns, technology selections — that you never see and can’t influence until something goes wrong.

Telemetry changes that dynamic. With OTEL tracing, every tool call, every token, every permission decision, and every failure is captured and queryable. The profiler plugin turns that raw data into actionable artifacts — CLAUDE.md guidance, permission rules, refined prompts — that encode lessons learned into the project itself.

This is the same shift that happened in backend engineering when we went from “check the logs” to structured observability. Once you can see what’s happening inside the system, you stop guessing and start engineering.

Personal Insight: Building the monitoring stack and profiler plugin started as curiosity — I wanted to understand what Claude Code was actually doing during those long sessions where the terminal scrolled faster than I could read.

The biggest surprise wasn’t the waste itself — it was how predictable it is. The same failure modes show up in nearly every session I’ve profiled since: probing for tools that aren’t installed, guessing tech choices that could have been specified, writing files one at a time when they could be batched. Once you see that, CLAUDE.md stops being a nice-to-have and becomes the single highest-leverage artifact in your project.

The tools referenced in this article:

• claude-code-monitoring — ClickStack docker-compose + HyperDX dashboard for Claude Code telemetry
• claude-session-profiler — Claude Code plugin that analyzes session telemetry and produces optimization artifacts
• claude-code-container — Docker container for running Claude Code in isolated, reproducible environments

But what happens when the work spans multiple machines? When you want a manager agent on one host coordinating developer agents on others — each running their own internal agent teams, writing to shared workspaces, negotiating API contracts in real time?

That’s the gap. And I used another experimental Claude Code capability — channels — to fill it.

The Missing Step

Claude Code’s agent capabilities today have a clear hierarchy:

Sub-agents — specialized workers spawned by the main agent with their own context window, custom tools, and system prompts. They execute a task and return a summary to the caller. But they can’t spawn other sub-agents (no nesting), and they can’t talk to each other — they only report back to whoever spawned them.

Agent teams (experimental) — a step further. Multiple Claude Code sessions coordinate through direct messaging and a shared task list. Teammates can talk to each other, not just back to the lead. But the entire team still runs on one machine, in one terminal session.

Distributed agents — multiple Claude Code instances on different machines, each potentially running its own internal sub-agents or agent teams, collaborating across the network in real time. This doesn’t exist out of the box.

The piece that makes it possible is channels — an experimental research preview that lets external events push into a running Claude Code session via MCP servers. Channels were designed for things like chat platforms (Telegram, Discord), but the underlying mechanism is general: any MCP server can send channel notifications into Claude’s conversation. That’s the hook I built on.

The jump from “agent teams on one machine” to “distributed agent teams across machines” is the same jump that software organizations made decades ago — and it’s worth looking at that parallel.

The Model We Already Know

Distributed human teams are not a new idea. Every engineering organization of meaningful size runs some version of this:

graph LR
    AM["🏗️ Architect / Manager<br/>Coordination & Vision"]

    AM <-->|defines tasks & reviews| T1
    AM <-->|defines tasks & reviews| T2
    AM <-->|defines tasks & reviews| T3

    subgraph T1["Team 1 — Frontend"]
        direction TB
        T1L["Tech Lead"]
        T1D1["Developer"]
        T1D2["Developer"]
        T1L <--> T1D1
        T1L <--> T1D2
        T1D1 <--> T1D2
    end

    subgraph T2["Team 2 — Backend API"]
        direction TB
        T2L["Tech Lead"]
        T2D1["Developer"]
        T2D2["Developer"]
        T2L <--> T2D1
        T2L <--> T2D2
        T2D1 <--> T2D2
    end

    subgraph T3["Team 3 — Infrastructure"]
        direction TB
        T3L["Tech Lead"]
        T3D1["Developer"]
        T3D2["Developer"]
        T3L <--> T3D1
        T3L <--> T3D2
        T3D1 <--> T3D2
    end

    T1 <-->|API contracts| T2
    T2 <-->|deployment| T3
    T3 <-->|hosting & CI/CD| T1

    style AM fill:#6366f1,stroke:#4f46e5,color:#fff
    style T1L fill:#6366f1,stroke:#4f46e5,color:#fff
    style T2L fill:#6366f1,stroke:#4f46e5,color:#fff
    style T3L fill:#6366f1,stroke:#4f46e5,color:#fff
    style T1D1 fill:#818cf8,stroke:#6366f1,color:#fff
    style T1D2 fill:#818cf8,stroke:#6366f1,color:#fff
    style T2D1 fill:#818cf8,stroke:#6366f1,color:#fff
    style T2D2 fill:#818cf8,stroke:#6366f1,color:#fff
    style T3D1 fill:#818cf8,stroke:#6366f1,color:#fff
    style T3D2 fill:#818cf8,stroke:#6366f1,color:#fff

A senior architect or manager holds the vision and breaks work into components. Team leads manage their teams, each responsible for a service or layer. Developers within each team collaborate closely, and teams coordinate with each other through well-defined contracts — API specs, shared schemas, deployment interfaces.

This model works. It scales. It’s how we build complex systems with humans.

Now look at what a single Claude Code instance already does internally: a main agent (the team lead) spawning sub-agents (the developers), each with a defined role and scoped context. With agent teams, teammates even message each other directly — just like developers within a team collaborating on interfaces.

The structure is the same. Each Claude Code instance is already a team. The only thing missing was the communication layer between teams — the equivalent of cross-team API contracts and coordination meetings. That’s what channels and claude-code-chat provide. Connect multiple Claude Code instances via a broker, and each instance becomes a node in the distributed team model. Internally, each runs its own agent team. Externally, they coordinate with other instances through messages.

What I Built

claude-code-chat — a lightweight bridge that lets Claude Code instances discover each other and exchange messages in real time, across machines.

It has two components:

A WebSocket broker (broker.ts, ~80 lines) — a central message relay. Agents connect, register a name, and send messages — either broadcast to everyone or directed to a specific recipient. The broker tracks who’s online and notifies everyone when agents join or leave. No persistent storage, no authentication, no external dependencies. Just Bun’s built-in WebSocket server.

An MCP channel server (client.ts, ~110 lines) — runs as an MCP server alongside each Claude Code instance. It connects to the broker and exposes two tools to Claude: send_message (with an optional to for directed messages) and list_participants. When messages arrive from the broker, they’re delivered to Claude as MCP channel notifications — appearing inline in the conversation as <channel> tags.

That’s it. Two files, ~190 lines of TypeScript, one dependency beyond the MCP SDK.

Important caveat: MCP channels are an experimental research preview in Claude Code. Running this requires the --dangerously-load-development-channels flag. This is not a production-ready feature — it’s an early look at what’s coming. The API may change, and the flag name tells you exactly how Anthropic feels about its stability right now.

Architecture

graph LR
    subgraph Machine_A["Machine A — Manager"]
        CA["Claude Code<br/>(manager)"] <--> MCA["MCP Server<br/>(client.ts)"]
    end

    subgraph Broker["Broker (any host)"]
        B["broker.ts<br/>WebSocket relay"]
    end

    subgraph Machine_B["Machine B — Alice's Team"]
        direction TB
        CB["Claude Code<br/>(alice)"] <--> MCB["MCP Server<br/>(client.ts)"]
        CB -->|spawns| SA1["Sub-agent"]
        CB -->|spawns| SA2["Sub-agent"]
    end

    subgraph Machine_C["Machine C — Bob's Team"]
        direction TB
        CC["Claude Code<br/>(bob)"] <--> MCC["MCP Server<br/>(client.ts)"]
        CC -->|spawns| SB1["Sub-agent"]
        CC -->|spawns| SB2["Sub-agent"]
    end

    MCA <-->|WebSocket| B
    MCB <-->|WebSocket| B
    MCC <-->|WebSocket| B

    style CA fill:#6366f1,stroke:#4f46e5,color:#fff
    style CB fill:#6366f1,stroke:#4f46e5,color:#fff
    style CC fill:#6366f1,stroke:#4f46e5,color:#fff
    style MCA fill:#10b981,stroke:#059669,color:#fff
    style MCB fill:#10b981,stroke:#059669,color:#fff
    style MCC fill:#10b981,stroke:#059669,color:#fff
    style B fill:#f59e0b,stroke:#d97706,color:#000
    style SA1 fill:#818cf8,stroke:#6366f1,color:#fff
    style SA2 fill:#818cf8,stroke:#6366f1,color:#fff
    style SB1 fill:#818cf8,stroke:#6366f1,color:#fff
    style SB2 fill:#818cf8,stroke:#6366f1,color:#fff

Each Claude Code instance runs its own client.ts as an MCP server, connecting to a single broker over WebSocket. But notice the shape of each machine — alice and bob aren’t solo agents. Each can spawn its own sub-agents or run an agent team internally, just like a team lead managing developers. The broker sits between these teams as a pure relay — it doesn’t interpret messages, store history, or make routing decisions beyond “send to this name” or “send to everyone.”

Why a central broker instead of peer-to-peer? Simplicity. Agents don’t need to know each other’s addresses. They connect to one endpoint, register a name, and start talking. The broker handles discovery (list_participants) and routing. Adding a new agent means starting another Claude Code instance pointed at the same broker — no reconfiguration.

How messages reach Claude. When an agent sends a message, it travels: Claude tool call → client.ts → WebSocket → broker → WebSocket → recipient’s client.ts → MCP channel notification → Claude sees it as a <channel> tag in the conversation. The whole round trip happens in milliseconds.

The MCP channel integration is what makes this work naturally. Messages don’t arrive as tool results that Claude has to poll for. They arrive as channel notifications — inline in the conversation, tagged with the sender’s name. Claude reads them the way it reads any other context and decides how to respond. No special handling, no polling loops, no prompt engineering to make the agent “check for messages.”

The Demo: Agents Building an App Together

The repo includes start-collab.sh — a tmux-based launcher that spins up four Docker containers on a shared network: the broker, a manager agent, and two developer agents (alice and bob). Each agent gets a system prompt defining its role. Since agents run with --dangerously-skip-permissions (full tool access), Docker provides the sandbox — each container runs as a non-root user, isolating the agent from the host system.

Here’s what happens when you tell the manager to build a counter app with a backend API and HTML frontend:

Discovery. The manager uses list_participants and sees alice and bob are online.

Manager → alice: Build the backend API for a counter app. Create a /api/count endpoint that supports GET (return current count) and POST (increment and return new count). Store the count in memory. Write the code to /app/workspace/server.ts. Message me when done.

Manager → bob: Build the HTML frontend for a counter app. It should display the current count, have an Increment button, and fetch from /api/count. Write the code to /app/workspace/index.html. Message me when done.

Contract negotiation. Before coding, the developers talk to each other:

alice → bob: I’ll expose GET /api/count returning { count: number } and POST /api/count returning the same shape. The server will run on port 3000. Does that work for your frontend?

bob → alice: Works for me. I’ll fetch from http://localhost:3000/api/count. I’m assuming you’ll handle CORS — can you add Access-Control-Allow-Origin: *?

alice → bob: Done, I’ll include CORS headers.

Parallel building. Both agents write code simultaneously to the shared /app/workspace directory. Alice creates server.ts, Bob creates index.html. They work independently because they agreed on the contract upfront.

Completion and verification. Each developer messages the manager when done. The manager reviews the files in the workspace, runs the server, opens the frontend, tests the increment flow, and either approves or sends issues back for fixing.

This is the same workflow a human team follows — task breakdown, contract agreement, parallel execution, integration testing. The difference is it happens in minutes instead of days, and the “team” is three Claude Code instances coordinating over WebSocket. You can watch a recording of this collaboration at the end of the article.

What I Learned

MCP channels change the interaction model fundamentally. Without channels, you’d need agents to poll for messages via tool calls — creating awkward loops and timing issues. Channels make messages arrive naturally as part of the conversation flow. Claude just sees them and responds. This is the difference between “chat” and “polling an inbox.”

Broadcast + directed messaging is the right default. Early on, I considered only directed messages. But broadcast is essential for the organic collaboration you see in real teams — when alice and bob negotiate an API contract, the manager overhears and stays in context. Directed messages handle the cases where you need private coordination.

Ephemeral is fine for v1. No message history means late-joining agents miss earlier context. In practice, this hasn’t been a problem for the demo scenarios — agents establish context quickly through list_participants and direct questions. Persistent history is a natural v2 addition (in-memory buffer or SQLite on the broker), but it’s not blocking useful work today.

The 190-line constraint is a feature. The entire system is small enough that any developer can read and understand it in minutes. There’s no framework to learn, no configuration to tune, no infrastructure to deploy beyond a single process. This matters for a proof-of-concept that’s demonstrating a new pattern.

Limitations

Channels are experimental. The --dangerously-load-development-channels flag exists because MCP channels are a research preview. The API may change. Build on this with that understanding.

No authentication. The broker accepts any connection. This is fine for a trusted LAN or Docker network, not for anything exposed to the internet.

No persistence. Messages are fire-and-forget. If an agent is offline when a message is sent, it’s lost.

Single broker. No clustering, no failover. The broker is a single process. For a proof-of-concept, this is acceptable. For production use, you’d want redundancy.

Quick Start

You need Docker, tmux, and a Claude Code OAuth token. Clone the repo, export your token, run ./start-collab.sh, and give the manager a task in its tmux pane. The full setup instructions are in the README — it’s designed to get you running in under five minutes.

Closing Thoughts

What started as a question — “can Claude Code instances talk to each other?” — turned into a working proof-of-concept for distributed AI teams. The architecture mirrors what we’ve been doing with human teams for decades: a coordinator breaking down work, developers negotiating interfaces, parallel execution against shared contracts.

The interesting part isn’t the WebSocket broker — that’s deliberately trivial. The interesting part is that Claude Code agents, given nothing more than two messaging tools and a system prompt, naturally fall into the same coordination patterns that human teams use. They discover each other, negotiate contracts, divide work, build in parallel, and report back. Nobody programmed that workflow — it emerges from the combination of capable agents and a communication channel.

The building blocks are already here. Sub-agents give each Claude Code instance an internal team of specialized workers. Agent teams add peer-to-peer coordination within a single machine. Channels — the experimental capability I built on — provide the push-based communication layer that makes cross-machine messaging possible. Stack these together, and the distributed human team model from the diagram above isn’t a metaphor — it’s an architecture you can run today.

Channels are experimental. Agent teams are experimental. The pieces are early and rough. But they exist, they work, and the direction is clear. This project is a proof-of-concept for where AI-driven development is heading.

The code is open source. It’s ~190 lines. Read it, run it, break it, extend it.

Personal Insight: I’ve written before about how AI agents mirror organizational structures — replacing the coordination overhead of large teams with scoped context and automated orchestration. Building claude-code-chat made that abstract idea concrete. Each Claude Code instance already behaves like a team — a lead coordinating specialized workers. Channels gave me the bridge to connect those teams across machines. When I watched three instances negotiate an API contract without any human intervention, it stopped being a prediction about the future and became something I could point at and say: “this is how it works now.”

See It In Action

Watch the collaboration session as scripted in the project README — three Claude Code instances coordinating a full-stack feature in real-time:

Understanding this internal flow isn’t just academic curiosity. It explains real behaviors you observe every day: why Claude asks for permission sometimes but not others, why subagents feel “isolated,” why skills behave differently from regular tools, and why Claude sometimes self-corrects right before returning a response.

Disclaimer: Claude Code is closed source. What follows is my mental model based on extensive use of Claude Code, its publicly available documentation, changelog, and my understanding of agentic frameworks like LangGraph. I am not claiming this is exactly how it works internally — but this model has consistently explained the behaviors I observe.

What the Docs Tell You (and What They Don’t)

Before diving into the internals, let’s see what’s already out there.

The official How Claude Code works page describes the agentic loop as three blended phases: gather context, take action, verify results. It lists tool categories — file operations, search, execution, web, and code intelligence. It explains that Claude “chooses which tools to use based on your prompt.”

All true. But none of this explains the mechanics inside the loop.

How does the agent decide whether it’s done or needs to keep going? How are permissions checked — and what happens when they’re denied? What’s the architectural difference between a skill, a subagent, and a regular tool? Why do background subagents sometimes fail on permissions while foreground ones don’t?

These are the questions this article answers.

This article focuses on the flow mechanics — the how and why of the loop. For details on individual tools, hooks, permissions, and skills, the official docs are the right place.

The Main Agent Loop

Here’s the flow that executes every time you send a prompt to Claude Code:

%%{init: {'flowchart': {'defaultRenderer': 'elk'}}}%%
flowchart BT
subagent_loop["See subagent loop"]
subgraph cli["ClaudeCode Cli MainAgent - session"]
  session
  session_init
  mainagent
  llm
  permission_check{"permission_check"}
  tools["Built-in + MCP Tools"]
  decide{decide}
  tool_use{tool_use}
  skilltool
  tasktool
  stop_hook{"stop_hook"}
end
user --> |1.prompt|session_init
session_init --> |2.add memoryfile,claude.md,skill metadata| session
session_init --> |3.user prompt|mainagent
session --> |4.read context into system prompt| mainagent
mainagent --> |5.system+user prompt|llm
llm -.-> |6.response|mainagent
mainagent --> |7.add llm response| session
mainagent --> |8.|tool_use
tool_use --> |yes| permission_check
tool_use --> |no - done| stop_hook
stop_hook --> |approve| user
stop_hook --> |block| mainagent
permission_check --> |allow|decide
permission_check --> |deny| mainagent
permission_check --> |ask| user
decide --> |subagent call needed|tasktool
decide --> |skill needed|skilltool
decide --> |other tool call| tools
skilltool -.-> |provide skill body|mainagent
tools -.-> |other tool response|mainagent
tasktool --> |request prompt|subagent_loop
subagent_loop -.-> |sync: direct result / async: via TaskOutput| mainagent

Let’s walk through it step by step.

Step 1-2: Session Initialization. When you start a session, session_init loads context into the session: your memory files (auto-memory from MEMORY.md), CLAUDE.md files (project instructions), and skill metadata (descriptions of available skills, not their full content). This is the foundation the agent works with.

Step 3-4: Prompt Assembly. Your user prompt is passed to the main agent, which reads the session context to assemble the full system prompt. This is why CLAUDE.md instructions and memory are available from the very first interaction.

Step 5-6: LLM Call. The assembled system + user prompt is sent to the Claude model. The model responds — possibly with text, possibly with tool_use blocks, possibly both.

Step 7-8: Response Processing & tool_use Check. The LLM response is added to the session. Then comes a critical gate: does the response contain tool_use blocks?

• No tool_use → The agent thinks it’s done. Flow goes to the stop hook.
• Yes tool_use → Flow continues to permission check.

Stop Hook. This fires before the response is returned to the user. It can approve (let the response through) or block (force the agent to loop again). This is why Claude sometimes self-corrects at the very end of a task — the stop hook evaluated the response and decided it wasn’t ready.

Permission Check. A three-way gate:

• Allow → Tool is permitted, flow continues to decide
• Deny → Tool is blocked, agent loops back (often tries a different approach)
• Ask → User is prompted for approval. If approved, flow continues to decide. If denied, the agent loops back just like an automatic deny.

Decide. After permission is granted, the agent routes to the correct handler:

• Skill tool → Returns the skill’s full body content back to the agent (context injection, not execution)
• Task tool → Spawns an isolated subagent (see below)
• Regular tools → Executes built-in or MCP tools and returns the result

The tool response flows back to the main agent, and the loop continues until the LLM produces a response with no tool_use blocks.

Key Architectural Insights

Four patterns in this flow that matter for power users:

Permission check happens BEFORE routing. All tools — skills, subagents, regular tools — go through the same permission pipeline before the decide step. This is why your permission rules in .claude/settings.json work uniformly. There’s no special permission path for skills vs regular tools.

Stop hook is a quality gate, not just a passthrough. When the LLM produces a text-only response (no tool_use), it doesn’t go directly to you. The stop hook evaluates first. If it blocks, the agent is forced to continue working. This explains the behavior where Claude appears to “change its mind” right at the end — it’s the stop hook rejecting a premature completion.

Skills are lazy-loaded context, not tools. Skill metadata (short descriptions) is loaded at session start — this is how Claude knows what skills are available. But the full skill body is only injected when the skill is actually invoked via the skill tool. This is progressive disclosure — it keeps the context window lean until a skill is needed. When a skill fires, it doesn’t “execute” — it returns its body content to the agent, enriching its context for the next LLM call.

The decide routing is the orchestration layer. This is what makes Claude Code more than a chat-with-tools. The agent distinguishes between three fundamentally different operations: injecting knowledge (skill), delegating work (subagent), and taking action (regular tool). Each has different implications for context, isolation, and control flow.

The Subagent Loop

When the main agent needs to delegate work, the task tool spawns a subagent — an isolated session with its own agentic loop:

%%{init: {'flowchart': {'defaultRenderer': 'elk'}}}%%
flowchart TD
mainagent_loop["Main Agent (caller)"]
user
subgraph cli["ClaudeCode Cli Subagent - isolated session"]
  session
  session_init
  subagent
  llm
  permission_check{"permission_check"}
  tools["Built-in + MCP Tools"]
  decide{decide}
  skilltool
  tool_use{tool_use}
  stop_hook{"stop_hook"}
end
mainagent_loop --> |1.prompt|session_init
session_init --> |2.add claude.md,skill metadata| session
session_init --> |3.prompt|subagent
session --> |4.read context into system prompt| subagent
subagent --> |5.system+user prompt|llm
llm -.-> |6.response|subagent
subagent --> |7.add llm response| session
subagent --> |8.|tool_use
tool_use --> |yes| permission_check
tool_use --> |no - done| stop_hook
stop_hook --> |approve| mainagent_loop
stop_hook --> |block| subagent
permission_check --> |allow|decide
permission_check --> |deny| subagent
permission_check --> |ask| user
decide --> |skill needed|skilltool
decide --> |other tool call| tools
skilltool -.-> |provide skill body|subagent
tools -.-> |other tool response|subagent

Note: Background subagents collect permissions upfront before launch and auto-deny during execution.

The subagent loop looks similar to the main agent loop, but there are critical differences:

No memory files. Session init only loads CLAUDE.md and skill metadata — not memory files. The subagent gets project instructions but not your personal auto-memory.

No nested subagents. There is no tasktool in the subagent’s toolset. A subagent cannot spawn its own subagents. This prevents unbounded recursion and keeps the execution model predictable.

Returns to caller, not user. When the subagent completes, the stop hook sends the result back to the main agent (not the user). The main agent then incorporates the result and continues its own loop.

Foreground vs background permission behavior. This is a nuance that trips people up:

• Foreground subagents pass permission prompts through to the user — the ask → user path works normally.
• Background subagents collect all needed permissions upfront before launch. During execution, any permission request that wasn’t pre-approved is auto-denied. This is why background subagents sometimes fail on unexpected tool calls — they can only use tools that were anticipated and approved at launch time.

Fresh context window. Each subagent gets its own context, completely isolated from the main agent’s conversation. This is a feature, not a limitation — it prevents long sessions from degrading subagent performance and keeps each subtask focused.

Why Skills Are Cheap and Subagents Are Not (and When That’s OK)

The Claude Code docs compare skills and subagents on context cost — skills are “low” while subagents are “isolated from main session.” But why? The architecture above makes it obvious.

Look at the skill tool path in the main agent diagram. When the decide node routes to skilltool, there’s a single dotted arrow back: provide skill body → mainagent. That’s it. No new session. No new LLM call. The skill body is injected into the existing agent’s context, and the loop continues with the next LLM call now enriched with that knowledge. The cost is just the additional tokens of the skill body in the current context window.

Now look at the subagent diagram. When decide routes to tasktool, it triggers an entirely new agentic loop — session_init → session → subagent → llm → tool_use → permission_check → decide → tools — all running independently. Every iteration of that loop is a separate LLM call with its own context window. The subagent might make dozens of tool calls, each cycling through the full loop, before finally returning a summary to the main agent.

This is the architectural reason subagents cost more. It’s not an implementation detail — it’s a fundamental consequence of isolation. A skill enriches the current loop. A subagent spawns a new one.

So when is the subagent cost justified?

When the alternative is worse. If a task requires reading 30 files, running a test suite, or processing verbose logs, doing that inside the main agent’s loop means all that output lands in the main context window — making every subsequent LLM call more expensive and potentially degrading quality. A subagent absorbs that cost in isolation and returns only a summary. The main agent’s context stays lean.

Additionally, subagents can run on cheaper models. The built-in Explore subagent uses Haiku — fast and inexpensive for read-only exploration. Your main agent stays on Opus or Sonnet for reasoning-heavy work while Haiku handles the legwork. This is the kind of cost optimization that becomes obvious once you see the two separate loops in the architecture.

Closing Thoughts

This is a mental model, not a specification. Claude Code is closed source and evolving fast — the internal architecture likely changes with every release. But having this model has consistently helped me explain and predict behaviors that would otherwise seem arbitrary.

When you understand the flow, things click into place: why Shift+Tab cycling through permission modes changes Claude’s behavior, why your CLAUDE.md instructions take effect immediately, why skills feel different from regular tools, and why background subagents need their permissions figured out upfront.

Personal Insight: My background with LangGraph — where you explicitly define nodes, edges, and conditional routing in agent graphs — made this mental model feel natural. Claude Code’s internal flow maps closely to concepts like state graphs, conditional edges, and tool nodes. If you’re familiar with any agentic framework, you already have the vocabulary to reason about what Claude Code is doing under the hood.

Use this understanding to work more effectively. Don’t fight the architecture — work with it.

In simple terms, many of these problems—delays, unexpected outcomes, and high costs—stem from context drift, context overload, and context loss as information flows across layers of people with varying degrees of knowledge, understanding, and incentives.

Key Systemic Pain Points

To understand the necessity of the AI shift, we must acknowledge the weight of current systemic issues:

The Communication & Context Gap

• Unclear or poorly understood customer requirements: Starting off on the wrong foot.

• Context loss: Information degrading as it flows through multiple layers of management with different levels of technical understanding.

• Poor task breakdown and synchronization: Especially when done by people who lack technical depth or full context.

• Delays caused by unavailability: Communication issues, conflicts, and misunderstandings that grow with team size.

• Requirement churn: Delays leading to requirement changes, which in turn create more confusion and rework.

The Management & Organizational Burden

• The challenge of large teams: Getting people with varying experience, intelligence, and skills to produce high-quality, timely, and consistent output.

• Maintenance of hierarchies: High costs of maintaining large hierarchies of managers, senior managers, and directors to allocate and track work.

• High people costs: Compensation growing with seniority in organizational hierarchies rather than direct output.

• Infrastructure and tool spend: Significant spending on infrastructure, training, and communication tools.

Technical & Strategic Friction

• Architectural shortsightedness: Short-sighted or incorrect system architecture.

• Lack of predictability: Lack of reliable ways to predict delivery timelines and development costs.

• Solutions that fail: Solutions that ultimately fail to meet real customer needs.

The Evolution of AI Adoption

The Initial AI Phase: Productivity Boosting

In the early phase of AI adoption, agents were mainly used to write code or small parts of systems. In many cases, this did not fundamentally change how software was built. In fact, for some teams, it became more expensive and more chaotic:

• Organizations paid for expensive AI tools on top of existing engineering costs.

• Everyone started feeling like a “developer,” leading to experiments, side projects, and half-baked solutions.

• A lot of code was generated, but not necessarily the right code.

Many organizations today are still in this phase: using AI as a productivity booster without rethinking the overall software development model.

The Latest AI Phase: Developments Changing the Future

We are now entering a phase where AI tools are moving beyond just writing code. When provided with a well-designed solution and clear technical requirements, modern AI agents can:

1. Understand the intended system design and architectural constraints.

2. Analyze the solution and derive a structured work breakdown.

3. Allocate tasks across multiple agents.

4. Manage context across agents working in parallel.

5. Execute, verify, iterate, and refine the implementation.

Without a solid solution and clear requirements, AI can generate code, but it cannot solve the real problems of coordination, context management, or timely delivery. This is the critical foundation for the latest phase of AI-driven software development.

The AI-Driven Development Team

In an AI-driven development team, the execution model shifts from managing people to engineering context:

• Unified Capabilities: All agents have similar baseline capabilities and access to the same knowledge.

• Architectural Alignment: Work can be broken down logically based on the given architecture.

• On-Demand Scaling: “Virtual teams” of agents can be created based on task size.

• Scoped Context: Context can be managed carefully to reduce information corruption.

• Synchronized Execution: Fast, synchronized execution reduces delays and downstream requirement churn.

• Compute-Based Costing: Cost is tied to compute and usage rather than headcount and management layers.

• Predictability: With better automation, time and cost estimates can become more predictable.

Context management is still a hard problem for AI systems. But unlike human teams, it’s a problem that can be engineered away with better tooling and coordination mechanisms—and that’s exactly what the latest generation of AI development tools is starting to do. This makes the current phase a real game changer.

Personal Insight: Initially, I was skeptical of this shift. However, it was only after deep-diving into tools like Cursor and Claude Code (currently my favorite) that I truly grasped this new reality. Seeing them in action made it clear that the execution model of software development isn’t just evolving—it’s changing in fundamental ways.

Transitioning to this latest phase is a big and inevitable change for organizations that want to survive in the AI-driven era. However, it requires careful planning, process redesign, and culture adaptation. It can also affect human relationships and roles, which makes the transition challenging and, at times, painful.

What Is Still Missing (And Why Humans Still Matter)

Even with increasingly capable AI systems, there are two areas where AI still struggles—and where humans remain essential:

1. Understanding real customer requirements. Customers often don’t fully know what they want. Requirements are ambiguous, evolving, and shaped by real-world constraints, incentives, and organizational politics.

2. Designing the right solution. Creating systems that truly satisfy customer needs, remain flexible for the future, and are extensible over time still requires deep domain understanding, judgment, and architectural thinking.

AI can dramatically improve execution speed, reduce context loss, and increase consistency. But deciding what to build and how to design it remains a fundamentally human responsibility.

Next Phase: Imagining What’s Ahead

The next evolution might be AI not just executing well-designed solutions, but collaborating on design itself—understanding requirements, proposing architectures, and iterating with human guidance. If this becomes feasible, we could see a shift from execution-heavy teams to truly hybrid human-AI innovation teams, where humans focus on strategy and AI handles the heavy lifting of execution and coordination.

Not PowerPoint decks created for reviews and then forgotten.

But documentation as a living system that governs how software is designed, reviewed, built, released, operated, and evolved over time.

One of the most powerful practices I observed was how architectural deviations were treated as first-class signals — tracked, reviewed, and documented even before they caused incidents.

This single practice prevented entire classes of failures long before customers ever noticed.

Architecture Starts With Requirements — Always

One thing was very clear:

No architecture was ever created without properly documented customer requirements.

Requirements were reviewed, validated, and made visible to everyone involved. They formed the foundation for architectural decisions and helped eliminate failures caused by misunderstanding or assumption.

With a well-documented architecture, nearly 50% of the system gets validated during design reviews — before a single line of code is written.

This early validation builds confidence, exposes gaps, and aligns teams around clear, visible goals.

Equally important:

No software went to production without an approved end-to-end architecture.

Architecture documents were not optional references — they were contractual artifacts defining long-term intent, constraints, non-functional requirements, and trade-offs.

Long-Term Architecture, Iterative Delivery

Architectures were created with long-term thinking.

Software could be released in iterations, but always aligned with the goals and constraints defined by the approved architecture.

Implementation evolved continuously.

Architecture intent — the “what” and “why” — could not be silently bypassed.

Micro-architecture (how things are implemented) evolved with iteration. Macro-architecture (what problem is being solved and why) remained stable — and documentation evolved alongside both.

Requirements themselves evolved over time, but that evolution was explicit, reviewed, and reflected across architecture, code, and operations — not treated as a new solution each time.

Deviations Are Recorded — Even Before Incidents

Here’s a critical but often overlooked practice:

Tickets were filed for each and every architectural deviation — even if no incident had occurred yet.

Sometimes these deviation tickets were created with high priority and were:

• Tracked independently, or

• Explicitly linked to a larger customer-impacting incident

This meant deviations were treated as risks, not just future bugs.

When incidents occurred later, these tickets often became part of the main timeline, clearly showing where the system had drifted from its intended design.

Incidents Trigger End-to-End Reviews — Not Just Fixes

When failures did occur, retrospectives didn’t stop at the code fix.

They reviewed the entire chain:

• Alert clarity and correctness

• Ticket quality and diagnostic depth

• Runbook accuracy and usability

• Architectural assumptions and alignment

If a release had bypassed the approved architecture, it surfaced here — through alerts, tickets, or the first escalation.

And documentation was updated as part of the resolution.

People Follow What Is Written — Not What Is Said

Another hard truth:

People follow documented steps, not verbal communication.

In high-pressure situations, teams rely on:

• Runbooks

• Tickets

• Architecture documents

• Alert messages

This makes documentation not just important — but operationally authoritative.

If documentation is incomplete, outdated, or confusing, recovery slows down and risk increases.

Everything Is Connected

Documentation wasn’t fragmented or siloed:

• Alerts linked to runbooks

• Runbooks referenced architectural decisions

• Tickets captured analysis, deviations, and resolutions

• Architecture documents evolved based on real production behavior

Retrospectives reviewed the full loop:

signal → ticket → runbook → architecture → requirements → prevention

Incidents often revealed missing or misunderstood non-functional requirements, which were then explicitly documented to prevent recurrence.

How to Recognize a Documentation Problem

Regardless of what an organization claims, documentation quality is revealed by behavior, not statements.

Good documentation is visible in how systems operate under stress — not in how confidently teams talk about it.

Some strong indicators include:

• Incidents are not tracked within minutes of occurrence

• Alert messages are unclear or don’t explain the issue

• Support teams cannot recover systems using runbooks alone

• Simple integrations require multiple meetings instead of documentation

• The goal or use case of a service is hard to understand

• The organization has multiple overlapping or duplicate services

• Requirements are not available or not clearly visible to everyone

• Requirements cannot be linked to architecture or solutions

• Issues and incidents cannot be traced back to architectural decisions

• Documentation is outdated, conflicting, or confusing

• Review meetings are spent explaining the solution instead of reviewing it

• Documentation is treated as a task or deliverable to gain acceptance

• “Let’s build the system first and document later” is considered acceptable

• AI systems consistently fail to generate meaningful output from existing documentation

• Projects frequently exceed timelines, budgets, or cost more than the revenue they generate

• A system cannot be recovered because one specific engineer is unavailable (That’s not a technical problem — it’s a documentation failure.)

Tools Don’t Create Good Documentation

Documentation quality is not determined by tools.

Tools provide features — not clarity.

More tools often mean more fragmentation and confusion.

What creates good documentation is:

• Clear intent

• Semantic linking across artifacts

• Consistency across requirements, architecture, code, and operations

Documentation as a Competitive Advantage

This level of rigor is a major differentiator between highly successful engineering organizations and those that struggle at scale.

Strong documentation:

• Validates requirements early

• Enforces architectural discipline

• Makes deviations visible before incidents

• Reduces reliance on tribal knowledge

• Enables reliable systems at scale

Weak documentation allows silent drift — until customers pay the price.

Why This Matters Even More With AI

As organizations push AI into engineering and operations, documentation quality becomes a force multiplier — or a failure amplifier.

AI systems only work well when grounded in accurate, semantically rich documentation:

• Clear architecture context

• Well-defined operational flows

• Trusted historical data

Without that foundation, AI doesn’t create leverage — it creates noise.

Final Thought

Documentation is not about writing more.

Documentation should be a habit — not a task.

When treated as a first-class architectural practice, documentation enforces intent, accountability, and alignment over time.

Teams don’t just fix incidents faster — they prevent entire categories of failures from happening at all.

TL;DR: Monolith vs microservices is less important than modular vs non-modular. A modular monolith (clear contracts, one-way dependencies, no cycles) is reliable to build and evolve, and is also the cleanest starting point if/when you later extract microservices.

A monolith is a geological feature consisting of a single massive stone or rock, such as a mountain (Wikipedia).

In software, the term “monolith” is usually used to describe how an application is packaged and deployed (a single deployable unit). “Modular” vs “non-modular” describes how the code inside is structured (boundaries, contracts, dependencies).

What people usually mean by a monolith

• Application with a single module or multi-module large code base.
• It is deployed as a single application (one deployable unit).
• Higher throughput is often achieved by vertical scaling and/or by running multiple full instances.
• Horizontal scaling of the application means deploying multiple instances of the complete application.
• Single build, deployment/release pipeline.

Monolithic designs have worked successfully for years. With the advent of cloud platforms, many organizations moved toward microservices, but monoliths still remain a very practical choice in many scenarios.

Use cases for a monolith application

• An application that is not distributed multi-regional and/or multi-tenant and not expecting varying unlimited loads can be successfully developed and delivered as a monolith.
• Organizations on a budget, with a small team and a need for fast time-to-market, can start with a monolith and still deploy it to cloud or on-premise with a predictable overall cost.
• Many enterprise applications are developed and operated as monoliths (often with multiple internal modules).

Where monoliths hurt

• Individual components or modules cannot scale independently. For example, if a “sales” module gets a seasonal traffic spike compared to “inventory” or “users”, you still need to scale the whole application.
• Horizontal scaling of the whole application can get costly, especially if all modules don’t need to be scaled out.

What is a module?

A system is modular if it’s composed of independent, loosely coupled components integrated via well-defined interfaces and dependencies. A simple analogy is computer hardware: memory, storage, and USB are separate modules with a well-defined interface on the motherboard. Internals are hidden from other modules (encapsulation), and replacements are possible as long as the interface stays compatible.

Similarly, a software module should have:

• A clear responsibility/boundary
• A stable contract (API)
• Encapsulated internals (other modules shouldn’t rely on internal classes/tables/files)
• Intentional dependency direction (avoid cycles)

Modularity enables parallel development, testing, and releases with reduced complexity.

Are monoliths bad?

There’s a common belief that monoliths are always bad and should be avoided. To reason about that, it helps to separate three patterns:

• Non-modular monolith: a single deployable with tight coupling and cyclic dependencies inside
• Distributed monolith: many deployables, but still tightly coupled (often through shared code, synchronized releases, and runtime/config coupling)
• Modular monolith: a single deployable with clean internal boundaries and one-way dependencies

Non-modular monolith: symptoms and outcomes

This is the form that creates the impression that monoliths are painful, costly, and difficult to manage.

graph TD
    Sales[Sales] <--> Inventory[Inventory]
    Inventory <--> Users[Users]
    Users <--> Reporting[Reporting]
    Reporting <--> Sales
    Sales <--> Users
    Inventory <--> Reporting
    
    style Sales fill:#ff6b6b
    style Inventory fill:#ff6b6b
    style Users fill:#ff6b6b
    style Reporting fill:#ff6b6b
    
    classDef default stroke:#333,stroke-width:2px

Non-Modular Monolith: Cyclic dependencies and tight coupling between modules

Definition:

Single-module application: A large multi-feature application where most code lives in a single “fat” module.

Multi-module application (but non-modular in practice): A large application split across modules, but with high coupling and circular dependencies. It may look modular, but behaves like a single tangled unit. This form is common.

Characteristics and outcomes:

• Long builds: Even in a multi-module setup, cyclic dependencies force sequential builds and frequent rebuilds.
• CI instability: In a single repo (or in the worst case, multiple repos), ambiguous dependencies surface during parallel merges, causing build/test failures.
• Long validations: Small changes require running “everything” because impact is unclear.
• Test duplication: Integration tests either become duplicated or incomplete.
• Patch fixes over root-cause fixes: Failures trigger chain reactions, making issues hard to isolate and leading to “safe” patching instead of improving design.
• Vicious cycles: Slow build/test/release cycles slow delivery; rushing changes by bypassing validations often increases defects.
• Unreliable estimation: Small changes carry hidden coupling, so timelines frequently slip.
• Poor work distribution: Without clear boundaries, work is hard to allocate; reviews and coordination increase; some people become overloaded while others are blocked.
• Tooling won’t save architecture: Teams may keep adding tools/technologies to compensate, while core dependency and boundary problems remain.
• Team structure leaks into code: “Reuse” and “common code” can easily break contracts and introduce cycles if boundaries aren’t enforced.
• Too many stakeholders: If a minor change requires broad coordination, it’s a sign boundaries/contracts aren’t working.
• Unhealthy environment: Constant firefighting and fear of change can degrade morale.

Distributed monolith: coupling survives the split

• Multiple non-modular monoliths: The pain of a non-modular monolith pushes teams to look for a fix. Microservices are often chosen with the belief that “splitting the app splits the complexity”.
• In reality, when boundaries are unclear and dependencies are cyclic/ambiguous, complexity is copied into every service (shared code, synchronized releases, runtime coupling), and the original problems resurface in a harder-to-debug form.
• Additional problems: The application breaks into services, but the underlying coupling doesn’t. Build, deployment, runtime, and configuration dependencies still exist — they’re just harder to see and coordinate. What were previously in-process calls become network calls, increasing latency, failure modes, and operational complexity.
• Upgrades are difficult: As the same code exists in multiple services because of cyclic dependencies, every dependency version upgrade needs to be upgraded and tested across all services. This multiplies the workload and complexity.
• Monolith Explosion: The performance of the application will degrade if there are a high number of extra calls over the network due to obvious reasons. To match the original performance and reduce network calls, individual microservices can do some local calls as there is code duplication on each service, which means it needs to be vertically scaled to do more local processing. Hence more such non-modular monoliths are born, each having similar resource requirements as the original application, which will make the application costly and difficult to manage.

Modular monolith: what good looks like

This is the form of monolith one should design and implement and also proves that monoliths are good and future-ready if done properly.

graph TD
    Sales[Sales] --> Inventory[Inventory]
    Sales --> Users[Users]
    Inventory --> Reporting[Reporting]
    Users --> Reporting
    
    style Sales fill:#51cf66
    style Inventory fill:#51cf66
    style Users fill:#51cf66
    style Reporting fill:#51cf66
    
    classDef default stroke:#333,stroke-width:2px

Modular Monolith: Clear one-way dependencies, no cyclic dependencies

Definition:

• A single deployable application with a large code base divided into modules with clear separation of responsibilities.
• Modules communicate over fixed and clearly defined contracts.
• Dependencies are intentional and one-way (no cycles).
• Internals and transitive dependencies are not “leaked” to dependent modules.

Characteristics and outcomes:

• Modules can exist in separate repositories. This enables faster merges and clearer ownership because teams mostly coordinate with direct dependencies/dependents.
• Modules can be built in parallel, reducing build time.
• Fixes are faster because you usually need to validate only the module and its direct dependencies/dependents.
• Integration tests can achieve high coverage with less duplication, improving confidence and efficiency.
• Effort estimates become more accurate because surprise coupling is rarer.
• Releases are more stable and more frequent, so confidence stays high.
• When teams ship continuously, credit is shared more fairly, which improves morale.
• Team size and development cost become more predictable. The fear of the unknown is reduced.
• Issues are easier to isolate. Failures can be contained within a module (or a known set of modules), while other modules degrade gracefully via well-defined contracts.
• Dependencies can be easily and independently upgraded as they are hidden from other modules.
• Teams get more time for new features because change and validation cycles are shorter.
• Modules can be enhanced, extended, replaced, or removed based on requirements.
• Hot modules (under heavy load) can be extracted into microservices and scaled independently.
• A modular monolith is the best starting point if you later need microservices.

A practical checklist to aim for:

• No cyclic dependencies (enforced by tooling)
• Stable module contracts (APIs) and versioning discipline
• Encapsulated internals (no “reaching into” other modules)
• Intentional dependency direction (layering or domain boundaries)
• The ability to build/test modules with fast feedback

How to enforce this in practice:

• Add tooling to enforce module dependency rules (and fail CI on violations).
• Treat contracts as first-class: document APIs, version them, and avoid leaking internals.
• Avoid “shared persistence”: don’t let other modules write directly to your module’s tables/collections.
• Keep cross-module communication explicit (public APIs/events), and measure it (module-level metrics).

Conclusion

The application can be a monolith or microservices — modularity is what determines long-term success, whether on cloud or on-premise. A design is modular when contracts are defined and documented, external dependencies are explicit, and internal logic/dependencies are encapsulated behind clear boundaries.

Language/module features can help (for example Java’s module system from Java 9+, or JavaScript modules since ES2015), but the core work is still architectural: define boundaries, control dependency direction, and enforce contracts.