@owloops/claude-powerline 1.5.6 → 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 -312
  2. package/dist/index.js +9 -60
  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,345 +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
- Configuration priority (top overrides bottom):
160
+ - `./.claude-powerline.json` - Project-specific
161
+ - `~/.claude/claude-powerline.json` - User config
162
+ - `~/.config/claude-powerline/config.json` - XDG standard
206
163
 
207
- 1. CLI arguments (`--theme`, `--style`, `--usage`, `--session-budget`, `--config`)
208
- 2. Environment variables (`CLAUDE_POWERLINE_THEME`, `CLAUDE_POWERLINE_STYLE`, `CLAUDE_POWERLINE_USAGE_TYPE`, `CLAUDE_POWERLINE_SESSION_BUDGET`, `CLAUDE_POWERLINE_CONFIG`)
209
- 3. Config files (first found):
210
- - `./.claude-powerline.json` (project)
211
- - `~/.claude/claude-powerline.json` (user)
212
- - `~/.config/claude-powerline/config.json` (XDG)
213
- 4. Default values
164
+ **Override priority:** CLI flags → Environment variables → Config files → Defaults
214
165
 
215
- > [!NOTE]
216
- > Config files are reloaded automatically when changed - no need to restart Claude Code.
166
+ Config files reload automatically and no restart needed.
217
167
 
218
168
  ### Available Segments
219
169
 
220
- ```json
221
- {
222
- "display": {
223
- "lines": [
224
- {
225
- "segments": {
226
- "directory": {
227
- "enabled": true,
228
- "showBasename": false
229
- },
230
- "git": {
231
- "enabled": true,
232
- "showSha": true,
233
- "showWorkingTree": false,
234
- "showOperation": false,
235
- "showTag": false,
236
- "showTimeSinceCommit": false,
237
- "showStashCount": false,
238
- "showUpstream": false,
239
- "showRepoName": false
240
- },
241
- "model": { "enabled": true },
242
- "session": { "enabled": true, "type": "tokens" },
243
- "block": { "enabled": true, "type": "cost", "burnType": "cost" },
244
- "today": { "enabled": true, "type": "cost" },
245
- "context": { "enabled": true },
246
- "tmux": { "enabled": true },
247
- "metrics": {
248
- "enabled": true,
249
- "showResponseTime": true,
250
- "showLastResponseTime": false,
251
- "showDuration": true,
252
- "showMessageCount": true
253
- },
254
- "version": { "enabled": true }
255
- }
256
- }
257
- ]
258
- }
259
- }
260
- ```
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 | - |
261
182
 
262
- ### Segment Details
183
+ ### Segment Configuration
263
184
 
264
- - **directory**: Current working directory name (supports `showBasename` option)
265
- - **git**: Branch, status, and extensive repository information (see Git Configuration below)
266
- - **model**: Current Claude model being used
267
- - **session**: Token usage and costs for current session
268
- - **block**: Usage within current 5-hour billing window
269
- - **today**: Total daily usage with budget monitoring
270
- - **context**: Context window usage and auto-compact threshold
271
- - **tmux**: Tmux session name and window info (when in tmux)
272
- - **metrics**: Performance analytics (see Metrics Configuration below)
273
- - **version**: Claude Code version (e.g., v1.0.81)
185
+ #### Directory
274
186
 
275
- #### Directory Configuration
187
+ Shows current working directory name.
276
188
 
277
189
  ```json
278
190
  "directory": {
279
191
  "enabled": true,
280
- "showBasename": false // Show only folder name instead of full path
192
+ "showBasename": false
281
193
  }
282
194
  ```
283
195
 
284
- #### Git Configuration
196
+ **Options:**
285
197
 
286
- The git segment now supports extensive repository information:
198
+ - `showBasename`: Show only folder name instead of full path
199
+
200
+ #### Git
201
+
202
+ Shows branch, status, and repository information.
287
203
 
288
204
  ```json
289
205
  "git": {
290
206
  "enabled": true,
291
- "showSha": true, // Show abbreviated commit SHA (♯ abc123)
292
- "showWorkingTree": false, // Show staged/unstaged/untracked counts ((+1 ~2 ?3))
293
- "showOperation": false, // Show ongoing operations (MERGE/REBASE/CHERRY-PICK)
294
- "showTag": false, // Show nearest tag (⌂ v1.5.0)
295
- "showTimeSinceCommit": false, // Show time since last commit (⏰ 2h)
296
- "showStashCount": false, // Show stash count (⧇ 3)
297
- "showUpstream": false, // Show upstream branch (→ origin/main)
298
- "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
299
215
  }
300
216
  ```
301
217
 
302
- **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
303
228
 
304
- - `✓` Clean working tree
305
- - `●` Uncommitted changes
306
- - `⚠` Merge conflicts
307
- - `↑3` Commits ahead of upstream
308
- - `↓2` Commits behind upstream
309
- - `(+1 ~2 ?3)` Staged/Unstaged/Untracked file counts
229
+ **Symbols:**
310
230
 
311
- #### Metrics Configuration
231
+ - `⎇` Branch • `♯` SHA • `⌂` Tag • `⧇` Stash • `✓` Clean • `●` Dirty • `⚠` Conflicts • `↑3` Ahead • `↓2` Behind • `(+1 ~2 ?3)` Staged/Unstaged/Untracked
312
232
 
313
- The metrics segment displays performance analytics from your Claude sessions:
233
+ #### Metrics
234
+
235
+ Shows performance analytics from your Claude sessions.
314
236
 
315
237
  ```json
316
238
  "metrics": {
317
239
  "enabled": true,
318
- "showResponseTime": true, // Average response time (`⧖ 3.2s`)
319
- "showLastResponseTime": false, // Last response time (`Δ 2.8s`)
320
- "showDuration": true, // Session duration (`⧗ 28m`)
321
- "showMessageCount": true // User message count (`⟐ 93`)
240
+ "showResponseTime": true,
241
+ "showLastResponseTime": false,
242
+ "showDuration": true,
243
+ "showMessageCount": true
322
244
  }
323
245
  ```
324
246
 
325
- **Metrics Display:**
247
+ **Options:**
326
248
 
327
249
  - `showResponseTime`: Average response time across all messages
328
250
  - `showLastResponseTime`: Time for the last response (shows `0.0s` while waiting)
329
251
  - `showDuration`: Total time since session started
330
252
  - `showMessageCount`: Number of user messages sent
331
253
 
332
- ![Metrics Segment Example](images/claude-powerline-metrics.png)
254
+ **Symbols:**
255
+
256
+ - `⧖` Average response time • `Δ` Last response time • `⧗` Session duration • `⟐` Message count
333
257
 
334
- #### Usage Segments Configuration
258
+ #### Model
335
259
 
336
- The powerline includes three complementary usage segments:
260
+ Shows current Claude model being used.
337
261
 
338
262
  ```json
339
- {
340
- "segments": {
341
- "session": { "enabled": true, "type": "tokens" },
342
- "block": { "enabled": true, "type": "cost" },
343
- "today": { "enabled": true, "type": "cost" }
344
- },
345
- "budget": {
346
- "session": { "amount": 10.0, "warningThreshold": 80 },
347
- "today": { "amount": 25.0, "warningThreshold": 80 }
348
- }
263
+ "model": {
264
+ "enabled": true
265
+ }
266
+ ```
267
+
268
+ #### Context
269
+
270
+ Shows context window usage and auto-compact threshold.
271
+
272
+ ```json
273
+ "context": {
274
+ "enabled": true
349
275
  }
350
276
  ```
351
277
 
352
- **Segment Types:**
278
+ **Display:** `◔ 34,040 (79%)` - tokens used and percentage remaining until auto-compact
353
279
 
354
- - **session**: Real-time usage for current Claude conversation
355
- - **block**: Usage within current 5-hour billing window (Claude's rate limit period)
356
- - **today**: Total daily usage with budget monitoring
280
+ #### Tmux
357
281
 
358
- **Display Options:**
282
+ Shows tmux session name and window info when in tmux.
359
283
 
360
- **Session & Today segments:**
284
+ ```json
285
+ "tmux": {
286
+ "enabled": true
287
+ }
288
+ ```
361
289
 
362
- - `cost`: Show dollar amounts (`$0.05`)
363
- - `tokens`: Show token counts (`1.2K tokens`)
364
- - `both`: Show both (`$0.05 (1.2K)`)
365
- - `breakdown`: Show token breakdown (`1.2Kin + 0.8Kout + 1.5Kcached`)
290
+ #### Version
366
291
 
367
- **Block segment** (always shows time remaining):
292
+ Shows Claude Code version.
368
293
 
369
- - `cost`: Show cost + time (`$0.05 (2h 30m left)`)
370
- - `tokens`: Show tokens + time (`1.2K tokens (2h 30m left)`)
371
- - `both`: Show both cost and tokens + time
372
- - `time`: Show only time remaining
294
+ ```json
295
+ "version": {
296
+ "enabled": true
297
+ }
298
+ ```
299
+
300
+ **Display:** `v1.0.81`
373
301
 
374
- **Block burn rates** (configured with `burnType`):
302
+ #### Session
303
+
304
+ Shows real-time usage for current Claude conversation.
375
305
 
376
306
  ```json
377
- "block": { "enabled": true, "type": "cost", "burnType": "cost" }
307
+ "session": {
308
+ "enabled": true,
309
+ "type": "tokens"
310
+ }
378
311
  ```
379
312
 
380
- - `cost`: Show cost burn rate (`$0.05 | $1.20/h (2h 30m left)`)
381
- - `tokens`: Show token burn rate (`1.2K | 450K/h (2h 30m left)`)
382
- - `both`: Show both burn rates
383
- - `none`: Hide burn rates
313
+ **Options:**
314
+
315
+ - `type`: Display format - `cost` | `tokens` | `both` | `breakdown`
316
+
317
+ **Symbols:** `§` Session
384
318
 
385
- **Budget Configuration:**
319
+ #### Block
320
+
321
+ Shows usage within current 5-hour billing window (Claude's rate limit period).
386
322
 
387
323
  ```json
388
- "budget": {
389
- "session": {
390
- "amount": 10.0,
391
- "warningThreshold": 80
392
- },
393
- "today": {
394
- "amount": 25.0,
395
- "warningThreshold": 80
396
- }
324
+ "block": {
325
+ "enabled": true,
326
+ "type": "cost",
327
+ "burnType": "cost"
397
328
  }
398
329
  ```
399
330
 
400
- **Budget Indicators:**
331
+ **Options:**
401
332
 
402
- - `25%` Normal (under 50%)
403
- - `+75%` Moderate (50-79%)
404
- - `!85%` Warning (80%+)
333
+ - `type`: Display format - `cost` | `tokens` | `both` | `time`
334
+ - `burnType`: Burn rate display - `cost` | `tokens` | `both` | `none`
405
335
 
406
- **Why Use Different Segments?**
336
+ **Symbols:** `◱` Block
407
337
 
408
- - **session**: Track spending per conversation
409
- - **block**: Monitor rate limits with time remaining (Claude throttles after 5-hour usage peaks)
410
- - **today**: Stay within daily budgets
338
+ #### Today
411
339
 
412
- ### Multi-line Layout (Optional)
340
+ Shows total daily usage with budget monitoring.
413
341
 
414
- 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.
415
369
 
416
370
  ```json
417
371
  {
@@ -426,13 +380,9 @@ To prevent segment cutoff, configure multiple lines:
426
380
  },
427
381
  {
428
382
  "segments": {
429
- "session": { "enabled": true, "type": "tokens" },
430
- "block": { "enabled": true, "type": "cost", "burnType": "cost" },
431
- "today": { "enabled": true, "type": "cost" },
432
- "context": { "enabled": true },
433
- "tmux": { "enabled": false },
434
- "metrics": { "enabled": true },
435
- "version": { "enabled": true }
383
+ "session": { "enabled": true },
384
+ "today": { "enabled": true },
385
+ "context": { "enabled": true }
436
386
  }
437
387
  }
438
388
  ]
@@ -441,11 +391,11 @@ To prevent segment cutoff, configure multiple lines:
441
391
  ```
442
392
 
443
393
  > [!NOTE]
444
- > 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.
445
395
 
446
396
  ### Custom Colors
447
397
 
448
- 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.
449
399
 
450
400
  ```json
451
401
  {
@@ -454,92 +404,60 @@ To customize colors, copy dark or light theme colors from `src/themes/` in the r
454
404
  "custom": {
455
405
  "directory": { "bg": "#ff6600", "fg": "#ffffff" },
456
406
  "git": { "bg": "#0066cc", "fg": "#ffffff" },
457
- "model": { "bg": "#9900cc", "fg": "#ffffff" },
458
- "session": { "bg": "#cc0099", "fg": "#ffffff" },
459
- "block": { "bg": "#404040", "fg": "#cccccc" },
460
- "today": { "bg": "#303030", "fg": "#dddddd" },
461
- "context": { "bg": "#4a5568", "fg": "#ffffff" },
462
- "tmux": { "bg": "#228b22", "fg": "#ffffff" },
463
- "metrics": { "bg": "#374151", "fg": "#ffffff" },
464
- "version": { "bg": "#2d3748", "fg": "#ffffff" }
407
+ "session": { "bg": "#cc0099", "fg": "#ffffff" }
465
408
  }
466
409
  }
467
410
  }
468
411
  ```
469
412
 
470
- > [!TIP]
471
- > Use `"transparent"` or `"none"` for background colors to create a minimal look:
472
- > ```json
473
- > "directory": { "bg": "transparent", "fg": "#00ff00" }
474
- > ```
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.
475
420
 
476
421
  ## Custom Segments
477
422
 
478
- Extend the statusline by wrapping the command with shell composition:
423
+ Extend the statusline using shell composition for unlimited flexibility.
479
424
 
480
- ### Add Custom Segments
425
+ ### Simple Addition
481
426
 
482
- Use `tput` for colors that match your terminal theme:
427
+ Add custom segments using shell commands:
483
428
 
484
429
  ```json
485
430
  {
486
431
  "statusLine": {
487
432
  "type": "command",
488
- "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)\"",
489
434
  "padding": 0
490
435
  }
491
436
  }
492
437
  ```
493
438
 
494
- Common `tput` colors:
439
+ ### With Colors
495
440
 
496
- - `setab 1` (red bg) `setaf 15` (white fg)
497
- - `setab 2` (green bg) `setaf 0` (black fg)
498
- - `setab 4` (blue bg) `setaf 15` (white fg)
499
- - `setab 6` (cyan bg) `setaf 0` (black fg)
500
-
501
- ### Custom Wrapper Script
502
-
503
- Create `~/.local/bin/my-statusline`:
441
+ Use `tput` for terminal-compatible colors:
504
442
 
505
443
  ```bash
506
- #!/bin/bash
507
- # Option 1: Same line (continuous)
508
- cat | npx -y @owloops/claude-powerline | tr -d '\n'
509
- echo -n "$(tput setab 6)$(tput setaf 0) ⏱ $(date +%H:%M) $(tput sgr0)"
510
- echo "$(tput setab 2)$(tput setaf 0) ☁ $(curl -s wttr.in?format=%t 2>/dev/null || echo '?') $(tput sgr0)"
511
-
512
- # Option 2: Separate lines (multiline)
513
- # cat | npx -y @owloops/claude-powerline
514
- # echo "$(tput setab 6)$(tput setaf 0) ⏱ $(date +%H:%M) $(tput sgr0)"
515
- # 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
516
446
  ```
517
447
 
518
- Then use it in `settings.json`:
448
+ ### Advanced Script
519
449
 
520
- ```json
521
- {
522
- "statusLine": {
523
- "type": "command",
524
- "command": "/full/path/to/my-statusline",
525
- "padding": 0
526
- }
527
- }
528
- ```
529
-
530
- > [!TIP]
531
- > 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.
532
-
533
- ## Environment Variables
450
+ Create `~/.local/bin/my-statusline` for complex extensions:
534
451
 
535
452
  ```bash
536
- export CLAUDE_POWERLINE_THEME=dark
537
- export CLAUDE_POWERLINE_STYLE=powerline
538
- export CLAUDE_POWERLINE_USAGE_TYPE=tokens
539
- export CLAUDE_POWERLINE_CONFIG=/path/to/config.json
540
- 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)"
541
456
  ```
542
457
 
458
+ > [!TIP]
459
+ > Shell composition provides unlimited flexibility while keeping the core package secure.
460
+
543
461
  ## Contributing
544
462
 
545
463
  Contributions are welcome! Please feel free to submit issues or pull requests.