npm package: @robmorris/claude-usage-line
Description: Cross-platform Claude Code statusline showing session, 5h, and 7d rate limits
Author: Rob Morris
Latest version: 1.3.0

# claude-usage-line

[![npm](https://img.shields.io/npm/v/@robmorris/claude-usage-line)](https://npmjs.com/package/@robmorris/claude-usage-line)
[![license](https://img.shields.io/npm/l/@robmorris/claude-usage-line)](LICENSE)
[![node](https://img.shields.io/node/v/@robmorris/claude-usage-line)](package.json)

<img width="633" height="137" alt="claude-usage-line statusline screenshot" src="https://raw.githubusercontent.com/Rob-Morris/claude-usage-line/main/screenshot.png" />

Cross-platform Claude Code statusline — session context, 5-hour & 7-day rate limits, git branch, diff stats, cost, and duration. Zero runtime dependencies, no `jq` required.

> Forked from [canack/claude-usage-line](https://github.com/canack/claude-usage-line). Props to Engin Açıkgöz. Chosen from a crowded field for its zero runtime dependencies, strong security posture, and well-structured (clean, thorough, transparent) TypeScript

**Full output** (when Claude Code sends extended data):

```
~/dev/project → main • +123 -45 • $0.50 • ⏱ 12m
Opus 4.6 • Cx █████░░░ 62% • 5h ████░░░░ 48% ⟳3h28m • 7d █████░░░ 63% ⟳22h30m
```

**Minimal output** (backward compatible — only `context_window` provided):

```
Cx █████░░░ 62% • 5h ████░░░░ 48% ⟳3h28m • 7d █████░░░ 63% ⟳22h30m
```

## Prerequisites

- Node.js ≥ 18
- Claude Code with statusline support
- **Claude.ai Pro/Max subscription** — required for rate limit data (5h / 7d bars). Session bar works without it.

## Quick Start

```bash
npx @robmorris/claude-usage-line setup
```

With a theme:

```bash
npx @robmorris/claude-usage-line setup --theme dark-contrast
```

Or manually add to `~/.claude/settings.json`:

```json
{
  "statusLine": {
    "type": "command",
    "command": "npx @robmorris/claude-usage-line"
  }
}
```

With a theme and custom bar style:

```json
{
  "statusLine": {
    "type": "command",
    "command": "npx @robmorris/claude-usage-line --theme dark-contrast --style dot"
  }
}
```

Restart Claude Code and the statusline appears. Setup also copies an editable theme file to `~/.claude/statusline-theme.json`.

## How It Works

```
Claude Code                      claude-usage-line
    │                                   │
    │  stdin: {                         │
    │    "context_window": {...},        │
    │    "cwd": "/path",                │
    │    "model": {"display_name":".."},│
    │    "cost": {...},                 │
    │    "rate_limits": {...}           │
    │  }                                │
    ├──────────────────────────────────▶│
    │                                   ├─▶ Load theme (--theme + user file)
    │                                   ├─▶ Cache rate limits / read cached
    │                                   ├─▶ Detect git branch (if cwd given)
    │                                   │
    │  stdout: ANSI statusline          │
    │◀──────────────────────────────────┤
```

The tool accepts these fields via stdin JSON:

| Field | Required | Description |
|-------|----------|-------------|
| `context_window.used_percentage` | Yes | Session context usage % |
| `cwd` | No | Working directory → enables git branch detection |
| `model.display_name` | No | Model name shown on line 2 |
| `cost.total_lines_added` | No | Lines added (green) |
| `cost.total_lines_removed` | No | Lines removed (red) |
| `cost.total_cost_usd` | No | Session cost in USD |
| `cost.total_duration_ms` | No | Session duration |
| `rate_limits.five_hour.used_percentage` | No | 5-hour rolling window usage % |
| `rate_limits.five_hour.resets_at` | No | Reset time (Unix epoch seconds) |
| `rate_limits.seven_day.used_percentage` | No | 7-day rolling window usage % |
| `rate_limits.seven_day.resets_at` | No | Reset time (Unix epoch seconds) |

When `cwd` or `model` is present → 2-line output. Otherwise → single-line (backward compatible).

Rate limit data is provided by Claude Code via stdin. The `rate_limits` fields are only present for Claude.ai Pro/Max subscribers — bars show `0%` and `--` without a qualifying subscription. Rate limit data is cached locally so new sessions display the last known values until fresh data arrives. Cached values expire when their reset window passes.

## Bar Styles

| Style | Preview | Width |
|-------|---------|-------|
| `classic` (default) | `█████░░░` | 8 |
| `dot` | `●●●●●○○○` | 8 |
| `braille` | `⣿⣿⣿⣿⣿⣀⣀⣀` | 8 |
| `block` | `▰▰▰▰▰▰▱▱▱▱` | 10 |
| `ascii` | `#####-----` | 10 |
| `square` | `▪▪▪▪▪·····` | 10 |
| `pipe` | `┃┃┃┃┃╌╌╌` | 8 |

## Themes

Themes bundle colors, bar style, and hidden fields into a single file. Use `--theme` to select a shipped theme, or edit `~/.claude/statusline-theme.json` for full customization.

### Shipped themes

| Theme | Description |
|-------|-------------|
| `default` | Standard 16-color theme — works in any terminal |
| `dark-contrast` | Truecolor, dark — high-contrast palette with wider bars |
| `dark-muted` | Truecolor, dark — split-complementary with rose identity, cool grey structure, warm amber/coral status |
| `dark-vivid` | Truecolor, dark — triadic violet/orange/cyan, high saturation, bold and energetic |
| `dark-vintage` | Truecolor, dark — monochromatic warm, all colours between gold and burnt sienna |
| `dark-rainbow` | Truecolor, dark — every element its own hue, maximum colour variety at consistent brightness |
| `light-muted` | Truecolor, light — same muted palette darkened for white backgrounds |
| `light-vivid` | Truecolor, light — same triadic energy adapted for light backgrounds |
| `light-vintage` | Truecolor, light — warm monochromatic with neutral grey structure for contrast |
| `light-rainbow` | Truecolor, light — full spectrum, high saturation tuned for readability on white |

### Using themes

Select a shipped theme:

```json
{
  "statusLine": {
    "type": "command",
    "command": "npx @robmorris/claude-usage-line --theme dark-contrast"
  }
}
```

Or set it up automatically:

```bash
npx @robmorris/claude-usage-line setup --theme dark-contrast
```

### User theme file

`~/.claude/statusline-theme.json` is your personal override layer. It's created on first `setup` (a copy of your chosen theme) and always takes precedence over shipped themes.

Edit any key to customize:

```json
{
  "style": {
    "filled": "▰",
    "empty": "▱",
    "width": 10,
    "separator": "•",
    "resetIcon": "⟳"
  },
  "colors": {
    "context": "magenta",
    "five_hour": "cyan",
    "seven_day": "green",
    "cwd": "blue",
    "branch": "green",
    "model": "magenta",
    "cost": "yellow",
    "diff_add": "green",
    "diff_remove": "red",
    "duration": "blue",
    "dim": "bright_black",
    "warn": "yellow",
    "danger": "red"
  },
  "hide": ["cost", "duration"]
}
```

### Color formats

| Format | Example | Notes |
|--------|---------|-------|
| Named | `"red"`, `"bright_cyan"` | 16 standard terminal colors |
| 256-color | `"256:208"` | xterm-256 palette index |
| RGB | `"rgb:180,140,255"` | Truecolor — requires terminal support |
| Raw ANSI | `"\x1b[38;5;208m"` | Escape sequences (also `\e`, `\033`) |

### Color keys

`context`, `five_hour`, `seven_day`, `cwd`, `branch`, `model`, `cost`, `diff_add`, `diff_remove`, `duration`, `five_hour_reset`, `seven_day_reset`, `dim`, `warn`, `danger`

Each bar changes color at thresholds: **< 50%** uses the base color, **≥ 50%** uses `warn`, **≥ 80%** uses `danger`.

### Precedence

```
styles.ts defaults → --theme file → ~/.claude/statusline-theme.json → --style flag → --sep flag
```

- `--theme` sets both style and colors from a shipped preset
- User theme file (`~/.claude/statusline-theme.json`) overrides on top — user always wins
- `--style` overrides bar characters/separator (but not colors) when explicitly passed
- `--sep` overrides the separator character

## JSON Output

```bash
echo '{"context_window":{"used_percentage":62}}' | npx @robmorris/claude-usage-line --json
```

```json
{
  "model": null,
  "cwd": null,
  "git_branch": null,
  "session": { "utilization_pct": 62, "resets_at": null, "remaining": "--" },
  "five_hour": { "utilization_pct": 48, "resets_at": "2026-02-26T14:00:00Z", "remaining": "3h28m" },
  "seven_day": { "utilization_pct": 63, "resets_at": "2026-02-28T00:00:00Z", "remaining": "22h30m" },
  "diff": { "added": 0, "removed": 0 },
  "cost_usd": null,
  "duration_min": null
}
```

## CLI Reference

```
Usage: claude-usage-line [options]
       claude-usage-line setup [--theme <name>] [--force]

Options:
  --theme <name>  Use a shipped theme (e.g. dark-contrast)
  --style <name>  Bar style (classic, dot, braille, block, ascii, square, pipe)
  --hide <fields> Hide fields (comma-separated): cost,diff,duration,model,cwd,branch
  --sep <name>    Separator: bullet (default), pipe, dot, diamond, arrow, star
  --json          Output JSON
  --help          Show help
  --version       Show version

Setup options:
  --theme <name>  Include --theme in the statusline command and copy that theme file
  --force         Overwrite existing settings and theme file
```

### Hiding Fields

Hide parts of the output using `--hide` or the `hide` key in your theme file:

```json
{
  "statusLine": {
    "type": "command",
    "command": "npx @robmorris/claude-usage-line --hide cost,duration"
  }
}
```

Or in `~/.claude/statusline-theme.json`:

```json
{
  "hide": ["cost", "duration"]
}
```

Theme and CLI hide fields are combined (union of both). Available fields: `cost`, `diff`, `duration`, `model`, `cwd`, `branch`

## Development

```bash
npm run build
echo '{"context_window":{"used_percentage":62}}' | node dist/cli.js
echo '{"cwd":"/tmp","model":{"display_name":"Opus 4.6"},"context_window":{"used_percentage":85},"cost":{"total_lines_added":42,"total_lines_removed":10,"total_cost_usd":1.23,"total_duration_ms":3720000}}' | node dist/cli.js
echo '{"context_window":{"used_percentage":55}}' | node dist/cli.js --theme dark-contrast
echo '{"context_window":{"used_percentage":55}}' | node dist/cli.js --theme dark-contrast --style ascii
```

## License

MIT