statusline

claude-statusline

A Claude-native, modular status line for Claude Code. Compose it from small, self-contained components — and let Claude read, vet, and tune them for you.

What it is

claude-statusline is a Claude Code plugin that replaces the single-line status bar with a multi-line, component-based one. Each piece — a context bar, a rate-limit countdown, a news ticker, a little ASCII creature — is an independent component. A profile is a template that picks which components run and where they sit. Swap the profile, drop in a new component, and the line re-composes itself.

📰  Breaking ……… latest headlines scrolling across the top …………………………
────────────────────────────────────────────────────────────────────
        ▟▙              ▗▄▖
       ▟██▙            ▟███▙        ← a little creature pacing the strip
      ▝▀██▀▘           ▝███▘
▁▂▃▄▅▆▇█▇▆▅▄▃▂▁▂▃▄▅▆▇█▇▆▅▄▃▂▁▂▃▄▅▆▇█  (time-of-day grass)
 opus-4.8  ·  ctx 38%  ·  5h 22% ↻1h47m  ·  7d 61% ↻3d  ·  $0.42
 ⎇ main ✓  ·  PR #128 ✓  ·  $0.18/hr  ·  ♪ Nujabes — Aruarian Dance
 0050 ▲131.05   2353 ▼ 78.40   2382 ▲142.00   3231 ▲ 24.95   TAIEX ▲

That's the full profile: a news widget on top, a rule, the creatures stage in middle, a session row (row1) and a repo/usage row (row2), and a stock ticker at the bottom.

Install

/plugin marketplace add zyx1121/claude-statusline
/plugin install statusline@claude-statusline
/statusline:setup

/statusline:setup installs a stable shim, points settings.json's statusLine.command at it, creates your user layer, and previews the result. (Claude Code can't expand a plugin path inside statusLine.command, and the plugin cache path is version-numbered and churns on every update — so the shim resolves the latest installed version at runtime, and you only wire it once.)

Concepts

• Component — one widget or segment: a directory under components/<id>/ with a component.json manifest and a renderer (render.sh or render.py). It reads a fixed set of CC_* inputs and emits its own piece of the line.
• Profile — a template that composes components. It declares which components to run, which slot each sits in, their order, and per-instance config. The same component can appear more than once (e.g. a 5h and a 7d ratelimit segment, distinguished by order + config). Profiles are JSON; full and minimal ship as examples.
• Marketplace — components are distributed like plugins. Install this plugin's built-ins, or drop a component into your user layer (~/.claude/statusline/components/<id>), which is searched first and overrides a built-in of the same id.

Slots

The line is built top to bottom from named slots:

Slot	Type	Behaviour
top / middle / bottom	line widgets	each may emit one or more full lines
row1 / row2	segments	joined together with ·

Built-in components

id	type	what it shows
model	segment	model display name (short)
ctx	segment	context-window usage %, red at ≥80%
ratelimit	segment	5h / 7d usage-limit % + reset countdown (multi-instance)
cost	segment	session cost in USD
burn	segment	cost burn rate ($/hr over the session)
git	segment	branch + dirty / ahead / behind state
pr	segment	open PR number + CI / review state
nowplaying	segment	now-playing track (macOS)
news	line	scrolling headlines ticker
creatures	line	a tiny ASCII creature world that paces the line
stock-ticker	line	left-scrolling TWSE stock ticker (keyless)

Writing a component

A component is a directory with a component.json manifest and a renderer. The interface is spec'd in plugin/spec/CONTRACT.md, with JSON schemas at plugin/spec/; the short version of the manifest:

{
  "$schema": "statusline/component@1",
  "id": "ctx",
  "name": "Context Usage",
  "version": "0.1.0",
  "author": { "github": "you" },
  "description": "Context-window usage percentage, turning red at ≥80%.",
  "type": "segment",                       // "segment" | "line"
  "runtime": "bash",                       // "bash" | "python3" | ...
  "render": { "entry": "render.sh" },      // line widgets may add a "ttl"
  "inputs": ["context_window.used_percentage"],  // stdin fields the host projects
  "requires": {},                          // { bin, network, macos }
  "config": {},                            // { schema, file } for tunable knobs
  "placement": { "slot": "row1", "order": 20 },
  "capabilities": { "stdin_fields": ["context_window.used_percentage"] }
}

Two types: