Metadata-Version: 2.4
Name: claude-code-statusline-designer
Version: 0.2.0
Summary: Design, preview and install a themed statusline for Claude Code
Author: Aleš Langer
License-Expression: MIT
Project-URL: Homepage, https://github.com/aleslanger/claude-code-statusline-designer
Project-URL: Issues, https://github.com/aleslanger/claude-code-statusline-designer/issues
Project-URL: Changelog, https://github.com/aleslanger/claude-code-statusline-designer/releases
Keywords: claude-code,statusline,powerline,terminal,theme,curses
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Terminals
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pyte>=0.8; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

<div align="center">

# Claude Code Statusline Designer

**A statusline designer for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).**
Pick a theme, tune every color with a live preview, and install it in one keystroke.

[![PyPI](https://img.shields.io/pypi/v/claude-code-statusline-designer)](https://pypi.org/project/claude-code-statusline-designer/)
[![CI](https://github.com/aleslanger/claude-code-statusline-designer/actions/workflows/ci.yml/badge.svg)](https://github.com/aleslanger/claude-code-statusline-designer/actions/workflows/ci.yml)
![License: MIT](https://img.shields.io/badge/license-MIT-blue)
![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-3776ab)
![Runtime dependencies: none](https://img.shields.io/badge/runtime%20deps-none-2ea44f)
![Themes: 22](https://img.shields.io/badge/themes-11%20dark%20%2B%2011%20light-8a63d2)
![Contrast: WCAG AA](https://img.shields.io/badge/contrast-WCAG%20AA%20checked-0a7bbb)

<img src="https://raw.githubusercontent.com/aleslanger/claude-code-statusline-designer/master/docs/menu.png" alt="The designer: theme and segment settings above a live preview of two sample statuslines" width="760">

</div>

---

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

<img src="https://raw.githubusercontent.com/aleslanger/claude-code-statusline-designer/master/docs/themes-dark.png" alt="The eleven dark themes, each showing a clean and a busy sample statusline" width="820">

<img src="https://raw.githubusercontent.com/aleslanger/claude-code-statusline-designer/master/docs/themes-light.png" alt="The eleven light themes on a white terminal background" width="820">

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](https://pipx.pypa.io/) or
[uv](https://docs.astral.sh/uv/). Both keep it in its own environment:

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

Then open the designer:

```bash
claude-style
```

To try it without installing anything, run
`uvx --from claude-code-statusline-designer claude-style`.
To work on the code, see [Development](#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:

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

Then regenerate your statusline:

```bash
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:

   ```bash
   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:**

   ```bash
   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

<img src="https://raw.githubusercontent.com/aleslanger/claude-code-statusline-designer/master/docs/palette.png" alt="The 256-color palette picker, previewing the hovered color in the live statusline below it" width="760">

| Key | Where | Action |
|-----|-------|--------|
| `↑` `↓` | everywhere | Move between rows or fields |
| `←` `→` | Scheme / Separator / Glyphs | Cycle themes (each dark theme is followed by its light variant), separator style or glyph set |
| `space` / `enter` | segment row | Turn a segment on or off |
| `c` | segment row | Open the segment's color editor |
| `←` `→` / `PgUp` `PgDn` | color editor | Nudge the color code by 1 / 16 |
| `enter` | color editor | Open the 256-color palette; the preview follows the hovered color |
| `#` | color editor, palette | Type a hex color (`#5e81ac`) or a code (`0`–`255`) |
| `r` / `R` | color editor | Reset this field / every color of the segment |
| `s` | menu | Save the current look as your own scheme |
| `v` | menu | Full-screen preview in your terminal's exact colors |
| `q` | menu | Save selections and quit |

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:

| Command | Description |
|---------|-------------|
| `claude-style` | Open the designer |
| `claude-style install` | Write `~/.claude/statusline-command.sh` and register it in `~/.claude/settings.json` |
| `claude-style uninstall` | Remove the `statusLine` entry and restore your previous script |
| `claude-style preview` | Render the sample statuslines in this terminal |
| `claude-style presets` | List built-in themes and your schemes |
| `claude-style preset <name>` | Switch theme (`nord`, `gruvbox-light`, one of yours, …) |
| `claude-style toggle <segment> on\|off` | Show or hide a segment (`context-word` toggles the mood word) |
| `claude-style glyphs nerdfont\|unicode\|ascii` | Glyph set: Nerd Font icons, plain Unicode, or ASCII only |
| `claude-style separator powerline\|plain` | Powerline arrows or plain `\|` separators |
| `claude-style color list` | Every editable color, with its code and hex value |
| `claude-style color set <segment> <field> <color>` | Set a color: `61` or `'#5e81ac'` |
| `claude-style color reset <segment> [field]` | Reset one field, or the whole segment |
| `claude-style reset` | Undo all changes and return to the theme you started from |
| `claude-style scheme save <name>` | Save the current look as a scheme |
| `claude-style scheme export [name] [-o file]` | Export a scheme (default: current look, to stdout) |
| `claude-style scheme import <file\|-> [--name n] [--apply]` | Import a shared scheme |
| `claude-style scheme delete <name>` | Delete one of your schemes |
| `claude-style show` | Print the current configuration as JSON |

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

## Segments

| Segment | Shows | Default |
|---------|-------|---------|
| `user_host` | `user@host` | on |
| `dir` | Working directory, shortened in narrow terminals | on |
| `git` | Branch; the color and a `±` mark flag uncommitted changes | on |
| `model` | Model name, e.g. `Opus 5` | on |
| `effort` | Effort level, colored from `low` (green) to `max` | on |
| `context` | Context-window usage as a 10-block bar or a percentage, optionally with a mood word (`Smart` … `Dumb`) | on |
| `output_style` | Output style, shown only when it isn't `default` | off |
| `cost` | Session cost in USD; turns red past a threshold (default $5) | off |
| `duration` | Session duration, e.g. `12m34s` | off |

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:

```json
{ "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:

| Key | Default | Meaning |
|-----|---------|---------|
| `segments.dir.responsive` | `true` | Shorten the path when the terminal is narrow |
| `segments.dir.narrow_cols` / `medium_cols` | `60` / `100` | Below `narrow_cols`: basename only. Below `medium_cols`: `…/last/parts` |
| `segments.dir.medium_segments` | `2` | Number of path parts kept at medium width |
| `segments.context.style` | `"bar"` | `"bar"` or `"percent"` |
| `segments.context.true_color` | `true` | Use the 24-bit gradient when `COLORTERM` is `truecolor` or `24bit` |
| `segments.context.gradient_peak` | `255` | Brightest gradient channel (`100`–`255`). Light themes use about `175` |
| `segments.context.state_labels` | `Smart, Coasting, Foggy, Cooked, Dumb` | The five mood words (letters, digits, spaces, `.` `_` `-`; up to 16 characters) |
| `segments.context.state_thresholds` | `25, 50, 70, 90` | Usage % at which words 2–5 start (four ascending values, 1–99) |
| `segments.cost.warn_threshold_usd` | `5.0` | Cost above which the segment turns red |
| `segments.cost.hide_zero`, `segments.duration.hide_zero` | `true` | Hide the segment while its value is zero |

## 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](https://www.nerdfonts.com/) for the default powerline
  arrows and git icon. Without one, run `claude-style glyphs unicode` (or
  `ascii`), or pick **Glyphs** in the designer.

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| Boxes instead of arrows or the git icon | Switch your terminal to a Nerd Font, or run `claude-style glyphs unicode` (or `ascii`) |
| The context bar has three flat colors, not a gradient | Your terminal doesn't advertise 24-bit color. Set `COLORTERM=truecolor` if it supports it |
| Nothing shows up after installing | Start a new Claude Code session and check that `statusLine` exists in `~/.claude/settings.json` |
| Colors look washed out on a white terminal | Pick a `-light` theme; they are tuned for light backgrounds |

## Development

```bash
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](https://github.com/selectel/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](https://docs.pypi.org/trusted-publishers/), 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](https://github.com/kcchien/claude-code-statusline),
[rz1989s](https://github.com/rz1989s/claude-code-statusline) and
[ilia-pluzhnikov](https://github.com/ilia-pluzhnikov/claude-code-statusline).
The context mood word and its default labels and thresholds come from
[Dumbometer](https://github.com/MaximoCorrea1/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](https://github.com/tmck-code/yet-another-statusline).
Theme palettes follow [Catppuccin](https://catppuccin.com/),
[Tokyo Night](https://github.com/folke/tokyonight.nvim),
[One Dark](https://github.com/atom/atom/tree/master/packages/one-dark-syntax),
[Dracula](https://draculatheme.com/), [Nord](https://www.nordtheme.com/),
[Gruvbox](https://github.com/morhetz/gruvbox) and
[Solarized](https://ethanschoonover.com/solarized/), mapped to the xterm
256-color palette.

## License

[MIT](LICENSE) © 2026 Aleš Langer
