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

"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 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:

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 (text)

"metrics": {
  "enabled": true,
  "showResponseTime": true,
  "showLastResponseTime": false,
  "showDuration": true,
  "showMessageCount": true,
  "showLinesAdded": true,
  "showLinesRemoved": true
}

Options:

• showResponseTime: Total API duration across all requests
• showLastResponseTime: Individual response time for most recent query
• showDuration: Total session duration
• showMessageCount: Number of user messages sent
• showLinesAdded: Lines of code added during session
• showLinesRemoved: Lines of code removed during session

Symbols:

• Unicode: ⧖ Total API time • Δ Last response • ⧗ Session duration • ⟐ Messages • + Lines added • - Lines removed
• Text: R Total API time • L Last response • T Session duration • # Messages • + Lines added • - Lines removed

"version": {
  "enabled": true
}

Display: v1.0.81

Symbols: ◈ Version (unicode) • V Version (text)

"agent": {
  "enabled": true,
  "showLabel": false
}

Display: ◇ researcher (or ◇ agent: researcher with showLabel: true)

Symbols: ◇ Agent (unicode) • & Agent (text)

"thinking": {
  "enabled": true,
  "showEnabled": true,
  "showEffort": true
}

Set showEnabled: false to hide the On/Off state, or showEffort: false to hide the effort level. If both are true the two parts are joined with ·; if only one is shown, no separator is rendered.

Display: ✦ On · xhigh (both shown) • ✦ On (enabled only) • ✦ xhigh (effort only)

Symbols: ✦ Thinking (unicode) • T Thinking (text)

Opt-in (enabled: false by default).

"outputStyle": {
  "enabled": true,
  "showLabel": false,
  "hideDefault": false
}

Set showLabel: true to prefix the name with style: . Set hideDefault: true to omit the segment while the active style is default (compared case-insensitively), so the segment only appears once you switch away from the default style.

Display: ✎ Explanatory (or ✎ style: Explanatory with showLabel: true)

Symbols: ✎ Output Style (unicode) • OS Output Style (text)

The style name comes from Claude Code on stdin and is rendered verbatim. Older Claude Code builds do not send it — the segment is then hidden entirely rather than rendered empty.

Opt-in (enabled: false by default).

"cacheTimer": {
  "enabled": true
}

Display: ◴ 3:42 (m:ss under 5m) • ◴ 17m (5–59m) • ◴ 1h+ (1 hour or more)

Color tiers: healthy green (0–3m) → yellow warn (3–5m) → red critical (5m+). Hidden when transcript_path is unavailable.

Anchor: elapsed time is measured from the last user message in the transcript (matches Anthropic's cache TTL anchor), falling back to the transcript file mtime if JSONL parsing fails.

Display modes: displayMode: "elapsed" (default) shows time-since-last-turn as above. displayMode: "remaining" flips it to a countdown of the cache TTL — useful when you care about how long until cold rather than how stale (matches the Codex CLI status line):

"cacheTimer": {
  "enabled": true,
  "displayMode": "remaining"
}

In remaining mode the display reads ◴ 59:51 while warm and ◴ cold once expired; color tiers invert (warn under 5m left, critical under 1m left or cold).

TTL detection: the segment auto-detects which cache window Claude Code is using by reading the last assistant message's usage.cache_creation block. ephemeral_1h_input_tokens > 0 ⇒ 1h TTL; ephemeral_5m_input_tokens > 0 ⇒ 5-minute TTL. Falls back to 3600 if no usage data is available yet (e.g. the very first turn). Set ttlSeconds explicitly to override:

"cacheTimer": { "enabled": true, "displayMode": "remaining", "ttlSeconds": 300 }

TUI: also available in grid templates via {cacheTimer}, {cacheTimer.icon}, and {cacheTimer.value}.

Symbols: ◴ Cache timer (unicode) • C! Cache timer (text)

Note: cacheTimer only updates when Claude Code re-runs the statusline. Set refreshInterval in your Claude Code ~/.claude/settings.json statusLine block so the elapsed time ticks while you're idle — otherwise the timer freezes between events:

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

refreshInterval is in seconds (min 1). 10 keeps the displayed value within ~10s of reality.

"tmux": {
  "enabled": true
}

Display: tmux:session-name

"sessionId": {
  "enabled": false,
  "showIdLabel": true
}

Options:

• showIdLabel: Show the ⌗ icon prefix before the session ID (default: true)

Display: ⌗ a1b2c3d4-...

Symbols: ⌗ Session ID (unicode) • # Session ID (text)

"env": {
  "enabled": true,
  "variable": "CLAUDE_ACCOUNT",
  "prefix": "Acct"
}

Options:

• variable (required): Environment variable name to read
• prefix: Label shown before the value. Defaults to the variable name

Hidden when the variable is unset or empty.

Symbols: ⚙ Env (unicode) • $ Env (text)

"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)
• showPercentage: Show the N% suffix (default: true)
• showValue: Show the base cost/token value (default: true)

Indicators: 25% Normal • +75% Moderate (50-79%) • !85% Warning (80%+)

Display toggles. For session and today, you can hide the percentage suffix, the base value, or both:

"budget": {
  "today": { "amount": 50, "showPercentage": false }
}

• showPercentage: false hides the N% suffix while keeping the budget configured (e.g. for warning thresholds).
• showValue: false renders only the percentage (e.g. ◱ 15%).
• Both false hides the segment entirely.

A visible effect requires amount > 0 AND a computable percentage (e.g. when type: "tokens", tokens must be present). Without a budget or a computable percentage, these flags are no-ops and the segment falls back to rendering the base value. block accepts the same fields for config symmetry but does not render a budget suffix today, so they have no visible effect there.

[!TIP] Claude's rate limits consider multiple factors beyond tokens (message count, length, attachments, model). See Anthropic's usage documentation for details.

Choose between Unicode symbols (requires Nerd Font) or ASCII text mode for maximum compatibility.

{
  "display": {
    "charset": "unicode"
  }
}

Options:

• unicode (default) - Uses Nerd Font icons and symbols
• text - ASCII-only characters for terminals without Nerd Font

The charset setting works independently from separator styles, giving you 8 possible combinations:

• minimal + unicode / text - No separators
• powerline + unicode / text - Arrow separators (requires Nerd Font for unicode)
• capsule + unicode / text - Rounded caps (requires Nerd Font for unicode)
• tui + unicode / text - Bordered panel with rounded or ASCII box characters

Auto-Wrap (enabled by default):

{
  "display": {
    "autoWrap": true
  }
}

Segments flow naturally and wrap to new lines when they exceed the terminal width.

Multi-line Layout for manual control:

{
  "display": {
    "lines": [
      {
        "segments": {
          "directory": { "enabled": true },
          "git": { "enabled": true },
          "model": { "enabled": true }
        }
      },
      {
        "segments": {
          "session": { "enabled": true },
          "today": { "enabled": true },
          "context": { "enabled": true }
        }
      }
    ]
  }
}

Padding - number of spaces on each side of segment text:

{
  "display": {
    "padding": 1
  }
}

Set to 0 for compact, 1 (default) for standard spacing.

Show Icons - hide the leading emblem on each segment for a text-only look:

{
  "display": {
    "showIcons": false
  }
}

Default true. Per-segment override via showIcon on any segment (e.g. "git": { "enabled": true, "showIcon": true }) takes precedence. Status glyphs (git ● ✓ ⚠, ahead/behind arrows), powerline separators, and metrics sub-icons are unaffected.

[!NOTE] Claude Code system messages may truncate long status lines. Use autoWrap or manual multi-line layouts to prevent segment cutoff.

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) • bold (boolean, optional, defaults to false)

TUI Grid Colors: In TUI grid mode, custom colors also support bare segment names and dot-notation parts as keys. A bare segment key (e.g. "context") sets the default color for the segment and all its parts. A part key (e.g. "context.bar") overrides a specific part:

"colors": {
  "custom": {
    "model": { "fg": "#e0d68a" },
    "context": { "fg": "#7dcfff" },
    "metrics.lastResponse": { "fg": "#bb9af7" }
  }
}

Compatibility Modes: auto (default), ansi, ansi256, truecolor

Environment Variables:

• NO_COLOR - Disable all colors when set to any non-empty value (follows NO_COLOR standard)
• FORCE_COLOR - Force enable color output (follows FORCE_COLOR standard):
  • 0 or false - Disable colors
  • 1 or true - Force basic 16 colors (ANSI)
  • 2 - Force 256 colors
  • 3 - Force truecolor (16 million colors)
  • Any other non-empty value - Force basic colors
• COLORTERM - Auto-detected for truecolor support

Priority: FORCE_COLOR overrides NO_COLOR (allowing color to be forced on even when NO_COLOR is set)

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

By default, the TUI panel uses a built-in responsive layout. For full control over what goes where, add a display.tui object to your config. This activates the grid layout engine, a CSS Grid-inspired system that lets you define rows, columns, spans, and responsive breakpoints.

Grid Layout Configuration

Add display.tui to your config file to enable the grid engine:

{
  "display": {
    "style": "tui",
    "tui": {
      "fitContent": true,
      "widthReserve": 45,
      "minWidth": 32,
      "maxWidth": 120,
      "padding": { "horizontal": 4 },
      "separator": {
        "column": "  ",
        "divider": "─"
      },
      "box": { ... },
      "title": { ... },
      "footer": { ... },
      "segments": { ... },
      "breakpoints": [ ... ]
    }
  }
}

Breakpoints

Each breakpoint defines a complete layout that activates when the panel width is at or above its minWidth. The engine picks the first match, sorted widest-first.

"breakpoints": [
  {
    "minWidth": 80,
    "areas": [
      "git.head      git.head     git.head     .               git.working",
      "---",
      "context.icon  context.bar  context.bar  context.pct     context.tokens",
      "block.icon    block.bar    block.bar    block.value     block.time"
    ],
    "columns": ["auto", "1fr", "auto", "auto", "auto"],
    "align": ["left", "left", "right", "right", "right"]
  },
  {
    "minWidth": 55,
    "areas": [
      "git.head             git.working",
      "---",
      "context.bar          context.tokens",
      "block                ."
    ],
    "columns": ["1fr", "auto"],
    "align": ["left", "right"]
  },
  {
    "minWidth": 0,
    "areas": [
      "git.head",
      "git.working",
      "---",
      "context",
      "block"
    ],
    "columns": ["1fr"],
    "align": ["left"]
  }
]

Column sizing:

• "auto" - shrinks to the widest content in that column
• "1fr", "2fr" - fractional units that divide remaining space proportionally
• "20" - fixed width in characters

Special area tokens:

• . - empty cell (renders as blank space)
• --- - full-width horizontal divider row

Spanning: repeat the same name in adjacent cells to span columns:

"context.bar  context.bar  context.bar  context.pct  context.tokens"

Here context.bar spans the first three columns.

Segment Names

Use bare segment names to render the full pre-formatted segment:

context  block    session  today    weekly
git      dir      model    version  tmux
metrics  activity env      agent    thinking
cacheTimer  outputStyle

Dot-Notation Subsegments

Use segment.part to place individual pieces of a segment into separate cells with independent alignment:

Example, block segment with a progress bar, mirroring the context layout:

"areas": [
  "context.icon  context.bar  context.bar  context.pct  context.tokens",
  "block.icon    block.bar    block.bar    block.value  block.time"
]

[!NOTE] context.bar, block.bar, and weekly.bar are width-aware. Their progress bars render at exactly the resolved column width. Block bar uses nativeUtilization from the 5-hour rate limit data. Weekly bar uses the 7-day used_percentage.

Custom Box Characters

Override individual box-drawing characters. Partial overrides merge with the charset default (unicode or text):

"box": {
  "topLeft": "┌",
  "topRight": "┐",
  "bottomLeft": "└",
  "bottomRight": "┘",
  "horizontal": "─",
  "vertical": "│",
  "teeLeft": "├",
  "teeRight": "┤"
}

Only specify the characters you want to change. The rest inherit from the active charset.

Title Bar

Configure the left and right text in the top border. Supports {model} and any {segment} or {segment.part} token that resolves from segment data:

"title": {
  "left": "{model}",
  "right": "{dir}"
}

Footer

Same as the title bar, but on the bottom border. Defaults to no text (plain border):

"footer": {
  "left": "{weekly}",
  "right": "{metrics.lastResponse}"
}

Tokens resolve any segment or subsegment reference: {model}, {dir}, {git.head}, {block.value}, {metrics.lastResponse}, etc.

Segment Templates

Define custom compositions for composite cells using the segments key. This assembles multiple parts into a single cell:

"segments": {
  "metrics.lastResponse": {
    "items": ["{lastResponseIcon}", "{lastResponseVal}"],
    "gap": 1,
    "justify": "start"
  }
}

The template name (e.g. metrics.lastResponse) can then be used as a cell name in areas.

Automatic Culling

Empty segments are automatically removed. Cells resolve to ., empty rows are dropped, and orphaned dividers are cleaned up. A wide layout gracefully degrades when data is unavailable.

[!NOTE] Claude Code's internal progress indicators (spinner, context bar) may briefly overlap the TUI panel during tool calls. This is a limitation of the hook architecture and resolves once the tool call completes.

Extend the statusline using shell composition:

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

[!NOTE] Use tput for 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.