15 — Scaling Claude Code — Parallelism, Worktrees, Teams, and Headless

"Just run more of them" was my scaling theory, and parallel agents collided on the same files. The map of mechanisms that replaced it: every scaling mechanism is a different way to fan out work while keeping contexts isolated, and they solve different isolation problems. [1] Subagents isolate a side task inside one session; agent view isolates whole sessions to the background; agent teams coordinate isolated sessions through a shared task list; worktrees isolate sessions into separate git checkouts; headless isolates Claude into a Unix pipe for automation. Same goal — parallelism without collision — five different isolation boundaries.

The framing that clicked is to stop asking "how do I run more Claude?" and start asking "what do I need to keep isolated from what?" Two tasks that touch the same files need git isolation (worktrees). Two tasks that share a plan need coordination isolation (agent teams). A side task inside one workflow needs context isolation (subagents). Background work I'm not watching needs session isolation (agent view). A job in CI needs process isolation (headless). Picking the mechanism is picking the boundary [1][2].

The five mechanisms and their isolation boundaries

The roadmap lists them directly, and reading each as an isolation answer made them click [1]:

• Subagents — delegated workers that handle a side task in their own context and return a summary. Isolation boundary: _context_. The main conversation stays clean. (Covered in detail in the subagents post — the context-hygiene play.)
• Agent view — dispatch independent sessions to the background and monitor them from a single screen. Isolation boundary: _attention_. I can spin up several sessions and watch them without context-switching my terminal between each.
• Agent teams — coordinate multiple sessions through a shared task list and inter-agent messaging, managed by a lead agent. Isolation boundary: _coordination_. The sessions stay separate but share a plan and can talk to each other.
• Git worktrees — isolate parallel sessions into separate git checkouts so they never conflict over the same files. Isolation boundary: _the working tree_. Two sessions editing the same repo physically cannot collide because they're in different checkouts.
• Headless mode — the -p/--print flag turns the interactive terminal into a programmable Unix utility for automation and CI/CD. Isolation boundary: _the process_. Claude runs, does one job, exits — no interactive session at all.

Worktrees: parallel sessions without file collisions

The mechanism I underrated longest is git worktrees, because it solves the most concrete pain of running multiple sessions: two agents editing the same files at the same time is a recipe for conflict. The roadmap frames worktrees as the scaling technique that lets me run multiple independent sessions in parallel without context-switching or file-edit collisions [3]. Each session gets its own checkout of the repo, so they physically cannot stomp each other's working tree.

The workflow that made it click: I "fan out" several tasks across separate worktrees, supervise each one, and delete the worktree folder once the branch is merged. Because they share the same underlying repo history, prompt caching can share codebase context across them, and the cleanup is just removing a directory. This is the right answer whenever I have two independent features to build at once — worktrees keep them isolated at the filesystem level without the overhead of full clones.

Agent teams: coordination through a shared plan

Agent teams are the experimental orchestration feature for when the parallel work isn't fully independent — the sessions need to share findings and debate [4]. A designated Team Lead manages a shared task list and delegates work to Teammates who can message each other directly. The isolation is real (each session has its own context), but the coordination layer on top is what makes it a _team_ rather than four separate agents.

The roadmap's example — building a C compiler with a team of parallel Claudes — is the shape of problem this fits: a single large artifact where different parts have to agree on interfaces, but the work on each part is deep enough to deserve its own context [4][5]. For genuinely independent tasks, agent teams are overhead; for interdependent ones, the shared task list and messaging are the point.

Headless: Claude as a Unix utility

Headless mode (-p / --print) is the scaling mechanism that targets automation rather than a human at a keyboard [6]. It transforms the interactive terminal into a non-interactive, single-use utility: I provide a prompt on the command line, Claude runs its agentic loop (researching, editing, running commands as needed), and exits when the task is done. The roadmap frames it as programmable and built for CI/CD pipelines, shell scripts, and one-liners.

The way of thinking: headless is how Claude enters automation. A GitHub Action that runs a security review on every PR, a cron job that generates a daily report, a pre-commit hook that fixes lint — each is a headless invocation where Claude is one stage in a pipeline. No one is watching a terminal; the process isolation is total, and the output flows into whatever consumes it.

How I use this

The habit these notes left me with is the isolation-boundary question before I fan out. Side task inside one workflow — subagent (context isolation). Two independent features on the same repo — worktrees (working-tree isolation). Several sessions I want to watch together — agent view (attention isolation). One big artifact with interdependent parts — agent teams (coordination isolation). A job no human watches — headless (process isolation). The default mistake is reaching for agent teams when the tasks are actually independent, or running two sessions in one checkout when they touch the same files. Naming the boundary first turns "scaling" from a vague ambition into a concrete mechanism choice.

References

[1] Anthropic, "Run agents in parallel," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/agents

[2] Anthropic, "Agent view," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/agent-view

[3] Anthropic, "Run parallel Claude Code sessions with Git worktrees," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/worktrees

[4] Anthropic, "Orchestrate teams of Claude Code sessions," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/agent-teams

[5] Anthropic, "Building a C compiler with a team of parallel Claudes," Anthropic Engineering, 2025. [Online]. Available: https://www.anthropic.com/engineering/building-c-compiler

[6] Anthropic, "Run Claude Code programmatically," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/headless