A configurable status bar for Claude Code that shows model, context, git state, context-window headroom, reasoning effort, and time in a persistent visual segment bar.
The layout is FE:MODEL · CONTEXT · GIT · CTX · EFFORT · TIME. Segment colors shift with state: git turns amber when dirty, CTX and EFF warm up (green → amber → red) as you approach a limit.
- Model segment — active model short name (
SNT/OPS/HKU) plus a+1Mflag for 1M-context models. The label before the colon defaults toCLAUDEbut can be driven per-session (see Frontend label). - Context segment — a mapped host alias, or an active working path, falling back to
LOCAL. - Git segment — branch name (truncated to 12 chars), dirty indicator
*(amber), ahead/behind counts in debug mode. - CTX segment — approximate headroom before auto-compact (
CTX→N%). See Context window. - Effort segment — current reasoning effort (
EFF:L/M/H/XH/MAX), shown only when the model supports it. - Time segment — current
HH:MMin ops/debug modes. - Three styles —
blend(default, ▌ half-block color fusion),flat(spaced blocks),powerline(▶ arrows). No Nerd Font required for any style. - Three modes —
focus(minimal),ops(default),debug(+ CWD).
- Bash 4+ (macOS ships Bash 3 — install via
brew install bashor use the systemsh) jq— for parsing Claude Code's JSON inputgit— for branch/dirty detection- Claude Code with statusLine support
git clone https://github.com/clouitreee/claude-statusline.git
cd claude-statusline
bash install.shThe installer:
- Copies
statusline.shto~/.claude/statusline.sh - Patches
~/.claude/settings.jsonwith the statusLine command - Backs up any existing files before overwriting
cp statusline.sh ~/.claude/statusline.sh
chmod +x ~/.claude/statusline.shThen add to ~/.claude/settings.json:
{
"statusLine": {
"type": "command",
"command": "bash ~/.claude/statusline.sh"
}
}All configuration is done via environment variables — no config files, no edits to the script.
Add these to your shell profile (~/.zshrc, ~/.bashrc, etc.):
export CLAUDE_SL_STYLE=flat # blend (default) | flat | powerline
export CLAUDE_STATUSLINE_MODE=focus # focus | ops (default) | debug| Mode | Segments shown |
|---|---|
focus |
FE:MODEL, CONTEXT, GIT, CTX, EFFORT |
ops |
FE:MODEL, CONTEXT, GIT, CTX, EFFORT, TIME |
debug |
FE:MODEL, CONTEXT, GIT, CTX, EFFORT, TIME, CWD, git ahead/behind |
Map your server hostnames to short aliases. The matched alias appears in the context segment, so a Claude Code session running over SSH on a known host is recognizable at a glance.
# Single server
export STATUSLINE_HOST_MAP="myserver=PROD"
# Multiple servers
export STATUSLINE_HOST_MAP="web-01=PROD db-01=PROD devbox=DEV staging=STAGE"Without any mapping, hosts show as LOCAL.
When the host is LOCAL, the context segment can show a short label read from a per-session file: ~/.claude/.active_path-<session_id> (whitespace-trimmed), where <session_id> is the session_id field Claude Code passes on stdin — stable and unique for the lifetime of a session. This is meant to be written by a hook — for example a PreToolUse hook that records which project or area the session is currently working in. A ready-to-use example hook is in examples/track-active-path.sh.
If no session-scoped file exists yet, the statusline falls back to the legacy shared ~/.claude/.active_path (pre-session_id versions of this tool); if neither exists, the segment shows LOCAL.
# example: a hook writes the current area into a file scoped to its own session
SESSION_ID=$(echo "$HOOK_INPUT" | jq -r '.session_id')
echo "billing-api" > ~/.claude/.active_path-"$SESSION_ID"Why per-session, not one shared file: a single
~/.claude/.active_pathis shared by every Claude Code session open at once. APreToolUsehook fires per-session, so with a shared file, a tool call in one terminal tab silently overwrites what every other open session's statusline displays — the label you see can belong to a completely different project. Namespacing bysession_idisolates each session's state; seeexamples/track-active-path.shfor the reference implementation, including an opportunistic cleanup pass for files left behind by closed sessions.
The CTX segment approximates Claude Code's "% until auto-compact" badge. Claude Code does not expose that exact number to the statusline, so it is derived from context_window.remaining_percentage minus a reserved buffer (the output reservation plus safety margin Claude Code keeps before it compacts):
CTX→N% = remaining_percentage − STATUSLINE_COMPACT_RESERVE
export STATUSLINE_COMPACT_RESERVE=16 # percentage points (default: 16)- Colors: green at
≥25, amber at10–24, red below10. - Set
STATUSLINE_COMPACT_RESERVE=0to show the true free-context percentage instead of the countdown. - This is an approximation. The real auto-compact threshold is internal to Claude Code, and the buffer expressed in percentage points shifts if the context window size changes (200k vs 1M), since the underlying reservation is a fixed token count. Recalibrate the reserve for the window size you actually run.
The EFF segment is automatic and needs no configuration. It reads the live effort level from the statusline JSON (effort.level), falling back to effortLevel in ~/.claude/settings.json. It is hidden for models that do not support the effort parameter.
The label before the model name (CLAUDE:OPS) defaults to CLAUDE. Three ways to set it, checked in this order:
-
CLAUDE_LAUNCH_ALIASenvironment variable — set by the shell function that launches Claude Code, inherited per-process. Recommended when you run more than one launch alias concurrently (e.g. a plainclaudeand anops/clobs-style alias in different tabs): each session gets its own value, correctly isolated, no shared state.# in a shell wrapper function, before exec'ing claude ops() { export CLAUDE_LAUNCH_ALIAS="ops" command claude "$@" }
-
~/.claude/.launch_context(whitespace-trimmed, uppercased) — fallback for callers that can't set an env var before launch:echo "ops" > ~/.claude/.launch_context # shows as: OPS:OPS
⚠️ Unlike active-path tracking above, this file cannot be namespaced bysession_id— a launch alias is chosen by the shell before Claude Code starts and is assigned a session ID, so no session-scoped key exists yet at that point. The file is shared by every concurrently open session: whichever alias launched most recently wins and relabels every other open session's statusline until it's relaunched. If you only ever run one launch alias at a time, this is harmless; if you regularly run several at once, useCLAUDE_LAUNCH_ALIASinstead. -
STATUSLINE_FE_NAMEenvironment variable — static default used only when neither of the above is set.export STATUSLINE_FE_NAME="ACME" # shows as: ACME:OPS
# ~/.zshrc
export STATUSLINE_HOST_MAP="web-01=PROD web-02=PROD db-primary=DB staging=STAGE"
export CLAUDE_SL_STYLE=powerlineResult on web-01: CLAUDE:SNT PROD main CTX→48% EFF:M 09:15
# warn earlier — treat a bigger slice as reserved
export STATUSLINE_COMPACT_RESERVE=22export CLAUDE_STATUSLINE_MODE=focusResult: CLAUDE:SNT LOCAL main CTX→62% EFF:H
The examples/ directory contains a fuller, self-contained variant you can adopt or borrow from:
| File | Description |
|---|---|
examples/msp.sh |
An independent MSP / multi-server variant with its own segment set (server aliases, vault-area detection, goal progress from a markdown file, a LIVE/SAFE state segment, TTL-cached file reads). It is a separate example layout, not a drop-in mirror of the main statusline.sh. |
examples/track-active-path.sh |
Reference PreToolUse hook for the Active path segment — writes a per-session_id file so concurrent sessions don't overwrite each other's label. |
To use an example as your statusline:
cp examples/msp.sh ~/.claude/statusline.shThe script is designed to be easy to fork. Key extension points:
Add a custom segment — append it wherever you like after the segment arrays are initialized:
add_seg "MYDATA" $C_BLUE $C_WHITEadd_seg TEXT BG_COLOR_256 FG_COLOR_256 pushes a segment with a 256-color background and foreground; the renderer handles the blend/flat/powerline transitions for you.
Read a value from the JSON input — the full Claude Code statusline payload is in $INPUT:
SESSION=$(printf '%s' "$INPUT" | jq -r '.session_name // empty')
[ -n "$SESSION" ] && add_seg "$SESSION" $C_DARK $C_GRAYStatusline not appearing:
- Check
~/.claude/settings.jsoncontains thestatusLinekey - Run
bash ~/.claude/statusline.sh </dev/nullmanually — should output a colored line - Verify
jqis installed:jq --version
CTX number doesn't match the "% until auto-compact" badge:
- Expected. The badge is internal Claude Code state and is not exposed to the statusline;
CTXapproximates it (see Context window). TuneSTATUSLINE_COMPACT_RESERVEfor your window size.
Colors look wrong:
- Your terminal must support 256 colors:
echo $TERMshould showxterm-256coloror similar - If using tmux, add
set -g default-terminal "screen-256color"to~/.tmux.conf
Powerline arrows look broken:
- The
▶character (U+25B6) is a standard Unicode block — no Nerd Font needed - If it renders as a box, your terminal font may lack this codepoint; switch to
flatstyle
Slow statusline:
- The git operations (
git status,git branch) run on every render - For large repos, consider setting
CLAUDE_STATUSLINE_MODE=focus - The
examples/msp.shvariant uses a TTL cache for expensive file reads
MIT