Claude Powerline

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

Dark	Light
Nord	Tokyo Night
Rose Pine	Create your own!

Features

Core Features

Vim-style powerline with proper arrows and segments
Real-time session tracking with costs and tokens
Billing window tracking with 5-hour block usage
Daily usage monitoring with budget alerts
Performance metrics with response times and burn rates
Context monitoring showing tokens used and auto-compact threshold
Git integration with branch, status, ahead/behind counts

Customization

Custom themes with full color control
Budget monitoring with percentage warnings
Flexible configuration via JSON files and environment variables

Installation

Requirements

Node.js 18+
Claude Code

Setup

Install powerline fonts:

npx -y @owloops/claude-powerline --install-fonts

Warning

Without powerline fonts, arrow separators display as placeholder characters (�). The default --style=minimal mode resolves it by not using the powerline unicode.

Add to your Claude Code settings.json:

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

Note

Using npx automatically downloads and runs the latest version, ensuring you always have the newest features and fixes without manual updates.

Start a Claude session: It appears at the bottom during conversations.

Tip

The statusline shows your current directory name (not "claude powerline") and updates with live usage data during Claude conversations.

Usage

claude-powerline [OPTIONS]

Options are specified by command line flags. Overall configuration can also use environment variables or configuration files.

Command Line Options

Option	Values	Description
`--theme`	`dark` (default), `light`, `nord`, `tokyo-night`, `rose-pine`, `custom`	Set color theme
`--style`	`minimal` (default), `powerline`	Set separator style
`--usage`	`cost`, `tokens`, `both`, `breakdown`	Set usage display format
`--session-budget`	`AMOUNT`	Set session budget limit in USD
`--config`	`PATH`	Use custom config file path
`--install-fonts`	-	Install powerline fonts to system
`-h, --help`	-	Show help message

Note

Global options have CLI flags and environment variables. Individual segments are configured through config files.

Usage Display Types

cost: Show dollar amounts ($0.05)
tokens: Show token counts (1.2K tokens)
both: Show both ($0.05 (1.2K tokens))
breakdown: Show detailed token breakdown (1.2Kin + 0.8Kout + 1.5Kcached)

Examples

Default Configuration

# Shows directory, git, model, session usage (tokens), block usage, context info
# Uses dark theme, minimal style
claude-powerline

Theme and Style

# Nord theme with powerline arrows
claude-powerline --theme=nord --style=powerline

# Tokyo Night theme, minimal style
claude-powerline --theme=tokyo-night --style=minimal

Usage Display

# Show token breakdown instead of costs
claude-powerline --usage=breakdown

# Set session budget limit
claude-powerline --session-budget=50

Status Indicators

Git: ✓ Clean, ● Dirty, ⚠ Conflicts, ↑3 Ahead, ↓2 Behind remote
Context: ⊡ 34,040 (79%) - Token count and percentage remaining until auto-compact (uses 75% of 200k limit)
Budget: 25% Normal (under 50%), +75% Moderate (50-79%), !85% Warning (80%+)

Configuration

Create config file:

# Copy example config from repository
curl -o ~/.claude/claude-powerline.json https://raw.githubusercontent.com/Owloops/claude-powerline/main/.claude-powerline.json

Configuration priority (top overrides bottom):

CLI arguments (--theme, --style, --usage, --session-budget, --config)
Environment variables (CLAUDE_POWERLINE_THEME, CLAUDE_POWERLINE_STYLE, CLAUDE_POWERLINE_USAGE_TYPE, CLAUDE_POWERLINE_SESSION_BUDGET, CLAUDE_POWERLINE_CONFIG)
Config files (first found):
- ./.claude-powerline.json (project)
- ~/.claude/claude-powerline.json (user)
- ~/.config/claude-powerline/config.json (XDG)
Default values

Note

Config files are reloaded automatically when changed - no need to restart Claude Code.

Available Segments

{
  "display": {
    "lines": [
      {
        "segments": {
          "directory": { "enabled": true },
          "git": { "enabled": true, "showSha": true },
          "model": { "enabled": true },
          "session": { "enabled": true, "type": "tokens" },
          "block": { "enabled": true, "type": "cost" },
          "today": { "enabled": true, "type": "cost" },
          "context": { "enabled": true },
          "tmux": { "enabled": true },
          "metrics": { 
            "enabled": true,
            "showResponseTime": true,
            "showDuration": true,
            "showMessageCount": true,
            "showCostBurnRate": false,
            "showTokenBurnRate": false
          }
        }
      }
    ]
  }
}

Segment Details

directory: Current working directory name
git: Branch, status (clean/dirty), ahead/behind counts, SHA (optional)
model: Current Claude model being used
session: Token usage and costs for current session
block: Usage within current 5-hour billing window
today: Total daily usage with budget monitoring
context: Context window usage and auto-compact threshold
tmux: Tmux session name and window info (when in tmux)
metrics: Performance analytics (response time, session duration, message count, burn rates)

Metrics Configuration

The metrics segment displays performance analytics from your Claude sessions:

"metrics": {
  "enabled": true,
  "showResponseTime": true,
  "showDuration": true, 
  "showMessageCount": true,
  "showCostBurnRate": false,
  "showTokenBurnRate": false
}

Options:

showResponseTime: Average response time per message (⧖ 3.2s)
showDuration: Total session duration (⧗ 28m)
showMessageCount: Number of user messages (⟐ 93)
showCostBurnRate: Cost burn rate per hour (⟢ $1.20/h)
showTokenBurnRate: Token burn rate per hour (⟢ 450K/h)

Usage Segments Configuration

The powerline includes three complementary usage segments:

{
  "segments": {
    "session": { "enabled": true, "type": "tokens" },
    "block": { "enabled": true, "type": "cost" },
    "today": { "enabled": true, "type": "cost" }
  },
  "budget": {
    "session": { "amount": 10.0, "warningThreshold": 80 },
    "today": { "amount": 25.0, "warningThreshold": 80 }
  }
}

Segment Types:

session: Real-time usage for current Claude conversation
block: Usage within current 5-hour billing window (Claude's rate limit period)
today: Total daily usage with budget monitoring

Display Options:

Session & Today segments:

cost: Show dollar amounts ($0.05)
tokens: Show token counts (1.2K tokens)
both: Show both ($0.05 (1.2K))
breakdown: Show token breakdown (1.2Kin + 0.8Kout + 1.5Kcached)

Block segment (always shows time remaining):

cost: Show cost + time ($0.05 (2h 30m left))
tokens: Show tokens + time (1.2K tokens (2h 30m left))

Budget Configuration:

"budget": {
  "session": {
    "amount": 10.0,
    "warningThreshold": 80
  },
  "today": {
    "amount": 25.0, 
    "warningThreshold": 80
  }
}

Budget Indicators:

25% Normal (under 50%)
+75% Moderate (50-79%)
!85% Warning (80%+)

Why Use Different Segments?

session: Track spending per conversation
block: Monitor rate limits with time remaining (Claude throttles after 5-hour usage peaks)
today: Stay within daily budgets

Multi-line Layout (Optional)

To prevent segment cutoff, configure multiple lines:

{
  "display": {
    "lines": [
      {
        "segments": {
          "directory": { "enabled": true },
          "git": { "enabled": true },
          "model": { "enabled": true }
        }
      },
      {
        "segments": {
          "session": { "enabled": true, "type": "tokens" },
          "block": { "enabled": true, "type": "cost" },
          "today": { "enabled": true, "type": "cost" },
          "context": { "enabled": true },
          "tmux": { "enabled": false },
          "metrics": { "enabled": true }
        }
      }
    ]
  }
}

Note

Claude Code system messages (e.g., Context left until auto-compact) may truncate the status line mid-sequence. Multi-line layouts help prevent segment cutoff.

Custom Colors

To customize colors, copy dark or light theme colors from src/themes/ in the repository, then modify:

{
  "theme": "custom",
  "colors": {
    "custom": {
      "directory": { "bg": "#ff6600", "fg": "#ffffff" },
      "git": { "bg": "#0066cc", "fg": "#ffffff" },
      "model": { "bg": "#9900cc", "fg": "#ffffff" },
      "session": { "bg": "#cc0099", "fg": "#ffffff" },
      "block": { "bg": "#404040", "fg": "#cccccc" },
      "today": { "bg": "#303030", "fg": "#dddddd" },
      "context": { "bg": "#4a5568", "fg": "#ffffff" },
      "tmux": { "bg": "#228b22", "fg": "#ffffff" },
      "metrics": { "bg": "#374151", "fg": "#ffffff" }
    }
  }
}

Custom Segments

Extend the statusline by wrapping the command with shell composition:

Add Custom Segments

Use tput for colors that match your terminal theme:

{
  "statusLine": {
    "type": "command",
    "command": "npx -y @owloops/claude-powerline && echo \"$(tput setab 4)$(tput setaf 15) ⏱ $(date +%H:%M) $(tput sgr0)\"",
    "padding": 0
  }
}

Common tput colors:

setab 1 (red bg) setaf 15 (white fg)
setab 2 (green bg) setaf 0 (black fg)
setab 4 (blue bg) setaf 15 (white fg)
setab 6 (cyan bg) setaf 0 (black fg)

Custom Wrapper Script

Create ~/.local/bin/my-statusline:

#!/bin/bash
# Option 1: Same line (continuous)
cat | npx -y @owloops/claude-powerline | tr -d '\n'
echo -n "$(tput setab 6)$(tput setaf 0) ⏱ $(date +%H:%M) $(tput sgr0)"
echo "$(tput setab 2)$(tput setaf 0) ☁ $(curl -s wttr.in?format=%t 2>/dev/null || echo '?') $(tput sgr0)"

# Option 2: Separate lines (multiline)
# cat | npx -y @owloops/claude-powerline
# echo "$(tput setab 6)$(tput setaf 0) ⏱ $(date +%H:%M) $(tput sgr0)"
# echo "$(tput setab 2)$(tput setaf 0) ☁ $(curl -s wttr.in?format=%t 2>/dev/null || echo '?') $(tput sgr0)"

Then use it in settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "/full/path/to/my-statusline",
    "padding": 0
  }
}

Tip

Shell composition provides unlimited flexibility while keeping the core package secure - no arbitrary command execution needed. Use full absolute paths or ensure scripts are in your PATH.

Environment Variables

export CLAUDE_POWERLINE_THEME=dark
export CLAUDE_POWERLINE_STYLE=powerline
export CLAUDE_POWERLINE_USAGE_TYPE=tokens
export CLAUDE_POWERLINE_CONFIG=/path/to/config.json

Troubleshooting

Arrows not displaying? Run claude-powerline --install-fonts and set terminal font to a powerline-patched font.

Cost showing N/A? Check that Claude session files are accessible in ~/.claude directory.

Tmux segment not showing? Ensure you're in a tmux session and enable it in config.

Debug logging: Enable debug output to troubleshoot issues:

export CLAUDE_POWERLINE_DEBUG=1
# Then use Claude Code normally - debug info will appear in stderr

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

See CONTRIBUTORS.md for people who have contributed outside of GitHub PRs.

License

This project is licensed under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 79 Commits
.github/workflows		.github/workflows
images		images
src		src
test		test
.claude-powerline.json		.claude-powerline.json
.gitignore		.gitignore
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTORS.md		CONTRIBUTORS.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
pricing.json		pricing.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Navigation Menu

Repository files navigation

Claude Powerline

Features

Core Features

Customization

Installation

Requirements

Setup

Usage

Command Line Options

Usage Display Types

Examples

Default Configuration

Theme and Style

Usage Display

Status Indicators

Configuration

Available Segments

Segment Details

Metrics Configuration

Usage Segments Configuration

Multi-line Layout (Optional)

Custom Colors

Custom Segments

Add Custom Segments

Custom Wrapper Script

Environment Variables

Troubleshooting

Contributing

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Claude Powerline

Features

Core Features

Customization

Installation

Requirements

Setup

Usage

Command Line Options

Usage Display Types

Examples

Default Configuration

Theme and Style

Usage Display

Status Indicators

Configuration

Available Segments

Segment Details

Metrics Configuration

Usage Segments Configuration

Multi-line Layout (Optional)

Custom Colors

Custom Segments

Add Custom Segments

Custom Wrapper Script

Environment Variables

Troubleshooting

Contributing

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages