claude-simple-status

A simple, no-frills statusline for Claude Code that shows what matters: project name, git branch, model, context usage, quota, and API costs.

Features

• Zero dependencies — single Node.js script, no runtime dependencies
• Cross-platform — works on macOS, Linux, and Windows
• Non-blocking — returns cached data instantly, refreshes quota in the background
• Color-coded — green/orange/red percentages at a glance
• Context velocity — estimates remaining turns until context compaction (42% →~8t), with directional arrows showing if burn rate is accelerating (↑), steady (→), or decelerating (↓)
• Quota pressure — reset time changes color based on projected burn rate: green (safe), orange (cutting it close), red (will hit the limit before reset). The 7d percentage color is also overridden when the projection says danger
• Project name — bold uppercase project directory name so you never mix up sessions
• Git-aware — shows the current branch name in repos (cached 30s to reduce overhead)
• API cost tracking — pay-as-you-go API users see cumulative session cost instead of quota
• Stale-aware — shows -- for quota values when cache is outdated, real values appear after first refresh
• Timezone-smart — quota reset time converted to your local timezone

If the quota API is unreachable, a red ERR indicator appears at the end and clears automatically once the connection recovers.

Installation

npm install -g claude-simple-status

That's it — Claude Code is configured automatically. The statusline appears immediately.

To uninstall:

claude-simple-status --uninstall
npm uninstall -g claude-simple-status

curl -fsSL https://raw.githubusercontent.com/edimuj/claude-simple-status/main/install.sh | bash

irm https://raw.githubusercontent.com/edimuj/claude-simple-status/main/install.ps1 | iex

1. Copy the script

mkdir -p ~/.claude/statusline
curl -o ~/.claude/statusline/statusline.mjs \
  https://raw.githubusercontent.com/edimuj/claude-simple-status/main/statusline.mjs

2. Configure Claude Code

Add to your ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "node ~/.claude/statusline/statusline.mjs"
  }
}

To uninstall, remove ~/.claude/statusline/ and the "statusLine" block from settings.json.

Requirements

• Claude Code CLI
• Node.js (v18+)

How it works

1. Receives model/context/cost info from Claude Code via stdin (JSON)
2. Reads cached quota data and returns immediately (never blocks the UI)
3. If the cache is stale (>2 minutes), refreshes from Anthropic's OAuth API in the background
4. Tracks context usage and quota utilization over time to compute velocity/burn rate predictions
5. Outputs a formatted statusline with ANSI colors

Subscription users see quota percentages and reset times. API (pay-as-you-go) users see cumulative session cost (e.g. $4.72) — calculated by Claude Code from actual token usage, no external pricing lookups needed.

Quota data is cached to the system temp directory and refreshed every 2 minutes. Context and quota history are tracked across invocations to power the predictive features — both reset automatically when a new window or compaction is detected.

Troubleshooting

Indicators:

• -- for quota values means the cache is stale (>5 minutes old) — values appear after the first background refresh
• ? means quota data has never been fetched yet
• ERR (red) means the last quota fetch failed — clears automatically on recovery

If the statusline shows ERR, check the error log:

# macOS/Linux
cat /tmp/claude-statusline.log

# Windows (PowerShell)
Get-Content $env:TEMP\claude-statusline.log

To force a fresh quota fetch, clear the cache:

# macOS/Linux
rm /tmp/claude-statusline-quota.json

# Windows (PowerShell)
Remove-Item $env:TEMP\claude-statusline-quota.json

Related projects

claude-rig

Run multiple isolated Claude Code configurations simultaneously — each with its own plugins, skills, MCP servers, and settings. When a session is launched through claude-rig, the active profile name appears in the statusline in bold magenta:

MY-PROJECT [main] | minimal | Opus 4.6 | 12% | 14:30 | 5h:34% | 7d:12%

No configuration needed — claude-simple-status detects claude-rig automatically. Users not using claude-rig are unaffected.

Contributing

Contributions are welcome! This project follows a few principles:

• Single file, zero dependencies
• Cross-platform (macOS, Linux, Windows)
• Never block the UI

Open an issue or submit a pull request.

License

MIT