hoangsonww/Claude-Code-Agent-Monitor

Claude Code & Codex Agent Dashboard

What it is – A self‑hosted web application that watches the activity of Anthropic’s Claude Code and OpenAI’s Codex agents in real time. It receives the hook events the agents emit (tool calls, sub‑agent launches, token usage, errors, etc.), stores them in a local SQLite database, and pushes the data to a React‑based UI via WebSockets / Server‑Sent Events. The UI visualises sessions, agents, tool usage, token flow, health metrics, and workflow graphs, and even ships a desktop wrapper (Electron) and a VS Code extension for quick access.

---

Core features (as described in the README)

• Live monitoring – Hook handler receives HTTP POSTs from Claude Code / Codex, writes to SQLite, and broadcasts updates instantly.
• Rich visualisations – D3/Mermaid charts for token usage, tool‑frequency heatmaps, DAGs of sub‑agent orchestration, Sankey diagrams of tool pipelines, and health‑score gauges.
• Kanban boards – Agents and sessions are grouped by status (Working, Waiting, Completed, Error, etc.) with hover‑tooltips explaining why a session is waiting.
• Session explorer – Paginated, searchable table of every recorded session with cost, model, duration, and per‑session detail pages (agents, conversation transcript, timeline, analytics).
• Internationalisation – UI supports English, Chinese, Vietnamese, Korean and Spanish via i18next; language preference persists across reloads.
• Plugin marketplace & extensions – Built‑in layer for Claude Code / Codex plugins, skills and sub‑agents that can interact with the dashboard via a local MCP (Model‑Context‑Protocol) server.
• Desktop & IDE integration – Electron builds for macOS (DMG) and Windows (NSIS/portable); a VS Code extension to open the dashboard directly from the editor.
• Observability stack – Optional Prometheus metrics, Grafana dashboards, OpenTelemetry collector, and Coralogix integration for production deployments.
• Deployment flexibility – Docker/Podman images, Helm chart, Terraform modules, and Kubernetes manifests are provided; the server can also run as a simple npm start process.
• Automation helpers – CLI scripts, Make targets, and auto‑release pipelines (GitHub Actions) for building, testing (Vitest + React Testing Library) and publishing.

---

Tech stack (summarised from the badge list)

Layer	Technology
Backend	Node.js ≥ 22, Express 4.21, better‑sqlite3 (WAL mode), WebSocket, Server‑Sent Events, Swagger‑UI, OpenAPI 3, Multer (file uploads)
Frontend	React 19, TypeScript 5, Vite 7, Tailwind CSS, D3.js, Mermaid, i18next, React‑Router
Desktop	Electron 35 + electron‑builder
Observability	Prometheus, Grafana, OpenTelemetry, Coralogix
Infrastructure	Docker, Podman, OCI, Kubernetes ≥ 1.29, Helm, Terraform ≥ 1.7, Nginx ingress
Testing / Linting	Vitest, React Testing Library, ESLint, Prettier
Database	SQLite 3 (via better‑sqlite3)
CI/CD	GitHub Actions (auto‑release)
License	MIT

---

Who might use it

• Developers building multi‑agent applications with Claude Code or Codex who need visibility into how agents invoke tools, spawn sub‑agents, and consume tokens.
• Teams operating LLM‑powered code assistants and want a central UI to audit usage, costs, and error patterns.
• Ops / SREs deploying LLM agents at scale who want Prometheus metrics and Grafana dashboards alongside the dashboard UI.
• Researchers studying agent orchestration, tool‑use patterns, or token flow across sessions.

---

Getting started (quick‑start outline from the README)

1. Clone the repo

   git clone https://github.com/hoangsonww/Claude-Code-Agent-Monitor.git
   cd Claude-Code-Agent-Monitor
   

2. Install dependencies

   npm ci   # installs backend & frontend packages
   

3. Run the server (development mode)

   npm run dev   # starts Express + SQLite + WebSocket + hot‑reloading Vite UI
   

4. Configure Claude Code / Codex
   • Add the provided hook URL (e.g., http://localhost:3000/hook) to the agents’ native hook settings so they POST events on tool use, stop, etc.
5. Open the dashboard
   • Visit http://localhost:5173 (Vite dev server) or the packaged Electron app.
6. Optional production deployment
   • Build the UI: npm run build
   • Run the compiled Express server: npm start
   • Or use the supplied Dockerfile / Helm chart for containerised/K8s deployment.

---

Where to find more info

• Wiki – Practical handbook, automation recipes, and troubleshooting: https://github.com/hoangsonww/Claude-Code-Agent-Monitor/wiki
• Docs folder – Detailed API spec, i18n guide, server architecture, and MCP integration.
• Localized READMEs – Chinese, Vietnamese, Korean, Spanish versions for region‑specific tips.

---

License

MIT – free for personal, academic, or commercial use with attribution.