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,
  "showAheadBehind": true,
  "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
• showAheadBehind: Show ahead/behind arrows (default true)
• showUpstream: Show the upstream branch name, e.g. →origin/main
• showRepoName: Show repository name
• showWorktree: Show the worktree indicator (⧉) when the current directory belongs to a linked git worktree. Defaults to whatever showRepoName is, so set it explicitly to get the indicator on its own — or to false to suppress it while still showing the repo name

The two upstream options are independent. showUpstream controls the branch name only, showAheadBehind controls the ↑/↓ arrows. The default (showUpstream: false) already gives you arrows without the name; to drop the arrows too, set showAheadBehind: false.

Symbols:

• Unicode: ⎇ Branch • ♯ SHA • ⌂ Tag • ⧇ Stash • ✓ Clean • ● Dirty • ⚠ Conflicts • ↑3 Ahead • ↓2 Behind • ⧉ Worktree • (+1 ~2 ?3) Staged/Unstaged/Untracked
• Text: ~ Branch • # SHA • T Tag • S Stash • = Clean • * Dirty • ! Conflicts • ^3 Ahead • v2 Behind • W Worktree • (+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:

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

Model Context Limits

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