Mastering 8 Sessions Alone! The Complete Guide to Claude Code Orchestration

"I'm using Claude Code, but as the scale grows, the context overflows and accuracy drops."

"In the end, my own hands giving correction instructions to the AI have become the biggest bottleneck."

Many people are likely stuck at this point. I was the same at first, throwing code, tests, and design discussions all into one session, watching Claude's accuracy decline as the history expanded.

What I've recently realized is that Claude Code itself officially provides three mechanisms for running multiple sessions in parallel.

Furthermore, these three are similar but distinct; confusing them can lead to accidents. Conversely, if you divide them by role, you can move to the "commanding side" without writing a single line of code yourself.

Today, I will organize these three mechanisms and the correct way to fix role boundaries while checking primary information from the official documentation.

Specifically, I will break it down into a configuration where 8 sessions are placed across three layers: Command, Implementation, and Quality.

As a bonus, I'll also use primary information to explain why common explanations like "writing role IDs in CLAUDE.md to switch" or "sharing memory with SQLite" are slightly off from the official mechanism.

My name is tatsuki (@nobel_824).

I support AI utilization for small and medium-sized enterprises, helping with the business implementation of Claude / Codex while running Claude Code myself all day long. Parallel operation is an area I touch every day for both work and personal projects.

Related Article: Introduction to Vibe Coding: 6 Steps for Non-Coders to Build Apps with Claude. The Era of In-house Production in a Weekend

https://note.com/nobel/n/n8192ec07d689

1. Why "Stuffing Everything into One Session" Fails

The first trap is overloading a single session with too much information. No matter how smart the Claude model is, it hits structural limits.

Specifically, you encounter these three issues:

• Context Contamination: When implementation code, tests, debug history, and design discussions mix in the same context, the reasoning foundation becomes muddy and accuracy drops.
• Instruction Conflict: If "implement with speed priority" and "be strict with security" exist in the same place, judgments become halfway.
• Token Bloat: Loading a massive history every time is a waste of both time and cost.

The solution is the idea of "becoming a single commander and lining up specialized Claudes." It's similar to a CTO having a Tech Lead and Backend Lead, but the important thing isn't the vibe—it's correctly utilizing the official Claude Code mechanisms.

One action you can take today: Think about your current session and check if "implementation," "research," and "review" are coexisting in one context. If they are, that's your starting point for splitting them.

2. Correcting the "Three Parallel Mechanisms" Provided Officially

This is the core of the article. Claude Code has three mechanisms for parallelism, each with a different scope.

The first is subagent (a helper AI that runs in a context separate from the main conversation). It executes side tasks like research or reviews using its own context window, dedicated system prompt, and limited tool permissions, returning only a summary of the results to the main session. The key point is that subagents run within the same session, report only to the main, and subagents do not talk to each other (Official Docs).

The second is agent teams (a mechanism where multiple Claude Code sessions collaborate as a team). One session becomes the team lead and spawns teammates, collaborating via a shared task list and mailbox. Unlike subagents, teammates can send messages directly to each other. This is an experimental feature and is disabled by default. You need to set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and use Claude Code v2.1.32 or later (Official Docs).

The third is git worktree (a Git feature that allows multiple working directories from the same repository). By starting with claude --worktree feature-auth, Claude launches in an isolated environment on a different branch/directory. If you run another one in a different terminal, they can run in parallel without stepping on each other's files (Official Docs). When using the desktop app, a worktree is automatically created for each new session.

Here is a table comparing the three:

You won't get confused if you remember that worktree handles file isolation, while subagents and agent teams handle the coordination of the work itself.

One action you can take today: First, try typing claude --worktree bugfix-test to get a feel for launching an isolated session. When you finish after making changes, it will ask whether to keep or delete the worktree.

3. Practice: Deploying 8 Sessions in a "3-Layer Structure"

How do these three mechanisms translate into 8 sessions? I use a layout divided into Command, Execution, and Quality layers.

Command/Design Layer (2 Sessions)

• Session 1 PM (Project Manager): Overall progress management, task breakdown, reporting to humans.
• Session 2 Architect: Decides technical consistency and directory structure. Requires plan approval to produce designs without writing code.

Execution/Implementation Layer (4 Sessions)

• Session 3 Frontend: Component creation, UI adjustments.
• Session 4 Backend: Endpoint implementation, query optimization.
• Session 5 Infra/DevOps: Docker, CI/CD maintenance.
• Session 6 Security: Vulnerability checks, hardening authentication.

Quality/Maintenance Layer (2 Sessions)

• Session 7 QA/Reviewer: PR reviews, pointing out edge cases.
• Session 8 Technical Writer: README, API documentation maintenance.

There are three tips for this layout: Isolate the four implementation layer sessions with worktrees so they don't step on each other's files. Fix roles for the quality layer as subagent definitions or agent team teammates. And have each session relay information via shared Markdown files (design notes or review results). The Architect updates the design, the implementation layer moves based on that, and the Reviewer writes back results. Humans only need to give instructions to each session triggered by these file updates.

One note: The official guideline for one agent team is 3–5 people, so don't stuff all 8 into one team at once (Official Docs). It's safer to combine worktree-isolated sessions with a 3–5 person agent team and subagents as needed to reach a total of 8 workers.

One action you can take today: Choose two roles from the 8 above that seem easy to split in your current project. In many cases, Architect and Reviewer are the first points of division.

4. Fix Role Boundaries with "Subagent Definitions," Not "CLAUDE.md"

Let me correct one common misunderstanding about parallel operation. You might see explanations like "Write roles (ID: arch, ID: dev-main...) in CLAUDE.md and switch personas at startup," but this mechanism doesn't actually exist.

CLAUDE.md is a shared instruction file that Claude Code reads at startup. However, the official docs clearly state that CLAUDE.md is "context, not a forced setting." Since it's passed as a user message after the system prompt, strict compliance isn't guaranteed. If you absolutely want to stop something, you should use hooks (Official Docs). Think of it as a strong recommendation rather than an absolute "constitution."

So where do you fix roles? The answer is subagent definitions. By placing a file under .claude/agents/ with a name, description, available tools, and model in the frontmatter, you complete a reusable expert. Here is a minimal example:

name: security-reviewer

description: Critically audits code from the perspective of authentication, input validation, and session management.

tools: Read, Grep, Bash

model: sonnet

You are a senior security reviewer. Focus on token handling,

session management, and input validation, and report findings with severity levels.

Furthermore, these definitions can be called by name as teammates in agent teams. If you ask to "set up a teammate with the security-reviewer agent type to audit the auth module," it becomes a member inheriting the tools and model from that definition (Official Docs). The design allows you to write a role once as a subagent definition and reuse it as both a subagent and a team member.

Prompt example to try (letting Claude create a role definition):

Create a subagent definition to be placed in .claude/agents/.

The role is "a reviewer who points out performance issues and N+1 queries in implementation code."

Include name / description / tools / model in the frontmatter,

and write the body in the persona of a senior engineer.

5. Building an "Architect-Reviewer" Team with Agent Teams to Boost Accuracy

A configuration that is highly effective in parallel operation is setting up a "creator" and a "doubter" separately. This isn't just theory; the official documentation provides real-world examples.

In the official "Parallel Code Review" example, for one PR, three teammates are set up for security, performance, and test coverage, each looking from a different perspective while the lead integrates the results. Furthermore, in the "Competing Hypotheses" example, five teammates are assigned different hypotheses for a bug to argue and disprove each other's theories, treating the surviving theory as the root cause (Official Docs). Since a single investigator tends to get pulled toward the first theory, this approach intentionally creates conflict to improve accuracy.

You can also implement an operation where the Architect is "not given permission to write code" using official features. By requiring plan approval for a teammate, the teammate stays in a read-only plan mode, producing only designs until the lead approves. Approval criteria can be written in the lead's prompt, such as "only approve plans that include test coverage."

Prompt example to try (setting up a conflict structure in one go):

Create an agent team to review PR #142. Set up three teammates:

one for security, one for performance, and one for test coverage.

Have them review independently and output findings with severity, then integrate them at the end.

There are two display modes: in-process (all teammates run in the same terminal, cycle with Shift+Down) and split panes (each teammate in a separate pane; requires tmux or iTerm2). It's easier to start with in-process as it requires no extra setup.

6. Share Memory via Official Auto Memory (Markdown), Not "SQLite"

When running multiple sessions, the next hurdle is "sharing memory across sessions." While advanced techniques like "storing tagged memory in SQLite and dynamically injecting it" are sometimes introduced, that is not a standard Claude Code feature. It's possible if you build a DB via MCP (Model Context Protocol), but you should distinguish that from the officially provided memory mechanism.

Official auto memory works with markdown files. Inside ~/.claude/projects/<project>/memory/, files like MEMORY.md (index) and topic-specific files like debugging.md are placed, and Claude writes to them as it works. The loading rules are clear: every session reads up to the first 200 lines or 25KB of MEMORY.md, and Claude only goes to read topic-specific files when necessary. This is available from Claude Code v2.1.59, saved per repository (so shared across worktrees), and stored locally (Official Docs).

The beauty of this design is that by "always loading the index and fetching details only when needed," you can keep the context window clean. Even with thousands of small rules, the context won't be contaminated every time as long as the index doesn't bloat.

In terms of order, use the official markdown-based auto memory to its full extent before trying to build a custom SQLite solution.

One action you can take today: Typing /memory during a session shows the list of currently loaded CLAUDE.md and auto memory files. First, take a peek at where and how many memories you have.

7. Three Pitfalls in Parallel Operation (Cost, DB, Permissions)

Now that you understand the mechanism, here are three points of caution for operation.

First is token cost. The official docs state that since each teammate in an agent team has an independent context, token usage increases proportionally to the number of people. Using 5 people for routine tasks will result in a cost loss. That's why the official recommendation is 3–5 people, noting that "three focused members often beat five distracted members" (Official Docs).

Second is the isolation scope of worktrees. A worktree is just a Git mechanism for file separation; databases, environment variables, and running services are still shared. If two sessions run migrations on the same local DB, it will break. The official docs warn to "remember to initialize the development environment (install dependencies, set up virtual envs) in each worktree," and if tasks touch the DB, you need to separate schemas, Docker containers, or .env files (Official Docs).

Third is permissions. Teammates inherit the lead's permission settings when spawned. If you run the lead with --dangerously-skip-permissions, all teammates will also be in that same unconfirmed state. Since the impact of an accident spreads in parallel, it's safer to restrict permissions on the lead side.

8. FAQ for Intermediate Users: Headcount, Expansion, and Quality Gates

Finally, some supplementary answers to common questions.

Q. How many sessions are realistic?

A good guideline is the 3-layer, 8-session structure mentioned earlier. The key is not to stuff 8 people into one agent team, but to use a 3–5 person team as the core and add worktree sessions or subagents. This aligns with official recommendations (3–5 people per team, 5–6 tasks per teammate). The ultimate limit is the range you can monitor and steer. If you increase the number beyond what you can command, efficiency will diminish.

Q. What if I outgrow subagents and agent teams?

If you want to monitor a large number of independent sessions from one place, the official subagents page mentions a mechanism called background agents. Think of it in layers: subagents for help within a session, agent teams for a conversational parallel team, and background agents for managing many independent sessions.

Q. How can I guarantee quality?

Recommendations in CLAUDE.md are just "easy-to-follow instructions." For checks you absolutely want to execute, force them with hooks. Agent teams have hooks like TeammateIdle, TaskCreated, and TaskCompleted; returning exit code 2 sends feedback and forces the work to continue (Official Docs). This means you can programmatically enforce rules like "don't complete until tests are green."

Summary: From Monitor to Designer/Delegator

The value of Claude Code lies more in the ability for one person to control multiple specialized Claudes than in just writing code faster. Here are the key points:

Don't confuse the three mechanisms: subagents return results, agent teams are conversational teams, and worktrees isolate files. Divide 8 sessions into Command, Implementation, and Quality layers; isolate implementation with worktrees and fix quality roles with subagent definitions or agent teams. Fix role boundaries in subagent definitions rather than CLAUDE.md, and enforce absolute rules with hooks. Organize official markdown-based auto memory before building a custom SQLite solution. Aim for 3–5 people per team and build up to 8 workers by adding layers.

3 steps to try starting today:

• [ ] Type claude --worktree test-1 to get a feel for launching an isolated session.
• [ ] Write one subagent definition for a "reviewer" role in .claude/agents/ and have it review your implementation.
• [ ] Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and try running a PR review in parallel with three teammates.

The time you spent constantly typing correction instructions in a single session will change into time spent designing and delegating roles. Deciding what to let go of and what to oversee is the most human job left in parallel operation.

Reference Links (Official Primary Sources)

• Create custom subagents
• Orchestrate teams of Claude Code sessions
• Run parallel sessions with worktrees
• How Claude remembers your project / CLAUDE.md and auto memory

I plan to share useful information that I can't post on X in this Open Chat. If you're interested, please join now.

https://t.co/90omRA4UQ7