{"id":30717947,"url":"https://github.com/owloops/claude-powerline","last_synced_at":"2026-04-20T10:03:54.581Z","repository":{"id":309173388,"uuid":"1035385503","full_name":"Owloops/claude-powerline","owner":"Owloops","description":"Beautiful vim-style powerline statusline for Claude Code","archived":false,"fork":false,"pushed_at":"2026-04-01T20:59:57.000Z","size":6069,"stargazers_count":976,"open_issues_count":4,"forks_count":69,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-02T04:27:39.063Z","etag":null,"topics":["claude-code","cli","developer-tools","git","lightweight","statusline"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Owloops.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-10T09:35:29.000Z","updated_at":"2026-04-01T22:55:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"01c4de9f-8406-4c51-844c-a2b05c1c3831","html_url":"https://github.com/Owloops/claude-powerline","commit_stats":null,"previous_names":["owloops/claude-powerline"],"tags_count":109,"template":false,"template_full_name":null,"purl":"pkg:github/Owloops/claude-powerline","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Owloops%2Fclaude-powerline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Owloops%2Fclaude-powerline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Owloops%2Fclaude-powerline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Owloops%2Fclaude-powerline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Owloops","download_url":"https://codeload.github.com/Owloops/claude-powerline/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Owloops%2Fclaude-powerline/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31560476,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","cli","developer-tools","git","lightweight","statusline"],"created_at":"2025-09-03T09:02:47.043Z","updated_at":"2026-04-08T15:00:46.427Z","avatar_url":"https://github.com/Owloops.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Claude Powerline\n\n**A vim-style powerline statusline for Claude Code with real-time usage tracking, git integration, and custom themes.**\n\n![License:MIT](https://img.shields.io/static/v1?label=License\u0026message=MIT\u0026color=blue\u0026style=flat-square)\n[![npm downloads](https://img.shields.io/npm/dm/@owloops/claude-powerline.svg)](https://www.npmjs.com/package/@owloops/claude-powerline)\n[![npm version](https://img.shields.io/npm/v/@owloops/claude-powerline?style=flat-square)](https://www.npmjs.com/package/@owloops/claude-powerline)\n[![Install size](https://packagephobia.com/badge?p=@owloops/claude-powerline)](https://packagephobia.com/result?p=@owloops/claude-powerline)\n[![Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen)](https://www.npmjs.com/package/@owloops/claude-powerline)\n\n[![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/hesreallyhim/awesome-claude-code)\n\n\u003cimg src=\"images/demo-tui.gif\" alt=\"Claude Powerline TUI Mode Demo\" width=\"600\"/\u003e\n\n\u003c/div\u003e\n\n## Installation\n\nRequires Node.js 18+, Claude Code, and Git 2.0+. For best display, install a [Nerd Font](https://www.nerdfonts.com/) or use `--charset=text` for ASCII-only symbols.\n\n### Setup Wizard (Recommended)\n\nThe interactive wizard walks you through theme, style, font, segment, and budget selection.\n\n```bash\n# run inside Claude Code, one at a time\n/plugin marketplace add Owloops/claude-powerline\n/plugin install claude-powerline@claude-powerline\n/powerline\n```\n\nThe wizard writes `~/.claude/claude-powerline.json` and updates your `settings.json` automatically. Run `/powerline` again any time to reconfigure.\n\n### Manual Setup\n\nAdd to your Claude Code `settings.json`:\n\n```json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"npx -y @owloops/claude-powerline@latest --style=powerline\"\n  }\n}\n```\n\nStart a Claude session and the statusline appears at the bottom. Using `npx` automatically downloads and runs the latest version without manual updates.\n\n## Styles\n\n\u003cimg src=\"images/claude-powerline-styles.png\" alt=\"Claude Powerline Styles\" width=\"700\"\u003e\n\n## Themes\n\n\u003cimg src=\"images/claude-powerline-themes.png\" alt=\"Claude Powerline Themes\" width=\"700\"\u003e\n\n6 built-in themes (dark, light, nord, tokyo-night, rose-pine, gruvbox) or [create your own](#configuration).\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch2\u003eConfiguration\u003c/h2\u003e\u003c/summary\u003e\n\n**Config locations** (in priority order):\n\n- `./.claude-powerline.json` - Project-specific\n- `~/.claude/claude-powerline.json` - User config\n- `~/.config/claude-powerline/config.json` - XDG standard\n\n**Override priority:** CLI flags \u003e Environment variables \u003e Config files \u003e Defaults\n\nConfig files reload automatically, no restart needed.\n\n**Get example config:**\n\n```bash\ncurl -o ~/.claude/claude-powerline.json https://raw.githubusercontent.com/Owloops/claude-powerline/main/.claude-powerline.json\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCLI Options and Environment Variables\u003c/strong\u003e\u003c/summary\u003e\n\n**CLI Options** (both `--arg value` and `--arg=value` syntax supported):\n\n- `--theme` - `dark` (default), `light`, `nord`, `tokyo-night`, `rose-pine`, `gruvbox`, `custom`\n- `--style` - `minimal` (default), `powerline`, `capsule`, `tui`\n- `--charset` - `unicode` (default), `text`\n- `--config` - Custom config file path\n- `--help` - Show help\n\n**Examples:**\n\n```bash\nclaude-powerline --theme=nord --style=powerline\nclaude-powerline --theme=dark --style=capsule --charset=text\nclaude-powerline --config=/path/to/config.json\n```\n\n**Environment Variables:**\n\n```bash\nexport CLAUDE_POWERLINE_THEME=dark\nexport CLAUDE_POWERLINE_STYLE=powerline\nexport CLAUDE_POWERLINE_CONFIG=/path/to/config.json\nexport CLAUDE_POWERLINE_DEBUG=1  # Enable debug logging\n```\n\n\u003c/details\u003e\n\n### Segment Configuration\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDirectory\u003c/strong\u003e - Shows current working directory name\u003c/summary\u003e\n\n```json\n\"directory\": {\n  \"enabled\": true,\n  \"style\": \"full\"\n}\n```\n\n**Options:**\n\n- `style`: Display format - `full` | `fish` | `basename`\n  - `full`: Show complete path (e.g., `~/projects/claude-powerline`)\n  - `fish`: Fish-shell style abbreviation (e.g., `~/p/claude-powerline`)\n  - `basename`: Show only folder name (e.g., `claude-powerline`)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eGit\u003c/strong\u003e - Shows branch, status, and repository information\u003c/summary\u003e\n\n```json\n\"git\": {\n  \"enabled\": true,\n  \"showSha\": true,\n  \"showWorkingTree\": false,\n  \"showOperation\": false,\n  \"showTag\": false,\n  \"showTimeSinceCommit\": false,\n  \"showStashCount\": false,\n  \"showUpstream\": false,\n  \"showRepoName\": false\n}\n```\n\n**Options:**\n\n- `showSha`: Show abbreviated commit SHA\n- `showWorkingTree`: Show staged/unstaged/untracked counts\n- `showOperation`: Show ongoing operations (MERGE/REBASE/CHERRY-PICK)\n- `showTag`: Show nearest tag\n- `showTimeSinceCommit`: Show time since last commit\n- `showStashCount`: Show stash count\n- `showUpstream`: Show upstream branch\n- `showRepoName`: Show repository name\n\n**Symbols:**\n\n- Unicode: `⎇` Branch \u0026#8226; `♯` SHA \u0026#8226; `⌂` Tag \u0026#8226; `⧇` Stash \u0026#8226; `✓` Clean \u0026#8226; `●` Dirty \u0026#8226; `⚠` Conflicts \u0026#8226; `↑3` Ahead \u0026#8226; `↓2` Behind \u0026#8226; `(+1 ~2 ?3)` Staged/Unstaged/Untracked\n- Text: `~` Branch \u0026#8226; `#` SHA \u0026#8226; `T` Tag \u0026#8226; `S` Stash \u0026#8226; `=` Clean \u0026#8226; `*` Dirty \u0026#8226; `!` Conflicts \u0026#8226; `^3` Ahead \u0026#8226; `v2` Behind \u0026#8226; `(+1 ~2 ?3)` Staged/Unstaged/Untracked\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eModel\u003c/strong\u003e - Shows current Claude model being used\u003c/summary\u003e\n\n```json\n\"model\": {\n  \"enabled\": true\n}\n```\n\n**Symbols:** `✱` Model (unicode) \u0026#8226; `M` Model (text)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSession\u003c/strong\u003e - Shows real-time usage for current Claude conversation\u003c/summary\u003e\n\n```json\n\"session\": {\n  \"enabled\": true,\n  \"type\": \"tokens\",\n  \"costSource\": \"calculated\"\n}\n```\n\n**Options:**\n\n- `type`: Display format - `cost` | `tokens` | `both` | `breakdown`\n- `costSource`: Cost calculation method - `calculated` (ccusage-style) | `official` (hook data)\n\n**Symbols:** `§` Session (unicode) \u0026#8226; `S` Session (text)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eToday\u003c/strong\u003e - Shows total daily usage with budget monitoring\u003c/summary\u003e\n\n```json\n\"today\": {\n  \"enabled\": true,\n  \"type\": \"cost\"\n}\n```\n\n**Options:**\n\n- `type`: Display format - `cost` | `tokens` | `both` | `breakdown`\n\n**Symbols:** `☉` Today (unicode) \u0026#8226; `D` Today (text)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eContext\u003c/strong\u003e - Shows context window usage and auto-compact threshold\u003c/summary\u003e\n\n```json\n\"context\": {\n  \"enabled\": true,\n  \"showPercentageOnly\": false,\n  \"displayStyle\": \"text\",\n  \"autocompactBuffer\": 33000\n}\n```\n\n**Options:**\n\n- `showPercentageOnly`: Show only percentage remaining (default: false)\n- `displayStyle`: Visual style for context display (default: `\"text\"`)\n- `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\n- `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\n\n**Display Styles:**\n\n| Style | Filled | Empty | Example |\n|-------|--------|-------|---------|\n| `text` | -- | -- | `◔ 34,040 (79%)` |\n| `ball` | ─ | ─ | `─────●──── 50%` |\n| `bar` | ▓ | ░ | `▓▓▓▓▓░░░░░ 50%` |\n| `blocks` | █ | ░ | `█████░░░░░ 50%` |\n| `blocks-line` | █ | ─ | `█████───── 50%` |\n| `capped` | ━ | ┄ | `━━━━╸┄┄┄┄┄ 50%` |\n| `dots` | ● | ○ | `●●●●●○○○○○ 50%` |\n| `filled` | ■ | □ | `■■■■■□□□□□ 50%` |\n| `geometric` | ▰ | ▱ | `▰▰▰▰▰▱▱▱▱▱ 50%` |\n| `line` | ━ | ┄ | `━━━━━┄┄┄┄┄ 50%` |\n| `squares` | ◼ | ◻ | `◼◼◼◼◼◻◻◻◻◻ 50%` |\n\n**Symbols:** `◔` Context (unicode) \u0026#8226; `C` Context (text)\n\n#### Model Context Limits\n\nConfigure context window limits for different model types. Defaults to 200K tokens for all models.\n\n```json\n\"modelContextLimits\": {\n  \"sonnet\": 1000000,\n  \"opus\": 200000\n}\n```\n\n**Available Model Types:**\n\n- `sonnet`: Claude Sonnet models (3.5, 4, etc.)\n- `opus`: Claude Opus models\n- `default`: Fallback for unrecognized models (200K)\n\n**Note:** Sonnet 4's 1M context window is currently in beta for tier 4+ users. Set `\"sonnet\": 1000000` when you have access.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eBlock\u003c/strong\u003e - Shows usage within current 5-hour billing window (Claude's rate limit period)\u003c/summary\u003e\n\n```json\n\"block\": {\n  \"enabled\": true,\n  \"displayStyle\": \"text\"\n}\n```\n\n**Options:**\n\n- `displayStyle`: Visual style for utilization display (see table below)\n\nRequires 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.\n\n**Display Styles:**\n\n| Style | Example |\n|-------|---------|\n| `text` (default) | `◱ 23% (4h 12m)` |\n| `bar` | `◱ ▪▪▫▫▫▫▫▫▫▫ 23% (4h 12m)` |\n| `blocks` | `◱ ██░░░░░░░░ 23% (4h 12m)` |\n| `blocks-line` | `◱ ██──────── 23% (4h 12m)` |\n| `capped` | `◱ ━╸┄┄┄┄┄┄┄┄ 23% (4h 12m)` |\n| `dots` | `◱ ●●○○○○○○○○ 23% (4h 12m)` |\n| `filled` | `◱ ■■□□□□□□□□ 23% (4h 12m)` |\n| `geometric` | `◱ ▰▰▱▱▱▱▱▱▱▱ 23% (4h 12m)` |\n| `line` | `◱ ━━┄┄┄┄┄┄┄┄ 23% (4h 12m)` |\n| `squares` | `◱ ◼◼◻◻◻◻◻◻◻◻ 23% (4h 12m)` |\n| `ball` | `◱ ──●─────── 23% (4h 12m)` |\n\n**Symbols:** `◱` Block (unicode) \u0026#8226; `B` Block (text)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWeekly\u003c/strong\u003e - Shows usage within 7-day rolling rate limit window\u003c/summary\u003e\n\n```json\n\"weekly\": {\n  \"enabled\": true,\n  \"displayStyle\": \"text\"\n}\n```\n\n**Options:**\n\n- `displayStyle`: Visual style for utilization display - same options as the block segment (see table above)\n\nOnly visible when Claude Code provides native `rate_limits.seven_day` data (Claude.ai Pro/Max subscribers). Hidden when the data is not available.\n\n**Symbols:** `◑` Weekly (unicode) \u0026#8226; `W` Weekly (text)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eMetrics\u003c/strong\u003e - Shows performance analytics from your Claude sessions\u003c/summary\u003e\n\n```json\n\"metrics\": {\n  \"enabled\": true,\n  \"showResponseTime\": true,\n  \"showLastResponseTime\": false,\n  \"showDuration\": true,\n  \"showMessageCount\": true,\n  \"showLinesAdded\": true,\n  \"showLinesRemoved\": true\n}\n```\n\n**Options:**\n\n- `showResponseTime`: Total API duration across all requests\n- `showLastResponseTime`: Individual response time for most recent query\n- `showDuration`: Total session duration\n- `showMessageCount`: Number of user messages sent\n- `showLinesAdded`: Lines of code added during session\n- `showLinesRemoved`: Lines of code removed during session\n\n**Symbols:**\n\n- Unicode: `⧖` Total API time \u0026#8226; `Δ` Last response \u0026#8226; `⧗` Session duration \u0026#8226; `⟐` Messages \u0026#8226; `+` Lines added \u0026#8226; `-` Lines removed\n- Text: `R` Total API time \u0026#8226; `L` Last response \u0026#8226; `T` Session duration \u0026#8226; `#` Messages \u0026#8226; `+` Lines added \u0026#8226; `-` Lines removed\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eVersion\u003c/strong\u003e - Shows Claude Code version\u003c/summary\u003e\n\n```json\n\"version\": {\n  \"enabled\": true\n}\n```\n\n**Display:** `v1.0.81`\n\n**Symbols:** `◈` Version (unicode) \u0026#8226; `V` Version (text)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTmux\u003c/strong\u003e - Shows tmux session name and window info when in tmux\u003c/summary\u003e\n\n```json\n\"tmux\": {\n  \"enabled\": true\n}\n```\n\n**Display:** `tmux:session-name`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSession ID\u003c/strong\u003e - Shows the current Claude session identifier\u003c/summary\u003e\n\n```json\n\"sessionId\": {\n  \"enabled\": false,\n  \"showIdLabel\": true\n}\n```\n\n**Options:**\n\n- `showIdLabel`: Show the `⌗` icon prefix before the session ID (default: `true`)\n\n**Display:** `⌗ a1b2c3d4-...`\n\n**Symbols:** `⌗` Session ID (unicode) \u0026#8226; `#` Session ID (text)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eEnv\u003c/strong\u003e - Shows the value of an environment variable\u003c/summary\u003e\n\n```json\n\"env\": {\n  \"enabled\": true,\n  \"variable\": \"CLAUDE_ACCOUNT\",\n  \"prefix\": \"Acct\"\n}\n```\n\n**Options:**\n\n- `variable` (required): Environment variable name to read\n- `prefix`: Label shown before the value. Defaults to the variable name\n\nHidden when the variable is unset or empty.\n\n**Symbols:** `⚙` Env (unicode) \u0026#8226; `$` Env (text)\n\n\u003c/details\u003e\n\n### Advanced Configuration\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eBudget Configuration\u003c/strong\u003e\u003c/summary\u003e\n\n```json\n\"budget\": {\n  \"session\": { \"amount\": 10.0, \"warningThreshold\": 80 },\n  \"today\": { \"amount\": 25.0, \"warningThreshold\": 80 },\n  \"block\": { \"amount\": 15.0, \"type\": \"cost\", \"warningThreshold\": 80 }\n}\n```\n\n**Options:**\n\n- `amount`: Budget limit (required for percentage display)\n- `type`: Budget type - `cost` (USD) | `tokens` (for token-based limits)\n- `warningThreshold`: Warning threshold percentage (default: 80)\n\n**Indicators:** `25%` Normal \u0026#8226; `+75%` Moderate (50-79%) \u0026#8226; `!85%` Warning (80%+)\n\n\u003e [!TIP]\n\u003e Claude's rate limits consider multiple factors beyond tokens (message count, length, attachments, model). See [Anthropic's usage documentation](https://support.anthropic.com/en/articles/11014257-about-claude-s-max-plan-usage) for details.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCharacter Sets\u003c/strong\u003e\u003c/summary\u003e\n\nChoose between Unicode symbols (requires Nerd Font) or ASCII text mode for maximum compatibility.\n\n```json\n{\n  \"display\": {\n    \"charset\": \"unicode\"\n  }\n}\n```\n\n**Options:**\n\n- `unicode` (default) - Uses Nerd Font icons and symbols\n- `text` - ASCII-only characters for terminals without Nerd Font\n\nThe charset setting works independently from separator styles, giving you 8 possible combinations:\n\n- `minimal` + `unicode` / `text` - No separators\n- `powerline` + `unicode` / `text` - Arrow separators (requires Nerd Font for unicode)\n- `capsule` + `unicode` / `text` - Rounded caps (requires Nerd Font for unicode)\n- `tui` + `unicode` / `text` - Bordered panel with rounded or ASCII box characters\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eLayout: Auto-Wrap, Multi-line, and Padding\u003c/strong\u003e\u003c/summary\u003e\n\n**Auto-Wrap** (enabled by default):\n\n```json\n{\n  \"display\": {\n    \"autoWrap\": true\n  }\n}\n```\n\nSegments flow naturally and wrap to new lines when they exceed the terminal width.\n\n**Multi-line Layout** for manual control:\n\n```json\n{\n  \"display\": {\n    \"lines\": [\n      {\n        \"segments\": {\n          \"directory\": { \"enabled\": true },\n          \"git\": { \"enabled\": true },\n          \"model\": { \"enabled\": true }\n        }\n      },\n      {\n        \"segments\": {\n          \"session\": { \"enabled\": true },\n          \"today\": { \"enabled\": true },\n          \"context\": { \"enabled\": true }\n        }\n      }\n    ]\n  }\n}\n```\n\n**Padding** - number of spaces on each side of segment text:\n\n```json\n{\n  \"display\": {\n    \"padding\": 1\n  }\n}\n```\n\nSet to `0` for compact, `1` (default) for standard spacing.\n\n\u003e [!NOTE]\n\u003e Claude Code system messages may truncate long status lines. Use `autoWrap` or manual multi-line layouts to prevent segment cutoff.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eColors and Custom Themes\u003c/strong\u003e\u003c/summary\u003e\n\nCreate custom themes and configure color compatibility:\n\n```json\n{\n  \"theme\": \"custom\",\n  \"display\": {\n    \"colorCompatibility\": \"auto\"\n  },\n  \"colors\": {\n    \"custom\": {\n      \"directory\": { \"bg\": \"#ff6600\", \"fg\": \"#ffffff\" },\n      \"git\": { \"bg\": \"#0066cc\", \"fg\": \"#ffffff\" },\n      \"session\": { \"bg\": \"#cc0099\", \"fg\": \"#ffffff\" }\n    }\n  }\n}\n```\n\n**Color Options:** `bg` (hex, `transparent`, `none`) \u0026#8226; `fg` (hex)\n\n**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:\n\n```json\n\"colors\": {\n  \"custom\": {\n    \"model\": { \"fg\": \"#e0d68a\" },\n    \"context\": { \"fg\": \"#7dcfff\" },\n    \"metrics.lastResponse\": { \"fg\": \"#bb9af7\" }\n  }\n}\n```\n\n**Compatibility Modes:** `auto` (default), `ansi`, `ansi256`, `truecolor`\n\n**Environment Variables:**\n\n- `NO_COLOR` - Disable all colors when set to any non-empty value (follows [NO_COLOR standard](https://no-color.org/))\n- `FORCE_COLOR` - Force enable color output (follows [FORCE_COLOR standard](https://force-color.org/)):\n  - `0` or `false` - Disable colors\n  - `1` or `true` - Force basic 16 colors (ANSI)\n  - `2` - Force 256 colors\n  - `3` - Force truecolor (16 million colors)\n  - Any other non-empty value - Force basic colors\n- `COLORTERM` - Auto-detected for truecolor support\n\n**Priority:** `FORCE_COLOR` overrides `NO_COLOR` (allowing color to be forced on even when NO_COLOR is set)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eTUI Panel Mode\u003c/strong\u003e\u003c/summary\u003e\n\n```json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"npx -y @owloops/claude-powerline@latest --style=tui\"\n  }\n}\n```\n\nBy 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.\n\n#### Grid Layout Configuration\n\nAdd `display.tui` to your config file to enable the grid engine:\n\n```json\n{\n  \"display\": {\n    \"style\": \"tui\",\n    \"tui\": {\n      \"fitContent\": true,\n      \"widthReserve\": 45,\n      \"minWidth\": 32,\n      \"maxWidth\": 120,\n      \"padding\": { \"horizontal\": 4 },\n      \"separator\": {\n        \"column\": \"  \",\n        \"divider\": \"─\"\n      },\n      \"box\": { ... },\n      \"title\": { ... },\n      \"footer\": { ... },\n      \"segments\": { ... },\n      \"breakpoints\": [ ... ]\n    }\n  }\n}\n```\n\n| Property | Type | Default | Description |\n|---|---|---|---|\n| `fitContent` | `boolean` | `false` | Panel shrinks to fit content instead of filling terminal width |\n| `widthReserve` | `number` | `45` | Characters reserved from terminal width (ignored when `fitContent: true`) |\n| `minWidth` | `number` | `32` | Minimum panel width |\n| `maxWidth` | `number` | `∞` | Maximum panel width |\n| `padding.horizontal` | `number` | `0` | Extra horizontal padding in `fitContent` mode |\n| `separator.column` | `string` | `\"  \"` | String placed between columns |\n| `separator.divider` | `string` | box char | Character used for `---` divider rows |\n| `box` | `object` | -- | Custom box-drawing characters (see below) |\n| `title` | `object` | -- | Title bar text configuration (see below) |\n| `footer` | `object` | -- | Footer text configuration (see below) |\n| `segments` | `object` | -- | Custom segment templates (see below) |\n| `breakpoints` | `array` | required | Responsive layout definitions |\n\n#### Breakpoints\n\nEach 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.\n\n```json\n\"breakpoints\": [\n  {\n    \"minWidth\": 80,\n    \"areas\": [\n      \"git.head      git.head     git.head     .               git.working\",\n      \"---\",\n      \"context.icon  context.bar  context.bar  context.pct     context.tokens\",\n      \"block.icon    block.bar    block.bar    block.value     block.time\"\n    ],\n    \"columns\": [\"auto\", \"1fr\", \"auto\", \"auto\", \"auto\"],\n    \"align\": [\"left\", \"left\", \"right\", \"right\", \"right\"]\n  },\n  {\n    \"minWidth\": 55,\n    \"areas\": [\n      \"git.head             git.working\",\n      \"---\",\n      \"context.bar          context.tokens\",\n      \"block                .\"\n    ],\n    \"columns\": [\"1fr\", \"auto\"],\n    \"align\": [\"left\", \"right\"]\n  },\n  {\n    \"minWidth\": 0,\n    \"areas\": [\n      \"git.head\",\n      \"git.working\",\n      \"---\",\n      \"context\",\n      \"block\"\n    ],\n    \"columns\": [\"1fr\"],\n    \"align\": [\"left\"]\n  }\n]\n```\n\n| Property | Type | Required | Description |\n|---|---|---|---|\n| `minWidth` | `number` | yes | Minimum panel width to activate this layout |\n| `areas` | `string[]` | yes | Grid rows, each string is one row of space-separated cell names |\n| `columns` | `string[]` | yes | Column sizing: `\"auto\"`, `\"1fr\"` / `\"2fr\"`, or a fixed number like `\"20\"` |\n| `align` | `string[]` | no | Per-column alignment: `\"left\"`, `\"center\"`, or `\"right\"` (defaults to `\"left\"`) |\n\n**Column sizing:**\n- `\"auto\"` - shrinks to the widest content in that column\n- `\"1fr\"`, `\"2fr\"` - fractional units that divide remaining space proportionally\n- `\"20\"` - fixed width in characters\n\n**Special area tokens:**\n- `.` - empty cell (renders as blank space)\n- `---` - full-width horizontal divider row\n\n**Spanning:** repeat the same name in adjacent cells to span columns:\n\n```\n\"context.bar  context.bar  context.bar  context.pct  context.tokens\"\n```\n\nHere `context.bar` spans the first three columns.\n\n#### Segment Names\n\nUse bare segment names to render the full pre-formatted segment:\n\n```\ncontext  block  session  today   weekly\ngit      dir    version  tmux    metrics\nactivity env\n```\n\n#### Dot-Notation Subsegments\n\nUse `segment.part` to place individual pieces of a segment into separate cells with independent alignment:\n\n| Segment | Parts |\n|---|---|\n| `git` | `icon`, `branch`, `status`, `ahead`, `behind`, `working`, `head` |\n| `context` | `icon`, `bar`, `pct`, `tokens` |\n| `block` | `icon`, `bar`, `value`, `time`, `budget` |\n| `session` | `icon`, `cost`, `tokens`, `budget` |\n| `today` | `icon`, `cost`, `label`, `budget` |\n| `weekly` | `icon`, `bar`, `pct`, `time` |\n| `metrics` | `response`, `responseIcon`, `responseVal`, `lastResponse`, `lastResponseIcon`, `lastResponseVal`, `added`, `addedIcon`, `addedVal`, `removed`, `removedIcon`, `removedVal` |\n| `activity` | `duration`, `durationIcon`, `durationVal`, `messages`, `messagesIcon`, `messagesVal` |\n| `version` | `icon`, `value` |\n| `tmux` | `label`, `value` |\n| `dir` | `value` |\n| `env` | `prefix`, `value` |\n\nExample, block segment with a progress bar, mirroring the context layout:\n\n```json\n\"areas\": [\n  \"context.icon  context.bar  context.bar  context.pct  context.tokens\",\n  \"block.icon    block.bar    block.bar    block.value  block.time\"\n]\n```\n\n\u003e [!NOTE]\n\u003e `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`.\n\n#### Custom Box Characters\n\nOverride individual box-drawing characters. Partial overrides merge with the charset default (`unicode` or `text`):\n\n```json\n\"box\": {\n  \"topLeft\": \"┌\",\n  \"topRight\": \"┐\",\n  \"bottomLeft\": \"└\",\n  \"bottomRight\": \"┘\",\n  \"horizontal\": \"─\",\n  \"vertical\": \"│\",\n  \"teeLeft\": \"├\",\n  \"teeRight\": \"┤\"\n}\n```\n\nOnly specify the characters you want to change. The rest inherit from the active charset.\n\n#### Title Bar\n\nConfigure the left and right text in the top border. Supports `{model}` and any `{segment}` or `{segment.part}` token that resolves from segment data:\n\n```json\n\"title\": {\n  \"left\": \"{model}\",\n  \"right\": \"{dir}\"\n}\n```\n\n| Property | Type | Default | Description |\n|---|---|---|---|\n| `left` | `string` | `\"{model}\"` | Left-side text (supports tokens) |\n| `right` | `string \\| false` | `\"claude-powerline\"` | Right-side text, or `false` to hide |\n\n#### Footer\n\nSame as the title bar, but on the bottom border. Defaults to no text (plain border):\n\n```json\n\"footer\": {\n  \"left\": \"{weekly}\",\n  \"right\": \"{metrics.lastResponse}\"\n}\n```\n\n| Property | Type | Default | Description |\n|---|---|---|---|\n| `left` | `string` | -- | Left-side footer text (supports tokens) |\n| `right` | `string` | -- | Right-side footer text (supports tokens) |\n\nTokens resolve any segment or subsegment reference: `{model}`, `{dir}`, `{git.head}`, `{block.value}`, `{metrics.lastResponse}`, etc.\n\n#### Segment Templates\n\nDefine custom compositions for composite cells using the `segments` key. This assembles multiple parts into a single cell:\n\n```json\n\"segments\": {\n  \"metrics.lastResponse\": {\n    \"items\": [\"{lastResponseIcon}\", \"{lastResponseVal}\"],\n    \"gap\": 1,\n    \"justify\": \"start\"\n  }\n}\n```\n\n| Property | Type | Default | Description |\n|---|---|---|---|\n| `items` | `string[]` | required | Part references like `\"{partName}\"` or literal strings |\n| `gap` | `number` | `1` | Spaces between items |\n| `justify` | `string` | `\"start\"` | `\"start\"` packs items left; `\"between\"` distributes across cell width |\n\nThe template name (e.g. `metrics.lastResponse`) can then be used as a cell name in `areas`.\n\n#### Automatic Culling\n\nEmpty 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.\n\n\u003e [!NOTE]\n\u003e 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.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCustom Segments (Shell Composition)\u003c/strong\u003e\u003c/summary\u003e\n\nExtend the statusline using shell composition:\n\n```json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"npx -y @owloops/claude-powerline \u0026\u0026 echo \\\" $(date +%H:%M)\\\"\",\n    \"padding\": 0\n  }\n}\n```\n\n\u003e [!NOTE]\n\u003e Use `tput` for colors: `setab \u003cbg\u003e` (background), `setaf \u003cfg\u003e` (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.\n\n\u003c/details\u003e\n\n\u003c/details\u003e\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues or pull requests.\n\nSee [CONTRIBUTORS.md](CONTRIBUTORS.md) for people who have contributed outside of GitHub PRs.\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowloops%2Fclaude-powerline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fowloops%2Fclaude-powerline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowloops%2Fclaude-powerline/lists"}