OwloopsClaude Powerline
A vim-style powerline statusline for Claude Code with real-time usage tracking, git integration, and custom themes.
Demo
Live demonstration: real-time usage tracking, git integration, and theme showcase
 Dark |
 Light |
 Nord |
 Tokyo Night |
 Rose Pine |
 Create your own! |
Features
Usage Tracking
Git Integration
|
Customization
Performance Metrics
|
Installation
Setup
Requires Node.js 18+, Claude Code, Git 2.0+, and terminal with Nerd Font for proper icon display.
1. Add to your Claude Code settings.json:
{
"statusLine": {
"type": "command",
"command": "npx -y @owloops/claude-powerline@latest --style=powerline"
}
}2. Start a Claude session - the statusline appears at the bottom during conversations.
Using npx automatically downloads and runs the latest version without manual updates.
Usage
Once added to Claude Code settings, the statusline runs automatically. For customization:
CLI Options:
--theme-dark(default),light,nord,tokyo-night,rose-pine,custom--style-minimal(default),powerline,capsule--config- Custom config file path--help- Show help
Examples:
claude-powerline --theme=nord --style=powerline
claude-powerline --theme=dark --style=capsule
claude-powerline --config=/path/to/config.jsonEnvironment 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 loggingStyles
Configuration
Get example config:
# Download full-featured example config
curl -o ~/.claude/claude-powerline.json https://raw.githubusercontent.com/Owloops/claude-powerline/main/.claude-powerline.jsonConfig 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 and no restart needed.
Segment Configuration
"directory": {
"enabled": true,
"showBasename": false
}Options:
showBasename: Show only folder name instead of full path
"git": {
"enabled": true,
"showSha": true,
"showWorkingTree": false,
"showOperation": false,
"showTag": false,
"showTimeSinceCommit": false,
"showStashCount": false,
"showUpstream": false,
"showRepoName": false
}Options:
showSha: Show abbreviated commit SHAshowWorkingTree: Show staged/unstaged/untracked countsshowOperation: Show ongoing operations (MERGE/REBASE/CHERRY-PICK)showTag: Show nearest tagshowTimeSinceCommit: Show time since last commitshowStashCount: Show stash countshowUpstream: Show upstream branchshowRepoName: Show repository name
Symbols:
⎇Branch •♯SHA •⌂Tag •⧇Stash •✓Clean •●Dirty •⚠Conflicts •↑3Ahead •↓2Behind •(+1 ~2 ?3)Staged/Unstaged/Untracked
"metrics": {
"enabled": true,
"showResponseTime": true,
"showLastResponseTime": false,
"showDuration": true,
"showMessageCount": true,
"showLinesAdded": true,
"showLinesRemoved": true
}Options:
showResponseTime: Total API duration across all requestsshowLastResponseTime: Individual response time for most recent queryshowDuration: Total session durationshowMessageCount: Number of user messages sentshowLinesAdded: Lines of code added during sessionshowLinesRemoved: Lines of code removed during session
Symbols:
⧖Total API time •ΔLast response •⧗Session duration •⟐Messages •+Lines added •-Lines removed
"model": {
"enabled": true
}"context": {
"enabled": true,
"showPercentageOnly": false
}Options:
showPercentageOnly: Show only percentage remaining (default: false)
Display: ◔ 34,040 (79%) or ◔ 79% (percentage only)
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 modelsdefault: 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.
"tmux": {
"enabled": true
}Display: tmux:session-name
"version": {
"enabled": true
}Display: v1.0.81
"session": {
"enabled": true,
"type": "tokens",
"costSource": "calculated"
}Options:
type: Display format -cost|tokens|both|breakdowncostSource: Cost calculation method -calculated(ccusage-style) |official(hook data)
Symbols: § Session
"block": {
"enabled": true,
"type": "weighted",
"burnType": "cost"
}Options:
type: Display format -cost|tokens|both|time|weightedburnType: Burn rate display -cost|tokens|both|none
Weighted Tokens: Opus tokens count 5x toward rate limits compared to Sonnet/Haiku tokens
Symbols: ◱ Block
"today": {
"enabled": true,
"type": "cost"
}Options:
type: Display format -cost|tokens|both|breakdown
Symbols: ☉ Today
Budget Configuration
"budget": {
"session": { "amount": 10.0, "warningThreshold": 80 },
"today": { "amount": 25.0, "warningThreshold": 80 },
"block": { "amount": 15.0, "type": "cost", "warningThreshold": 80 }
}Options:
amount: Budget limit (required for percentage display)type: Budget type -cost(USD) |tokens(for token-based limits)warningThreshold: Warning threshold percentage (default: 80)
Indicators: 25% Normal • +75% Moderate (50-79%) • !85% Warning (80%+)
[!TIP]
Claude's rate limits consider multiple factors beyond tokens (message count, length, attachments, model). See Anthropic's usage documentation for details.
Multi-line Layout
Prevent segment cutoff by organizing segments across multiple lines.
{
"display": {
"lines": [
{
"segments": {
"directory": { "enabled": true },
"git": { "enabled": true },
"model": { "enabled": true }
}
},
{
"segments": {
"session": { "enabled": true },
"today": { "enabled": true },
"context": { "enabled": true }
}
}
]
}
}[!NOTE]
Claude Code system messages may truncate long status lines. Multi-line layouts prevent segment cutoff and improve readability.
Colors & Themes
Create custom themes and configure color compatibility:
{
"theme": "custom",
"display": {
"colorCompatibility": "auto"
},
"colors": {
"custom": {
"directory": { "bg": "#ff6600", "fg": "#ffffff" },
"git": { "bg": "#0066cc", "fg": "#ffffff" },
"session": { "bg": "#cc0099", "fg": "#ffffff" }
}
}
}Color Options: bg (hex, transparent, none) • fg (hex)
Compatibility Modes: auto (default), ansi, ansi256, truecolor. Respects NO_COLOR, FORCE_COLOR, and COLORTERM environment variables.
Performance
Execution times for different configurations:
- ~80ms default config (
directory,git,model,session,today,context) - ~240ms full-featured (all segments enabled)
| Segment | Timing | Notes |
|---|---|---|
directory |
~40ms | No external commands |
model |
~40ms | Uses hook data |
session |
~40ms | Minimal transcript parsing |
context |
~40ms | Hook data calculation |
metrics |
~40ms | Transcript analysis |
git |
~60ms | No caching for fresh data |
tmux |
~50ms | Environment check + command |
block |
~180ms | 5-hour window transcript load |
today |
~250ms | Full daily transcript load (cached: ~50ms) |
version |
~40ms | Uses hook data |
Benchmark: npm run benchmark:timing
Optimization Tips
- Global install:
npm install -gto avoid npx overhead - Disable unused segments for faster execution
- Cache cleanup: Remove
~/.claude/powerline/if needed
Custom Segments
Extend the statusline using shell composition:
{
"statusLine": {
"type": "command",
"command": "npx -y @owloops/claude-powerline && echo \" $(date +%H:%M)\"",
"padding": 0
}
}[!NOTE]
Usetputfor colors:setab <bg>(background),setaf <fg>(foreground),sgr0(reset). Example:echo "$(tput setab 4)$(tput setaf 15) text $(tput sgr0)". For complex logic, create a shell script with multiple commands, conditions, and variables.
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.