The Problem

AI coding agents (Claude Code, Codex, etc.) generate large volumes of telemetry—tokens, cache reads/writes, model calls, and cost estimates. Teams need a single, local‑first view that aggregates this data across laptops, build servers, and cloud workstations without sending any data outside the network.

What This Does

The console collects agent telemetry from local transcripts or optional OpenTelemetry streams, normalises it into a common schema, and serves the data through a lightweight Express API and a web UI. Key components include:

  • lib/collector/collector.js – pulls raw measurements from local files or inbound streams.
  • lib/analysis/index.js – produces aggregated token counts, cost estimates, and alerts.
  • lib/hub/routes.js – exposes /metrics, /projects, and /alerts endpoints for downstream consumption.
  • public/index.html – renders an interactive dashboard that pulls data from the API.

The tool also supports a “presenting” mode that scrubs identities, and it ships Apple‑signed macOS binaries with notarisation and CycloneDX SBOMs.

How It Is Wired

Execution start – node server.js (entry point server.js). server.js imports Express, mounts routes from lib/hub/routes.js, and starts the HTTP server on the port defined in lib/config.js. Routes call into lib/hub/store.js to read/write state files (state-file.js, state-lock.js). When a request hits /metrics, routes.js delegates to lib/collector/collector.js, which reads the raw measurement files (see collector/measurement.js) and streams them to analysis/index.js. analysis/index.js orchestrates analysis/cost-outcome.js, analysis/alerts.js, and analysis/policy.js, producing JSON that the UI consumes.

Side‑channel ingestion – lib/collector/ingest.js listens for OpenTelemetry events over HTTP (configured in lib/hub/http.js) and forwards them to the same collector pipeline. Policy hooks – lib/policy/hook.mjs and lib/policy/classify.mjs are invoked during analysis to flag suspicious usage patterns; the policy logic lives in policy/schema.json.

The wiring forms a linear chain: HTTP request → routes → store → collector → analysis → JSON response. The biggest blast radius is the collector module, which reads arbitrary files on the host; a change here would affect all data ingestion paths.

How To Use It

Setup

git clone https://github.com/moses-y/agent-console
cd agent-console
npm install           # resolves dependencies in package.json

Configuration Create a config.json in the repo root (or set env vars). Sample keys:

{
  "hubUrl": "http://localhost:3000",
  "authToken": "YOUR_TEAM_TOKEN",
  "presenting": false
}

Environment fall‑back (process.env) is documented in lib/config.js.

Running

node server.js          # starts the web UI on http://localhost:3000

For CLI usage (e.g., running policy checks), use the bundled script:

node bin/agent-console.mjs policy --project myproj

Deployment Docker image is built via the Dockerfile.

docker build -t agent-console .
docker run -p 3000:3000 agent-console

Real‑World Use

A software‑engineering team installs the console on each developer’s laptop and on the CI server. Each machine writes its own console-v0.4.json traces. The console aggregates them on a central hub; the web UI shows a unified view of token usage per project and estimated cost per build. The team runs node bin/agent-console.mjs policy nightly to flag projects exceeding a token budget.

Code Health & Issues

Security audit – test/fixtures/secrets.js contains a placeholder secret; no active secrets are committed. CI status – All GitHub Actions workflows (ci.yml, installers.yml, pages.yml) pass. Coverage – 105 test files exist, but no coverage report is generated automatically. Lint – scripts/lint.mjs runs ESLint; the latest run shows no errors.

The Bottom Line

Agent Console delivers a focused, local‑first observability layer for AI coding agents with minimal runtime overhead. Its clear separation of ingestion, analysis, and presentation makes it straightforward to extend or replace components. Teams that already run Claude Code or Codex across multiple machines will benefit from a single dashboard and policy engine, especially when privacy or compliance requires keeping telemetry on‑premise.