Running multiple Claude agents in VS Code

A working tutorial for going from one Claude Code chat to a coordinated stack of leads, project leads, and autonomous workers that talk to each other with SendMessage. Built around the daily-driver setup described by Daisy, an engineer on Claude Code, and checked against the current Claude Code docs.

Written for Tommy · FrameLogic Studio · August 2026 · Revision 3 (Aug 23), field-tested end-to-end and verified against Claude Code v2.1.240 (cross-session messaging: v2.1.224+, native Windows v2.1.234+). Agent teams are still marked experimental, so expect details to shift. A beginner companion edition (Brick Break project) exists separately.

Before you start · The mental model: three kinds of “agent”

Claude Code has three different mechanisms that people all call “agents.” Daisy's setup uses all three, stacked. Getting the vocabulary right up front saves a lot of confusion later.

How this maps onto Daisy's quote

• “Two lead agents that keep each other accountable” → two long-running sessions (two VS Code windows or terminals) using cross-session messaging to check in on each other.
• “Delegate to tech lead or PM agents for 8–10 projects” → one session per project, usually in its own git worktree. Leads message PMs; PMs never message the leads' teammates.
• “Each project has 5–10 IC agents” → each PM session has agent teams enabled and spawns a team of teammates. This is where the shared task list lives.
• “IC agents work autonomously for 2–3 days” → teammates with clear file ownership, 5–6 sized tasks each, plan approval for risky changes, and quality-gate hooks so they don't go idle on bad work.
• “All communicate with SendMessage” → the same tool serves all three layers: subagent resume, teammate messaging, and cross-session messaging.

0Install and enable everything

1. Install the standalone CLI. The VS Code extension bundles its own private copy of the CLI for the chat panel, but it does not put claude on your PATH. You need the standalone install to run claude in the integrated terminal, which is where most of the multi-agent work happens.

   # Native installer (recommended in the docs; avoids npm permission issues)
   curl -fsSL https://claude.ai/install.sh | bash   # macOS / Linux / WSL
   # or
   npm install -g @anthropic-ai/claude-code
   claude --version   # want 2.1.224+ (2.1.234+ on native Windows); 2.1.236+ for idle notices

2. Install the VS Code extension. Cmd/Ctrl+Shift+X → search “Claude Code” → install the one published by Anthropic (there are look-alikes). Needs VS Code 1.94+. Click the ✱ Claude Code item in the status bar, sign in with your Claude subscription. No API key needed.
3. Open the integrated terminal and run claude once. Ctrl+` (or Cmd+`), type claude, and inside the session run /ide if it didn't auto-connect. You'll know it's connected when Claude's edits open in VS Code's diff viewer. Run /terminal-setup once so Shift+Enter inserts a newline instead of sending.
4. Enable agent teams in your user settings. Open ~/.claude/settings.json (create it if missing) and add the env var. Adding the $schema line gives you autocomplete in VS Code.

   {
     "$schema": "https://json.schemastore.org/claude-code-settings.json",
     "env": {
       "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
       "CLAUDE_CODE_SUBAGENT_MODEL": "sonnet"
     },
     "teammateMode": "in-process"
   }

   CLAUDE_CODE_SUBAGENT_MODEL is the default for any subagent or teammate that doesn't name a model. (teammateDefaultModel was removed in v2.1.234 and is ignored if you still have it; delete it.) One side effect to know about: with the teams flag on, any subagent Claude decides to name launches as a teammate instead. If you ever see a delegation stall waiting for a result, that's why; flip the value to "0" and it takes effect without restarting.
5. Pre-approve the boring stuff. Teammate permission prompts bubble up to the lead, and with 5–10 teammates that gets noisy fast. Add a project-level .claude/settings.json that allows the commands your project uses constantly. Keep the deny list for anything destructive.

   {
     "permissions": {
       "allow": [
         "Read", "Edit", "Write", "Glob", "Grep",
         "Bash(npm test:*)", "Bash(npm run:*)", "Bash(node:*)",
         "Bash(git status:*)", "Bash(git diff:*)", "Bash(git add:*)",
         "Bash(git commit:*)", "Bash(git log:*)"
       ],
       "deny": [
         "Bash(git push --force:*)", "Bash(rm -rf:*)",
         "Read(.env)", "Read(.env.*)", "Read(**/.env)", "Read(**/.env.*)"
       ]
     }
   }

6. Verify. In a terminal session run /status (should show a “Peer address” row if cross-session messaging is available) and /list-agents (alias /peers; should run, and its first line is this session's own name). In the chat panel, type / and confirm you can see the permission mode switcher at the bottom of the prompt box.

1One session, subagents

A subagent is a Markdown file with YAML frontmatter. The frontmatter is the config (name, when to use it, tool allowlist, model); the body is its system prompt. Project-level files go in .claude/agents/; personal ones in ~/.claude/agents/. The description field is what Claude reads to decide whether to delegate, so make it specific.

Three roles to create

Create these in the practice project from the Gallery Proof section, or any repo you have handy.

# .claude/agents/explorer.md — read-only, cheap, fast
---
name: explorer
description: Read-only codebase investigation. Use when you need to find where something lives, how it's used, or what a module exports, without changing anything.
tools: Read, Grep, Glob
model: haiku
---
You are a codebase investigator. Answer with file paths, line numbers, and a short summary.
Do not propose changes. Do not read .env files.

# .claude/agents/implementer.md — writes code, runs tests
---
name: implementer
description: Implements a clearly scoped feature or fix in a specific set of files, with tests. Use when the files to change are already known.
tools: Read, Edit, Write, Grep, Glob, Bash, SendMessage
model: sonnet
---
You implement exactly the scope you were given, in exactly the files you were given.
Before finishing: run `npm test`. If tests fail, fix them or report precisely why you couldn't.
Never edit files outside your assigned list. If you need a change elsewhere, say so instead of making it.

# .claude/agents/reviewer.md — read-only critic
---
name: reviewer
description: Reviews a diff or a set of files for correctness, security, and test coverage. Use after code is written and before it is merged.
tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*), SendMessage
model: sonnet
---
You are a senior reviewer. Run `git diff` to see what changed. Report findings as
Critical / Warning / Suggestion, each with file:line and a one-sentence fix. Be specific and brief.

Try it

In the VS Code chat panel or the terminal session:

What to notice: each subagent runs in its own context window and hands back a summary, so your main conversation stays clean. That isolation is the entire reason subagents exist; the main session's context is the scarce resource.

2Your first agent team (review only)

1. Start a terminal session in the repo. claude in the integrated terminal. (The graphical chat panel also supports teams, but the terminal's agent panel gives you the clearest view of who's doing what while you're learning.)
2. Ask for a team explicitly. Claude sometimes spawns subagents when you meant teammates; say “agent team” and “teammates.”
   Prompt

   Create an agent team to review the current state of this repo. Spawn three teammates named security, performance, and tests, using Sonnet for each: - security: look for auth, input-validation, and secrets-handling problems - performance: look for N+1 queries, unbounded reads, and anything that won't scale past a few hundred galleries - tests: assess what's covered, what isn't, and which untested paths are riskiest Have them message each other when one finds something relevant to another's area, then each report findings to you with severity. Wait for all three before you synthesize.
3. Watch the agent panel. Teammates appear below the prompt box. ↑/↓ selects one, Enter opens its transcript so you can read it and message it directly, Esc interrupts its current turn, x stops it, Ctrl+T toggles the shared task list. Since v2.1.199 an idle row stays put while any agent is still working; rows hide 30 s after the whole panel goes idle, and more than three idle rows collapse into one “N idle agents” row (Enter expands).
4. Message a teammate directly. Select tests, press Enter, and type: “Also check whether the upload route has any test at all.” Plain text and skills go to that teammate; built-in slash commands still run in the lead's session.
5. Read the synthesis, then shut down. “Ask all teammates to shut down.” Team directories clean up automatically when your session ends.

What just happened under the hood

• Each teammate is a full Claude Code session: it loaded CLAUDE.md, your MCP servers, and skills, but not the lead's conversation history. Everything it knows about the job came from the spawn prompt.
• Messages were written to per-agent inbox files under ~/.claude/teams/<session-xxxxxxxx>/inboxes/ and delivered automatically; nobody polls.
• When a teammate finished, the lead got an idle notification without the output. Results only travel by message or by task-list updates. That's why the prompt says “report findings to you.” (From v2.1.198, a teammate that dies on an API error reports the failure and error text instead of looking finished.)
• Teammates inherited the lead's permission mode. Prompts they trigger show up in your lead session for you to approve.

3A team that builds

Habit 1 — file ownership, written down

Two teammates editing one file produces overwrites. The fix is not cleverness; it's an explicit ownership map in the spawn prompt and in the task list. The practice project below is laid out so that each module is a separate directory precisely to make this easy.

Habit 2 — plan approval for anything that touches shared contracts

Tell the lead to require plan approval for the teammate whose work others depend on (usually the data layer or the API contract). The teammate stays in read-only plan mode until the lead approves. The lead approves autonomously, so give it criteria: “only approve plans that list the exact files to be changed and include test coverage.”

Habit 3 — hooks that refuse bad completions

Three hook events exist specifically for teams. Exit code 2 sends feedback and keeps the agent working.

# .claude/settings.json (project) — gate task completion on green tests
{
  "hooks": {
    "TaskCompleted": [
      { "hooks": [ { "type": "command",
        "command": "npm test --silent >/tmp/cc-test.log 2>&1 || { echo 'Tests failed. Fix them before completing this task:'; tail -30 /tmp/cc-test.log; exit 2; }" } ] }
    ],
    "TeammateIdle": [
      { "hooks": [ { "type": "command",
        "command": "if [ -n \"$(git status --porcelain)\" ]; then echo 'You have uncommitted changes. Commit to your branch and message the lead with a summary before going idle.'; exit 2; fi" } ] }
    ]
  }
}

The build prompt

Run this in the practice project after Level 2. It's long on purpose; teammates only know what the spawn prompt tells them.

While it runs

• Open Ctrl+T and watch tasks move pending → in progress → completed. Dependent tasks unblock automatically.
• If the lead starts coding, tell it: “Wait for your teammates to complete their tasks before proceeding.”
• If a task looks stuck, check whether the work is actually done (task status can lag) and nudge the owner by name.
• When done, you merge the four branches yourself, or ask the lead to. Keep the human on merges and releases; that's the 5% of your day that matters most.

4The Daisy stack: leads, PMs, cross-session messaging

Everything in Levels 1–3 happened inside one session. Daisy's setup is many sessions, arranged in layers, each started by you. Here's the layout for two projects; add more PM windows for more projects.

VS Code window 1 ─ lead-a      claude --name lead-a                             (repo root, no team; it coordinates)
VS Code window 2 ─ lead-b      claude --name lead-b                             (repo root, no team; mirrors lead-a)
VS Code window 3 ─ pm-gallery  claude --worktree gallery-proof --name pm-gallery (own checkout; runs a team)
VS Code window 4 ─ pm-site     claude --worktree site-refresh  --name pm-site    (own checkout; runs a team)
…one window per project

Step-by-step

1. One worktree per project. Each PM session gets an isolated checkout and branch so teams can't collide across projects. claude --worktree <name> creates it under your repo and starts the session there. Name every session so messages have stable addresses; /rename works too. If two live sessions would share a name, Claude Code renames the newer one to a variant, and /list-agents shows each session's working directory so you can tell them apart.
2. Open one VS Code window per session. File → New Window, open the worktree folder, integrated terminal, start claude with the name. (Tabs in the chat panel also work for the leads, but separate windows make it obvious which agent you're typing at, and you'll be switching windows all day.) Use the Activity Bar session list's groups to keep “leads,” “PMs,” and “scratch” separate.
3. Confirm they can see each other. In any session: /list-agents. The first line is this session's own name; below it are the other local sessions with state, age and directory. If the command isn't recognized, you're below v2.1.224 (or v2.1.234 on native Windows).
4. Give each PM a standing brief. This is the project's charter. It goes in the PM session's first prompt and, for anything durable, into that worktree's CLAUDE.md.
   Prompt — to pm-gallery

   You are the project lead for Gallery Proof. Your job is to run an agent team that delivers the milestones in docs/ROADMAP.md, in order, one milestone per team run. You never implement; you plan, spawn teammates with explicit file ownership, require plan approval for db changes, keep 5–6 tasks per teammate, and merge completed branches into this worktree's branch after qa signs off. Reporting: when a milestone completes or you are blocked for more than one task cycle, message lead-a with a 5-line status (milestone, done, blocked, next, risk). If lead-a does not reply within one cycle, message lead-b. Do not message the other project leads. Start milestone 1 now.
5. Give the leads their accountability loop. Leads hold no team; they coordinate.
   Prompt — to lead-a (mirror it for lead-b, swapping names)

   You are lead-a. Your peers are lead-b and the project leads pm-gallery and pm-site. Your responsibilities: 1. Keep a running status board in docs/STATUS.md (one line per project) from the status messages PMs send you. 2. Every time you receive a PM status, decide: approve next milestone, ask a question, or escalate to me. Escalate only for scope changes, spend concerns, or anything touching billing or customer data. 3. Accountability with lead-b: after each status update, message lead-b a one-line ping. If you receive no ping from lead-b across two PM updates, or lead-b reports an error, tell me immediately and include the last thing you heard from lead-b, so I can restart it. 4. When you approve a milestone for a PM, ask to be notified when that PM session next goes idle, so you hear about completion without polling. 5. Never approve your own permission prompts via another agent; anything that needs consent comes to me.
6. Run it for a day. Your interaction pattern should start to look like Daisy's: most prompts go to a lead, a third go to a PM when you care about the details of one project, and occasionally you're in an IC's transcript because something went sideways. From v2.1.232 you can address a session directly in any prompt with an @-mention: “Let @pm-site know the shared auth helper changed.” Type @ plus a letter or two and pick the session from the typeahead.

About “restart the other if either fails”

This is the part of Daisy's setup that the public docs don't spell out, so here's a clear-eyed version of what you can and can't do today.

Practice project · Gallery Proof — a small app built to be split

A throwaway client-proofing app for photographers: upload a gallery, share a link, client marks favorites, photographer sees the picks. Close enough to your real world that the decisions feel real, small enough to build in an afternoon, and deliberately laid out so four to six agents can work without touching each other's files.

Stack

Node 20 + Express, SQLite via better-sqlite3, vanilla HTML/JS frontend served statically, Node's built-in test runner (node --test). No build step, no framework decisions to argue about, tests run in under a second, which matters when a hook runs them on every task completion.

Layout (ownership boundaries are directories)

gallery-proof/
├── CLAUDE.md                ← conventions every agent reads
├── .claude/
│   ├── settings.json        ← permissions + hooks from Level 0 / Level 3
│   └── agents/              ← explorer.md, implementer.md, reviewer.md
├── docs/
│   ├── ROADMAP.md           ← milestones (below)
│   ├── STATUS.md            ← leads write here
│   └── specs/               ← one spec per feature
├── src/
│   ├── db/                  ← schema.sql, migrate.js, repositories/*.js
│   ├── api/                 ← routes.js + one folder per resource
│   ├── web/                 ← static pages + client JS
│   └── server.js            ← wires api + static
├── tests/
│   ├── unit/                ← per-module
│   └── integration/         ← end-to-end over HTTP
└── package.json

Bootstrap it

Let a single session scaffold it. Spend the prompt on conventions, not code.

Roadmap (one milestone per team run)

The spec that teammates will read

Teammates only know what's in the spawn prompt plus the files they read, so specs need to be concrete. Example for M2:

# docs/specs/favorites.md
## Goal
A client with a valid share token can mark/unmark images as favorites.
The photographer sees a "Favorites (n)" view per gallery.

## Data
favorites(gallery_id, image_id, created_at) — unique on (gallery_id, image_id)

## API
POST   /api/galleries/:token/favorites/:imageId → 201 {imageId}
DELETE /api/galleries/:token/favorites/:imageId → 204
GET    /api/galleries/:token/favorites          → 200 {imageIds:[...]}
All three 404 on unknown token. Token check reuses src/api/share/auth.js.

## Web
Heart toggle on each image in gallery.html; favorites.html lists picks.

## Tests
Unit: repository functions. Integration: all three endpoints incl. 404s.

CLAUDE.md — the part that does the most work

# Gallery Proof — conventions for every agent
## Boundaries (hard rules)
- src/db: all SQL lives here. Exposes repository functions only.
- src/api: HTTP only. Calls repositories. No SQL.
- src/web: static files. Talks to /api only.
- tests: node --test. Unit tests mirror src/ paths.

## Working agreement
- One branch per teammate: feat/<milestone>-<name>. Conventional commits.
- Run `npm test` before marking any task complete. Failing tests = not complete.
- Never edit files outside your assigned ownership. Message the owner instead.
- Report results by messaging the lead; going idle is not a report.
- Never read .env files. Never run git push --force.

Day to day · Operating the stack

Checklist before letting a team run unattended

• Ownership map is in the task list and in the spawn prompt.
• TaskCompleted hook runs tests; TeammateIdle hook demands a commit and a report.
• Plan approval is on for the data layer.
• Permissions allowlist covers routine commands; deny list covers the destructive ones.
• Every agent has a name you chose.
• The PM's reporting protocol names a lead and a fallback lead, and the lead subscribes to idle notices instead of polling.
• Merges and releases stay with you.

Field notes from the first real run

This guide was walked end-to-end on a MacBook Pro against Claude Code v2.1.240 before being published. Everything worked; these are the trip-wires that actually fired, so you can step over them.

When it goes sideways · Troubleshooting

Verified against · Sources

• Orchestrate teams of Claude Code sessions — code.claude.com/docs/en/agent-teams (enable flag, display modes, plan approval, hooks, architecture, limitations, troubleshooting)
• Use Claude Code in VS Code — code.claude.com/docs/en/vs-code (extension install, bundled vs standalone CLI, tabs/windows, session groups, settings, worktrees)
• Message your other Claude Code sessions — code.claude.com/docs/en/cross-session-messaging (ListAgents/SendMessage, platform support, @-mentions, idle notices, inbound controls, throttling)
• Create custom subagents — code.claude.com/docs/en/sub-agents (frontmatter fields, scopes, model selection)
• Claude Code docs index — code.claude.com/docs/llms.txt

Credits. Written by Tommy Waddell (FrameLogic Studio) with Claude (Anthropic). Multi-agent architecture based on the daily-driver workflow described by Daisy, an engineer on the Claude Code team, as quoted in an Anthropic email newsletter (2026). Verified against Claude Code v2.1.240, August 2026. Agent teams are experimental — trust your screen over this document where they differ.

Agent teams are experimental and the docs note version-specific behaviour changes almost weekly. When something here disagrees with what you see on screen, trust the screen and re-check the docs page.