0rrery
Trace-first, local-first observability for AI agent workflows. Watch what your Claude Code sessions actually did (every tool call, subagent, LLM call, and permission decision) as live traces in a local dashboard. One process, one SQLite file, no cloud. Ingests Claude Code and OpenAI Codex CLI sessions.
Quickstart
npm install -g 0rrery # or: bun install -g 0rrery
0rrery init
init does three things (each skippable): installs Claude Code hooks (--no-hooks), sets up a user service so 0rrery runs persistently (--no-service), and imports your existing session history (--no-import). Then open http://localhost:7317.
Requires Bun ≥ 1.1 at runtime: the CLI runs on Bun even when installed via npm, so npm install succeeds without Bun, but the 0rrery command exits with an install-Bun message until Bun is on your PATH. Claude Code hooks require the global install (the hook command is 0rrery hook); bunx 0rrery serve works for a look around without installing.
Commands
| Command | What it does |
|---|---|
0rrery init | hooks + agent skill + service + history import, idempotently |
0rrery serve | run the server + dashboard in the foreground |
0rrery install | (re)install Claude Code hooks into ~/.claude/settings.json; replaces stale 0rrery entries |
0rrery import <file.jsonl> | import one transcript |
0rrery import --all | import everything under ~/.claude/projects |
0rrery service install|uninstall|status | manage the systemd user unit (Linux) / launchd agent (macOS) |
What gets written where
~/.claude/settings.json— hook entries (command0rrery hook)~/.0rrery/— SQLite DB + tailer offsets~/.config/systemd/user/0rrery.serviceor~/Library/LaunchAgents/com.0pon.0rrery.plist
Configuration
| Env var | Default | |
|---|---|---|
ORRERY_PORT | 7317 | dashboard/API port |
ORRERY_HOST | 127.0.0.1 | bind address (localhost-only by design) |
ORRERY_DATA_DIR | ~/.0rrery | data directory |
ORRERY_DB | <data dir>/0rrery.db | database path |
ORRERY_URL | http://localhost:7317 | where hooks/import post to |
ORRERY_CLAUDE_DIR | ~/.claude | Claude Code config/transcripts root |
Agent skill
init installs a skill at ~/.claude/skills/0rrery/ that teaches Claude to answer questions like "what did I spend this week", "what keeps failing in this repo", or "what did my last session do" by querying the local API. Skip with --no-skill; remove with rm -rf ~/.claude/skills/0rrery.
Releases
Versions are published by CI via npm Trusted Publishing: bump the version in scripts/build-pkg.ts, tag vX.Y.Z, push the tag — the workflow tests, stages, and publishes with provenance. No tokens.
Upgrade
npm install -g 0rrery@latest # or: bun install -g 0rrery@latest
0rrery service uninstall && 0rrery service install # regenerate if the bin path changed
After upgrading (or when developing from the repo), rebuild and force a reinstall so the dashboard picks up the new bundle: bun run build:pkg, then bun install -g 0rrery@latest for registry installs, or cd ~ && bun install --force for file:-pinned dev installs — an unchanged file: dep may skip re-copying otherwise.
Uninstall
0rrery service uninstall
npm uninstall -g 0rrery # or: bun remove -g 0rrery
rm -rf ~/.0rrery
Hook entries: re-run a Claude session or remove entries whose command is 0rrery hook from ~/.claude/settings.json.
Development
bun install
bun run build # dashboard
bun test
bun packages/cli/src/index.ts serve
bun run build:pkg # stage the npm package in dist-pkg/
Specs live in docs/superpowers/specs/.
Want 0rrery to ingest another agent CLI? See ADAPTERS.md.