Skip to content
Back to search

claude-powerline

MarketplaceWorks with Claude CodeGitHub

Beautiful vim-style powerline for Claude Code

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Owloops/claude-powerline with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Owloops/claude-powerline'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/owloops-claude-powerline/badge.svg)](/listings/owloops-claude-powerline)

HTML

<a href="/listings/owloops-claude-powerline"><img src="/api/listings/owloops-claude-powerline/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires 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.

Setup Wizard (Recommended)

The interactive wizard walks you through theme, style, font, segment, and budget selection.

# run inside Claude Code, one at a time
/plugin marketplace add Owloops/claude-powerline
/plugin install claude-powerline@claude-powerline
/powerline

The wizard writes `~/.claude/claude-powerline.json` and updates your `settings.json` automatically. Run `/powerline` again any time to reconfigure.

Manual Setup

Add to your Claude Code `settings.json`:

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

Start a Claude session and the statusline appears at the bottom. Using `npx` automatically downloads and runs the latest version without manual updates.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 31 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "claude-powerline",
  3. "owner": {
  4. "name": "Owloops"
  5. },
  6. "metadata": {
  7. "description": "Claude Powerline statusline setup wizard",
  8. "version": "1.0.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "claude-powerline",
  13. "source": "./plugin",
  14. "description": "Interactive setup wizard for theme, style, segment, and budget configuration",
  15. "version": "1.0.0",
  16. "author": {
  17. "name": "Owloops"
  18. },
  19. "homepage": "https://github.com/Owloops/claude-powerline",
  20. "repository": "https://github.com/Owloops/claude-powerline",
  21. "keywords": [
  22. "powerline",
  23. "statusline",
  24. "claude-code",
  25. "themes"
  26. ],
  27. "category": "statusline",
  28. "tags": ["statusline", "powerline", "customization"]
  29. }
  30. ]
  31. }
README.md · README · 1,093 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # Claude Powerline
  3. **A vim-style powerline statusline for Claude Code with real-time usage tracking, git integration, and custom themes.**
  4. ![License:MIT](https://img.shields.io/static/v1?label=License&message=MIT&color=blue&style=flat-square)
  5. [![npm downloads](https://img.shields.io/npm/dm/@owloops/claude-powerline.svg)](https://www.npmjs.com/package/@owloops/claude-powerline)
  6. [![npm version](https://img.shields.io/npm/v/@owloops/claude-powerline?style=flat-square)](https://www.npmjs.com/package/@owloops/claude-powerline)
  7. [![Install size](https://packagephobia.com/badge?p=@owloops/claude-powerline)](https://packagephobia.com/result?p=@owloops/claude-powerline)
  8. [![Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen)](https://www.npmjs.com/package/@owloops/claude-powerline)
  9. [![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/hesreallyhim/awesome-claude-code)
  10. <img src="images/demo-tui.gif" alt="Claude Powerline TUI Mode Demo" width="600"/>
  11. </div>
  12. ## Installation
  13. Requires 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.
  14. ### Setup Wizard (Recommended)
  15. The interactive wizard walks you through theme, style, font, segment, and budget selection.
  16. ```bash
  17. # run inside Claude Code, one at a time
  18. /plugin marketplace add Owloops/claude-powerline
  19. /plugin install claude-powerline@claude-powerline
  20. /powerline
  21. ```
  22. The wizard writes `~/.claude/claude-powerline.json` and updates your `settings.json` automatically. Run `/powerline` again any time to reconfigure.
  23. ### Manual Setup
  24. Add to your Claude Code `settings.json`:
  25. ```json
  26. {
  27. "statusLine": {
  28. "type": "command",
  29. "command": "npx -y @owloops/claude-powerline@latest --style=powerline"
  30. }
  31. }
  32. ```
  33. Start a Claude session and the statusline appears at the bottom. Using `npx` automatically downloads and runs the latest version without manual updates.
  34. If you have [Bun](https://bun.sh), `bunx --bun @owloops/claude-powerline --style=powerline` is a faster alternative. Keep the `--bun` flag, without it `bunx` runs the package with Node.
  35. ## Powerline Studio
  36. <a href="https://powerline.owloops.com/">
  37. <img src="images/powerline-studio.gif" alt="Powerline Studio visual configurator" width="700">
  38. </a>
  39. [**powerline.owloops.com**](https://powerline.owloops.com/) is a visual configurator for claude-powerline. Click segments in the preview to toggle options, switch styles and themes live, reorder, then copy or download the JSON into `~/.claude/claude-powerline.json`. Paste an existing config to edit it.
  40. <details>
  41. <summary><strong>Styles</strong></summary>
  42. <img src="images/claude-powerline-styles.png" alt="Claude Powerline Styles" width="700">
  43. </details>
  44. <details>
  45. <summary><strong>Themes</strong></summary>
  46. <img src="images/claude-powerline-themes.png" alt="Claude Powerline Themes" width="700">
  47. 6 built-in themes (dark, light, nord, tokyo-night, rose-pine, gruvbox) or [create your own](#configuration).
  48. </details>
  49. <details>
  50. <summary><h2>Configuration</h2></summary>
  51. **Config locations** (in priority order):
  52. - `./.claude-powerline.json` - Project-specific
  53. - `~/.claude/claude-powerline.json` - User config
  54. - `~/.config/claude-powerline/config.json` - XDG standard
  55. **Override priority:** CLI flags > Environment variables > Config files > Defaults
  56. Config files reload automatically, no restart needed.
  57. **Get example config:**
  58. ```bash
  59. curl -o ~/.claude/claude-powerline.json https://raw.githubusercontent.com/Owloops/claude-powerline/main/.claude-powerline.json
  60. ```
  61. <details>
  62. <summary><strong>CLI Options and Environment Variables</strong></summary>
  63. **CLI Options** (both `--arg value` and `--arg=value` syntax supported):
  64. - `--theme` - `dark` (default), `light`, `nord`, `tokyo-night`, `rose-pine`, `gruvbox`, `custom`
  65. - `--style` - `minimal` (default), `powerline`, `capsule`, `tui`
  66. - `--charset` - `unicode` (default), `text`
  67. - `--config` - Custom config file path
  68. - `--help` - Show help
  69. **Examples:**
  70. ```bash
  71. claude-powerline --theme=nord --style=powerline
  72. claude-powerline --theme=dark --style=capsule --charset=text
  73. claude-powerline --config=/path/to/config.json
  74. ```
  75. **Environment Variables:**
  76. ```bash
  77. export CLAUDE_POWERLINE_THEME=dark
  78. export CLAUDE_POWERLINE_STYLE=powerline
  79. export CLAUDE_POWERLINE_CONFIG=/path/to/config.json
  80. export CLAUDE_POWERLINE_DEBUG=1 # Enable debug logging
  81. export CLAUDE_POWERLINE_CACHE_DIR=/path/to/cache # Usage cache location (default: ~/.claude/powerline)
  82. ```
  83. </details>
  84. ### Segment Configuration
  85. <details>
  86. <summary><strong>Directory</strong> - Shows current working directory name</summary>
  87. ```json
  88. "directory": {
  89. "enabled": true,
  90. "style": "full"
  91. }
  92. ```
  93. **Options:**
  94. - `style`: Display format - `full` | `fish` | `basename`
  95. - `full`: Show complete path (e.g., `~/projects/claude-powerline`)
  96. - `fish`: Fish-shell style abbreviation (e.g., `~/p/claude-powerline`)
  97. - `basename`: Show only folder name (e.g., `claude-powerline`)
  98. In `--worktree` sessions, the directory segment automatically shows the original repo path instead of the worktree folder (no config required).
  99. </details>
  100. <details>
  101. <summary><strong>Git</strong> - Shows branch, status, and repository information</summary>
  102. ```json
  103. "git": {
  104. "enabled": true,
  105. "showSha": true,
  106. "showWorkingTree": false,
  107. "showOperation": false,
  108. "showTag": false,
  109. "showTimeSinceCommit": false,
  110. "showStashCount": false,
  111. "showAheadBehind": true,
  112. "showUpstream": false,
  113. "showRepoName": false
  114. }
  115. ```
  116. **Options:**
  117. - `showSha`: Show abbreviated commit SHA
  118. - `showWorkingTree`: Show staged/unstaged/untracked counts
  119. - `showOperation`: Show ongoing operations (MERGE/REBASE/CHERRY-PICK)
  120. - `showTag`: Show nearest tag
  121. - `showTimeSinceCommit`: Show time since last commit
  122. - `showStashCount`: Show stash count
  123. - `showAheadBehind`: Show ahead/behind arrows (default `true`)
  124. - `showUpstream`: Show the upstream branch name, e.g. `→origin/main`
  125. - `showRepoName`: Show repository name
  126. - `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
  127. 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`.
  128. **Symbols:**
  129. - Unicode: `⎇` Branch &#8226; `♯` SHA &#8226; `⌂` Tag &#8226; `⧇` Stash &#8226; `✓` Clean &#8226; `●` Dirty &#8226; `⚠` Conflicts &#8226; `↑3` Ahead &#8226; `↓2` Behind &#8226; `⧉` Worktree &#8226; `(+1 ~2 ?3)` Staged/Unstaged/Untracked
  130. - Text: `~` Branch &#8226; `#` SHA &#8226; `T` Tag &#8226; `S` Stash &#8226; `=` Clean &#8226; `*` Dirty &#8226; `!` Conflicts &#8226; `^3` Ahead &#8226; `v2` Behind &#8226; `W` Worktree &#8226; `(+1 ~2 ?3)` Staged/Unstaged/Untracked
  131. </details>
  132. <details>
  133. <summary><strong>Model</strong> - Shows current Claude model being used</summary>
  134. ```json
  135. "model": {
  136. "enabled": true
  137. }
  138. ```
  139. **Symbols:** `✱` Model (unicode) &#8226; `M` Model (text)
  140. </details>
  141. <details>
  142. <summary><strong>Session</strong> - Shows real-time usage for current Claude conversation</summary>
  143. ```json
  144. "session": {
  145. "enabled": true,
  146. "type": "tokens",
  147. "costSource": "calculated"
  148. }
  149. ```
  150. **Options:**
  151. - `type`: Display format - `cost` | `tokens` | `both` | `breakdown`
  152. - `costSource`: Cost calculation method - `calculated` (ccusage-style) | `official` (hook data)
  153. - `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
  154. **Symbols:** `§` Session (unicode) &#8226; `S` Session (text)
  155. </details>
  156. <details>
  157. <summary><strong>Today</strong> - Shows total daily usage with budget monitoring</summary>
  158. ```json
  159. "today": {
  160. "enabled": true,
  161. "type": "both"
  162. }
  163. ```
  164. **Options:**
  165. - `type`: Display format - `cost` | `tokens` | `both` | `breakdown`
  166. - `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
  167. **Symbols:** `☉` Today (unicode) &#8226; `D` Today (text)
  168. </details>
  169. <details>
  170. <summary><strong>Month</strong> - Shows total usage for the current calendar month with budget monitoring</summary>
  171. ```json
  172. "month": {
  173. "enabled": true,
  174. "type": "cost"
  175. }
  176. ```
  177. **Options:**
  178. - `type`: Display format - `cost` | `tokens` | `both` | `breakdown`
  179. - `showUnits`: Show the trailing `tokens` unit when `type` is `tokens` or `both` (default: `true`). Set to `false` to render `◫ $123.45 (4.4M)` instead of `◫ $123.45 (4.4M tokens)`. Only applies to the powerline/capsule/minimal styles; the `tui` style already renders tokens without a suffix
  180. Opt-in (`enabled: false` by default). Resets on the 1st of each month.
  181. `budget.month.amount` defaults to `500` (like `today`'s default of `50`) unless overridden. Set it to `0` to disable the percentage — omitting the `month` key entirely does **not** disable it, since the default still applies (see Budget Configuration below).
  182. **Symbols:** `◫` Month (unicode) &#8226; `Mo` Month (text)
  183. </details>
  184. <details>
  185. <summary><strong>Context</strong> - Shows context window usage and auto-compact threshold</summary>
  186. ```json
  187. "context": {
  188. "enabled": true,
  189. "showPercentageOnly": false,
  190. "displayStyle": "text",
  191. "autocompactBuffer": 33000
  192. }
  193. ```
  194. **Options:**
  195. - `showPercentageOnly`: Show only percentage remaining (default: false)
  196. - `displayStyle`: Visual style for context display (default: `"text"`)
  197. - `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
  198. - `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
  199. **Display Styles:**
  200. | Style | Filled | Empty | Example |
  201. |-------|--------|-------|---------|
  202. | `text` | -- | -- | `◔ 34,040 (79%)` |
  203. | `ball` | ─ | ─ | `─────●──── 50%` |
  204. | `bar` | ▓ | ░ | `▓▓▓▓▓░░░░░ 50%` |
  205. | `blocks` | █ | ░ | `█████░░░░░ 50%` |
  206. | `blocks-line` | █ | ─ | `█████───── 50%` |
  207. | `capped` | ━ | ┄ | `━━━━╸┄┄┄┄┄ 50%` |
  208. | `dots` | ● | ○ | `●●●●●○○○○○ 50%` |
  209. | `filled` | ■ | □ | `■■■■■□□□□□ 50%` |
  210. | `geometric` | ▰ | ▱ | `▰▰▰▰▰▱▱▱▱▱ 50%` |
  211. | `line` | ━ | ┄ | `━━━━━┄┄┄┄┄ 50%` |
  212. | `squares` | ◼ | ◻ | `◼◼◼◼◼◻◻◻◻◻ 50%` |
  213. **Symbols:** `◔` Context (unicode) &#8226; `C` Context (text)
  214. #### Model Context Limits
  215. **You normally don't need this.** Claude Code 2.0.65+ reports the real context window
  216. in its status line data (`context_window.context_window_size`), and that value is used
  217. automatically. It already accounts for 1M-context models, the `[1m]` model suffix, the
  218. 1M beta header, plan entitlements, and `CLAUDE_CODE_MAX_CONTEXT_TOKENS` — none of which
  219. can be inferred from the model name.
  220. `modelContextLimits` is only consulted when Claude Code reports no context window data
  221. at all, i.e. on versions older than 2.0.65.
  222. ```json
  223. "modelContextLimits": {
  224. "sonnet": 1000000,
  225. "opus": 200000
  226. }
  227. ```
  228. **Available Model Types:**
  229. - `sonnet`: Claude Sonnet models (3.5, 4, etc.)
  230. - `opus`: Claude Opus models
  231. - `default`: Fallback for unrecognized models (200K)
  232. </details>
  233. <details>
  234. <summary><strong>Block</strong> - Shows usage within current 5-hour billing window (Claude's rate limit period)</summary>
  235. ```json
  236. "block": {
  237. "enabled": true,
  238. "displayStyle": "text"
  239. }
  240. ```
  241. **Options:**
  242. - `displayStyle`: Visual style for utilization display (see table below)
  243. - `showPace`: Compare usage against an even spend over the window (default: `false`, see Pace below)
  244. 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.
  245. **Display Styles:**
  246. | Style | Example |
  247. |-------|---------|
  248. | `text` (default) | `◱ 23% (4h 12m)` |
  249. | `bar` | `◱ ▪▪▫▫▫▫▫▫▫▫ 23% (4h 12m)` |
  250. | `blocks` | `◱ ██░░░░░░░░ 23% (4h 12m)` |
  251. | `blocks-line` | `◱ ██──────── 23% (4h 12m)` |
  252. | `capped` | `◱ ━╸┄┄┄┄┄┄┄┄ 23% (4h 12m)` |
  253. | `dots` | `◱ ●●○○○○○○○○ 23% (4h 12m)` |
  254. | `filled` | `◱ ■■□□□□□□□□ 23% (4h 12m)` |
  255. | `geometric` | `◱ ▰▰▱▱▱▱▱▱▱▱ 23% (4h 12m)` |
  256. | `line` | `◱ ━━┄┄┄┄┄┄┄┄ 23% (4h 12m)` |
  257. | `squares` | `◱ ◼◼◻◻◻◻◻◻◻◻ 23% (4h 12m)` |
  258. | `ball` | `◱ ──●─────── 23% (4h 12m)` |
  259. **Pace:** `showPace` adds the usage an even spend would have reached by now, after the actual usage: `◱ 60%/40% (3h)` in text style, `◱ ▰▰▰▰◆▰▱▱▱▱ 60%/40% (3h)` in bar styles (`◆` over pace, `◇` otherwise, `◈` where it meets the `ball` style's ball). The `tui` style shows `60%/40%`, and its `block.bar`/`weekly.bar` grid cells mark the pace the same way.
  260. **Symbols:**
  261. - Unicode: `◱` Block &#8226; `◆`/`◇` Over/Under pace
  262. - Text: `B` Block &#8226; `!`/`:` Over/Under pace (`bar` style and `tui` only)
  263. </details>
  264. <details>
  265. <summary><strong>Weekly</strong> - Shows usage within 7-day rolling rate limit window</summary>
  266. ```json
  267. "weekly": {
  268. "enabled": true,
  269. "displayStyle": "text"
  270. }
  271. ```
  272. **Options:**
  273. - `displayStyle`: Visual style for utilization display - same options as the block segment (see table above)
  274. - `showPace`: Compare usage against an even spend over the window - same behavior as the block segment (see Pace above)
  275. Only visible when Claude Code provides native `rate_limits.seven_day` data (Claude.ai Pro/Max subscribers). Hidden when the data is not available.
  276. **Symbols:** `◑` Weekly (unicode) &#8226; `W` Weekly (text)
  277. </details>
  278. <details>
  279. <summary><strong>Metrics</strong> - Shows performance analytics from your Claude sessions</summary>
  280. ```json
  281. "metrics": {
  282. "enabled": true,
  283. "showResponseTime": true,
  284. "showLastResponseTime": false,
  285. "showDuration": true,
  286. "showMessageCount": true,
  287. "showLinesAdded": true,
  288. "showLinesRemoved": true
  289. }
  290. ```
  291. **Options:**
  292. - `showResponseTime`: Total API duration across all requests
  293. - `showLastResponseTime`: Individual response time for most recent query
  294. - `showDuration`: Total session duration
  295. - `showMessageCount`: Number of user messages sent
  296. - `showLinesAdded`: Lines of code added during session
  297. - `showLinesRemoved`: Lines of code removed during session
  298. **Symbols:**
  299. - Unicode: `⧖` Total API time &#8226; `Δ` Last response &#8226; `⧗` Session duration &#8226; `⟐` Messages &#8226; `+` Lines added &#8226; `-` Lines removed
  300. - Text: `R` Total API time &#8226; `L` Last response &#8226; `T` Session duration &#8226; `#` Messages &#8226; `+` Lines added &#8226; `-` Lines removed
  301. </details>
  302. <details>
  303. <summary><strong>Version</strong> - Shows Claude Code version</summary>
  304. ```json
  305. "version": {
  306. "enabled": true
  307. }
  308. ```
  309. **Display:** `v1.0.81`
  310. **Symbols:** `◈` Version (unicode) &#8226; `V` Version (text)
  311. </details>
  312. <details>
  313. <summary><strong>Agent</strong> - Shows active subagent name when Claude Code is invoked with <code>--agent</code> (hidden otherwise)</summary>
  314. ```json
  315. "agent": {
  316. "enabled": true,
  317. "showLabel": false
  318. }
  319. ```
  320. **Display:** `◇ researcher` (or `◇ agent: researcher` with `showLabel: true`)
  321. **Symbols:** `◇` Agent (unicode) &#8226; `&` Agent (text)
  322. </details>
  323. <details>
  324. <summary><strong>Thinking</strong> - Shows extended-thinking on/off state and/or reasoning effort level when provided by Claude Code</summary>
  325. ```json
  326. "thinking": {
  327. "enabled": true,
  328. "showEnabled": true,
  329. "showEffort": true
  330. }
  331. ```
  332. 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.
  333. **Display:** `✦ On · xhigh` (both shown) &#8226; `✦ On` (enabled only) &#8226; `✦ xhigh` (effort only)
  334. **Symbols:** `✦` Thinking (unicode) &#8226; `T` Thinking (text)
  335. </details>
  336. <details>
  337. <summary><strong>Output Style</strong> - Shows the active Claude Code output style (<code>default</code>, <code>Explanatory</code>, <code>Learning</code>, or a custom style)</summary>
  338. Opt-in (`enabled: false` by default).
  339. ```json
  340. "outputStyle": {
  341. "enabled": true,
  342. "showLabel": false,
  343. "hideDefault": false
  344. }
  345. ```
  346. 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.
  347. **Display:** `✎ Explanatory` (or `✎ style: Explanatory` with `showLabel: true`)
  348. **Symbols:** `✎` Output Style (unicode) &#8226; `OS` Output Style (text)
  349. 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.
  350. </details>
  351. <details>
  352. <summary><strong>Cache Timer</strong> - Shows time since last turn, tracking Claude's 5-minute prompt cache TTL</summary>
  353. Opt-in (`enabled: false` by default).
  354. ```json
  355. "cacheTimer": {
  356. "enabled": true
  357. }
  358. ```
  359. **Display:** `◴ 3:42` (m:ss under 5m) &#8226; `◴ 17m` (5–59m) &#8226; `◴ 1h+` (1 hour or more)
  360. **Color tiers:** healthy green (0–3m) → yellow warn (3–5m) → red critical (5m+). Hidden when `transcript_path` is unavailable.
  361. **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.
  362. **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):
  363. ```json
  364. "cacheTimer": {
  365. "enabled": true,
  366. "displayMode": "remaining"
  367. }
  368. ```
  369. 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).
  370. **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:
  371. ```json
  372. "cacheTimer": { "enabled": true, "displayMode": "remaining", "ttlSeconds": 300 }
  373. ```
  374. **TUI:** also available in grid templates via `{cacheTimer}`, `{cacheTimer.icon}`, and `{cacheTimer.value}`.
  375. **Symbols:** `◴` Cache timer (unicode) &#8226; `C!` Cache timer (text)
  376. > **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:
  377. > ```json
  378. > {
  379. > "statusLine": {
  380. > "type": "command",
  381. > "command": "npx -y @owloops/claude-powerline@latest",
  382. > "refreshInterval": 10
  383. > }
  384. > }
  385. > ```
  386. > `refreshInterval` is in seconds (min 1). `10` keeps the displayed value within ~10s of reality.
  387. </details>
  388. <details>
  389. <summary><strong>Tmux</strong> - Shows tmux session name and window info when in tmux</summary>
  390. ```json
  391. "tmux": {
  392. "enabled": true
  393. }
  394. ```
  395. **Display:** `tmux:session-name`
  396. </details>
  397. <details>
  398. <summary><strong>Session ID</strong> - Shows the current Claude session identifier</summary>
  399. ```json
  400. "sessionId": {
  401. "enabled": false,
  402. "showIdLabel": true
  403. }
  404. ```
  405. **Options:**
  406. - `showIdLabel`: Show the `⌗` icon prefix before the session ID (default: `true`)
  407. **Display:** `⌗ a1b2c3d4-...`
  408. **Symbols:** `⌗` Session ID (unicode) &#8226; `#` Session ID (text)
  409. </details>
  410. <details>
  411. <summary><strong>Env</strong> - Shows the value of an environment variable</summary>
  412. ```json
  413. "env": {
  414. "enabled": true,
  415. "variable": "CLAUDE_ACCOUNT",
  416. "prefix": "Acct"
  417. }
  418. ```
  419. **Options:**
  420. - `variable` (required): Environment variable name to read
  421. - `prefix`: Label shown before the value. Defaults to the variable name
  422. Hidden when the variable is unset or empty.
  423. **Symbols:** `⚙` Env (unicode) &#8226; `$` Env (text)
  424. </details>
  425. ### Advanced Configuration
  426. <details>
  427. <summary><strong>Budget Configuration</strong></summary>
  428. ```json
  429. "budget": {
  430. "session": { "amount": 10.0, "warningThreshold": 80 },
  431. "today": { "amount": 25.0, "warningThreshold": 80 },
  432. "month": { "amount": 500.0, "warningThreshold": 80 },
  433. "block": { "amount": 15.0, "type": "cost", "warningThreshold": 80 }
  434. }
  435. ```
  436. **Options:**
  437. - `amount`: Budget limit (required for percentage display)
  438. - `type`: Budget type - `cost` (USD) | `tokens` (for token-based limits)
  439. - `warningThreshold`: Warning threshold percentage (default: 80)
  440. - `showPercentage`: Show the `N%` suffix (default: `true`)
  441. - `showValue`: Show the base cost/token value (default: `true`)
  442. **Indicators:** `25%` Normal &#8226; `+75%` Moderate (50-79%) &#8226; `!85%` Warning (80%+)
  443. **Display toggles.** For `session`, `today`, and `month`, you can hide the percentage suffix, the base value, or both:
  444. ```json
  445. "budget": {
  446. "today": { "amount": 50, "showPercentage": false }
  447. }
  448. ```
  449. - `showPercentage: false` hides the `N%` suffix while keeping the budget configured (e.g. for warning thresholds).
  450. - `showValue: false` renders only the percentage (e.g. `◱ 15%`).
  451. - Both `false` hides the segment entirely.
  452. 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.
  453. > [!TIP]
  454. > 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.
  455. </details>
  456. <details>
  457. <summary><strong>Character Sets</strong></summary>
  458. Choose between Unicode symbols (requires Nerd Font) or ASCII text mode for maximum compatibility.
  459. ```json
  460. {
  461. "display": {
  462. "charset": "unicode"
  463. }
  464. }
  465. ```
  466. **Options:**
  467. - `unicode` (default) - Uses Nerd Font icons and symbols
  468. - `text` - ASCII-only characters for terminals without Nerd Font
  469. The charset setting works independently from separator styles, giving you 8 possible combinations:
  470. - `minimal` + `unicode` / `text` - No separators
  471. - `powerline` + `unicode` / `text` - Arrow separators (requires Nerd Font for unicode)
  472. - `capsule` + `unicode` / `text` - Rounded caps (requires Nerd Font for unicode)
  473. - `tui` + `unicode` / `text` - Bordered panel with rounded or ASCII box characters
  474. </details>
  475. <details>
  476. <summary><strong>Layout: Auto-Wrap, Multi-line, and Padding</strong></summary>
  477. **Auto-Wrap** (enabled by default):
  478. ```json
  479. {
  480. "display": {
  481. "autoWrap": true
  482. }
  483. }
  484. ```
  485. Segments flow naturally and wrap to new lines when they exceed the terminal width.
  486. `widthReserve` (default `45`) is the number of columns kept free when deciding where to wrap. Outside fullscreen rendering, Claude Code shows notifications (MCP server errors, auto-updates, context-low warnings) on the right side of the status line row, which is what the reserve leaves room for. In [fullscreen rendering](https://code.claude.com/docs/en/fullscreen) notifications get a row of their own, so you can lower it to use the full width. The same reserve sizes the `tui` panel, unless `display.tui.widthReserve` sets one for the grid layout:
  487. ```json
  488. {
  489. "display": {
  490. "autoWrap": true,
  491. "widthReserve": 2
  492. }
  493. }
  494. ```
  495. **Multi-line Layout** for manual control:
  496. ```json
  497. {
  498. "display": {
  499. "lines": [
  500. {
  501. "segments": {
  502. "directory": { "enabled": true },
  503. "git": { "enabled": true },
  504. "model": { "enabled": true }
  505. }
  506. },
  507. {
  508. "segments": {
  509. "session": { "enabled": true },
  510. "today": { "enabled": true },
  511. "context": { "enabled": true }
  512. }
  513. }
  514. ]
  515. }
  516. }
  517. ```
  518. **Padding** - number of spaces on each side of segment text:
  519. ```json
  520. {
  521. "display": {
  522. "padding": 1
  523. }
  524. }
  525. ```
  526. Set to `0` for compact, `1` (default) for standard spacing.
  527. **Show Icons** - hide the leading emblem on each segment for a text-only look:
  528. ```json
  529. {
  530. "display": {
  531. "showIcons": false
  532. }
  533. }
  534. ```
  535. 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.
  536. > [!NOTE]
  537. > Claude Code system messages may truncate long status lines. Use `autoWrap` or manual multi-line layouts to prevent segment cutoff.
  538. </details>
  539. <details>
  540. <summary><strong>Colors and Custom Themes</strong></summary>
  541. Create custom themes and configure color compatibility:
  542. ```json
  543. {
  544. "theme": "custom",
  545. "display": {
  546. "colorCompatibility": "auto"
  547. },
  548. "colors": {
  549. "custom": {
  550. "directory": { "bg": "#ff6600", "fg": "#ffffff" },
  551. "git": { "bg": "#0066cc", "fg": "#ffffff" },
  552. "session": { "bg": "#cc0099", "fg": "#ffffff" }
  553. }
  554. }
  555. }
  556. ```
  557. **Color Options:** `bg` (hex, `transparent`, `none`) &#8226; `fg` (hex) &#8226; `bold` (boolean, optional, defaults to `false`)
  558. **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:
  559. ```json
  560. "colors": {
  561. "custom": {
  562. "model": { "fg": "#e0d68a" },
  563. "context": { "fg": "#7dcfff" },
  564. "metrics.lastResponse": { "fg": "#bb9af7" }
  565. }
  566. }
  567. ```
  568. **Compatibility Modes:** `auto` (default), `ansi`, `ansi256`, `truecolor`
  569. **Environment Variables:**
  570. - `NO_COLOR` - Disable all colors when set to any non-empty value (follows [NO_COLOR standard](https://no-color.org/))
  571. - `FORCE_COLOR` - Force enable color output (follows [FORCE_COLOR standard](https://force-color.org/)):
  572. - `0` or `false` - Disable colors
  573. - `1` or `true` - Force basic 16 colors (ANSI)
  574. - `2` - Force 256 colors
  575. - `3` - Force truecolor (16 million colors)
  576. - Any other non-empty value - Force basic colors
  577. - `COLORTERM` - Auto-detected for truecolor support
  578. **Priority:** `FORCE_COLOR` overrides `NO_COLOR` (allowing color to be forced on even when NO_COLOR is set)
  579. </details>
  580. <details>
  581. <summary><strong>TUI Panel Mode</strong></summary>
  582. ```json
  583. {
  584. "statusLine": {
  585. "type": "command",
  586. "command": "npx -y @owloops/claude-powerline@latest --style=tui"
  587. }
  588. }
  589. ```
  590. 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.
  591. #### Grid Layout Configuration
  592. Add `display.tui` to your config file to enable the grid engine:
  593. ```json
  594. {
  595. "display": {
  596. "style": "tui",
  597. "tui": {
  598. "fitContent": true,
  599. "widthReserve": 45,
  600. "minWidth": 32,
  601. "maxWidth": 120,
  602. "padding": { "horizontal": 4 },
  603. "separator": {
  604. "column": " ",
  605. "divider": "─"
  606. },
  607. "box": { ... },
  608. "title": { ... },
  609. "footer": { ... },
  610. "segments": { ... },
  611. "breakpoints": [ ... ]
  612. }
  613. }
  614. }
  615. ```
  616. | Property | Type | Default | Description |
  617. |---|---|---|---|
  618. | `fitContent` | `boolean` | `false` | Panel shrinks to fit content instead of filling terminal width |
  619. | `widthReserve` | `number` | `display.widthReserve`, else `45` | Characters reserved from terminal width (ignored when `fitContent: true`) |
  620. | `minWidth` | `number` | `32` | Minimum panel width |
  621. | `maxWidth` | `number` | `∞` | Maximum panel width |
  622. | `padding.horizontal` | `number` | `0` | Extra horizontal padding in `fitContent` mode |
  623. | `separator.column` | `string` | `" "` | String placed between columns |
  624. | `separator.divider` | `string` | box char | Character used for `---` divider rows |
  625. | `box` | `object` | -- | Custom box-drawing characters (see below) |
  626. | `title` | `object` | -- | Title bar text configuration (see below) |
  627. | `footer` | `object` | -- | Footer text configuration (see below) |
  628. | `segments` | `object` | -- | Custom segment templates (see below) |
  629. | `breakpoints` | `array` | required | Responsive layout definitions |
  630. #### Breakpoints
  631. 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.
  632. ```json
  633. "breakpoints": [
  634. {
  635. "minWidth": 80,
  636. "areas": [
  637. "git.head git.head git.head . git.working",
  638. "---",
  639. "context.icon context.bar context.bar context.pct context.tokens",
  640. "block.icon block.bar block.bar block.value block.time"
  641. ],
  642. "columns": ["auto", "1fr", "auto", "auto", "auto"],
  643. "align": ["left", "left", "right", "right", "right"]
  644. },
  645. {
  646. "minWidth": 55,
  647. "areas": [
  648. "git.head git.working",
  649. "---",
  650. "context.bar context.tokens",
  651. "block ."
  652. ],
  653. "columns": ["1fr", "auto"],
  654. "align": ["left", "right"]
  655. },
  656. {
  657. "minWidth": 0,
  658. "areas": [
  659. "git.head",
  660. "git.working",
  661. "---",
  662. "context",
  663. "block"
  664. ],
  665. "columns": ["1fr"],
  666. "align": ["left"]
  667. }
  668. ]
  669. ```
  670. | Property | Type | Required | Description |
  671. |---|---|---|---|
  672. | `minWidth` | `number` | yes | Minimum panel width to activate this layout |
  673. | `areas` | `string[]` | yes | Grid rows, each string is one row of space-separated cell names |
  674. | `columns` | `string[]` | yes | Column sizing: `"auto"`, `"1fr"` / `"2fr"`, or a fixed number like `"20"` |
  675. | `align` | `string[]` | no | Per-column alignment: `"left"`, `"center"`, or `"right"` (defaults to `"left"`) |
  676. **Column sizing:**
  677. - `"auto"` - shrinks to the widest content in that column
  678. - `"1fr"`, `"2fr"` - fractional units that divide remaining space proportionally
  679. - `"20"` - fixed width in characters
  680. **Special area tokens:**
  681. - `.` - empty cell (renders as blank space)
  682. - `---` - full-width horizontal divider row
  683. **Spanning:** repeat the same name in adjacent cells to span columns:
  684. ```
  685. "context.bar context.bar context.bar context.pct context.tokens"
  686. ```
  687. Here `context.bar` spans the first three columns.
  688. #### Segment Names
  689. Use bare segment names to render the full pre-formatted segment:
  690. ```
  691. context block session today weekly
  692. git dir model version tmux
  693. metrics activity env agent thinking
  694. cacheTimer outputStyle month
  695. ```
  696. #### Dot-Notation Subsegments
  697. Use `segment.part` to place individual pieces of a segment into separate cells with independent alignment:
  698. | Segment | Parts |
  699. |---|---|
  700. | `session` | `icon`, `label`, `cost`, `tokens`, `budget` |
  701. | `block` | `icon`, `label`, `value`, `time`, `budget`, `bar` |
  702. | `today` | `icon`, `cost`, `label`, `budget` |
  703. | `month` | `icon`, `cost`, `label`, `budget` |
  704. | `weekly` | `icon`, `label`, `pct`, `time`, `bar` |
  705. | `git` | `icon`, `headVal`, `branch`, `status`, `ahead`, `behind`, `working`, `worktree`, `head` |
  706. | `context` | `icon`, `label`, `bar`, `pct`, `tokens` |
  707. | `metrics` | `response`, `responseIcon`, `responseVal`, `lastResponse`, `lastResponseIcon`, `lastResponseVal`, `added`, `addedIcon`, `addedVal`, `removed`, `removedIcon`, `removedVal` |
  708. | `activity` | `icon`, `duration`, `durationIcon`, `durationVal`, `messages`, `messagesIcon`, `messagesVal` |
  709. | `model` | `icon`, `value` |
  710. | `version` | `icon`, `value` |
  711. | `tmux` | `label`, `value` |
  712. | `dir` | `icon`, `value` |
  713. | `env` | `prefix`, `value` |
  714. | `agent` | `icon`, `name` |
  715. | `thinking` | `icon`, `enabled`, `effort` |
  716. | `cacheTimer` | `icon`, `value` |
  717. | `outputStyle` | `icon`, `name` |
  718. Example, block segment with a progress bar, mirroring the context layout:
  719. ```json
  720. "areas": [
  721. "context.icon context.bar context.bar context.pct context.tokens",
  722. "block.icon block.bar block.bar block.value block.time"
  723. ]
  724. ```
  725. > [!NOTE]
  726. > `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`.
  727. #### Custom Box Characters
  728. Override individual box-drawing characters. Partial overrides merge with the charset default (`unicode` or `text`):
  729. ```json
  730. "box": {
  731. "topLeft": "┌",
  732. "topRight": "┐",
  733. "bottomLeft": "└",
  734. "bottomRight": "┘",
  735. "horizontal": "─",
  736. "vertical": "│",
  737. "teeLeft": "├",
  738. "teeRight": "┤"
  739. }
  740. ```
  741. Only specify the characters you want to change. The rest inherit from the active charset.
  742. #### Title Bar
  743. Configure the left and right text in the top border. Supports `{model}` and any `{segment}` or `{segment.part}` token that resolves from segment data:
  744. ```json
  745. "title": {
  746. "left": "{model}",
  747. "right": "{dir}"
  748. }
  749. ```
  750. | Property | Type | Default | Description |
  751. |---|---|---|---|
  752. | `left` | `string` | `"{model}"` | Left-side text (supports tokens) |
  753. | `right` | `string \| false` | `"claude-powerline"` | Right-side text, or `false` to hide |
  754. #### Footer
  755. Same as the title bar, but on the bottom border. Defaults to no text (plain border):
  756. ```json
  757. "footer": {
  758. "left": "{weekly}",
  759. "right": "{metrics.lastResponse}"
  760. }
  761. ```
  762. | Property | Type | Default | Description |
  763. |---|---|---|---|
  764. | `left` | `string` | -- | Left-side footer text (supports tokens) |
  765. | `right` | `string` | -- | Right-side footer text (supports tokens) |
  766. Tokens resolve any segment or subsegment reference: `{model}`, `{dir}`, `{git.head}`, `{block.value}`, `{metrics.lastResponse}`, etc.
  767. #### Segment Templates
  768. Define custom compositions for composite cells using the `segments` key. This assembles multiple parts into a single cell:
  769. ```json
  770. "segments": {
  771. "metrics.lastResponse": {
  772. "items": ["{lastResponseIcon}", "{lastResponseVal}"],
  773. "gap": 1,
  774. "justify": "start"
  775. }
  776. }
  777. ```
  778. | Property | Type | Default | Description |
  779. |---|---|---|---|
  780. | `items` | `string[]` | required | Part references like `"{partName}"` or literal strings |
  781. | `gap` | `number` | `1` | Spaces between items |
  782. | `justify` | `string` | `"start"` | `"start"` packs items left; `"between"` distributes across cell width |
  783. The template name (e.g. `metrics.lastResponse`) can then be used as a cell name in `areas`.
  784. #### Automatic Culling
  785. 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.
  786. > [!NOTE]
  787. > 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.
  788. </details>
  789. <details>
  790. <summary><strong>Custom Segments (Shell Composition)</strong></summary>
  791. Extend the statusline using shell composition:
  792. ```json
  793. {
  794. "statusLine": {
  795. "type": "command",
  796. "command": "npx -y @owloops/claude-powerline && echo \" $(date +%H:%M)\"",
  797. "padding": 0
  798. }
  799. }
  800. ```
  801. > [!NOTE]
  802. > 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.
  803. </details>
  804. </details>
  805. ## Contributing
  806. Contributions are welcome! Please feel free to submit issues or pull requests.
  807. If your change touches how the statusline renders, run `npm run bench` (Node 22.18+) before opening the PR. It compares your branch with `main` and prints a before/after table to paste into the PR description. CI runs the same comparison on every PR that changes `src/`.
  808. See [CONTRIBUTORS.md](CONTRIBUTORS.md) for people who have contributed outside of GitHub PRs.
  809. ## License
  810. This project is licensed under the [MIT License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.