Claude Code Statusline

Claude Code Statusline (ccs): Real-time usage stats in Claude Code's status line — see your session limit, weekly limit, remaining time, context usage, and cost at a glance.

[Opus 4.6] 📁 my-project | ✹main | $0.3595
▓▓▓▓░░░░░░░░░░░░░░░░ ctx 20% | sess: ▓▓▓▓▓▓▓▓░░ 75% 3h19m | week: ▓▓▓▓▓▓▓░░░░░░░░░░░░░ 34% 3d20h

Progress bars are color-coded: green (<70%), yellow (70-89%), red (>=90%).

Quick Start

npx ccs-stats install

That's it. Restart Claude Code and the status line appears.

Requirements

Requirement	Details
OS	macOS, Linux (verified), Windows (experimental)
Claude Code	Logged in via OAuth — Pro or Max plan
Node.js	>= 18

Zero external dependencies — uses only Node.js built-ins.

Installation

Option 1: npx (no global install)

npx ccs-stats install

Option 2: Global install

npm install -g ccs-stats
ccs install

What happens during install

1. Checks Node.js version (>= 18 required)
2. Copies statusline.js to ~/.claude/statusline.js
3. Adds statusLine config to ~/.claude/settings.json (creates a backup first)
4. Cleans up old statusline.sh if present (from previous versions)

Existing settings are preserved — only the statusLine key is added. Running install multiple times is safe (idempotent).

Updating

Re-run install to update to the latest version:

npx ccs-stats install

This overwrites ~/.claude/statusline.js with the latest script while leaving your other settings untouched.

Usage

ccs install      # Install script & configure settings
ccs uninstall    # Remove script & clean up settings
ccs status       # Check if statusline is active

ccs and ccs-stats are interchangeable.

What It Shows

Line 1 — Session info:

Segment	Description
[Opus 4.6]	Active model (cyan)
📁 my-project	Current workspace folder
✹main	Current git branch (green) — ✹ (purple) appears when there are uncommitted changes; hidden outside git repos
$0.3595	Current session cost (yellow)

Line 2 — Usage bars:

Segment	Description
▓▓▓▓░░░░ ctx 20%	Context window usage with color-coded progress bar
sess: 75% 3h19m	5-hour rolling window utilization + time until reset
week: 34% 3d20h	7-day rolling window utilization + time until reset

Progress bars are color-coded: green (<70%), yellow (70-89%), red (>=90%). If usage data is unavailable, line 2 shows only the context bar.

How It Works

Claude Code response
  → triggers statusline.js via stdin
    → parses model, cost, context from JSON input
    → reads OAuth token from platform credential store
    → fetches usage from api.anthropic.com/api/oauth/usage (cached 60s)
    → outputs formatted status line with progress bars

The script caches API responses at <tmpdir>/claude_usage_cache_<session_id>.json (5-minute TTL, isolated per session) to avoid hitting the API on every response.

Credential Access

OAuth token is read in priority order:

1. CLAUDE_CODE_OAUTH_TOKEN environment variable
2. ~/.claude/.credentials.json file — primary on Linux; present on macOS and Windows when available
3. macOS Keychain via security command — fallback when macOS removes the credentials file after login

Verified on macOS and Linux. Windows credential access is experimental.

API Details

• Endpoint: GET https://api.anthropic.com/api/oauth/usage
• Auth: OAuth token from platform credential store
• Required header: anthropic-beta: oauth-2025-04-20

Uninstalling

ccs uninstall

This removes ~/.claude/statusline.js and deletes the statusLine key from ~/.claude/settings.json (with backup). No other settings are modified.

Limitations

• OAuth login only — API key authentication does not have access to the usage endpoint.
• Beta header may change — anthropic-beta: oauth-2025-04-20 could be updated by Anthropic in the future. If the status line stops showing usage data, check for an updated version of this package.
• Windows support is experimental — credential access on Windows has not been verified. macOS and Linux are tested.

Troubleshooting

Problem	Solution
Usage data not showing	Make sure you're logged in via OAuth (claude command), not API key
Usage data not showing on Windows	Credential access is experimental on Windows; try setting the CLAUDE_CODE_OAUTH_TOKEN env var manually
Stale data	Delete /tmp/claude_usage_cache_*.json (macOS/Linux) or %TEMP%\claude_usage_cache_*.json (Windows)
Status line not appearing	Run ccs status to check, then restart Claude Code

Contributing

git clone https://github.com/yusufalikync/ccs.git
cd ccs
npm test              # Run smoke tests
node bin/cli.js install   # Test install locally

See CLAUDE.md for architecture details and coding conventions.

Author

Yusuf Ali Koyuncu — GitHub

License

MIT