fathom-cli 0.3.1 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fathom-cli",
-  "version": "0.3.1",
+  "version": "0.3.4",
   "description": "Headless intelligence layer for AI-augmented development — intent-driven, provider-agnostic, self-improving. Active development.",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
   "files": [
     "dist",
     "dist/data",
+    "plugins/fathom",
     "README.md"
   ],
   "keywords": [
@@ -41,7 +42,12 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/olivelliott/fathom"
+    "url": "https://github.com/olivelliott/fathom.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/olivelliott/fathom",
+  "bugs": {
+    "url": "https://github.com/olivelliott/fathom/issues"
   },
   "author": "olivelliott",
   "license": "MIT",
@@ -67,13 +73,13 @@
     "tsup": "^8.3.0",
     "typescript": "^5.7.0",
     "vitest": "^2.1.0",
-    "@fathom/intent": "0.1.0",
     "@fathom/core": "0.1.0",
     "@fathom/intake": "0.1.0",
-    "@fathom/projections": "0.1.0",
+    "@fathom/intent": "0.1.0",
     "@fathom/reports": "0.1.0",
-    "@fathom/store": "0.1.0",
+    "@fathom/projections": "0.1.0",
     "@fathom/sync": "0.1.0",
+    "@fathom/store": "0.1.0",
     "@fathom/velocity": "0.1.0",
     "@fathom/tracker": "0.1.0"
   },

package/plugins/fathom/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "fathom",
+  "description": "AI cost intelligence for Claude Code. Estimate token costs, get model recommendations, track budgets, and generate tool-specific rules -- all without leaving your workflow.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Fathom"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/olive/fathom"
+  },
+  "license": "MIT"
+}

package/plugins/fathom/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "fathom": {
+      "command": "npx",
+      "args": ["-y", "fathom-token-mcp@latest", "--project-dir", "."]
+    }
+  }
+}

package/plugins/fathom/skills/budget/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: budget
+description: Check the project's AI spending budget status including monthly limit, current spend, remaining balance, and burn rate.
+argument-hint: "[optional: budget question]"
+---
+
+# Check Budget
+
+Check the project's current AI spending budget status.
+
+## Steps
+
+1. Call `fathom_check_budget` with no arguments
+2. Present the budget status clearly
+
+## Output Format
+
+| Metric | Value |
+|--------|-------|
+| Monthly Limit | ${monthlyLimit} |
+| Current Spend | ${currentSpend} |
+| Remaining | ${remaining} |
+| Burn Rate | ${dailyBurnRate}/day |
+| Days Until Limit | {daysRemaining} |
+
+## Threshold Interpretation
+
+Interpret the spending level for the user:
+- **Below 50%** -- Healthy. Plenty of budget remaining.
+- **50-79%** -- Moderate. On track but worth monitoring.
+- **80-89%** -- Caution. Approaching the monthly limit.
+- **90%+** -- Warning. Budget nearly exhausted. Consider using more economical models or deferring non-critical tasks.
+
+## Error Handling
+
+If no budget is configured, tell the user to set one up:
+- Run `fathom init` to create a project configuration, or
+- Manually add a budget section to `.fathom/intent.yaml`
+
+If the `fathom_check_budget` MCP tool is not available, tell the user to check their MCP configuration. They may need to run `npx fathom-token-mcp` or verify that the Fathom MCP server is configured in their `.mcp.json`.

package/plugins/fathom/skills/budget-warning/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: budget-warning
+description: Check project budget status and warn proactively when spending approaches the configured monthly limit. Activate when the user is about to start work that will consume tokens, especially at the beginning of work sessions or before large tasks.
+user-invocable: false
+---
+
+# Proactive Budget Warning
+
+Check the project's budget status and warn if spending is approaching or has exceeded the configured monthly limit.
+
+## Activation
+
+Trigger at natural checkpoints:
+- Start of a new work session
+- Before the user begins a large task (L or XL complexity)
+- When budget-related context is relevant
+
+## Steps
+
+1. Call `fathom_check_budget` to get current budget status
+2. Evaluate the spending level against thresholds:
+   - Below 50%: No warning needed
+   - 50-79%: No warning, but note if asked
+   - 80-89%: Gentle note about approaching limit
+   - 90-99%: Clear warning with remaining budget
+   - 100%+: Strong warning that budget is exceeded
+3. If a warning is warranted, present it briefly using the appropriate format below
+
+## Warning Behavior
+
+- Warn at most ONCE per conversation at each threshold level
+- If you already warned about 80% in this conversation, only warn again if it crosses 90%
+- Never repeat the same warning in the same session
+- Do not warn at all if budget data is unavailable -- just skip silently
+
+## Format
+
+At 80-89%:
+
+> Budget note: You've used {percent}% of your ${monthlyLimit}/month budget (${remaining} remaining). Current burn rate: ${dailyBurnRate}/day.
+
+At 90-99%:
+
+> Budget warning: ${remaining} remaining of ${monthlyLimit}/month budget ({percent}% used). At current rate, budget runs out in {daysRemaining} days. Consider using a more economical model or deferring non-critical tasks.
+
+At 100%+:
+
+> Budget exceeded: You've spent ${currentSpend} against a ${monthlyLimit}/month limit. All further AI usage is over budget. Consider pausing non-essential tasks or adjusting your monthly limit in .fathom/intent.yaml.
+
+## Fallback
+
+If budget data is not configured, skip silently. The user can configure a budget via `fathom init` or by editing `.fathom/intent.yaml`.

package/plugins/fathom/skills/cost-preview/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: cost-preview
+description: Automatically preview estimated cost when the user describes building, implementing, creating, or writing code for a specific feature or task. Do not activate for questions, discussions, debugging, or code review.
+user-invocable: false
+---
+
+# Inline Cost Preview
+
+When the user describes a concrete implementation task, automatically provide a brief cost estimate alongside your normal response.
+
+## Activation Criteria
+
+ACTIVATE when the user says things like:
+- "Build a user authentication system"
+- "Create a React component for..."
+- "Implement the payment integration"
+- "Write tests for the API"
+- "Add a new database table for..."
+- "Set up CI/CD pipeline"
+
+DO NOT activate for:
+- Questions ("How does X work?")
+- Discussions ("Should we use React or Vue?")
+- Code review ("Can you review this PR?")
+- Debugging ("Why is this test failing?")
+- Reading/exploring code ("Show me the auth module")
+- Planning ("What should we build next?")
+
+## Task Type Mapping
+
+Map the user's description to one of these task types:
+- **scaffold**: Project setup, boilerplate, initial structure
+- **api-endpoint**: REST/GraphQL endpoints, server routes, handlers
+- **react-component**: UI components, pages, forms, layouts
+- **complex-ui**: Animations, data visualizations, interactive widgets
+- **database-schema**: Schema design, migrations, ORM models
+- **integration**: Third-party APIs, OAuth, webhooks, external services
+- **test-unit**: Unit tests, test utilities, mocking
+- **test-e2e**: End-to-end tests, integration tests, test infrastructure
+- **devops**: CI/CD, Docker, deployment configs, infrastructure
+- **documentation**: README, API docs, guides, comments
+- **refactoring**: Code restructuring, performance optimization, cleanup
+- **architecture**: System design, major structural changes
+- **debugging**: Bug fixes, error investigation, troubleshooting
+
+## Complexity Guide
+
+- **S**: Quick change, 1-2 files, well-understood pattern
+- **M**: Standard feature, 3-5 files, some design decisions
+- **L**: Complex feature, 5-10 files, significant design work
+- **XL**: Major system change, 10+ files, cross-cutting concerns
+
+## Steps
+
+1. Identify the task type from the user's description using the mapping above
+2. Estimate complexity (S/M/L/XL) based on the scope described
+3. Call `fathom_estimate_task_cost` with the inferred taskType and complexity
+4. Present a 1-line cost note appended to your normal response
+
+## Format
+
+Keep it to one line appended to your normal response:
+
+> Cost estimate: ~${cost} ({tokens} tokens on {model}) for this {complexity} {taskType} task.
+
+Do NOT make this the focus of your response. It is supplementary information. Do not interrupt your normal response flow.
+
+## Fallback
+
+If the cost-preview didn't auto-trigger, the user can always run /fathom:estimate manually.

package/plugins/fathom/skills/estimate/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: estimate
+description: Estimate the token cost and dollar amount for an AI task before starting work. Use when the user asks about cost, tokens, or wants to know how expensive a task will be.
+argument-hint: "[task description]"
+---
+
+# Estimate Task Cost
+
+Estimate how many tokens and dollars a task will cost before the user starts working on it.
+
+## Input
+
+The user provides a task description via $ARGUMENTS. If no arguments provided, ask what task they want to estimate.
+
+## Task Type Mapping
+
+Map the user's description to one of these task types:
+- **scaffold**: Project setup, boilerplate, initial structure
+- **api-endpoint**: REST/GraphQL endpoints, server routes, handlers
+- **react-component**: UI components, pages, forms, layouts
+- **complex-ui**: Animations, data visualizations, interactive widgets
+- **database-schema**: Schema design, migrations, ORM models
+- **integration**: Third-party APIs, OAuth, webhooks, external services
+- **test-unit**: Unit tests, test utilities, mocking
+- **test-e2e**: End-to-end tests, integration tests, test infrastructure
+- **devops**: CI/CD, Docker, deployment configs, infrastructure
+- **documentation**: README, API docs, guides, comments
+- **refactoring**: Code restructuring, performance optimization, cleanup
+- **architecture**: System design, major structural changes
+- **debugging**: Bug fixes, error investigation, troubleshooting
+
+## Complexity Guide
+
+- **S**: Quick change, 1-2 files, well-understood pattern
+- **M**: Standard feature, 3-5 files, some design decisions
+- **L**: Complex feature, 5-10 files, significant design work
+- **XL**: Major system change, 10+ files, cross-cutting concerns
+
+## Steps
+
+1. Infer taskType and complexity from the description
+2. Call `fathom_estimate_task_cost` with taskType and complexity
+3. Present results as a clear summary
+
+## Output Format
+
+| Metric | Value |
+|--------|-------|
+| Task | {taskType} ({complexity}) |
+| Tokens | {input + output with overhead} |
+| Cost | ${estimatedCost} |
+| Model | {recommendedModel} |
+
+If overhead is significant, briefly note the breakdown (retries, context loading, iteration).
+
+## Error Handling
+
+If the `fathom_estimate_task_cost` MCP tool is not available, tell the user to check their MCP configuration. They may need to run `npx fathom-token-mcp` or verify that the Fathom MCP server is configured in their `.mcp.json`.

package/plugins/fathom/skills/gsd/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: estimate-phase
+description: Estimate token cost and recommend a model for a development phase. Use when planning a phase and wanting to know the expected AI cost before starting.
+argument-hint: "[phase goal or description]"
+---
+
+# Estimate Phase Cost
+
+Estimate the total token cost and optimal model for a development phase.
+
+## Input
+
+The user provides a phase goal or description via $ARGUMENTS. This should describe what the phase will accomplish (e.g., "Add authentication with JWT tokens, login/signup pages, and password reset flow").
+
+## Steps
+
+1. Call the `fathom_estimate_task_cost` MCP tool with the phase description from $ARGUMENTS as the task description
+2. Call the `fathom_recommend_model` MCP tool to get the optimal model recommendation for this type of work
+3. Present results in a clear summary:
+   - **Estimated tokens**: input + output token counts
+   - **Estimated cost**: dollar amount
+   - **Recommended model**: which model to use and why
+   - **Confidence level**: how confident the estimate is
+
+## Output Format
+
+Present a concise summary:
+
+**Phase Estimate: [phase name]**
+- Tokens: ~X input / ~Y output
+- Cost: ~$Z
+- Model: [recommended model] — [reason]
+- Confidence: [high/medium/low]
+
+If the estimate confidence is low, suggest breaking the phase into smaller tasks for more accurate estimates.

package/plugins/fathom/skills/projections/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: projections
+description: Generate tool-specific rules and configuration files (Cursor, Copilot, Windsurf, Claude) from your project's intent.yaml.
+argument-hint: "[optional: specific tool to generate for]"
+---
+
+# Generate Projections
+
+Generate tool-specific configuration and rules files from the project's intent.yaml. These files encode your project's intent, constraints, and guardrails into formats that each AI coding tool understands natively.
+
+## Steps
+
+1. Call `fathom_generate_tool_configs` with no arguments
+2. Report which files were generated and where they are located
+
+## Output Format
+
+List the generated files under `.fathom/projections/`:
+
+| Tool | Generated File |
+|------|---------------|
+| Claude | `.fathom/projections/claude/SKILL.md` |
+| Cursor | `.fathom/projections/cursor/.cursorrules` |
+| Copilot | `.fathom/projections/copilot/copilot-instructions.md` |
+| Windsurf | `.fathom/projections/windsurf/.windsurfrules` |
+| Generic | `.fathom/projections/generic/SYSTEM_PROMPT.md` |
+
+After presenting the list, note:
+
+> These files are auto-generated from your intent.yaml. Edit intent.yaml to change the rules, then re-run this skill.
+
+## Error Handling
+
+If intent.yaml is not found, tell the user to run `fathom init` first to create a project configuration with an intent file.
+
+If the `fathom_generate_tool_configs` MCP tool is not available, tell the user to check their MCP configuration. They may need to run `npx fathom-token-mcp` or verify that the Fathom MCP server is configured in their `.mcp.json`.

package/plugins/fathom/skills/recommend-model/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: recommend-model
+description: Get the best AI model for a task based on complexity, requirements, and budget. Use when the user wants to know which model to use.
+argument-hint: "[task description]"
+---
+
+# Recommend Model
+
+Get the optimal AI model recommendation for a specific task based on its complexity, requirements, and the project's budget constraints.
+
+## Input
+
+The user provides a task description via $ARGUMENTS. If no arguments provided, ask what task they need a model recommendation for.
+
+## Complexity Guide
+
+- **S**: Quick change, 1-2 files, well-understood pattern
+- **M**: Standard feature, 3-5 files, some design decisions
+- **L**: Complex feature, 5-10 files, significant design work
+- **XL**: Major system change, 10+ files, cross-cutting concerns
+
+## Steps
+
+1. Infer complexity (S/M/L/XL) from the task description
+2. Call `fathom_recommend_model` with:
+   - `description`: the user's task description
+   - `complexity`: the inferred complexity level
+   - `budget`: if the user mentions a budget limit (e.g., "under $5"), pass it as a number
+3. Present the recommendation clearly
+
+## Output Format
+
+| Detail | Value |
+|--------|-------|
+| Recommended Model | {model name} |
+| Reasoning | {why this model fits the task} |
+| Estimated Cost | ${cost} |
+| Confidence | {confidence level} |
+
+### Alternatives
+
+If the tool returns alternative models, list them:
+
+| Model | Cost | Tradeoff |
+|-------|------|----------|
+| {alt1} | ${cost} | {what you gain/lose} |
+| {alt2} | ${cost} | {what you gain/lose} |
+
+If the user provided a budget, note how the recommendation accounts for their budget.
+
+## Error Handling
+
+If the `fathom_recommend_model` MCP tool is not available, tell the user to check their MCP configuration. They may need to run `npx fathom-token-mcp` or verify that the Fathom MCP server is configured in their `.mcp.json`.

package/plugins/fathom/skills/status/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: status
+description: Get a quick project overview showing feature progress, budget status, and configuration summary.
+argument-hint: "[optional: specific area to check]"
+---
+
+# Project Status
+
+Get a quick overview of the current project's state including feature progress, budget, and configuration.
+
+## Steps
+
+1. Call `fathom_get_project_status` with no arguments
+2. Present the results organized into clear sections
+
+## Output Format
+
+### Features
+
+| Status | Count | Features |
+|--------|-------|----------|
+| Complete | {count} | {list of completed features} |
+| In Progress | {count} | {list of in-progress features} |
+| Pending | {count} | {list of pending features} |
+
+### Budget
+
+{One-line summary: "${spent} of ${limit} used ({percent}%) -- {status}"}
+
+### Configuration
+
+| Setting | Value |
+|---------|-------|
+| Store Type | {file or convex} |
+| Intent Loaded | {yes/no} |
+| Projections | {which tools configured} |
+
+## Error Handling
+
+If the project is not initialized, tell the user to run `fathom init` to set up a Fathom project in the current directory.
+
+If the `fathom_get_project_status` MCP tool is not available, tell the user to check their MCP configuration. They may need to run `npx fathom-token-mcp` or verify that the Fathom MCP server is configured in their `.mcp.json`.

package/plugins/fathom/tests/integrations.test.ts

@@ -0,0 +1,66 @@
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, it, expect } from "vitest";
+
+const DOCS_ROOT = resolve(__dirname, "../../../docs/integrations");
+
+const INTEGRATION_DOCS = [
+  {
+    file: "cursor.md",
+    rootKey: "mcpServers",
+    configPath: ".cursor/mcp.json",
+  },
+  {
+    file: "vscode.md",
+    rootKey: "servers", // VS Code uses different root key!
+    configPath: ".vscode/mcp.json",
+  },
+  {
+    file: "windsurf.md",
+    rootKey: "mcpServers",
+    configPath: "~/.codeium/windsurf/mcp_config.json",
+  },
+  {
+    file: "cline.md",
+    rootKey: "mcpServers",
+    configPath: "cline_mcp_settings.json",
+  },
+];
+
+for (const doc of INTEGRATION_DOCS) {
+  describe(`${doc.file}`, () => {
+    const filePath = resolve(DOCS_ROOT, doc.file);
+
+    it("exists", () => {
+      expect(existsSync(filePath)).toBe(true);
+    });
+
+    it("has 3-section structure (Prerequisites, Configuration, Verify)", () => {
+      const content = readFileSync(filePath, "utf-8");
+      expect(content).toContain("## Prerequisites");
+      expect(content).toContain("## Configuration");
+      expect(content).toContain("## Verify It Works");
+    });
+
+    it(`uses correct root key "${doc.rootKey}"`, () => {
+      const content = readFileSync(filePath, "utf-8");
+      expect(content).toContain(`"${doc.rootKey}"`);
+    });
+
+    it("references fathom-token-mcp", () => {
+      const content = readFileSync(filePath, "utf-8");
+      expect(content).toContain("fathom-token-mcp@latest");
+    });
+
+    it("contains copy-pasteable JSON config block", () => {
+      const content = readFileSync(filePath, "utf-8");
+      expect(content).toContain("```json");
+      expect(content).toContain('"fathom"');
+    });
+
+    it(`mentions config file path ${doc.configPath}`, () => {
+      const content = readFileSync(filePath, "utf-8");
+      expect(content).toContain(doc.configPath);
+    });
+  });
+}

package/plugins/fathom/tests/plugin.test.ts

@@ -0,0 +1,49 @@
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, it, expect } from "vitest";
+
+const PLUGIN_ROOT = resolve(__dirname, "..");
+
+describe("plugin.json", () => {
+  const pluginPath = resolve(PLUGIN_ROOT, ".claude-plugin/plugin.json");
+
+  it("exists", () => {
+    expect(existsSync(pluginPath)).toBe(true);
+  });
+
+  it("is valid JSON with required fields", () => {
+    const raw = readFileSync(pluginPath, "utf-8");
+    const manifest = JSON.parse(raw);
+
+    expect(manifest.name).toBe("fathom");
+    expect(manifest.description).toBeTypeOf("string");
+    expect(manifest.description.length).toBeGreaterThan(0);
+    expect(manifest.version).toMatch(/^\d+\.\d+\.\d+$/);
+    expect(manifest.author?.name).toBeTypeOf("string");
+    expect(manifest.license).toBeTypeOf("string");
+  });
+});
+
+describe(".mcp.json", () => {
+  const mcpPath = resolve(PLUGIN_ROOT, ".mcp.json");
+
+  it("exists", () => {
+    expect(existsSync(mcpPath)).toBe(true);
+  });
+
+  it("is valid JSON with fathom MCP server config", () => {
+    const raw = readFileSync(mcpPath, "utf-8");
+    const config = JSON.parse(raw);
+
+    expect(config.mcpServers.fathom.command).toBe("npx");
+    expect(config.mcpServers.fathom.args).toBeInstanceOf(Array);
+    expect(config.mcpServers.fathom.args).toContain("fathom-token-mcp@latest");
+    expect(config.mcpServers.fathom.args).toContain("--project-dir");
+  });
+});
+
+describe("directory structure", () => {
+  it("skills directory exists", () => {
+    expect(existsSync(resolve(PLUGIN_ROOT, "skills"))).toBe(true);
+  });
+});