ai-statusline 1.0.0

package/README.md

@@ -0,0 +1,331 @@
+# ai-statusline
+
+A high-performance, customizable status line for [Claude Code](https://claude.ai/code) CLI.
+
+Built in Rust. Zero runtime dependencies. Sub-millisecond rendering.
+
+```
+[Opus] ▓▓▓▓░░░░░░ 42% | $0.08 | 5m 23s
+📁 my-project | 🌿 main +3 ~2 | +156 -23 | v2.1.31
+```
+
+**✨ Features:**
+- 🎨 **Interactive TUI configurator** — Visual configuration with live preview
+- ⚡ **26 customizable widgets** — Model, tokens, cost, git status, and more
+- 🎭 **11 built-in themes** — Dracula, Nord, Tokyo Night, Catppuccin, and more
+- 🚀 **Sub-millisecond rendering** — Zero lag, always fresh
+- 🔧 **Zero dependencies** — Single 1MB binary, no Node.js required
+
+## Why ai-statusline?
+
+| | ai-statusline | ccstatusline |
+|---|---|---|
+| **Language** | Rust (compiled binary) | TypeScript (bunx/npx) |
+| **Render time** | <1ms | ~200ms (npx overhead) |
+| **Binary size** | 1.0 MB | N/A (requires Node.js) |
+| **Runtime deps** | None | Node.js or Bun |
+| **Data source** | Native JSON API (stdin) | Transcript file parsing |
+| **Accuracy** | Always correct (official API) | Breaks across models/versions |
+| **Memory** | 1.2 MB | ~50 MB (Node.js runtime) |
+| **Widgets** | 26 | ~15 |
+| **Config format** | TOML (with comments) | JSON |
+
+## Quick Start
+
+### Install
+
+```bash
+# npm (downloads platform binary automatically)
+npm install -g ai-statusline
+
+# Or direct binary
+curl -fsSL https://raw.githubusercontent.com/mstuart/ai-statusline/main/scripts/install.sh | sh
+
+# Or build from source
+cargo install --path .
+```
+
+### Configure Claude Code
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "ai-statusline"
+  }
+}
+```
+
+Restart Claude Code. Done.
+
+### Configure Your Status Line
+
+**🎨 Interactive TUI (Recommended for Beginners)**
+
+The easiest way to customize your status line:
+
+```bash
+ai-statusline config
+```
+
+The TUI configurator lets you:
+- **Add/remove widgets** — Choose from 26 available widgets with live preview
+- **Reorder widgets** — Use `j`/`k` to move widgets up/down
+- **Switch themes** — Browse and preview 11 built-in themes instantly
+- **Configure powerline** — Toggle powerline mode, change separators, enable auto-align
+- **Manage layouts** — Add/remove status lines, adjust flex modes
+- **Save instantly** — `Ctrl-S` to save, changes apply immediately to Claude Code
+
+**⚡ Quick Presets**
+
+Apply pre-built layouts instantly:
+
+```bash
+ai-statusline preset full       # Two-line layout with everything
+ai-statusline preset minimal    # Just model + context %
+ai-statusline preset powerline  # Full layout with powerline arrows
+ai-statusline preset compact    # Single line, compact values
+```
+
+## Widgets
+
+26 built-in widgets, all reading from Claude Code's native JSON API:
+
+### Core Metrics
+| Widget | Type | Description |
+|--------|------|-------------|
+| Model | `model` | Current model name (Opus, Sonnet, etc.) |
+| Context % | `context-percentage` | Context window usage with optional progress bar |
+| Context Length | `context-length` | Absolute token count (e.g., "42K") |
+| Tokens In | `tokens-input` | Input tokens from current usage |
+| Tokens Out | `tokens-output` | Output tokens |
+| Tokens Cached | `tokens-cached` | Cache creation + read tokens |
+| Tokens Total | `tokens-total` | All tokens combined |
+| Session Cost | `session-cost` | Running cost in USD with optional burn rate |
+| Session Duration | `session-duration` | Elapsed time with optional API ratio |
+| Block Timer | `block-timer` | 5-hour usage block tracker with progress bar |
+
+### Git Integration
+| Widget | Type | Description |
+|--------|------|-------------|
+| Branch | `git-branch` | Current branch (with detached HEAD support) |
+| Status | `git-status` | Staged/modified/untracked file counts |
+| Worktree | `git-worktree` | Active worktree name (hidden when not in worktree) |
+
+### Workspace
+| Widget | Type | Description |
+|--------|------|-------------|
+| CWD | `cwd` | Current directory (basename, full, fish-style) |
+| Lines Changed | `lines-changed` | Lines added/removed this session |
+| Version | `version` | Claude Code version |
+| Session ID | `session-id` | Truncated session identifier |
+
+### Advanced
+| Widget | Type | Description |
+|--------|------|-------------|
+| Vim Mode | `vim-mode` | NORMAL/INSERT (hidden when vim mode off) |
+| Agent Name | `agent-name` | Active agent (hidden when not using --agent) |
+| Output Style | `output-style` | Current output style (hidden when "default") |
+| Exceeds 200K | `exceeds-tokens` | Warning when tokens exceed 200K threshold |
+| API Duration | `api-duration` | Ratio of API wait time to total time |
+| Custom Command | `custom-command` | Run any shell command, display output |
+| Custom Text | `custom-text` | Static text with emoji support |
+| Separator | `separator` | Visual divider between widgets |
+| Flex Separator | `flex-separator` | Flexible spacer that pushes widgets apart |
+| Terminal Width | `terminal-width` | Current terminal width in columns |
+
+## Configuration
+
+### TUI Configurator
+
+Launch the interactive TUI to configure your status line visually:
+
+```bash
+ai-statusline config
+```
+
+**Navigation:**
+- `Tab` / `Shift-Tab` — Switch between tabs (Widgets, Theme, Powerline, Layout, Preview)
+- `↑` / `↓` — Navigate items
+- `←` / `→` — Switch between status lines (in Widgets tab)
+- `Enter` / `Space` — Select/toggle options
+- `a` — Add widget
+- `d` / `Delete` — Remove widget
+- `j` / `k` — Move widget down/up
+- `Ctrl-S` — Save configuration
+- `q` — Quit
+
+**Tabs:**
+- **Widgets** — Add, remove, and reorder widgets on each status line
+- **Theme** — Browse and select from 11 built-in color themes
+- **Powerline** — Toggle powerline mode, cycle separators, enable auto-align
+- **Layout** — Add/remove status lines, change flex mode
+- **Preview** — Live preview of your current configuration
+
+### Manual Configuration
+
+Config lives at `~/.config/ai-statusline/config.toml`. Generate a default:
+
+```bash
+ai-statusline init
+```
+
+Or edit the TOML file directly for advanced customization.
+
+### Example config
+
+```toml
+theme = "dracula"
+default_separator = " | "
+default_padding = " "
+flex_mode = "full-minus-40"
+compact_threshold = 60
+global_bold = false
+inherit_separator_colors = false
+
+# First status line
+[[lines]]
+type = "model"
+color = "cyan"
+raw_value = true
+
+[[lines]]
+type = "context-percentage"
+metadata = { bar = "true" }
+
+[[lines]]
+type = "session-cost"
+color = "yellow"
+raw_value = true
+
+[[lines]]
+type = "session-duration"
+raw_value = true
+
+# Second status line (start a new line group)
+[[lines]]
+type = "cwd"
+metadata = { fish_style = "true" }
+
+[[lines]]
+type = "git-branch"
+color = "magenta"
+
+[[lines]]
+type = "git-status"
+
+[powerline]
+enabled = false
+separator = "\uE0B0"
+auto_align = false
+```
+
+### Widget options
+
+Every widget supports:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `type` | string | Widget type (see table above) |
+| `color` | string | Foreground color (named, hex, or 256-color index) |
+| `background_color` | string | Background color |
+| `bold` | bool | Bold text |
+| `raw_value` | bool | Compact mode without labels |
+| `padding` | string | Override default padding |
+| `merge_next` | bool | Merge with next widget (no separator) |
+| `metadata` | table | Widget-specific options |
+
+### Widget-specific metadata
+
+| Widget | Key | Values | Description |
+|--------|-----|--------|-------------|
+| `context-percentage` | `bar` | `"true"` | Show progress bar |
+| `context-percentage` | `inverse` | `"true"` | Show remaining instead of used |
+| `session-cost` | `burn_rate` | `"true"` | Show hourly burn rate |
+| `session-duration` | `api_ratio` | `"true"` | Show API time percentage |
+| `block-timer` | `bar` | `"true"` | Show progress bar |
+| `block-timer` | `bar_width` | `"16"` | Progress bar width |
+| `cwd` | `full` | `"true"` | Show full path |
+| `cwd` | `fish_style` | `"true"` | Fish-style abbreviation |
+| `cwd` | `segments` | `"3"` | Show last N segments |
+| `custom-command` | `command` | shell cmd | Command to execute |
+| `custom-text` | `text` | any string | Static text to display |
+| `separator` | `char` | any char | Separator character |
+| `flex-separator` | `char` | any char | Fill character (default: space) |
+
+## Themes
+
+11 built-in themes optimized for popular terminal color schemes:
+
+```bash
+ai-statusline theme list    # List all themes
+ai-statusline theme set nord  # Switch theme
+```
+
+Available: `default`, `solarized`, `nord`, `dracula`, `gruvbox`, `monokai`, `light`, `high-contrast`, `one-dark`, `tokyo-night`, `catppuccin`
+
+## Color Support
+
+ai-statusline auto-detects terminal color capabilities:
+
+- **Truecolor** (24-bit): detected via `COLORTERM=truecolor`
+- **256-color**: detected via `TERM=*256color*`
+- **16-color**: fallback for basic terminals
+- **No color**: respects `NO_COLOR` environment variable
+
+Override with `--color-level`:
+
+```bash
+ai-statusline --color-level truecolor
+ai-statusline --color-level none
+```
+
+## CLI Commands
+
+```bash
+ai-statusline              # Render status line (reads JSON from stdin)
+ai-statusline init         # Generate default config file
+ai-statusline doctor       # Check environment compatibility
+ai-statusline theme list   # List available themes
+ai-statusline theme set <name>  # Switch theme
+ai-statusline preset <name>     # Apply a preset layout
+ai-statusline config            # Interactive TUI configurator
+ai-statusline dump-schema       # Print expected JSON input schema
+ai-statusline --version         # Show version
+```
+
+## Performance
+
+Benchmarked on Apple M1:
+
+| Metric | Value |
+|--------|-------|
+| Render time | <1ms |
+| Binary size | 1.0 MB |
+| Memory usage | 1.2 MB |
+| Startup time | <1ms |
+
+Claude Code debounces status line updates at 300ms. ai-statusline completes in <1ms, ensuring the status line is always fresh and never causes UI lag.
+
+## How It Works
+
+Claude Code pipes JSON session data to your status line script via stdin. ai-statusline reads this JSON, applies your configuration, and prints formatted ANSI text to stdout. No transcript parsing, no file watching, no external dependencies.
+
+```
+Claude Code → JSON stdin → ai-statusline → ANSI stdout → Terminal
+```
+
+## Building from Source
+
+```bash
+git clone https://github.com/mstuart/ai-statusline
+cd ai-statusline
+cargo build --release
+# Binary at ./target/release/ai-statusline
+```
+
+## License
+
+MIT

package/bin/ai-statusline

@@ -0,0 +1,24 @@
+#!/bin/sh
+# Wrapper script for ai-statusline binary
+# The actual binary is downloaded during npm postinstall
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+BINARY="$SCRIPT_DIR/ai-statusline-bin"
+
+if [ -f "$BINARY" ]; then
+  exec "$BINARY" "$@"
+fi
+
+# Check for binary with platform-specific name
+case "$(uname -s)" in
+  MINGW*|MSYS*|CYGWIN*) BINARY="$SCRIPT_DIR/ai-statusline.exe" ;;
+esac
+
+if [ -f "$BINARY" ]; then
+  exec "$BINARY" "$@"
+fi
+
+echo "Error: ai-statusline binary not found."
+echo "Try reinstalling: npm install -g ai-statusline"
+echo "Or build from source: cargo install --path ."
+exit 1

package/bin/cli.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const ext = process.platform === 'win32' ? '.exe' : '';
+const bin = path.join(__dirname, `claude-status-bin${ext}`);
+
+const result = spawnSync(bin, process.argv.slice(2), {
+  stdio: 'inherit',
+  windowsHide: false,
+});
+
+if (result.error) {
+  if (result.error.code === 'ENOENT') {
+    console.error('claude-status binary not found. Try reinstalling: npm install -g claude-status');
+  } else {
+    console.error(result.error.message);
+  }
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "ai-statusline",
+  "version": "1.0.0",
+  "description": "Customizable status line for AI coding assistants - real-time model, tokens, cost, git status display",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mstuart/ai-statusline"
+  },
+  "homepage": "https://github.com/mstuart/ai-statusline#readme",
+  "keywords": [
+    "ai-coding",
+    "statusline",
+    "terminal",
+    "cli",
+    "developer-tools",
+    "claude-code",
+    "cursor",
+    "ai-assistant"
+  ],
+  "bin": {
+    "ai-statusline": "bin/ai-statusline"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}

package/scripts/install.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+"use strict";
+
+const https = require("https");
+const http = require("http");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execSync } = require("child_process");
+
+const PACKAGE = require("../package.json");
+const VERSION = PACKAGE.version;
+const REPO = "mstuart/ai-statusline";
+const BINARY_NAME = "ai-statusline";
+
+function getPlatformTarget() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  const targets = {
+    "darwin-x64": "x86_64-apple-darwin",
+    "darwin-arm64": "aarch64-apple-darwin",
+    "linux-x64": "x86_64-unknown-linux-gnu",
+    "linux-arm64": "aarch64-unknown-linux-gnu",
+    "win32-x64": "x86_64-pc-windows-msvc",
+  };
+
+  const key = `${platform}-${arch}`;
+  const target = targets[key];
+
+  if (!target) {
+    console.error(`Unsupported platform: ${key}`);
+    console.error(`Supported platforms: ${Object.keys(targets).join(", ")}`);
+    process.exit(1);
+  }
+
+  return { target, platform, arch };
+}
+
+function getDownloadUrl(target) {
+  const ext = target.includes("windows") ? ".exe" : "";
+  const archive = target.includes("windows") ? "zip" : "tar.gz";
+  return `https://github.com/${REPO}/releases/download/v${VERSION}/${BINARY_NAME}-v${VERSION}-${target}.${archive}`;
+}
+
+function download(url) {
+  return new Promise((resolve, reject) => {
+    const handler = (response) => {
+      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        const redirectUrl = response.headers.location;
+        const client = redirectUrl.startsWith("https") ? https : http;
+        client.get(redirectUrl, handler).on("error", reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        reject(new Error(`Download failed with status ${response.statusCode}: ${url}`));
+        return;
+      }
+
+      const chunks = [];
+      response.on("data", (chunk) => chunks.push(chunk));
+      response.on("end", () => resolve(Buffer.concat(chunks)));
+      response.on("error", reject);
+    };
+
+    https.get(url, handler).on("error", reject);
+  });
+}
+
+async function extractTarGz(buffer, destDir) {
+  const tmpFile = path.join(os.tmpdir(), `ai-statusline-${Date.now()}.tar.gz`);
+  fs.writeFileSync(tmpFile, buffer);
+
+  try {
+    execSync(`tar xzf "${tmpFile}" -C "${destDir}"`, { stdio: "pipe" });
+  } finally {
+    try { fs.unlinkSync(tmpFile); } catch (_) {}
+  }
+}
+
+async function extractZip(buffer, destDir) {
+  const tmpFile = path.join(os.tmpdir(), `ai-statusline-${Date.now()}.zip`);
+  fs.writeFileSync(tmpFile, buffer);
+
+  try {
+    execSync(`unzip -o "${tmpFile}" -d "${destDir}"`, { stdio: "pipe" });
+  } finally {
+    try { fs.unlinkSync(tmpFile); } catch (_) {}
+  }
+}
+
+async function install() {
+  const { target, platform } = getPlatformTarget();
+  const binDir = path.join(__dirname, "..", "bin");
+  const binPath = path.join(binDir, platform === "win32" ? `${BINARY_NAME}.exe` : BINARY_NAME);
+
+  // Check if binary already exists
+  if (fs.existsSync(binPath)) {
+    console.log(`ai-statusline binary already installed at ${binPath}`);
+    return;
+  }
+
+  const url = getDownloadUrl(target);
+  console.log(`Downloading ai-statusline v${VERSION} for ${target}...`);
+  console.log(`  URL: ${url}`);
+
+  try {
+    const data = await download(url);
+    console.log(`  Downloaded ${(data.length / 1024 / 1024).toFixed(1)} MB`);
+
+    // Extract
+    fs.mkdirSync(binDir, { recursive: true });
+
+    if (target.includes("windows")) {
+      await extractZip(data, binDir);
+    } else {
+      await extractTarGz(data, binDir);
+    }
+
+    // Make executable
+    if (platform !== "win32") {
+      fs.chmodSync(binPath, 0o755);
+    }
+
+    console.log(`  Installed to ${binPath}`);
+  } catch (error) {
+    console.warn(`\nFailed to download pre-built binary: ${error.message}`);
+    console.warn("\nYou can build from source instead:");
+    console.warn("  cargo install --path .");
+    console.warn("\nOr download manually from:");
+    console.warn(`  https://github.com/${REPO}/releases`);
+
+    // Create a stub script that tells the user to install manually
+    const stub = platform === "win32"
+      ? `@echo off\necho ai-statusline binary not installed. Run: cargo install --path . in the ai-statusline repo\nexit /b 1\n`
+      : `#!/bin/sh\necho "ai-statusline binary not installed. Run: cargo install --path . in the ai-statusline repo"\nexit 1\n`;
+
+    fs.mkdirSync(binDir, { recursive: true });
+    fs.writeFileSync(binPath, stub);
+    if (platform !== "win32") {
+      fs.chmodSync(binPath, 0o755);
+    }
+  }
+}
+
+install().catch((error) => {
+  console.error("Installation failed:", error.message);
+  process.exit(1);
+});