Meterbility

The debugger for AI agents. Capture every run, inspect every decision, pause and inject live, fork from any step, diff the trajectories.

Meterbility turns AI agent runs into a queryable, replayable, forkable corpus and surfaces them through a terminal inspector, a local web UI, and a Live Probe operator surface. It works against Claude Code, Codex CLI, Cursor, the Anthropic and OpenAI proxies, and any custom agent that uses the TypeScript or Python SDK.

Status

v0.5 — full-fidelity Bash capture. Working end-to-end. On npm as @meterbility/cli.

Latest milestones (v0.5):

• Bash side-effect capture (closes SPEC §3.1.3): what tool-call inspection can't see (sed, mv, npm install, build scripts) now lands as filesystem_watch FileChange rows, two ways — hook capture for Claude Code (meter init --hooks → meter capture, exact per-step attribution) and the FileSentinel (meter watch --files, cross-vendor fallback with temporal-proximity attribution). Both watch the whole project tree by default — every file under the current directory (or --files-dir), recursively, filtered only by .meterbilityignore/.gitignore; there's nothing per-file to configure. See Live inspector docs.
• Markdown-aware pretty printing — meter inspect --pretty-print and the web step cards detect markdown in messages, thinking, tool results, and decisions, and style headings/bold/code/lists/links in place.
• Sensitive-path content policy — explicit agent edits to .env, keys, and credential stores record the fact of the change (path, op, size) but never the contents.

Earlier milestones:

• v0.3 — file capture + Live Probe. Claude Code file-history-snapshot diffs in the Files tab; Live Probe pause/inject/resume across TypeScript + Python SDKs, meter probe CLI, and web panel; OSS launch deliverables (licenses, dependency audit, CONTRIBUTING, SECURITY, fresh-laptop test).

60-second tour →

Install

Requires Node 24+ (rebuilds better-sqlite3 natively). Python SDK additionally requires Python 3.9+ (stdlib only — no install-time deps).

npm install -g @meterbility/cli

meter doctor                 # verify the Claude Code surface
meter ingest claude-code --limit 5
meter list
meter inspect <run-id> --at 5 --show context   # exactly what the model saw at step 5
meter web                    # open the inspector at http://127.0.0.1:4317

Instrumenting your own agent? Add the SDK to your project instead: npm install @meterbility/agent (TypeScript) or pip install meterbility-agent (Python).

From a clone

For development, or to run ahead of the latest release:

git clone https://github.com/HoneycombHairDevelopers/Meterbility
cd Meterbility
nvm use                      # picks up .nvmrc → Node 24
npm install
./bin/meter doctor           # same CLI, run from source

./bin/meter is the launcher. To put it on $PATH, symlink it into ~/.local/bin/ or wherever you keep scripts.

For the cleanest possible install verification, run:

./scripts/fresh-laptop-test.sh

This is the same script CI runs — clones into a tempdir, installs, runs the full test suite, exercises every documented command, and tears down.

What ships today

Full milestone history: SPEC-V0.2.md §16, docs/v0-3-followups.md.

The five DevTools panels

Meterbility maps the browser DevTools mental model onto agents. See SPEC §4 for the full mapping; all five are delivered:

Repo layout

packages/
  cli/                # `meter` command (commander)
  shared/             # types, hashing, redaction, paths, probe protocol
  spec/               # trace-format schema + pricing tables
  collector/          # SQLite + content-addressed blob store
  server/             # replay, fork, diff, web (Hono), live inspector, probe panel
  agent/              # TypeScript SDK (MeterbilityTracer + traceAnthropic + probe hook)
  agent-py/           # Python SDK — stdlib only, same shape as TS
  proxy/              # Anthropic + OpenAI HTTP proxies with capture
  store-postgres/     # optional Postgres backend
  web/                # placeholder for future SPA

adapters/
  claude-code/        # Claude Code JSONL + file-history-snapshot adapter
  codex-cli/          # Codex / Codex Desktop rollout JSONL adapter
  cursor/             # Cursor composer/Agents reverse-engineered SQLite adapter

ee/                   # Enterprise Edition modules (ELv2 — empty today)

docs/
  getting-started.md  # 60-second tour
  architecture.md     # how capture, storage, replay, diff fit together
  sdk.md              # instrument a custom TS agent
  live-inspector.md   # meter web --live + notifications
  regression.md       # promote canonicals + assertions
  postgres.md         # optional Postgres backend
  trace-format.md     # v0.2 wire format spec
  v0-3-followups.md   # known limitations + their resolution paths
  test-plan-v0_4-capture.md  # manual release checklist for the Bash capture paths

Docs

License

Meterbility ships under an open-core model:

• MIT (LICENSE) — everything outside the /ee directory. The capture surfaces, trace format, replay engine, Inspector + Debugger UI, Live Probe, and CLI. The full single-operator product.
• Elastic License 2.0 (ee/LICENSE) — anything inside /ee (empty today; reserved for multi-tenant fleet orchestration, SSO, RBAC, audit logs, long-retention modules).
• Commercial — the hosted cloud (when it ships).

Every dependency in the tree is permissive (MIT / ISC / Apache-2.0 / BSD). Zero copyleft. See LICENSES-third-party.md and run ./scripts/license-audit.sh to re-verify.

Contributing

Read CONTRIBUTING.md. The short version:

git clone https://github.com/HoneycombHairDevelopers/Meterbility
cd Meterbility && nvm use && npm install
npm test                                   # TypeScript suite
cd packages/agent-py && python3 -m unittest discover tests

1,290+ tests across both runtimes. Add tests with every change. Keep
the suite green before you ask for review.

Security

Report vulnerabilities privately per SECURITY.md. Please do not file public issues for exploitable bugs.