ContextBricks Universal

Cross-platform statusline for Claude Code CLI with real-time context brick visualization.

Works on Windows, Linux, and macOS — pure Node.js, no bash or jq required.

[Opus 4.7 (1m)] claude-skills:main *↑2 | +145/-23 @alice
[5f2ce67] Remove auth-js skill
[■■■■■■■■■■■■■□□□□□□□□□□□□□□□□□] 43% | 113k free | 0h12m | $0.87 | extra:$0.00/$20.00
session:27%/25% +0.4/m ~3h43m | week:77%/35% +1.3/hr ~4d12h | sonnet:22%/36% | design:0%/35% | TTL:1h 99.9%

Features

• Real-time context tracking — brick visualization of context window usage
• Unified Line 4 quotas — session (5h) + weekly (7d) + sonnet/opus sub-limits + Claude Design, all on one line
• Pacing target (/NN%) — shows expected % for elapsed-time-in-window (green = under pace, red = ahead of pace)
• OAuth-authoritative quotas — session/week/sonnet/opus/design always from Anthropic OAuth API. Optional extras (TTL/hit/PEAK/OVERAGE) from claude-code-cache-fix when fresh (<30 min)
• Extra usage on Line 3 — monthly overage billing extra:$N/$M next to session cost
• Burn rates — +0.4/m (5h) / +1.3/hr (7d) from OAuth data
• TTL tier indicator — TTL:1h 99.9% (warm cache) or red TTL:5m (cold tier)
• 10-step graceful degradation — short labels (s/w/son/des) then drops markers → TTL → design → pacing → burn → reset → sub-limits
• Color gradient — 256-color green-to-red scale based on utilization percentage
• Git integration — repo, branch, commit hash, message, dirty/ahead/behind indicators
• OAuth account identifier — auto-fetched @username on Line 1, invalidates cache on relogin (via .credentials.json mtime)
• Compact model label — (1M context) shortened to (1m)
• Environment config — CONTEXTBRICKS_SHOW_DIR, CONTEXTBRICKS_BRICKS, CONTEXTBRICKS_SHOW_LIMITS, CONTEXTBRICKS_SHOW_CACHE_FIX, CONTEXTBRICKS_USER, CONTEXTBRICKS_LABELS

Installation

Quick Install (Recommended)

npm install -g contextbricks-universal

The postinstall script runs contextbricks install automatically.

One-liner via npx

npx contextbricks-universal

From GitHub

npm install -g github:thebtf/contextbricks-universal

From Source

git clone https://github.com/thebtf/contextbricks-universal.git
cd contextbricks-universal
node bin/cli.js install

Node.js is the only requirement (already present if you use Claude Code).

What the Installer Does

1. Copies statusline.js to ~/.claude/statusline.js
2. Updates ~/.claude/settings.json with the statusLine command
3. Backs up existing configuration before any changes

Updating

npm update -g contextbricks-universal
contextbricks install

Topology auto-detection (v5.0+)

Statusline reads quota data from response headers of $ANTHROPIC_BASE_URL/v1/messages — the same endpoint Claude Code itself uses. Works with native OAuth, CLIProxyAPI, claude-code-cache-fix, or any combination.

For proxy users: if Line 4 shows [no compatible probe model in upstream], set CONTEXTBRICKS_QUOTA_PROBE_MODEL to a model your proxy dispatcher recognizes.

Display Layout

Line 1 — Model + Git + Changes + OAuth Account

[Opus 4.6 (1m)] claude-skills:main *↑2 | +145/-23 @alice

Model label auto-shortens (NM context) → (Nm) (e.g. (1M context) → (1m), (200K context) → (200k)).

The trailing @username is fetched from GET /api/oauth/profile (same OAuth token used for Line 4) and cached for 24 hours at ~/.claude/.profile-cache.json (mode 0600). Drops first on narrow terminals. Configure display via CONTEXTBRICKS_USER:

Line 2 — Commit Details

[5f2ce67] Remove auth-js skill

Line 3 — Context Bricks + Billing

[■■■■■■■■■■■■■□□□□□□□□□□□□□□□□□] 43% | 113k free | 0h12m | $0.87 | extra:$0/$20

extra:$N/$M appears when the OAuth profile has extra-usage (monthly overage billing) enabled. Monthly limit is shown in USD (converted from cents).

Line 4 — Unified Quota Line

Full render (wide terminal, cache-fix installed):

session:27%/25% +0.4/m ~3h43m | week:77%/35% +1.3/hr ~4d12h | sonnet:22%/36% ~4d10h | design:0%/35% | TTL:1h 99.9% | PEAK

Auto-merges:

• Anthropic OAuth /api/oauth/usage — single authoritative source for all quota values: session (5h), week (7d), sonnet/opus sub-limits, design (seven_day_omelette), and extra_usage.
• claude-code-cache-fix via ~/.claude/claude-meter.jsonl or quota-status.json — optional extras only: TTL tier, cache hit %, PEAK, OVERAGE. Used only when fresh (< 30 min old). Stale or absent → extras hidden, quota values unaffected.

Pacing target (/NN%): expected % for elapsed-time-in-window. Coloured relative to actual usage:

• Green → more than 5% under pace (headroom)
• Dim → within ±5% of pace
• Red → more than 5% over pace (burning fast)

10-step graceful degradation on narrow terminals:

1. Full labels (session, week, sonnet, design)
2. Short labels (s, w, son, des) — ~16 chars saved, no info loss
3. Drop PEAK / OVERAGE markers
4. Drop cache hit %
5. Drop TTL entirely
6. Drop design segment
7. Drop pacing /NN%
8. Drop burn rates
9. Drop reset times
10. Drop sub-limits → minimum: s:NN% | w:NN%

Configuration

How It Works

Context Tracking (Claude Code 2.1.6+)

Uses pre-calculated percentage fields:

{
  "context_window": {
    "context_window_size": 200000,
    "used_percentage": 43.5,
    "remaining_percentage": 56.5
  }
}

Fallback (Claude Code 2.0.70+)

Calculates from current_usage token counts when percentage fields are unavailable.

Settings

The installer configures ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "node ~/.claude/statusline.js",
    "padding": 0
  }
}

Rate Limit Tracking

Line 4 shows your current utilization of Claude's rate limits — useful for Max and Pro subscribers to avoid hitting caps.

How It Works

1. Reads your OAuth token from Claude Code credentials (~/.claude/.credentials.json, or macOS keychain)
2. Fetches usage data from api.anthropic.com/api/oauth/usage
3. Caches the response for 5 minutes (~/.claude/.usage-cache.json)
4. Displays utilization percentages with 256-color gradient:
   • Green (0-49%) — plenty of capacity
   • Yellow (50-79%) — approaching limit
   • Red (80-100%) — near or at limit

Requirements

• Active Claude Max or Pro subscription with OAuth credentials
• API-only users will not see Line 4 (gracefully skipped)

Privacy

• Your OAuth token is never logged or exposed in command arguments
• Token is passed to the HTTPS subprocess via environment variable
• Cache file (~/.claude/.usage-cache.json) is stored locally with restricted permissions (0600)

Troubleshooting

Testing

contextbricks test

Requirements

• Node.js >= 16.7 (installer uses fs.cpSync({recursive:true}))
• git (optional, for git info display)

No bash, jq, bc, sed, cut, or any other Unix tools required.

Comparison with Original

Uninstallation

contextbricks uninstall

Or manually:

1. Delete ~/.claude/statusline.js
2. Remove the statusLine section from ~/.claude/settings.json
3. Restart Claude Code

To remove the global package:

npm uninstall -g contextbricks-universal

Acknowledgements

This project is a cross-platform Node.js rewrite of ContextBricks created by Jeremy Dawes (jezweb.com.au). The original bash implementation provided the foundation for the statusline format, brick visualization, and git integration.

Also inspired by ccstatusline.

License

MIT — Copyright (c) 2025 Jeremy Dawes (Jezweb)