You're running multiple Claude Code agents across projects. Suddenly, chaos:

• Lost visibility: Which agent is doing what? You have no idea.
• Ghost messages: Agents talk to each other. You can't see it.
• Debug hell: Something breaks. You're stuck playing detective across 5 terminal windows.
• Task black holes: Tasks start, disappear, maybe finish. Who knows?

Running multi-agent workflows without monitoring is like driving blindfolded.

Claude Agent Dashboard gives you X-ray vision into your agent teams:

✅ See everything — Live status, tasks, messages, system metrics ✅ Debug faster — Trace inter-agent communication in real time ✅ Stay in control — Know exactly what's happening, always ✅ Ship with confidence — Spot failures before they cascade

Built by a cybersecurity researcher who knows that visibility is the first line of defense — even for AI agents.

📘 Deep dive: See FEATURES.md for the complete feature breakdown with architecture details.

• Node.js v18+ (Download)

npm install -g claude-team-dashboard
claude-dashboard

Or run without installing:

npx claude-team-dashboard

Open http://localhost:3001 and you're monitoring agents in real time.

# 1. Clone the repo
git clone https://github.com/mukul975/claude-team-dashboard.git
cd claude-team-dashboard

# 2. Install dependencies
npm install

# 3. Build the frontend
npm run build

# 4. Start the dashboard
npm start

Open http://localhost:3001 and you're monitoring agents in real time.

The dashboard always requires a password. The first time you open it, you'll see a setup screen — create your password there. After that, you'll be asked for it on every visit.

First run:

npm start
→ open http://localhost:3001
→ "Set Up Dashboard" screen appears
→ enter and confirm your password
→ dashboard unlocks

Every run after that:

npm start
→ open http://localhost:3001
→ login screen appears
→ enter your password
→ dashboard unlocks

Your password is stored as a secure scrypt hash in ~/.claude/dashboard.key. The session token lives in sessionStorage and clears when the browser tab closes.

Have VS Code + Docker? Skip setup entirely:

1. Open project in VS Code
2. Click "Reopen in Container" when prompted
3. Everything auto-installs. You're ready.

To work on the frontend with hot-reload:

# Terminal 1 — backend
npm run server

# Terminal 2 — frontend dev server
npm run dev

What gets monitored automatically:

• ~/.claude/teams/ — Active agent teams
• ~/.claude/tasks/ — Task management
• /tmp/claude/{project}/tasks/ — Agent outputs

🎥 Demo video coming soon — Watch a 2-minute walkthrough of key features

Try it yourself: Clone the repo and run npm start — see your agent team in action within 60 seconds.

┌─────────────────────────────────────────────────────────┐
│  Frontend (React + Vite)                                │
│  ├── Real-time UI components                            │
│  ├── WebSocket client                                   │
│  └── State management                                   │
└────────────────┬────────────────────────────────────────┘
                 │ WebSocket (bidirectional)
┌────────────────▼────────────────────────────────────────┐
│  Backend (Node.js + Express)                            │
│  ├── WebSocket server                                   │
│  ├── Agent event aggregation                            │
│  └── File system monitoring (chokidar)                  │
└────────────────┬────────────────────────────────────────┘
                 │ Reads agent logs
┌────────────────▼────────────────────────────────────────┐
│  Claude Code Agent Teams                                │
│  ├── ~/.claude/projects/{project}/*.jsonl               │
│  └── Real-time agent session logs                       │
└─────────────────────────────────────────────────────────┘

When Claude Code creates a team, it creates this folder structure:

~/.claude/teams/
└── {team-name}/
    ├── config.json          ← team configuration & members
    └── inboxes/
        ├── team-lead.json   ← messages for team-lead
        ├── researcher.json  ← messages for researcher
        └── ...              ← one file per agent

Each inbox file is a JSON array of messages:

[
  {
    "from": "team-lead",
    "text": "Your task assignment...",
    "summary": "Brief summary",
    "timestamp": "2026-02-18T10:00:00.000Z",
    "read": false,
    "color": "green"
  }
]

The dashboard watches ~/.claude/teams/*/inboxes/*.json with a dedicated chokidar watcher. Every time an inbox file changes:

• The new messages are read immediately
• An inbox_update WebSocket event is pushed to all connected dashboard clients
• The UI updates in real-time — no polling required

On initial connection, allInboxes is included in the initial_data payload so you see all current messages instantly.

// On connect — full inbox snapshot
{ type: 'initial_data', allInboxes: { [teamName]: { [agentName]: { messages, messageCount } } } }

// On inbox change — targeted update
{ type: 'inbox_update', teamName: string, inboxes: { [agentName]: { messages, messageCount } } }

claude-team-dashboard/
├── src/                      # Frontend source code
│   ├── components/           # React UI components
│   │   ├── InboxViewer.jsx       # Browse agent inbox messages
│   │   └── TeamTimeline.jsx      # Chronological activity timeline
│   ├── hooks/                # Custom React hooks
│   │   └── useInboxNotifications.js  # Browser notifications for new messages
│   ├── utils/                # Shared utilities
│   │   ├── messageParser.js      # Natural language message parsing
│   │   └── formatting.js         # Time, color, initials utilities
│   ├── config/               # Configuration constants
│   ├── styles/               # CSS stylesheets
│   └── test/                 # Test setup
├── .devcontainer/            # VS Code dev container config
├── .github/                  # GitHub templates & workflows
│   └── workflows/            # CI/CD pipelines
├── test/                     # Test files
├── dist/                     # Production build output
├── server.js                 # WebSocket backend server
├── start.js                  # Launcher script
├── cleanup.js                # Process cleanup utility
├── config.js                 # Server configuration
├── vite.config.js            # Vite bundler config
├── FEATURES.md               # Detailed feature list
├── CONTRIBUTING.md           # Contribution guide
└── CODE_OF_CONDUCT.md        # Community standards

React 19.2 UI Framework

Node.js 18+ Backend Runtime

Vite 7.x Build Tool

JavaScript ES6+ Core Language

Core Technologies:

• WebSocket (ws) — Real-time bidirectional communication
• Express.js — Backend API framework
• Chokidar — File system monitoring for agent logs
• Lucide React — Icon library
• Vitest — Unit testing framework

Need help? Open a Discussion or check existing Issues.

One of the dashboard's most powerful features is its ability to automatically translate technical agent messages into human-readable natural language. This makes it easy to understand what your agents are doing without decoding JSON or technical jargon.

The dashboard intelligently parses inter-agent messages and converts them from raw technical format to friendly, contextual descriptions:

The parser automatically identifies message types and formats them appropriately:

Status Updates

// Raw message:
{"type": "idle_notification", "lastTaskSubject": "Fix authentication bug"}

// Displayed as:
💤 Finished "Fix authentication bug" - ready for next task

Task Completions

// Raw message:
{"type": "task_completed", "taskSubject": "Write documentation"}

// Displayed as:
✅ Completed: Write documentation

Task Assignments

// Raw message:
{"type": "task_assigned", "taskSubject": "Review pull request"}

// Displayed as:
📋 Started working on: Review pull request

Coordination Messages

// Raw message:
{"type": "coordination", "message": "Waiting for backend team to finish API endpoint"}

// Displayed as:
🤝 Waiting for backend team to finish API endpoint

Questions

// Raw message:
{"type": "question", "message": "Should I use the staging or production database?"}

// Displayed as:
❓ Should I use the staging or production database?

Messages are automatically categorized into four types with distinct visual styling:

Summary Prioritization: If a message includes a summary field, the dashboard displays it instead of the full technical content, making messages more concise.

Truncation: Long messages are automatically truncated to 150 characters with "..." to prevent UI clutter.

Fallback Handling: If a message can't be parsed as JSON, it's displayed as-is with intelligent handling of empty or malformed messages.

Real-Time Translation: Messages are parsed and displayed instantly as they arrive via WebSocket — no delays or batch processing.

The dashboard provides two views for agent communication:

1. Live Communication Panel (LiveCommunication.jsx)

• Chat-style interface showing conversation flow
• Team selector to focus on specific team messages
• Auto-scroll feature (can be toggled)
• Shows sender → recipient for each message
• Updates every 5 seconds

2. Agent Inter-Communication Stream (RealTimeMessages.jsx)

• Aggregated view across all teams
• Filter messages by type (all, status, completion, coordination, question)
• Displays last 100 messages across all teams
• Shows team context for each message
• Visual stats showing breakdown by message type

The parsing logic is located in:

• File: src/components/RealTimeMessages.jsx (lines 8-83)
• Function: parseMessageToNatural(text, summary)

Message Sources: Messages are fetched from the Claude Code inbox files:

~/.claude/teams/{team-name}/inboxes/{agent-name}.json

API Endpoints:

• GET /api/teams/:teamName/inboxes - Get all inboxes for a team
• GET /api/teams/:teamName/inboxes/:agentName - Get specific agent's inbox

1. Agent sends technical message
   → Claude Code writes to ~/.claude/teams/my-team/inboxes/agent-1.json

2. Dashboard fetches message via API
   → GET /api/teams/my-team/inboxes

3. Parser processes message
   → parseMessageToNatural(rawMessage)

4. Natural language message displayed
   → "💤 Finished 'Fix bug' - ready for next task"

• No Technical Knowledge Required: Anyone can understand what agents are doing
• Quick Status Checks: Glance at communication panel to see team progress
• Contextual Understanding: Message types provide instant context
• Reduced Cognitive Load: No need to parse JSON or technical logs
• Instant Clarity: Messages are translated in real-time as they arrive

The dashboard automatically tracks the complete lifecycle of every agent team from creation to completion, with automatic archiving for historical reference.

The dashboard watches the Claude Code teams directory (~/.claude/teams/) in real-time and tracks:

Team Creation

• Automatically detected when a new config.json appears
• Logs creation timestamp
• Starts activity monitoring
• Console notification: 🎉 New team created: {team-name}

Team Activity

• Tracks every configuration change
• Updates "last seen" timestamp
• Monitors task progress
• Records all agent actions
• Console notification: 🔄 Team active: {team-name}

Team Completion

• Detected when team directory is removed
• Triggers automatic archiving
• Records final state
• Calculates session duration
• Console notification: 👋 Team completed: {team-name} - archiving for reference...

When a team completes its work, the dashboard automatically archives all team data for future reference.

Complete Team Snapshot:

• Team configuration (name, description, lead, members)
• All tasks (subject, description, status, owner, dependencies)
• Team statistics (member count, task counts, completion rate)
• Lifecycle metadata (created date, duration, last activity)

Natural Language Summary:

{
  "teamName": "dashboard-devops",
  "archivedAt": "2026-02-10T15:30:00.000Z",
  "summary": {
    "overview": "Team 'dashboard-devops' with 4 members worked on 12 tasks and completed 10.",
    "created": "Started on 02/10/2026",
    "members": [
      "team-lead (general-purpose)",
      "backend-dev (general-purpose)",
      "ui-polish-dev (general-purpose)",
      "archive-viewer-dev (general-purpose)"
    ],
    "accomplishments": [
      "✅ Fix Communication tab to display natural language messages properly",
      "✅ Verify and improve team lifecycle archiving",
      "✅ Polish dashboard UI for better user experience",
      "✅ Add archive viewer component to frontend",
      "✅ Test all features and fix empty task outputs",
      "✅ Document natural language features and team lifecycle",
      "✅ Create archive viewer UI component",
      "✅ Add API endpoint for retrieving archives",
      "✅ Test archive functionality end-to-end",
      "✅ Write comprehensive documentation"
    ],
    "duration": "Active for 45 minutes"
  },
  "rawData": {
    // Complete team data for detailed analysis
  }
}

Location: ~/.claude/archive/

File Naming: {team-name}_{timestamp}.json

• Example: dashboard-devops_2026-02-10T15-30-00-000Z.json
• Timestamp in ISO format with colons replaced by hyphens (filesystem-safe)

Automatic Creation: Archive directory is created automatically if it doesn't exist

The dashboard calculates how long each team was active:

// Example console output:
"📊 Team 'dashboard-devops' was active for 45 minutes"

Tracking Method:

1. Team created → Start timestamp recorded
2. Team activity → Last seen timestamp updated
3. Team completed → Duration calculated from timestamps
4. Duration included in archive summary

Access archived team data programmatically:

Get All Archives

GET /api/archive

Response:

{
  "archives": [
    {
      "filename": "dashboard-devops_2026-02-10T15-30-00-000Z.json",
      "overview": "Team 'dashboard-devops' with 4 members worked on 12 tasks and completed 10.",
      "created": "Started on 02/10/2026",
      "members": ["team-lead (general-purpose)", "..."],
      "accomplishments": ["✅ Task 1", "✅ Task 2", "..."],
      "duration": "Active for 45 minutes",
      "archivedAt": "2026-02-10T15:30:00.000Z"
    }
  ],
  "count": 1
}

Get Specific Archive

GET /api/archive/{filename}

Response: Complete archive including raw data

The Team History feature provides a complete chronological view of all teams:

API Endpoint:

GET /api/team-history

Response:

{
  "history": [
    {
      "name": "dashboard-devops",
      "config": { /* team config */ },
      "tasks": [ /* all tasks */ ],
      "createdAt": "2026-02-10T14:45:00.000Z",
      "lastModified": "2026-02-10T15:30:00.000Z",
      "isActive": false
    }
  ]
}

Features:

• Shows all teams (active and completed)
• Sorted by last modified (most recent first)
• Includes creation and modification timestamps
• Active status indicator

The dashboard provides console notifications for all lifecycle events:

🎉 New team created: dashboard-devops
🔄 Team active: dashboard-devops
✨ New task created: task-123.json
📝 Task updated: task-123.json
✅ Task completed/removed: task-123.json
👋 Team completed: dashboard-devops - archiving for reference...
📦 Team archived: dashboard-devops → /home/user/.claude/archive/dashboard-devops_2026-02-10T15-30-00-000Z.json
📊 Team "dashboard-devops" was active for 45 minutes

The lifecycle tracking is powered by three independent watchers:

1. Team Watcher (~/.claude/teams/**/*.json)

• Monitors: config.json files
• Triggers: Team creation, updates, completion

2. Task Watcher (~/.claude/tasks/**/*.json)

• Monitors: Individual task files
• Triggers: Task creation, updates, completion

3. Output Watcher (/tmp/claude/{project}/tasks/*.output)

• Monitors: Agent output files
• Triggers: Agent activity updates

Watch Options (configurable in config.js):

{
  persistent: true,         // Keep process running
  ignoreInitial: true,      // Don't trigger on startup
  usePolling: true,         // Use polling for cross-platform reliability
  interval: 1000,           // Polling interval (ms)
  depth: 10,                // Directory depth limit
  awaitWriteFinish: {       // Wait for complete writes
    stabilityThreshold: 500,
    pollInterval: 100
  }
}

The dashboard was audited by a team of 6 security specialists. Every layer has been hardened:

• First-time setup screen — set your password in the browser on first run; stored as an scrypt hash (N=16384, r=8, p=1 — OWASP recommended) in ~/.claude/dashboard.key (chmod 600)
• Token rotation — a fresh 256-bit random token is issued on every successful login
• Timing-safe comparison — crypto.timingSafeEqual used for both password and token validation (prevents timing attacks)
• Auth rate limiter — max 5 login/setup attempts per IP per 15 minutes (separate from the global limiter)
• sessionStorage — token clears on tab close; acceptable tradeoff for a localhost tool
• Key file permission check — warns on startup if dashboard.key is world-readable

• CSP — strict allowlist: default-src 'self', explicit connect-src/img-src/font-src, frame-ancestors 'none', object-src 'none'
• CORP / COOP — Cross-Origin-Resource-Policy: same-origin, Cross-Origin-Opener-Policy: same-origin
• HSTS — max-age=31536000; includeSubDomains
• Referrer-Policy — strict-origin-when-cross-origin
• Permissions-Policy — camera=(), microphone=(), geolocation=(), payment=(), usb=()
• Helmet — noSniff, frameguard: deny, xssFilter all enabled

• Strict sanitization — sanitizeTeamName(), sanitizeAgentName(), sanitizeFileName() enforce [a-zA-Z0-9_.-] allowlist with 100-char max on every route param
• Exact-match validation — every parameterized route returns 400 if sanitized value ≠ original (catches partial encoding attacks)
• Content-Type enforcement — POST requests without application/json get 415
• Body type checking — rejects arrays, nulls, and non-object bodies on all POST endpoints
• ReDoS-safe search — uses String.indexOf() not regex; 200-char query limit

• Token always required — connection closed with 4001 if no valid token in query string
• Ping/pong heartbeat — 30s interval, 10s pong timeout; dead clients terminated
• Per-connection rate limit — 50 messages/sec max; exceeding closes with code 1008
• Message size limit — 64 KB max; exceeding closes with code 1009
• Connection audit log — IP logged on connect/disconnect/error

• validatePath() on every fs call — uses path.resolve() to block all path traversal
• No symlink following — followSymlinks: false on all 5 chokidar watchers
• Log injection prevention — team names sanitized before appearing in log output

• CORS — restricted to localhost:3001 and localhost:5173 only; no wildcard origins
• Rate limiting — global limiter on all /api/ routes
• Error hardening — global error handler never leaks stack traces or internal messages

Read-Only: The dashboard never modifies Claude Code files — it only reads and archives data.

Project Retrospectives: Review what a team accomplished and how long it took

Performance Analysis: Track team efficiency across multiple projects

Audit Trails: Maintain records of all agent activities for compliance

Learning: Study successful team patterns and task breakdowns

Recovery: Restore team context if needed from archived data

• Zero Configuration: Archiving happens automatically — nothing to set up
• Complete History: Never lose team data when a project completes
• Natural Language: Archive summaries are human-readable
• Forensic Analysis: Full raw data included for detailed investigation
• Storage Efficient: JSON format with automatic cleanup of old archives (future feature)
• Fast Retrieval: Timestamped filenames for easy chronological sorting

• Full security audit (6-expert team) — OWASP scrypt auth, auth rate limiting, token rotation, tight CSP, CORP/COOP, Permissions-Policy, strict input validation on every route, WebSocket heartbeat + rate limiting + size limits, followSymlinks: false on all watchers, 0 npm vulnerabilities
• First-time setup flow — open dashboard → set your password in the browser → hash stored in ~/.claude/dashboard.key → login on every subsequent visit; WebSocket reconnects immediately after login (no backoff delay)
• Password auth (always on) — scrypt hash with OWASP params, timing-safe comparison, token rotation, 5-attempt rate limit per IP
• Tailwind v4 + code splitting — @tailwindcss/vite installed; 4 heavy components lazy-loaded, cutting initial JS bundle by ~50 kB
• Expanded test suite — 223 tests across 15 files covering all 4 custom hooks, key components, and utility functions
• Full accessibility audit — 50+ buttons with aria-label, interactive divs with role/tabIndex/onKeyDown, aria-live on status components, role="alert" on error states, focus management in modals
• Security hardening — server.js: fixed wrong sanitizer on inbox route, patched error message leakage in global handler, added path validation on archive listing, consistent error responses across all endpoints
• Complete inline styles migration — All 30+ components now use React inline style={{}} for every sizing, color, animation, and layout value — no broken Tailwind arbitrary values remain
• Production code cleanup — Removed 5 debug console.log statements from useWebSocket.js; cleaned unused imports across multiple components
• Light / Dark mode — Full CSS-variable-based theme system; every component, card, chart, modal, and toast adapts instantly
• Export reports — CSV & JSON export for tasks and inbox messages via the header Export menu
• Performance analytics — Analytics panel with historical charts, team comparison, and performance scoring
• Keyboard shortcuts — Command palette (⌘K), tab hotkeys (⌘1–8), shortcuts reference modal (?)
• Notification center — Grouped notification tray (Just Now / Today / Earlier) with mark-read, clear-all, and direct tab navigation
• PWA support — Installable progressive web app with offline caching via Service Worker
• Agent network graph — Live D3 force-directed graph of inter-agent communication flows
• Task dependency graph — Visual map of which tasks block which across the whole team
• Team comparison — Side-by-side performance view across multiple active teams
• Skeleton loaders — Smooth loading states instead of blank panels on first connect

• Multi-project workspace — Switch between multiple Claude projects in one dashboard
• Custom alerts — Webhook integrations (Slack, Discord, email)
• Plugin system — Extensible architecture for custom visualizations
• Docker deployment — One-command containerised setup
• Agent replay — Rewind and replay agent sessions for debugging
• Collaborative mode — Share dashboards with team members

We prioritize features based on community feedback. Open a feature request →

We love contributions! Whether you're fixing bugs, adding features, or improving docs — every contribution matters.

# 1. Fork & clone
git clone https://github.com/YOUR_USERNAME/claude-team-dashboard.git

# 2. Create feature branch
git checkout -b feature/amazing-feature

# 3. Make changes & commit
git commit -m "feat: add amazing feature"

# 4. Push & create PR
git push origin feature/amazing-feature

📖 Read the full guide: CONTRIBUTING.md

• 🐛 Report bugs — Use the bug report template
• ✨ Suggest features — Use the feature request template
• 📝 Improve docs — Fix typos, add examples, clarify instructions
• 🧪 Write tests — Increase code coverage and reliability
• 🎨 Design improvements — UI/UX enhancements welcome

First time contributing? Check out issues labeled good first issue.

This project is licensed under the MIT License — see the LICENSE file for details.

TL;DR: Free to use, modify, and distribute. Commercial use allowed. Just keep the license notice.