skill-statusline

skill-statusline

Rich, themeable statusline for Claude Code with accurate context tracking, 5 color themes, 3 layout modes, and zero dependencies.

Install

npx skill-statusline install

Or install globally:

npm install -g skill-statusline
ccsl install

The installer walks you through choosing a theme and layout. Use --quick to skip the wizard and use defaults.

Layouts

Compact (2 rows)

 Opus 4.6         │ Downloads/Project      │ 47% $1.23
 Context: ████████████████████░░░░░░░░░░░░░░░░░░░░ 47%

Standard (4 rows — default)

 Skill: Edit                      │  GitHub: user/repo/main+~
 Model: Opus 4.6                  │  Dir: Downloads/Project
 Tokens: 85k + 12k                │  Cost: $1.23
 Context: ████████████████████░░░░░░░░░░░░░░░░░░░░ 46%

Full (6 rows)

 Skill: Edit                      │  GitHub: user/repo/main+~
 Model: Opus 4.6                  │  Dir: Downloads/Project
 Window: 85k + 12k                │  Cost: $1.23 ($0.12/m)
 Session: 125k + 34k              │  +156/-23  12m34s
 Cache: W:5k R:2k                 │  NORMAL @code-reviewer
 Context: ████████████████████░░░░░░░░░░░░░░░░░░░░ 46% 54% left

Themes

Theme	Palette
default	Classic purple/pink/cyan
nord	Arctic, blue-tinted
tokyo-night	Vibrant neon
catppuccin	Warm pastels (Mocha)
gruvbox	Retro groovy

ccsl theme set nord

Fields

Field	Color	Description
Skill	Pink	Last tool used (Read, Write, Edit, Terminal, Agent...)
Model	Purple	Active model name + version
GitHub	White	user/repo/branch with + staged ~ unstaged indicators
Dir	Cyan	Last 3 path segments of working directory
Tokens	Yellow	Current context window: input + output
Cost	Green	Session cost in USD
Context	Adaptive	40-char bar — white <=40%, orange 41-75%, red 76-90%, deep red >90%
Session	Dim	Cumulative tokens across all turns (full layout)
Duration	Dim	Session elapsed time (full layout)
Lines	Dim	+added/-removed (full layout)
Cache	Blue	Write/Read cache token counts (full layout)
Vim	Teal	NORMAL/INSERT mode when vim mode is on (full layout)
Agent	Blue	@agent-name when running with --agent (full layout)

Accurate Context Tracking

v2 computes context percentage from actual token counts (current_usage.input_tokens + cache_creation + cache_read) divided by context_window_size, instead of relying on the pre-calculated used_percentage which can lag behind. This fixes the v1 bug where the bar showed 77% while real usage was 92%.

Compaction warnings appear at configurable thresholds:

• 85%+: Shows remaining percentage (15% left)
• 95%+: Shows COMPACTING warning

CLI Commands

ccsl install              Install with theme/layout wizard
ccsl install --quick      Install with defaults
ccsl uninstall            Remove statusline
ccsl update               Update scripts (preserves config)

ccsl theme                List themes
ccsl theme set <name>     Set active theme
ccsl layout               List layouts
ccsl layout set <name>    Set active layout

ccsl preview              Preview with sample data
ccsl preview --theme x    Preview a specific theme
ccsl preview --layout x   Preview a specific layout

ccsl config               Show current config
ccsl config set k v       Set config option
ccsl doctor               Run diagnostics + benchmark
ccsl version              Show version

Config Options

Stored in ~/.claude/statusline-config.json:

Option	Default	Description
compaction_warning_threshold	85	% at which to show remaining context warning
bar_width	40	Width of context bar in characters
cache_ttl_seconds	5	How long to cache git/transcript results
show_burn_rate	false	Show $/min burn rate (full layout)
show_vim_mode	true	Show vim mode indicator
show_agent_name	true	Show --agent name

Architecture

Pure bash at runtime — zero dependencies. Node.js CLI is only for installation.

~/.claude/
  statusline-command.sh           # Entry point (called by Claude Code)
  statusline/
    core.sh                       # Engine: parse JSON, compute fields, render
    json-parser.sh                # Nested JSON extraction (no jq)
    helpers.sh                    # Utilities + filesystem caching
    themes/{default,nord,...}.sh  # Color palettes
    layouts/{compact,...}.sh      # Render functions
  statusline-config.json          # User preferences

Performance: <50ms with caching, <100ms cold. Git and transcript reads are cached with configurable TTL.

Terminal width is auto-detected — layouts gracefully degrade on narrow terminals.

Requirements

• Bash (Git Bash on Windows, or any Unix shell)
• Git (for GitHub field)
• Node.js >=16 (for installer only)
• Works on Windows, macOS, Linux

Part of the Thinqmesh Skills Ecosystem

This statusline is also bundled with codebase-context-skill.

npx codebase-context-skill init

License

MIT — Thinqmesh Technologies