claude-context-bar

A live, multi-session context-window meter for Claude Code.

What it does

I built contextbar because I was getting sick of running /context over and over to keep tabs on my agents.

This started as a little afternoon for-fun project that I wasn't going to put on GitHub, but it's actually really useful to watch your agents' context grow in real time. So I decided to throw it up on GitHub for shiggles.

contextbar watches every session file under ~/.claude/projects/ and shows a live TUI dashboard with one row per active Claude Code session: project name, colored usage bar, percentage, token counts, and time since the session was last updated. It refreshes once per second, depends only on the Python standard library, and ships as a single file.

Install

pip install claude-context-bar
contextbar

That's it.

Native Windows (adds windows-curses):

pip install "claude-context-bar[windows]"

From source / GitHub:

pip install git+https://github.com/ethanarnold/claude-context-bar.git

No-install one-liner:

curl -O https://raw.githubusercontent.com/ethanarnold/claude-context-bar/main/contextbar.py
python3 contextbar.py

Usage

contextbar [--ascii] [--limit N] [--no-auto-limit]
           [--refresh SEC] [--once] [--version]

Combine --once --ascii for clean piping:

contextbar --once --ascii | head -3

How it works

Claude Code stores each session as a JSON-Lines file under ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl. contextbar walks those files and, for each one, scans entries of the form:

{"type": "assistant", "message": {"model": "claude-...", "usage": { ... }}}

The token count for a session is the sum of the four token fields in the most recent usage object:

• input_tokens
• cache_creation_input_tokens
• cache_read_input_tokens
• output_tokens

The model name is read from message.model on the same entries and is used to pick the right context window via the regex table in MODEL_LIMITS.

Color thresholds

Caveats

• The Claude Code session file format is undocumented and unofficial. If it changes, the bar may render 0% or display a yellow schema? warning on affected rows. Open an issue if you see this.
• Model auto-detection is regex-based and only knows about opus, sonnet, haiku, and the 1M-context Sonnet beta. Use --limit for anything else.
• The TUI uses Unicode block glyphs by default. On terminals that can't render them, pass --ascii.
• Reads files only — contextbar never writes to or modifies your Claude Code sessions.

Requirements

• Python 3.9+
• A curses-capable terminal:
  • macOS / Linux / WSL: built in
  • Native Windows: pip install windows-curses (or use the [windows] install extra above)
• Claude Code installed and run at least once, so that ~/.claude/projects/ exists

Development

git clone https://github.com/ethanarnold/claude-context-bar.git
cd claude-context-bar
python3 contextbar.py

Single-file project. No build step, no dependencies.

License

MIT © 2026 Ethan

Disclaimer

Not affiliated with Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic. This project depends on an undocumented file format and may break without warning when Claude Code is updated.