{"_id":"@abnersajr/claude-timeline","_rev":"5-99456f2ed8d970e6547d2dd845faa9f2","name":"@abnersajr/claude-timeline","dist-tags":{"latest":"1.0.4"},"versions":{"1.0.0":{"name":"@abnersajr/claude-timeline","version":"1.0.0","keywords":["claude","anthropic","claude-code","timeline","session","extractor","cost-tracker","statusline"],"license":"MIT","_id":"@abnersajr/claude-timeline@1.0.0","maintainers":[{"name":"abnersajr","email":"abnersajr@gmail.com"}],"homepage":"https://github.com/abnersajr/claude-timeline#readme","bugs":{"url":"https://github.com/abnersajr/claude-timeline/issues"},"bin":{"claude-timeline":"dist/cli.js"},"dist":{"shasum":"15e3376b3bc79b615322a9e4fe479d2bd596104c","tarball":"https://registry.npmjs.org/@abnersajr/claude-timeline/-/claude-timeline-1.0.0.tgz","fileCount":87,"integrity":"sha512-MCie5h2kqIEl11gwJLX0xP/FJyAzIu5xb/3NzUv8eNHUAdgr20xryRWD8QxeAx4MHR567ojgYsVM/GP449nMfQ==","signatures":[{"sig":"MEYCIQC/My1lFtor1bhsIwKUxEef0iWHIE8heHU9Aw/qXb5ndQIhAIGvOABWjGvOyEIXytMY8BymaBJ2wQanamH+MGJF+NBw","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1962647},"main":"./dist/cli.js","pnpm":{},"type":"module","engines":{"node":">=22.0.0"},"gitHead":"e7199a3968ef881bc7488c17705056eea26d58eb","scripts":{"dev":"node scripts/dev.mjs","build":"node scripts/build.mjs","dev:api":"turbo dev --filter=claude-timeline-api","prepack":"node scripts/build.mjs","release":"changeset publish","build:cli":"node scripts/build.mjs --cli","build:web":"node scripts/build.mjs --web","changeset":"changeset","typecheck":"turbo run typecheck --filter=./packages/*","build:server":"node scripts/build.mjs --server","version-packages":"changeset version"},"_npmUser":{"name":"abnersajr","email":"abnersajr@gmail.com"},"repository":{"url":"git+https://github.com/abnersajr/claude-timeline.git","type":"git"},"_npmVersion":"10.9.8","description":"Claude Code session timeline — extract, visualize, and track costs from your Claude Code sessions","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"4.4.3","cors":"2.8.5","chalk":"5.6.2","express":"5.1.0","minimist":"1.2.8","commander":"14.0.3","better-sqlite3":"11.7.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@11.0.3","devDependencies":{"tsx":"4.19.2","turbo":"2","tsdown":"0.22.0","vitest":"3.1.1","rolldown":"1.0.0","typescript":"5.7.3","@types/cors":"2.8.17","@types/node":"22.10.5","@biomejs/biome":"2.4.14","@types/express":"5.0.6","@changesets/cli":"^2.31.0","@types/minimist":"1.2.5","@types/better-sqlite3":"7.6.12"},"_npmOperationalInternal":{"tmp":"tmp/claude-timeline_1.0.0_1780619337503_0.3813834162526957","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@abnersajr/claude-timeline","version":"1.0.1","keywords":["claude","anthropic","claude-code","timeline","session","extractor","cost-tracker","statusline"],"license":"MIT","_id":"@abnersajr/claude-timeline@1.0.1","maintainers":[{"name":"abnersajr","email":"abnersajr@gmail.com"}],"homepage":"https://github.com/abnersajr/claude-timeline#readme","bugs":{"url":"https://github.com/abnersajr/claude-timeline/issues"},"bin":{"claude-timeline":"dist/cli.js"},"dist":{"shasum":"12d7e79973f66896e37d880a119552757e38202a","tarball":"https://registry.npmjs.org/@abnersajr/claude-timeline/-/claude-timeline-1.0.1.tgz","fileCount":84,"integrity":"sha512-Gd+GHmE7joZSBgXbmwICYAvkmbLwgOVn4z8NqoytYanMsyRDce3Epws99S5iRcvf1BqOksrgb9u/E6Vf1tx/Cw==","signatures":[{"sig":"MEUCIQDI+oTr+iKrmpdjlMlT71jogbHvcGViyChIoZoJGEWjpwIgDArL4f8C7adKyNr/OCzAXX9fy0Y2hzL0WxndCWNEMGU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1889101},"main":"./dist/cli.js","pnpm":{},"type":"module","engines":{"node":">=22.0.0"},"gitHead":"f3d3707a9691b7b2961a2d7bcce36f58ab7ca409","scripts":{"dev":"node scripts/dev.mjs","build":"node scripts/build.mjs","dev:api":"turbo dev --filter=claude-timeline-api","prepack":"node scripts/build.mjs","release":"changeset publish","build:cli":"node scripts/build.mjs --cli","build:web":"node scripts/build.mjs --web","changeset":"changeset","typecheck":"turbo run typecheck --filter=./packages/*","build:server":"node scripts/build.mjs --server","version-packages":"changeset version"},"_npmUser":{"name":"abnersajr","email":"abnersajr@gmail.com"},"repository":{"url":"git+https://github.com/abnersajr/claude-timeline.git","type":"git"},"_npmVersion":"10.9.8","description":"Claude Code session timeline — extract, visualize, and track costs from your Claude Code sessions","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"4.4.3","cors":"2.8.5","chalk":"5.6.2","express":"5.1.0","minimist":"1.2.8","commander":"14.0.3","better-sqlite3":"11.7.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@11.0.3","devDependencies":{"tsx":"4.19.2","turbo":"2","tsdown":"0.22.0","vitest":"3.1.1","rolldown":"1.0.0","typescript":"5.7.3","@types/cors":"2.8.17","@types/node":"22.10.5","@biomejs/biome":"2.4.14","@types/express":"5.0.6","@changesets/cli":"^2.31.0","@types/minimist":"1.2.5","@types/better-sqlite3":"7.6.12"},"_npmOperationalInternal":{"tmp":"tmp/claude-timeline_1.0.1_1780622536513_0.6958958923261342","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@abnersajr/claude-timeline","version":"1.0.2","keywords":["claude","anthropic","claude-code","timeline","session","extractor","cost-tracker","statusline"],"license":"MIT","_id":"@abnersajr/claude-timeline@1.0.2","maintainers":[{"name":"abnersajr","email":"abnersajr@gmail.com"}],"homepage":"https://github.com/abnersajr/claude-timeline#readme","bugs":{"url":"https://github.com/abnersajr/claude-timeline/issues"},"bin":{"claude-timeline":"dist/cli.js"},"dist":{"shasum":"15d1709412a09851ccb1206c0808396508acdeed","tarball":"https://registry.npmjs.org/@abnersajr/claude-timeline/-/claude-timeline-1.0.2.tgz","fileCount":84,"integrity":"sha512-1aamw2tIWY+v04Vt8drU1BFjM6i2qNjngtDhuFEsrniRgnkohqne0EyN4GBoskgUHdzO1Dqrl31INwD6oEn3Ug==","signatures":[{"sig":"MEQCIGaqzfAgOdsI3aOpUYKAsCUNLG9U3pa6DR7vQ/TO+lfnAiAcgxU+hVNWHm2gZw6bZLv2DK5rC6OScLJcS/3u1i8BxA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1889217},"main":"./dist/cli.js","pnpm":{},"type":"module","engines":{"node":">=22.0.0"},"gitHead":"51e5124f66af84e92210b03cc78ec54ba7da9681","scripts":{"dev":"node scripts/dev.mjs","build":"node scripts/build.mjs","dev:api":"turbo dev --filter=claude-timeline-api","prepack":"node scripts/build.mjs","release":"changeset publish","build:cli":"node scripts/build.mjs --cli","build:web":"node scripts/build.mjs --web","changeset":"changeset","typecheck":"turbo run typecheck --filter=./packages/*","build:server":"node scripts/build.mjs --server","version-packages":"changeset version"},"_npmUser":{"name":"abnersajr","email":"abnersajr@gmail.com"},"repository":{"url":"git+https://github.com/abnersajr/claude-timeline.git","type":"git"},"_npmVersion":"10.9.8","description":"Claude Code session timeline — extract, visualize, and track costs from your Claude Code sessions","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"4.4.3","cors":"2.8.5","chalk":"5.6.2","express":"5.1.0","minimist":"1.2.8","commander":"14.0.3","better-sqlite3":"11.7.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@11.0.3","devDependencies":{"tsx":"4.19.2","turbo":"2","tsdown":"0.22.0","vitest":"3.1.1","rolldown":"1.0.0","typescript":"5.7.3","@types/cors":"2.8.17","@types/node":"22.10.5","@biomejs/biome":"2.4.14","@types/express":"5.0.6","@changesets/cli":"^2.31.0","@types/minimist":"1.2.5","@types/better-sqlite3":"7.6.12"},"_npmOperationalInternal":{"tmp":"tmp/claude-timeline_1.0.2_1780622820575_0.7135424179544256","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@abnersajr/claude-timeline","version":"1.0.3","keywords":["claude","anthropic","claude-code","timeline","session","extractor","cost-tracker","statusline"],"license":"MIT","_id":"@abnersajr/claude-timeline@1.0.3","maintainers":[{"name":"abnersajr","email":"abnersajr@gmail.com"}],"homepage":"https://github.com/abnersajr/claude-timeline#readme","bugs":{"url":"https://github.com/abnersajr/claude-timeline/issues"},"bin":{"claude-timeline":"dist/cli.js"},"dist":{"shasum":"f08d7d2e24afdf4091df0b8ef3a93a27873d7140","tarball":"https://registry.npmjs.org/@abnersajr/claude-timeline/-/claude-timeline-1.0.3.tgz","fileCount":84,"integrity":"sha512-EiVMfaAtrl51EuFpMciirU/COLIqUtKHHmHJ/W+FmnGAaL3bKVrz6vUMqu+pPQeiLAcBZNS50OE/OSaancQyXA==","signatures":[{"sig":"MEQCIAwgfGZ1j0EuqJ6EcR3lN9d5vwqZsw2+DzGnDi7YwANuAiBk11zbbB+PHwFy+XuIHz2v0wiuUWDccHzN0ePX+RAllQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1890467},"main":"./dist/cli.js","pnpm":{},"type":"module","engines":{"node":">=22.0.0"},"gitHead":"0da2fa3d5103b1fe27d5ec74daa31eb1e1771f52","scripts":{"dev":"node scripts/dev.mjs","build":"node scripts/build.mjs","dev:api":"turbo dev --filter=claude-timeline-api","prepack":"node scripts/build.mjs","release":"changeset publish","build:cli":"node scripts/build.mjs --cli","build:web":"node scripts/build.mjs --web","changeset":"changeset","typecheck":"turbo run typecheck --filter=./packages/*","build:server":"node scripts/build.mjs --server","version-packages":"changeset version"},"_npmUser":{"name":"abnersajr","email":"abnersajr@gmail.com"},"repository":{"url":"git+https://github.com/abnersajr/claude-timeline.git","type":"git"},"_npmVersion":"10.9.8","description":"Claude Code session timeline — extract, visualize, and track costs from your Claude Code sessions","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"4.4.3","cors":"2.8.5","chalk":"5.6.2","express":"5.1.0","minimist":"1.2.8","commander":"14.0.3","better-sqlite3":"11.7.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@11.0.3","devDependencies":{"tsx":"4.19.2","turbo":"2","tsdown":"0.22.0","vitest":"3.1.1","rolldown":"1.0.0","typescript":"5.7.3","@types/cors":"2.8.17","@types/node":"22.10.5","@biomejs/biome":"2.4.14","@types/express":"5.0.6","@changesets/cli":"^2.31.0","@types/minimist":"1.2.5","@types/better-sqlite3":"7.6.12"},"_npmOperationalInternal":{"tmp":"tmp/claude-timeline_1.0.3_1781648887813_0.5802069997673449","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@abnersajr/claude-timeline","version":"1.0.4","description":"Claude Code session timeline — extract, visualize, and track costs from your Claude Code sessions","type":"module","packageManager":"pnpm@11.0.3","main":"./dist/cli.js","bin":{"claude-timeline":"dist/cli.js"},"repository":{"type":"git","url":"git+https://github.com/abnersajr/claude-timeline.git"},"license":"MIT","publishConfig":{"access":"public"},"keywords":["claude","anthropic","claude-code","timeline","session","extractor","cost-tracker","statusline"],"engines":{"node":">=22.0.0"},"scripts":{"build":"node scripts/build.mjs","build:cli":"node scripts/build.mjs --cli","build:server":"node scripts/build.mjs --server","build:web":"node scripts/build.mjs --web","dev":"node scripts/dev.mjs","dev:api":"turbo dev --filter=claude-timeline-api","prepack":"node scripts/build.mjs","typecheck":"turbo run typecheck --filter=./packages/*","changeset":"changeset","version-packages":"changeset version","release":"changeset publish"},"dependencies":{"better-sqlite3":"11.7.0","chalk":"5.6.2","commander":"14.0.3","cors":"2.8.5","express":"5.1.0","minimist":"1.2.8","zod":"4.4.3"},"devDependencies":{"@biomejs/biome":"2.4.14","@changesets/cli":"^2.31.0","@types/better-sqlite3":"7.6.12","@types/cors":"2.8.17","@types/express":"5.0.6","@types/minimist":"1.2.5","@types/node":"22.10.5","rolldown":"1.0.0","tsdown":"0.22.0","tsx":"4.19.2","turbo":"2","typescript":"5.7.3","vitest":"3.1.1"},"pnpm":{},"_id":"@abnersajr/claude-timeline@1.0.4","gitHead":"f402685e96ce85abe4f159d0622cfce2d313f1f7","bugs":{"url":"https://github.com/abnersajr/claude-timeline/issues"},"homepage":"https://github.com/abnersajr/claude-timeline#readme","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-Uepo9vxHEPxnrqR1LfyY5hH5OQZ4jnErBunOPsQmoWJ1STnBAiCuiavqOOA/bwl4PDn1FhKDlNhwuu+Yws//Qg==","shasum":"9cc7ed6ce6d3afc66dd5adc2099b6a082543f760","tarball":"https://registry.npmjs.org/@abnersajr/claude-timeline/-/claude-timeline-1.0.4.tgz","fileCount":84,"unpackedSize":1894486,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCPNVlvyeqn9n1iSqVFdgv4YrzGXdttGtheBijoeKXlQQIgLyrIklsSPR7G/aeU2TMYZlF+7D3OIeAkg0CXt6uHe+I="}]},"_npmUser":{"name":"abnersajr","email":"abnersajr@gmail.com"},"directories":{},"maintainers":[{"name":"abnersajr","email":"abnersajr@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/claude-timeline_1.0.4_1781707914131_0.9957354259560602"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-05T00:28:57.315Z","modified":"2026-06-17T14:51:54.450Z","1.0.0":"2026-06-05T00:28:57.707Z","1.0.1":"2026-06-05T01:22:16.781Z","1.0.2":"2026-06-05T01:27:00.710Z","1.0.3":"2026-06-16T22:28:07.999Z","1.0.4":"2026-06-17T14:51:54.337Z"},"bugs":{"url":"https://github.com/abnersajr/claude-timeline/issues"},"license":"MIT","homepage":"https://github.com/abnersajr/claude-timeline#readme","keywords":["claude","anthropic","claude-code","timeline","session","extractor","cost-tracker","statusline"],"repository":{"type":"git","url":"git+https://github.com/abnersajr/claude-timeline.git"},"description":"Claude Code session timeline — extract, visualize, and track costs from your Claude Code sessions","maintainers":[{"name":"abnersajr","email":"abnersajr@gmail.com"}],"readme":"

\n \"claude-timeline\"\n

\n\n

\n Extract and visualize Claude Code session timelines
\n Conversations · Tool calls · Pricing · Tokens · Subagents\n

\n\n

\n \"CI\"\n \"npm\n \"license\"\n \"Ko-fi\"\n

\n\n> **👋 About me:** I'm Abner — a dev from Brazil 🇧🇷 now living in Montreal 🍁. This project started because I was frustrated with existing tools and decided to vibe-code my own. It grew into something real, and now I'm sharing it with the community.\n>\n> **☕ Donations** will support continued development of this project, and a portion will be donated to an NGO that takes care of animals 🐾. If this tool saved you time, consider fueling the next feature!\n\n---\n\n## Installation\n\n```bash\nnpm install -g @abnersajr/claude-timeline\n```\n\nOr run directly with npx (no install needed):\n\n```bash\nnpx @abnersajr/claude-timeline\n```\n\n**Requirements:** Node.js >= 22\n\n> **No setup required before sessions.** claude-timeline reads Claude Code's existing transcript files (`~/.claude/projects/`). Install it any time — past sessions are immediately available. Nothing needs to run in the background while you work.\n\n## Usage\n\n### Web UI (recommended)\n\nStart the server and open the interactive timeline in your browser:\n\n```bash\nclaude-timeline serve\n```\n\nOpens `http://localhost:5199` automatically. Use `--port` to change the port:\n\n```bash\nclaude-timeline serve --port 3000\n```\n\n### CLI\n\nList recent sessions:\n\n```bash\nclaude-timeline list\n```\n\nExtract a specific session to JSON:\n\n```bash\nclaude-timeline extract --session-id \n```\n\n### Cost Capture Setup\n\nGet real-time per-turn cost tracking by installing the statusline wrapper:\n\n```bash\nclaude-timeline setup\n```\n\nThis hooks into Claude Code's statusline and captures token usage, pricing, and model data to a local SQLite database. The web UI reads this data for live cost streaming.\n\nTo uninstall, remove the `statusLine` key from `~/.claude/settings.json` and run:\n\n```bash\nrm -rf ~/.claude-timeline/\n```\n\n## What is this?\n\nClaude Code stores rich session data in local SQLite and JSONL files, but there's no built-in way to see the full picture. **claude-timeline** extracts, merges, and visualizes everything — conversations, tool calls, token usage, costs, and subagent activity.\n\n### Features\n\n- 📊 **Full session timelines** — conversations, tool calls, file edits, all in order\n- 💰 **Cost tracking** — per-turn and per-model pricing with token breakdowns\n- 🤖 **Subagent detection** — automatically identifies and resolves subagent sessions\n- 🧠 **Context analysis** — tracks context window usage, phases, and injections\n- 🎨 **Web UI** — interactive timeline visualization with dark/light themes\n- ⚡ **CLI tool** — extract session data from the command line\n\n## CLI Reference\n\n```\nclaude-timeline [options]\n\nCommands:\n serve [--port ] Start web UI + API server (default: 5199)\n extract --session-id Extract a specific session to JSON\n list List all available sessions\n setup Install cost-capture statusline wrapper\n update-pricing Fetch latest model pricing from Anthropic\n --help Show help\n\nOptions:\n --port Server port (serve mode, default: 5199)\n --db-path SQLite DB path (default: ~/.claude/usage.db)\n --projects-dir Projects directory (default: ~/.claude/projects)\n --output Write JSON to file instead of stdout\n```\n\n## Understanding Claude Code Sessions\n\nTo get the most out of claude-timeline, it helps to understand how Claude Code works under the hood.\n\n### Core Concepts\n\n| Concept | What it is |\n|---------|------------|\n| **Session** | A single Claude Code interaction lifecycle. Started when you launch `claude` or run a slash command. All work shares a persistent conversation history. |\n| **Turn** | A single API call to the Claude model. Each turn includes cached context, new input, and model output. |\n| **Token** | A unit of text (~4 English characters). All billing is token-based. \"Hello world\" is roughly 3 tokens. |\n| **Prompt Caching** | Claude caches repeated context (system prompt, conversation history) to avoid re-processing. Cached context is billed at 10% of standard input rates. |\n\n### How Tokens Are Billed\n\nEvery Claude Code interaction uses four billable token types:\n\n| Token Type | What it means | Cost (Sonnet 4) |\n|------------|---------------|-----------------|\n| **Input** | New text sent to the model that is NOT cached. Usually tiny (1-2 tokens). | $3.00 / MTok |\n| **Output** | Model-generated text, tool requests, thinking. The most expensive type. | $15.00 / MTok |\n| **Cache Creation** | One-time cost to write context to the cache. | $3.75 / MTok |\n| **Cache Read** | Per-turn cost to retrieve cached context. Compounds over turns. | $0.30 / MTok |\n\n> **Key insight**: `input_tokens` is NOT the total input. It's the non-cached delta (typically 1-2 tokens). The bulk of your context is in `cache_read_input_tokens`.\n\n### How Cache Read Compounds\n\nEach turn reads the entire cached context (system prompt + all previous conversation). As the conversation grows, so does cache read:\n\n| Session Length | Avg Cache Read/Turn | Total Cache Read | Cache Read Cost |\n|----------------|---------------------|------------------|-----------------|\n| 1 turn | 12k | 12k | ~$0.004 |\n| 10 turns | 34k | 340k | ~$0.10 |\n| 28 turns | 33k | 929k | ~$0.28 |\n| 100 turns | 35k | 3.5M | ~$1.05 |\n\nThe 929k number sounds large, but at $0.30/MTok it costs less than a quarter. **Output tokens are 5x more expensive** than cache read.\n\n### How Tool Calls Affect Cost\n\nTool results (success or failure) are added to conversation history. Large tool outputs compound:\n\n- Reading a 100k-token file in Turn 5 adds 100k tokens to history\n- Turns 6-28 each read that extra 100k in cache\n- Cost: 23 turns × 100k × $0.30/MTok = ~$0.69 extra\n\nThis is why targeted searches (`grep \"ERROR\" app.log`) are cheaper than reading entire files (`cat app.log`).\n\n## Tips for Efficient Sessions\n\n| Strategy | Impact |\n|----------|--------|\n| **Start in the project directory** | `cd ~/projects/my-app && claude` instead of `cd ~ && claude \"fix X in my-app\"`. Broader scope = more file discovery = more cache bloat. |\n| **Use exact file paths** | \"Edit `src/components/Button.tsx`\" instead of \"edit the button component\". Reduces discovery turns. |\n| **Batch related tasks** | \"Fix X, Y, Z\" in one session vs three separate sessions. Fewer turns = less cumulative cache read. |\n| **Keep sessions under 15 turns** | After 10-15 turns, restart to reset cache accumulation. A 10-turn session costs ~$0.18 vs ~$0.63 for 28 turns. |\n| **Watch tool output sizes** | Use `head`, `tail`, `grep` to limit output. A 100k-token file read adds ~$0.69 in cache bloat over 28 turns. |\n| **Use `.claudeignore`** | Exclude `node_modules/`, `dist/`, `*.log` from discovery to prevent unrelated files from entering context. |\n\n## Data Sources\n\n| Source | Location | Contents |\n|--------|----------|----------|\n| SQLite | `~/.claude/usage.db` | Sessions, turns, token counts |\n| JSONL | `~/.claude/projects//.jsonl` | Full message content, tool calls, file paths |\n\n## Troubleshooting\n\n### `usage.db` not found / no sessions showing\n\nClaude Timeline reads `~/.claude/usage.db`, which is created and managed by Claude Code itself.\nIf the file is missing, it means Claude Code hasn't generated it yet — this happens with older\nversions of Claude Code or on a fresh install before the first session completes.\n\n**What to do:**\n- Run at least one Claude Code session and let it finish.\n- Upgrade Claude Code to the latest version (`npm i -g @anthropic-ai/claude-code`).\n- If the file still doesn't exist, check the path: `ls -la ~/.claude/usage.db`.\n\nClaude Timeline will still show sessions found in `~/.claude/projects/` (JSONL files),\nso most data will be available even without `usage.db`.\n\n### Find your recent sessions\n\n```bash\nsqlite3 ~/.claude/usage.db \"SELECT session_id, project_name, total_cache_read, turn_count, last_timestamp FROM sessions WHERE last_timestamp > datetime('now', '-1 day') ORDER BY total_cache_read DESC LIMIT 5;\"\n```\n\n### Get full token breakdown for a session\n\n```bash\nsqlite3 ~/.claude/usage.db \"SELECT timestamp, cache_read_tokens, cache_creation_tokens, input_tokens, output_tokens, tool_name FROM turns WHERE session_id='YOUR_SESSION_ID' ORDER BY timestamp;\"\n```\n\n### Calculate session cost (Sonnet 4 rates)\n\n```bash\nsqlite3 ~/.claude/usage.db \"SELECT\n session_id,\n ROUND(total_cache_read * 0.30 / 1000000, 4) AS cache_read_USD,\n ROUND(total_output_tokens * 15.00 / 1000000, 4) AS output_USD,\n ROUND(total_cache_creation * 3.75 / 1000000, 4) AS creation_USD,\n ROUND(total_input_tokens * 3.00 / 1000000, 4) AS input_USD,\n ROUND((total_cache_read * 0.30 + total_output_tokens * 15.00 + total_cache_creation * 3.75 + total_input_tokens * 3.00) / 1000000, 4) AS total_USD\nFROM sessions WHERE session_id='YOUR_SESSION_ID';\"\n```\n\n### Check which files were read in a session\n\n```bash\ncat ~/.claude/projects/YOUR_PROJECT_DIR/YOUR_SESSION_ID.jsonl | jq -r 'select(.type == \"assistant\" and .message.content) | .message.content[]? | select(.type == \"tool_use\" and .name == \"Read\") | .input.filePath' 2>/dev/null\n```\n\n## Development\n\n```bash\ngit clone https://github.com/abnersajr/claude-timeline.git\ncd claude-timeline\npnpm install\npnpm dev\n```\n\n## License\n\n[MIT](LICENSE)\n","readmeFilename":"README.md"}