Watch Claude Code agent teams work on a live board

What agent teams are, and where you can see them

Agent teams are off by default. Setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 turns them on. One session is the lead: it spawns teammates, each a separate Claude Code instance with its own context window, and they coordinate through a shared task list (pending, in progress, completed, with dependencies) and direct messages.

You watch a team from the lead's terminal: an agent panel under the prompt in the default in-process mode, or one pane per teammate with tmux or iTerm2. The team's task list is stored under ~/.claude/tasks/ on that machine. From another room, or from your phone, none of it is visible.

Why the Taskhold tools work inside a team

Claude Code's docs say a spawned teammate "loads the same project context as a regular session: CLAUDE.md, MCP servers, and skills." So when Taskhold is in your user or project MCP config, every teammate gets the taskhold_* tools and reads the same CLAUDE.md lines telling it to use them.

• Add the server with --scope user, so every session on the machine has it, including teammates started in any repo.
• An in-process teammate ignores the mcpServers field of a subagent definition and loads MCP servers from your project and user settings.
• If you define teammate roles with a subagent definition that has a tools list, Claude Code limits the teammate to that list. Include the Taskhold tools there (in Claude Code, MCP tools are named mcp__<server>__<tool>), or leave tools out.

Set it up

1. Connect Claude Code with a setup URL from Settings (see the quickstart). The setup URL uses --scope user.
2. Turn agent teams on in settings.json, as below.
3. Add the team lines below to the project's CLAUDE.md, next to the usual Taskhold workflow snippet. Teammates read CLAUDE.md when they start; they don't see the lead's conversation.
4. Open the live board at taskhold.com/dashboard/live, then ask the lead for a team as usual.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

## Agent teams and Taskhold
- Lead: before spawning teammates, taskhold_create one task per piece of work you hand out, and put its task id in that teammate's spawn prompt.
- Teammate: taskhold_start your task with agent set to "<your teammate name> (team)", taskhold_plan your steps, report taskhold_progress at milestones, and taskhold_complete with a one-line summary.
- A decision only the person can make: taskhold_block with the question, then check taskhold_updates for the reply. Questions for another teammate go by message, not Taskhold.

What the board shows while the team works

• A card per teammate's task with its label, elapsed time and the message from its last progress report.
• A progress bar split by the teammate's own steps, so you see which part is running.
• Questions under Needs you, answered from the board or your phone. See answer a blocked coding agent.
• A status dot that turns Quiet after two minutes without a report and No word after fifteen. Claude Code's docs list task status lag as a known limitation of teams, and that dot is where a stalled teammate shows up.

When the session ends, the tasks, notes and summaries stay in Taskhold, which is what reviewing what your agents did reads from.

Limits to know before you rely on it

• Agent teams are experimental, and spawning teammates needs an interactive session: with -p, a named subagent runs as an ordinary subagent.
• /resume and /rewind don't restore in-process teammates. The Taskhold tasks remain, so new teammates can pick them up with taskhold_get_current and taskhold_list.
• A session has one team, and teammates can't spawn teams of their own.
• Each teammate is a separate Claude instance, so token use grows with the size of the team.