Claude Code Token Star

Live star overlay that visualizes Claude Code context usage — six stellar stages from red dwarf to quasar.

Claude Code sends its status-line data to a small local bridge. The bridge updates the star without making extra API calls or using extra tokens. The installation is scoped to the project where you run it.

Quasar in motion

Star stages

| | | | --- | --- | | Red Dwarf · 0–15% | Main Sequence · 15–35% | | Blue Giant · 35–55% | Hypergiant · 55–75% | | Neutron Star · 75–90% | Quasar · 90–100% |

Platform support

| Platform | Display | Status | | --- | --- | --- | | Windows | Transparent overlay for JetBrains IDEs, VS Code, Cursor, Visual Studio, and Eclipse; optional Windows Terminal shader | Fully supported | | macOS | Ghostty shader | Ghostty only | | Linux | Ghostty shader | Ghostty only |

macOS and Linux do not currently have native overlays for Terminal, iTerm2, VS Code, or other terminals and editors.

Quick install

You need Claude Code and Node.js 18+. Run this from your project root:

npx --yes claude-token-star@latest

@latest makes npx fetch the newest release instead of reusing a cached copy. To try unreleased changes from main, use npx --yes github:0Alduin0/Claude-Code-Token-Star instead; that also needs Git.

On Windows, the installer uses ExecutionPolicy Bypass only for the child PowerShell process because the local scripts are not code-signed. It does not change your user or system execution policy. The source is copied into .claude-token-star/ so it remains inspectable. Each project gets its own .claude/settings.local.json, overlay process, and hashed runtime directory.

Windows does not require Python. Linux and macOS require Ghostty 1.3+ and Python 3.10+. There, Claude Code settings are also written to the project's .claude/settings.local.json. Ghostty has a single shader setting, so the most recently installed project owns it; uninstalling another project leaves it in place.

Update by running the same command again. Remove it with:

npx --yes claude-token-star uninstall

Windows

git clone https://github.com/0Alduin0/Claude-Code-Token-Star.git .claude-token-star
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\.claude-token-star\src\windows\install.ps1

Linux and macOS

git clone https://github.com/0Alduin0/Claude-Code-Token-Star.git .claude-token-star
sh ./.claude-token-star/src/ghostty/install.sh

Use it

• Drag the star to move it near an IDE corner or edge.
• The compact bar and details card stay centered directly below the star and keep a stage-aware safety gap, so controls never cover the stellar visual.
• Custom dragging lets the star center reach IDE corners without the invisible overlay window forcing it back toward the middle.
• MASS 656K / 1.00M shows used tokens beside the model's context capacity.
• 5H 61% | 2h 23m shows five-hour usage and the time until reset.
• The compact bar shows the active Claude model and a readable effort label.
• Click the arrow for model, effort, input, cache-read, remaining-context, five-hour, reset, and seven-day details.
• Choose Auto to evolve through every stellar stage, or pin one stage such as Quasar so its appearance stays fixed.
• Enable Grow with token usage when the selected star should scale from 65% to 100% as the context fills.
• Choose 1x, 2x, or 3x to resize the star.
• Enable Lock position to prevent accidental dragging.
• If several Claude tabs are open in the project, the overlay shows the active session with the highest context-token usage. The details card also shows the number of active sessions.
• The Windows overlay hides when you switch away from its installed project.

Test every stage without spending tokens:

.\.claude-token-star\token-test.ps1 sweep

On Linux or macOS:

./.claude-token-star/token-test.sh sweep

Turn the Windows overlay off or on

The setting persists across Claude sessions. Run either command from the project where Token Star is installed:

npx --yes claude-token-star off
npx --yes claude-token-star on

off closes the current overlay process and prevents status refreshes from starting it again. on re-enables it; the star appears on the next Claude status refresh.

Browser preview

On Windows:

.\.claude-token-star\preview.ps1

This opens http://127.0.0.1:4173/preview.html. Press Enter in the terminal to stop it. The preview mirrors the current Windows overlay geometry and animation for all six stellar stages using animation assets rendered directly by WPF.

Troubleshooting

.\.claude-token-star\token-test.ps1 doctor

On Linux or macOS:

python3 ./.claude-token-star/token-mass.py --doctor

The Windows overlay appears only while the installed project is open in a supported IDE. Seeing -- before Claude Code sends its first status update is normal. An enabled overlay process is restarted automatically by the next status refresh if it exits unexpectedly.

For installation problems, include your OS, terminal/editor, Claude Code version, and doctor output in a GitHub issue. Do not include tokens, settings, or conversation contents.

Resource use

The bridge reads data Claude Code already sends to the status line. It makes no extra API requests and consumes no additional model tokens. The overlay uses a single low-frequency WPF animation timer; hidden overlays refresh roughly once every 1.5 seconds. Only the active stellar stage stays in the render tree, and the transparent window shrinks vertically to the visible content.

On the 16-logical-core Windows test machine, two consecutive 10-second warmed-up Quasar runs averaged 73.8 MB resident RAM and 0.61% total CPU. WPF initialization briefly reached 327.9 MB resident RAM; private committed memory averaged 302.7 MB. The larger Hypergiant stage measured 95.0 MB and 0.65% total CPU. The warmed-up resident figure is the useful physical-RAM comparison; results vary by Windows, DPI, GPU driver, and selected stage.

Repository layout

• src/windows/ contains the Windows installer, bridge, WPF overlay, and HLSL.
• src/ghostty/ contains the macOS/Linux bridge, scripts, and GLSL.
• tools/ contains preview and visual-test utilities.
• scripts/windows/ contains optional .cmd wrappers.
• tests/ and assets/ contain automated checks and documentation media.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md for setup, tests, and visual-change guidelines.

License

MIT. Visual references: NASA Star Lifecycle and NASA Active Galactic Nuclei.