lumira

Real-time statusline plugin for Claude Code and Qwen Code.

Interactive version → (scrub, copy text, adjustable speed)

Quick start

Via Claude Code plugin (recommended):

/plugin marketplace add cativo23/lumira
/lumira:setup

No npm required. The /lumira:setup skill writes statusLine.command automatically. Restart Claude Code when done.

Via npm:

npx lumira install

Interactive wizard — preset, theme, icons — previewed live before write.

What's new in v1.18.0: Custom Widgets — your own shell commands can now map their output to an icon/color per value range (valueMap), the same idea as the built-in rate-limit battery glyph. Renamed from "Custom Commands" (customCommands/lumira custom keep working as permanent aliases, nothing breaks) and gained a description field so a widget copy-pasted from someone else's config explains itself. Recent highlights: ⚡fast badge for Claude Code's Opus fast-mode (v1.17.0); the PR widget renders GitLab merge requests with the right !N prefix instead of GitHub's #N (v1.16.2); refreshInterval keeps idle-session data fresh (v1.16.0) — full feature comparison since v1.10. Still a Claude Code plugin — /plugin marketplace add cativo23/lumira, no npm required; run /lumira:setup to activate.

Table of contents

• Why lumira?
• How lumira compares
• Requirements
• Features
• Install
• Display modes
• Themes
• Stats CLI
• Subagent rows
• Prompt cache badge
• Powerline
• Configuration
• Custom Widgets
• Contributing
• License

Why lumira?

Claude Code's default statusline shows the model name and current directory. That's it. Lumira surfaces what actually changes during a session and what you'd want to react to:

• Context-window pressure — color-coded bar from green to blinking red, with a /compact? hint at high fill so you act before hitting the wall.
• Burn rate — $/h next to total cost, so a runaway agent shows up immediately.
• Rate-limit battery — 5h/7d usage shows as a Nerd Font battery glyph (or 🔋/🪫 in emoji mode) that fills as you consume quota, with a reset countdown above 70%. Hidden below 50% to keep the line uncluttered when you have margin.
• Active tools, agents, and todo progress — parsed from the live transcript, updated every render.
• Cross-platform — same config drives Claude Code and Qwen Code; Qwen sessions auto-collapse to single-line.

Inspired by GSD's statusline; takes its own stance on opt-in powerline rendering, theme contrast guarantees, and Qwen Code compatibility.

How lumira compares

The Claude Code statusline space has several good tools. Here's an honest head-to-head on features against the other true statuslines (feature claims checked against each tool's current README, 2026-06-14):

| Tool | Runtime / deps | Distribution | Platforms | Config UX | Powerline + themes | Session-intel widgets | |---|---|---|---|---|---|---| | lumira | TS / 0 runtime deps | npm + npx + plugin (+ Qwen skill) | Claude Code + Qwen Code | Wizard + JSON + CLI flags | Yes (7 styles) + 7 themes, WCAG-AA guard | Quota projection, pace delta, API-latency, auto-compact glyph + counter, cache, agents, MCP, todos, tools + stats CLI | | ccstatusline | TS / bundled | npm + npx | Claude Code | Ink TUI (live preview) | Yes + themes | Context, cost, usage %, block timer, compaction count, git; no quota/pace/latency | | claude-hud | JS / Node 18+ | Plugin marketplace | Claude Code (v1.0.80+) | Guided /configure + JSON | No / no themes | Context, 5h/7d usage, cost, git, tools, agents, todos, cache TTL; no quota ETA/pace/latency | | CCometixLine | Rust binary | npm + binary + source | Claude Code | TUI (TOML) | Yes + themes | Model, dir, git, context %, usage, cost, time, output-style | | claude-pace | Bash + jq | curl + plugin + npx | Claude Code 2.1.80+ | JSON block | No / no | 5h+7d %, pace delta, reset countdown, git diff; ~10ms (lightest) | | cship | Rust binary | binary / script / cargo | Claude Code | TOML (Starship-style) | Yes (Starship) + themes | Cost, context bar, usage limits, model, effort, agent, session, peak-time | | starship-claude | Shell / needs Starship | Plugin + manual | Claude Code (no tmux) | Wizard + TOML | Via Starship + palettes | Context bar, model, session |

Where lumira leads: breadth of session-intelligence widgets — sole owner of an API-latency widget, a 7-day quota projection ETA, an MCP-server count, and a bundled stats analytics CLI, on top of the full pace / agents / todos / cache set. Plus zero runtime deps, dual-platform (Claude Code and Qwen Code), and WCAG-AA contrast enforced in CI on every theme. Where it doesn't: no Ink-style interactive widget builder — config is a wizard + JSON, not a live drag-and-drop TUI.

See docs/competitive-comparison.md for the full per-widget matrix, config-UX detail, and distribution breakdown across every tool.

Requirements

• Node ≥18
• Nerd Font (recommended) — for branch, folder, model, and spinner icons. Use a recent build (Nerd Fonts v3.0+); some indicators use newer Material Design Icons codepoints (e.g. the extended-thinking glyph U+F09D1) that older font releases render as a blank/tofu cell. Falls back to plain glyphs via icons: emoji or icons: none.
• Truecolor terminal (for themes / powerline) — auto-detected via COLORTERM=truecolor. 256-color terminals get a nearest-index projection; named-ANSI terminals fall back to default colors silently.

Features

• Context bar with thresholds — green → yellow → orange → blinking red, plus an actionable /compact? hint when fill is high.
• Session intelligence — pace delta (🐢/🏎️) shows whether you're burning quota faster than the time window allows, with ETA when ahead of pace. Live agent count and cache hit rate round it out.
• Powerline mode + 7 separator presets (arrow, flame, slant, round, diamond, compatible, plain) across 3 lines.
• OSC 8 hyperlinks — clickable directory, repo, PR, and version tag on iTerm2, WezTerm, Kitty, VS Code, Alacritty.
• 7 hand-curated themes — dracula, nord, tokyo-night, catppuccin, monokai, gruvbox, solarized. WCAG AA contrast guaranteed in CI.
• Token + cost metrics — input/output counts, speed (tok/s), $ total + burn rate ($/h), cache hit rate.
• Auto-fits at <70 cols — switches from 3-line custom mode to single-line minimal automatically.
• Zero runtime dependencies — Node 18+ only.
• Dual-platform — Claude Code and Qwen Code share the same config.

• Git status — branch + staged/modified/untracked counts, 5s TTL cache. Branch turns red on dirty repos in powerline mode.
• Repo identity — when Claude Code exposes workspace.repo, line1 shows owner/name as a segment linked (OSC 8) to the repo on its host. Toggle via display.repo.
• PR widget — open pull request/merge request for the current branch, with review state colored by tier (approved/pending/changes_requested) and an OSC 8 hyperlink to it. Shows #N for GitHub PRs, !N for GitLab MRs (including self-hosted instances) — the prefix is derived from the URL's path shape, not the hostname. Toggle via display.pr.
• Rate limits — 5h/7d usage as a battery glyph (Nerd Font level fill, or 🔋/🪫 in emoji mode) with color tier and reset countdown. Threshold-gated at 50% to stay invisible while you have margin.
• Pace delta — usedPct − elapsedPct of the 5h window. Turtle when behind pace (healthy), car with time-to-exhaustion when ahead. Color escalates green → yellow → orange → blinkRed. Toggle independently via display.paceDelta.
• 7d quota projection — when the current burn rate would exhaust the 7d quota before the window resets, the 7d segment grows a warning: ⚠ ~24h, ⚠ ~2d, ⚠ Tue, or 🔥 ~8h (critical icon under 12h). Default on. Toggle via display.quotaProjection; off in the minimal preset. Different from pace delta — pace looks backwards at the 5h window's actual vs proportional burn, projection looks forwards at the 7d window's exhaustion ETA.
• Active agents — live count of running subagents (⚡N agents) plus types parsed from the transcript. Toggle via display.agents.
• Subagent panel rows — custom rendering for each row in Claude Code's agent panel via lumira subagent: a state glyph (running / done / error / killed), the agent type and model as aligned columns, what each agent is doing, and its token count, in your configured theme and icon set. Opt-in at install.
• Cache hit rate — prompt cache efficiency for the current turn (87%⚡). Alarm-mode: hidden while ≥90% (Anthropic's prompt cache pins this near 99% in healthy steady state, so an always-on number is wallpaper, not signal). Surfaces as yellow/orange/blinkRed only when the cache is actually degrading. Same hide-when-healthy pattern as rate-limits and agent count.
• Prompt cache badge — warns before your prompt cache goes cold (❄ 8m · 103k), once it has (❄ cold · 103k), and right after a cache miss (miss ×2 · 203k · model changed). Hidden while the cache is healthy. See Prompt cache badge for how to read it. Toggle: display.promptCache.
• GSD integration — current task and update notifications (opt-in).
• Config health widget — surfaces silent fallbacks (theme/powerline degrading in named-ANSI, missing GSD STATE.md). Opt-in.
• Memory usage — process RSS percentage.
• MCP server detection — count of attached MCP servers per session.
• Fast mode badge — shown when CC reports Opus running at 2.5x output speed (premium pricing). Renders as fast next to the same lightning glyph used for cache hit rate (nerd: U+F140B, emoji: ⚡). Toggle: display.fastMode.
• Vim-mode hint, thinking effort, worktree, output style, session name, added-dirs badge, worktree origin-branch breadcrumb — all togglable per-field via display.*.
• 3-tier color system — named ANSI / 256-color / truecolor, auto-detected.
• Config-driven — every feature toggleable via JSON config + CLI flags.

Install

Option 1 — Claude Code plugin (recommended)

No npm required. Works with the Claude Code plugin marketplace:

/plugin marketplace add cativo23/lumira
/lumira:setup

/lumira:setup finds the cached binary, writes statusLine.command to ~/.claude/settings.json, and creates a default config. Restart Claude Code when done. To customize afterward: /lumira:lumira.

Option 2 — npm

npx lumira install

The installer walks you through preset (full / balanced / minimal), theme, and icons — showing a live preview at each step. Press Esc to abort without writing anything. In non-interactive shells (piped stdin, CI), the installer skips the wizard and writes sensible defaults (preset: balanced, icons: nerd). If Qwen Code is detected (~/.qwen/ exists), the /lumira skill is installed for both CLIs.

For the fastest statusline (the command runs on every render), the installer offers to install lumira globally so it can invoke the compiled binary directly (lumira, ~60ms) instead of npx (~10× slower). It also migrates older npx lumira@latest setups to the faster form automatically.

Or install globally:

npm install -g lumira
lumira install

To uninstall:

npx lumira uninstall

Your preferences are saved to ~/.config/lumira/config.json — hand-edited keys (e.g. custom display toggles) are preserved on re-install.

Manual setup

The statusLine.command runs on every render, so prefer the direct binary. Install globally (npm install -g lumira), then add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "lumira",
    "padding": 0
  }
}

If installed from source, point at the compiled entry:

{
  "statusLine": {
    "type": "command",
    "command": "node /path/to/lumira/dist/index.js",
    "padding": 0
  }
}

Without a global install you can use "command": "npx lumira" — it works, but resolves through npx on every render (~10× slower). Avoid npx lumira@latest: the @latest hits the npm registry on every render.

Keeping idle sessions fresh (refreshInterval) — Claude Code only re-renders the status line on session events, so time-based data (the clock, quota projection) goes stale while a session sits idle. Add CC's refreshInterval (seconds, minimum 1) to statusLine in settings.json to also re-run on a fixed timer:

{
  "statusLine": {
    "type": "command",
    "command": "lumira",
    "padding": 0,
    "refreshInterval": 5
  }
}

Set refreshInterval in lumira's own ~/.config/lumira/config.json instead (see Configuration) and re-run lumira install to have it transcribed into settings.json for you. It only applies to the main statusLine — subagentStatusLine isn't affected, since the agent panel already updates on token-stream events. Values below 1 (CC's documented minimum) round up to 1, and non-integers truncate — a value that low means one process spawn per second for the session's lifetime, so prefer 5+ unless you specifically need second-level freshness. One-way transcription: removing the key from config.json and re-running lumira install does NOT remove an already-transcribed refreshInterval from settings.json — the installer only ever preserves or overwrites, never deletes it. Unset it by editing settings.json directly.

Clickable footer badges (footerLinksRegexes) — a separate, native Claude Code feature (no lumira script involved): configure footerLinksRegexes in settings.json to turn IDs that appear in the conversation (ticket numbers, PR links, etc.) into clickable badges in CC's footer row, below the status line. See the Claude Code settings docs.

Display

Custom Mode (default, >=70 columns)

Minimal Mode (<70 columns or --minimal)

Powerline Mode (opt-in via style: "powerline")

Each segment renders with a distinct background color drawn from the active theme; segments are separated by a Nerd Font glyph (default ``). On dirty git repos the branch segment turns red. Falls back to classic mode silently in named-ANSI terminals (powerline needs RGB backgrounds). See Powerline below for the 7 separator styles.

Themes

Seven hand-curated themes, every one tested for WCAG AA contrast against white foreground in CI. Themes apply to both classic and powerline modes:

dracula · nord · tokyo-night · catppuccin · monokai · gruvbox · solarized

Classic mode — pipe-separated layout, theme colors applied to text:

Powerline mode — colored segment backgrounds with arrow separators:

Themes apply in truecolor and 256-color terminals; named-ANSI terminals fall back to default colors (8 base hues can't represent arbitrary palettes).

Browse from the CLI

Try a theme without touching your config:

lumira themes                                # list all themes
lumira themes preview tokyo-night            # render a sample
lumira themes preview nord --powerline       # same in powerline (default arrow separator)
lumira themes preview gruvbox --style=flame  # powerline with flame separator
lumira themes preview --all                  # render every theme in sequence
lumira themes preview --all --powerline      # the powerline grid (great for screenshots)

Want your favorite theme?

Adding a theme is a single new file plus a one-line registration. Every PR runs the WCAG AA contrast guard — if any powerline cell drops below 4.5:1 against the foreground, CI rejects it. See CONTRIBUTING.md → Adding a theme for the walkthrough.

Stats CLI

lumira stats reads a Claude Code or Qwen Code transcript .jsonl and prints a one-shot analytics summary — session duration, total cost, token totals, cache hit rate, tool call frequency, and burn rate ($/h). Useful for post-session review, scripting, and CI dashboards.

# Just works — auto-discovers the newest transcript for the current cwd.
lumira stats
# Session: 2h 15m — $4.23 — 156k tokens — 87% cache
# Tools: Bash×45 Read×32 Write×18 Edit×12 Agent×8
# Burn: $1.88/h

Auto-discovery: with no flags, lumira stats derives the Claude Code project slug from cwd (/home/me/proj → -home-me-proj) and reads the newest .jsonl under ~/.claude/projects/<slug>/. If the current directory has no matching project dir, it falls back to the globally most-recently-modified transcript under ~/.claude/projects/ and prints a notice to stderr ("reading most recent session from …") so JSON pipelines on stdout stay clean.

Flags:

• --session-id <path-or-uuid> — override auto-discovery. A path (anything containing / or ending in .jsonl) is used as-is. A bare uuid is resolved first under ~/.claude/projects/<cwd-slug>/<uuid>.jsonl, then by scanning every project dir for that filename.
• --no-color — strip ANSI escapes (also honored when the NO_COLOR env var is set, per no-color.org).
• --json — emit the raw SessionStats object as pretty-printed JSON for jq / CI composability.

Qwen Code sessions are parsed the same way, but cost and burn-rate lines are suppressed when the transcript lacks usage blocks (hasCostData: false in the JSON output) — no misleading $0.00.

Subagent rows

Claude Code (≥ 2.1.x) exposes a subagentStatusLine hook that lets a command customize how each subagent renders in the agent panel — replacing the default name · description · token count row. lumira subagent reads the visible tasks from stdin and renders each row in your configured theme and icon set:

󱎫 Explore          haiku   reviewing auth module · 15k tok · running
✓ general-purpose  sonnet  exploring the codebase · 3k tok · done

Reading a row, left to right:

| Part | Example | Meaning | |---|---|---| | Glyph | 󱎫 / ✓ / ⚠ / — | State: running (cyan), done (green), error (red), killed — stopped by you, not a failure (yellow) | | Agent type | Explore, general-purpose, code-reviewer | Which kind of subagent it is — built-in or one of your custom agents. Claude Code's own row shows this too; lumira keeps it so replacing the row doesn't lose it. Names longer than 28 columns are cut | | Model | haiku, sonnet, opus | The model family the subagent runs on (dim). Claude Code's default row doesn't show it — handy when you mix models across agents | | Description | reviewing auth module | What the agent was asked to do | | Tokens · state | 15k tok · running | Its running token count and state in words |

The type and model line up as columns across all visible rows, so parallel agents are easy to tell apart. Both need Claude Code ≥ 2.1.293: on older versions the columns are left out and rows look exactly as before, and a row that lacks one (say, a model Claude Code hasn't resolved yet) leaves that cell blank. Only claude-… model ids have a family to show. When rows don't fit, the descriptions are shortened first, then the model column is dropped, then the type column is narrowed — decided once for all rows so they stay aligned, and the state glyph and label always stay.

The description column falls back through name → a meaningful type → description → id: Claude Code reports every Task subagent with the generic type: "local_agent" and no name, so in practice it's the description. Rows respect your icons (nerd/emoji/none) and colors.mode config, and text from the payload is stripped of terminal control characters before it's drawn.

Enable it: the installer offers to register subagentStatusLine alongside the main statusline (opt-in — it never writes the second key without asking). To wire it manually, add to ~/.claude/settings.json:

{
  "subagentStatusLine": { "type": "command", "command": "lumira subagent", "padding": 0 }
}

It's robust by design: on any unreadable or malformed payload it emits nothing and exits 0, so Claude Code falls back to its default rows — a bad render never breaks the panel. Set LUMIRA_DEBUG=1 to log the raw payload Claude Code sends to stderr.

Prompt cache badge

Claude Code caches your conversation's prompt between requests. While the cache is warm, each message reads that context back cheaply; once it expires, the next message has to process and write the whole context again, which costs noticeably more. The cache lives for a fixed TTL (5 minutes or 1 hour — Claude Code reports which) and every message resets the clock — so it only goes cold when you step away.

Claude Code (≥ 2.1.251) reports the cache state to the statusline, and lumira turns it into a badge on line 2. It stays hidden while the cache is healthy and appears only when there's something to act on:

| State | When it appears | Example | What it means | |---|---|---|---| | Expiring (yellow) | Last 10 minutes of a 1h TTL, or the last minute of a 5m one | ❄ 8m · 103k | The cache goes cold in 8 minutes. If it does, your next message re-caches 103k tokens. | | Cold (cyan) | The TTL has passed with no new message | ❄ cold · 103k | The cache is gone. Your next message pays to re-cache 103k tokens. | | Miss (orange) | For 5 minutes after a cache miss | miss ×2 · 203k · model changed | A request just missed the cache. See below. |

❄ stands for the Nerd Font snowflake; emoji mode shows 🧊 and icons: "none" shows cache. When more than one state applies, cold wins over expiring, and both win over a recent miss — they're the ones still worth acting on.

Reading a miss. The count and the token figure are totals for the whole session, not for the last miss alone. miss ×6 · 680k · idle >1h means this session has missed the cache six times and re-cached 680k tokens across all of them — roughly 113k each. Only the cause describes the most recent miss:

| Cause | Meaning | |---|---| | idle >1h / idle >5m | The TTL expired between messages | | model changed | You switched models (e.g. /model) — each model has its own cache | | tools changed | Tools were added or removed (e.g. an MCP server connected) | | prompt changed | The system prompt changed | | server-side | Most likely evicted on Anthropic's side; nothing you did |

Causes Claude Code adds later show up as-is, with underscores turned into spaces.

What to do with it. When you see expiring, sending any message within the window keeps the cache warm. When you see cold, decide whether the old context is still worth its re-cache cost: if it is, carry on — you pay once and the cache is warm again; if not, /compact or a fresh session re-caches far less. A climbing miss total is a hint that long sessions with frequent breaks are getting expensive.

Countdown vs. clock time. Claude Code only redraws the statusline when something happens, so a countdown would freeze while you're away. lumira shows the minute countdown only when it knows the line redraws at least once a minute — refreshInterval ≤ 60 in lumira's own config, applied with lumira install (see Manual setup); a value set only in settings.json isn't visible to lumira. Otherwise the badge shows the clock time the cache expires (❄ 14:26 · 103k), which stays correct however long the line goes without a redraw.

The badge tracks the main session only — subagents keep their own caches and aren't counted — and appears after the first response of a session. Toggle with display.promptCache (on in full and balanced, off in minimal). It's independent of the cache hit rate widget (87%⚡), which measures the current turn; both can show after a miss.

Powerline

style: "powerline" (or --powerline) renders the statusline with colored segment backgrounds and glyph separators inspired by powerline-go / oh-my-posh. Available separator presets via powerline.style (or --powerline-style=<name>):

| Style | Look | |---|---| | arrow | classic right-pointing triangle separator (default) | | flame | wavy flame-shaped separator | | slant | forward-slanting separator | | round | rounded caps at line ends + thin internal separators | | diamond | each segment isolated as its own pill with rounded caps | | compatible | unicode ▶ separator (no Nerd Font required) | | plain | no separator glyphs — just colored blocks | | auto | picks arrow if Nerd Font icons are configured, else compatible |

Hyperlinks (OSC 8)

The directory on line 1 becomes a clickable file:// link, and the version tag links to its npm release page on terminals that support OSC 8 (iTerm2, WezTerm, Kitty, Alacritty, VS Code terminal, tmux ≥3.4 with passthrough). Other terminals show plain text. Auto-disabled in Apple_Terminal (which leaks markers) and TERM=dumb.

NO_HYPERLINKS=1 claude    # disable
FORCE_HYPERLINK=1 claude  # force-enable (overrides denylist)

Qwen Code

Lumira auto-detects the platform. In Qwen Code sessions, the renderer automatically switches to single-line output regardless of your configured layout — Qwen only displays the first statusline row, so lumira fits everything (model, branch, context bar, cost, cached tokens, thoughts) into one line. No configuration needed: the same config.json serves both Claude Code and Qwen Code.

Configuration

Create ~/.config/lumira/config.json — every field is optional, an empty file gets you the balanced preset defaults. Preset, theme, icons, style, layout, per-widget display.* toggles, context-bar thresholds, and every CLI flag are documented in docs/configuration.md.

Debugging

Set LUMIRA_DEBUG=1 to trace parser decisions on stderr — cache hits, GSD state-file resolution, MCP server loads. Useful when investigating "why doesn't X show up?" reports. Stdout stays clean so it doesn't corrupt the statusline.

LUMIRA_DEBUG=1 claude    # or export LUMIRA_DEBUG=1

Custom Widgets

Render your own shell commands as statusline segments on any line — disabled by default, one command (lumira widget enable) turns it on. Output can map to an icon/color per value range (valueMap), same idea as the built-in rate-limit battery glyph. A widget is a single, self-contained JSON object — copy-paste-shareable, no import/registry needed. Full field reference, valueMap details, and ready-to-copy examples: docs/custom-widgets.md.

Was called "Custom Commands" (customCommands/lumira custom) — both names keep working as permanent aliases.

Contributing

PRs welcome — particularly for new themes (one of the most common contribution paths). See CONTRIBUTING.md for the branching model, theme submission walkthrough, and the contrast-guard CI step that runs on every theme PR.

What's next

• Themes — community theme contributions welcome via the theme PR template.
• Backlog — incremental transcript parsing for very large sessions (deferred; full re-parse stays under budget for real-world transcripts).

CLI flags, preset names, and the config schema have been stable since v1.0 — additive changes only.

For security issues, see SECURITY.md.

Credits

Migrated from claude-setup statusline.

Theme palettes drawn from upstream specs: Dracula, Nord, Tokyo Night, Catppuccin, Monokai, Gruvbox, Solarized.

License

MIT © Carlos Cativo — see LICENSE for the full text.