How to run a multi-agent team in Claude Code

One Claude Code session doing everything gets messy fast. A better setup is a small team of subagents with clear roles: a Scrum Master that plans, a Tech Lead that writes the contract and reviews, a Developer that builds and a QA agent that tests. This guide shows how to set that up in one command with AgenticSquad.dev, and how to watch the team work.

What you get

• A Scrum Master (tech-pm) you talk to. It sizes each request, picks the platform team and writes the cards.
• One team per platform for Web, Android and iOS, each with a Tech Lead, Developer and QA.
• A Kanban board where every brief, decision and result lives on the cards, moving from Backlog to In Progress, Review and Done.
• A live office view in your browser that shows who is working on which card and every handoff between agents.

Step 1: Install it in your project

You need Node.js. Open a terminal, go to your project folder and run the command. There is nothing to install globally and it takes under 5 seconds.

cd your-project
npx agenticsquad

The portal opens in your browser at http://localhost:3000 (or the next free port). If the project has no team yet, the setup screen lets you pick a Web, Android or iOS team, or all three, and you can change roles later in Team Studio.

Step 2: Let it write the agent files

Your team is stored as plain Markdown and YAML in .agents/. One command writes it out in the format each AI tool reads:

npx -p agenticsquad agents sync

Edit a role once, run npx -p agenticsquad agents sync again, and every tool gets the same change. npx -p agenticsquad agents validate and npx -p agenticsquad agents doctor check the setup for missing skills and delegation loops.

Step 3: Ask Claude Code as usual

Describe the work in your normal Claude Code session. The session hands the request to the Scrum Master, which decides how big it is:

• Small change (one to three files, no change to a shared type, API or stored data): one card goes straight to the platform's Developer, and the Tech Lead reviews it.
• Bigger change: the Tech Lead splits it into contracts for the Developer and hands testing to QA. QA records pass or fail for every acceptance criterion, and the Tech Lead reviews against the contract.

Each agent reads its own card instead of a long pasted prompt, which keeps every subagent's context small and focused.

Step 4: Watch the team work

The portal reads Claude Code's own session history for the project (~/.claude/projects/, including subagents and worktrees), so there is nothing to add to Claude Code. You can see:

• the floor plan, with agents walking cards to each other;
• the Kanban board with timestamps and assignees;
• the handoff stream with the exact brief each agent received;
• the tools each agent used, the code it changed, and work time and tokens per role.

Is it private?

Yes. The portal only listens on 127.0.0.1 and reads files on your machine. Your code, file paths, card text and tokens are never sent anywhere. It sends anonymous usage statistics, which you can turn off in Settings or with VO_ANALYTICS=off npx agenticsquad.

Not using Claude Code?

The same team works in OpenAI Codex, Gemini and Antigravity, and OpenCode, including local models through OpenCode. Run the same command and ask in your usual tool.