AgentFlow Dashboard v0.7.1

Real-time monitoring dashboard for AI agent systems. Visualize execution graphs, session transcripts, and performance metrics from any agent framework.

Features

Error Surfacing

• Crystal-clear error tracking — Failed node errors (state.error and metadata.error) are surfaced in all detail views: Flame Chart, Agent Flow, Summary, and Transcript
• Error messages like "403 Forbidden — Key limit exceeded" appear directly in the UI — no more digging through log files

Universal Agent Monitoring

• Multi-Format Ingestion - AgentFlow JSON traces, JSONL session logs (Claude Code compatible), structured log files, cron run logs
• Auto-Discovery - Recursively scans directories for trace files, watches for new files in real-time
• Framework Agnostic - Works with any agent system that produces JSON traces or JSONL session logs

9 Interactive Tabs

• Timeline - Waterfall execution timeline with duration bars and status icons
• Transcript - Full conversation view: user messages, assistant responses, thinking blocks, tool calls
• Graph - Interactive Cytoscape.js execution flow visualization
• Metrics - Success rates, token usage, duration stats, node breakdown
• Heatmap - Error distribution across recent traces
• State Machine - Execution state flow diagram with node counts
• Summary - Auto-generated text summary with recommendations
• Agent Timeline - Gantt chart of all executions for an agent with expandable sub-activities
• Process Map - Process mining graph showing activity flows, transition frequencies, and failure rates

Agent Timeline (Gantt Chart)

• All executions for an agent on a shared time axis
• Click any execution row to expand and see nested sub-activities
• Color-coded bars by type: user, assistant, thinking, tool call, tool result
• Trigger badges (cron, message, worker) and status indicators
• Up to 50 most recent executions per agent

Process Map (Process Mining)

• Directed graph of activity flows aggregated across all executions
• Node size proportional to frequency, edge width proportional to transition count
• Color-coded by failure rate (green → yellow → red)
• Click nodes for occurrence count, frequency, avg duration, fail rate
• Filters rare activities to keep the graph readable

Session Transcripts

• Chat-bubble UI for JSONL sessions
• User/assistant messages, tool calls with args and results
• Collapsible thinking blocks
• Token usage and cost per message
• Subagent spawn tracking

Process Health

• Live process detection and categorization
• PID file and systemd unit monitoring
• Orphan process detection
• CPU/memory resource tracking

Real-Time Updates

• WebSocket live trace broadcasting with auto-reconnect
• File watcher triggers instant sidebar updates on new/changed files

Quick Start

# Install globally
npm install -g agentflow-dashboard

# Monitor a traces directory
agentflow-dashboard --traces ./traces --port 3000

# Watch multiple directories
agentflow-dashboard \
  --traces ./traces \
  --data-dir ./sessions \
  --data-dir ./cron-runs \
  --host 0.0.0.0

# Or run with npx
npx agentflow-dashboard --traces ./my-agent-traces

Open http://localhost:3000 to view the dashboard.

CLI Options

agentflow-dashboard [options]

Options:
  -p, --port <number>     Server port (default: 3000)
  -t, --traces <path>     Primary traces directory (default: ./traces)
  -h, --host <address>    Host address (default: localhost)
  --data-dir <path>       Extra data directory (repeatable)
  --cors                  Enable CORS headers
  --help                  Show help message

Supported File Formats

| Format | Extension | Description | |--------|-----------|-------------| | AgentFlow JSON | .json | Execution graph traces with nodes, edges, timing | | JSONL Sessions | .jsonl | Claude Code / OpenClaw session transcripts | | Cron Run Logs | .jsonl | Job execution logs (ts, jobId, action, status) | | Structured Logs | .log | Python structlog, JSON logs, key=value logs | | Session Index | sessions.json | Agent session metadata (auto-discovered) |

JSONL Session Format

Compatible with Claude Code session format:

{"type":"session","id":"abc123","timestamp":"2026-03-19T10:00:00Z"}
{"type":"model_change","modelId":"claude-sonnet-4-20250514","provider":"anthropic"}
{"type":"message","message":{"role":"user","content":[{"type":"text","text":"Hello"}]}}
{"type":"message","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}],"usage":{"input":100,"output":50}}}

AgentFlow Trace Format

{
  "id": "node_001",
  "rootNodeId": "node_001",
  "agentId": "my-agent",
  "trigger": "cron",
  "startTime": 1710800000000,
  "endTime": 1710800060000,
  "status": "completed",
  "nodes": {
    "node_001": { "id": "node_001", "type": "agent", "name": "my-agent", "children": ["node_002"] },
    "node_002": { "id": "node_002", "type": "tool", "name": "search", "children": [] }
  }
}

Programmatic Usage

import { DashboardServer } from 'agentflow-dashboard';

const dashboard = new DashboardServer({
  port: 3000,
  tracesDir: './traces',
  dataDirs: ['./sessions', './cron-runs'],
  host: 'localhost',
  enableCors: false,
});

await dashboard.start();

API Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/traces | List all traces with metadata | | GET | /api/traces/:filename | Full trace detail (nodes, events, token usage) | | GET | /api/traces/:filename/events | Session events and token usage | | GET | /api/agents | All discovered agents with metrics | | GET | /api/agents/:agentId/timeline | Gantt data: executions with nested activities | | GET | /api/agents/:agentId/process-graph | Process mining graph: activity transitions | | GET | /api/stats | Global performance statistics | | GET | /api/stats/:agentId | Per-agent statistics | | GET | /api/process-health | Running process audit | | WS | / | Real-time trace updates |

Architecture

Trace files (.json, .jsonl, .log)
        │
        ▼
  TraceWatcher ──▶ AgentStats ──▶ Express + WebSocket
  (file watcher)   (metrics)      (REST API + live updates)
                                        │
                                        ▼
                                   Browser SPA
                                  (dashboard.js)

Deployment

Systemd

[Unit]
Description=AgentFlow Dashboard
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/agentflow-dashboard --host 0.0.0.0 --traces /var/log/agentflow
Restart=always

[Install]
WantedBy=multi-user.target

Docker

FROM node:20-alpine
RUN npm install -g agentflow-dashboard
EXPOSE 3000
CMD ["agentflow-dashboard", "--host", "0.0.0.0", "--traces", "/traces"]

License

MIT