team-monitor

name	team-monitor
description	Real-time team performance tracking, status reporting, and bottleneck detection. Use to check team health, track progress, identify stalled work, and optimize team throughput.

Team Monitor

Track team performance, surface blocked work, and keep multi-agent teams running at full capacity.

When to Use

• You need a quick snapshot of what every member is doing.
• You want to know whether the team is on track or falling behind.
• Something feels stuck and you need to find out where the bottleneck is.
• You are deciding whether to reassign work, unblock a dependency, or add capacity.

Tools

Quick Status -- team_status.py

python scripts/team_status.py              # list every team
python scripts/team_status.py my-team      # full status for one team

Reads ~/.claude/teams/{name}/config.json and ~/.claude/tasks/{name}/*.json.

Output sections:

1. Team info -- name, member count, task count.
2. Member table -- name, role (agentType), model, color, assigned tasks, completed tasks.
3. Task summary -- totals for pending, in_progress, completed, and blocked.
4. Task list -- each task on one line with a status icon:
   • [completed] completed
   • [in_progress] in progress
   • [pending] pending
   • [blocked] blocked (has unresolved blockedBy)
5. Warnings -- members with zero tasks, tasks with unknown owners, tasks blocked by nonexistent IDs.

Example output:

=== Team: backend-crew (4 members, 12 tasks) ===

Members
  Name            Role              Model                    Color   Assigned  Done
  ─────────────────────────────────────────────────────────────────────────────────
  team-lead       architect-review  claude-opus-4-6          green        4     2
  frontend-dev    frontend-developer claude-sonnet-4-5       yellow       3     1
  backend-dev     backend-architect claude-sonnet-4-5        purple       3     0
  tester          test-automator    claude-sonnet-4-5        orange       2     2

Task Summary
  Total: 12 | Pending: 3 | In Progress: 4 | Completed: 5 | Blocked: 0

Tasks
  [completed] TASK-001  Set up project scaffolding          (alice)
  [completed] TASK-002  Design database schema               (alice)
  [in_progress] TASK-003  Implement auth module                (bob)
  [pending] TASK-004  Write integration tests              (carol)
  ...

Warnings
  ! carol has 0 completed tasks out of 3 assigned

Progress Analysis -- task_progress.py

python scripts/task_progress.py my-team

Calculates quantitative metrics and outputs an at-a-glance report.

Output sections:

1. Overall completion -- percentage and ASCII progress bar.
2. Per-member breakdown -- each member's assigned / completed / in-progress / pending counts plus their individual completion rate.
3. Workload balance score -- 0 to 100. 100 means perfectly even distribution; lower means some members are overloaded while others are idle.
4. Blocked chain analysis -- for each blocked task, the full chain of upstream blockers.
5. Recommendations -- plain-language suggestions based on the numbers.

Example output:

=== Progress: backend-crew ===

Overall: 41.7% [========..............] 5/12

Per-Member Breakdown
  Name       Assigned  Done  In Prog  Pending  Rate
  ────────────────────────────────────────────────────
  team-lead       4      2       1        1    50.0%
  frontend-dev    3      1       1        1    33.3%
  backend-dev     3      0       1        2     0.0%
  tester          2      2       0        0   100.0%

Workload Balance: 72/100 (acceptable)

Blocked Chains
  TASK-009 <- TASK-007 <- TASK-003
    Root cause: TASK-003 (in_progress, owner: bob)

Recommendations
  - backend-dev has 0% completion rate -- consider lighter assignments or pairing.
  - tester is idle with all tasks done -- reassign pending work from backend-dev.
  - Unblock TASK-003 to release 2 downstream tasks.

Bottleneck Detection -- bottleneck_detector.py

python scripts/bottleneck_detector.py my-team

Performs deeper structural analysis of the task graph.

Detected issues, by severity:

Severity	Label	Conditions
CRITICAL	Circular dependency	Task A blocks B blocks ... blocks A
CRITICAL	Overloaded member	More than 3 tasks with status in_progress
CRITICAL	Long blocked chain	Chain of 3+ blocked tasks
WARNING	Stalled task	in_progress task whose file mtime is older than 30 minutes
WARNING	Orphaned task	Task whose owner does not match any team member
WARNING	Unresolved blocker	blockedBy references a task ID that does not exist
INFO	Idle member	Member with 0 assigned tasks or all tasks completed
INFO	Single point of failure	One member owns more than 50% of remaining work

Output sections:

1. Issue list -- severity icon, category, description, affected task/member.
2. Dependency graph -- ASCII rendering of which tasks block which.
3. Summary counts -- total critical / warning / info.

Example output:

=== Bottleneck Report: backend-crew ===

Issues
  [CRITICAL] Overloaded member: frontend-dev has 4 tasks in_progress
  [WARNING]  Stalled task: TASK-003 (last modified 47 min ago)
  [WARNING]  Orphaned task: TASK-011 owner "eve" not in team
  [INFO]     Idle member: tester (all tasks completed)

Dependency Graph
  TASK-001 -> TASK-003 -> TASK-007
                       -> TASK-009
  TASK-002 -> TASK-005
  TASK-004 (no dependencies)
  TASK-006 (no dependencies)

Summary: 1 critical, 2 warnings, 1 info

Health Score System

A single number from 0 to 100 that summarizes team health.

Calculation

The score starts at 100 and applies deductions:

Factor	Deduction
Each blocked task	-5
Each critical bottleneck	-15
Each warning bottleneck	-5
Completion rate below 50%	-(50 - rate)
Workload balance below 50	-(50 - balance) / 2

The score is clamped to the range 0-100.

Thresholds

Range	Color	Meaning
71-100	Green	Healthy. Monitor normally.
40-70	Yellow	At risk. Review warnings and consider adjustments.
0-39	Red	Unhealthy. Immediate intervention required.

Monitoring Cadence

• Green teams: check every 10-15 minutes or after major milestones.
• Yellow teams: check every 5 minutes. Address warnings promptly.
• Red teams: check continuously. Reassign, unblock, or escalate immediately.

Intervention Playbook

Situation	Action
Member has 0% completion	Pair them with a productive member or reduce their scope.
Member has >3 in-progress tasks	Help them close tasks before starting new ones.
Blocked chain length >= 3	Prioritize the root blocker above all else.
Idle member + overloaded member	Reassign tasks from the overloaded member.
Circular dependency detected	Manually break the cycle by removing one dependency.
Stalled task (>30 min no change)	Check on the owner. They may be stuck and need help.
Orphaned task	Assign it to a real team member or remove it.
Overall health Red for >15 min	Escalate to the user. The team may need restructuring.

Data Locations

• Team configs: ~/.claude/teams/{team-name}/config.json
• Task files: ~/.claude/tasks/{team-name}/*.json

Each task JSON:

{
  "id": "TASK-001",
  "subject": "Set up project scaffolding",
  "description": "Create the initial directory structure and configuration files.",
  "status": "completed",
  "owner": "alice",
  "blockedBy": [],
  "blocks": ["TASK-003", "TASK-005"]
}

Team config JSON:

{
  "name": "backend-crew",
  "members": [
    {
      "name": "team-lead",
      "agentType": "architect-review",
      "model": "claude-opus-4-6",
      "color": "green"
    }
  ]
}

Tips

• Run team_status.py first for a quick overview, then drill into task_progress.py or bottleneck_detector.py only if something looks off.
• All three scripts use only the Python standard library. No installation required.
• Pipe output through less or redirect to a file if the team is large.
• The scripts handle missing files, malformed JSON, and empty directories gracefully.

Related Skills

• team-doctor -- When monitoring reveals critical issues, use diagnose_team.py for deeper analysis and repair_tasks.py for fixes
• team-orchestrator -- Reorganize task dependencies and workflows when bottlenecks are found
• team-lifecycle -- Use monitoring data to decide when a team is ready for shutdown