Frequently Asked Questions

Fathom is a free, open-source CLI tool that records telemetry from your Claude Code sessions. After each session it writes a structured JSON file to a local directory on your machine, capturing token usage, tool call counts, model used, and estimated cost. It is designed to give you visibility into how you are using Claude Code while sending no data outside your machine.

Claude Code is Anthropic's official CLI for Claude - an AI coding assistant that runs in your terminal.

Fathom works alongside Claude Code to track how much you are spending and what the tool is doing across sessions.

Fathom records the following for each Claude Code session:

• Input tokens, output tokens, and cache tokens consumed
• Estimated cost in USD based on the model and token counts
• Tool calls made and their types (e.g., Read, Edit, Bash)
• Model used (e.g., claude-sonnet-4-5, claude-opus-4)
• Session start time and duration

It does not record the content of your conversations, the code you write, or any personal information.

You need Node.js v18+ and Claude Code installed. Fathom installs as a global npm package. Run npm install -g @aquarium-tools/fathom. Once installed, add Fathom to your Claude Code settings.json hooks via fathom install.

Fathom writes JSON files to a local directory on your machine under ~/.fathom/sessions/ by default. Each session produces one file named by timestamp (e.g., 2026-06-27T14-32-00Z.jsonl).

Each session file is a plain JSON object. It contains fields like model, startedAt, durationMs, tokens (with input, output, and cacheRead sub-fields), costUsd, and toolCalls (a count keyed by tool name). The schema is intentionally simple so any script, spreadsheet, or data tool can read it without a special library.

Any JSON tool works but I personally use jq.

No. Fathom is a local-only tool and makes no network requests.

Nothing.

Fathom runs automatically via a Claude Code hook. There is no manual "record a session" step. After installing, run fathom install to register Fathom's SessionEnd hook in your Claude Code settings, and it fires automatically at the end of every session from then on.

fathom summary shows stats - including estimated cost - for your most recent session. For a table of recent sessions instead, use fathom sessions (-n/--count to control how many). For aggregate token usage and cost across all your sessions, use fathom trend. All three accept --since <iso> and --until <iso> to filter by timestamp.

Yes. Each Claude Code session produces one JSONL file.

Fathom writes to ~/.fathom/sessions/ by default. If that directory does not exist yet, Fathom creates it on first run - if your home directory is writable. If the directory exists but is owned by root, which can happen after a sudo npm install, you can take ownership of it with sudo chown -R $(whoami) ~/.fathom.