ai-statusline

A high-performance, customizable status line for Claude Code CLI.

Built in Rust. Zero runtime dependencies. Sub-millisecond rendering.

[Opus] ▓▓▓▓░░░░░░ 42% | $0.08 | 5m 23s
📁 my-project | 🌿 main +3 ~2 | +156 -23 | v2.1.31

✨ Features:

• 🎨 Interactive TUI configurator — Visual configuration with live preview
• ⚡ 26 customizable widgets — Model, tokens, cost, git status, and more
• 🎭 11 built-in themes — Dracula, Nord, Tokyo Night, Catppuccin, and more
• 🚀 Sub-millisecond rendering — Zero lag, always fresh
• 🔧 Zero dependencies — Single 1MB binary, no Node.js required

Why ai-statusline?

| | ai-statusline | ccstatusline | |---|---|---| | Language | Rust (compiled binary) | TypeScript (bunx/npx) | | Render time | <1ms | ~200ms (npx overhead) | | Binary size | 1.0 MB | N/A (requires Node.js) | | Runtime deps | None | Node.js or Bun | | Data source | Native JSON API (stdin) | Transcript file parsing | | Accuracy | Always correct (official API) | Breaks across models/versions | | Memory | 1.2 MB | ~50 MB (Node.js runtime) | | Widgets | 26 | ~15 | | Config format | TOML (with comments) | JSON |

Quick Start

Install

# npm (downloads platform binary automatically)
npm install -g ai-statusline

# Or direct binary
curl -fsSL https://raw.githubusercontent.com/mstuart/ai-statusline/main/scripts/install.sh | sh

# Or build from source
cargo install --path .

Configure Claude Code

Add to ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "ai-statusline"
  }
}

Restart Claude Code. Done.

Configure Your Status Line

🎨 Interactive TUI (Recommended for Beginners)

The easiest way to customize your status line:

ai-statusline config

The TUI configurator lets you:

• Add/remove widgets — Choose from 26 available widgets with live preview
• Reorder widgets — Use j/k to move widgets up/down
• Switch themes — Browse and preview 11 built-in themes instantly
• Configure powerline — Toggle powerline mode, change separators, enable auto-align
• Manage layouts — Add/remove status lines, adjust flex modes
• Save instantly — Ctrl-S to save, changes apply immediately to Claude Code

⚡ Quick Presets

Apply pre-built layouts instantly:

ai-statusline preset full       # Two-line layout with everything
ai-statusline preset minimal    # Just model + context %
ai-statusline preset powerline  # Full layout with powerline arrows
ai-statusline preset compact    # Single line, compact values

Widgets

26 built-in widgets, all reading from Claude Code's native JSON API:

Core Metrics

| Widget | Type | Description | |--------|------|-------------| | Model | model | Current model name (Opus, Sonnet, etc.) | | Context % | context-percentage | Context window usage with optional progress bar | | Context Length | context-length | Absolute token count (e.g., "42K") | | Tokens In | tokens-input | Input tokens from current usage | | Tokens Out | tokens-output | Output tokens | | Tokens Cached | tokens-cached | Cache creation + read tokens | | Tokens Total | tokens-total | All tokens combined | | Session Cost | session-cost | Running cost in USD with optional burn rate | | Session Duration | session-duration | Elapsed time with optional API ratio | | Block Timer | block-timer | 5-hour usage block tracker with progress bar |

Git Integration

| Widget | Type | Description | |--------|------|-------------| | Branch | git-branch | Current branch (with detached HEAD support) | | Status | git-status | Staged/modified/untracked file counts | | Worktree | git-worktree | Active worktree name (hidden when not in worktree) |

Workspace

| Widget | Type | Description | |--------|------|-------------| | CWD | cwd | Current directory (basename, full, fish-style) | | Lines Changed | lines-changed | Lines added/removed this session | | Version | version | Claude Code version | | Session ID | session-id | Truncated session identifier |

Advanced

| Widget | Type | Description | |--------|------|-------------| | Vim Mode | vim-mode | NORMAL/INSERT (hidden when vim mode off) | | Agent Name | agent-name | Active agent (hidden when not using --agent) | | Output Style | output-style | Current output style (hidden when "default") | | Exceeds 200K | exceeds-tokens | Warning when tokens exceed 200K threshold | | API Duration | api-duration | Ratio of API wait time to total time | | Custom Command | custom-command | Run any shell command, display output | | Custom Text | custom-text | Static text with emoji support | | Separator | separator | Visual divider between widgets | | Flex Separator | flex-separator | Flexible spacer that pushes widgets apart | | Terminal Width | terminal-width | Current terminal width in columns |

Configuration

TUI Configurator

Launch the interactive TUI to configure your status line visually:

ai-statusline config

Navigation:

• Tab / Shift-Tab — Switch between tabs (Widgets, Theme, Powerline, Layout, Preview)
• ↑ / ↓ — Navigate items
• ← / → — Switch between status lines (in Widgets tab)
• Enter / Space — Select/toggle options
• a — Add widget
• d / Delete — Remove widget
• j / k — Move widget down/up
• Ctrl-S — Save configuration
• q — Quit

Tabs:

• Widgets — Add, remove, and reorder widgets on each status line
• Theme — Browse and select from 11 built-in color themes
• Powerline — Toggle powerline mode, cycle separators, enable auto-align
• Layout — Add/remove status lines, change flex mode
• Preview — Live preview of your current configuration

Manual Configuration

Config lives at ~/.config/ai-statusline/config.toml. Generate a default:

ai-statusline init

Or edit the TOML file directly for advanced customization.

Example config

theme = "dracula"
default_separator = " | "
default_padding = " "
flex_mode = "full-minus-40"
compact_threshold = 60
global_bold = false
inherit_separator_colors = false

# First status line
[[lines]]
type = "model"
color = "cyan"
raw_value = true

[[lines]]
type = "context-percentage"
metadata = { bar = "true" }

[[lines]]
type = "session-cost"
color = "yellow"
raw_value = true

[[lines]]
type = "session-duration"
raw_value = true

# Second status line (start a new line group)
[[lines]]
type = "cwd"
metadata = { fish_style = "true" }

[[lines]]
type = "git-branch"
color = "magenta"

[[lines]]
type = "git-status"

[powerline]
enabled = false
separator = "\uE0B0"
auto_align = false

Widget options

Every widget supports:

| Option | Type | Description | |--------|------|-------------| | type | string | Widget type (see table above) | | color | string | Foreground color (named, hex, or 256-color index) | | background_color | string | Background color | | bold | bool | Bold text | | raw_value | bool | Compact mode without labels | | padding | string | Override default padding | | merge_next | bool | Merge with next widget (no separator) | | metadata | table | Widget-specific options |

Widget-specific metadata

| Widget | Key | Values | Description | |--------|-----|--------|-------------| | context-percentage | bar | "true" | Show progress bar | | context-percentage | inverse | "true" | Show remaining instead of used | | session-cost | burn_rate | "true" | Show hourly burn rate | | session-duration | api_ratio | "true" | Show API time percentage | | block-timer | bar | "true" | Show progress bar | | block-timer | bar_width | "16" | Progress bar width | | cwd | full | "true" | Show full path | | cwd | fish_style | "true" | Fish-style abbreviation | | cwd | segments | "3" | Show last N segments | | custom-command | command | shell cmd | Command to execute | | custom-text | text | any string | Static text to display | | separator | char | any char | Separator character | | flex-separator | char | any char | Fill character (default: space) |

Themes

11 built-in themes optimized for popular terminal color schemes:

ai-statusline theme list    # List all themes
ai-statusline theme set nord  # Switch theme

Available: default, solarized, nord, dracula, gruvbox, monokai, light, high-contrast, one-dark, tokyo-night, catppuccin

Color Support

ai-statusline auto-detects terminal color capabilities:

• Truecolor (24-bit): detected via COLORTERM=truecolor
• 256-color: detected via TERM=*256color*
• 16-color: fallback for basic terminals
• No color: respects NO_COLOR environment variable

Override with --color-level:

ai-statusline --color-level truecolor
ai-statusline --color-level none

CLI Commands

ai-statusline              # Render status line (reads JSON from stdin)
ai-statusline init         # Generate default config file
ai-statusline doctor       # Check environment compatibility
ai-statusline theme list   # List available themes
ai-statusline theme set <name>  # Switch theme
ai-statusline preset <name>     # Apply a preset layout
ai-statusline config            # Interactive TUI configurator
ai-statusline dump-schema       # Print expected JSON input schema
ai-statusline --version         # Show version

Performance

Benchmarked on Apple M1:

| Metric | Value | |--------|-------| | Render time | <1ms | | Binary size | 1.0 MB | | Memory usage | 1.2 MB | | Startup time | <1ms |

Claude Code debounces status line updates at 300ms. ai-statusline completes in <1ms, ensuring the status line is always fresh and never causes UI lag.

How It Works

Claude Code pipes JSON session data to your status line script via stdin. ai-statusline reads this JSON, applies your configuration, and prints formatted ANSI text to stdout. No transcript parsing, no file watching, no external dependencies.

Claude Code → JSON stdin → ai-statusline → ANSI stdout → Terminal

Building from Source

git clone https://github.com/mstuart/ai-statusline
cd ai-statusline
cargo build --release
# Binary at ./target/release/ai-statusline

License

MIT