TeamClaude

Stop flying blind with AI agent teams.
Real-time observability and structured sprints for Claude Code.

Multi-agent Claude Code sessions are powerful but opaque. You can't see what agents are doing, which tasks are stuck, how much they're costing, or whether the work is actually converging. TeamClaude fixes that with a live dashboard and a manager/engineer sprint workflow that keeps agents on track.

Get started

npx teamclaude init

This enables Agent Teams, scaffolds agents and commands into .claude/, and creates .teamclaude/ for sprint history. Then open Claude Code and type:

/sprint Add user authentication, fix payment bug, refactor database layer

The dashboard opens at http://localhost:3456 and streams everything live.

Prerequisites: Node.js 18+. Optional: tmux for live terminal views of each agent.

When to use TeamClaude

What you get

Live observability dashboard

See what every agent is doing, in real time.

• Agent topology with active/idle status — click any agent to view their live terminal (tmux) or message history
• Task board (list or kanban) with real-time status, protocol tags, and review round tracking
• Message feed showing inter-agent communication (TASK_ASSIGNED, READY_FOR_REVIEW, APPROVED, etc.)
• Token cost tracking per agent with estimated USD cost (model-aware pricing)

Structured sprint workflow

Agents don't just run — they follow a review loop.

1. Manager assigns tasks to engineers with context
2. Engineer implements and submits for review
3. Manager approves or requests changes (max 3 rounds)
4. If stuck after 3 rounds, it escalates to you

This prevents the common failure mode: agents running indefinitely without converging.

Sprint analytics and retros

Every sprint generates data.

• Retrospective — auto-generated markdown on sprint stop (summary, task results, team performance, improvement suggestions)
• Sprint history — completion rates, review rounds, velocity trends across cycles
• Sprint replay — re-watch any recorded sprint in the dashboard at adjustable speed
• Git integration — auto-creates sprint branches, generates PR summaries

Cost control

• Token budget — auto-pause when spend exceeds a threshold, with dashboard warnings at 80%
• Human checkpoints — pause before specific tasks for manual review
• Model routing — automatically assigns haiku/sonnet/opus per task based on complexity

Modes

Manual — you define the work

/sprint Add user auth, fix payment bug, refactor DB layer
/sprint path/to/ROADMAP.md

You see the parsed task list and approve before anything starts.

Autonomous — PM agent drives

/sprint

A PM agent analyzes the codebase, creates a roadmap, and hands it to the manager. Runs in continuous cycles until no issues remain.

Configuration

Auto-detects your project tooling from lockfiles and package.json. For explicit control, add .sprint.yml:

agents:
  model: sonnet              # haiku | sonnet | opus
  roles:                     # custom team composition
    - engineer
    - engineer
    - qa

sprint:
  max_review_rounds: 3

budget:
  max_tokens: 100000
  warn_at: 80000

verification:
  type_check: "npm run type-check"
  test: "npm test"

server:
  port: 3456

CLI

npx teamclaude init [--global] [--force]            # Scaffold into .claude/
npx teamclaude init --template <name|list>           # Use a pre-built template
npx teamclaude start [--port N]                      # Start server (default: 3456)
npx teamclaude replay <file.jsonl> [--speed N]       # Replay a recorded sprint

Alternative install

# Claude Code plugin marketplace
claude plugin marketplace add albertnahas/teamclaude
claude plugin install teamclaude@teamclaude

# Standalone server
npx teamclaude start

Custom roles: drop an agents/<role>.md file and reference it in .sprint.yml.

Agents communicate via structured prefixed messages:

WebSocket events: init, task_updated, message_sent, agent_status, token_usage, checkpoint, cycle_info, paused, escalation, terminal_output, panes_discovered, merge_conflict.

Drop a .js file into .teamclaude/plugins/:

export default {
  name: "notify",
  hooks: {
    onSprintStart(state) { console.log(`Sprint started: ${state.teamName}`); },
    onTaskComplete(task) { console.log(`Task done: ${task.subject}`); },
    onSprintStop(state) { console.log(`Sprint stopped`); },
  },
};

Hooks: onSprintStart, onTaskComplete, onEscalation, onSprintStop. Errors are caught — they never crash the server.

Auto-create issues from tasks and post retros as PR comments:

github:
  repo: "your-org/your-repo"
  pr_number: 42

Set GITHUB_TOKEN in your environment (needs issues:write and pull_requests:write).

~/.claude/teams/<team>/config.json     ──┐
~/.claude/teams/<team>/inboxes/*.json  ──┤  chokidar
~/.claude/tasks/<team>/*.json          ──┘  watches
                                           │
                                     ┌─────▼─────┐
              tmux (panes) ◄────────►│   server   │
              capture-pane           │ HTTP + WS  │
              send-keys              └─────┬──────┘
                                           │
                                     ┌─────▼─────┐
                                     │  browser   │
                                     │ xterm.js   │
                                     └────────────┘

The server watches Claude Code's native Agent Teams filesystem and streams deltas via WebSocket. When tmux is available, it polls panes for terminal output and relays keyboard input. On sprint stop, it records analytics, generates a retrospective, and creates a PR summary.

License

MIT