flux-code — a live status line for Claude Code

🎯

Native data only

Reads the fields Claude Code already passes to the status line. No /usage scraping, no network calls, no undocumented APIs.

🪶

Self-contained plugin

Ships a pre-built bundle with zero runtime dependencies. Install straight from GitHub — nothing to compile, no npm package required.

🎨

Five single-line themes

Compact, minimal, powerline, nerd-font, and a plain-text mode safe for tmux, CI, and logs. Every theme fits the one-row status line — no wasted vertical space.

⏳

No loading flicker

Usage segments stay hidden until Claude Code reports them, then appear — no -- placeholders on a fresh session.

🔔

Usage alerts

Opt in to a desktop notification the moment your 5-hour or weekly usage crosses a threshold — a rate limit never surprises you mid-task.

📊

Extra segments

Optional lines-changed, session time, spend-rate, repo, context tokens, git-dirty count, version, and supa-mcp Supabase project segments — all from data Claude Code already provides (or a local CLI call, cached per session).

Install

flux-code is a self-contained Claude Code plugin. Run these inside Claude Code — nothing to build.

Add the marketplace
```
/plugin marketplace add im-shubhamsharma/flux-code
```
Registers this GitHub repo as a plugin marketplace.
Install the plugin
```
/plugin install flux-code@flux-code
```
The name is flux-code@flux-code — plugin name @ marketplace name.
Run setup
```
/flux-code
```
Writes the statusLine block into ~/.claude/settings.json and seeds a default ~/.claude/flux-code.json. Send one message (or restart Claude Code) to see it. A plugin can't set the main status line itself, so this step wires it for you.

Updating later

/plugin marketplace update flux-code
/reload-plugins

The marketplace update git-pulls the latest release; /reload-plugins applies it in-session. Your existing ~/.claude/flux-code.json is left untouched — edit it (or delete it and re-run /flux-code) to pick up new defaults.

Prefer source? (development / manual)

git clone https://github.com/im-shubhamsharma/flux-code.git
cd flux-code && npm install && npm run build
node dist/index.js install   # or: npm link && flux-code install

Themes

Set theme in your config. compact is the default; every theme degrades gracefully when a value isn't available yet.

compact · default

Opus 4.8 | main | Ctx 41% | 5h 61% (2h 13m) | Week 19% | $0.12

One line, pipe-separated. The everyday default. Past 50% the 5-hour segment shows when it resets and how long is left.

powerline

Opus 4.8‡ feature/authCTX 82%5H 61% · (2h 13m)7D 19%$0.12

Colored background segments chained with separators. Needs a Powerline or Nerd Font in your terminal.

nerd-font

❖ Opus 4.8 ⎇ feature/auth ◔ 82% ↯ 61% (2h 13m) ▤ 19% $ 0.12

Glyph icons instead of labels — shown here with stand-ins; a Nerd Font terminal renders crisp Font Awesome icons.

minimal

Opus 4.8 │ 5h 24% │ Week 11%

Only the numbers that matter, thin separators.

plain-text

Opus 4.8 | main | Ctx 82% [##########--] | 5h 61% | Week 19% | $0.12

ASCII only, no color — safe for tmux, CI, and logs.

Run flux-code preview to see all five in your own terminal with color.

Configure

Config lives at ~/.claude/flux-code.json (override with FLUX_CODE_CONFIG). Every key is optional; unknown or malformed values fall back to defaults, so the status line never crashes.

{
  "theme": "compact",
  "showBranch": true,
  "showCost": true,
  "hideUnavailable": true,
  "progressWidth": 12,
  "useColors": true,
  "refreshSeconds": 30,
  "colorThresholds": { "yellow": 60, "orange": 80, "red": 90 }
}

Key	Default	What it does
`theme`	compact	compact · minimal · powerline · nerd-font · plain-text
`countdownAfterPercent`	50	5-hour usage above which the segment appends `(2h 13m)`
`hideUnavailable`	true	Hide 5h/weekly until they load instead of showing `--`
`showLines`	false	Lines added/removed this session (`+124 −18`)
`showSessionTime`	false	Elapsed session time (`2h 13m`)
`showBurnRate`	false	Spend rate in USD per hour (`$0.34/h`)
`showRepo`	false	Repository as `owner/name`
`showTokens`	false	Context token count (`45.2k tok`)
`showGitDirty`	false	Count of uncommitted git changes (`±3`)
`showSupaMcp`	false	Active supa-mcp Supabase project and access mode (`acme-prod (ro)`). Hidden when unlinked or supa-mcp isn't installed.
`showVersion` / `showOutputStyle` / `showEffort`	false	Claude Code version, output style, and effort level
`notify`	false	Desktop notification when 5h/weekly cross `notifyThresholds`
`notifyThresholds`	[90]	Percent levels that trigger a notification, e.g. `[80, 95]`
`showBranch`	true	Show the git branch (set false to skip the git call entirely)
`showCost`	true	Show session cost in USD when available
`showWorkingDirectory`	false	Show the current directory
`progressWidth`	12	Progress-bar width in characters (1–60)
`useColors`	true	ANSI colors (also honors `NO_COLOR`)
`refreshSeconds`	30	How often the line re-runs so countdowns tick while idle
`colorThresholds`	60/80/90	Percent boundaries for yellow, orange, red

Recipes

// A quiet single line — only the numbers
{ "theme": "minimal", "showBranch": false, "showContext": false }

// Always show the 5-hour reset time, from the very first percent
{ "countdownAfterPercent": 0 }

// Warn earlier: yellow at 50%, red at 80%
{ "colorThresholds": { "yellow": 50, "orange": 70, "red": 80 } }

FAQ

The questions that come up most.

Why do 5-hour and weekly numbers take a moment to appear on launch?

The plugin doesn't fetch them — Claude Code hands them over in its status-line payload, and it only fills in rate_limits after the first API response of the session. On a fresh launch, before your first request returns, the fields simply aren't there yet. They pop in on the next render once your first message completes. Nothing can make the data arrive sooner; the plugin itself renders instantly. This is why hideUnavailable defaults to true — no -- flicker during that window.

Where did the multi-line default theme go?

Removed in v1.4.0. The Claude Code status line is a single row, so a multi-line dashboard only ate vertical space in the terminal. Every remaining theme is one line; a config that still says "theme": "default" falls back to compact. The reset countdown it carried now lives in the 5-hour segment itself — see countdownAfterPercent.

Does it scrape /usage or make network calls?

No. It reads the rate_limits object Claude Code already passes to the status line. No network, no scraping, no undocumented APIs.

Does it cost API tokens?

No. Status line commands run locally and don't consume API tokens.

The 5h / Week segments never show up.

rate_limits appears only for Claude.ai Pro and Max subscribers, after the first API response. API-key sign-ins never receive these fields, so with the default hideUnavailable: true the segments stay hidden. Set it to false to show them as --.

Why does cost reset when I run /clear?

That's Claude Code's own behavior for cost.total_cost_usd. flux-code just displays the field.

Can a plugin set my status line automatically?

No — Claude Code only lets a plugin ship agent and subagentStatusLine defaults, never the main statusLine. That's why /flux-code runs the installer to write it into your settings.