Claude Code Token Counter

A status line plugin for Claude Code that displays real-time rate limit usage and context window stats directly in your terminal.

Preview

 5h ━━━━━━────── 58%  4h32m   7d ━━──────── 22%  6d14h   ctx ━━━─── 48% 125k

The status bar uses color-coded progress indicators:

What It Shows

Installation

One-liner

git clone https://github.com/M4xSec/claude-code-token-counter.git && cd claude-code-token-counter && chmod +x install.sh && ./install.sh

Step by step

git clone https://github.com/M4xSec/claude-code-token-counter.git
cd claude-code-token-counter
chmod +x install.sh
./install.sh

Restart Claude Code after installing.

Manual

mkdir -p ~/.claude
cp claude-counter-statusline.py ~/.claude/
cp statusline-combined.sh ~/.claude/
chmod +x ~/.claude/claude-counter-statusline.py
chmod +x ~/.claude/statusline-combined.sh

{
  "statusLine": {
    "type": "command",
    "command": "/home/YOUR_USER/.claude/statusline-combined.sh",
    "refreshInterval": 30
  }
}

Uninstall

chmod +x uninstall.sh
./uninstall.sh

Configuration

The refresh interval controls how often the status line updates (in seconds):

"refreshInterval": 15

Requirements

• Claude Code CLI v1.0.24+
• Python 3.6+
• Bash

How It Works

Claude Code                statusline-combined.sh         claude-counter-statusline.py
    │                              │                                │
    ├── pipes JSON status ──────►  │                                │
    │   (rate limits, context)     ├── forwards to python ────────► │
    │                              │                                ├── parses JSON
    │                              │                                ├── calculates bars
    │   ◄── ANSI-colored output ───┤  ◄── formatted string ────────┤
    │                              │                                │

Claude Code sends a JSON payload containing rate limit and context window data to the configured statusLine command on each refresh cycle. The shell wrapper passes it to the Python formatter, which outputs ANSI escape sequences for colored progress bars.

File Structure

.
├── claude-counter-statusline.py   # Core formatter — parses JSON, outputs colored bars
├── statusline-combined.sh         # Bash wrapper — handles encoding, invokes Python
├── install.sh                     # Automated installer
├── uninstall.sh                   # Automated uninstaller
├── instructions.txt               # Plain-text install guide
└── README.md

License

MIT