fathom-cli

Know what your AI coding actually costs. Estimate tokens before you build, track actuals while you build, calibrate so estimates get better over time.

npm install -g fathom-cli
fathom

The Problem

You're spending real money on AI coding and have zero visibility into where it goes. You don't know what a feature costs until the bill arrives. Overhead — context resends, tool calls, error recovery — is invisible.

What Fathom Does

Estimate → token cost per feature, based on task type + complexity + overhead model

Track → auto-imports sessions from Claude, GPT, Gemini, or any provider. Tags to features automatically.

Calibrate → compares estimates to actuals, adjusts the model. Gets more accurate every cycle.

$ fathom estimate "add OAuth login with Google and GitHub"
  ~42,000 tokens (~$0.84) — complexity: L, type: integration

$ fathom track
  3 sessions imported, 2 auto-tagged (auth-login: 89%, payment: 72%)

$ fathom reconcile
  auth-login: estimated 42K, actual 67K (1.6x over — error recovery overhead)

$ fathom calibrate
  adjusted integration overhead: 1.8x → 2.4x (based on 12 data points)

One Command Workflow

fathom

With no arguments, fathom runs the full loop:

1. Intent — captures what you're building, what matters, your budget and guardrails
2. Intake — extracts work items, estimates tokens and cost
3. Build — launches your AI tool with full context
4. Review — tracks sessions, reconciles, calibrates

New project? Auto-scaffolds everything. Returning? Shows progress:

$ fathom

  Fathom — myproject
  6/12 features complete (50%) — $8.40 of $14.20 spent

  > Continue building (next: payment-integration)
    New intake — add more work
    Review — reconcile recent sessions

Also Does

• Model routing — recommends Haiku/Sonnet/Opus based on task complexity and budget
• Tool config generation — creates system prompts for Claude, Cursor, Copilot, Windsurf from your project intent
• Guardrail templates — OWASP, WCAG, HIPAA, GDPR, PCI, SOC2 built-in
• MCP server — use Fathom as tools inside any MCP-compatible editor
• Velocity benchmarks — "auth features take 2.3 days and 85K tokens on average"

All Commands

| Command | What it does | |---------|-------------| | fathom | Full workflow — intake, build, review | | fathom estimate <desc> | Quick cost estimate | | fathom intake | Requirements → estimated spec slices | | fathom analyze <spec> | Parse spec, estimate features | | fathom track | Import + auto-tag sessions | | fathom reconcile | Estimates vs actuals | | fathom calibrate | Adjust from real data | | fathom velocity | Throughput metrics | | fathom status | Project overview | | fathom pricing | Model pricing table | | fathom go | Launch AI tool with context |

Environment Variables

| Variable | Purpose | |----------|---------| | ANTHROPIC_API_KEY | For intake extraction | | OPENAI_API_KEY | Alternative provider | | CONVEX_URL | Optional — real-time dashboard |

Part of Fathom

fathom-cli wraps the Fathom headless packages into a CLI. Use the packages directly if you're building your own tooling.

License

MIT