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.
npx teamclaude initThis 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.
| Good fit | Not a good fit |
|---|---|
| Multi-task sprints (3+ related tasks) | Single quick fixes or one-liners |
| Feature batches with review cycles | Exploratory research or brainstorming |
| Bug-bash sessions across a codebase | Tasks requiring constant human decisions |
| Refactoring with test validation | Projects without tests or type-checking |
| Autonomous overnight/background work | Highly sensitive code needing line-by-line review |
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)
Agents don't just run — they follow a review loop.
- Manager assigns tasks to engineers with context
- Engineer implements and submits for review
- Manager approves or requests changes (max 3 rounds)
- If stuck after 3 rounds, it escalates to you
This prevents the common failure mode: agents running indefinitely without converging.
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
- 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
/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.
/sprint
A PM agent analyzes the codebase, creates a roadmap, and hands it to the manager. Runs in continuous cycles until no issues remain.
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: 3456npx 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# Claude Code plugin marketplace
claude plugin marketplace add albertnahas/teamclaude
claude plugin install teamclaude@teamclaude
# Standalone server
npx teamclaude startAgent roles
| Agent | Role |
|---|---|
| sprint-pm | Analyzes codebase, creates roadmaps, validates results. Never writes code. (Autonomous mode only) |
| sprint-manager | Delegates tasks, reviews code, drives sprint to completion. Never writes code. |
| sprint-engineer | Implements features, fixes bugs, writes tests. Submits work for review. |
| sprint-qa | Validates acceptance criteria, runs tests, reports defects. Never writes code. |
| sprint-tech-writer | Updates docs, changelogs, inline comments. Never writes code. |
Custom roles: drop an agents/<role>.md file and reference it in .sprint.yml.
Message protocol
Agents communicate via structured prefixed messages:
| Prefix | Direction | Meaning |
|---|---|---|
TASK_ASSIGNED: |
Manager → Engineer | Task delegated with context |
READY_FOR_REVIEW: |
Engineer → Manager | Work submitted for review |
APPROVED: |
Manager → Engineer | Work accepted, task complete |
REQUEST_CHANGES: |
Manager → Engineer | Feedback with round counter (N/3) |
RESUBMIT: |
Engineer → Manager | Revised work after feedback |
ESCALATE: |
Either → Human | Stuck after 3 rounds |
ROADMAP_READY: |
PM → Manager | Sprint tasks created (autonomous) |
SPRINT_COMPLETE: |
Manager → PM | All tasks done (autonomous) |
ACCEPTANCE: |
PM → Manager | Validation pass/fail (autonomous) |
REST API
| Endpoint | Method | Description |
|---|---|---|
/api/state |
GET | Full sprint state snapshot |
/api/launch |
POST | Launch a sprint ({ roadmap, engineers, includePM, cycles }) |
/api/stop |
POST | Stop sprint, record analytics, generate retro + PR summary |
/api/pause |
POST | Toggle pause/resume |
/api/resume |
POST | Resume persisted sprint after server restart |
/api/process-status |
GET | Running process info (PID, startedAt) |
/api/analytics |
GET | Sprint history (?cycle=N&limit=N&format=csv) |
/api/retro |
GET | Last retrospective (?format=json) |
/api/retro/gist |
POST | Publish retro to GitHub Gist |
/api/retro/diff |
GET | Diff two sprints (?a=<id>&b=<id>) |
/api/history |
GET | All sprint history entries |
/api/history/:id/retro |
GET | Retro for a past sprint |
/api/velocity.svg |
GET | Velocity chart SVG (?w=N&h=N) |
/api/plan |
GET | Task dependency analysis + model routing |
/api/task-models |
GET | Model routing per task |
/api/git-status |
GET | Branch status |
/api/checkpoint |
POST | Set human checkpoint ({ taskId }) |
/api/checkpoint/release |
POST | Release pending checkpoint |
/api/templates |
GET | Available sprint templates |
/api/memories |
GET/POST | Agent memory store (?role=X&q=query) |
/api/memories/:id |
DELETE | Delete a memory |
WebSocket events: init, task_updated, message_sent, agent_status, token_usage, checkpoint, cycle_info, paused, escalation, terminal_output, panes_discovered, merge_conflict.
Plugin API
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.
GitHub integration
Auto-create issues from tasks and post retros as PR comments:
github:
repo: "your-org/your-repo"
pr_number: 42Set GITHUB_TOKEN in your environment (needs issues:write and pull_requests:write).
How it works
~/.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.
MIT