fathom-cli 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,173 @@
+# fathom-cli
+
+Workflow intelligence for AI-augmented development. Estimate token costs before work, automatically track actuals during work, reconcile and calibrate after work, and build velocity benchmarks over time.
+
+```
+intake → estimate → build (tracked) → reconcile → calibrate → velocity
+```
+
+## Install
+
+```bash
+npm install -g fathom-cli
+```
+
+## Quick Start
+
+```bash
+# Quick estimate — "how much will this cost?"
+# AI scores complexity automatically when ANTHROPIC_API_KEY is set
+fathom estimate "React dashboard with OAuth"
+
+# Generate a full spec sheet — "break this down into work items"
+fathom intake "Users say the calendar is slow and Zoom links are missing" --project myapp
+
+# Analyze a full spec with multiple features
+fathom analyze spec.md --project myapp
+
+# Scaffold tracking for an existing project
+fathom setup --project myapp
+
+# Import and auto-tag Claude Code sessions
+fathom track --project myapp
+
+# Compare estimates vs actuals
+fathom reconcile --project myapp
+
+# See velocity metrics
+fathom velocity --project myapp
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `fathom estimate <desc>` | Quick cost estimate — AI scores complexity, returns tokens + cost |
+| `fathom intake <text>` | Generate spec sheet — extracts work items, estimates each, outputs markdown |
+| `fathom analyze <spec>` | Parse spec, estimate all features, generate registry |
+| `fathom track` | Import Claude Code sessions, auto-tag to features |
+| `fathom reconcile` | Compare estimates vs actuals per feature |
+| `fathom calibrate` | Show drift and suggest profile adjustments |
+| `fathom velocity` | Velocity metrics and benchmarks |
+| `fathom status` | Project overview with tracking data |
+| `fathom pricing` | Show current model pricing |
+| `fathom setup` | Scaffold `.claude/` skill + hooks + registry |
+| `fathom validate <spec>` | Validate spec file format |
+| `fathom init` | Initialize global config |
+
+## How It Works
+
+### 1. Estimate vs Intake (Before Work)
+
+**`estimate`** — quick cost number from a description:
+
+```bash
+fathom estimate "Build a real-time chat system with WebSocket support"
+# AI analyzes → L complexity, 205K tokens, $2.51, recommends Sonnet
+# Use --complexity M to override, --no-ai for heuristic-only scoring
+```
+
+**`intake`** — full spec sheet from raw feedback:
+
+```bash
+fathom intake "Users need real-time chat and the Zoom integration is broken" --project myapp
+# Extracts discrete work items, classifies each by complexity/priority,
+# estimates tokens + cost per item, attaches velocity benchmarks,
+# outputs structured markdown spec ready for implementation
+```
+
+Use `estimate` when you want a quick number. Use `intake` when you want a plan.
+
+Both use a calibrated model: base tokens per task type × complexity multiplier × overhead (context resend, tool calls, thinking, error recovery, planning, review).
+
+### 2. Track (During Work)
+
+Fathom automatically discovers Claude Code sessions from `~/.claude/projects/` and tags them to features using a 4-signal cascade:
+
+1. **Explicit feature ID** in conversation → 99% confidence
+2. **Git branch** pattern match → 85%
+3. **Keyword** match → 75%
+4. **File path** match → 70%
+
+Zero configuration needed — just run `fathom track`.
+
+### 3. Reconcile + Calibrate (After Work)
+
+```bash
+fathom reconcile --project myapp
+# Shows: Feature | Estimated | Actual | Drift% | Cost | Sessions
+
+fathom calibrate --project myapp
+# Shows: Feature | Drift | Suggested adjustment multiplier
+```
+
+Over time, your estimates get more accurate as the profiles learn from real data.
+
+### 4. Velocity Intelligence
+
+```bash
+fathom velocity --project myapp --benchmarks
+# "M-complexity React components: $0.85 avg, 1.1 days, 2.8 sessions"
+```
+
+## Dashboard
+
+Fathom includes a real-time web dashboard (Next.js + Convex) with 7 views: overview, projects, burn-down, intake queue, cost analytics, velocity benchmarks, and calibration health.
+
+```bash
+# Set up Convex sync (optional — CLI works fully offline)
+export CONVEX_URL=https://your-deployment.convex.cloud
+
+# All commands auto-sync when CONVEX_URL is set
+fathom analyze spec.md --project myapp  # → syncs estimates
+fathom track --project myapp            # → syncs actuals
+```
+
+See the [full repo](https://github.com/olivelliott/fathom) for dashboard setup.
+
+## Intake Pipeline
+
+Turn raw feedback into estimated, structured work items:
+
+```bash
+# From text
+fathom intake "Users say the calendar is slow and Zoom links are missing" --project myapp
+
+# From a file
+fathom intake --file meeting-notes.md --project myapp --markdown
+```
+
+Requires `ANTHROPIC_API_KEY` environment variable.
+
+## Environment Variables
+
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `ANTHROPIC_API_KEY` | For `estimate` + `intake` | AI complexity scoring and work item extraction |
+| `CONVEX_URL` | Optional | Enable dashboard sync |
+
+## Spec Format
+
+Fathom parses markdown specs with `### Feature:` headings:
+
+```markdown
+### Feature: User Authentication
+- **Complexity**: L
+- **Category**: Infrastructure
+- **Description**: OAuth2 with Google + email/password login
+
+### Feature: Dashboard
+- **Complexity**: M
+- **Category**: Frontend
+- **Description**: Main dashboard with metrics and charts
+```
+
+## Links
+
+- [GitHub Repository](https://github.com/olivelliott/fathom)
+- [Roadmap](https://github.com/olivelliott/fathom/blob/main/ROADMAP.md)
+- [Report an Issue](https://github.com/olivelliott/fathom/issues)
+
+## License
+
+MIT

package/dist/data/remote-manifest.json

@@ -0,0 +1,78 @@
+{
+  "version": 1,
+  "updated": "2026-03-05",
+  "models": [
+    {
+      "id": "claude-opus-4-6",
+      "provider": "anthropic",
+      "name": "Claude Opus 4.6",
+      "input_per_mtok": 15.0,
+      "output_per_mtok": 75.0,
+      "cache_read_per_mtok": 1.5,
+      "batch_discount": 0.5,
+      "tier": "frontier"
+    },
+    {
+      "id": "claude-sonnet-4-6",
+      "provider": "anthropic",
+      "name": "Claude Sonnet 4.6",
+      "input_per_mtok": 3.0,
+      "output_per_mtok": 15.0,
+      "cache_read_per_mtok": 0.3,
+      "batch_discount": 0.5,
+      "tier": "balanced"
+    },
+    {
+      "id": "claude-haiku-4-5",
+      "provider": "anthropic",
+      "name": "Claude Haiku 4.5",
+      "input_per_mtok": 1.0,
+      "output_per_mtok": 5.0,
+      "cache_read_per_mtok": 0.1,
+      "batch_discount": 0.5,
+      "tier": "speed"
+    }
+  ],
+  "recommendations": {
+    "architecture": {
+      "model": "claude-opus-4-6",
+      "reason": "Deep reasoning, trade-off analysis"
+    },
+    "complex-implementation": {
+      "model": "claude-sonnet-4-6",
+      "reason": "Best cost/capability for multi-file coding"
+    },
+    "standard-crud": {
+      "model": "claude-sonnet-4-6",
+      "reason": "Reliable, fast, cost-effective"
+    },
+    "scaffolding": {
+      "model": "claude-haiku-4-5",
+      "reason": "Speed + cost over reasoning depth"
+    },
+    "documentation": {
+      "model": "claude-haiku-4-5",
+      "reason": "Straightforward generation"
+    },
+    "test-generation": {
+      "model": "claude-sonnet-4-6",
+      "reason": "Needs code logic understanding"
+    },
+    "code-review": {
+      "model": "claude-opus-4-6",
+      "reason": "Benefits from deeper reasoning"
+    },
+    "debugging": {
+      "model": "claude-opus-4-6",
+      "reason": "Benefits from deeper reasoning"
+    },
+    "refactoring-architectural": {
+      "model": "claude-opus-4-6",
+      "reason": "Needs system-wide understanding"
+    },
+    "refactoring-mechanical": {
+      "model": "claude-sonnet-4-6",
+      "reason": "Pattern application"
+    }
+  }
+}