UsageMonitor

Local-first observability for Claude Code and Xcode CodingAssistant usage. Watches your JSONL transcripts, stores everything in a local SQLite database, and surfaces the numbers through a React dashboard and a SwiftUI menu bar app.

Nothing leaves your machine.

What it does

• Watches ~/.claude/projects/**/*.jsonl and the Xcode CodingAssistant transcripts for new sessions and appended turns.
• Parses incrementally — per-file byte checkpoints mean restarts resume mid-file instead of re-scanning gigabytes.
• Stores sessions, turns, daily rollups, and cache-health grades in a local SQLite database under ~/Library/Application Support/UsageMonitor/.
• Serves a Hono JSON API (/api/*) and an SSE stream (/api/events) on port 19876.
• Visualizes cost, tokens, cache efficiency, projects, and per-session detail via a React + Vite dashboard.
• Shows today's budget in the macOS menu bar through a SwiftUI app that spawns the engine as a child process.

Repository layout

ai-usage/
├── README.md                 # You are here
├── docs/                     # Full documentation set
│   ├── README.md             #   Doc index
│   ├── architecture.md       #   System design, data flow, SQLite schema
│   ├── runbook.md            #   Install, run, operate, troubleshoot
│   ├── api-reference.md      #   HTTP + SSE endpoints
│   └── development.md        #   Contributor setup, tests, conventions
└── usage-monitor/            # pnpm monorepo
    └── packages/
        ├── shared/           # Constants, types, pricing (both TS sides import this)
        ├── data-engine/      # Node backend: scanner + SQLite + Hono API + CLI
        ├── dashboard/        # React + Vite + Tailwind SPA
        └── macos-app/        # SwiftUI menu bar app (SPM)

Quick start

cd usage-monitor
pnpm install
pnpm build                                # shared → data-engine → dashboard → copy SPA into engine

# Run the engine (serves API + dashboard in production mode)
NODE_ENV=production node packages/data-engine/dist/index.js
# → http://localhost:19876

After the first successful build, normal restarts do not require another pnpm build.

cd usage-monitor
NODE_ENV=production node packages/data-engine/dist/index.js

Run pnpm build again only when source code or dependencies change, when you pull new commits, or if the build output was removed.

Production startup is location-independent: the engine resolves packages/data-engine/dashboard-dist/ from its own module path, so the same command works whether you launch it from usage-monitor/ or usage-monitor/packages/data-engine/. If you package the app differently, set USAGE_MONITOR_DASHBOARD_ROOT to override the dashboard bundle path.

Build outputs:

• packages/shared/dist/ — compiled shared package
• packages/data-engine/dist/ — compiled backend and CLI
• packages/dashboard/dist/ — built dashboard SPA
• packages/data-engine/dashboard-dist/ — dashboard bundle copied into the backend for production serving

Dev mode with hot reload on the dashboard:

# Terminal A
node packages/data-engine/dist/index.js

# Terminal B
pnpm --filter @usage-monitor/dashboard dev    # http://localhost:5173

macOS menu bar app:

cd usage-monitor/packages/macos-app
swift run UsageMonitor

CLI

After pnpm build:

node packages/data-engine/dist/cli.js start       # long-running engine
node packages/data-engine/dist/cli.js scan        # one-shot scan → JSON
node packages/data-engine/dist/cli.js stats       # today's stats as a table
node packages/data-engine/dist/cli.js dashboard   # opens the browser

Uninstall

To remove the project completely, stop the engine and delete both the checkout and its local application data:

pkill -f "packages/data-engine/dist/index.js"
rm -rf "/Volumes/Extended/Projects/ai-usage/usage-monitor"
rm -rf "$HOME/Library/Application Support/UsageMonitor"

This removes the repository, build output, and the local SQLite/runtime data.

Documentation

Start with docs/README.md for the full table of contents. Direct links:

• Architecture — packages, data flow, SQLite schema, runtime files
• Runbook — install, start/stop, preferences, backups, troubleshooting
• API reference — every /api/* endpoint + SSE events
• Development — contributor workflow, testing, conventions

Requirements

• Node.js ≥ 20, pnpm ≥ 9
• macOS 13+ for the menu bar app (Swift 5.9 / Xcode 15)
• The engine itself runs on any Unix-like platform — only the menu bar app is mac-specific.

License

See the project root for licensing. The pricing table in @usage-monitor/shared is a static snapshot of published Anthropic model pricing and should be updated as model prices change.