smoothline

Smooth, gradient statusline for Claude Code — context window + Pro/Max 5h/7d rate-limit bars (Windows / macOS / Linux)

English | 한국어

A drop-in statusline for Claude Code that ships the same look across Windows, macOS, and Linux.

The core renderer (statusline.py) is identical on every OS. Only the installer branches per OS, and ~/.claude/settings.json's statusLine.command is wired to the right entry point automatically.

Preview

youja@HOSTNAME ~/workspace │ ⎇ main │ Claude Opus 4.7 │ ctx [████▏      ] 42% │ 5h [██▏     ] 28% ↻3h11m │ 7d [▉       ] 12% ↻4d23h

• user@host + current directory (home shown as ~)
• git branch (when present)
• model name
• ctx — context window usage of the current session (10-cell bar)
• 5h — Claude Pro/Max 5-hour rolling window usage + time until reset ↻Xh Ym (8-cell bar)
• 7d — Claude Pro/Max 7-day rolling window usage + time until reset ↻Xd (8-cell bar)

All bars use 1/8-cell smooth Unicode glyphs and a green→yellow→red gradient that follows the percentage.

When 5h / 7d show up: only for Claude.ai Pro/Max subscribers. After the first API response, the statusline JSON includes rate_limits.five_hour.* / rate_limits.seven_day.* (per Anthropic's official statusline schema). For API-key users, or before the first message, those two chunks are hidden automatically.

The renderer parses stdin JSON once and reads .git/HEAD directly — no git subprocess per prompt.

0. Prerequisites

• Python 3.x — required to run statusline.py. Any Python build works.
  • Windows: python / python.exe must be reachable on PATH, or set the absolute path inside statusline.cmd
  • macOS/Linux: python3 or python must be on PATH (install.sh discovers this automatically)
• A terminal with truecolor (24-bit) ANSI support so the gradient renders. Windows Terminal / iTerm2 / recent GNOME Terminal / etc. all qualify.

Verify Python:

# Windows (PowerShell)
where.exe python
# macOS / Linux
which python3 || which python

1. The three files

Destination: %USERPROFILE%\.claude\ (e.g. C:\Users\<USERNAME>\.claude\) on Windows, ~/.claude/ elsewhere.

1-A. statusline.cmd (Windows only — generated by the installer)

The installer writes this file at install time, baking in the absolute path to the Python it found on PATH. You normally don't touch it. A typical generated copy:

@echo off
"C:\Users\<USERNAME>\AppData\Local\Programs\Python\Python312\python.exe" "C:\Users\<USERNAME>\.claude\statusline.py"

If python is not on PATH at install time, the installer falls back to the literal python and warns you. Once Python is installed and on PATH, just re-run the installer.

1-B. statusline.py

Use the statusline.py shipped in this package as-is. The full source (Pro/Max rate_limits rendering included) lives in the file — the installer wires up the canonical copy.

Encoding note: statusline.py must be saved as UTF-8 (no BOM). PowerShell's default for Set-Content / Out-File is UTF-16 LE, which corrupts it. The "One-shot install" section below handles this safely.

1-C. statusline-command.ps1 (optional)

A pure-PowerShell fallback. No colors, no smooth bars, ASCII only. You don't normally need it — keep it as a backup for machines without Python installed.

2. Registering in settings.json (the installer does this for you)

The installer adds/merges the statusLine key into ~/.claude/settings.json, preserving any other keys.

If you wire it up by hand, here is what the OS-specific entry looks like:

Windows — %USERPROFILE%\.claude\settings.json

{
  "statusLine": {
    "type": "command",
    "command": "C:\\Users\\<USERNAME>\\.claude\\statusline.cmd",
    "padding": 0
  }
}

macOS / Linux — ~/.claude/settings.json

{
  "statusLine": {
    "type": "command",
    "command": "/Users/<USERNAME>/.claude/statusline.py",
    "padding": 0
  }
}

Replace <USERNAME>. On macOS/Linux, statusline.py is chmod +x'd and has a #!/usr/bin/env python3 shebang, so it runs directly — no wrapper needed.

3. One-shot install

3-A. One-liner (fastest)

The installer pulls everything it needs straight from GitHub, drops it under ~/.claude/, and patches settings.json.

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/youja2014/smoothline/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/youja2014/smoothline/main/install.ps1 | iex

Windows (cmd)

curl -fsSL https://raw.githubusercontent.com/youja2014/smoothline/main/install.cmd -o install.cmd && install.cmd && del install.cmd

3-B. git clone / zip install

Grab the sources and run the installer in local mode. Sibling files are copied verbatim, so this works fully offline.

Windows

install.cmd       :: double-click works

or PowerShell:

.\install.ps1

macOS / Linux

bash install.sh
# or
chmod +x install.sh && ./install.sh

Inside Claude Code (macOS/Linux)

On a machine that already has Claude Code, cd into the unpacked folder and just say:

"Run install.sh in this folder to set up the statusline"

What every installer does

1. Source the assets — if statusline.py is a sibling, copy it (local mode); otherwise download from the GitHub raw URL (one-liner mode)
2. Auto-detect Python — Windows checks python on PATH, Unix tries python3 then python
3. On Windows, regenerate statusline.cmd with the detected Python's absolute path (so the one-liner install just works without editing)
4. Add/replace only the statusLine key in ~/.claude/settings.json (other keys preserved)
5. Run the statusline once with a dummy JSON payload and print the output

3-C. Install via PyPI

If you'd rather grab smoothline as a regular Python tool — no installer, no file copies under ~/.claude:

uv tool install smoothline

or

pip install --user smoothline

Either way you get a smoothline executable on PATH. Wire it into ~/.claude/settings.json directly:

{
  "statusLine": {
    "type": "command",
    "command": "smoothline",
    "padding": 0
  }
}

Restart Claude Code. The PyPI binary is the entry point — no separate ~/.claude/statusline.py needed.

3-D. Install via Homebrew (macOS / Linux)

brew install youja2014/tap/smoothline

or, the two-step form:

brew tap youja2014/tap
brew install smoothline

Homebrew drops smoothline into a managed virtualenv. The settings.json registration is identical to 3-C:

{
  "statusLine": {
    "type": "command",
    "command": "smoothline",
    "padding": 0
  }
}

4. Verifying

The installer prints sample output, so usually you don't need to do anything. To re-run the check:

Windows (PowerShell)

$json = '{"model":{"display_name":"Claude Opus 4.7"},"workspace":{"current_dir":"D:\\workspace"},"context_window":{"used_percentage":42},"rate_limits":{"five_hour":{"used_percentage":28,"resets_at":2000000000},"seven_day":{"used_percentage":12,"resets_at":2000300000}}}'
$tmp = [System.IO.Path]::GetTempFileName()
[System.IO.File]::WriteAllText($tmp, $json, (New-Object System.Text.UTF8Encoding $false))
& cmd /c "type `"$tmp`" | `"$env:USERPROFILE\.claude\statusline.cmd`""
Remove-Item $tmp

Piping '{...}' | statusline.cmd directly in PowerShell encodes as UTF-16 LE and breaks Python's JSON parser. Going through a tempfile is the safe path.

macOS / Linux (bash)

NOW=$(date +%s)
echo '{"model":{"display_name":"Claude Opus 4.7"},"workspace":{"current_dir":"'"$HOME"'"},"context_window":{"used_percentage":42},"rate_limits":{"five_hour":{"used_percentage":28,"resets_at":'$((NOW+11600))'},"seven_day":{"used_percentage":12,"resets_at":'$((NOW+424600))'}}}' \
  | "$HOME/.claude/statusline.py"

You should see two colored lines. After that, restart Claude Code — the new statusline shows up immediately.

5. Troubleshooting

6. Customization

• Bar width: the 4th argument to each render_usage(...) call inside main() (ctx is 10, 5h/7d are 8)
• Colors: GRAY / BLUE / PURPLE / ORANGE / SEP RGB tuples
• Gradient breakpoints: green / yellow / red inside gradient_color()
• Display order: reorder how line1 / line2 chunks are appended
• Hide the 5h / 7d chunks: comment out their render_usage(...) calls
• Drop the reset-time tail: pass None as the resets_at argument to render_usage()

License

MIT