# fathom-cli

[![npm version](https://img.shields.io/npm/v/fathom-cli)](https://www.npmjs.com/package/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.

```bash
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

```bash
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 init` | Initialize Fathom for a project (creates `.fathom/` + `.mcp.json`) |
| `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 |
| `fathom install-plugin` | Install Claude Code plugin (skills + MCP config) |
| `fathom report` | Generate client reports (markdown, HTML, JSON) |
| `fathom sync` | Sync features to Linear, GitHub Issues, Notion, Jira |

## 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](https://github.com/olivelliott/fathom) headless packages into a CLI. Use the packages directly if you're building your own tooling.

## License

MIT