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.

[Sonnet 4.5] claude-skills:main *↑2 | +145/-23
[5f2ce67] Remove auth-js skill
[■■■■■■■■■■■■■□□□□□□□□□□□□□□□□□] 43% | 113k free | 0h12m | $0.87
5h:64% ~23m | 7d:57% ~1d23h | sonnet:9% ~3d23h

Features

• Real-time context tracking — brick visualization of context window usage
• Rate limit tracking — 5-hour and 7-day utilization with reset timers (Max/Pro subscribers)
• Color gradient — 256-color green-to-red scale based on utilization percentage
• Official percentage fields (Claude Code 2.1.6+) with fallback calculation (2.0.70+)
• Git integration — repo, branch, commit hash, message, dirty/ahead/behind indicators
• Session metrics — model name, lines changed, duration, cost (hidden for Max subscribers)
• Environment config — CONTEXTBRICKS_SHOW_DIR, CONTEXTBRICKS_BRICKS, CONTEXTBRICKS_SHOW_LIMITS

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

Display Layout

Line 1 — Model + Git + Changes

[Sonnet 4.5] claude-skills:main *↑2 | +145/-23

Line 2 — Commit Details

[5f2ce67] Remove auth-js skill

Line 3 — Context Bricks

[■■■■■■■■■■■■■□□□□□□□□□□□□□□□□□] 43% | 113k free | 0h12m | $0.87

Line 4 — Rate Limits (Max/Pro subscribers)

5h:64% ~23m | 7d:57% ~1d23h | sonnet:9% ~3d23h

| Symbol | Meaning | |--------|---------| | ■ (cyan) | Used context | | □ (dim) | Free space | | * | Uncommitted changes | | ↑3 | Ahead of remote by 3 | | ↓2 | Behind remote by 2 | | 5h:X% | 5-hour rolling limit utilization | | 7d:X% | 7-day overall limit utilization | | sonnet:X% | 7-day Sonnet sub-limit (if applicable) | | opus:X% | 7-day Opus sub-limit (if applicable) | | ~22m / ~1d23h | Time until limit resets (exact by default) |

Configuration

| Environment Variable | Default | Description | |---|---|---| | CONTEXTBRICKS_SHOW_DIR | 1 | Show current subdirectory (0 to hide) | | CONTEXTBRICKS_BRICKS | 30 | Number of bricks in the visualization | | CONTEXTBRICKS_SHOW_LIMITS | 1 | Show rate limit utilization (0 to hide) | | CONTEXTBRICKS_RESET_EXACT | 1 | Exact reset times ~1d23h (0 for approximate ~1d) |

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

| Issue | Solution | |-------|----------| | Line 4 not showing | Verify ~/.claude/.credentials.json exists with claudeAiOauth.accessToken | | Stale data | Delete ~/.claude/.usage-cache.json to force refresh | | Want to hide Line 4 | Set CONTEXTBRICKS_SHOW_LIMITS=0 |

Testing

contextbricks test

Requirements

• Node.js >= 14
• git (optional, for git info display)

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

Comparison with Original

| | contextbricks (bash) | contextbricks-universal (Node.js) | |---|---|---| | Platform | Linux/macOS only | Windows + Linux + macOS | | Dependencies | bash, jq, git, bc, sed, cut | Node.js only (git optional) | | JSON parsing | External jq | Native JSON.parse() | | Rate limits | No | Yes (Line 4) | | Install | Shell scripts | npm i -g contextbricks-universal |

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)