{
  "statusLine": {
    "type": "command",
    "command": "npx -y @owloops/claude-powerline@latest --style=powerline"
  }
}

Start a Claude session and the statusline appears at the bottom. Using npx automatically downloads and runs the latest version without manual updates.

Styles

Themes

6 built-in themes (dark, light, nord, tokyo-night, rose-pine, gruvbox) or create your own.

Config locations (in priority order):

• ./.claude-powerline.json - Project-specific
• ~/.claude/claude-powerline.json - User config
• ~/.config/claude-powerline/config.json - XDG standard

Override priority: CLI flags > Environment variables > Config files > Defaults

Config files reload automatically, no restart needed.

Get example config:

curl -o ~/.claude/claude-powerline.json https://raw.githubusercontent.com/Owloops/claude-powerline/main/.claude-powerline.json

CLI Options (both --arg value and --arg=value syntax supported):

• --theme - dark (default), light, nord, tokyo-night, rose-pine, gruvbox, custom
• --style - minimal (default), powerline, capsule, tui
• --charset - unicode (default), text
• --config - Custom config file path
• --help - Show help

Examples:

claude-powerline --theme=nord --style=powerline
claude-powerline --theme=dark --style=capsule --charset=text
claude-powerline --config=/path/to/config.json

Environment Variables:

export CLAUDE_POWERLINE_THEME=dark
export CLAUDE_POWERLINE_STYLE=powerline
export CLAUDE_POWERLINE_CONFIG=/path/to/config.json
export CLAUDE_POWERLINE_DEBUG=1  # Enable debug logging

Segment Configuration

"directory": {
  "enabled": true,
  "style": "full"
}

Options:

• style: Display format - full | fish | basename
  • full: Show complete path (e.g., ~/projects/claude-powerline)
  • fish: Fish-shell style abbreviation (e.g., ~/p/claude-powerline)
  • basename: Show only folder name (e.g., claude-powerline)

"git": {
  "enabled": true,
  "showSha": true,
  "showWorkingTree": false,
  "showOperation": false,
  "showTag": false,
  "showTimeSinceCommit": false,
  "showStashCount": false,
  "showUpstream": false,
  "showRepoName": false
}

Options:

• showSha: Show abbreviated commit SHA
• showWorkingTree: Show staged/unstaged/untracked counts
• showOperation: Show ongoing operations (MERGE/REBASE/CHERRY-PICK)
• showTag: Show nearest tag
• showTimeSinceCommit: Show time since last commit
• showStashCount: Show stash count
• showUpstream: Show upstream branch
• showRepoName: Show repository name

Symbols:

• Unicode: ⎇ Branch • ♯ SHA • ⌂ Tag • ⧇ Stash • ✓ Clean • ● Dirty • ⚠ Conflicts • ↑3 Ahead • ↓2 Behind • (+1 ~2 ?3) Staged/Unstaged/Untracked
• Text: ~ Branch • # SHA • T Tag • S Stash • = Clean • * Dirty • ! Conflicts • ^3 Ahead • v2 Behind • (+1 ~2 ?3) Staged/Unstaged/Untracked

"model": {
  "enabled": true
}

Symbols: ✱ Model (unicode) • M Model (text)

"session": {
  "enabled": true,
  "type": "tokens",
  "costSource": "calculated"
}

Options:

• type: Display format - cost | tokens | both | breakdown
• costSource: Cost calculation method - calculated (ccusage-style) | official (hook data)

Symbols: § Session (unicode) • S Session (text)

"today": {
  "enabled": true,
  "type": "cost"
}

Options:

• type: Display format - cost | tokens | both | breakdown

Symbols: ☉ Today (unicode) • D Today (text)

"context": {
  "enabled": true,
  "showPercentageOnly": false,
  "displayStyle": "text",
  "autocompactBuffer": 33000
}

Options:

• showPercentageOnly: Show only percentage remaining (default: false)
• displayStyle: Visual style for context display (default: "text")
• autocompactBuffer: Number of tokens reserved as the auto-compact trigger zone (default: 33000). The usable percentage reflects how close you are to the point where compaction fires. Set to 0 if you have auto-compact disabled to show raw context usage instead
• percentageMode: How to display the percentage. "remaining" counts down from 100% (context left), "used" counts up from 0% (context consumed). Default depends on display style: "remaining" for text, "used" for bar styles

Display Styles:

| Style | Filled | Empty | Example | |-------|--------|-------|---------| | text | -- | -- | ◔ 34,040 (79%) | | ball | ─ | ─ | ─────●──── 50% | | bar | ▓ | ░ | ▓▓▓▓▓░░░░░ 50% | | blocks | █ | ░ | █████░░░░░ 50% | | blocks-line | █ | ─ | █████───── 50% | | capped | ━ | ┄ | ━━━━╸┄┄┄┄┄ 50% | | dots | ● | ○ | ●●●●●○○○○○ 50% | | filled | ■ | □ | ■■■■■□□□□□ 50% | | geometric | ▰ | ▱ | ▰▰▰▰▰▱▱▱▱▱ 50% | | line | ━ | ┄ | ━━━━━┄┄┄┄┄ 50% | | squares | ◼ | ◻ | ◼◼◼◼◼◻◻◻◻◻ 50% |

Symbols: ◔ Context (unicode) • C Context (text)

Model Context Limits

Configure context window limits for different model types. Defaults to 200K tokens for all models.

"modelContextLimits": {
  "sonnet": 1000000,
  "opus": 200000
}

Available Model Types:

• sonnet: Claude Sonnet models (3.5, 4, etc.)
• opus: Claude Opus models
• default: Fallback for unrecognized models (200K)

Note: Sonnet 4's 1M context window is currently in beta for tier 4+ users. Set "sonnet": 1000000 when you have access.

"block": {
  "enabled": true,
  "displayStyle": "text"
}

Options:

• displayStyle: Visual style for utilization display (see table below)

Requires Claude Code's native rate_limits hook data (Claude.ai Pro/Max subscribers). Displays the official 5-hour utilization percentage and reset countdown. Hidden when native data is unavailable.

Display Styles:

| Style | Example | |-------|---------| | text (default) | ◱ 23% (4h 12m) | | bar | ◱ ▪▪▫▫▫▫▫▫▫▫ 23% (4h 12m) | | blocks | ◱ ██░░░░░░░░ 23% (4h 12m) | | blocks-line | ◱ ██──────── 23% (4h 12m) | | capped | ◱ ━╸┄┄┄┄┄┄┄┄ 23% (4h 12m) | | dots | ◱ ●●○○○○○○○○ 23% (4h 12m) | | filled | ◱ ■■□□□□□□□□ 23% (4h 12m) | | geometric | ◱ ▰▰▱▱▱▱▱▱▱▱ 23% (4h 12m) | | line | ◱ ━━┄┄┄┄┄┄┄┄ 23% (4h 12m) | | squares | ◱ ◼◼◻◻◻◻◻◻◻◻ 23% (4h 12m) | | ball | ◱ ──●─────── 23% (4h 12m) |

Symbols: ◱ Block (unicode) • B Block (text)

"weekly": {
  "enabled": true,
  "displayStyle": "text"
}

Options:

• displayStyle: Visual style for utilization display - same options as the block segment (see table above)

Only visible when Claude Code provides native rate_limits.seven_day data (Claude.ai Pro/Max subscribers). Hidden when the data is not available.

Symbols: ◑ Weekly (unicode) • W Weekly (