Claude: Context Window

Real-time context window usage bar for Claude Code.

Shows a two-line status bar in Claude Code with project info on the first line and a color-coded context window progress bar on the second.

[user] [project]:[repo-name]/[main] [+3 ~2]
[Opus 4.6] [100K/1M tokens] █░░░░░░░░░ [10%]     ← green

The first line shows the OS username, project directory, a clickable link to the git repo (Cmd/Ctrl+click), branch name, and staged/modified file counts. The second line shows the model (with effort level if available), token usage, and a color-coded progress bar.

Installation

There are three ways to install, depending on your setup. Restart Claude Code after installing.

Option 1: npx (standalone)

The quickest way if you just want the status bar. No plugin system needed.

npx claude-context-window@latest

Copies the script to ~/.claude/statusline.js and configures ~/.claude/settings.json.

To remove:

npx claude-context-window@latest uninstall

Option 2: Claude Code plugin (from this repo)

Register this repository as a plugin marketplace, then install the plugin:

claude plugin marketplace add https://github.com/matuscvengros/claude-context-window
claude plugin install claude-context-window

Once installed, activate the status line:

/claude-context-window:install

This points the status line directly at the plugin's cached copy of the script — nothing is copied to ~/.claude/. To remove:

/claude-context-window:uninstall

Option 3: Shell script (Docker / CI)

For headless environments where there is no interactive Claude Code session. Requires node and jq.

./install.sh
./install.sh --force   # overwrite existing statusLine from another tool
./uninstall.sh

Copies the script to ~/.claude/statusline.js and configures ~/.claude/settings.json. The script resolves its own location, so it works from any working directory — just call it by its path.

How it works

Claude Code's status line is a customizable bar at the bottom of the terminal. It runs a shell command after each assistant message, piping JSON session data to stdin. The command's stdout becomes the status bar content.

This tool provides that command: a Node.js script that reads the JSON and outputs two lines — project/git info and a color-coded context window progress bar.

Colors indicate context usage:

| Color | Usage | Meaning | |--------|---------|---------------| | Green | 0–50% | Plenty of room | | Yellow | 50–75% | Getting there | | Orange | 75–90% | Caution | | Red | 90–100% | Nearly full |

The script has zero dependencies, runs in under 100ms, and handles edge cases gracefully (null fields before the first API call, missing data, auto-compaction resets).

Ownership detection

All install methods embed a # claude-context-window marker comment in the settings.json command string. This allows safe uninstall — the tool only removes its own statusLine entry and will not touch configurations from other tools.

Requirements

• Node.js >= 18
• Claude Code
• jq (only for install.sh / uninstall.sh)

License

MIT