claudeline

README

claudeline

Real-time statusline for Claude Code showing live quota usage from the Anthropic API.

⚠️ claudeline uses an undocumented Anthropic API. If you encounter an unexpected error or status message, please open an issue with the error text — it helps us handle more edge cases!

Known limitations

The Anthropic usage API (/api/oauth/usage) has a very low rate limit — roughly 5 requests per Valve Time window before it starts returning HTTP 429. claudeline caches successful usage API responses for 10 minutes by default to stay within this budget. Error responses are handled separately: HTTP 429 respects the server's Retry-After header (plus a 5-second buffer), and HTTP 401 is cached by token hash until the token changes (e.g., after claude login). Other data (model, cost, context) comes from Claude Code stdin and is always fresh. You can tune usage_ttl in the config, but lower values will burn through the rate limit faster.

Example output

🤖 Claude | 💰 $1.37 | 🟢 7d: 45% (4d 2h) | 🟢 5h: 12% (4h 23m)

🤖 Claude | 💰 $0.00 | ⚠️ degraded | 🧠 67% | 🔄 2 | 🟠 7d: 74% (1d 17h) | 🔴 5h: 91% (27m) | 💳 $12/$100

Segments

Segment	Description
🤖 Model	Active model name
💰 Cost	Cumulative session cost in USD
⚠️/🔶/🔴 Status	Anthropic platform status: ⚠️ degraded, 🔶 major outage, 🔴 critical (hidden when all clear)
🧠 Context	Context window usage percentage (color-coded)
🔄 Compactions	Number of context compactions in current session
🟢/🟡/🟠/🔴 7d	7-day rolling quota utilization with time until reset
🟢/🟡/🟠/🔴 5h	5-hour rolling quota utilization with time until reset
💳 Credits	Monthly extra credit usage (only shown when active)

Quota indicators compare your usage rate against elapsed time to warn about hitting limits:

• 🟢 usage pace is sustainable
• 🟡 usage is slightly ahead of schedule
• 🟠 usage is significantly ahead of schedule
• 🔴 on track to hit the limit before reset

Requirements

• macOS only (uses macOS Keychain for OAuth token storage)
• Claude Code with OAuth login (claude login)

Installation

Homebrew

brew install lexfrei/tap/claudeline

From source

go install github.com/lexfrei/claudeline/cmd/claudeline@latest

Usage

Add the statusLine block to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "claudeline",
    "padding": 0
  }
}

Claude Code pipes session data as JSON to stdin. claudeline reads it and outputs a formatted statusline string.

Restart Claude Code after changing settings.

Configuration

Optional config file at ~/.claudelinerc.toml:

[segments]
model = true
cost = true
status = true
context = true
compactions = true
quota = true
credits = true

[cache]
usage_ttl = "10m"
status_ttl = "15s"

Set any segment to false to hide it. Cache TTLs control how often API data is refreshed.

CLI flags

Flags override config file settings:

claudeline --no-cost --no-status
claudeline --config /path/to/config.toml

Available flags: --no-model, --no-cost, --no-status, --no-context, --no-compactions, --no-quota, --no-credits.

License

BSD-3-Clause