ccstatusline-usage 2.1.7 → 2.1.11

package/README.md

@@ -9,21 +9,38 @@
                                                      
 </pre>
 
-# ccstatusline
+# ccstatusline-usage
 
 **🎨 A highly customizable status line formatter for Claude Code CLI**
-*Display model info, git branch, token usage, and other metrics in your terminal*
+*Display model info, git branch, token usage, API usage, and other metrics in your terminal*
 
-[![npm version](https://img.shields.io/npm/v/ccstatusline.svg)](https://www.npmjs.com/package/ccstatusline)
-[![npm downloads](https://img.shields.io/npm/dm/ccstatusline.svg)](https://www.npmjs.com/package/ccstatusline)
+> Fork of [sirmalloc/ccstatusline](https://github.com/sirmalloc/ccstatusline) with added **API usage widgets** (session/weekly utilization bars, reset timer, context bar).
+
+[![npm version](https://img.shields.io/npm/v/ccstatusline-usage.svg)](https://www.npmjs.com/package/ccstatusline-usage)
+[![npm downloads](https://img.shields.io/npm/dm/ccstatusline-usage.svg)](https://www.npmjs.com/package/ccstatusline-usage)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/sirmalloc/ccstatusline/blob/main/LICENSE)
-[![Node.js Version](https://img.shields.io/node/v/ccstatusline.svg)](https://nodejs.org)
-[![install size](https://packagephobia.com/badge?p=ccstatusline)](https://packagephobia.com/result?p=ccstatusline)
-[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/sirmalloc/ccstatusline/graphs/commit-activity)
+[![Node.js Version](https://img.shields.io/node/v/ccstatusline-usage.svg)](https://nodejs.org)
+[![install size](https://packagephobia.com/badge?p=ccstatusline-usage)](https://packagephobia.com/result?p=ccstatusline-usage)
+[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/pcvelz/ccstatusline-usage/graphs/commit-activity)
 
 [![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge.svg)](https://github.com/hesreallyhim/awesome-claude-code)
 [![ClaudeLog - A comprehensive knowledge base for Claude](https://claudelog.com/img/claude_log_badge.svg)](https://claudelog.com/)
 
+## Fork Enhancements
+
+This fork adds API-based usage widgets beyond the upstream:
+
+- **Session/Weekly Usage** - Real utilization from Anthropic API with progress bars
+- **Reset Timer** - Time until 5-hour session window resets
+- **Context Window Display** - Visual bar showing context usage
+- **Two-line Layout** - Session info on line 1, context on line 2
+
+### Enhanced Status Line Preview
+
+```
+Session: [████░░░░░░░░░░░] 27.0% | Weekly: [████████████░░░] 86.0% | 1:56 hr | Model: Opus 4.6 ▌▌▌ | Session ID: 0109b99d...
+  Context: [███████░░░░░░░░] 103k/200k (51%)
+```
 
 ![Demo](https://raw.githubusercontent.com/sirmalloc/ccstatusline/main/screenshots/demo.gif)
 
@@ -39,6 +56,7 @@
 - [API Documentation](#-api-documentation)
 - [Development](#️-development)
 - [Contributing](#-contributing)
+- [Uninstall](#️-uninstall)
 - [License](#-license)
 - [Related Projects](#-related-projects)
 
@@ -46,6 +64,14 @@
 
 ## 🆕 Recent Updates
 
+### [v2.1.11](https://github.com/pcvelz/ccstatusline-usage/releases/tag/v2.1.11) - Configurable extra usage balance
+
+- [pcvelz/ccstatusline-usage](https://github.com/pcvelz/ccstatusline-usage): **Configurable extra usage balance** — Add `extraUsageBalance` setting (in cents) to `~/.config/ccstatusline/settings.json` to override the API's monthly limit with your actual prepaid balance (e.g., `"extraUsageBalance": 5000` shows `Extra: €0.00/€50.00`)
+
+### [v2.1.8](https://github.com/pcvelz/ccstatusline-usage/releases/tag/v2.1.8) - Windows support for API usage widgets
+
+- [pcvelz/ccstatusline-usage](https://github.com/pcvelz/ccstatusline-usage): **Windows compatibility** — API usage widgets now work on Windows by using `os.homedir()` instead of `process.env.HOME` for credential and cache file paths
+
 ### [v2.1.7](https://github.com/pcvelz/ccstatusline-usage/releases/tag/v2.1.7) - Battery widget, extra usage fix & upstream sync
 
 - [pcvelz/ccstatusline-usage](https://github.com/pcvelz/ccstatusline-usage): **Battery widget** — shows `B: xx%` on macOS and Linux when on battery power (hidden when charging)
@@ -143,10 +169,13 @@
 ## ✨ Features
 
 - **📊 Real-time Metrics** - Display model name, git branch, token usage, session duration, block timer, and more
+- **📈 API Usage Tracking** - Real-time 5-hour session and weekly utilization from Anthropic API with progress bars
+- **⏱️ Reset Timer** - Countdown to when your 5-hour session window resets
 - **🎨 Fully Customizable** - Choose what to display and customize colors for each element
 - **⚡ Powerline Support** - Beautiful Powerline-style rendering with arrow separators, caps, and custom fonts
 - **📐 Multi-line Support** - Configure multiple independent status lines
 - **🖥️ Interactive TUI** - Built-in configuration interface using React/Ink
+- **🔎 Fast Widget Picker** - Add/change widgets by category with search and ranked matching
 - **⚙️ Global Options** - Apply consistent formatting across all widgets (padding, separators, bold, background)
 - **🚀 Cross-platform** - Works seamlessly with both Bun and Node.js
 - **🔧 Flexible Configuration** - Supports custom Claude Code config directory via `CLAUDE_CONFIG_DIR` environment variable
@@ -161,10 +190,10 @@
 
 ```bash
 # Run the configuration TUI with npm
-npx ccstatusline@latest
+npx -y ccstatusline-usage@latest
 
 # Or with Bun (faster)
-bunx ccstatusline@latest
+bunx -y ccstatusline-usage@latest
 ```
 
 ### Configure ccstatusline
@@ -189,6 +218,24 @@ The interactive configuration tool provides a terminal UI where you can:
 > $env:CLAUDE_CONFIG_DIR="C:\custom\path\.claude"
 > ```
 
+### Claude Code settings.json format
+
+When you install from the TUI, ccstatusline writes a `statusLine` command object to your Claude Code settings:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "npx -y ccstatusline-usage@latest",
+    "padding": 0
+  }
+}
+```
+
+Other supported command values are:
+- `bunx -y ccstatusline-usage@latest`
+- `ccstatusline` (for self-managed/global installs)
+
 ---
 
 ## 🪟 Windows Support
@@ -203,13 +250,13 @@ ccstatusline works seamlessly on Windows with full feature compatibility across
 irm bun.sh/install.ps1 | iex
 
 # Run ccstatusline
-bunx ccstatusline@latest
+bunx -y ccstatusline@latest
 ```
 
 #### Option 2: Using Node.js
 ```powershell
 # Using npm
-npx ccstatusline@latest
+npx -y ccstatusline@latest
 
 # Or with Yarn
 yarn dlx ccstatusline@latest
@@ -270,7 +317,7 @@ winget install Git.Git
 **Issue**: Permission errors during installation
 ```powershell
 # Use non-global installation (recommended)
-npx ccstatusline@latest
+npx -y ccstatusline@latest
 
 # Or run PowerShell as Administrator for global install
 ```
@@ -298,7 +345,7 @@ ccstatusline works perfectly in WSL environments:
 # Install in WSL Ubuntu/Debian
 curl -fsSL https://bun.sh/install | bash
 source ~/.bashrc
-bunx ccstatusline@latest
+bunx -y ccstatusline@latest
 ```
 
 **WSL Benefits**:
@@ -335,14 +382,22 @@ Configure ccstatusline in your Claude Code settings:
 **For Bun users**:
 ```json
 {
-  "statusLine": "bunx ccstatusline@latest"
+  "statusLine": {
+    "type": "command",
+    "command": "bunx -y ccstatusline@latest",
+    "padding": 0
+  }
 }
 ```
 
 **For npm users**:
 ```json
 {
-  "statusLine": "npx ccstatusline@latest"
+  "statusLine": {
+    "type": "command",
+    "command": "npx -y ccstatusline@latest",
+    "padding": 0
+  }
 }
 ```
 
@@ -350,11 +405,10 @@ Configure ccstatusline in your Claude Code settings:
 
 ### Performance on Windows
 
-ccstatusline is optimized for Windows performance:
-- **Bun runtime**: Significantly faster startup times on Windows
-- **Caching**: Intelligent caching of git status and file operations
-- **Async operations**: Non-blocking command execution
-- **Memory efficient**: Minimal resource usage
+ccstatusline includes Windows-specific runtime behavior:
+- **UTF-8 piped output fix**: In piped mode, it attempts to set code page `65001` for reliable symbol rendering
+- **Path compatibility**: Git and CWD widgets handle both `/` and `\` separators
+- **Block timer cache**: Cached block metrics reduce repeated JSONL scanning
 
 ### Windows-Specific Widget Behavior
 
@@ -371,17 +425,31 @@ Some widgets have Windows-specific optimizations:
 
 Once configured, ccstatusline automatically formats your Claude Code status line. The status line appears at the bottom of your terminal during Claude Code sessions.
 
+### Runtime Modes
+
+- **Interactive mode (TUI)**: Launches when there is no stdin input
+- **Piped mode (renderer)**: Parses Claude Code status JSON from stdin and prints one or more formatted lines
+
+```bash
+# Interactive TUI
+bun run start
+
+# Piped mode with example payload
+bun run example
+```
+
 ### 📊 Available Widgets
 
 - **Model Name** - Shows the current Claude model (e.g., "Claude 3.5 Sonnet")
 - **Git Branch** - Displays current git branch name
 - **Git Changes** - Shows uncommitted insertions/deletions (e.g., "+42,-10")
+- **Git Root Dir** - Shows the git repository root directory name
 - **Git Worktree** - Shows the name of the current git worktree
 - **Session Clock** - Shows elapsed time since session start (e.g., "2hr 15m")
 - **Session Cost** - Shows total session cost in USD (e.g., "$1.23")
 - **Session Name** - Shows the session name set via `/rename` command in Claude Code
 - **Block Timer** - Shows time elapsed in current 5-hour block or progress bar
-- **Current Working Directory** - Shows current working directory with configurable path segments
+- **Current Working Directory** - Shows current working directory with segment limit, fish-style abbreviation, and optional `~` home abbreviation
 - **Version** - Shows Claude Code version
 - **Output Style** - Shows the currently set output style in Claude Code
 - **Tokens Input** - Shows input tokens used
@@ -389,15 +457,20 @@ Once configured, ccstatusline automatically formats your Claude Code status line
 - **Tokens Cached** - Shows cached tokens used
 - **Tokens Total** - Shows total tokens used
 - **Context Length** - Shows current context length in tokens
-- **Context Percentage** - Shows percentage of context limit used (dynamic: 1M for Sonnet 4.5 with `[1m]` suffix, 200k otherwise)
-- **Context Percentage (usable)** - Shows percentage of usable context (dynamic: 800k for Sonnet 4.5 with `[1m]` suffix, 160k otherwise, accounting for auto-compact at 80%)
+- **Context Percentage** - Shows percentage of context limit used (dynamic: 1M for model IDs with `[1m]` suffix, 200k otherwise)
+- **Context Percentage (usable)** - Shows percentage of usable context (dynamic: 800k for model IDs with `[1m]` suffix, 160k otherwise, accounting for auto-compact at 80%)
 - **Terminal Width** - Shows detected terminal width (for debugging)
 - **Memory Usage** - Shows system memory usage (used/total, e.g., "Mem: 12.4G/16.0G")
 - **Battery** - Shows battery percentage on macOS and Linux (only visible when on battery power, hidden when charging)
+- **Claude Session ID** - Shows the current Claude Code session ID (compact: 8-char truncation)
+- **Session Usage** *(ccstatusline-usage)* - Shows 5-hour session API utilization as a progress bar (e.g., "Session: [███░░░░░░░░░░░░] 20%")
+- **Weekly Usage** *(ccstatusline-usage)* - Shows 7-day API utilization as a progress bar (e.g., "Weekly: [██░░░░░░░░░░░░░] 12%")
+- **Reset Timer** *(ccstatusline-usage)* - Shows time until session limit resets (e.g., "4:30 hr"), or extra usage spending when weekly budget is exhausted
+- **Context Bar** *(ccstatusline-usage)* - Shows context window usage as a progress bar (e.g., "Context: [████░░░░░░░░░░░] 50k/200k (25%)")
 - **Custom Text** - Add your own custom text to the status line
 - **Custom Command** - Execute shell commands and display their output (refreshes whenever the statusline is updated by Claude Code)
-- **Separator** - Visual divider between widgets (customizable: |, -, comma, space)
-- **Flex Separator** - Expands to fill available space
+- **Separator** - Visual divider between widgets (customizable: |, -, comma, space; available when Powerline mode is off and no default separator is configured)
+- **Flex Separator** - Expands to fill available space (available when Powerline mode is off)
 
 ---
 
@@ -467,6 +540,23 @@ Some widgets support "raw value" mode which displays just the value without a la
 - Normal: `Block: 3hr 45m` → Raw: `3hr 45m`
 - Normal: `Ctx: 18.6k` → Raw: `18.6k`
 
+### ⌨️ Widget Editor Keybinds
+
+Common controls in the line editor:
+- `a` add widget
+- `i` insert widget
+- `Enter` enter/exit move mode
+- `d` delete selected widget
+- `r` toggle raw value (supported widgets)
+- `m` cycle merge mode (`off` → `merge` → `merge no padding`)
+
+Widget-specific shortcuts:
+- **Git widgets**: `h` toggle hide `no git` output
+- **Context % widgets**: `l` toggle used vs remaining display
+- **Block Timer**: `p` cycle display mode (time/full bar/short bar)
+- **Current Working Dir**: `h` home abbreviation, `s` segment editor, `f` fish-style path
+- **Custom Command**: `e` command, `w` max width, `t` timeout, `p` preserve ANSI colors
+
 ---
 
 ### 🔧 Custom Widgets
@@ -483,6 +573,8 @@ Execute shell commands and display their output dynamically:
 - Receives the full Claude Code JSON data via stdin (model info, session ID, transcript path, etc.)
 - Displays command output inline in your status line
 - Configurable timeout (default: 1000ms)
+- Optional max-width truncation
+- Optional ANSI color preservation (`preserve colors`)
 - Examples:
   - `pwd | xargs basename` - Show current directory name
   - `node -v` - Display Node.js version
@@ -554,7 +646,7 @@ The documentation will be generated in the `docs/` directory and can be viewed b
 
 - [Bun](https://bun.sh) (v1.0+)
 - Git
-- Node.js 18+ (optional, for npm publishing)
+- Node.js 14+ (optional, for running the built `dist/ccstatusline.js` binary or npm publishing)
 
 ### Setup
 
@@ -570,13 +662,38 @@ bun install
 ### Development Commands
 
 ```bash
-# Run in TUI mode (configuration)
-bun run src/ccstatusline.ts
+# Run in TUI mode
+bun run start
+
+# Test piped mode with example payload
+bun run example
+
+# Run tests
+bun test
+
+# Run typecheck + eslint autofix
+bun run lint
 
 # Build for distribution
 bun run build
+
+# Generate TypeDoc documentation
+bun run docs
 ```
 
+### Configuration Files
+
+- `~/.config/ccstatusline/settings.json` - ccstatusline UI/render settings
+- `~/.claude/settings.json` - Claude Code settings (`statusLine` command object)
+- `~/.cache/ccstatusline/block-cache-*.json` - block timer cache (keyed by Claude config directory hash)
+
+If you use a custom Claude config location, set `CLAUDE_CONFIG_DIR` and ccstatusline will read/write that path instead of `~/.claude`.
+
+### Build Notes
+
+- Build target is Node.js 14+ (`dist/ccstatusline.js`)
+- During install, `ink@6.2.0` is patched to fix backspace handling on macOS terminals
+
 ### 📁 Project Structure
 
 ```
@@ -627,11 +744,13 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ---
 
-## Support
+## 🗑️ Uninstall
 
-If ccstatusline is useful to you, consider buying me a coffee:
-
-<a href="https://www.buymeacoffee.com/sirmalloc" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
+```bash
+npm uninstall -g ccstatusline-usage
+rm -rf ~/.npm/_npx ~/.config/ccstatusline ~/.cache/ccstatusline*
+jq 'del(.statusLine)' ~/.claude/settings.json > /tmp/cs.json && cat /tmp/cs.json > ~/.claude/settings.json
+```
 
 ---
 
@@ -647,6 +766,10 @@ If ccstatusline is useful to you, consider buying me a coffee:
 
 - GitHub: [@sirmalloc](https://github.com/sirmalloc)
 
+**PC van Velzen** ([pcvelz/ccstatusline-usage](https://github.com/pcvelz/ccstatusline-usage) fork)
+
+- GitHub: [@pcvelz](https://github.com/pcvelz)
+
 ---
 
 ## 🔗 Related Projects
@@ -684,8 +807,8 @@ Give a ⭐ if this project helped you!
 [![GitHub forks](https://img.shields.io/github/forks/sirmalloc/ccstatusline?style=social)](https://github.com/sirmalloc/ccstatusline/network/members)
 [![GitHub watchers](https://img.shields.io/github/watchers/sirmalloc/ccstatusline?style=social)](https://github.com/sirmalloc/ccstatusline/watchers)
 
-[![npm version](https://img.shields.io/npm/v/ccstatusline.svg)](https://www.npmjs.com/package/ccstatusline)
-[![npm downloads](https://img.shields.io/npm/dm/ccstatusline.svg)](https://www.npmjs.com/package/ccstatusline)
+[![npm version](https://img.shields.io/npm/v/ccstatusline-usage.svg)](https://www.npmjs.com/package/ccstatusline-usage)
+[![npm downloads](https://img.shields.io/npm/dm/ccstatusline-usage.svg)](https://www.npmjs.com/package/ccstatusline-usage)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/sirmalloc/ccstatusline/blob/main/LICENSE)
 [![Made with Bun](https://img.shields.io/badge/Made%20with-Bun-000000.svg?logo=bun)](https://bun.sh)