From 801c5f1b38ec8e0b475c6ecb78b3041841a110d7 Mon Sep 17 00:00:00 2001 From: Matthew Breedlove Date: Fri, 27 Feb 2026 13:09:08 -0500 Subject: [PATCH] chore: Update README.md --- README.md | 127 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 106 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index da83e63..56f9d98 100644 --- a/README.md +++ b/README.md @@ -137,6 +137,7 @@ - **⚡ 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 @@ -151,10 +152,10 @@ ```bash # Run the configuration TUI with npm -npx ccstatusline@latest +npx -y ccstatusline@latest # Or with Bun (faster) -bunx ccstatusline@latest +bunx -y ccstatusline@latest ``` ### Configure ccstatusline @@ -179,6 +180,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@latest", + "padding": 0 + } +} +``` + +Other supported command values are: +- `bunx -y ccstatusline@latest` +- `ccstatusline` (for self-managed/global installs) + --- ## 🪟 Windows Support @@ -193,13 +212,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 @@ -260,7 +279,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 ``` @@ -288,7 +307,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**: @@ -325,14 +344,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 + } } ``` @@ -340,11 +367,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 @@ -361,17 +387,32 @@ 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 +- **Claude Session ID** - Shows the current Claude Code session ID from status JSON - **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 @@ -379,14 +420,14 @@ 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") - **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) --- @@ -456,6 +497,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 @@ -472,6 +530,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 @@ -543,7 +603,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 @@ -559,13 +619,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 ```