Claude Powerline

Claude Powerline looks for configuration files in the following order of priority:

1. ./.claude-powerline.json (Project-specific)
2. ~/.claude/claude-powerline.json (User config)
3. ~/.config/claude-powerline/config.json (XDG standard)

Override Priority: CLI flags > Environment variables > Config files > Defaults.

Config files reload automatically; no restart is required for changes to take effect.

To use Claude Powerline, ensure your environment meets the following requirements:

• Node.js: version 18 or higher.
• Claude Code: installed and available.
• Git: version 2.0 or higher.
• Fonts: For the best visual experience (including icons), install a Nerd Font.

Note on Symbols: If you cannot use a Nerd Font, you can use the --charset=text flag to switch to ASCII-only symbols.

Claude Powerline requires Node.js 18+ to function. If your system does not meet this requirement, install it using your package manager:

macOS

brew install node

Ubuntu/Debian

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

node --version

You can visually configure claude-powerline using powerline.owloops.com.

Workflow:

1. Click segments in the live preview to toggle options.
2. Switch styles and themes.
3. Reorder segments.
4. Copy or download the resulting JSON.
5. Save the JSON to ~/.claude/claude-powerline.json to apply your configuration.

If you prefer manual configuration, you can add Claude Powerline to your Claude Code settings.json file. Using npx ensures that the latest version is downloaded and executed automatically without requiring manual package updates.

Add the following configuration to your settings.json:

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

After installation, you can verify that your statusline renders correctly by running the preview script with your chosen parameters. This allows you to see the visual output in your terminal before relying on it in Claude Code.

Use the following command structure, replacing the placeholders with your actual configuration values:

${CLAUDE_PLUGIN_ROOT}/bin/preview.sh --theme=${chosen_theme} --style=${chosen_style} --charset=${charset}

The recommended way to install Claude Powerline is using the interactive Setup Wizard inside Claude Code. This wizard automates the configuration of themes, styles, fonts, segments, and budget tracking. It automatically writes the configuration to ~/.claude/claude-powerline.json and updates your Claude Code settings.json.

Run these commands one at a time inside a Claude Code session:

1. Add the plugin to the marketplace.
2. Install the specific package.
3. Launch the powerline command to start the wizard.

/plugin marketplace add Owloops/claude-powerline
/plugin install claude-powerline@claude-powerline
/powerline

The src/browser.ts file serves as the browser-safe entry point for @owloops/claude-powerline. It exports all rendering modules, themes, types, and utilities required to generate statusline output without relying on Node.js built-in modules.

Note: Data providers (such as git, session, or metrics) are NOT exported here. When using this entry point, you must supply pre-built data objects (e.g., GitInfo, UsageInfo, MetricsInfo) directly to the rendering functions.

The ContextProvider determines the context limit based on the modelId provided. It maps model IDs to specific limits using the following logic:

• Sonnet models: Uses the sonnet limit defined in PowerlineConfig.modelContextLimits.
• Opus models: Uses the opus limit defined in PowerlineConfig.modelContextLimits.
• Other models: Falls back to the default limit in modelContextLimits.
• Global Fallback: If no limits are configured, it defaults to 200,000 tokens.

Ensure your PowerlineConfig object contains a modelContextLimits mapping to override these defaults for specific model families.