Claude Powerline

A vim-style powerline statusline for Claude Code with real-time usage tracking, git integration, and custom themes.

Installation

Requires Node.js 18+, Claude Code, and Git 2.0+. For best display, install a Nerd Font or use --charset=text for ASCII-only symbols.

Setup Wizard (Recommended)

The interactive wizard walks you through theme, style, font, segment, and budget selection.

# run inside Claude Code, one at a time
/plugin marketplace add Owloops/claude-powerline
/plugin install claude-powerline@claude-powerline
/powerline

The wizard writes ~/.claude/claude-powerline.json and updates your settings.json automatically. Run /powerline again any time to reconfigure.

Manual Setup

Add to your Claude Code settings.json:

{
  "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.

Powerline Studio

powerline.owloops.com is a visual configurator for claude-powerline. Click segments in the preview to toggle options, switch styles and themes live, reorder, then copy or download the JSON into ~/.claude/claude-powerline.json. Paste an existing config to edit it.

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)

In --worktree sessions, the directory segment automatically shows the original repo path instead of the worktree folder (no config required).

"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)
• showUnits: Show the trailing tokens unit when type is tokens or both (default: true). Set to false to render § 4.4M instead of § 4.4M tokens. Only applies to the powerline/capsule/minimal styles; the tui style already renders tokens without a suffix

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

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

Options:

• type: Display format - cost | tokens | both | breakdown
• showUnits: Show the trailing tokens unit when type is tokens or both (default: true). Set to false to render ☉ $12.34 (4.4M) instead of ☉ $12.34 (4.4M tokens). Only applies to the powerline/capsule/minimal styles; the tui style already renders tokens without a suffix

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