@owloops/claude-powerline 1.6.0 → 1.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +230 -314
  2. package/dist/index.js +7 -59
  3. package/dist/index.js.map +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -4,38 +4,41 @@
4
4
 
5
5
  **A vim-style powerline statusline for Claude Code with real-time usage tracking, git integration, and custom themes.**
6
6
 
7
- ![Language:TypeScript](https://img.shields.io/static/v1?label=Language&message=TypeScript&color=blue&style=flat-square)
8
7
  ![License:MIT](https://img.shields.io/static/v1?label=License&message=MIT&color=blue&style=flat-square)
8
+ [![npm downloads](https://img.shields.io/npm/dm/ccstatusline.svg)](https://www.npmjs.com/package/ccstatusline)
9
9
  [![npm version](https://img.shields.io/npm/v/@owloops/claude-powerline?style=flat-square)](https://www.npmjs.com/package/@owloops/claude-powerline)
10
+ [![Install size](https://packagephobia.com/badge?p=@owloops/claude-powerline)](https://packagephobia.com/result?p=@owloops/claude-powerline)
11
+
12
+ [![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/hesreallyhim/awesome-claude-code)
10
13
 
11
14
  <table>
12
15
  <tr>
13
16
  <td align="center">
14
- <img src="images/claude-powerline-dark.png" width="400" alt="Dark Theme"><br>
17
+ <img src="images/claude-powerline-dark.png" width="500" alt="Dark Theme"><br>
15
18
  <strong>Dark</strong>
16
19
  </td>
17
20
  <td align="center">
18
- <img src="images/claude-powerline-light.png" width="400" alt="Light Theme"><br>
21
+ <img src="images/claude-powerline-light.png" width="500" alt="Light Theme"><br>
19
22
  <strong>Light</strong>
20
23
  </td>
21
24
  </tr>
22
25
  <tr>
23
26
  <td align="center">
24
- <img src="images/claude-powerline-nord.png" width="400" alt="Nord Theme"><br>
27
+ <img src="images/claude-powerline-nord.png" width="500" alt="Nord Theme"><br>
25
28
  <strong>Nord</strong>
26
29
  </td>
27
30
  <td align="center">
28
- <img src="images/claude-powerline-tokyo-night.png" width="400" alt="Tokyo Night Theme"><br>
31
+ <img src="images/claude-powerline-tokyo-night.png" width="500" alt="Tokyo Night Theme"><br>
29
32
  <strong>Tokyo Night</strong>
30
33
  </td>
31
34
  </tr>
32
35
  <tr>
33
36
  <td align="center">
34
- <img src="images/claude-powerline-rose-pine.png" width="400" alt="Rose Pine Theme"><br>
37
+ <img src="images/claude-powerline-rose-pine.png" width="500" alt="Rose Pine Theme"><br>
35
38
  <strong>Rose Pine</strong>
36
39
  </td>
37
40
  <td align="center">
38
- <img src="images/claude-powerline-custom.png" width="400" alt="Custom Theme"><br>
41
+ <img src="images/claude-powerline-custom.png" width="500" alt="Custom Theme"><br>
39
42
  <em>Create your own!</em>
40
43
  </td>
41
44
  </tr>
@@ -46,26 +49,38 @@
46
49
 
47
50
  <table>
48
51
  <tr>
49
- <td width="50%" valign="top">
52
+ <td width="50%">
53
+
54
+ ### Usage Tracking
50
55
 
51
- ### Core Features
56
+ - Real-time session costs
57
+ - 5-hour billing window monitoring
58
+ - Daily budget alerts with percentages
59
+ - Token breakdown (input/output/cached)
52
60
 
53
- - **Vim-style powerline** with proper arrows and segments
54
- - **Real-time session tracking** with costs and tokens
55
- - **Billing window tracking** with 5-hour blocks and burn rates
56
- - **Daily usage monitoring** with budget alerts
57
- - **Performance metrics** with response times
58
- - **Context monitoring** showing tokens used and auto-compact threshold
59
- - **Git integration** with branch, status, ahead/behind counts
61
+ ### Git Integration
62
+
63
+ - Branch status with clean/dirty indicators
64
+ - Commits ahead/behind remote tracking
65
+ - Repository info (SHA, tags, stash count)
66
+ - Working tree staged/unstaged/untracked counts
60
67
 
61
68
  </td>
62
- <td width="50%" valign="top">
69
+ <td width="50%">
63
70
 
64
71
  ### Customization
65
72
 
66
- - **Custom themes** with full color control
67
- - **Budget monitoring** with percentage warnings
68
- - **Flexible configuration** via JSON files and environment variables
73
+ - 5 built-in themes (dark, light, nord, tokyo-night, rose-pine)
74
+ - Custom color configuration
75
+ - Powerline and minimal separator styles
76
+ - Multi-line layouts to prevent cutoff
77
+
78
+ ### Performance Metrics
79
+
80
+ - Average and last response times
81
+ - Session duration tracking
82
+ - Message count monitoring
83
+ - Context usage with auto-compact threshold
69
84
 
70
85
  </td>
71
86
  </tr>
@@ -73,347 +88,284 @@
73
88
 
74
89
  ## Installation
75
90
 
76
- ### Requirements
77
-
78
- - **Node.js 18+**
79
- - **Claude Code**
80
-
81
91
  ### Setup
82
92
 
83
- **Install powerline fonts:**
93
+ Requires Node.js 18+ and Claude Code.
94
+
95
+ **1. Install powerline fonts:**
84
96
 
85
97
  ```bash
86
98
  npx -y @owloops/claude-powerline --install-fonts
87
99
  ```
88
100
 
89
- > [!WARNING]
90
- > Without powerline fonts, arrow separators display as placeholder characters (�). The default `--style=minimal` mode resolves it by not using the powerline unicode.
91
-
92
- **Add to your Claude Code `settings.json`:**
101
+ **2. Add to your Claude Code `settings.json`:**
93
102
 
94
103
  ```json
95
104
  {
96
105
  "statusLine": {
97
106
  "type": "command",
98
107
  "command": "npx -y @owloops/claude-powerline@latest --style=powerline",
99
- "padding": 0
100
108
  }
101
109
  }
102
110
  ```
103
111
 
104
- > [!NOTE]
105
- > Using `npx` automatically downloads and runs the latest version, ensuring you always have the newest features and fixes without manual updates.
106
-
107
- **Start a Claude session:** It appears at the bottom during conversations.
112
+ **3. Start a Claude session** - the statusline appears at the bottom during conversations.
108
113
 
109
114
  ![Claude Code with powerline](images/claude-interface-with-powerline.png)
110
115
 
111
- > [!TIP]
112
- > The statusline shows your **current directory name** (not "claude powerline") and updates with live usage data during Claude conversations.
113
-
114
- ## Usage
115
-
116
- ```bash
117
- claude-powerline [OPTIONS]
118
- ```
119
-
120
- Options are specified by command line flags. Overall configuration can also use environment variables or configuration files.
121
-
122
- ## Command Line Options
123
-
124
- | Option | Values | Description |
125
- | ------------------ | ----------------------------------------------------------------------- | --------------------------------- |
126
- | `--theme` | `dark` (default), `light`, `nord`, `tokyo-night`, `rose-pine`, `custom` | Set color theme |
127
- | `--style` | `minimal` (default), `powerline` | Set separator style |
128
- | `--usage` | `cost`, `tokens`, `both`, `breakdown` | Set usage display format |
129
- | `--session-budget` | `AMOUNT` | Set session budget limit in USD |
130
- | `--config` | `PATH` | Use custom config file path |
131
- | `--install-fonts` | - | Install powerline fonts to system |
132
- | `-h, --help` | - | Show help message |
116
+ Using `npx` automatically downloads and runs the latest version without manual updates.
133
117
 
134
118
  > [!NOTE]
135
- > Global options have CLI flags and environment variables. Individual segments are configured through config files.
119
+ > If you encounter font issues, use `--style=minimal` (default) which works without powerline fonts.
136
120
 
137
- ### Usage Display Types
121
+ ## Usage
138
122
 
139
- - **cost**: Show dollar amounts (`$0.05`)
140
- - **tokens**: Show token counts (`1.2K tokens`)
141
- - **both**: Show both (`$0.05 (1.2K tokens)`)
142
- - **breakdown**: Show detailed token breakdown (`1.2Kin + 0.8Kout + 1.5Kcached`)
123
+ Once added to Claude Code settings, the statusline runs automatically. For customization:
143
124
 
144
- ## Examples
125
+ **CLI Options:**
145
126
 
146
- ### Default Configuration
127
+ - `--theme` - `dark` (default), `light`, `nord`, `tokyo-night`, `rose-pine`, `custom`
128
+ - `--style` - `minimal` (default), `powerline`
129
+ - `--config` - Custom config file path
130
+ - `--install-fonts` - Install powerline fonts
131
+ - `--help` - Show help
147
132
 
148
- ```bash
149
- # Shows directory, git, model, session usage (tokens), block usage, context info
150
- # Uses dark theme, minimal style
151
- claude-powerline
152
- ```
153
-
154
- ### Theme and Style
133
+ **Examples:**
155
134
 
156
135
  ```bash
157
- # Nord theme with powerline arrows
158
136
  claude-powerline --theme=nord --style=powerline
159
-
160
- # Tokyo Night theme, minimal style
161
- claude-powerline --theme=tokyo-night --style=minimal
137
+ claude-powerline --config=/path/to/config.json
162
138
  ```
163
139
 
164
- ### Usage Display
140
+ **Environment Variables:**
165
141
 
166
142
  ```bash
167
- # Show token breakdown instead of costs
168
- claude-powerline --usage=breakdown
169
-
170
- # Set session budget limit
171
- claude-powerline --session-budget=50
143
+ export CLAUDE_POWERLINE_THEME=dark
144
+ export CLAUDE_POWERLINE_STYLE=powerline
145
+ export CLAUDE_POWERLINE_CONFIG=/path/to/config.json
146
+ export CLAUDE_POWERLINE_DEBUG=1 # Enable debug logging
172
147
  ```
173
148
 
174
- ### Status Indicators
175
-
176
- #### Symbols
177
-
178
- - **Session**: `§` Section sign for session costs
179
- - **Block**: `◱` Clock symbol for 5-hour blocks
180
- - **Today**: `☉` Sun symbol for daily usage
181
- - **Git Branch**: `⎇` Branch symbol
182
- - **Git Tag**: `⌂` House/tag symbol
183
- - **Git SHA**: `♯` Hash symbol
184
- - **Git Stash**: `⧇` Double square symbol
185
- - **Metrics Delta**: `Δ` Delta for last response time
186
-
187
- #### Status States
188
-
189
- - **Git**: `✓` Clean, `●` Dirty, `⚠` Conflicts, `↑3` Ahead, `↓2` Behind remote
190
- - **Context**: `◔ 34,040 (79%)` - Token count and percentage remaining until auto-compact
191
- - **Budget**: `25%` Normal (under 50%), `+75%` Moderate (50-79%), `!85%` Warning (80%+)
192
-
193
149
  ## Configuration
194
150
 
195
- Create config file:
151
+ **Get example config:**
196
152
 
197
153
  ```bash
198
- # Copy example config from repository
154
+ # Download full-featured example config
199
155
  curl -o ~/.claude/claude-powerline.json https://raw.githubusercontent.com/Owloops/claude-powerline/main/.claude-powerline.json
200
156
  ```
201
157
 
202
- > [!IMPORTANT]
203
- > The example configuration showcases all available segments and features of the powerline.
158
+ **Config locations** (first found wins):
204
159
 
205
- ![All Segments Demo](images/claude-powerline-all-segments.png)
160
+ - `./.claude-powerline.json` - Project-specific
161
+ - `~/.claude/claude-powerline.json` - User config
162
+ - `~/.config/claude-powerline/config.json` - XDG standard
206
163
 
207
- Configuration priority (top overrides bottom):
164
+ **Override priority:** CLI flags → Environment variables → Config files → Defaults
208
165
 
209
- 1. CLI arguments (`--theme`, `--style`, `--usage`, `--session-budget`, `--config`)
210
- 2. Environment variables (`CLAUDE_POWERLINE_THEME`, `CLAUDE_POWERLINE_STYLE`, `CLAUDE_POWERLINE_USAGE_TYPE`, `CLAUDE_POWERLINE_SESSION_BUDGET`, `CLAUDE_POWERLINE_CONFIG`)
211
- 3. Config files (first found):
212
- - `./.claude-powerline.json` (project)
213
- - `~/.claude/claude-powerline.json` (user)
214
- - `~/.config/claude-powerline/config.json` (XDG)
215
- 4. Default values
216
-
217
- > [!NOTE]
218
- > Config files are reloaded automatically when changed - no need to restart Claude Code.
166
+ Config files reload automatically and no restart needed.
219
167
 
220
168
  ### Available Segments
221
169
 
222
- ```json
223
- {
224
- "display": {
225
- "lines": [
226
- {
227
- "segments": {
228
- "directory": {
229
- "enabled": true,
230
- "showBasename": false
231
- },
232
- "git": {
233
- "enabled": true,
234
- "showSha": true,
235
- "showWorkingTree": false,
236
- "showOperation": false,
237
- "showTag": false,
238
- "showTimeSinceCommit": false,
239
- "showStashCount": false,
240
- "showUpstream": false,
241
- "showRepoName": false
242
- },
243
- "model": { "enabled": true },
244
- "session": { "enabled": true, "type": "tokens" },
245
- "block": { "enabled": true, "type": "cost", "burnType": "cost" },
246
- "today": { "enabled": true, "type": "cost" },
247
- "context": { "enabled": true },
248
- "tmux": { "enabled": true },
249
- "metrics": {
250
- "enabled": true,
251
- "showResponseTime": true,
252
- "showLastResponseTime": false,
253
- "showDuration": true,
254
- "showMessageCount": true
255
- },
256
- "version": { "enabled": true }
257
- }
258
- }
259
- ]
260
- }
261
- }
262
- ```
170
+ | Segment | Description | Key Options |
171
+ |---------|-------------|-------------|
172
+ | `directory` | Current working directory | `showBasename` |
173
+ | `git` | Branch, status, repository info | `showSha`, `showWorkingTree`, `showTag`, `showStashCount`, `showOperation`, `showTimeSinceCommit`, `showUpstream`, `showRepoName` |
174
+ | `model` | Current Claude model | - |
175
+ | `session` | Real-time usage for conversation | `type`: `cost`\|`tokens`\|`both`\|`breakdown` |
176
+ | `block` | 5-hour billing window usage | `type`, `burnType`: `cost`\|`tokens`\|`both`\|`none` |
177
+ | `today` | Daily usage with budget monitoring | `type` |
178
+ | `context` | Context window usage | - |
179
+ | `tmux` | Tmux session info | - |
180
+ | `metrics` | Performance analytics | `showResponseTime`, `showLastResponseTime`, `showDuration`, `showMessageCount` |
181
+ | `version` | Claude Code version | - |
263
182
 
264
- ### Segment Details
183
+ ### Segment Configuration
265
184
 
266
- - **directory**: Current working directory name (supports `showBasename` option)
267
- - **git**: Branch, status, and extensive repository information (see Git Configuration below)
268
- - **model**: Current Claude model being used
269
- - **session**: Token usage and costs for current session
270
- - **block**: Usage within current 5-hour billing window
271
- - **today**: Total daily usage with budget monitoring
272
- - **context**: Context window usage and auto-compact threshold
273
- - **tmux**: Tmux session name and window info (when in tmux)
274
- - **metrics**: Performance analytics (see Metrics Configuration below)
275
- - **version**: Claude Code version (e.g., v1.0.81)
185
+ #### Directory
276
186
 
277
- #### Directory Configuration
187
+ Shows current working directory name.
278
188
 
279
189
  ```json
280
190
  "directory": {
281
191
  "enabled": true,
282
- "showBasename": false // Show only folder name instead of full path
192
+ "showBasename": false
283
193
  }
284
194
  ```
285
195
 
286
- #### Git Configuration
196
+ **Options:**
197
+
198
+ - `showBasename`: Show only folder name instead of full path
287
199
 
288
- The git segment now supports extensive repository information:
200
+ #### Git
201
+
202
+ Shows branch, status, and repository information.
289
203
 
290
204
  ```json
291
205
  "git": {
292
206
  "enabled": true,
293
- "showSha": true, // Show abbreviated commit SHA (♯ abc123)
294
- "showWorkingTree": false, // Show staged/unstaged/untracked counts ((+1 ~2 ?3))
295
- "showOperation": false, // Show ongoing operations (MERGE/REBASE/CHERRY-PICK)
296
- "showTag": false, // Show nearest tag (⌂ v1.5.0)
297
- "showTimeSinceCommit": false, // Show time since last commit (⏰ 2h)
298
- "showStashCount": false, // Show stash count (⧇ 3)
299
- "showUpstream": false, // Show upstream branch (→ origin/main)
300
- "showRepoName": false // Show repository name
207
+ "showSha": true,
208
+ "showWorkingTree": false,
209
+ "showOperation": false,
210
+ "showTag": false,
211
+ "showTimeSinceCommit": false,
212
+ "showStashCount": false,
213
+ "showUpstream": false,
214
+ "showRepoName": false
301
215
  }
302
216
  ```
303
217
 
304
- **Git Status Indicators:**
218
+ **Options:**
219
+
220
+ - `showSha`: Show abbreviated commit SHA
221
+ - `showWorkingTree`: Show staged/unstaged/untracked counts
222
+ - `showOperation`: Show ongoing operations (MERGE/REBASE/CHERRY-PICK)
223
+ - `showTag`: Show nearest tag
224
+ - `showTimeSinceCommit`: Show time since last commit
225
+ - `showStashCount`: Show stash count
226
+ - `showUpstream`: Show upstream branch
227
+ - `showRepoName`: Show repository name
305
228
 
306
- - `✓` Clean working tree
307
- - `●` Uncommitted changes
308
- - `⚠` Merge conflicts
309
- - `↑3` Commits ahead of upstream
310
- - `↓2` Commits behind upstream
311
- - `(+1 ~2 ?3)` Staged/Unstaged/Untracked file counts
229
+ **Symbols:**
312
230
 
313
- #### Metrics Configuration
231
+ - `⎇` Branch • `♯` SHA • `⌂` Tag • `⧇` Stash • `✓` Clean • `●` Dirty • `⚠` Conflicts • `↑3` Ahead • `↓2` Behind • `(+1 ~2 ?3)` Staged/Unstaged/Untracked
314
232
 
315
- The metrics segment displays performance analytics from your Claude sessions:
233
+ #### Metrics
234
+
235
+ Shows performance analytics from your Claude sessions.
316
236
 
317
237
  ```json
318
238
  "metrics": {
319
239
  "enabled": true,
320
- "showResponseTime": true, // Average response time (`⧖ 3.2s`)
321
- "showLastResponseTime": false, // Last response time (`Δ 2.8s`)
322
- "showDuration": true, // Session duration (`⧗ 28m`)
323
- "showMessageCount": true // User message count (`⟐ 93`)
240
+ "showResponseTime": true,
241
+ "showLastResponseTime": false,
242
+ "showDuration": true,
243
+ "showMessageCount": true
324
244
  }
325
245
  ```
326
246
 
327
- **Metrics Display:**
247
+ **Options:**
328
248
 
329
249
  - `showResponseTime`: Average response time across all messages
330
250
  - `showLastResponseTime`: Time for the last response (shows `0.0s` while waiting)
331
251
  - `showDuration`: Total time since session started
332
252
  - `showMessageCount`: Number of user messages sent
333
253
 
334
- ![Metrics Segment Example](images/claude-powerline-metrics.png)
254
+ **Symbols:**
255
+
256
+ - `⧖` Average response time • `Δ` Last response time • `⧗` Session duration • `⟐` Message count
335
257
 
336
- #### Usage Segments Configuration
258
+ #### Model
337
259
 
338
- The powerline includes three complementary usage segments:
260
+ Shows current Claude model being used.
339
261
 
340
262
  ```json
341
- {
342
- "segments": {
343
- "session": { "enabled": true, "type": "tokens" },
344
- "block": { "enabled": true, "type": "cost" },
345
- "today": { "enabled": true, "type": "cost" }
346
- },
347
- "budget": {
348
- "session": { "amount": 10.0, "warningThreshold": 80 },
349
- "today": { "amount": 25.0, "warningThreshold": 80 }
350
- }
263
+ "model": {
264
+ "enabled": true
351
265
  }
352
266
  ```
353
267
 
354
- **Segment Types:**
268
+ #### Context
355
269
 
356
- - **session**: Real-time usage for current Claude conversation
357
- - **block**: Usage within current 5-hour billing window (Claude's rate limit period)
358
- - **today**: Total daily usage with budget monitoring
270
+ Shows context window usage and auto-compact threshold.
359
271
 
360
- **Display Options:**
272
+ ```json
273
+ "context": {
274
+ "enabled": true
275
+ }
276
+ ```
361
277
 
362
- **Session & Today segments:**
278
+ **Display:** `◔ 34,040 (79%)` - tokens used and percentage remaining until auto-compact
363
279
 
364
- - `cost`: Show dollar amounts (`$0.05`)
365
- - `tokens`: Show token counts (`1.2K tokens`)
366
- - `both`: Show both (`$0.05 (1.2K)`)
367
- - `breakdown`: Show token breakdown (`1.2Kin + 0.8Kout + 1.5Kcached`)
280
+ #### Tmux
368
281
 
369
- **Block segment** (always shows time remaining):
282
+ Shows tmux session name and window info when in tmux.
370
283
 
371
- - `cost`: Show cost + time (`$0.05 (2h 30m left)`)
372
- - `tokens`: Show tokens + time (`1.2K tokens (2h 30m left)`)
373
- - `both`: Show both cost and tokens + time
374
- - `time`: Show only time remaining
284
+ ```json
285
+ "tmux": {
286
+ "enabled": true
287
+ }
288
+ ```
289
+
290
+ #### Version
375
291
 
376
- **Block burn rates** (configured with `burnType`):
292
+ Shows Claude Code version.
377
293
 
378
294
  ```json
379
- "block": { "enabled": true, "type": "cost", "burnType": "cost" }
295
+ "version": {
296
+ "enabled": true
297
+ }
380
298
  ```
381
299
 
382
- - `cost`: Show cost burn rate (`$0.05 | $1.20/h (2h 30m left)`)
383
- - `tokens`: Show token burn rate (`1.2K | 450K/h (2h 30m left)`)
384
- - `both`: Show both burn rates
385
- - `none`: Hide burn rates
300
+ **Display:** `v1.0.81`
301
+
302
+ #### Session
386
303
 
387
- **Budget Configuration:**
304
+ Shows real-time usage for current Claude conversation.
388
305
 
389
306
  ```json
390
- "budget": {
391
- "session": {
392
- "amount": 10.0,
393
- "warningThreshold": 80
394
- },
395
- "today": {
396
- "amount": 25.0,
397
- "warningThreshold": 80
398
- }
307
+ "session": {
308
+ "enabled": true,
309
+ "type": "tokens"
310
+ }
311
+ ```
312
+
313
+ **Options:**
314
+
315
+ - `type`: Display format - `cost` | `tokens` | `both` | `breakdown`
316
+
317
+ **Symbols:** `§` Session
318
+
319
+ #### Block
320
+
321
+ Shows usage within current 5-hour billing window (Claude's rate limit period).
322
+
323
+ ```json
324
+ "block": {
325
+ "enabled": true,
326
+ "type": "cost",
327
+ "burnType": "cost"
399
328
  }
400
329
  ```
401
330
 
402
- **Budget Indicators:**
331
+ **Options:**
403
332
 
404
- - `25%` Normal (under 50%)
405
- - `+75%` Moderate (50-79%)
406
- - `!85%` Warning (80%+)
333
+ - `type`: Display format - `cost` | `tokens` | `both` | `time`
334
+ - `burnType`: Burn rate display - `cost` | `tokens` | `both` | `none`
407
335
 
408
- **Why Use Different Segments?**
336
+ **Symbols:** `◱` Block
409
337
 
410
- - **session**: Track spending per conversation
411
- - **block**: Monitor rate limits with time remaining (Claude throttles after 5-hour usage peaks)
412
- - **today**: Stay within daily budgets
338
+ #### Today
413
339
 
414
- ### Multi-line Layout (Optional)
340
+ Shows total daily usage with budget monitoring.
415
341
 
416
- To prevent segment cutoff, configure multiple lines:
342
+ ```json
343
+ "today": {
344
+ "enabled": true,
345
+ "type": "cost"
346
+ }
347
+ ```
348
+
349
+ **Options:**
350
+
351
+ - `type`: Display format - `cost` | `tokens` | `both` | `breakdown`
352
+
353
+ **Symbols:** `☉` Today
354
+
355
+ ### Budget Configuration
356
+
357
+ ```json
358
+ "budget": {
359
+ "session": { "amount": 10.0, "warningThreshold": 80 },
360
+ "today": { "amount": 25.0, "warningThreshold": 80 }
361
+ }
362
+ ```
363
+
364
+ **Indicators:** `25%` Normal • `+75%` Moderate (50-79%) • `!85%` Warning (80%+)
365
+
366
+ ### Multi-line Layout
367
+
368
+ Prevent segment cutoff by organizing segments across multiple lines.
417
369
 
418
370
  ```json
419
371
  {
@@ -428,13 +380,9 @@ To prevent segment cutoff, configure multiple lines:
428
380
  },
429
381
  {
430
382
  "segments": {
431
- "session": { "enabled": true, "type": "tokens" },
432
- "block": { "enabled": true, "type": "cost", "burnType": "cost" },
433
- "today": { "enabled": true, "type": "cost" },
434
- "context": { "enabled": true },
435
- "tmux": { "enabled": false },
436
- "metrics": { "enabled": true },
437
- "version": { "enabled": true }
383
+ "session": { "enabled": true },
384
+ "today": { "enabled": true },
385
+ "context": { "enabled": true }
438
386
  }
439
387
  }
440
388
  ]
@@ -443,11 +391,11 @@ To prevent segment cutoff, configure multiple lines:
443
391
  ```
444
392
 
445
393
  > [!NOTE]
446
- > Claude Code system messages (e.g., Context left until auto-compact) may truncate the status line mid-sequence. Multi-line layouts help prevent segment cutoff.
394
+ > Claude Code system messages may truncate long status lines. Multi-line layouts prevent segment cutoff and improve readability.
447
395
 
448
396
  ### Custom Colors
449
397
 
450
- To customize colors, copy dark or light theme colors from `src/themes/` in the repository, then modify:
398
+ Create custom themes by defining segment colors.
451
399
 
452
400
  ```json
453
401
  {
@@ -456,92 +404,60 @@ To customize colors, copy dark or light theme colors from `src/themes/` in the r
456
404
  "custom": {
457
405
  "directory": { "bg": "#ff6600", "fg": "#ffffff" },
458
406
  "git": { "bg": "#0066cc", "fg": "#ffffff" },
459
- "model": { "bg": "#9900cc", "fg": "#ffffff" },
460
- "session": { "bg": "#cc0099", "fg": "#ffffff" },
461
- "block": { "bg": "#404040", "fg": "#cccccc" },
462
- "today": { "bg": "#303030", "fg": "#dddddd" },
463
- "context": { "bg": "#4a5568", "fg": "#ffffff" },
464
- "tmux": { "bg": "#228b22", "fg": "#ffffff" },
465
- "metrics": { "bg": "#374151", "fg": "#ffffff" },
466
- "version": { "bg": "#2d3748", "fg": "#ffffff" }
407
+ "session": { "bg": "#cc0099", "fg": "#ffffff" }
467
408
  }
468
409
  }
469
410
  }
470
411
  ```
471
412
 
472
- > [!TIP]
473
- > Use `"transparent"` or `"none"` for background colors to create a minimal look:
474
- > ```json
475
- > "directory": { "bg": "transparent", "fg": "#00ff00" }
476
- > ```
413
+ **Color Options:**
414
+
415
+ - `bg`: Background color (hex, `transparent`, or `none`)
416
+ - `fg`: Foreground/text color (hex)
417
+
418
+ > [!TIP]
419
+ > Copy existing theme colors from `src/themes/` in the repository as a starting point.
477
420
 
478
421
  ## Custom Segments
479
422
 
480
- Extend the statusline by wrapping the command with shell composition:
423
+ Extend the statusline using shell composition for unlimited flexibility.
481
424
 
482
- ### Add Custom Segments
425
+ ### Simple Addition
483
426
 
484
- Use `tput` for colors that match your terminal theme:
427
+ Add custom segments using shell commands:
485
428
 
486
429
  ```json
487
430
  {
488
431
  "statusLine": {
489
432
  "type": "command",
490
- "command": "npx -y @owloops/claude-powerline && echo \"$(tput setab 4)$(tput setaf 15) ⏱ $(date +%H:%M) $(tput sgr0)\"",
433
+ "command": "npx -y @owloops/claude-powerline && echo \" $(date +%H:%M)\"",
491
434
  "padding": 0
492
435
  }
493
436
  }
494
437
  ```
495
438
 
496
- Common `tput` colors:
439
+ ### With Colors
497
440
 
498
- - `setab 1` (red bg) `setaf 15` (white fg)
499
- - `setab 2` (green bg) `setaf 0` (black fg)
500
- - `setab 4` (blue bg) `setaf 15` (white fg)
501
- - `setab 6` (cyan bg) `setaf 0` (black fg)
502
-
503
- ### Custom Wrapper Script
504
-
505
- Create `~/.local/bin/my-statusline`:
441
+ Use `tput` for terminal-compatible colors:
506
442
 
507
443
  ```bash
508
- #!/bin/bash
509
- # Option 1: Same line (continuous)
510
- cat | npx -y @owloops/claude-powerline | tr -d '\n'
511
- echo -n "$(tput setab 6)$(tput setaf 0) ⏱ $(date +%H:%M) $(tput sgr0)"
512
- echo "$(tput setab 2)$(tput setaf 0) ☁ $(curl -s wttr.in?format=%t 2>/dev/null || echo '?') $(tput sgr0)"
513
-
514
- # Option 2: Separate lines (multiline)
515
- # cat | npx -y @owloops/claude-powerline
516
- # echo "$(tput setab 6)$(tput setaf 0) ⏱ $(date +%H:%M) $(tput sgr0)"
517
- # echo "$(tput setab 2)$(tput setaf 0) ☁ $(curl -s wttr.in?format=%t 2>/dev/null || echo '?') $(tput sgr0)"
444
+ echo "$(tput setab 4)$(tput setaf 15) ⏱ $(date +%H:%M) $(tput sgr0)"
445
+ # setab: background (1-7) | setaf: foreground (0-15) | sgr0: reset
518
446
  ```
519
447
 
520
- Then use it in `settings.json`:
448
+ ### Advanced Script
521
449
 
522
- ```json
523
- {
524
- "statusLine": {
525
- "type": "command",
526
- "command": "/full/path/to/my-statusline",
527
- "padding": 0
528
- }
529
- }
530
- ```
531
-
532
- > [!TIP]
533
- > Shell composition provides unlimited flexibility while keeping the core package secure - no arbitrary command execution needed. Use full absolute paths or ensure scripts are in your PATH.
534
-
535
- ## Environment Variables
450
+ Create `~/.local/bin/my-statusline` for complex extensions:
536
451
 
537
452
  ```bash
538
- export CLAUDE_POWERLINE_THEME=dark
539
- export CLAUDE_POWERLINE_STYLE=powerline
540
- export CLAUDE_POWERLINE_USAGE_TYPE=tokens
541
- export CLAUDE_POWERLINE_CONFIG=/path/to/config.json
542
- export CLAUDE_POWERLINE_DEBUG=1 # Enable debug logging
453
+ #!/bin/bash
454
+ npx -y @owloops/claude-powerline
455
+ echo "$(tput setab 6)$(tput setaf 0) ⏱ $(date +%H:%M) $(tput sgr0)"
543
456
  ```
544
457
 
458
+ > [!TIP]
459
+ > Shell composition provides unlimited flexibility while keeping the core package secure.
460
+
545
461
  ## Contributing
546
462
 
547
463
  Contributions are welcome! Please feel free to submit issues or pull requests.