8 providers. 5 time periods. 17 currencies. Every dollar your AI coding tools spend, tracked automatically from local session data. No API keys, no cloud, no wrappers.

npm install -g exe-watcher

Features

Native macOS menubar app

exe-watcher menubar            # install + launch
exe-watcher menubar --force    # reinstall latest

A Swift/SwiftUI popover that lives in your menu bar. Today's spend is always visible at a glance.

• Period switcher — Today, 7 Days, 30 Days, Month, All Time. Each period shows comparison to prior period (e.g. "+12% vs last 7d").
• Provider tabs — Switch between All, Claude, Codex, Cursor, etc. Only providers with actual spend appear. Cache prefetching makes tab switching instant.
• Project spend — Per-project cost breakdown across 24h / 7d / 30d.
• Daily history heatmap — 365 days of spend history, GitHub-contribution-style.
• Subscription tracking — Claude Pro ($20/mo), Claude Max ($200/mo), Cursor Pro ($20/mo) — see how much of your quota you've used.
• Capacity estimation — Derives your token limits from usage patterns when hard caps aren't published.
• Cache hit % — Track prompt caching efficiency across providers.
• One-shot rate — What percentage of edits land on the first try vs. retry loops.
• Token optimization — Surfaces waste patterns with estimated savings.
• Multi-currency — 17 currencies (USD, GBP, EUR, JPY, AUD, CAD, CHF, CNY, SEK, NOK, DKK, NZD, SGD, HKD, KRW, INR, BRL). ECB exchange rates, cached 24h.

Silent background refresh every 30 seconds. Launches at login via macOS Login Items. No loading spinners — all periods are pre-fetched on launch.

Interactive TUI dashboard

exe-watcher                    # default: 7 days
exe-watcher today              # today only
exe-watcher month              # this calendar month

Full-screen terminal dashboard with gradient charts, responsive panels, and keyboard navigation. Breaks down spend by day, project, model, activity type, tools, MCP servers, and shell commands. Auto-refreshes every 30 seconds.

Keys: 1-5 switch periods (Today / 7d / 30d / Month / All). p toggle providers. c compare mode. o optimize view. q quit.

Optimize

exe-watcher optimize           # full scan
exe-watcher optimize -p week   # scope to last 7 days

Scans your sessions and ~/.claude/ config for waste: re-read files, low read:edit ratios, uncapped bash output, unused MCP servers, ghost agents, bloated CLAUDE.md files. Returns exact copy-paste fixes and estimated savings. Grades your setup A through F.

Compare

exe-watcher compare            # interactive model picker

Side-by-side model comparison on your own data. One-shot rate, retry rate, cost per edit, cache hit rate, delegation style, fast mode usage — broken down by task category.

Supported providers

| Provider | Data source | Notes | |----------|-------------|-------| | Claude Code | ~/.claude/projects/ | Full support — tokens, cost, cache, tools | | Codex (OpenAI) | ~/.codex/sessions/ | Full support | | Cursor | SQLite (state.vscdb) | Auto mode estimated at Sonnet pricing | | Cursor Agent | CLI sessions | Full support | | Copilot | ~/.copilot/session-state/ | Output tokens only | | OpenCode | SQLite (~/.local/share/opencode/) | Subtask sessions excluded | | OMP (Oh My Pi) | ~/.omp/agent/sessions/ | Full support | | Pi | ~/.pi/agent/sessions/ | Full support |

All providers auto-detected. If multiple tools have data, press p in the dashboard to toggle between them. The provider plugin system makes adding new tools straightforward — each provider is a single file in src/providers/.

CLI reference

# Dashboard
exe-watcher                                    # interactive (default: 7 days)
exe-watcher today                              # today only
exe-watcher month                              # this month

# Reports
exe-watcher report -p 30days                   # rolling 30-day window
exe-watcher report -p all                      # everything on disk
exe-watcher report --from 2026-04-01 --to 2026-04-10
exe-watcher report --format json               # structured JSON to stdout
exe-watcher status                             # compact one-liner (today + month)

# Menubar data (used by the Swift app)
exe-watcher status --format menubar-json --period today --provider all

# Filter
exe-watcher report --provider claude           # single provider
exe-watcher report --project myapp             # project substring match
exe-watcher report --exclude tests             # exclude projects

# Tools
exe-watcher optimize                           # find waste, get fixes
exe-watcher optimize -p week                   # scope to last 7 days
exe-watcher compare                            # interactive model picker
exe-watcher export                             # CSV (today, 7d, 30d)
exe-watcher export -f json                     # JSON export

Flags work everywhere: --provider, --project, --exclude, --from, --to, and --format json combine freely across all commands.

Configuration

Currency

exe-watcher currency GBP              # any supported ISO 4217 code
exe-watcher currency --reset           # back to USD

Supported: USD, GBP, EUR, JPY, AUD, CAD, CHF, CNY, SEK, NOK, DKK, NZD, SGD, HKD, KRW, INR, BRL. Exchange rates from the ECB via Frankfurter, cached 24 hours. Applies everywhere: dashboard, menubar, exports.

Plans

Track spend against your subscription quota:

exe-watcher plan set claude-max        # $200/month
exe-watcher plan set claude-pro        # $20/month
exe-watcher plan set cursor-pro        # $20/month
exe-watcher plan set custom --monthly-usd 150 --provider claude
exe-watcher plan set none              # disable

The menubar shows a usage bar against your plan limit when a plan is active.

Model aliases

If a model shows $0.00, your provider's model name doesn't match LiteLLM pricing data. Map it:

exe-watcher model-alias "my-proxy-model" "claude-opus-4-6"
exe-watcher model-alias --list
exe-watcher model-alias --remove "my-proxy-model"

Stored in ~/.config/exe-watcher/config.json. User aliases override built-ins.

Exe OS integration

When Exe OS is installed, Watcher auto-detects it and adds an AI Employees section to the menubar with two panels:

• Memory — Per-agent memory count with 24h / 7d / 30d growth columns
• Employee Spend — Per-agent cost across 24h / 7d / 30d, using model-aware pricing (Opus, Sonnet, Haiku rates applied per-model)

How it works:

1. Exe OS's SessionStart hook maps Claude Code sessions to agents via ~/.exe-os/session-cache/
2. The daemon computes getAgentSpend() with per-model pricing and writes ~/.exe-os/agent-stats.json every 60 seconds
3. Watcher reads the stats file — zero coupling, no auth, no direct database access
4. Worktree-aware: agent worktree paths collapse into parent project names

The section appears automatically when exe-os is present and hides when it's not. Also shows daemon uptime and agent memory growth trends.

Architecture

Two components, loosely coupled via CLI output:

┌──────────────────────────────────┐      ┌─────────────────────────────────┐
│  CLI (Node.js / TypeScript)      │      │  Menubar App (Swift / SwiftUI)  │
│                                  │      │                                 │
│  Reads provider session files    │ JSON │  Calls CLI with --format        │
│  Computes cost via LiteLLM rates ├─────►│  menubar-json                   │
│  Daily cache (v5, atomic writes) │      │  @Observable state management   │
│  365-day historical backfill     │      │  30s cache TTL, prefetch on     │
│  Lock serialization for safety   │      │  launch, concurrent fetch       │
│                                  │      │  guards                         │
└──────────────────────────────────┘      └─────────────────────────────────┘

CLI pipeline: Parse provider session files from disk → deduplicate by message ID → compute cost per token type (input, output, cache write, cache read, web search) → aggregate by period, project, model, activity → output as TUI, JSON, or CSV.

Menubar app: Calls exe-watcher status --format menubar-json --period <period> --provider <provider> → decodes JSON → renders SwiftUI popover. All 5 periods are pre-fetched on launch for instant tab switching. Security: no shell injection — validated argv array passed directly, no /bin/zsh -c.

Deduplication per provider: API message ID (Claude), cumulative token cross-check (Codex), conversation/timestamp (Cursor), session+message ID (OpenCode), responseId (Pi/OMP).

Test suite

637 tests across 3 layers:

| Layer | Framework | Count | What it covers | |-------|-----------|-------|----------------| | CLI data integrity | Vitest | 594 | Schema validation, provider sum consistency, period monotonicity, project spend accuracy, 365-day history, token sanity checks | | Swift state | XCTest | 37 | Period windowing, cache isolation, prefetch logic, capacity estimation, CLI resolution, provider sum validation, JSON decode | | UI smoke | XCTest + Accessibility | 6 | App launch, status item presence, popover display, period switching via macOS Accessibility APIs |

# Run CLI tests
npm test

# Run Swift tests
cd mac && swift test

# Run UI tests
cd mac && xcodebuild test -scheme ExeWatcherUITests

Activity tracking

6 categories classified from tool usage patterns and keywords. No LLM calls, fully deterministic.

| Category | What triggers it | |----------|-----------------| | Building | Edit, Write tools; "add", "create", "implement"; refactoring keywords | | Debugging | Error/fix/bug keywords + tools | | Testing | pytest, vitest, jest in Bash | | Research | Read, Grep, WebSearch without edits; brainstorming; conversation | | DevOps | git push/commit/merge; npm build, docker, deploy | | Planning | EnterPlanMode, TaskCreate, Agent tool spawns |

Reading the signals

| What you see | What it might mean | |---|---| | Cache hit < 80% | Unstable system prompt or caching not enabled | | Lots of Read calls per session | Agent re-reading files, missing context | | Low 1-shot rate (Coding 30%) | Agent struggling, retry loops | | Opus on small turns | Overpowered model for simple tasks | | Bash dominated by git status, ls | Agent exploring instead of executing | | Conversation category dominant | Agent talking instead of doing |

Starting points, not verdicts. A single experimental session with 60% cache hit is fine. That same number across weeks of work is a config issue.

How it works

Reads session data directly from disk. No wrapper, no proxy, no API keys needed. Pricing from LiteLLM (auto-cached 24h). Handles input, output, cache write, cache read, and web search costs.

Environment variables:

| Variable | Description | |----------|-------------| | CLAUDE_CONFIG_DIR | Override Claude data directory (default: ~/.claude) | | CODEX_HOME | Override Codex data directory (default: ~/.codex) | | EXE_WATCHER_CACHE_DIR | Override cache directory (default: ~/.cache/exe-watcher) |

Contributing

Contributions welcome. The provider plugin system is the easiest entry point — each provider is a single file in src/providers/.

src/
  cli.ts            Entry point (Commander.js)
  dashboard.tsx     TUI (Ink — React for terminals)
  parser.ts         Session reader, dedup, date filter
  models.ts         LiteLLM pricing engine
  classifier.ts     Activity classifier (6 categories)
  compare-stats.ts  Model comparison engine
  menubar-json.ts   Menubar payload builder (agent spend, project spend)
  export.ts         CSV/JSON export
  config.ts         Config management
  currency.ts       Currency conversion
  providers/        One file per supported tool
mac/                Native macOS menubar app (Swift + SwiftUI)
tests/              CLI data integrity tests (Vitest)

Origin & attribution

Watcher is forked from codeburn by AgentSeal (MIT license). We forked rather than contributed upstream because our roadmap diverges significantly:

What we changed:

• Rebranded to Watcher with the Exe Foundry Bold design system
• 8 provider support (added Cursor Agent, Copilot, OMP, Pi, OpenCode)
• Native macOS menubar app with multi-period views, provider tabs, project spend, and subscription tracking
• Exe OS integration — per-agent spend and memory tracking for AI employee teams
• Daily cache system (v5) with atomic writes and cold-start 365-day backfill
• Capacity estimation from usage patterns
• Multi-currency support (17 currencies)
• 637-test suite across CLI, Swift state, and UI smoke layers
• Consolidated activity categories from 13 to 6
• Fixed double-counting bugs in the menubar JSON pipeline
• Performance: 7-day and 30-day queries from 2-5s down to ~1s via daily cache

Why we forked:

• Full control over the data pipeline to integrate with exe-os (our AI employee operating system)
• Our classification model, provider support, and UI direction serve a different user base (AI-first teams running multi-agent workflows)
• MIT license allows this — we give full credit to AgentSeal for the foundation

Thank you to AgentSeal for building the original. If you want a clean cost tracker without exe-os integration, codeburn is excellent.

Star History

License

MIT

Built by Exe AI. Forked from codeburn by AgentSeal (MIT). Pricing data from LiteLLM. Exchange rates from Frankfurter.