Configuration

Configuration file

Persisted to ~/.claude/claude-statusbar.json:

{
  "style": "capsule",
  "theme": "twilight",
  "density": "regular",
  "auto_compact_width": 100,
  "show_weekly": true,
  "show_language": true,
  "show_cost": false,
  "show_balance": true,
  "balance_bar": true,
  "show_cache_age": true,
  "show_project_branch": true,
  "show_party": true,
  "show_todos": true,
  "show_tools": false,
  "show_agents": false,
  "show_duration": false,
  "show_lines": true,
  "show_ahead_behind": false
}

Key	Values	What it does
style	classic / capsule / hairline	Layout
theme	9 themes (see Styles & themes)	Colors
density	compact / regular / cozy	Segment padding (capsule + hairline only)
auto_compact_width	int	Force hairline below this terminal width; 0 = off
show_cost	bool, false	Append $ X.XX session cost (API-equivalent value for subscribers)
show_balance / balance_bar	bool, true	No-quota relay balance as a fuel-gauge bar — auto-hidden if the relay doesn't support it
show_cache_age	bool, true	cache 4m23s prompt-cache countdown (TTL auto-detected 5m/1h)
show_project_branch	bool, true	Second line: project + branch + ● dirty dot
show_ahead_behind	bool, false	↑2↓1 commits ahead/behind on the branch line
show_party	bool, true	AgentParty / Codex bridge line (reads local cache only)
show_todos	bool, true	Activity line: in-progress todo + done/total
show_tools / show_tool_rollup	bool, false	Active tool / completed-tool frequency rollup
show_projection / show_forecast	bool, true	→NN% projection / ⚠ETA at-risk warning chip
show_agents	bool, false	One bottom line per running subagent (Claude Code shows these natively too)
show_duration / show_lines	bool	Session ⏱ duration / +/− lines on the identity line
show_version	bool, true	Faint · vX.Y.Z (+ amber ↑newver when a newer PyPI release exists)
show_mode / mode_gradient	bool, true	⚙ session-mode line + effort-tier gradient tint
show_weekly / show_language	bool	Toggle the 7d bar / language-coach segment
bar_shimmer	bool, false	Experimental twinkling starfield on bars (classic only)
api_mode	auto / on / off	No-quota mode (see No-quota mode); CS_API_MODE env overrides

Full per-key detail is in the segment reference or cs config show. Set with cs config set <key> <value>; cs config reset restores defaults.

Environment variables

Variable	Effect
CLAUDE_STATUSBAR_STYLE=capsule	Render with this style (overrides config file)
CLAUDE_STATUSBAR_THEME=twilight	Render with this theme (overrides config file)
CLAUDE_STATUSBAR_NO_UPDATE=1	Disable automatic update checks
CLAUDE_STATUSBAR_WARNING_THRESHOLD=40	Switch from green to yellow at 40%
CLAUDE_STATUSBAR_CRITICAL_THRESHOLD=85	Switch from yellow to red at 85%
NO_COLOR=1	Disable ANSI colors

CLAUDE_PLAN is still accepted for legacy compatibility, but it no longer changes the rendered status line.

JSON output

Use --json-output if you want a machine-readable payload instead of the formatted status line:

cs --json-output

Usage cheatsheet

cs                              # render the status line (default command)
cs --style capsule              # render with a one-off style
cs --theme twilight             # render with a one-off theme

# Configuration
cs config show                  # show all persistent config
cs config set style hairline    # persist style → ~/.claude/claude-statusbar.json
cs config set theme linen       # persist theme
cs config set show_cost true    # session $ cost segment
cs config set show_cache_age false  # hide prompt-cache age segment
cs config set show_party false  # hide local AgentParty channel/unread line
cs config set show_tools true   # activity line: active tool + completed rollup
cs config set show_agents true  # bottom line(s): running subagents + elapsed
cs config set show_duration true # identity line: ⏱ session duration
cs config set show_lines false  # hide identity-line +added -removed (on by default)
cs config set show_version false  # hide the faint · vX.Y.Z (+ ↑update hint) at line end
cs config set show_mode false    # hide the ⚙ effort/thinking/fast/style line
cs config set mode_gradient false # mode line: plain per-tier colours, no gradient
cs config set show_ahead_behind true  # ↑2↓1 on the project/branch line
cs config set api_mode on        # force no-quota layout (relay/Bedrock/Vertex; default auto)
cs config set bar_shimmer true  # experimental: twinkling starfield on the battery bars
cs config set show_projection false  # hide the →NN% end-of-window projection
cs config set show_forecast false    # hide the ⚠~eta at-risk warning chip
cs config set show_todos false  # hide the todo-progress segment (on by default)
cs config reset                 # wipe config back to defaults

# Discovery
cs styles                       # list available styles
cs themes                       # list available themes
cs preview                      # render every style × theme with YOUR real data
cs preview --theme nord         # filter to one theme
cs preview --style hairline --theme dracula   # one specific combo

# Daemon mode (default since v3.6.0; v3.2 introduced it as opt-in)
cs --setup                      # default: writes `cs render` + starts daemon
cs --setup --inline             # opt out, use legacy inline path
cs daemon start                 # start daemon (manual)
cs daemon stop                  # stop daemon
cs daemon status                # pid + rendered.ansi freshness
cs daemon install               # install LaunchAgent (macOS) / systemd unit (Linux)
cs daemon uninstall             # remove the OS-level service
cs daemon service               # report whether the OS service is registered

# Diagnostics + flags
cs doctor                       # self-diagnostic — paste output in bug reports
cs --json-output                # machine-readable JSON
cs --no-color                   # disable ANSI colors
cs --warning-threshold 40 --critical-threshold 85
cs --no-auto-update             # skip the per-day PyPI version check

--plan still exists for older scripts, but is deprecated and no longer changes the rendered output.