skill-statusline 1.0.0 → 2.0.0

package/README.md

@@ -1,15 +1,6 @@
-# Claude Code Statusline
+# skill-statusline
 
-A rich, customizable statusline for Claude Code with colored legends, context progress bar, GitHub info, token tracking, and active skill display.
-
-## Layout
-
-```
- Skill: Edit                      │  GitHub: User/Repo/master+~
- Model: Opus 4.6                  │  Dir: Downloads/Project
- Tokens: 25k + 12k = 37k         │  Cost: $1.23
- Context: ████████████████████░░░░░░░░░░░░░░░░░░░░ 50%
-```
+Rich, themeable statusline for Claude Code with accurate context tracking, 5 color themes, 3 layout modes, and zero dependencies.
 
 ## Install
 
@@ -24,40 +15,143 @@ npm install -g skill-statusline
 ccsl install
 ```
 
-Then restart Claude Code.
+The installer walks you through choosing a theme and layout. Use `--quick` to skip the wizard and use defaults.
+
+## Layouts
+
+### Compact (2 rows)
+
+```
+ Opus 4.6         │ Downloads/Project      │ 47% $1.23
+ Context: ████████████████████░░░░░░░░░░░░░░░░░░░░ 47%
+```
+
+### Standard (4 rows — default)
+
+```
+ Skill: Edit                      │  GitHub: user/repo/main+~
+ Model: Opus 4.6                  │  Dir: Downloads/Project
+ Tokens: 85k + 12k                │  Cost: $1.23
+ Context: ████████████████████░░░░░░░░░░░░░░░░░░░░ 46%
+```
+
+### Full (6 rows)
+
+```
+ Skill: Edit                      │  GitHub: user/repo/main+~
+ Model: Opus 4.6                  │  Dir: Downloads/Project
+ Window: 85k + 12k                │  Cost: $1.23 ($0.12/m)
+ Session: 125k + 34k              │  +156/-23  12m34s
+ Cache: W:5k R:2k                 │  NORMAL @code-reviewer
+ Context: ████████████████████░░░░░░░░░░░░░░░░░░░░ 46% 54% left
+```
+
+## Themes
 
-## Uninstall
+| Theme | Palette |
+|-------|---------|
+| `default` | Classic purple/pink/cyan |
+| `nord` | Arctic, blue-tinted |
+| `tokyo-night` | Vibrant neon |
+| `catppuccin` | Warm pastels (Mocha) |
+| `gruvbox` | Retro groovy |
 
 ```bash
-ccsl uninstall
+ccsl theme set nord
 ```
 
 ## Fields
 
-| Field   | Color            | Description |
-|---------|------------------|-------------|
-| Skill   | Pink             | Last tool used (Read, Write, Edit, Terminal, Agent, etc.) |
-| Model   | Purple           | Active model name and version |
-| GitHub  | White            | username/repo/branch with +~ dirty indicators |
-| Dir     | Cyan             | Last 3 segments of working directory |
-| Tokens  | Yellow           | Input + Output = Total (e.g., 25k + 12k = 37k) |
-| Cost    | Green            | Session cost in USD |
-| Context | White/Orange/Red | 40-char progress bar (white ≤40%, orange 41-75%, red >75%) |
+| Field | Color | Description |
+|-------|-------|-------------|
+| Skill | Pink | Last tool used (Read, Write, Edit, Terminal, Agent...) |
+| Model | Purple | Active model name + version |
+| GitHub | White | user/repo/branch with `+` staged `~` unstaged indicators |
+| Dir | Cyan | Last 3 path segments of working directory |
+| Tokens | Yellow | Current context window: input + output |
+| Cost | Green | Session cost in USD |
+| Context | Adaptive | 40-char bar — white <=40%, orange 41-75%, red 76-90%, deep red >90% |
+| Session | Dim | Cumulative tokens across all turns (full layout) |
+| Duration | Dim | Session elapsed time (full layout) |
+| Lines | Dim | +added/-removed (full layout) |
+| Cache | Blue | Write/Read cache token counts (full layout) |
+| Vim | Teal | NORMAL/INSERT mode when vim mode is on (full layout) |
+| Agent | Blue | @agent-name when running with --agent (full layout) |
+
+## Accurate Context Tracking
+
+v2 computes context percentage from actual token counts (`current_usage.input_tokens + cache_creation + cache_read`) divided by `context_window_size`, instead of relying on the pre-calculated `used_percentage` which can lag behind. This fixes the v1 bug where the bar showed 77% while real usage was 92%.
+
+Compaction warnings appear at configurable thresholds:
+- **85%+**: Shows remaining percentage (`15% left`)
+- **95%+**: Shows `COMPACTING` warning
+
+## CLI Commands
+
+```
+ccsl install              Install with theme/layout wizard
+ccsl install --quick      Install with defaults
+ccsl uninstall            Remove statusline
+ccsl update               Update scripts (preserves config)
+
+ccsl theme                List themes
+ccsl theme set <name>     Set active theme
+ccsl layout               List layouts
+ccsl layout set <name>    Set active layout
+
+ccsl preview              Preview with sample data
+ccsl preview --theme x    Preview a specific theme
+ccsl preview --layout x   Preview a specific layout
+
+ccsl config               Show current config
+ccsl config set k v       Set config option
+ccsl doctor               Run diagnostics + benchmark
+ccsl version              Show version
+```
+
+## Config Options
+
+Stored in `~/.claude/statusline-config.json`:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `compaction_warning_threshold` | `85` | % at which to show remaining context warning |
+| `bar_width` | `40` | Width of context bar in characters |
+| `cache_ttl_seconds` | `5` | How long to cache git/transcript results |
+| `show_burn_rate` | `false` | Show $/min burn rate (full layout) |
+| `show_vim_mode` | `true` | Show vim mode indicator |
+| `show_agent_name` | `true` | Show --agent name |
+
+## Architecture
+
+Pure bash at runtime — zero dependencies. Node.js CLI is only for installation.
+
+```
+~/.claude/
+  statusline-command.sh           # Entry point (called by Claude Code)
+  statusline/
+    core.sh                       # Engine: parse JSON, compute fields, render
+    json-parser.sh                # Nested JSON extraction (no jq)
+    helpers.sh                    # Utilities + filesystem caching
+    themes/{default,nord,...}.sh  # Color palettes
+    layouts/{compact,...}.sh      # Render functions
+  statusline-config.json          # User preferences
+```
+
+Performance: <50ms with caching, <100ms cold. Git and transcript reads are cached with configurable TTL.
+
+Terminal width is auto-detected — layouts gracefully degrade on narrow terminals.
 
 ## Requirements
 
-- Bash shell (Git Bash on Windows, or any Unix shell)
+- Bash (Git Bash on Windows, or any Unix shell)
 - Git (for GitHub field)
+- Node.js >=16 (for installer only)
 - Works on Windows, macOS, Linux
 
-## What it installs
-
-- `~/.claude/statusline-command.sh` — the statusline script
-- Updates `~/.claude/settings.json` — adds `statusLine` config
-
 ## Part of the Thinqmesh Skills Ecosystem
 
-This statusline is also bundled with [codebase-context-skill](https://www.npmjs.com/package/codebase-context-skill) — context engineering middleware for Claude Code with 23 slash commands, 6 agents, and session persistence.
+This statusline is also bundled with [codebase-context-skill](https://www.npmjs.com/package/codebase-context-skill).
 
 ```bash
 npx codebase-context-skill init