Claude Code Statusline Designer

A statusline designer for Claude Code. Pick a theme, tune every color with a live preview, and install it in one keystroke.

Claude Code can run any shell script as its status line. This tool writes that script for you. It shows the model, effort level, git branch, context usage, cost and more as powerline segments, in a theme you design in an interactive terminal UI.

Highlights

• Live preview while you design. Two sample statuslines, a clean session and a busy one, repaint on every change. They even update while you hover over a color in the palette. The preview runs the real generated script, so it shows exactly what Claude Code will display.
• 22 themes, dark and light. Catppuccin, Tokyo Night, One Dark, Dracula, Nord, Gruvbox, Solarized, Agnoster, Neon, Mono and Minimal, each with a variant tuned for light terminals.
• A context mood word. Optionally name how full the context window is, Smart → Coasting → Foggy → Cooked → Dumb, tinted like the bar, so you can read it at a glance.
• No Nerd Font required. Nerd Font arrows and icons by default, or switch to plain Unicode or pure ASCII glyphs that render in any terminal.
• Every color is editable. Use a 256-color palette picker, nudge values with the arrow keys, or type a hex code such as #5e81ac.
• Readable by construction. A test checks every built-in theme against the WCAG contrast minimum for UI text (3:1). The color editor warns you when your own choice becomes hard to read.
• Your own schemes. Save a look, then export it to a file and share it. Imports are validated strictly, so a shared file can't inject shell code into your statusline.
• Safe to experiment. Every change can be reset per field, per segment or all at once. You can exit without saving, and your previous statusline is backed up on install.
• Adapts to split panes. The directory segment shortens itself when the terminal gets narrow.
• No runtime dependencies. The designer uses only the Python standard library. The generated statusline needs just bash, jq and git.

Themes

Every row shows a clean repo at 25% context above a repo with uncommitted changes, max effort and 90% context. On terminals with 24-bit color the context bar is a smooth green → yellow → red gradient. Otherwise it falls back to three color steps.

Quick start

Install it as a standalone command with pipx or uv. Both keep it in its own environment:

pipx install claude-code-statusline-designer
# or
uv tool install claude-code-statusline-designer

Then open the designer:

claude-style

To try it without installing anything, run uvx --from claude-code-statusline-designer claude-style. To work on the code, see Development.

In the designer, pick a theme with ←/→ and toggle the segments you want. Then choose Install. Open a new Claude Code session to see your statusline. Run claude-style again any time to change it.

Updating

Upgrade the package with the tool you installed it with:

pipx upgrade claude-code-statusline-designer
# or
uv tool upgrade claude-code-statusline-designer

Then regenerate your statusline:

claude-style install

The installed statusline is a plain script file, so upgrading the package alone doesn't change it. Re-running install applies new features and fixes to it and keeps your current look. Your settings and saved schemes in ~/.config/claude-style/ are kept across upgrades. Check the installed version with claude-style --version.

Uninstalling

1. Remove the statusline from Claude Code. Do this first, while the command still exists:

   claude-style uninstall
   

   This removes the statusLine entry from ~/.claude/settings.json. If you had your own statusline script before, it also puts that script back. Open a new Claude Code session to see the default status bar again.

2. Remove the package:

   pipx uninstall claude-code-statusline-designer
   # or
   uv tool uninstall claude-code-statusline-designer
   

3. Optionally, remove the leftover files. Nothing runs them any more, but they stay on disk until you delete them:

   Path	What it is
   ~/.config/claude-style/	Your settings and saved schemes (schemes/)
   ~/.claude/statusline-command.sh	The generated statusline script, or your own restored script
   ~/.claude/statusline-command.sh.bak	Backup of the script you had before the first install

   Export any scheme you want to keep before deleting the config folder: claude-style scheme export <name> -o <name>.json.

The designer

Colors you changed are marked • along with their original value (was 24). The scheme shows as ● unsaved (from nord) until you save it. Switching themes asks for a second key press before it discards your edits. Reset to '…' returns everything to the theme you started from, and Exit without saving leaves your configuration untouched. The menu scrolls, so it also works in a short split pane.

If the terminal can't run the full-screen UI (for example over a pipe or on a dumb terminal), the designer falls back to a numbered menu with the same features. You can also force it with claude-style menu --classic.

Command line

Everything in the designer is also scriptable:

The Makefile wraps the common ones: make menu, make preview, make reinstall, make uninstall.

Segments

All values come from the JSON that Claude Code passes to the statusline script.

Your own schemes

A scheme is a complete look: colors, visible segments and separator style. Saved schemes live in ~/.config/claude-style/schemes/ and appear alongside the built-in themes everywhere. An exported scheme is a small JSON file you can share:

{ "format": "claude-style-scheme", "version": 1, "name": "mine", "config": { … } }

Imports are validated before anything is written. Scheme values end up inside a shell script that runs on every prompt, so the designer is strict:

• Every color must be an integer from 0 to 255.
• Every option must have its expected type.
• Names may contain only letters, digits, - and _.
• Unknown keys are dropped.
• Files over 64 KiB are refused.

A rejected file is reported with the offending field. The same validation runs whenever the statusline is generated, which protects a hand-edited config.json too.

Configuration

Your selections are stored in ~/.config/claude-style/config.json. The designer and the CLI cover everything, but a few options exist only in the file:

How it works

The designer renders your configuration into a self-contained bash script at ~/.claude/statusline-command.sh. It then registers the script under statusLine in ~/.claude/settings.json. Claude Code runs the script with a JSON description of the session on stdin. The script reads it with jq, checks the repository with git --no-optional-locks, and prints ANSI-colored segments.

The designer's preview runs that same script against sample sessions. These run in a throwaway home directory with two tiny git repositories, one clean and one with uncommitted changes. That way the git segment shows its colors even if your own directories are not repositories.

install backs up an existing script to statusline-command.sh.bak, and uninstall restores it.

Requirements

• Designer: Python 3.9 or newer on Linux or macOS. It uses curses from the standard library.
• Statusline: bash, jq and git on your PATH.
• Font: a Nerd Font for the default powerline arrows and git icon. Without one, run claude-style glyphs unicode (or ascii), or pick Glyphs in the designer.

Troubleshooting

Development

git clone https://github.com/aleslanger/claude-code-statusline-designer.git
cd claude-code-statusline-designer
pip install -e ".[dev]"   # editable install + pytest, pytest-cov, ruff, pyte
make test                 # full suite with coverage
make lint                 # ruff
make docs                 # regenerate the screenshots in docs/ (needs Chromium for the PNGs)
make dist                 # build the sdist and wheel into dist/ and check them

The suite includes end-to-end tests of the designer. They drive the real curses UI in a pseudo-terminal, rebuild the screen with the pyte terminal emulator, and assert on what a user would see: characters and their colors. Other tests enforce the contrast rules for every theme, the import validation, and regressions for past rendering bugs.

Releasing

Releases go to PyPI from GitHub Actions through Trusted Publishing, so no API token is stored anywhere.

One-time setup:

1. On PyPI, go to Account settings → Publishing and add a pending trusted publisher with these values:
   • project: claude-code-statusline-designer
   • owner: aleslanger
   • repository: claude-code-statusline-designer
   • workflow: release.yml
   • environment: pypi
2. In the GitHub repository settings, create an environment named pypi. Add a required reviewer if you want to approve each upload.

For each release:

1. Bump version in pyproject.toml, then commit and push.
2. Publish a GitHub Release tagged vX.Y.Z with the same version. The Release workflow checks that the tag matches, runs the tests, builds, and uploads to PyPI.

The images in this README are generated from real output by scripts/make_screenshots.py. It uses a placeholder dev@workstation identity, so no personal user or host names end up in the repository.

Acknowledgements

Cost and duration tracking, and hiding empty values, were inspired by other Claude Code statusline projects, notably those by kcchien, rz1989s and ilia-pluzhnikov. The context mood word and its default labels and thresholds come from Dumbometer by Maximo Correa Rosas (MIT). The idea to add it, the extra themes and a no-Nerd-Font glyph mode were prompted by yet-another-statusline. Theme palettes follow Catppuccin, Tokyo Night, One Dark, Dracula, Nord, Gruvbox and Solarized, mapped to the xterm 256-color palette.

License

MIT © 2026 Aleš Langer