Claude Code agent teams

Tie every teammate's Claude Code agent team to one PugBase plan: no two people's teams take the same task, a task only closes when PugBase says it is done, and idle teammates pick up the next task.

Why

A Claude Code agent team keeps its task list on one machine. Two people can each start a team on the same plan task and never find out. These hooks send the team's task events to PugBase, where the plan is shared by the whole team.

Before you start

Claude Code with agent teams turned on (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) and the task tools turned on (CLAUDE_CODE_ENABLE_TODO_TOOLS=1). Newer models leave the task tools off, and without them a team coordinates by messages only - no task events, so the hooks never fire. The settings below set both.
PugBase connected over MCP in this project - the hook reads the key from the project's .mcp.json. Claude Code installation
Node.js 18 or newer on each machine.

Install (once per project)

Download the hook script into the project:

mkdir -p .claude/hooks
curl -fsSL https://pugbase.io/hooks/pugbase-hook.mjs -o .claude/hooks/pugbase-hook.mjs

Add the hooks to .claude/settings.json and commit both files, so every teammate gets them:

{
  "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1", "CLAUDE_CODE_ENABLE_TODO_TOOLS": "1" },
  "hooks": {
    "TaskCreated": [
      { "hooks": [{ "type": "command", "command": "node .claude/hooks/pugbase-hook.mjs", "timeout": 30 }] }
    ],
    "TaskCompleted": [
      { "hooks": [{ "type": "command", "command": "node .claude/hooks/pugbase-hook.mjs", "timeout": 30 }] }
    ],
    "TeammateIdle": [
      { "hooks": [{ "type": "command", "command": "node .claude/hooks/pugbase-hook.mjs", "timeout": 30 }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "node .claude/hooks/pugbase-hook.mjs", "timeout": 30 }] }
    ]
  }
}

Teammates with a key that is not tied to one workspace also set PUGBASE_WORKSPACE to the workspace id.

Link team tasks to the plan

Put the PugBase note id of the plan task in the task subject or description, as [pb:<noteId>]. The lead gets the ids from get_plan_spec or next_action. Tasks without a tag still work - they are just not tied to the plan.

Spawn two teammates. Give each one a task from the PugBase plan and put
the note id in the subject, e.g. "Backend - Auth [pb:5G8WCgZLzPF5zrRo9bPi]".

What each hook does

TaskCreated - takes the linked plan task for your team. If another person's agent is working it, the task is not created and the lead is told who has it. A task on a finished or missing note is refused too.
TaskCompleted - the task cannot close while the note has open or QA-reopened items. The agent is told which items, and ticks them with mark_task_done and its evidence.
TeammateIdle - a teammate about to stop is sent to the plan's next free task, twice at most for the same task, then left to rest.
Stop - when a session ends while your agent still holds plan notes, its last message is written into each of them as a dated handoff, so the next agent starts from what was actually said. Works in any Claude Code session, not only agent teams; never blocks.

If something goes wrong

A missing key, a network error or PugBase being down never blocks your session - the hook lets the action through.
Nothing happens on a task: check that its subject has [pb:<noteId>] and that the key belongs to this workspace.
Your own teams never block each other - only another member's agents do.