cc-api-statusline 0.2.1 → 1.0.0

package/README.md

@@ -1,7 +1,5 @@
 # cc-api-statusline
 
-> Claude Code statusline widget for monitoring API usage from third-party proxy backends
-
 A high-performance TUI statusline tool that polls API usage data from Claude API proxy services (sub2api, claude-relay-service, or custom providers) and renders a configurable one-line status display.
 
 ## Features
@@ -12,47 +10,46 @@ A high-performance TUI statusline tool that polls API usage data from Claude API
 - 💾 **Smart caching** — Disk cache with atomic writes, TTL validation, automatic garbage collection
 - 🎯 **Claude Code integration** — Auto-setup with `--install` command
 - 📊 **Multiple components** — Daily/weekly/monthly quotas, balance, tokens, rate limits
-- 🐛 **Debug logging** — Detailed execution logs for troubleshooting
+- 🔁 **Hot switching** — Auto-detects API endpoint and credential changes at runtime
 - 🔒 **Reliability** — No stale data display, race-condition-free writes, auto cache cleanup
 
-## Installation
+## Quick Start
 
-```bash
-# Using npm
-npm install -g cc-api-statusline
+### 1. Set up your API endpoint
 
-# Using bun
-bun add -g cc-api-statusline
+You need `ANTHROPIC_BASE_URL` (your proxy URL) and `ANTHROPIC_AUTH_TOKEN` (your API key).
 
-# From source
-git clone https://github.com/liafonx/cc-api-statusline
-cd cc-api-statusline
-bun install
-bun run build
-```
+**Recommended: via `~/.claude/settings.json` env overlay** (automatically passed to the widget):
 
-## Quick Start
-
-### Claude Code Integration (Recommended)
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "https://your-proxy.example.com",
+    "ANTHROPIC_AUTH_TOKEN": "your-api-token"
+  }
+}
+```
 
-The easiest way to use cc-api-statusline is with auto-setup:
+Or export them in your shell:
 
 ```bash
-# Set required environment variables first
 export ANTHROPIC_BASE_URL="https://your-proxy.example.com"
 export ANTHROPIC_AUTH_TOKEN="your-api-token"
+```
 
-# Install as Claude Code statusline widget
-npx cc-api-statusline --install
+### 2. Preview
+
+```bash
+bunx cc-api-statusline@latest --once
+```
 
-# Or with bunx (auto-detects if available)
-bunx cc-api-statusline --install --runner bunx
+### 3. Install as Claude Code widget (optional)
 
-# Uninstall
-npx cc-api-statusline --uninstall
+```bash
+bunx cc-api-statusline@latest --install
 ```
 
-This automatically adds to `~/.claude/settings.json`:
+This adds to `~/.claude/settings.json`:
 
 ```json
 {
@@ -64,89 +61,37 @@ This automatically adds to `~/.claude/settings.json`:
 }
 ```
 
-### Standalone Mode
+Using `bunx` ensures you always run the latest version without a global install. To uninstall:
 
 ```bash
-# Set required environment variables
-export ANTHROPIC_BASE_URL="https://your-proxy.example.com"
-export ANTHROPIC_AUTH_TOKEN="your-api-token"
-
-# Run once and exit
-cc-api-statusline --once
-
-# Run with custom config
-cc-api-statusline --config ./my-config.json
+bunx cc-api-statusline --uninstall
 ```
 
-### ccstatusline Custom Command (Legacy)
-
-Add to your `~/.claude/ccstatusline/config.json`:
-
-```json
-{
-  "customCommands": {
-    "usage": {
-      "command": "cc-api-statusline",
-      "description": "API usage statusline",
-      "type": "piped"
-    }
-  },
-  "widgets": [
-    {
-      "type": "customCommand",
-      "command": "usage",
-      "refreshIntervalMs": 30000,
-      "maxWidth": 80,
-      "preserveColors": true
-    }
-  ]
-}
-```
-
-## Configuration
-
-Configuration file: `~/.claude/cc-api-statusline/config.json`
-
-### User-Agent Spoofing (Optional)
+Optional global install:
 
-Some API providers restrict requests to only come from Claude Code clients. Enable User-Agent spoofing to bypass these restrictions:
-
-```json
-{
-  "spoofClaudeCodeUA": true
-}
+```bash
+bun add -g cc-api-statusline
+# or
+npm install -g cc-api-statusline
 ```
 
-**Options:**
-- `false` / `undefined` — No User-Agent header (default)
-- `true` — Auto-detect Claude Code version, fallback to `claude-cli/2.1.56 (external, cli)`
-- `"string"` — Use custom User-Agent string
+## Hot Switching
 
-**Per-provider override (custom providers only):**
+cc-api-statusline automatically detects when `ANTHROPIC_BASE_URL` or `ANTHROPIC_AUTH_TOKEN` changes (e.g. when you switch Claude Code profiles or rotate tokens). On detection it shows a brief transition indicator (`⟳ Switching provider...`) and refreshes from the new endpoint — no restart required.
 
-```json
-{
-  "spoofClaudeCodeUA": true,
-  "customProviders": {
-    "my-provider": {
-      "spoofClaudeCodeUA": "custom-client/1.0.0"
-    }
-  }
-}
-```
+## Configuration
 
-### Example Configuration
+### Style Config (`~/.claude/cc-api-statusline/config.json`)
 
 ```json
 {
   "display": {
     "layout": "standard",
-    "displayMode": "bar",
-    "barSize": "medium",
-    "barStyle": "classic",
-    "separator": " | ",
-    "maxWidth": 80,
-    "clockFormat": "24h"
+    "displayMode": "text",
+    "progressStyle": "icon",
+    "barStyle": "block",
+    "divider": { "text": "|", "margin": 1, "color": "#555753" },
+    "maxWidth": 100
   },
   "components": {
     "daily": true,
@@ -154,313 +99,102 @@ Some API providers restrict requests to only come from Claude Code clients. Enab
     "monthly": true,
     "balance": true,
     "tokens": false,
-    "rateLimit": false,
-    "plan": false
-  },
-  "colors": {
-    "auto": {
-      "low": "green",
-      "medium": "yellow",
-      "high": "red",
-      "lowThreshold": 50,
-      "highThreshold": 80
-    }
-  },
-  "pollIntervalSeconds": 30,
-  "pipedRequestTimeoutMs": 800
+    "rateLimit": false
+  }
 }
 ```
 
-### Display Options
-
-#### Layouts
-
-- `standard` — Full labels (e.g., "Daily 24%")
-- `compact` — Single-letter labels (e.g., "D 24%")
-- `minimal` — No labels (e.g., "24%")
-- `percent-first` — Percentage before bar (e.g., "Daily 24% ━━──")
-
-#### Display Modes
-
-- `bar` — Progress bar visualization
-- `percentage` — Percentage only (no bar)
-- `icon-pct` — Nerd-font icon + percentage
+Key options:
 
-#### Bar Styles
+| Key | Values | Default | Description |
+|-----|--------|---------|-------------|
+| `layout` | `standard` / `percent-first` | `standard` | Assembly order of label, bar, value |
+| `displayMode` | `text` / `compact` / `emoji` / `nerd` / `hidden` | `text` | Label style. `nerd` requires a [Nerd Font](https://www.nerdfonts.com/font-downloads). |
+| `progressStyle` | `bar` / `icon` / `hidden` | `icon` | Usage fraction visualization. `icon` requires a [Nerd Font](https://www.nerdfonts.com/font-downloads). |
+| `barStyle` | `block` / `classic` / `dot` / `shade` / `pipe` / `braille` / `square` / `star` | `block` | Bar character style |
+| `barSize` | `small` / `small-medium` / `medium` / `medium-large` / `large` | `medium` | Bar width (4–12 chars) |
+| `divider` | `DividerConfig` or `false` | `{ text: "\|", margin: 1, color: "#555753" }` | Separator between components; `false` disables |
+| `maxWidth` | 20–100 | `100` | Max % of terminal width |
 
-- `classic` — `━━━━────` (default)
-- `block` — `████░░░░`
-- `shade` — `▓▓▓▓░░░░`
-- `pipe` — `||||····`
-- `dot` — `●●●●○○○○`
-- `braille` — `⣿⣿⣿⣿⠀⠀⠀⠀` (smooth gradients)
-- `square` — `■■■■□□□□`
-- `star` — `★★★★☆☆☆☆`
-- Custom — `{"fill": "▰", "empty": "▱"}`
+For the full style reference including per-component overrides, color aliases, and countdown config see [docs/spec-tui-style.md](docs/spec-tui-style.md).
 
-#### Bar Sizes
+#### User-Agent Spoofing
 
-- `small` — 4 chars
-- `small-medium` — 6 chars
-- `medium` — 8 chars (default)
-- `medium-large` — 10 chars
-- `large` — 12 chars
-
-### Per-Component Configuration
-
-Override global settings per component:
+Some providers restrict requests to Claude Code clients. Enable to bypass:
 
 ```json
 {
-  "components": {
-    "daily": {
-      "barStyle": "dot",
-      "color": "chill",
-      "countdown": {
-        "format": "duration",
-        "divider": " · ",
-        "prefix": "⏱ "
-      }
-    },
-    "weekly": {
-      "layout": "compact",
-      "displayMode": "icon-pct"
-    },
-    "balance": {
-      "label": "Credits"
-    }
-  }
+  "spoofClaudeCodeUA": true
 }
 ```
 
-**Note:** Countdown divider defaults to ` · ` (space-dot-space) for clean spacing.
-
-### Color Configuration
-
-#### Named Colors
+- `false` / `undefined` — No User-Agent header (default)
+- `true` — Auto-detect Claude Code version, fallback to `claude-cli/2.1.56 (external, cli)`
+- `"string"` — Use a custom User-Agent string
 
-`black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `dim`, `bright-red`, `bright-green`, etc.
+### API Config (`~/.claude/cc-api-statusline/api-config/`)
 
-#### Hex Colors
+Define custom providers as JSON files in this directory. After adding or modifying provider files, run:
 
-```json
-{
-  "components": {
-    "daily": {
-      "color": "#00ff00"
-    }
-  }
-}
+```bash
+cc-api-statusline --apply-config
 ```
 
-#### Dynamic Color Aliases
+See [docs/api-config-reference.md](docs/api-config-reference.md) for the full schema.
 
-```json
-{
-  "colors": {
-    "auto": {
-      "low": "green",
-      "medium": "yellow",
-      "high": "red",
-      "lowThreshold": 50,
-      "highThreshold": 80
-    },
-    "chill": {
-      "low": "cyan",
-      "medium": "blue",
-      "high": "magenta",
-      "lowThreshold": 60,
-      "highThreshold": 90
-    }
-  }
-}
-```
+## [ccstatusline](https://github.com/anthropics/claude-code) Custom Command
 
-#### Per-Part Coloring
+Add to `~/.claude/ccstatusline/config.json`:
 
 ```json
 {
-  "components": {
-    "daily": {
-      "colors": {
-        "label": "#8a8a8a",
-        "bar": "auto",
-        "value": "white",
-        "countdown": "#666666"
-      }
+  "customCommands": {
+    "usage": {
+      "command": "cc-api-statusline",
+      "description": "API usage statusline",
+      "type": "piped"
     }
-  }
+  },
+  "widgets": [
+    {
+      "type": "customCommand",
+      "command": "usage",
+      "refreshIntervalMs": 30000,
+      "maxWidth": 100,
+      "preserveColors": true
+    }
+  ]
 }
 ```
 
 ## Environment Variables
 
-| Variable | Required | Description |
+All variables are optional at the shell level — `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` can be set via `settings.json` env overlay instead of shell exports (see [Quick Start](#quick-start)).
+
+| Variable | Optional | Description |
 |----------|----------|-------------|
 | `ANTHROPIC_BASE_URL` | Yes | API endpoint (e.g., `https://api.sub2api.com`) |
 | `ANTHROPIC_AUTH_TOKEN` | Yes | API key or token |
-| `CC_STATUSLINE_PROVIDER` | No | Override provider detection (`sub2api`, `claude-relay-service`, or custom) |
-| `CC_STATUSLINE_POLL` | No | Override poll interval (seconds, min 5) |
-| `CC_STATUSLINE_TIMEOUT` | No | Piped mode timeout (milliseconds, default 1000) |
-| `DEBUG` or `CC_STATUSLINE_DEBUG` | No | Enable debug logging to `~/.claude/cc-api-statusline/debug.log` |
-
-## Provider Setup
-
-### sub2api
-
-```bash
-export ANTHROPIC_BASE_URL="https://api.sub2api.com"
-export ANTHROPIC_AUTH_TOKEN="sk-sub2api-..."
-```
-
-### claude-relay-service
-
-```bash
-export ANTHROPIC_BASE_URL="https://relay.example.com"
-export ANTHROPIC_AUTH_TOKEN="your-relay-token"
-```
-
-### Custom Providers
-
-Define custom providers in config.json:
-
-```json
-{
-  "customProviders": {
-    "my-provider": {
-      "urlPatterns": ["my-proxy.example.com"],
-      "endpoint": "/api/usage",
-      "method": "GET",
-      "authMode": "bearer",
-      "responseMapping": {
-        "billingMode": "$.mode",
-        "daily.used": "$.usage.daily",
-        "daily.limit": "$.limits.daily"
-      }
-    }
-  }
-}
-```
-
-## CLI Usage
-
-```bash
-# Show help
-cc-api-statusline --help
-
-# Show version
-cc-api-statusline --version
-
-# Fetch once and exit
-cc-api-statusline --once
-
-# Use custom config file
-cc-api-statusline --config /path/to/config.json
-
-# Install as Claude Code statusline widget
-cc-api-statusline --install
-cc-api-statusline --install --runner bunx
-cc-api-statusline --install --force  # Overwrite existing
-
-# Uninstall from Claude Code
-cc-api-statusline --uninstall
-```
-
-## Debug Logging
-
-Enable detailed execution logs for troubleshooting:
-
-```bash
-# Enable debug logging
-DEBUG=1 cc-api-statusline --once
-
-# For Claude Code widget, add to settings.json:
-{
-  "statusLine": {
-    "type": "command",
-    "command": "DEBUG=1 bunx -y cc-api-statusline@latest",
-    "padding": 0
-  }
-}
-
-# View logs in real-time
-tail -f ~/.claude/cc-api-statusline/debug.log
-
-# View recent logs
-tail -20 ~/.claude/cc-api-statusline/debug.log
-
-# Search for errors
-grep "ERROR" ~/.claude/cc-api-statusline/debug.log
-```
-
-Debug logs include:
-- Execution start/finish timestamps
-- Mode detection (piped vs TTY)
-- Environment variables (sanitized)
-- Config and cache status
-- Execution paths taken (A/B/C/D)
-- Fetch timing and performance metrics
-- Cache operations
-- Error details with fallback behavior
-
-## Performance
-
-Piped mode performance targets (1000ms timeout):
-
-- **Path A (warm cache)**: ≤25ms (p95 ≤100ms)
-- **Path B (re-render)**: ≤55ms (p95 ≤100ms)
-- **Path C (fetch)**: ≤840ms worst case
-- **Path D (fallback)**: ≤25ms
-
-Cache validation:
-- TTL check
-- Provider match
-- Base URL match
-- Version match
-- Token hash match
-
-Cache garbage collection:
-- Automatic cleanup after successful cache writes
-- Deletes cache files older than 7 days
-- Maintains maximum of 20 cache files (deletes oldest)
-- Removes orphaned temporary files older than 1 hour
-- Best-effort operation (never blocks or throws)
-
-Exit code behavior:
-- Returns `0` for all error states (stale data is never shown, only error messages)
-- Ensures clean widget display without `[Exit: 1]` indicators
+| `CC_STATUSLINE_PROVIDER` | Yes | Override provider detection (`sub2api`, `claude-relay-service`, or custom) |
+| `CC_STATUSLINE_POLL` | Yes | Override poll interval (seconds, min 5) |
+| `CC_STATUSLINE_TIMEOUT` | Yes | Piped mode timeout (milliseconds, default 1000) |
+| `DEBUG` or `CC_STATUSLINE_DEBUG` | Yes | Enable debug logging to `~/.claude/cc-api-statusline/debug.log` |
 
 ## Troubleshooting
 
 ### "Missing required environment variable"
 
-Set `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN`:
-
-```bash
-export ANTHROPIC_BASE_URL="https://your-proxy.example.com"
-export ANTHROPIC_AUTH_TOKEN="your-token"
-```
-
-Or add to `~/.claude/settings.json`:
-
-```json
-{
-  "env": {
-    "ANTHROPIC_BASE_URL": "https://your-proxy.example.com",
-    "ANTHROPIC_AUTH_TOKEN": "your-token"
-  }
-}
-```
+Set `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` via shell exports or the `settings.json` env overlay (see [Quick Start](#quick-start)).
 
 ### "Unknown provider"
 
-Provider autodetection failed. Explicitly set provider:
+Provider autodetection failed. Explicitly set the provider:
 
 ```bash
 export CC_STATUSLINE_PROVIDER="sub2api"
 ```
 
-Or define a custom provider in config.json.
+Or define a custom provider in `api-config/`.
 
 ### "[offline]" or "[stale]" indicator
 
@@ -478,15 +212,18 @@ Check:
 
 ### Slow performance in piped mode
 
-Check cache validity:
-- Run `cc-api-statusline --once` standalone to warm cache
-- Verify `~/.claude/cc-api-statusline/cache-*.json` exists
-- Check `pipedRequestTimeoutMs` config (default 800ms)
-- Enable debug logging to see fetch timing
+```bash
+# Warm the cache standalone
+cc-api-statusline --once
+# Check debug timing
+DEBUG=1 cc-api-statusline --once
+```
+
+Verify `pipedRequestTimeoutMs` in config (default 800ms) and check `~/.claude/cc-api-statusline/cache-*.json` exists.
 
 ### Widget shows `[Exit: 1]` in Claude Code
 
-This indicates the statusline command failed. Enable debug logging:
+Enable debug logging in `~/.claude/settings.json`:
 
 ```json
 {
@@ -502,82 +239,44 @@ Then check logs: `tail -f ~/.claude/cc-api-statusline/debug.log`
 
 ## Development
 
-```bash
-# Install dependencies
-bun install
+| Command | Description |
+|---------|-------------|
+| `bun install` | Install dependencies |
+| `bun run start` | Quick dev fetch (--once mode) |
+| `bun run example` | Simulate piped mode |
+| `bun run test` | Run tests |
+| `bun run lint` | Lint |
+| `bun run build` | Build |
+| `bun run check` | Run all checks |
 
-# Quick dev fetch (--once mode)
-bun run start
+### Debug Logging
 
-# Simulate piped mode
-bun run example
+Enable detailed execution logs for troubleshooting:
 
-# Run tests
-bun run test
+```bash
+# Enable debug logging
+DEBUG=1 cc-api-statusline --once
 
-# Lint
-bun run lint
+# For Claude Code widget, add to settings.json:
+# "command": "DEBUG=1 bunx -y cc-api-statusline@latest"
 
-# Build
-bun run build
+# View logs in real-time
+tail -f ~/.claude/cc-api-statusline/debug.log
 
-# Run all checks
-bun run check
+# Search for errors
+grep "ERROR" ~/.claude/cc-api-statusline/debug.log
 ```
 
-## Architecture
+Debug logs include execution timestamps, mode detection, config/cache status, execution paths (A/B/C/D), fetch timing, and error details.
 
-```
-┌─────────────┐
-│   main.ts   │ ← Thin router: parse args → dispatch
-└──────┬──────┘
-       │
-┌──────▼────────┐
-│    src/cli/   │ ← Argument parsing, install/uninstall, piped-mode
-│  - args.ts    │
-│  - commands.ts│
-│  - piped-mode │
-└──────┬────────┘
-       │
-       ├──────────────────────────────────────┐
-       │                                      │
-┌──────▼────────┐                   ┌────────▼────────┐
-│   services/   │                   │   providers/    │
-│  - env        │                   │  - sub2api      │
-│  - cache      │                   │  - relay        │
-│  - config     │                   │  - custom       │
-│  - settings   │ ← settings.json   │  - autodetect   │
-│  - logger     │ ← debug logging   │  - quota-window │
-│  - atomic-write│← atomic writes   │  - custom-mapping│
-│  - cache-gc   │ ← auto cleanup    │                 │
-│  - ensure-dir │← dir creation     └────────┬────────┘
-└──────┬────────┘                            │
-       │                                      │
-       ├──────────────────────────────────────┘
-       │
-┌──────▼────────┐
-│  src/core/    │
-│ execute-cycle │ ← Unified execution (Path A/B/C/D)
-│  constants.ts │ ← Shared constants
-└──────┬────────┘
-       │
-┌──────▼────────┐
-│   renderer/   │
-│  - component  │ ← Per-component rendering (RenderContext)
-│  - bar        │ ← Progress bars
-│  - colors     │ ← ANSI color system
-│  - countdown  │ ← Time-to-reset
-│  - error      │ ← Error states
-│  - transition │ ← Transition state detection
-│  - icons      │ ← Nerd-font glyphs
-│  - truncate   │ ← Terminal width
-│  - index      │ ← Main pipeline
-└───────────────┘
-```
+Log files are automatically rotated (1-in-20 invocations):
+- `debug.log` ≥ 500 KB → archived as `debug.YYYY-MM-DDTHH-MM.log`
+- Archives older than 24h → compressed with gzip
+- Compressed archives older than 3 days → deleted
 
 ## Testing
 
-- **578 tests** across **34 test files**
+- **691 tests** across **39 test files**
 - Unit tests for all services, renderers, and shared utilities
 - Core execution path tests (A/B/C/D)
 - E2E smoke tests with isolated environments
@@ -598,4 +297,3 @@ MIT
 - [TUI Style Spec](docs/spec-tui-style.md)
 - [API Polling Spec](docs/spec-api-polling.md)
 - [Custom Providers Spec](docs/spec-custom-providers.md)
-- [AGENTS.md](AGENTS.md) - Development handoff guide