@owloops/claude-powerline 1.4.5 → 1.5.1

package/README.md

@@ -52,6 +52,8 @@
 
 - **Vim-style powerline** with proper arrows and segments
 - **Real-time session tracking** with costs and tokens
+- **Billing window tracking** with 5-hour block usage
+- **Daily usage monitoring** with budget alerts
 - **Performance metrics** with response times and burn rates
 - **Context monitoring** showing tokens used and auto-compact threshold
 - **Git integration** with branch, status, ahead/behind counts
@@ -119,15 +121,15 @@ Options are specified by command line flags. Overall configuration can also use
 
 ## Command Line Options
 
-| Option | Values | Description |
-|--------|--------|-------------|
-| `--theme` | `dark` (default), `light`, `nord`, `tokyo-night`, `rose-pine`, `custom` | Set color theme |
-| `--style` | `minimal` (default), `powerline` | Set separator style |
-| `--usage` | `cost`, `tokens`, `both`, `breakdown` | Set usage display format |
-| `--session-budget` | `AMOUNT` | Set session budget limit in USD |
-| `--config` | `PATH` | Use custom config file path |
-| `--install-fonts` | - | Install powerline fonts to system |
-| `-h, --help` | - | Show help message |
+| Option             | Values                                                                  | Description                       |
+| ------------------ | ----------------------------------------------------------------------- | --------------------------------- |
+| `--theme`          | `dark` (default), `light`, `nord`, `tokyo-night`, `rose-pine`, `custom` | Set color theme                   |
+| `--style`          | `minimal` (default), `powerline`                                        | Set separator style               |
+| `--usage`          | `cost`, `tokens`, `both`, `breakdown`                                   | Set usage display format          |
+| `--session-budget` | `AMOUNT`                                                                | Set session budget limit in USD   |
+| `--config`         | `PATH`                                                                  | Use custom config file path       |
+| `--install-fonts`  | -                                                                       | Install powerline fonts to system |
+| `-h, --help`       | -                                                                       | Show help message                 |
 
 > [!NOTE]  
 > Global options have CLI flags and environment variables. Individual segments are configured through config files.
@@ -144,7 +146,7 @@ Options are specified by command line flags. Overall configuration can also use
 ### Default Configuration
 
 ```bash
-# Shows directory, git, model, session usage (tokens), context info
+# Shows directory, git, model, session usage (tokens), block usage, context info
 # Uses dark theme, minimal style
 claude-powerline
 ```
@@ -171,8 +173,21 @@ claude-powerline --session-budget=50
 
 ### Status Indicators
 
+#### Symbols
+
+- **Session**: `§` Section sign for session costs
+- **Block**: `◱` Clock symbol for 5-hour blocks  
+- **Today**: `☉` Sun symbol for daily usage
+- **Git Branch**: `⎇` Branch symbol
+- **Git Tag**: `⌂` House/tag symbol
+- **Git SHA**: `♯` Hash symbol
+- **Git Stash**: `⧇` Double square symbol
+- **Metrics Delta**: `Δ` Delta for last response time
+
+#### Status States
+
 - **Git**: `✓` Clean, `●` Dirty, `⚠` Conflicts, `↑3` Ahead, `↓2` Behind remote
-- **Context**: `⊡ 34,040 (79%)` - Token count and percentage remaining until auto-compact (uses 75% of 200k limit)
+- **Context**: `◔ 34,040 (79%)` - Token count and percentage remaining until auto-compact
 - **Budget**: `25%` Normal (under 50%), `+75%` Moderate (50-79%), `!85%` Warning (80%+)
 
 ## Configuration
@@ -205,15 +220,31 @@ Configuration priority (top overrides bottom):
     "lines": [
       {
         "segments": {
-          "directory": { "enabled": true },
-          "git": { "enabled": true, "showSha": true },
+          "directory": { 
+            "enabled": true,
+            "useBasename": false
+          },
+          "git": { 
+            "enabled": true, 
+            "showSha": true,
+            "showWorkingTree": false,
+            "showOperation": false,
+            "showTag": false,
+            "showTimeSinceCommit": false,
+            "showStashCount": false,
+            "showUpstream": false,
+            "showRepoName": false
+          },
           "model": { "enabled": true },
           "session": { "enabled": true, "type": "tokens" },
+          "block": { "enabled": true, "type": "cost" },
+          "today": { "enabled": true, "type": "cost" },
           "context": { "enabled": true },
           "tmux": { "enabled": true },
           "metrics": { 
             "enabled": true,
             "showResponseTime": true,
+            "showLastResponseTime": false,
             "showDuration": true,
             "showMessageCount": true,
             "showCostBurnRate": false,
@@ -228,13 +259,51 @@ Configuration priority (top overrides bottom):
 
 ### Segment Details
 
-- **directory**: Current working directory name
-- **git**: Branch, status (clean/dirty), ahead/behind counts, SHA (optional)
+- **directory**: Current working directory name (supports `useBasename` option)
+- **git**: Branch, status, and extensive repository information (see Git Configuration below)
 - **model**: Current Claude model being used
 - **session**: Token usage and costs for current session
+- **block**: Usage within current 5-hour billing window
+- **today**: Total daily usage with budget monitoring
 - **context**: Context window usage and auto-compact threshold
 - **tmux**: Tmux session name and window info (when in tmux)
-- **metrics**: Performance analytics (response time, session duration, message count, burn rates)
+- **metrics**: Performance analytics (see Metrics Configuration below)
+
+#### Directory Configuration
+
+```json
+"directory": {
+  "enabled": true,
+  "useBasename": false  // Show only folder name instead of full path
+}
+```
+
+#### Git Configuration
+
+The git segment now supports extensive repository information:
+
+```json
+"git": {
+  "enabled": true,
+  "showSha": true,              // Show abbreviated commit SHA (♯ abc123)
+  "showWorkingTree": false,     // Show staged/unstaged/untracked counts ((+1 ~2 ?3))
+  "showOperation": false,        // Show ongoing operations (MERGE/REBASE/CHERRY-PICK)
+  "showTag": false,              // Show nearest tag (⌂ v1.5.0)
+  "showTimeSinceCommit": false, // Show time since last commit (⏰ 2h)
+  "showStashCount": false,      // Show stash count (⧇ 3)
+  "showUpstream": false,        // Show upstream branch (→ origin/main)
+  "showRepoName": false         // Show repository name
+}
+```
+
+**Git Status Indicators:**
+
+- `✓` Clean working tree
+- `●` Uncommitted changes
+- `⚠` Merge conflicts
+- `↑3` Commits ahead of upstream
+- `↓2` Commits behind upstream
+- `(+1 ~2 ?3)` Staged/Unstaged/Untracked file counts
 
 #### Metrics Configuration
 
@@ -243,24 +312,91 @@ The metrics segment displays performance analytics from your Claude sessions:
 ```json
 "metrics": {
   "enabled": true,
-  "showResponseTime": true,
-  "showDuration": true, 
-  "showMessageCount": true,
-  "showCostBurnRate": false,
-  "showTokenBurnRate": false
+  "showResponseTime": true,      // Average response time (`⧖ 3.2s`)
+  "showLastResponseTime": false, // Last response time (`Δ 2.8s`)
+  "showDuration": true,          // Session duration (`⧗ 28m`)
+  "showMessageCount": true,      // User message count (`⟐ 93`)
+  "showCostBurnRate": false,     // Cost per hour (`⟢ $1.20/h`)
+  "showTokenBurnRate": false     // Tokens per hour (`⟢ 450K/h`)
 }
 ```
 
-**Options:**
+**Metrics Display:**
 
-- `showResponseTime`: Average response time per message (`⧖ 3.2s`)
-- `showDuration`: Total session duration (`⧗ 28m`)
-- `showMessageCount`: Number of user messages (`⟐ 93`)
-- `showCostBurnRate`: Cost burn rate per hour (`⟢ $1.20/h`)
-- `showTokenBurnRate`: Token burn rate per hour (`⟢ 450K/h`)
+- `showResponseTime`: Average response time across all messages
+- `showLastResponseTime`: Time for the last response (shows `0.0s` while waiting)
+- `showDuration`: Total time since session started
+- `showMessageCount`: Number of user messages sent
+- `showCostBurnRate`: Spending rate per hour
+- `showTokenBurnRate`: Token consumption rate per hour
 
 ![Metrics Segment Example](images/claude-powerline-metrics.png)
 
+#### Usage Segments Configuration
+
+The powerline includes three complementary usage segments:
+
+```json
+{
+  "segments": {
+    "session": { "enabled": true, "type": "tokens" },
+    "block": { "enabled": true, "type": "cost" },
+    "today": { "enabled": true, "type": "cost" }
+  },
+  "budget": {
+    "session": { "amount": 10.0, "warningThreshold": 80 },
+    "today": { "amount": 25.0, "warningThreshold": 80 }
+  }
+}
+```
+
+**Segment Types:**
+
+- **session**: Real-time usage for current Claude conversation
+- **block**: Usage within current 5-hour billing window (Claude's rate limit period)
+- **today**: Total daily usage with budget monitoring
+
+**Display Options:**
+
+**Session & Today segments:**
+
+- `cost`: Show dollar amounts (`$0.05`)
+- `tokens`: Show token counts (`1.2K tokens`)
+- `both`: Show both (`$0.05 (1.2K)`)
+- `breakdown`: Show token breakdown (`1.2Kin + 0.8Kout + 1.5Kcached`)
+
+**Block segment** (always shows time remaining):
+
+- `cost`: Show cost + time (`$0.05 (2h 30m left)`)
+- `tokens`: Show tokens + time (`1.2K tokens (2h 30m left)`)
+
+**Budget Configuration:**
+
+```json
+"budget": {
+  "session": {
+    "amount": 10.0,
+    "warningThreshold": 80
+  },
+  "today": {
+    "amount": 25.0, 
+    "warningThreshold": 80
+  }
+}
+```
+
+**Budget Indicators:**
+
+- `25%` Normal (under 50%)
+- `+75%` Moderate (50-79%)
+- `!85%` Warning (80%+)
+
+**Why Use Different Segments?**
+
+- **session**: Track spending per conversation  
+- **block**: Monitor rate limits with time remaining (Claude throttles after 5-hour usage peaks)
+- **today**: Stay within daily budgets
+
 ### Multi-line Layout (Optional)
 
 To prevent segment cutoff, configure multiple lines:
@@ -279,6 +415,8 @@ To prevent segment cutoff, configure multiple lines:
       {
         "segments": {
           "session": { "enabled": true, "type": "tokens" },
+          "block": { "enabled": true, "type": "cost" },
+          "today": { "enabled": true, "type": "cost" },
           "context": { "enabled": true },
           "tmux": { "enabled": false },
           "metrics": { "enabled": true }
@@ -305,6 +443,8 @@ To customize colors, copy dark or light theme colors from `src/themes/` in the r
       "git": { "bg": "#0066cc", "fg": "#ffffff" },
       "model": { "bg": "#9900cc", "fg": "#ffffff" },
       "session": { "bg": "#cc0099", "fg": "#ffffff" },
+      "block": { "bg": "#404040", "fg": "#cccccc" },
+      "today": { "bg": "#303030", "fg": "#dddddd" },
       "context": { "bg": "#4a5568", "fg": "#ffffff" },
       "tmux": { "bg": "#228b22", "fg": "#ffffff" },
       "metrics": { "bg": "#374151", "fg": "#ffffff" }
@@ -377,21 +517,7 @@ export CLAUDE_POWERLINE_THEME=dark
 export CLAUDE_POWERLINE_STYLE=powerline
 export CLAUDE_POWERLINE_USAGE_TYPE=tokens
 export CLAUDE_POWERLINE_CONFIG=/path/to/config.json
-```
-
-## Troubleshooting
-
-**Arrows not displaying?** Run `claude-powerline --install-fonts` and set terminal font to a powerline-patched font.
-
-**Cost showing N/A?** Check that Claude session files are accessible in ~/.claude directory.
-
-**Tmux segment not showing?** Ensure you're in a tmux session and enable it in config.
-
-**Debug logging:** Enable debug output to troubleshoot issues:
-
-```bash
-export CLAUDE_POWERLINE_DEBUG=1
-# Then use Claude Code normally - debug info will appear in stderr
+export CLAUDE_POWERLINE_DEBUG=1  # Enable debug logging
 ```
 
 ## Contributing