claude-cli-plugin-usage

Powerline-style status line for the Claude Code CLI — see your model, git branch, context usage, rate limits, and reset countdowns at a glance.

 🧠 Opus 4.6  main  ████████░░ 78%  ⚡ 5h 32% │ 7d 15% 
📁 mvp │ ↻ 5h 2h15m │ 7d 3d12h

🤖 AI-Generated Project

This project was designed, implemented, tested, and documented by an AI agent (Claude / Claude Code). Every module, test, and doc — including this README — was produced through agent-driven development. It works and is covered by tests, but treat it as an experiment: review the code before relying on it in a critical setup, and see Known Limitations for issues the agents deliberately left open.

Table of Contents

• Features
• Installation
• Usage
• For AI Agents
• Configuration
• How It Works
• Project Structure
• Development
• Testing
• Roadmap
• Known Limitations
• Contributing
• Troubleshooting
• Requirements
• License
• Acknowledgements

Features

• Powerline visual style — ANSI 256-color segments with arrow transitions
• Auto-detects your plan — Free, Pro, Max, or API, with no configuration
• Dynamic context bar — green → yellow → red as context usage climbs
• Rate-limit tracking — 5-hour and 7-day windows (Pro / Max)
• Reset countdowns — time until each rate-limit window resets (Pro / Max)
• Cost tracking — cumulative session cost in USD (API users)
• Session name line — worktree / project / directory, at a glance
• Zero config — sensible defaults out of the box; fully customizable when you want it
• Zero dependencies — pure Node.js standard library
• Cross-platform — macOS, Linux, Windows

Installation

Two ways to install — both end up adding a statusLine entry to your settings.json:

• npm (fully automatic) — recommended for most users.
• Claude Code plugin — via /plugin; you run one command afterward to enable the status line.

Via npm (recommended)

npm install -g claude-cli-plugin-usage

The postinstall script automatically wires the status line into ~/.claude/settings.json.

From source

git clone https://github.com/freejerry/claude-cli-plugin-usage.git
cd claude-cli-plugin-usage
npm install -g .

As a Claude Code plugin

The repo doubles as its own plugin marketplace. In Claude Code:

/plugin marketplace add freejerry/claude-cli-plugin-usage
/plugin install claude-cli-plugin-usage@claude-cli-plugin-usage

A plugin can't set the status line on its own, so enable it afterward with the bundled command:

/claude-cli-plugin-usage:enable-statusline

It resolves the tool's bin/cli.js — first from the plugin cache, then falling back to a global npm install (command -v claude-cli-plugin-usage), and finally asking you — then merges { "statusLine": { "type": "command", "command": "node <absolute-path>/bin/cli.js" } } into your settings.json. (Claude Code does not expand ${CLAUDE_PLUGIN_ROOT} in the statusLine field, so a real absolute path is written; re-run the command after updating the plugin.) Restart Claude Code afterward.

Manual setup

If automatic configuration didn't run, add this to ~/.claude/settings.json (merge into existing keys — don't overwrite the file):

{
  "statusLine": {
    "type": "command",
    "command": "claude-cli-plugin-usage"
  }
}

Then restart Claude Code so it re-reads its settings.

Usage

Once installed and wired up, the status line renders automatically at the bottom of every Claude Code session. Claude Code pipes a JSON status payload to the command on stdin; this tool parses it and prints one or two colored lines.

First line — Powerline segments:

| Segment | Shows | Plan | |---------|-------|------| | 🧠 Model | Current model name | All | | Git | Current branch (hidden outside a git repo) | All | | Context | Usage bar + percentage | All | | ⚡ Rate Limits | 5h and 7d usage | Pro / Max | | 💰 Cost | Session cost in USD | API |

Second line — a low-key gray line:

• 📁 Session name — worktree name, or project folder (fallback: current directory)
• ↻ Reset countdowns — time until the 5h and 7d windows reset (Pro / Max only); the value is highlighted, turning green when the reset is under an hour away

The second line is omitted when there's nothing to show and can be disabled via configuration.

For AI Agents

Point any Claude Code agent at the self-contained, copy-paste-runnable install guide so it can install, wire up, and verify this tool in a single conversation:

• In-repo: docs/agent-install.md
• Raw URL: https://raw.githubusercontent.com/freejerry/claude-cli-plugin-usage/main/docs/agent-install.md

Configuration

All configuration is optional. To customize, create ~/.claude/claude-cli-plugin-usage.json. Any omitted key falls back to its default:

{
  "theme": "default",
  "segments": ["model", "git", "context", "ratelimit"],
  "contextBar": {
    "width": 10,
    "thresholds": { "warn": 60, "danger": 80 }
  },
  "ratelimit": {
    "thresholds": { "warn": 60, "danger": 80 }
  },
  "secondLine": {
    "enabled": true,
    "show": ["session", "resets"]
  }
}

Options

| Key | Type | Default | Description | |-----|------|---------|-------------| | theme | string | "default" | Color theme — default, minimal, or solarized | | segments | string[] | ["model","git","context","ratelimit"] | First-line segment order; also acts as show/hide | | contextBar.width | number | 10 | Width of the context progress bar, in cells | | contextBar.thresholds.warn | number | 60 | % at which the bar turns yellow | | contextBar.thresholds.danger | number | 80 | % at which the bar turns red | | ratelimit.thresholds.warn | number | 60 | Rate-limit warning threshold | | ratelimit.thresholds.danger | number | 80 | % at which rate-limit text turns red | | secondLine.enabled | boolean | true | Set false for single-line output | | secondLine.show | string[] | ["session","resets"] | Which second-line blocks to render |

Themes

• default — deep blue, purple, green/yellow/red
• minimal — monochrome with color alerts only
• solarized — solarized palette

Segment order

Reorder or hide first-line segments by editing segments:

{ "segments": ["context", "model"] }

How It Works

A simple stdin → stdout pipeline, each stage a small pure module:

Claude Code
    │  (JSON status payload on stdin)
    ▼
┌─────────────────────────────────────────────────────────┐
│ bin/cli.js — read stdin, orchestrate, write stdout       │
└─────────────────────────────────────────────────────────┘
    │            │              │                │
    ▼            ▼              ▼                ▼
 parser.js  detector.js   config.js      powerline.js
 (raw JSON  (Free/Pro/    (defaults +    (render segments +
  → fields)  Max/API)      user overrides) second line)
                                                │
                                    theme.js · width.js · format-duration.js
    │
    ▼  (ANSI-colored line(s) on stdout)
Claude Code status bar

• parser.js — extracts a clean field set from Claude Code's raw JSON.
• detector.js — classifies the plan (1M context ⇒ Max, rate limits ⇒ Pro, cost-only ⇒ API, else Free).
• config.js — loads ~/.claude/claude-cli-plugin-usage.json and deep-merges over defaults.
• powerline.js — builds segments and lays out the two lines.
• theme.js — ANSI 256-color palettes and powerline transitions.
• width.js — visible-width measurement (emoji/CJK-aware) and terminal width.
• format-duration.js — human-readable reset countdowns (2h15m, 3d12h).

Project Structure

claude-cli-plugin-usage/
├── .claude-plugin/
│   ├── plugin.json         # Claude Code plugin manifest
│   └── marketplace.json    # self-hosted marketplace entry
├── commands/
│   └── enable-statusline.md # /claude-cli-plugin-usage:enable-statusline
├── bin/cli.js              # entry point — stdin/stdout orchestration
├── src/
│   ├── parser.js           # raw JSON → clean fields
│   ├── detector.js         # plan auto-detection
│   ├── config.js           # defaults + user override merge
│   ├── powerline.js        # segment building + layout
│   ├── theme.js            # ANSI color themes
│   ├── width.js            # visible-width / terminal-width helpers
│   └── format-duration.js  # reset-countdown formatting
├── scripts/
│   ├── postinstall.js      # auto-inject statusLine into settings.json
│   └── preuninstall.js     # remove it on uninstall
├── tests/                  # node:test suites + fixtures
└── docs/
    └── agent-install.md    # LLM-oriented install guide

Development

git clone https://github.com/freejerry/claude-cli-plugin-usage.git
cd claude-cli-plugin-usage
npm install          # no runtime deps; installs nothing but sets up the repo
npm test             # run the full suite

Run the renderer locally by piping a sample payload:

echo '{"model":{"display_name":"Opus 4.6"},"worktree":{"branch":"main"},"context_window":{"used_percentage":78,"context_window_size":200000}}' | node bin/cli.js

Testing

Tests use Node's built-in test runner (node:test) — no framework, no fixtures beyond a sample JSON file.

npm test

Each src/ module has a matching tests/*.test.js (unit), plus tests/integration.test.js exercising the full stdin → stdout pipeline. Current status: 81 tests passing.

Roadmap

• [x] Publish to npm registry
• [x] Fix the arrow-width undercount
• [ ] Configurable second-line blocks beyond session / resets
• [ ] Additional built-in themes
• [ ] CI workflow (lint + test on push)

Known Limitations

• Experimental. As an AI-generated project, edge cases in unusual terminals or payload shapes may not be fully covered.

Contributing

Everyone's welcome to help maintain this — no ceremony required.

Open an issue, or send a PR. If you're adding logic, a quick npm test to keep it green is appreciated. That's it.

Troubleshooting

• No arrows / boxes shown → your terminal needs a Powerline-compatible font.
• Second line missing → expected when there's nothing to show (no session name, no rate limits), or secondLine.enabled is false.
• Rate-limit / reset segments absent → only Pro/Max plans expose rate_limits; Free/API won't show them.
• [claude-cli-plugin-usage: parse error] → the stdin JSON was malformed; check what Claude Code is sending.
• Nothing changes in Claude Code → restart the session so it re-reads settings.json.

Requirements

• Node.js ≥ 18 (already present if you use Claude Code)
• A terminal with ANSI 256-color support
• A Powerline-compatible font for arrow glyphs

License

MIT

Acknowledgements

• Built for the Claude Code CLI.
• Visual style inspired by Powerline.
• Designed and implemented by AI agents via agent-driven development.