Claude-Code-Agent-Monitor: A Local Dashboard for Claude Code and Codex Sessions

The gap this fills: agent sessions leave no local trace

Claude Code and Codex both run as terminal processes. When a session ends, the transcript is either gone or buried in a provider-side history you cannot query. If you want to know which tools an agent called across a week, how often a subagent was spawned, or which sessions stalled in a given state, there is no built-in view for it. This project targets exactly that gap: a local dashboard that records session and tool activity as it happens and keeps it in SQLite on your machine. The audience is narrow and specific. It is a developer running agents on a workstation, not a platform team running agents for other people. The README frames the product around tracking sessions, tool usage and subagent orchestration, and the presence of a Kanban status board and desktop builds for macOS and Windows suggests the intended use is a single operator watching their own work. Nothing in the material suggests multi-tenant deployment or team-wide analytics, and the feature list does not mention accounts, roles or sharing.

Hooks in, SQLite in the middle, WebSocket out

The mechanism is a three-stage pipeline. First, the project integrates with Claude Code and Codex through their native hook systems, which the README describes as the integration path for session tracking. Hooks fire as the agent runs, so the dashboard is fed by the agent process itself rather than by log scraping or a wrapper. Second, events land in SQLite through better-sqlite3, which the README lists alongside WAL mode. That choice matters: WAL allows a reader to query while the writer appends, which is what a dashboard polling a live event stream needs. Third, the Express server pushes updates outward. The README lists both WebSocket (RFC 6455 via the ws package) and Server-Sent Events, so the browser can receive live updates by either channel. A REST API sits alongside the push channels and is documented with OpenAPI 3.0 and served through swagger-ui-express. The front end is React 19 with Vite, Tailwind CSS and D3 for charts. The data flow is therefore one-directional and simple: hook event, SQLite row, push to client. There is no message broker and no external database, which keeps the deployment footprint to one Node process plus a file.

Getting the server and dashboard up

The README is explicit about runtime floors: Node.js >= 22.22 and Python >= 3.6, with Express 4.21, React 19.2, TypeScript 5.7 and Vite 7.3 in the stack. Docker and Podman are both listed as supported container runtimes against the OCI image format, and there are Terraform, Kubernetes, Helm and Kustomize badges, so a container path exists. What the README does not give, at least in the portion available here, is the literal npm script names or the .env keys for the server port, database path and VAPID credentials. The web-push badge indicates VAPID keys are part of push notification setup, and the multer, adm-zip and tar badges indicate an upload and archive-extraction surface on the API. Those are the config values to look for first when you clone the repository. The desktop builds are separate artifacts: Electron 35 packaged with electron-builder 25.1, distributed as a macOS DMG for arm64 and x64 and a Windows NSIS installer plus a portable build. On macOS the README lists SMAppService login items, which is how the app registers itself to start at login. Treat the desktop app as a packaging of the same server and UI, not a different product.

Where the design gets thin: hook wiring and data retention

The strongest claim in the README is that the tool integrates directly with Claude Code and Codex through their native hook systems. The weakest part of the README is that it does not, in the material available, show the hook configuration itself. There is no snippet showing which hook events are registered, where the configuration file lives, or what happens when a hook fires but the server is not running. That matters because hooks are the entire ingestion path. If the hook writes to a local HTTP endpoint and the server is down, events are lost unless the hook script buffers them, and nothing in the material indicates a buffer exists. A second gap is retention. SQLite in WAL mode grows; the README does not describe a pruning job, a size cap, or a compaction step. For a tool that records every tool call across every session, that is a real operational question. A third gap is scope: the dashboard is local, so there is no stated story for aggregating across machines, and the desktop builds are per-user. Anyone expecting a fleet view will not find one here.

How it differs from generic observability stacks

The obvious comparison is OpenTelemetry plus Prometheus and Grafana, both of which appear in the README badge list, which suggests the project has some awareness of that ecosystem. The difference in approach is the ingestion model. An OpenTelemetry pipeline expects your application to emit spans through an SDK or collector, and it is designed for services you control and deploy. Claude Code and Codex are third-party binaries; you cannot add instrumentation to them. This project sidesteps that by attaching at the hook layer, which is the only extension point the agents expose. The trade-off is fidelity: hook events are whatever the agent chooses to emit, not a schema you designed, so the dashboard's data model is constrained by another vendor's event surface and can change when that vendor changes hooks. A second difference is storage. Prometheus is a time-series store built for aggregation and downsampling; SQLite is a relational store built for exact rows. That makes this project better at answering "what exactly did this session do" and worse at answering "what is the 95th percentile tool latency over 30 days." If your question is the latter, a metrics stack is the right tool and this is not.

Maintenance cost and the MIT licence

The release cadence visible in the material is fast: v2.1.0, v2.1.1 and v2.1.2 all landed within roughly a week in September 2026. Frequent patch releases are normal for a young project but they mean you should pin a version rather than track the default branch if you depend on the REST API shape. The dependency surface is wide. The server side pulls in Express, ws, web-push, swagger-ui-express, multer, adm-zip, tar and better-sqlite3, and better-sqlite3 is a native module, so Node upgrades can require a rebuild. The client side carries React 19, Vite 7, Tailwind 3.4, D3, Mermaid, i18next and React Router. That is a lot of moving parts for a monitoring tool, and each one is a place where an upgrade can break the build. The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. MIT offers no patent grant and no warranty, so if you ship this inside a product, the compliance work is yours. This is a description of the licence text, not legal advice.

What the Kanban board and buddy actually change

Two features sit outside the core tracking loop and are worth judging on their own. The Kanban status board implies sessions have a state that a human can move, which turns the dashboard from a read-only log into a small workflow tool. That is useful if you run several agent sessions at once and need to remember which one is waiting on you, and it is dead weight if you run one session at a time. The buddy and the notification path (web-push with VAPID) point at the same use case: an agent that finishes or stalls while you are looking at something else. Push notifications require a service worker and VAPID keys, which is more setup than a local dashboard usually demands. The interactive web UI plus native macOS and Windows apps cover the display side, and the VS Code extension badge in the README suggests editor integration is planned or present, though the material does not describe what that extension does. Judge these as conveniences layered on the hook-to-SQLite pipeline, not as reasons to adopt the project on their own.

Editorial conclusion

Adopt it if you run Claude Code or Codex locally and want session, tool and subagent history in your own SQLite file rather than in a vendor dashboard. Do not adopt it if you need multi-user access control, a hosted service, or a tool whose hook wiring you can verify from the README alone; the README describes the stack and the API surface far more thoroughly than it describes installation. Before committing, verify three things: where the Claude Code and Codex hook configuration is written, whether the SQLite database stores prompt and tool payloads verbatim, and what the WebSocket server does about origin checks and authentication.

Official sources

1. hoangsonww/Claude-Code-Agent-Monitor on GitHub
2. License: MIT
3. Project website
4. README
5. Releases