How to Build a Multi-Agent AI Team with Claude Code

1. Why multi-agent?

A single Claude agent is powerful, but it has limits. Context windows fill up. Long projects lose earlier decisions. Parallel tasks block on each other. The multi-agent pattern solves this by splitting work across specialized agents: one orchestrates, others execute narrowly defined roles.

In practice this looks like: an orchestrator agent that plans and delegates, a coder agent that writes and runs code, a researcher agent that searches the web, and a writer agent that produces documents. Each agent has a focused context and can work in parallel. Once you have the basics working, our Claude Code agent teams setup guide walks through the coordination layer in more depth.

Claude Code's subagent architecture — where the main agent spawns child tasks via the Task tool — makes this pattern native. You do not need to build a custom orchestration framework.

2. Install Claude Code

Claude Code requires Node.js 18+. On macOS:

# Install Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install nodejs

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Verify
claude --version

On Linux (including WSL on Windows), replace the Homebrew steps with your package manager. Claude Code itself is cross-platform once Node.js is in place.

Authentication is handled via claude auth on first run, which opens a browser to complete OAuth with your Anthropic account. If you do not have a Claude subscription yet, you will need one — we cover the cost angle in section 9.

3. Create a Telegram Bot (optional interface)

Running agents from a terminal is fine for development, but inconvenient on mobile or when you want to hand tasks off mid-day. Wiring Claude Code to a Telegram Bot gives you a conversational interface accessible from anywhere.

To create a bot: open Telegram, search for @BotFather, send /newbot, give it a display name and a username ending in _bot. BotFather returns a token — save it.

The bridge between Claude Code and Telegram is handled during the onboarding wizard (next section), which accepts your bot token and sets up a persistent gateway process. After that, messages you send to the bot are routed to your local Claude Code instance, and responses come back through the same channel.

This pattern also works with Slack and Discord via community MCP servers, though Telegram is the easiest starting point — no workspace permissions or OAuth app setup required.

4. Run the onboarding wizard

Claude Code ships with an interactive setup wizard that configures your model provider, communication channel, and initial Skills in one pass:

claude onboard --install-daemon

The wizard asks you to choose a model (Claude, GPT-4o, Gemini), a communication channel (Telegram, CLI, or web UI), and whether to install default Skills. Choose QuickStart for the fastest path.

For the model step: Claude Sonnet 4.5 is the default and a strong choice — it balances speed and quality well for orchestration tasks. If you want maximum capability for the orchestrator role and are willing to pay more per token, Claude Opus 4.5 is the alternative.

When prompted for a communication channel, paste the Telegram bot token from the previous step. The wizard spins up a gateway process and confirms the connection. After setup, send any message to your bot — you should see Claude respond within a few seconds.

5. Add persistent memory

By default, Claude Code has no memory between sessions — every conversation starts fresh. For agent teams handling ongoing projects, this is a hard limitation. The standard fix is a MEMORY.md file.

Create it in your project directory:

# MEMORY.md — Agent persistent state

## Current project
- Goal: Build a SaaS backlink audit tool
- Stack: Next.js 15, Supabase, Cloudflare Workers

## Decisions made
- Using Ahrefs API (not Moz) — rate limits are better
- Authentication: NextAuth with Google OAuth

## Tasks completed
- [x] Database schema designed
- [x] Auth flow implemented

## In progress
- [ ] Ahrefs API integration (assigned to coder-agent)

## Notes
- Ahrefs API key stored in .env.local (never commit)
- Staging URL: https://staging.myapp.com

Tell your orchestrator agent to read MEMORY.md at session start and append any decisions or progress at session end. You can encode this as a Skill (see next section) so it happens automatically.

For more structured memory, the mem0 MCP server provides semantic search over past interactions. Browse the available memory Skills on our SkillsMap directory — filter by the "Memory" category.

6. Install Skills

Skills are markdown files stored in ~/.claude/skills/ that give agents specific instructions. Think of them as reusable system prompts for recurring task types.

Installing a Skill from GitHub:

# Install the sequential-thinking Skill
claude skills install https://github.com/anthropics/claude-code-skills

# Or copy manually
curl -o ~/.claude/skills/sequential-thinking.md   https://raw.githubusercontent.com/.../sequential-thinking.md

For a multi-agent setup, a useful starter set of Skills includes — and if you want a broader survey of what's available, our roundup of the best Claude Code skills covers 349 ranked by community adoption:

You can browse 349+ ranked Skills across 12 categories on our SkillsMap directory, sorted by GitHub stars so the most-adopted ones surface first.

7. Spawn sub-agents

Once your orchestrator is running, you trigger sub-agents using the Task tool natively built into Claude Code. From the orchestrator's perspective:

# In CLAUDE.md (orchestrator instructions):
When working on a feature, always:
1. Use /sequential-thinking to plan
2. Spawn a sub-agent via Task tool for implementation
3. Spawn a second sub-agent for code review
4. Only merge when both sub-agents complete

# The Task tool usage in practice:
# "Implement the Ahrefs API integration described in MEMORY.md.
#  Use the tdd-guide Skill. Write tests first."
# Claude spawns a child agent, runs it, returns results.

Sub-agents inherit the parent's working directory but not its conversation history. They receive a specific prompt, execute, return output, and terminate. This keeps each agent's context clean and allows genuinely parallel execution when tasks are independent.

A practical pattern for the orchestrator's CLAUDE.md:

# CLAUDE.md — Orchestrator

## Team structure
- Orchestrator (me): planning, delegation, memory management
- Coder sub-agent: implementation, tests (uses: tdd-guide, code-review)
- Researcher sub-agent: web search, summarization (uses: web-search)
- Writer sub-agent: documentation, blog posts (uses: content-writer)

## Rules
- Read MEMORY.md at start of every session
- Update MEMORY.md before ending every session
- Never implement directly — always delegate to Coder sub-agent
- Parallelise independent tasks with simultaneous Task calls

8. Safety guardrails

Multi-agent setups amplify both capability and risk. A misconfigured agent with filesystem access can delete files or expose credentials. A few rules that save pain:

• 1.
  Never store API keys in MEMORY.md or CLAUDE.md. Reference environment variables only. CLAUDE.md is checked into git by default — treat it as public.
• 2.
  Use allowlists for filesystem access. Claude Code's permission model lets you restrict which directories agents can modify. Set the working directory to your project root, not ~.
• 3.
  Require explicit confirmation for destructive operations. Add a rule to your orchestrator: "Before running any rm, DROP TABLE, or force-push, pause and confirm with the user."
• 4.
  Cap token budgets per sub-agent. Without limits, a looping agent can exhaust your monthly Pro quota in an afternoon. Use --max-tokens per Task invocation.
• 5.
  Log all agent actions. Claude Code writes a session log by default. Point a monitoring Skill at it to alert you if an agent takes unexpected actions.

9. Managing token costs

This is where multi-agent setups can get expensive fast. Every sub-agent call consumes tokens — the orchestrator's context, the sub-agent prompt, and the sub-agent response all count. A moderately complex coding task that spawns 3 sub-agents might use 50K–150K tokens per session. For context on how Claude Code stacks up against competing tools on this front, see our AI coding tools overview.

Claude Pro at $20/month includes roughly 5× the rate limits of the free tier, which is enough for light multi-agent experimentation. Claude Max at $100/month is where heavy orchestration becomes practical — it raises limits to 5× again and includes early access to longer context features.

If you want to experiment with Claude Pro without the full monthly commitment, GamsGo offers group subscription plans that bring Claude Pro, ChatGPT Plus, and other AI tool costs down by 30–70%. It is worth checking before committing to a solo plan — particularly useful when you are testing multi-agent setups and not yet sure what your actual monthly token usage will be.

Practical cost reduction tips:

• Use Claude Haiku 4.5 for researcher sub-agents (web search, summarization) — it is ~10× cheaper and fast enough for retrieval tasks
• Use Claude Sonnet 4.5 for the orchestrator and writer roles
• Reserve Opus 4.5 for architecture decisions and one-off complex reasoning tasks
• Set explicit context limits in each sub-agent's prompt to avoid runaway consumption
• Cache repeated context (project stack, coding conventions) in CLAUDE.md rather than re-explaining in each prompt

FAQ