{"_id":"@aquarium-tools/fathom","_rev":"5-98991e4e8993dac70da72598a9849cff","name":"@aquarium-tools/fathom","dist-tags":{"latest":"1.1.0"},"versions":{"0.1.0":{"name":"@aquarium-tools/fathom","version":"0.1.0","keywords":["claude-code","telemetry","observability","hooks","ai-tools"],"license":"MIT","_id":"@aquarium-tools/fathom@0.1.0","maintainers":[{"name":"rmferguson","email":"rmferguson@pm.me"}],"homepage":"https://github.com/rmferguson/fathom#readme","bugs":{"url":"https://github.com/rmferguson/fathom/issues"},"bin":{"fathom":"dist/cli/index.js"},"dist":{"shasum":"f965f36637f756918f1cbc59e8866565e021e08c","tarball":"https://registry.npmjs.org/@aquarium-tools/fathom/-/fathom-0.1.0.tgz","fileCount":26,"integrity":"sha512-bBYzvxtTJWYngpNKLskrYdMA01aMrZeoZcEZ8BqdMpUnI0xw/6QvKVgOrz2SBPTKMVUf+4e1Pmzn/UoLgvLXww==","signatures":[{"sig":"MEUCIQCikqzG2zSGqspkwWEGKplJKexfwqq7y+JNspAeglumxgIgUINg3OEgb6B9SjjpBh3AonntexsrktCWcdmpWVWhyi8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":71702},"main":"./dist/index.js","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"8caa31b8d5a054c846c14b2badc72ee73c4d1b50","scripts":{"dev":"tsx src/cli/index.ts","test":"vitest run","build":"tsc","test:watch":"vitest","install-hooks":"tsx scripts/install.ts","prepublishOnly":"npm run build"},"_npmUser":{"name":"rmferguson","email":"rmferguson@pm.me"},"repository":{"url":"git+https://github.com/rmferguson/fathom.git","type":"git"},"_npmVersion":"10.9.2","description":"Hooks-based telemetry and observability for Claude Code sessions","directories":{},"_nodeVersion":"22.14.0","dependencies":{"commander":"^12.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^4.1.5","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/fathom_0.1.0_1776914732038_0.749627210097026","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@aquarium-tools/fathom","version":"0.2.0","keywords":["claude-code","telemetry","observability","hooks","ai-tools"],"license":"MIT","_id":"@aquarium-tools/fathom@0.2.0","maintainers":[{"name":"rmferguson","email":"rmferguson@pm.me"}],"homepage":"https://github.com/rmferguson/fathom#readme","bugs":{"url":"https://github.com/rmferguson/fathom/issues"},"bin":{"fathom":"dist/cli/index.js"},"dist":{"shasum":"4ecc447004e1abb5df345d7731741e8f2ee870fd","tarball":"https://registry.npmjs.org/@aquarium-tools/fathom/-/fathom-0.2.0.tgz","fileCount":27,"integrity":"sha512-ePSuAeuOrzqurkSRZXbHdjSoYAifC3OLqWE9IWfSmX0BOWyvCcekKtZ/+edcQd1nGpG+RE34+KvwSTBE+WC/Xg==","signatures":[{"sig":"MEUCIHUc7+uHCceztjlqw+rM4G7YaEerz1pZo+uesT+CSpE6AiEA9BuYM5ZgyjJ4FvaFxU/emClzBPOAELLVrqJ5hR8spTQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":108728},"main":"./dist/index.js","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"488478d68736436df5e86c8c3bd91f9ceb8de2b8","scripts":{"dev":"tsx src/cli/index.ts","test":"vitest run","build":"tsc","test:watch":"vitest","install-hooks":"tsx scripts/install.ts","prepublishOnly":"npm run build"},"_npmUser":{"name":"rmferguson","email":"rmferguson@pm.me"},"repository":{"url":"git+https://github.com/rmferguson/fathom.git","type":"git"},"_npmVersion":"10.9.2","description":"Hooks-based telemetry and observability for Claude Code sessions","directories":{},"_nodeVersion":"22.14.0","dependencies":{"commander":"^12.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^4.1.5","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/fathom_0.2.0_1777340842012_0.7960030595513239","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"name":"@aquarium-tools/fathom","version":"0.5.0","keywords":["claude-code","telemetry","observability","hooks","ai-tools"],"license":"MIT","_id":"@aquarium-tools/fathom@0.5.0","maintainers":[{"name":"rmferguson","email":"rmferguson@pm.me"}],"homepage":"https://github.com/rmferguson/fathom#readme","bugs":{"url":"https://github.com/rmferguson/fathom/issues"},"bin":{"fathom":"dist/cli/index.js"},"dist":{"shasum":"5e33f8f92fdd2cb5e7b3c74a45cd158db166c3a8","tarball":"https://registry.npmjs.org/@aquarium-tools/fathom/-/fathom-0.5.0.tgz","fileCount":27,"integrity":"sha512-tit9L6thT85KSYs5MPW1FrLyFeT+swXb44fJBcuvvC0QUnSaY7zhUy7B9BqJVkvMFiCypRCcixzeHVm/gOJ2XQ==","signatures":[{"sig":"MEUCIQCTS5ijrEWZbE8r8T5celiWRWONBJctjN0bhMJYVeQBggIgUvkigUhRbhREBg23ydANJT8PBp7Dl77Hj6Oy/uKhLUQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":131576},"main":"./dist/index.js","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"bee4152be618fa4a5b01fa0140354aa41af3754e","scripts":{"dev":"tsx src/cli/index.ts","test":"vitest run","build":"tsc","format":"prettier --write \"src/**/*.ts\" \"scripts/**/*.ts\"","test:watch":"vitest","format:check":"prettier --check \"src/**/*.ts\" \"scripts/**/*.ts\"","install-hooks":"tsx scripts/install.ts","prepublishOnly":"npm run build"},"_npmUser":{"name":"rmferguson","email":"rmferguson@pm.me"},"repository":{"url":"git+https://github.com/rmferguson/fathom.git","type":"git"},"_npmVersion":"10.9.2","description":"Hooks-based telemetry and observability for Claude Code sessions","directories":{},"_nodeVersion":"22.14.0","dependencies":{"commander":"^12.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^4.1.5","prettier":"^3.8.3","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/fathom_0.5.0_1777504145323_0.2084494961042762","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@aquarium-tools/fathom","version":"1.0.5","keywords":["claude-code","telemetry","observability","hooks","ai-tools"],"license":"MIT","_id":"@aquarium-tools/fathom@1.0.5","maintainers":[{"name":"rmferguson","email":"rmferguson@pm.me"}],"homepage":"https://github.com/rmferguson/fathom#readme","bugs":{"url":"https://github.com/rmferguson/fathom/issues"},"bin":{"fathom":"dist/cli/index.js"},"dist":{"shasum":"37b61626662e560df196232dfe5c38bb42ae1997","tarball":"https://registry.npmjs.org/@aquarium-tools/fathom/-/fathom-1.0.5.tgz","fileCount":27,"integrity":"sha512-o+/ELLDdibkQ7Pdde+bQ+8BH7u6G7eUDq4ui3LuYjP2bKyJIx1UnCPD282C5kzQZwdur7lNkoqU/m8tggB5xxA==","signatures":[{"sig":"MEUCIGhxa1oTejHry4n6rZ8OJCZO6EIHubST5HwirZNQMSUvAiEA5PzAGuAFl+BjEipa6APKZg4I7LHSLYVMx5nRee33Gq8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aquarium-tools%2ffathom@1.0.5","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":179255},"main":"./dist/index.js","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"13fd6724384d98e61b084229dbd876b1404d9932","scripts":{"dev":"tsx src/cli/index.ts","test":"vitest run","build":"tsc","format":"prettier --write \"src/**/*.ts\" \"scripts/**/*.ts\"","test:watch":"vitest","format:check":"prettier --check \"src/**/*.ts\" \"scripts/**/*.ts\"","install-hooks":"tsx scripts/install.ts","prepublishOnly":"npm run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ca79fee3-2c7c-43d4-b29e-81427a76be4a"}},"repository":{"url":"git+https://github.com/rmferguson/fathom.git","type":"git"},"_npmVersion":"11.14.0","description":"Hooks-based telemetry and observability for Claude Code sessions","directories":{},"_nodeVersion":"22.22.2","dependencies":{"commander":"^12.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^4.1.5","prettier":"^3.8.3","typescript":"^5.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/fathom_1.0.5_1778096126639_0.2553149860257795","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@aquarium-tools/fathom","version":"1.1.0","description":"Hooks-based telemetry and observability for Claude Code sessions","license":"MIT","bin":{"fathom":"dist/cli/index.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"build":"tsc","prepublishOnly":"npm run build","dev":"tsx src/cli/index.ts","install-hooks":"tsx scripts/install.ts","test":"vitest run","test:watch":"vitest","format":"prettier --write \"src/**/*.ts\" \"scripts/**/*.ts\"","format:check":"prettier --check \"src/**/*.ts\" \"scripts/**/*.ts\""},"dependencies":{"commander":"^12.0.0"},"devDependencies":{"@types/node":"^20.0.0","prettier":"^3.8.3","tsx":"^4.0.0","typescript":"^5.0.0","vitest":"^4.1.5"},"engines":{"node":">=20"},"repository":{"type":"git","url":"git+https://github.com/rmferguson/fathom.git"},"homepage":"https://github.com/rmferguson/fathom#readme","bugs":{"url":"https://github.com/rmferguson/fathom/issues"},"publishConfig":{"access":"public"},"keywords":["claude-code","telemetry","observability","hooks","ai-tools"],"gitHead":"76a93312a14557193a411813c42cb7131c9c4591","_id":"@aquarium-tools/fathom@1.1.0","_nodeVersion":"22.23.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-ne8rPSGaruMFYrPYPwR8nLJOIC/AM4fSMnSKMYfQgJBNQnUedTY8LZFI3NAu/gIlqZcJ3jCePpq5f4d+2UFCBA==","shasum":"0bf9fab57b195b8d6c115f4ac201d4c3a5a8a88d","tarball":"https://registry.npmjs.org/@aquarium-tools/fathom/-/fathom-1.1.0.tgz","fileCount":27,"unpackedSize":188126,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@aquarium-tools%2ffathom@1.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGgRQZXQIO3Yqmu1SFk0O/0mRsSpaqyPUmNYOaSa2EX/AiAX8lvX7VHEv4RTOO2lEZuYwyZJdV8Nd+go3srAvCQ9kg=="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ca79fee3-2c7c-43d4-b29e-81427a76be4a"}},"directories":{},"maintainers":[{"name":"rmferguson","email":"rmferguson@pm.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/fathom_1.1.0_1782500547807_0.9598777742750626"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-23T03:25:31.939Z","modified":"2026-06-26T19:02:28.319Z","0.1.0":"2026-04-23T03:25:32.172Z","0.2.0":"2026-04-28T01:47:22.154Z","0.5.0":"2026-04-29T23:09:05.471Z","1.0.5":"2026-05-06T19:35:26.788Z","1.1.0":"2026-06-26T19:02:28.010Z"},"bugs":{"url":"https://github.com/rmferguson/fathom/issues"},"license":"MIT","homepage":"https://github.com/rmferguson/fathom#readme","keywords":["claude-code","telemetry","observability","hooks","ai-tools"],"repository":{"type":"git","url":"git+https://github.com/rmferguson/fathom.git"},"description":"Hooks-based telemetry and observability for Claude Code sessions","maintainers":[{"name":"rmferguson","email":"rmferguson@pm.me"}],"readme":"# fathom\n\n[![npm](https://img.shields.io/npm/v/@aquarium-tools/fathom.svg)](https://www.npmjs.com/package/@aquarium-tools/fathom)\n\n## Fathom Your Data\n\nHooks-based workflow telemetry for [Claude Code](https://claude.ai/code) sessions. Tracks tool invocations, session timing, and subagent dispatches locally.\n\n> **Important Limitation:** Claude Code does not expose per-turn token usage through hooks. Token counts appear only for `Agent` tool completions. For most sessions, token fields will be zero.\n> This tool is best used with workflows that routinely dispatch tasks via SubAgents so you can measure the effectiveness of those prompts and supporting files.\n\n## Install\n\n```bash\nnpm install -g @aquarium-tools/fathom\nfathom install              # global ~/.claude/settings.json\nfathom install --local      # project-local .claude/settings.local.json\n```\n\nAfter install, fathom hooks fire automatically during every Claude Code session.\n\n## Usage\n\n```bash\n$ fathom summary\n\nProject: /home/user/projects/myapp\n\nSession: a3f8b2c1...\nStarted: 2026-04-21T19:46:00.123\nDuration: 14.2m\n\nTokens\n  Total:        0\n  Input:        0\n  Output:        0\n  Cache read:   0\n\nTop tools\n  Bash                 34\n  Read                 28\n  Edit                 12\n  Write                 4\n  Agent                 2\n```\n\n*Reminder*: Token counts populate only when the `Agent` tool is invoked (Claude Code includes usage data in the Agent tool response).\n\n## Commands\n\n```bash\nfathom summary      Last session: tool calls, duration, token counts (Agent tool only)\nfathom sessions     List recent sessions with tool and timing stats\nfathom session <id> Full detail for a single session (id prefix ok, min 8 chars)\nfathom trend        All-time tool call counts; token totals (Agent tool only)\nfathom projects     List all projects that have recorded events\nfathom export       Dump raw events as JSON or JSONL\nfathom prune        Remove old events from the sink file\nfathom install      Register hook handlers in Claude Code settings\nfathom uninstall    Remove hook handlers from Claude Code settings\n```\n\n### Project filtering\n\nAll commands default to the current git repo. Use flags to change scope:\n\n```bash\nfathom summary --project myrepo    # filter by project name or path\nfathom summary --all               # all projects\n```\n\n### Sessions\n\n```bash\nfathom sessions                        # list recent sessions (current project)\nfathom sessions --all                  # all projects (adds PROJECT column)\nfathom sessions --json                 # JSON array with session_id, tokens, cost\nfathom sessions --group-by-project     # one row per project with rolled-up totals\nfathom sessions --group-by-project --json\n```\n\n### Session detail\n\n```bash\nfathom session <id>             # full session detail by exact or 8-char prefix\nfathom session <id> --json      # machine-readable JSON (session, errors fields)\nfathom session <id> --timeline  # include chronological event timeline\nfathom session <id> --all       # search across all projects\n```\n\n### Export\n\n```bash\nfathom export                      # JSONL (default)\nfathom export --format json        # pretty JSON\nfathom export --all --format json > events.json\n```\n\n### Pruning\n\nThe sink file grows indefinitely. Growth depends on session intensity (tool calls per session vary widely). At moderate usage (~8 sessions/day) expect roughly 100–250 MB/year; sprint-heavy days with many subagents push the high end. Prune old events with:\n\n```bash\nfathom prune --keep-days 90        # drop everything older than 90 days\nfathom prune --before 2026-01-01   # drop everything before a specific date\nfathom prune --keep-days 90 --yes  # skip confirmation prompt (useful in cron)\n```\n\nMalformed lines in the sink are always kept rather than silently dropped.\n\n## Data\n\nEvents are written to `~/.fathom/events.jsonl` as newline-delimited JSON.\n\nOverride the sink path by exporting `FATHOM_SINK` in your shell profile. It must be set in the environment Claude Code inherits — setting it inline for the CLI command only affects reads, not where the hook handler writes events.\n\n```bash\nexport FATHOM_SINK=/path/to/file    # in ~/.bashrc, ~/.zshrc, etc.\n```\n\nDisable without uninstalling:\n```bash\nexport FATHOM_OFF=1\n```\n\nUninstall (removes hooks from settings, leaves event data intact):\n```bash\nfathom uninstall              # global ~/.claude/settings.json\nfathom uninstall --local      # project-local .claude/settings.local.json\n```\n\n## Schema versioning\n\nEvery event written to the sink carries a `schema_version` field (currently `1.0.0`). Downstream consumers should pin to a major version range and fail fast on a mismatch:\n\n```ts\nimport type { FathomEvent } from \"@aquarium-tools/fathom\";\n\nconst SUPPORTED_MAJOR = 1;\nfunction check(e: FathomEvent) {\n  const major = parseInt(e.schema_version.split(\".\")[0], 10);\n  if (major !== SUPPORTED_MAJOR) {\n    throw new Error(`Unsupported fathom schema ${e.schema_version}`);\n  }\n}\n```\n\nVersioning rules fathom commits to:\n\n- **Patch** (`1.0.x`): bug fixes that don't change wire format. Always safe.\n- **Minor** (`1.x.0`): additive only. New optional fields, new event types, new payload variants. Existing consumers keep working.\n- **Major** (`x.0.0`): breaking. Field removal, renames, or type changes. Consumers must opt in by widening their pinned range.\n\nWhat this means in practice:\n\n- Treat any field marked optional in `src/schema/v1.ts` as truly optional — it may be absent on older or newer events.\n- New `event_type` values may appear within a major version. Use a default branch in your switch statements rather than asserting the union is exhaustive.\n- The `hook_source` field on `session_end` events is the contract between fathom's capture and aggregation layers; consumers using `aggregate()` shouldn't need to look at it directly.\n\n### Deprecated fields\n\n| Field | Since | Status | Notes |\n|-------|-------|--------|-------|\n| `SessionEndPayload.wall_time_ms` | 1.0.0 | **Deprecated — always `undefined`** | Claude Code's Stop and SessionEnd hooks do not populate a wall-time field. The field is retained as `?: number` for forward compatibility in case a future hook version supplies it. Do not read `wall_time_ms` from events. Derive session duration from `Date.parse(session_end.timestamp) - Date.parse(session_start.timestamp)` instead — that is what `aggregate()` does internally. |\n\n## Cost estimation\n\n`fathom summary` and `fathom trend` print an estimated USD cost for Agent-tool usage when token data is present.\n\n**Two hard limits apply:**\n- Cost only reflects Agent-tool spend — the only place Claude Code hooks expose token counts. Top-level orchestrator token usage is not counted.\n- The hook API does not tell you which model handled a turn, so a single rate is applied to all subagent spend.\n\nDefaults match Claude Sonnet pricing (USD per 1M tokens):\n\n```bash\nexport FATHOM_PRICE_INPUT=3\nexport FATHOM_PRICE_OUTPUT=15\nexport FATHOM_PRICE_CACHE_READ=0.3\nexport FATHOM_PRICE_CACHE_WRITE=3.75\n```\n\nIf your agents run on Opus, the default estimate will be roughly 5× too low. Override with Opus rates:\n\n```bash\nexport FATHOM_PRICE_INPUT=15\nexport FATHOM_PRICE_OUTPUT=75\nexport FATHOM_PRICE_CACHE_READ=1.5\nexport FATHOM_PRICE_CACHE_WRITE=18.75\n```\n\nTreat cost output as order-of-magnitude, not an invoice.\n\n## Time-range filtering\n\nAll commands accept ISO 8601 `--since` and `--until` bounds:\n\n```bash\nfathom summary --since 2026-04-01T00:00:00Z\nfathom trend   --since 2026-04-01 --until 2026-04-21\nfathom export  --since 2026-04-21T12:00:00Z --format json\n```\n\n## How it works\n\nFathom is *workflow telemetry*, not model telemetry.\n\nHooks expose tool invocations, subagent dispatches, and session boundaries, but not main-session token usage or cost. Token counts are only available for `Agent` tool completions, where Claude Code includes usage data in the tool response. Per-turn token data for the top-level session isn't exposed by any hook.\n\nFathom registers handlers for these Claude Code's events:\n\n- `PostToolUse`\n- `PreToolUse`\n- `PostToolUseFailure`\n- `SessionStart`\n- `SessionEnd`\n- `Stop`\n- `Notification`\n- `SubagentStart`\n- `SubagentStop`\n- `PreCompact`\n\nWhere each hook invocation writes one event to the sink, while the CLI reads at query time. There are no background processes, daemons or anything you need to worry about.\n\n## Pairs with\n\n**[Tackline](https://github.com/tyevans/tackline)** — composable Claude Code workflows. Skills like `/blossom`, `/consensus`, and `/premortem` dispatch parallel subagents, which is when fathom's token tracking actually populates. Run `fathom summary` after a heavy session to see where the cost went.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}