@buckits/claude-statusline 2.2.0 → 2.3.1

package/README.md

@@ -1,6 +1,64 @@
 # @buckits/claude-statusline
 
-A beautiful 2-line dashboard statusline for Claude Code with gradient progress bar, compact threshold marker, git status indicators, cost tracking, and GSD (Get Shit Done) update notifications.
+<div align="center">
+
+**The statusline Claude Code deserves.**
+
+[![npm version](https://img.shields.io/npm/v/@buckits/claude-statusline.svg)](https://www.npmjs.com/package/@buckits/claude-statusline)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+<br>
+
+![Statusline Preview](assets/statusline-preview.svg)
+
+<br>
+
+[Features](#features) • [Installation](#installation) • [Screenshots](#what-it-looks-like) • [GSD Compatible](#-gsd-compatible)
+
+</div>
+
+---
+
+## Why This Statusline?
+
+Claude Code's default statusline is... minimal. You deserve better.
+
+**This statusline shows you everything you need at a glance:**
+
+- 🎨 **Gradient progress bar** that flows green → yellow → red as you approach the limit
+- ⚡ **Auto-compact threshold marker** so you know exactly when Claude will summarize
+- 💰 **Session cost tracking** in real-time
+- 🔀 **Full git integration** with branch, status, and ahead/behind tracking
+
+## Features
+
+### 🎨 Gradient Progress Bar
+
+50 segments that smoothly transition through colors as your context fills up. The gradient is calculated relative to the auto-compact threshold, not total capacity—so you always know how close you are to summarization.
+
+### ⚡ Auto-Compact Threshold
+
+A red lightning bolt marks exactly where Claude will auto-summarize (78%). No more surprises—you'll see it coming.
+
+### 💰 Real-Time Cost
+
+See your session cost update as you work: `($12.41)`
+
+### 🔀 Git Status at a Glance
+
+| Symbol | Meaning |
+|--------|---------|
+| `✓` | Clean - all committed |
+| `●` | Unstaged changes |
+| `✚` | Staged and ready |
+| `●✚` | Both staged and unstaged |
+| `↑5` | 5 commits ahead of remote |
+| `↓2` | 2 commits behind remote |
+
+### 📊 2-Line Dashboard
+
+- **Line 1:** 🤖 Model • Cost • Context Progress
+- **Line 2:** 📁 Project • Branch • Git Status • Remote Tracking
 
 ## Installation
 
@@ -8,82 +66,86 @@ A beautiful 2-line dashboard statusline for Claude Code with gradient progress b
 npx @buckits/claude-statusline
 ```
 
-## Features
+That's it. The installer will:
+1. Ask where to install (global or local)
+2. Copy the statusline script
+3. Configure your settings
 
-- **2-Line Dashboard Layout** - Clean separation of AI info and project info
-- **Gradient Progress Bar** - 50 segments (4k tokens each) that smoothly transition green → yellow → orange → red
-- **⚡ Compact Threshold Marker** - Red lightning bolt shows exactly where auto-compact triggers (78%)
-- **Session Cost Tracking** - See your running cost in real-time
-- **Git Status Indicators**:
-  - `✓` Green checkmark = clean (all committed)
-  - `●` Yellow dot = unstaged changes
-  - `✚` Green plus = staged changes ready to commit
-  - `●✚` Both = partial commit state
-- **Ahead/Behind Tracking** - `↑5 ↓2` shows commits ahead/behind remote
-- **Visual Icons** - 🤖 for AI line, 📁 for project line
-- **GSD Update Notifications** - Automatically detects [Get Shit Done](https://www.npmjs.com/package/get-shit-done-cc) installations and shows available updates
-
-## Screenshot
+### Options
 
-```
-🤖 Opus 4.5 ($14.61) │ [████████████████████░░░░░░░░░░░░░░░░░░░⚡░░░░░░░░░░░] 80k/200k
-📁 trellis POC ✓ → origin/POC ↑15
-```
+```bash
+# Interactive (recommended)
+npx @buckits/claude-statusline
 
-With GSD update available:
-```
-🤖 Opus 4.5 ($14.61) │ [████████████████████░░░░░░░░░░░░░░░░░░░⚡░░░░░░░░░░░] 80k/200k
-📁 trellis POC ✓ → origin/POC ↑15    |  GSD 1.5.0>1.6.4
+# Install globally for all projects
+npx @buckits/claude-statusline --global
+
+# Install for current project only
+npx @buckits/claude-statusline --local
+
+# Replace existing statusline
+npx @buckits/claude-statusline --global --force
+
+# Uninstall
+npx @buckits/claude-statusline --global --uninstall
 ```
 
-## What Each Element Means
+## What It Looks Like
+
+### 🟢 Normal Usage (Green Zone)
+
+![Green Zone](assets/statusline-green.svg)
+
+Safe and sound. Plenty of context remaining.
+
+### 🟡 Getting Busy (Yellow Zone)
+
+![Yellow Zone](assets/statusline-yellow.svg)
+
+Making progress. Keep an eye on that threshold.
+
+### 🔴 Approaching Limit (Red Zone)
 
-### Line 1 - AI Session Info
-| Element | Description |
-|---------|-------------|
-| 🤖 | AI indicator |
-| `Opus 4.5` | Current model (cyan) |
-| `($14.61)` | Session cost (green) |
-| `│` | Separator |
-| `[███░░░⚡░░░]` | Context usage with compact threshold |
-| `80k/200k` | Tokens used / total |
+![Red Zone](assets/statusline-red.svg)
 
-### Line 2 - Project Info
-| Element | Description |
-|---------|-------------|
-| 📁 | Project indicator |
-| `trellis` | Project name (cyan) |
-| `POC` | Current branch (magenta) |
-| `✓●✚` | Git status (clean/unstaged/staged) |
-| `→` | Points to tracking branch |
-| `origin/POC` | Remote tracking branch (blue) |
-| `↑15` | Commits ahead (green) |
-| `↓3` | Commits behind (red) |
+Getting close to auto-compact. Consider wrapping up or starting fresh.
 
-## GSD Integration
+## 🤝 GSD Compatible
 
-If you have [Get Shit Done (GSD)](https://www.npmjs.com/package/get-shit-done-cc) installed, the statusline will automatically detect it and show update notifications when a newer version is available.
+This statusline works perfectly alongside [Get Shit Done (GSD)](https://www.npmjs.com/package/get-shit-done-cc)!
 
-**How it works:**
-1. Checks for GSD installation in project (`.claude/get-shit-done/VERSION`) or global (`~/.claude/get-shit-done/VERSION`)
-2. Reads the latest version from GSD's update cache (`~/.claude/cache/gsd-update-check.json`)
-3. If versions differ, shows the update notification on line 2
+If you have GSD installed, the statusline will automatically show update notifications when a new GSD version is available.
 
-**Note:** The cache is populated by GSD's SessionStart hook. If you see no notification, you're either on the latest version or GSD hasn't checked for updates yet.
+```bash
+# Install both for the ultimate Claude Code setup
+npx @buckits/claude-statusline
+npx get-shit-done-cc
+```
+
+## Requirements
+
+- **Claude Code CLI** (obviously)
+- **jq** - for JSON parsing ([install guide](https://stedolan.github.io/jq/download/))
+- **Bash** - ships with macOS/Linux
+- **Git** - for git status features (optional)
 
-## Progress Bar Colors
+### Installing jq
 
-The bar gradient is calculated relative to the ⚡ threshold (not total capacity):
+```bash
+# macOS
+brew install jq
 
-| Distance to ⚡ | Color |
-|---------------|-------|
-| Far (safe) | Bright green |
-| Approaching | Yellow |
-| Close | Orange |
-| At threshold | Red |
+# Ubuntu/Debian
+sudo apt install jq
+
+# Windows (via chocolatey)
+choco install jq
+```
 
 ## Manual Installation
 
+If you prefer to install manually:
+
 1. Copy `statusline.sh` to `~/.claude/statusline.sh`
 2. Make it executable: `chmod +x ~/.claude/statusline.sh`
 3. Add to `~/.claude/settings.json`:
@@ -97,13 +159,36 @@ The bar gradient is calculated relative to the ⚡ threshold (not total capacity
 }
 ```
 
-## Requirements
+## Troubleshooting
+
+### Statusline not showing?
+
+1. Make sure you restarted Claude Code after installation
+2. Check that `jq` is installed: `which jq`
+3. Verify the script is executable: `ls -la ~/.claude/statusline.sh`
+
+### Wrong colors?
+
+Your terminal needs to support 256 colors. Most modern terminals do.
+
+### Git status not showing?
 
-- Claude Code CLI
-- `jq` (for JSON parsing)
-- Bash
-- Git (for git status features)
+Make sure you're in a git repository with at least one commit.
+
+## Contributing
+
+Issues and PRs welcome at [github.com/Buckits/claude-statusline](https://github.com/Buckits/claude-statusline)
 
 ## License
 
-MIT
+MIT © [Buckits](https://github.com/Buckits)
+
+---
+
+<div align="center">
+
+**Made for the Claude Code community** 🤖
+
+*Star this repo if you find it useful!*
+
+</div>

package/bin/install.js

@@ -3,56 +3,335 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const readline = require('readline');
 
-const CLAUDE_DIR = path.join(os.homedir(), '.claude');
-const SETTINGS_FILE = path.join(CLAUDE_DIR, 'settings.json');
-const STATUSLINE_DEST = path.join(CLAUDE_DIR, 'statusline.sh');
-const STATUSLINE_SRC = path.join(__dirname, '..', 'statusline.sh');
+// Colors
+const cyan = '\x1b[36m';
+const green = '\x1b[32m';
+const yellow = '\x1b[33m';
+const red = '\x1b[31m';
+const magenta = '\x1b[35m';
+const dim = '\x1b[2m';
+const bold = '\x1b[1m';
+const reset = '\x1b[0m';
 
-console.log('\n🎨 Installing @buckits/claude-statusline...\n');
+// Get version from package.json
+const pkg = require('../package.json');
 
-// Ensure ~/.claude directory exists
-if (!fs.existsSync(CLAUDE_DIR)) {
-  console.log('📁 Creating ~/.claude directory...');
-  fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+// Parse args
+const args = process.argv.slice(2);
+const hasGlobal = args.includes('--global') || args.includes('-g');
+const hasLocal = args.includes('--local') || args.includes('-l');
+const hasHelp = args.includes('--help') || args.includes('-h');
+const hasUninstall = args.includes('--uninstall') || args.includes('-u');
+const hasForce = args.includes('--force') || args.includes('-f');
+
+// Directory constants
+const CLAUDE_DIR_NAME = '.claude';
+
+function getGlobalDir() {
+  if (process.env.CLAUDE_CONFIG_DIR) {
+    return expandTilde(process.env.CLAUDE_CONFIG_DIR);
+  }
+  return path.join(os.homedir(), CLAUDE_DIR_NAME);
+}
+
+function getLocalDir() {
+  return path.join(process.cwd(), CLAUDE_DIR_NAME);
 }
 
-// Copy statusline.sh
-console.log('📄 Copying statusline.sh...');
-fs.copyFileSync(STATUSLINE_SRC, STATUSLINE_DEST);
-fs.chmodSync(STATUSLINE_DEST, '755');
+function expandTilde(filePath) {
+  if (filePath && filePath.startsWith('~/')) {
+    return path.join(os.homedir(), filePath.slice(2));
+  }
+  return filePath;
+}
+
+// ASCII Art Banner
+const banner = `
+${cyan}   ╔═╗╦  ╔═╗╦ ╦╔╦╗╔═╗
+   ║  ║  ╠═╣║ ║ ║║║╣
+   ╚═╝╩═╝╩ ╩╚═╝═╩╝╚═╝${reset}
+   ${magenta}╔═╗╔╦╗╔═╗╔╦╗╦ ╦╔═╗╦  ╦╔╗╔╔═╗
+   ╚═╗ ║ ╠═╣ ║ ║ ║╚═╗║  ║║║║║╣
+   ╚═╝ ╩ ╩ ╩ ╩ ╚═╝╚═╝╩═╝╩╝╚╝╚═╝${reset}
+
+   ${bold}The statusline Claude Code deserves${reset} ${dim}v${pkg.version}${reset}
+
+   ${dim}───────────────────────────────────────────${reset}
+   ${green}█${reset}${green}█${reset}${yellow}█${reset}${yellow}█${reset}${red}█${reset}${red}█${reset}░░░░⚡░░░  ${dim}Gradient progress • Git status${reset}
+   ${dim}───────────────────────────────────────────${reset}
+`;
+
+const features = `
+   ${cyan}✦${reset} ${bold}Gradient Progress Bar${reset}
+     50 segments that flow ${green}green${reset} → ${yellow}yellow${reset} → ${red}red${reset}
+     as you approach the context limit
+
+   ${cyan}✦${reset} ${bold}⚡ Auto-Compact Threshold${reset}
+     Red lightning bolt shows exactly where
+     Claude will auto-summarize (78%)
+
+   ${cyan}✦${reset} ${bold}Git Integration${reset}
+     Branch • ${green}✓${reset}/${yellow}●${reset}/${green}✚${reset} status • ${green}↑${reset}ahead ${red}↓${reset}behind
+
+   ${cyan}✦${reset} ${bold}Session Cost Tracking${reset}
+     See your running \$ cost in real-time
+
+   ${cyan}✦${reset} ${bold}2-Line Dashboard${reset}
+     Line 1: 🤖 Model • Cost • Context
+     Line 2: 📁 Project • Branch • Status
+`;
+
+const example = `
+   ${dim}┌─────────────────────────────────────────────────────────────────┐${reset}
+   ${dim}│${reset} 🤖 ${cyan}Opus 4.5${reset} ${green}(\$12.41)${reset} │ [${green}████████${yellow}████${red}██${reset}░░░░░░░⚡░░░░░] ${yellow}62k${reset}/${cyan}200k${reset} ${dim}│${reset}
+   ${dim}│${reset} 📁 ${cyan}my-project${reset} ${magenta}main${reset} ${green}✓${reset} → ${cyan}origin/main${reset} ${green}↑2${reset}               ${dim}│${reset}
+   ${dim}└─────────────────────────────────────────────────────────────────┘${reset}
+`;
+
+// Help text
+if (hasHelp) {
+  console.log(banner);
+  console.log(`   ${yellow}Usage:${reset} npx @buckits/claude-statusline [options]
+
+   ${yellow}Options:${reset}
+     ${cyan}-g, --global${reset}     Install globally (${dim}~/.claude${reset})
+     ${cyan}-l, --local${reset}      Install locally (${dim}./.claude${reset})
+     ${cyan}-u, --uninstall${reset}  Remove statusline configuration
+     ${cyan}-f, --force${reset}      Replace existing statusline config
+     ${cyan}-h, --help${reset}       Show this help message
 
-// Update settings.json
-console.log('⚙️  Updating settings.json...');
-let settings = {};
+   ${yellow}Examples:${reset}
+     ${dim}# Interactive install (prompts for location)${reset}
+     npx @buckits/claude-statusline
 
-if (fs.existsSync(SETTINGS_FILE)) {
-  try {
-    const content = fs.readFileSync(SETTINGS_FILE, 'utf8');
-    settings = JSON.parse(content);
-  } catch (e) {
-    console.warn('⚠️  Could not parse existing settings.json, creating new one');
+     ${dim}# Install globally for all projects${reset}
+     npx @buckits/claude-statusline --global
+
+     ${dim}# Install for current project only${reset}
+     npx @buckits/claude-statusline --local
+
+     ${dim}# Replace existing statusline${reset}
+     npx @buckits/claude-statusline --global --force
+`);
+  process.exit(0);
+}
+
+console.log(banner);
+
+/**
+ * Read and parse settings.json
+ */
+function readSettings(settingsPath) {
+  if (fs.existsSync(settingsPath)) {
+    try {
+      return JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+    } catch (e) {
+      return {};
+    }
   }
+  return {};
 }
 
-// Remove old format if present
-if (settings.status_line) {
-  delete settings.status_line;
+/**
+ * Write settings.json with proper formatting
+ */
+function writeSettings(settingsPath, settings) {
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
 }
 
-// Set the statusLine configuration (correct camelCase format)
-settings.statusLine = {
-  type: "command",
-  command: STATUSLINE_DEST
-};
+/**
+ * Uninstall statusline
+ */
+function uninstall(isGlobal) {
+  const targetDir = isGlobal ? getGlobalDir() : getLocalDir();
+  const locationLabel = isGlobal
+    ? targetDir.replace(os.homedir(), '~')
+    : targetDir.replace(process.cwd(), '.');
 
-fs.writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2));
+  console.log(`   Uninstalling from ${cyan}${locationLabel}${reset}\n`);
 
-console.log('\n✅ Installation complete!\n');
-console.log('Your Claude Code statusline now features:');
-console.log('  • Gradient progress bar (green → yellow → orange → red)');
-console.log('  • ⚡ Compact threshold marker at 78%');
-console.log('  • Git branch, status, and ahead/behind tracking');
-console.log('  • Session cost display');
-console.log('  • GSD update notifications (if installed)');
-console.log('\nRestart Claude Code to see the new statusline.\n');
+  if (!fs.existsSync(targetDir)) {
+    console.log(`   ${yellow}⚠${reset} Directory does not exist: ${locationLabel}`);
+    console.log(`   Nothing to uninstall.\n`);
+    return;
+  }
+
+  let removed = false;
+
+  // Remove statusline.sh
+  const statuslinePath = path.join(targetDir, 'statusline.sh');
+  if (fs.existsSync(statuslinePath)) {
+    fs.unlinkSync(statuslinePath);
+    console.log(`   ${green}✓${reset} Removed statusline.sh`);
+    removed = true;
+  }
+
+  // Clean up settings.json
+  const settingsPath = path.join(targetDir, 'settings.json');
+  if (fs.existsSync(settingsPath)) {
+    const settings = readSettings(settingsPath);
+
+    if (settings.statusLine && settings.statusLine.command &&
+        settings.statusLine.command.includes('statusline.sh')) {
+      delete settings.statusLine;
+      writeSettings(settingsPath, settings);
+      console.log(`   ${green}✓${reset} Removed statusline from settings.json`);
+      removed = true;
+    }
+
+    // Also clean up old format
+    if (settings.status_line) {
+      delete settings.status_line;
+      writeSettings(settingsPath, settings);
+      removed = true;
+    }
+  }
+
+  if (!removed) {
+    console.log(`   ${yellow}⚠${reset} No statusline configuration found.`);
+  }
+
+  console.log(`
+   ${green}Done!${reset} Statusline has been removed.
+   Restart Claude Code to see the change.
+`);
+}
+
+/**
+ * Install statusline
+ */
+function install(isGlobal) {
+  const targetDir = isGlobal ? getGlobalDir() : getLocalDir();
+  const locationLabel = isGlobal
+    ? targetDir.replace(os.homedir(), '~')
+    : targetDir.replace(process.cwd(), '.');
+
+  console.log(`   Installing to ${cyan}${locationLabel}${reset}\n`);
+
+  // Ensure directory exists
+  if (!fs.existsSync(targetDir)) {
+    console.log(`   ${dim}Creating ${locationLabel}...${reset}`);
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  // Copy statusline.sh
+  const statuslineSrc = path.join(__dirname, '..', 'statusline.sh');
+  const statuslineDest = path.join(targetDir, 'statusline.sh');
+  fs.copyFileSync(statuslineSrc, statuslineDest);
+  fs.chmodSync(statuslineDest, '755');
+  console.log(`   ${green}✓${reset} Installed statusline.sh`);
+
+  // Update settings.json
+  const settingsPath = path.join(targetDir, 'settings.json');
+  const settings = readSettings(settingsPath);
+
+  // Check for existing statusline
+  const hasExisting = settings.statusLine != null || settings.status_line != null;
+
+  if (hasExisting && !hasForce) {
+    const existingCmd = settings.statusLine?.command || settings.status_line?.script || '(custom)';
+    console.log(`
+   ${yellow}⚠${reset} Existing statusline detected
+   ${dim}Current: ${existingCmd}${reset}
+
+   Use ${cyan}--force${reset} to replace it, or keep your current config.
+   ${dim}The statusline.sh file has been installed - you can switch anytime.${reset}
+`);
+  } else {
+    // Remove old format if present
+    if (settings.status_line) {
+      delete settings.status_line;
+    }
+
+    // Set new format
+    settings.statusLine = {
+      type: 'command',
+      command: statuslineDest
+    };
+
+    writeSettings(settingsPath, settings);
+    console.log(`   ${green}✓${reset} Configured settings.json`);
+  }
+
+  // Success message
+  console.log(`
+   ${green}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${reset}
+   ${green}✓${reset} ${bold}Installation complete!${reset}
+   ${green}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${reset}
+
+   ${cyan}Restart Claude Code${reset} to see your new statusline.
+
+   ${dim}Tip: Works great with GSD (Get Shit Done)!${reset}
+   ${dim}     npx get-shit-done-cc${reset}
+
+   ${dim}Issues? ${reset}${cyan}github.com/Buckits/claude-statusline${reset}
+`);
+}
+
+/**
+ * Interactive prompt for install location
+ */
+function promptLocation() {
+  if (!process.stdin.isTTY) {
+    console.log(`   ${dim}Non-interactive mode, defaulting to global install${reset}\n`);
+    install(true);
+    return;
+  }
+
+  console.log(features);
+  console.log(example);
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  let answered = false;
+
+  rl.on('close', () => {
+    if (!answered) {
+      console.log(`\n   ${yellow}Installation cancelled${reset}\n`);
+      process.exit(0);
+    }
+  });
+
+  const globalPath = getGlobalDir().replace(os.homedir(), '~');
+
+  console.log(`
+   ${yellow}Where would you like to install?${reset}
+
+   ${cyan}1${reset}) ${bold}Global${reset} ${dim}(${globalPath})${reset}
+      Available in all your projects
+
+   ${cyan}2${reset}) ${bold}Local${reset}  ${dim}(./.claude)${reset}
+      This project only
+`);
+
+  rl.question(`   Choice ${dim}[1]${reset}: `, (answer) => {
+    answered = true;
+    rl.close();
+    console.log('');
+    const choice = answer.trim() || '1';
+    install(choice !== '2');
+  });
+}
+
+// Main logic
+if (hasGlobal && hasLocal) {
+  console.log(`   ${red}✗${reset} Cannot specify both --global and --local\n`);
+  process.exit(1);
+}
+
+if (hasUninstall) {
+  if (!hasGlobal && !hasLocal) {
+    console.log(`   ${red}✗${reset} --uninstall requires --global or --local\n`);
+    process.exit(1);
+  }
+  uninstall(hasGlobal);
+} else if (hasGlobal || hasLocal) {
+  install(hasGlobal);
+} else {
+  promptLocation();
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@buckits/claude-statusline",
-  "version": "2.2.0",
-  "description": "A beautiful 2-line dashboard statusline for Claude Code with gradient progress bar, compact threshold marker, git status indicators, cost tracking, and GSD update notifications",
+  "version": "2.3.1",
+  "description": "The statusline Claude Code deserves - gradient progress bar, auto-compact threshold marker, git status, cost tracking, 2-line dashboard",
   "bin": {
     "claude-statusline": "./bin/install.js"
   },
@@ -14,7 +14,15 @@
     "claude-code",
     "statusline",
     "cli",
-    "terminal"
+    "terminal",
+    "progress-bar",
+    "git-status",
+    "context-window",
+    "anthropic",
+    "ai",
+    "developer-tools",
+    "gsd",
+    "get-shit-done"
   ],
   "author": "Buckits",
   "license": "MIT",
@@ -22,6 +30,10 @@
     "type": "git",
     "url": "https://github.com/Buckits/claude-statusline"
   },
+  "homepage": "https://github.com/Buckits/claude-statusline#readme",
+  "bugs": {
+    "url": "https://github.com/Buckits/claude-statusline/issues"
+  },
   "engines": {
     "node": ">=14"
   }