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 without sending any data outside your machine.

Claude Code is Anthropic's official CLI for Claude - an AI coding assistant that runs in your terminal. It can read and edit files, run commands, search the codebase, and help you build software. 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 (version 18 or later) 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 so it runs automatically at the end of each session.

Fathom writes JSON files to a local directory on your machine - by default ~/.fathom/sessions/. Each session produces one file named by timestamp (e.g., 2026-06-27T14-32-00Z.json). No data is sent anywhere. Everything stays on disk where you put it.

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.

No. Fathom makes zero outbound network calls. It reads Claude Code session events and writes JSON, all locally. There is no telemetry endpoint, no analytics backend, and no account system. The tool is designed to be completely offline.

By default, Fathom writes to ~/.fathom/sessions/ in your home directory. You can list recent sessions with ls -lt ~/.fathom/sessions/ or read the latest one with cat $(ls -t ~/.fathom/sessions/*.json | head -1). Run fathom summary to get a formatted overview of all recorded sessions without opening individual files.

Any JSON tool works: jq, fx, Python, Node.js, or even a spreadsheet via JSON import. For a quick summary across all sessions, run fathom summary from your terminal. This prints a table of sessions with date, model, token counts, and cost totals.

No. Fathom is a local-only tool. It does not make any network requests. Your session data is written to your local filesystem and goes nowhere else. Aquarium Apps has no server that receives it, no database that stores it, and no way to access it.

Nothing. Aquarium Apps does not operate any backend infrastructure for Fathom. The tool is open source - you can read every line of code to verify this. Fathom is published on npm at @aquarium-tools/fathom and the source is publicly available.

Claude Code sessions can involve sensitive work - private codebases, internal tooling, proprietary business logic. Routing session metadata through a third-party server would create unnecessary risk. Local-only means there is no privacy surface to worry about: your data is yours, stored where you control it, deleted whenever you want.

After installing with npm install -g @aquarium-tools/fathom, add Fathom to the hooks section of your Claude Code settings.json. Point it at the SessionStop event so it runs automatically when each Claude Code session ends. From that point on, Fathom records each session silently in the background. You can also run fathom summary manually at any time to view accumulated data.

Both modes are supported. The recommended setup uses Claude Code's SessionStop hook to run Fathom automatically at the end of every session - no manual step required. If you prefer, you can also invoke fathom record manually after a session. The fathom summary command is always manual.

Run fathom summary from your terminal. It reads all session files from ~/.fathom/sessions/ and prints a table showing date, model, input tokens, output tokens, and cost per session, plus a running total at the bottom. Use fathom summary --since 7d to filter to the past week, or --since 30d for the past month.

Yes. Each Claude Code session produces one JSON file. Fathom accumulates them over time in the same directory. The fathom summary command aggregates all of them. There is no limit on the number of sessions recorded - it depends only on your local disk space.

Check two things: (1) Confirm Fathom is wired into Claude Code's hooks - open your Claude Code settings.json and verify a SessionStop hook entry points to the fathom command. (2) Run fathom record manually from your terminal to confirm the binary is on your PATH and the output directory is writable. If the command fails, re-run npm install -g @aquarium-tools/fathom and check that your npm global bin directory is in your PATH.

Fathom writes to ~/.fathom/sessions/ by default. If that directory does not exist yet, Fathom creates it on first run - but only if your home directory is writable. Check with ls -la ~/.fathom/. If the directory exists but is owned by root (possible after a sudo npm install), fix it with sudo chown -R $(whoami) ~/.fathom.

Fathom requires Node.js 18 or later. Check your version with node --version. If you are on an older version, upgrade via your system package manager or use a version manager like nvm: nvm install 20 && nvm use 20.