# Coding Agent Analytics A unified analytics dashboard for AI coding agents. Reads local session data from **Claude Code**, **Kiro**, and **Codex CLI** and provides cross-agent usage metrics, cost estimation, activity patterns, tool analytics, and workspace management — all without sending data anywhere. ## Quick Start ```bash # Start the server (includes the analytics dashboard) npm run dev:server # Backend on port 4001 npm run dev # Frontend on port 4000 (separate terminal) # Or production mode (single process) npm run server ``` Open `http://localhost:4000` (dev) or `http://localhost:4001` (prod) and click the **Coding Agents** tab. The dashboard auto-detects installed agents and shows data immediately. ## Supported Agents | Agent | Data Location | What's Parsed | Cost Estimation | |-------|--------------|---------------|-----------------| | **Claude Code** | `~/.claude/projects//*.jsonl` | Messages, tool calls, token usage, cache metrics, MCP usage | Full (input/output/cache tokens) | | **Kiro** | `~/.kiro/sessions/cli/*.jsonl` + IDE workspace | Messages, tool calls, partial token counts, session metadata | Partial (Bedrock pricing) | | **Codex CLI** | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` | Messages, tool calls, session metadata | None (tokens not persisted) | No configuration required. If the agent's data directory exists, it's detected automatically. ## Dashboard Tabs ### Overview Top-level stats across all agents: total sessions, estimated cost, tool success rate, cost per completion, wasted cost (incomplete sessions), and detected agents. Includes daily activity chart, agent distribution pie chart, and auto-generated insights with actionable recommendations. ### Sessions Filterable, sortable session list with search. Click any session to open a resizable detail panel showing the full conversation with syntax highlighting. Supports filtering by agent, completion status, and project. Search highlights matches with prev/next navigation. ### Projects Per-project analytics cards showing session count, completion rate, cost, and tool errors. Click any project to drill into its sessions. ### Costs Cost breakdown by model and project with daily cost trend chart. Includes cache savings calculation. Click chart bars to drill into sessions or projects. ### Activity GitHub-style activity heatmap (last 90 days), sessions by hour and day of week, current/longest streaks, and active days. Click any element to explore related sessions. ### Efficiency Cross-agent comparison of tool success rate, completion rate, and cost per completion. Per-agent cards with detailed metrics. Click agent cards to view their sessions. ### Tools Tool usage analytics with category breakdown (file-io, shell, agent, web, planning, mcp, etc.). Click category bars to filter the tools table. Click tool rows to see sessions using that tool. Includes error rates and success percentages. ### Advanced MCP server analytics, hourly effectiveness (completion rate by hour), session duration distribution, conversation depth analysis, and recurring failure patterns. All elements are clickable for drill-down navigation. ### Workspace Agent-specific workspace management: - **Claude Code**: Active sessions, memory files (view/edit), plans, tasks, and settings - **Kiro**: MCP servers, agents, powers, extensions, and settings ## Architecture ``` Browser (React) → Express API (/api/coding-agents/*) → SessionCacheManager (in-memory, <1ms responses) → ReaderCache (per-agent, directory signature invalidation) → [ClaudeCodeReader, KiroReader, CodexReader] → Local filesystem (~/.claude/, ~/.kiro/, ~/.codex/) ``` ### In-Memory Cache Session data is cached in memory with a two-tier invalidation strategy: 1. **Directory signature** — `"latestMtime:fileCount"` fingerprint detects new/deleted sessions without re-parsing 2. **Active session refresh** — Background interval (30s) checks file mtime for non-completed sessions only First request after startup: ~30ms (cache warmup). Subsequent requests: <3ms. ### Key Files ``` server/services/codingAgents/ ├── index.ts # Barrel exports ├── types.ts # Unified type definitions (AgentSession, CombinedStats, etc.) ├── registry.ts # Core registry — merges data from all readers ├── cache.ts # Two-tier session cache with directory invalidation ├── pricing.ts # Multi-vendor pricing (Claude, Bedrock, OpenAI) ├── toolCategories.ts # Unified tool categorization across agents ├── insights.ts # Auto-generated actionable insights └── readers/ ├── claudeCode.ts # Claude Code JSONL parser ├── claudeCodeWorkspace.ts # Claude Code workspace (memory, plans, tasks) ├── kiro.ts # Kiro CLI + IDE session parser ├── kiroWorkspace.ts # Kiro workspace (MCP, agents, powers) └── codex.ts # Codex CLI rollout parser server/routes/ ├── codingAgents.ts # Analytics API endpoints (12 routes) └── claudeCodeWorkspace.ts # Workspace management endpoints (6 routes) components/codingAgents/ └── CodingAgentsPage.tsx # React dashboard (9 tabs, ~2600 LOC) ``` ## API Reference All endpoints support optional `from` and `to` query parameters for date range filtering (ISO 8601 format). | Endpoint | Description | |----------|-------------| | `GET /api/coding-agents/available` | List detected agents | | `GET /api/coding-agents/stats` | Combined stats across all agents | | `GET /api/coding-agents/sessions` | Paginated session list (supports `agent`, `completed`, `project`, `search`, `limit`, `offset`) | | `GET /api/coding-agents/sessions/:agent/:sessionId` | Session detail with full conversation | | `GET /api/coding-agents/costs` | Cost breakdown by model and project | | `GET /api/coding-agents/activity` | Activity patterns (streaks, hourly, daily, heatmap) | | `GET /api/coding-agents/tools` | Tool usage analytics with categories | | `GET /api/coding-agents/efficiency` | Per-agent efficiency metrics | | `GET /api/coding-agents/projects` | Per-project analytics | | `GET /api/coding-agents/advanced` | MCP, duration, conversation depth, hourly effectiveness | | `GET /api/coding-agents/failure-patterns` | Recurring tool failure patterns | | `GET /api/coding-agents/export` | Export all data as JSON or CSV (`format=json|csv`) | ### Remote Server Endpoints | Endpoint | Description | |----------|-------------| | `GET /api/remote-servers` | List configured remote servers (API keys masked) | | `POST /api/remote-servers` | Add a remote server (`{ name, url, apiKey? }`) | | `DELETE /api/remote-servers/:name` | Remove a remote server | | `POST /api/remote-servers/:name/test` | Test connectivity to a remote server | ### Workspace Endpoints | Endpoint | Description | |----------|-------------| | `GET /api/coding-agents/claude-code/memory` | Claude Code memory files by project | | `GET /api/coding-agents/claude-code/plans` | Active plans | | `GET /api/coding-agents/claude-code/tasks` | Task lists | | `GET /api/coding-agents/claude-code/settings` | Claude Code settings | | `GET /api/coding-agents/claude-code/active-sessions` | Currently active sessions | | `GET /api/coding-agents/kiro/workspace` | Kiro workspace (MCP servers, agents, powers, extensions) | ## Adding a New Agent Reader To add support for a new coding agent: 1. **Create a reader** in `server/services/codingAgents/readers/`: ```typescript import type { CodingAgentReader, AgentSession, AgentStats, SessionDetail } from '../types'; export class MyAgentReader implements CodingAgentReader { readonly agentName = 'my-agent' as const; readonly displayName = 'My Agent'; async isAvailable(): Promise { // Check if the agent's data directory exists } async getSessions(): Promise { // Parse session files and return normalized AgentSession[] } async getStats(): Promise { // Aggregate stats from sessions } async getSessionDetail(sessionId: string): Promise { // Return full conversation for a session } } ``` 2. **Register the reader** in `server/services/codingAgents/registry.ts`: ```typescript import { MyAgentReader } from './readers/myAgent'; // Add to the readers array private readers: CodingAgentReader[] = [ new ClaudeCodeReader(), new KiroReader(), new CodexReader(), new MyAgentReader(), // ← add here ]; ``` 3. **Add pricing** (if available) in `server/services/codingAgents/pricing.ts` 4. **Add tool categories** in `server/services/codingAgents/toolCategories.ts` 5. **Add cache signature** in `server/services/codingAgents/cache.ts` under `DIR_SIGNATURE_FNS` 6. **Add colors/labels** in `components/codingAgents/CodingAgentsPage.tsx`: ```typescript const AGENT_COLORS = { ..., 'my-agent': '#your-color' }; const AGENT_LABELS = { ..., 'my-agent': 'My Agent' }; ``` ## Remote Build Server Monitoring Monitor coding agents running on remote EC2 instances, build servers, or cloud dev environments from a single local dashboard. ### How It Works Each remote machine runs `agent-health` in **headless mode** (API only, no frontend). Your local dashboard aggregates data from all remotes transparently — the frontend code is unchanged, always talking to its own local server. ``` [Remote EC2-A] agent-health serve --headless --api-key sk-abc → :4001 [Remote EC2-B] agent-health serve --headless --api-key sk-xyz → :4001 [Local machine] Browser → localhost:4001 → Local server merges local + remote data ``` ### Setup **On each remote machine:** ```bash npx @opensearch-project/agent-health serve --headless --api-key sk-my-secret ``` **On your local machine:** ```bash # Add remote servers agent-health remote add --name ec2-build-1 --url http://10.0.1.50:4001 --api-key sk-my-secret agent-health remote add --name ec2-build-2 --url http://10.0.1.51:4001 --api-key sk-other # Test connectivity agent-health remote test # Start the dashboard — automatically aggregates from all servers agent-health ``` Or use the **Settings UI** — go to Settings > Remote Servers to add, test, and remove servers from the browser. Or configure via `agent-health.config.json`: ```json { "remoteServers": [ { "name": "ec2-build-1", "url": "http://10.0.1.50:4001", "apiKey": "sk-my-secret" }, { "name": "ec2-build-2", "url": "http://10.0.1.51:4001", "apiKey": "sk-other" } ] } ``` ### CLI Commands | Command | Description | |---------|-------------| | `agent-health remote add --name --url [--api-key ]` | Add a remote server | | `agent-health remote remove ` | Remove a remote server | | `agent-health remote list` | List configured remotes | | `agent-health remote test` | Test connectivity to all remotes | ### Key Behaviors - **Graceful degradation**: If a remote is unreachable, the dashboard still shows data from available sources - **30-second cache**: Remote session data is cached locally to avoid excessive network calls - **10-second timeout**: Slow remotes don't block the entire dashboard - **Server badges**: Sessions from remote servers show a colored badge with the server name - **Transparent aggregation**: All analytics (stats, costs, activity, tools, etc.) automatically include remote data ## Feature Toggle Coding Agent Analytics can be disabled entirely without affecting the core evaluation features: ```bash # Via environment variable AH_DISABLE_CODING_ANALYTICS=true npx @opensearch-project/agent-health ``` Or in `agent-health.config.json`: ```json { "codingAgentAnalytics": false } ``` When disabled: no routes are mounted, no background timers run, and the "Coding Agents" nav tab is hidden. All evaluation features continue to work normally. ## Privacy All data stays local. The dashboard reads session files directly from your filesystem (`~/.claude/`, `~/.kiro/`, `~/.codex/`). No data is sent to any external service. The `_filePath` internal field used for caching is stripped from all API responses. ## Design Document See [RFC 001: Coding Agent Analytics](rfcs/001-coding-agent-analytics.md) for the full design specification including motivation, architecture decisions, data flow diagrams, and planned future phases.