statusline-bar

A customizable statusline for Claude Code. One bash file and jq — no Node, no
Rust, no daemon, no network calls.

That is the default preset on a dark terminal. Here is the same statusline,
same session, on a light one:

6 of the 21 themes are drawn for a light background and 3 more work on either, so
light terminals are a first-class target, not an afterthought.

That was 18 tokens. There are 48.

Pick any of them, in any order, across up to four lines.

🤖 Fable 5.1 | 🧠 47% (471k/1M) | 💰 $8.47 | 🕔 5h █████░░░░░ 45% 🔄 2h 14m 37s | 🕖 7d ██████░░░░ 62% 🔄 3d 6h 41m 12s | ❄️ 47m 18s
💭 true | 💪 high | 📁 statusline-bar | 🌳 main | 🌿 feat/wizard | 📊 +3 ~5 ?2 | 🔀 ↑2 ↓1 | ➕ +342 | ➖ -118 | 💾 87% | 🪟 1h | ⏳ 2h 18m 4s

Why

The Claude Code ecosystem already has a dozen good statuslines, each strong at
one thing. This is an attempt at one tool that does all of it:

• Every useful field. 48 tokens — model, cost, context, prompt-cache
  health, 5h and 7d rate limits with countdowns, git branch and status and
  ahead/behind, vim mode, agent name, session id, plus free local readouts like
  clock, battery, memory and load.
• Good out of the box. 12 presets, 21 themes, 12 progress-bar styles,
  truecolor when your terminal has it.
• Trivial to install. One file plus jq. Nothing to build, nothing running
  in the background.
• Customizable to the last detail. Up to 4 lines, any token in any order,
  and per-token overrides for prefix, format, bar style and separator.

A TUI wizard drives all of it, with a preview pane that re-renders as you move
the cursor. The config is plain JSON with a schema shipped alongside, so your
editor autocompletes it if you would rather type.

Install

Clone it somewhere stable:

mkdir -p ~/.local/share
git clone https://github.com/Dworf/statusline-bar.git ~/.local/share/statusline-bar
chmod +x ~/.local/share/statusline-bar/statusline-bar.sh

Upgrade later with cd ~/.local/share/statusline-bar && git pull.

Requirements

bash 3.2+ (already on your machine) and jq, which does all the JSON
work and is the one thing you may need to install:

jq --version should print something like jq-1.7.1.

Optional: git for the git tokens, fc-list for Nerd Font detection, and
pmset or /sys/class/power_supply for the battery token. A
Nerd Font unlocks three separators and two prefix
styles; everything else works without one.

Wire it up in Claude Code

Claude Code reads ~/.claude/settings.json. The whole file is one JSON
object — if it already has model, permissions, hooks and friends, add
statusLine alongside them, don't overwrite the file:

{
  "model": "...",
  "permissions": { ... },
  "statusLine": {
    "type": "command",
    "command": "/Users/YOUR_USERNAME/.local/share/statusline-bar/statusline-bar.sh"
  }
}

Two things that trip people up:

• The path must be absolute — ~ and $HOME are not expanded. Paste the
  output of realpath ~/.local/share/statusline-bar/statusline-bar.sh. On
  Windows, use the WSL or Git Bash path.
• JSON has no trailing commas. If the key that used to be last had no comma
  after it, add one before appending statusLine.

Restart Claude Code and the statusline appears at the bottom. If it doesn't,
run the script by hand against the bundled sample payload — you should get a
populated two-line render:

~/.local/share/statusline-bar/statusline-bar.sh < ~/.local/share/statusline-bar/test/sample-input.json

Configure

statusline-bar.sh -w        # or --wizard

The main menu has a row per global setting — preset, theme, prefix style,
separator, bar style, Tokens & lines, empty-data behavior, color depth —
over a live preview. ↑/↓ navigates, ←/→ cycles values in place, Enter
drills in, Esc goes back, s saves, r resets, q quits.

Every picker follows the same shape — options on the left, a per-option sample
on the right, the full statusline preview underneath. Nothing is a guess:

Tokens & lines is the layout editor: line tabs across the top (up to 4),
the token list with its separators inline below, preview at the bottom. a
adds a token, c changes one, d deletes, Shift+↑/↓ reorders, m/p moves
a token to another line, and Enter on a token opens its per-token prefix /
format / bar-style overrides. Full keymap in the
reference.

Where your config lives

The wizard saves to the first of these that exists, and the script reads them
in the same order:

1. --config PATH
2. $STATUSLINE_BAR_CONFIG
3. ./.statusline-bar.json in the session's workspace directory — pin a
   statusline per project
4. $XDG_CONFIG_HOME/statusline-bar/config.json
5. ~/.config/statusline-bar/config.json
6. built-in defaults

Tune it live

Keep the wizard open in one terminal and a real Claude Code session in another.
Press s and the config lands on disk; Claude Code picks it up on its next
statusline refresh and renders it against your actual data — real cost, real
countdowns, real git status — instead of the wizard's synthetic preview. To
force a refresh, type / in Claude Code and pick any slash command.

What you can change

Twelve presets, from three tokens on one line to all 48 across four:

minimum	focus
coder	compact
cache	modern
rates (dark theme)	fancy (dark theme)

And the same preset under three different prefix styles — every token's label
is swappable, globally or one at a time:

emoji (default)	ascii	nerd

To see all of it rendered in your terminal at your color depth:

statusline-bar.sh -e                  # the whole catalog
statusline-bar.sh -e themes           # one section: presets | themes | prefixes
                                      # | separators | bars | tokens

More

• REFERENCE.md — every catalog in full, the config schema,
  per-token overrides, and the complete CLI.
• CHANGELOG.md — release history.

Contributing

Issues and PRs welcome at https://github.com/Dworf/statusline-bar.

Run the suite before submitting — 175 end-to-end cases, and they must all pass:

./test/run-tests.sh

If your change touches a token, preset, theme or catalog, regenerate the
screenshots too — see
Regenerating the screenshots.

License

MIT — see LICENSE.

Acknowledgements

• Anthropic, for Claude Code and
  the open statusline interface that makes this possible.