claude-statusline-kit/README.md

[English](#english) | [Deutsch](#deutsch)

---

## English

# Claude Code Statusline Kit

A portable, self-contained kit that installs a custom Claude Code statusline
(built on the [`cship`](https://cship.dev) Starship fork) onto any Windows PC
with a single command.

![Statusline screenshot](docs/statusline_screenshot.png)

### What it installs

| Asset                         | Target location            | Purpose                                   |
| ----------------------------- | -------------------------- | ----------------------------------------- |
| `assets/cship.exe`            | `~/.local/bin/`            | Renders the statusline                    |
| `assets/cship.toml`           | `~/.config/`               | Module config (colors, icons, bars)       |
| `assets/cship-statusline.ps1` | `~/.claude/`               | Wrapper (progress bars, token formatting) |
| `statusLine` block            | `~/.claude/settings.json`  | Wires everything into Claude Code         |

### Requirements

- **PowerShell 7** (`pwsh`). Install: `winget install --id Microsoft.PowerShell -e`
- An **emoji-capable terminal font** so `🤖 ⚡ 🧠 █░` render. **No Nerd Font
  required** — the statusline deliberately uses only standard Unicode (emoji +
  block-drawing chars), never Nerd-Font private-use glyphs. Windows Terminal
  renders them via `Segoe UI Emoji` out of the box. As a safety net the
  installer nevertheless installs a Nerd Font (Hack, ~17 MB) **per-user, no
  admin rights** if none is present — see below.

### Progress bars & color thresholds

The statusline has three progress bars. Each fills from 0–100 % and switches
color at fixed thresholds:

| Bar          | Measures                    | 🔵 blue  | 🟡 yellow | 🔴 bold red |
| ------------ | --------------------------- | -------- | --------- | ----------- |
| 🧠 Context   | context window filled       | `< 20 %` | `≥ 20 %`  | `≥ 40 %`    |
| ⏳ 5h        | 5-hour usage limit used     | `< 40 %` | `≥ 40 %`  | `≥ 70 %`    |
| 📅 7d        | 7-day usage limit used      | `< 40 %` | `≥ 40 %`  | `≥ 70 %`    |

Thresholds are **percentages**, so they stay model-independent. On a 1M-token
context window the 🧠 bar therefore turns yellow at **200k** tokens and red at
**400k**. Colors: blue `#7dcfff`, yellow, bold red.

Where to change them:

- **🧠 Context** — `warn_threshold` / `critical_threshold` in
  `[cship.context_bar]` (`assets/cship.toml`).
- **⏳ 5h / 📅 7d** — the color block in `assets/cship-statusline.ps1`; both
  bars share it, so keep the two thresholds in sync.

### Install on a new PC

```powershell
git clone https://github.com/Andre-Bzk/claude-statusline-kit claude-statusline-kit
cd claude-statusline-kit
.\install.ps1
```

Then restart Claude Code (or start a new session).

The installer is **idempotent** — run it again anytime. It auto-detects the
`pwsh` path on the target machine and merges the `statusLine` block into an
existing `settings.json` **without** overwriting your other settings (a
`.bak` backup is written first).

### Nerd Font (automatic, no admin)

If no Nerd Font is detected, the installer downloads one from
[ryanoasis/nerd-fonts](https://github.com/ryanoasis/nerd-fonts) and installs it
into the **per-user** font store (`%LOCALAPPDATA%\Microsoft\Windows\Fonts` +
`HKCU`), so **no administrator rights** are needed. If a download fails (e.g. no
internet), the step is skipped and the statusline still works via the emoji
fallback. To actually *use* the font, set it as your terminal font and restart
the terminal — the statusline renders correctly either way.

### Options

- `.\install.ps1 -Force` — also overwrite an existing `~/.config/cship.toml`
  (by default an existing config is kept, so local tweaks survive).
- `.\install.ps1 -SkipFont` — skip the Nerd-Font check/install entirely.
- `.\install.ps1 -FontName FiraCode` — install a different Nerd Font
  (default `Hack`; e.g. `FiraCode`, `CascadiaCode`, `JetBrainsMono`).

### Updating the kit

Edit the files under `assets/`, commit, `git push`. On another PC:

```powershell
git pull
.\install.ps1 -Force
```

---

## Deutsch

# Claude Code Statusline Kit

Ein portables, in sich geschlossenes Kit, das eine individuelle Claude-Code-
Statusline (basierend auf dem Starship-Fork [`cship`](https://cship.dev)) mit
einem einzigen Befehl auf jeden Windows-PC installiert.

![Screenshot der Statusline](docs/statusline_screenshot.png)

### Was installiert wird

| Asset                         | Zielort                    | Zweck                                    |
| ----------------------------- | -------------------------- | ---------------------------------------- |
| `assets/cship.exe`            | `~/.local/bin/`            | Rendert die Statusline                   |
| `assets/cship.toml`           | `~/.config/`               | Modul-Konfiguration (Farben, Icons, Bars)|
| `assets/cship-statusline.ps1` | `~/.claude/`               | Wrapper (Progress-Bars, Token-Format)    |
| `statusLine`-Block            | `~/.claude/settings.json`  | Verdrahtet alles in Claude Code          |

### Voraussetzungen

- **PowerShell 7** (`pwsh`). Installation: `winget install --id Microsoft.PowerShell -e`
- Ein **emoji-fähiger Terminal-Font**, damit `🤖 ⚡ 🧠 █░` dargestellt werden.
  **Kein Nerd-Font nötig** — die Statusline nutzt bewusst nur Standard-Unicode
  (Emoji + Block-Zeichen), keine Nerd-Font-Privatzeichen. Windows Terminal
  rendert sie standardmäßig über `Segoe UI Emoji`. Als Sicherheitsnetz
  installiert der Installer dennoch einen Nerd-Font (Hack, ~17 MB) **per-user,
  ohne Admin-Rechte**, falls keiner vorhanden ist — siehe unten.

### Progress-Bars & Farbschwellen

Die Statusline hat drei Progress-Bars. Jeder füllt sich von 0–100 % und wechselt
an festen Schwellen die Farbe:

| Bar          | Misst                          | 🔵 blau  | 🟡 gelb  | 🔴 fett rot |
| ------------ | ------------------------------ | -------- | -------- | ----------- |
| 🧠 Kontext   | Kontextfenster gefüllt         | `< 20 %` | `≥ 20 %` | `≥ 40 %`    |
| ⏳ 5h        | 5-Stunden-Limit ausgelastet    | `< 40 %` | `≥ 40 %` | `≥ 70 %`    |
| 📅 7d        | 7-Tage-Limit ausgelastet       | `< 40 %` | `≥ 40 %` | `≥ 70 %`    |

Die Schwellen sind **Prozentwerte** und damit model-unabhängig. Bei einem
Kontextfenster von 1M Tokens wird der 🧠-Bar deshalb bei **200k** Tokens gelb
und bei **400k** rot. Farben: blau `#7dcfff`, gelb, fett rot.

Wo man sie ändert:

- **🧠 Kontext** — `warn_threshold` / `critical_threshold` in
  `[cship.context_bar]` (`assets/cship.toml`).
- **⏳ 5h / 📅 7d** — der Farbblock in `assets/cship-statusline.ps1`; beide Bars
  teilen ihn sich, also beide Schwellen synchron halten.

### Installation auf einem neuen PC

```powershell
git clone https://github.com/Andre-Bzk/claude-statusline-kit claude-statusline-kit
cd claude-statusline-kit
.\install.ps1
```

Danach Claude Code neu starten (oder eine neue Session öffnen).

Der Installer ist **idempotent** — jederzeit erneut ausführbar. Er erkennt den
`pwsh`-Pfad auf dem Zielrechner automatisch und fügt den `statusLine`-Block in
eine vorhandene `settings.json` ein, **ohne** deine anderen Einstellungen zu
überschreiben (vorher wird ein `.bak`-Backup geschrieben).

### Nerd-Font (automatisch, ohne Admin)

Wird kein Nerd-Font erkannt, lädt der Installer einen von
[ryanoasis/nerd-fonts](https://github.com/ryanoasis/nerd-fonts) und installiert
ihn in den **benutzereigenen** Font-Speicher (`%LOCALAPPDATA%\Microsoft\Windows\Fonts`
+ `HKCU`) — **ohne Administrator-Rechte**. Schlägt der Download fehl (z. B. kein
Internet), wird der Schritt übersprungen und die Statusline funktioniert dank
Emoji-Fallback trotzdem. Um den Font tatsächlich zu *nutzen*, ihn als
Terminal-Font einstellen und das Terminal neu starten — die Statusline wird so
oder so korrekt dargestellt.

### Optionen

- `.\install.ps1 -Force` — überschreibt zusätzlich eine vorhandene
  `~/.config/cship.toml` (standardmäßig wird eine bestehende Config behalten,
  damit lokale Anpassungen erhalten bleiben).
- `.\install.ps1 -SkipFont` — überspringt die Nerd-Font-Prüfung/-Installation.
- `.\install.ps1 -FontName FiraCode` — installiert einen anderen Nerd-Font
  (Standard `Hack`; z. B. `FiraCode`, `CascadiaCode`, `JetBrainsMono`).

### Kit aktualisieren

Dateien unter `assets/` bearbeiten, committen, `git push`. Auf einem anderen PC:

```powershell
git pull
.\install.ps1 -Force
```