claude-code-session-tracker
v0.14.0
Published
See every Claude Code session on your machine in a local dashboard.
Maintainers
Readme
Claude Code Session Tracker
See every Claude Code session on your machine in a local dashboard — grouped by project, with live status, titles, and token usage.
npx claude-code-session-tracker@latestThen open the printed http://127.0.0.1:3099.
Run Claude Code in four terminals and you lose track of which one is waiting on
you, which is still working, and what you asked the one you abandoned yesterday.
Claude Code already writes all of that to ~/.claude. This reads it — nothing
else — and puts it on one page.
What you get
- ✅ Your limits — the five-hour and weekly windows: how full each is (the same
percentage
/usageshows), when it resets, and when it runs out at your current pace. More - ✅ A notification when either window is on course to run out before it resets. Off until you turn it on. More
- ✅ Auto continue: sessions that stopped on a limit pick up by themselves once it resets. Off until you turn it on; needs the plugin. More
- ✅ Active sessions, checked twice against the OS so a stale file or a recycled PID never shows up as running.
- ✅ Recent sessions across every project, with Claude's own title, the prompts, the model and the branch — filtered by date, sorted by recency or token spend. More
- ✅ A detail panel per session: message and tool-call counts, tokens, elapsed and
working time, subagent count, and a copyable
claude --resume <id>. - ✅ What the static context went on — which
CLAUDE.md, the skill listing, the agent listing, the MCP instructions — so the standing cost of every turn is itemised. - ✅ A history page: where the tokens went by day, hour of day, calendar year,
project and model, with PDF and
.xlsxexport and a year image to share. More - ✅ Start at login on macOS and Windows — below.
- ✅ A menu bar switch and a widget on macOS — below.
- ✅ A Claude Code plugin:
/session-tracker:statusand/session-tracker:open— below. - ✅
--jsonfor scripting, and an HTTP API. - ✅ No dependencies, no install scripts, no writes to your Claude directory.
Click a row and the panel opens beside it:
The history page:
Install
Node 20 or newer, and Claude Code having run at least once. macOS, Linux and Windows are all covered by CI.
npx claude-code-session-tracker@latest # npm
pnpm dlx claude-code-session-tracker@latest # pnpm
yarn dlx claude-code-session-tracker@latest # yarn
bunx claude-code-session-tracker@latest # bun@latest matters: without it, a runner may start the copy it cached last time.
Or put it on your PATH — Homebrew brings its own Node:
brew install meyusufdemirci/tap/claude-code-session-tracker
npm i -g claude-code-session-tracker # or pnpm add -g / bun add -gUpdating
The page and the menu bar app say when a newer version is out. Update does the
rest: it upgrades with whatever installed the tracker, checks the new version
starts, restarts as it on the same port, and updates the menu bar app too. Where
it cannot (a global npm folder that needs sudo, a source checkout), the notice
shows the command instead:
npx claude-code-session-tracker@latest # npx and the other runners
brew upgrade meyusufdemirci/tap/claude-code-session-tracker # Homebrew
npm i -g claude-code-session-tracker@latest # npm, or pnpm add -g / bun add -gBy hand, restart the tracker afterwards, and run menubar install again if you use
the menu bar app.
Start it at login
claude-code-session-tracker autostart onmacOS and Windows, no admin rights; autostart off undoes it. It needs an
installed copy (Homebrew or npm i -g), not npx. Details
Menu bar and widget (macOS)
A small native app whose switch turns the tracker on and off, with both limits and the running sessions under it, plus a desktop widget showing the limits as rings.
npx claude-code-session-tracker@latest menubar install --with-tracker--with-tracker installs the tracker itself first; leave it off when it is already
installed. Needs macOS 14 or later. Details
Inside Claude Code
/plugin marketplace add meyusufdemirci/claude-code-session-tracker
/plugin install session-tracker@claude-code-session-tracker| Command | What it does |
| --- | --- |
| /session-tracker:status | Prints both limits and when they reset, what today has billed, and the sessions that are running |
| /session-tracker:open | Opens the page in your browser, starting the tracker first if it is not running |
The plugin also carries the hook auto continue waits with.
The same two work in any terminal as claude-code-session-tracker status and
open. Details
Options
| Command | Description |
| --- | --- |
| status | Print both limits, what today has billed and the running sessions |
| open | Open the page, starting the tracker in the background first if needed |
| autostart on\|off\|status | Start at login (macOS and Windows) |
| menubar install\|uninstall\|status | The macOS menu bar app and widget; install --with-tracker installs the tracker too |
| Flag | Description |
| --- | --- |
| -p, --port <number> | Port to listen on, stepping forward up to 20 times if taken (default 3099) |
| --host <address> | Address to bind (default 127.0.0.1 — see Privacy) |
| --no-open | Do not open a browser |
| --json | Print the session list as JSON and exit |
| -n, --limit <number> | How many sessions to list (default 50; running ones are always shown) |
| --claude-dir <path> | Override the Claude data directory (or set CLAUDE_CONFIG_DIR) |
| --offline | Never ask Anthropic's server for the usage limits, or npm for a newer version |
| -h, --help | Show usage |
| -v, --version | Show the version |
--json, the HTTP API and the Node API are in Scripting and API.
Privacy
The tool reads what Claude Code already writes to ~/.claude, never writes
there, binds to loopback only, and rejects requests not addressed to a loopback
host. Its one outbound call is the usage endpoint Claude Code's own /usage reads,
at api.anthropic.com, with Claude Code's own token and at most every five
minutes. It also asks the npm registry for the newest version a few times a day,
so the page and the menu bar can say when an update is out. --offline turns both
off. No telemetry.
What it reads, and the rest
More
- The limits — how the windows, the forecast and the notifications work
- Auto continue — sessions that pick up again after a limit resets
- The history page — charts, export and sharing
- The dashboard — keys, range and sort
- Scripting and API
- Troubleshooting
- How it stays fast
- Development — building, testing and releasing
Contributing
Issues and pull requests are welcome. pnpm typecheck and a passing pnpm smoke
against a fresh npm pack are what CI will ask of a change. A bug report that
includes your GET /api/health output and the notes from an affected session is
worth far more than a description.
License
MIT © Yusuf Demirci
