howmuchleft 0.1.0 → 0.2.0

package/README.md

@@ -5,15 +5,23 @@
 [![license](https://img.shields.io/npm/l/howmuchleft)](https://github.com/smm-h/howmuchleft/blob/main/LICENSE)
 [![node](https://img.shields.io/node/v/howmuchleft)](https://nodejs.org)
 
-Pixel-perfect progress bars showing how much context and usage you have left, right in your Claude Code statusline.
+Pixel-perfect progress bars for your Claude Code statusline. See how much context and usage you have left at a glance.
 
-Three bars with sub-cell precision (using Unicode fractional block characters):
+| Dark | Light |
+|---|---|
+| ![Dark mode demo](./assets/demo-dark.gif) | ![Light mode demo](./assets/demo-light.gif) |
 
-- **Context window** -- how full your conversation context is, plus subscription tier and model name
-- **5-hour usage** -- your rolling 5-hour rate limit utilization, time until reset, git branch/changes, lines added/removed
-- **Weekly usage** -- your rolling 7-day rate limit utilization, time until reset, current directory
+## What you get
 
-Bars shift from green to yellow to orange to red as usage increases. Stale data is prefixed with `~`. Works with Pro, Max 5x, Max 20x, and Team subscriptions. API key users see an "API" label with context bar only.
+Three bars with sub-cell precision using Unicode fractional block characters:
+
+| Bar | Shows | Extra info |
+|---|---|---|
+| Context window | How full your conversation is | Subscription tier, model name |
+| 5-hour usage | Rolling rate limit utilization | Time until reset, git branch/changes, lines added/removed |
+| Weekly usage | Rolling 7-day rate limit utilization | Time until reset, current directory |
+
+Bars shift green to red as usage increases. Stale data (API unreachable) is prefixed with `~`. Works with Pro, Max 5x, Max 20x, and Team subscriptions. API key users see an "API" label with context bar only.
 
 ## Install
 
@@ -22,7 +30,7 @@ npm install -g howmuchleft
 howmuchleft --install
 ```
 
-For multiple Claude Code subscriptions:
+For multiple Claude Code config directories:
 
 ```bash
 howmuchleft --install ~/.claude-work
@@ -31,49 +39,67 @@ howmuchleft --install ~/.claude-personal
 
 ## Configuration
 
-Config file: `~/.config/howmuchleft.json`
+Config file: `~/.config/howmuchleft.json` (JSONC -- comments and trailing commas are allowed).
 
-```json
+```jsonc
 {
   "progressLength": 12,
-  "emptyBgDark": 236,
-  "emptyBgLight": 252
+  "colorMode": "auto",
+  "colors": [
+    // Truecolor dark: RGB gradient + RGB background
+    { "dark-mode": true, "true-color": true, "bg": [48, 48, 48], "gradient": [[0,215,0], [255,255,0], [255,0,0]] },
+    // 256-color dark: index gradient + index background
+    { "dark-mode": true, "true-color": false, "bg": 236, "gradient": [46, 226, 196] }
+  ]
 }
 ```
 
+### Top-level settings
+
 | Field | Default | Description |
 |---|---|---|
-| `progressLength` | `12` | Bar width in characters (3-40) |
-| `emptyBgDark` | `236` | 256-color index for empty bar background in dark terminals |
-| `emptyBgLight` | `252` | 256-color index for empty bar background in light terminals |
+| `progressLength` | `12` | Bar width in characters (3--40) |
+| `colorMode` | `"auto"` | `"auto"` (detect via `COLORTERM`), `"truecolor"`, or `"256"` |
+| `colors` | built-in | Array of color entries (see below) |
 
-Check current config:
+### Color entries
 
-```bash
-howmuchleft --config
-```
+Each entry in the `colors` array is matched against the current terminal. First match wins. Omit a condition to match both modes.
 
-## How it works
+| Field | Required | Description |
+|---|---|---|
+| `gradient` | Yes | Color stops: `[R,G,B]` arrays for truecolor, or integers (0--255) for 256-color |
+| `bg` | No | Empty bar background: `[R,G,B]` for truecolor, or integer (0--255) for 256-color |
+| `dark-mode` | No | Match dark (`true`) or light (`false`) terminals only |
+| `true-color` | No | Match truecolor (`true`) or 256-color (`false`) terminals only |
 
-Claude Code invokes `howmuchleft` as a child process on each statusline render, piping a JSON object to stdin with model info, context window usage, cwd, and cost data. The script:
+Truecolor gradients are smoothly interpolated between stops -- 3 stops (green, yellow, red) is enough for a smooth bar. 256-color gradients snap to the nearest stop.
 
-1. Reads the JSON from stdin
-2. Fetches usage data from Anthropic's OAuth API (cached for 60s, with stale-data fallback)
-3. Auto-refreshes expired OAuth tokens
-4. Runs `git status` for branch/change info (in parallel with the API call)
-5. Renders three lines of progress bars to stdout
+To preview your current gradient: `howmuchleft --test-colors`
 
 ## CLI
 
 ```
 howmuchleft [config-dir]              Run the statusline (called by Claude Code)
-howmuchleft --install [config-dir]    Add to Claude Code settings
-howmuchleft --uninstall [config-dir]  Remove from Claude Code settings
+howmuchleft --install [config-dir]    Add to Claude Code settings.json
+howmuchleft --uninstall [config-dir]  Remove from Claude Code settings.json
 howmuchleft --config                  Show config path and current settings
+howmuchleft --demo [seconds]          Time-lapse animation (default 60s)
+howmuchleft --test-colors             Preview gradient at seven sample levels
 howmuchleft --version                 Show version
 howmuchleft --help                    Show help
 ```
 
+## How it works
+
+Claude Code invokes `howmuchleft` as a child process on each statusline render, piping a JSON object to stdin with model info, context window usage, cwd, and cost data. The script:
+
+1. Parses the JSON from stdin
+2. Fetches usage data from Anthropic's OAuth API (cached 60s, stale-data fallback on failure)
+3. Auto-refreshes expired OAuth tokens
+4. Runs `git status --porcelain=v2` in parallel for branch/change info
+5. Renders three lines of ANSI-colored progress bars to stdout
+
 ## Uninstall
 
 ```bash
@@ -84,6 +110,6 @@ npm uninstall -g howmuchleft
 ## Requirements
 
 - Node.js >= 18
-- Claude Code with OAuth login (Pro/Max/Team subscription)
+- Claude Code with OAuth login (Pro, Max, or Team subscription)
 - `git` (optional, for branch/change display)
 - `gsettings` (Linux/GNOME) or `defaults` (macOS) for dark/light mode detection

package/bin/cli.js

@@ -9,7 +9,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { main, CONFIG_PATH } = require('../lib/statusline');
+const { main, CONFIG_PATH, testColors } = require('../lib/statusline');
 
 const VERSION = require('../package.json').version;
 
@@ -56,13 +56,15 @@ Usage:
   howmuchleft --install [config-dir]    Add howmuchleft to your Claude Code settings
   howmuchleft --uninstall [config-dir]  Remove howmuchleft from your Claude Code settings
   howmuchleft --config                  Show config file path and current settings
+  howmuchleft --demo [seconds]           Run a time-lapse demo (default 60s)
+  howmuchleft --test-colors             Preview gradient colors for your terminal
   howmuchleft --version                 Show version
 
 Config file: ${CONFIG_PATH}
   {
     "progressLength": 12,       Bar width in characters (3-40, default 12)
-    "emptyBgDark": 236,         256-color index for empty bar in dark mode
-    "emptyBgLight": 252         256-color index for empty bar in light mode
+    "colorMode": "auto",        Color depth: "auto", "truecolor", or "256"
+    "colors": [...]             Gradient and bg color entries (see README)
   }
 
 Examples:
@@ -151,13 +153,17 @@ function showConfig() {
     const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
     console.log('Current settings:');
     console.log(`  progressLength: ${config.progressLength ?? '(default: 12)'}`);
-    console.log(`  emptyBgDark:    ${config.emptyBgDark ?? '(default: 236)'}`);
-    console.log(`  emptyBgLight:   ${config.emptyBgLight ?? '(default: 252)'}`);
+    console.log(`  colorMode:      ${config.colorMode ?? '(default: auto)'}`);
+    if (Array.isArray(config.colors)) {
+      console.log(`  colors:         ${config.colors.length} entries`);
+    } else {
+      console.log('  colors:         (using built-in defaults)');
+    }
   } catch {
     console.log('No config file found. Using defaults:');
     console.log('  progressLength: 12');
-    console.log('  emptyBgDark:    236');
-    console.log('  emptyBgLight:   252');
+    console.log('  colorMode:      auto');
+    console.log('  colors:         built-in gradients');
     console.log();
     console.log(`Create one with: cp ${path.resolve(__dirname, '..', 'config.example.json')} ${CONFIG_PATH}`);
   }
@@ -177,8 +183,20 @@ if (args.includes('--help') || args.includes('-h')) {
   uninstall(args);
 } else if (args.includes('--config')) {
   showConfig();
+} else if (args.includes('--test-colors')) {
+  testColors();
+} else if (args.includes('--demo')) {
+  const { runDemo } = require('../lib/demo');
+  const demoIdx = args.indexOf('--demo');
+  const duration = parseInt(args[demoIdx + 1], 10);
+  runDemo(duration > 0 ? duration : undefined);
+} else if (process.stdin.isTTY) {
+  // Running from a terminal, not piped by Claude Code
+  console.log('This command is meant to be called by Claude Code, not run directly.');
+  console.log('Try: howmuchleft --help or howmuchleft --demo');
+  process.exit(0);
 } else {
-  // Default: run the statusline
+  // Default: run the statusline (stdin is piped by Claude Code)
   main().catch(err => {
     console.error('Statusline error:', err.message);
     process.exit(1);

package/config.example.json

@@ -1,5 +1,37 @@
 {
   "progressLength": 12,
-  "emptyBgDark": 236,
-  "emptyBgLight": 252
+  // "auto" (default), "truecolor", or "256"
+  "colorMode": "auto",
+  // First matching entry wins. Omit dark-mode/true-color to match both.
+  // bg: empty bar background color (integer for 256-color, [R,G,B] for truecolor)
+  "colors": [
+    // Truecolor on dark terminal: bright smooth gradient
+    {
+      "dark-mode": true,
+      "true-color": true,
+      "bg": [48, 48, 48],
+      "gradient": [[0,215,0], [95,215,0], [175,215,0], [255,255,0], [255,215,0], [255,175,0], [255,135,0], [255,95,0], [255,55,0], [255,0,0]]
+    },
+    // Truecolor on light terminal: medium intensity
+    {
+      "dark-mode": false,
+      "true-color": true,
+      "bg": [208, 208, 208],
+      "gradient": [[0,170,0], [75,170,0], [140,170,0], [200,200,0], [200,170,0], [200,135,0], [200,100,0], [200,65,0], [200,30,0], [190,0,0]]
+    },
+    // 256-color on dark terminal
+    {
+      "dark-mode": true,
+      "true-color": false,
+      "bg": 236,
+      "gradient": [46, 82, 118, 154, 190, 226, 220, 214, 208, 202, 196]
+    },
+    // 256-color on light terminal
+    {
+      "dark-mode": false,
+      "true-color": false,
+      "bg": 252,
+      "gradient": [40, 76, 112, 148, 184, 178, 172, 166, 160]
+    }
+  ]
 }

package/lib/demo.js

@@ -0,0 +1,139 @@
+/**
+ * Demo mode: time-lapse animation showing the statusline filling up.
+ *
+ * Single continuous run (default 60s, configurable):
+ *   - Weekly bar:  0→100%, 7d remaining → 0  (1 cycle)
+ *   - 5-hour bar:  0→100%, 5h remaining → 0  (8 cycles)
+ *   - Context bar: 0→100%                    (15 cycles)
+ *
+ * Git changes and lines added/removed accumulate on each context reset.
+ */
+
+const { progressBar, formatPercent, formatTimeRemaining, colors } = require('./statusline');
+
+const FRAME_MS = 100;
+
+const FIVE_HOUR_MS = 5 * 60 * 60 * 1000;
+const SEVEN_DAY_MS = 7 * 24 * 60 * 60 * 1000;
+
+const MODEL = 'Opus 4.5';
+const TIER = 'Max 5x';
+const BRANCH = 'feature/auth';
+const CWD = '~/Projects/myapp';
+
+const FRAME_LINES = 3;
+
+const CONTEXT_CYCLES = 15;
+const FIVE_HOUR_CYCLES = 8;
+
+/**
+ * Render one frame: 3 statusline bars.
+ * Overwrites previous frame by moving cursor up.
+ */
+function renderFrame(state, isFirst) {
+  if (!isFirst) process.stdout.write(`\x1b[${FRAME_LINES}A`);
+
+  const lines = [];
+
+  // Line 1: context bar
+  const ctxBar = progressBar(state.context);
+  lines.push(
+    `${ctxBar} ${colors.cyan}${Math.round(state.context)}%${colors.reset} ` +
+    `${colors.magenta}${TIER}${colors.reset} ` +
+    `${colors.white}${MODEL}${colors.reset}`
+  );
+
+  // Line 2: 5-hour bar + git info
+  const fiveBar = progressBar(state.fiveHour);
+  const fivePct = formatPercent(state.fiveHour);
+  const fiveReset = formatTimeRemaining(state.fiveHourResetIn);
+  lines.push(
+    `${fiveBar} ${fivePct} ` +
+    `${colors.dim}${fiveReset}${colors.reset} ` +
+    `${colors.cyan}${BRANCH}${colors.reset}` +
+    (state.changes > 0 ? ` ${colors.yellow}+${state.changes}${colors.reset}` : '') +
+    ` ${colors.green}+${state.linesAdded}${colors.reset}/${colors.red}-${state.linesRemoved}${colors.reset}`
+  );
+
+  // Line 3: weekly bar + cwd
+  const weekBar = progressBar(state.weekly);
+  const weekPct = formatPercent(state.weekly);
+  const weekReset = formatTimeRemaining(state.weeklyResetIn);
+  lines.push(
+    `${weekBar} ${weekPct} ` +
+    `${colors.dim}${weekReset}${colors.reset} ` +
+    `${colors.white}${CWD}${colors.reset}`
+  );
+
+  process.stdout.write(lines.map(l => '\x1b[2K' + l).join('\n') + '\n');
+}
+
+/**
+ * Run the demo animation.
+ * @param {number} [durationSec=60] Total duration in seconds.
+ */
+function runDemo(durationSec = 60) {
+  process.stdout.write('\x1b[?25l');
+
+  function cleanup() {
+    process.stdout.write('\x1b[?25h');
+    process.exit(0);
+  }
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+
+  const totalFrames = durationSec * (1000 / FRAME_MS);
+  let frame = 0;
+  let changes = 0;
+  let linesAdded = 0;
+  let linesRemoved = 0;
+  let prevCtxCycle = 0;
+
+  const interval = setInterval(() => {
+    if (frame >= totalFrames) {
+      clearInterval(interval);
+      cleanup();
+      return;
+    }
+
+    const t = frame / totalFrames; // 0→1 over full duration
+    const isLast = frame === totalFrames - 1;
+
+    // Weekly: single ramp 0→100%, 7d→0
+    const weekly = isLast ? 100 : t * 100;
+    const weeklyResetIn = isLast ? 0 : (1 - t) * SEVEN_DAY_MS;
+
+    // 5-hour: 8 sawtooth cycles (last frame pinned to 100%)
+    const fiveCycleT = (t * FIVE_HOUR_CYCLES) % 1;
+    const fiveHour = isLast ? 100 : fiveCycleT * 100;
+    const fiveHourResetIn = isLast ? 0 : (1 - fiveCycleT) * FIVE_HOUR_MS;
+
+    // Context: 15 sawtooth cycles (last frame pinned to 100%)
+    const ctxCycleT = (t * CONTEXT_CYCLES) % 1;
+    const context = isLast ? 100 : ctxCycleT * 100;
+
+    // Accumulate git stats on each context reset
+    const currCtxCycle = Math.floor(t * CONTEXT_CYCLES);
+    if (frame > 0 && currCtxCycle > prevCtxCycle) {
+      changes += Math.floor(Math.random() * 3) + 1;
+      linesAdded += Math.floor(Math.random() * 50) + 10;
+      linesRemoved += Math.floor(Math.random() * 20);
+    }
+    prevCtxCycle = currCtxCycle;
+
+    renderFrame({
+      context,
+      fiveHour,
+      fiveHourResetIn,
+      weekly,
+      weeklyResetIn,
+      changes,
+      linesAdded,
+      linesRemoved,
+    }, frame === 0);
+
+    frame++;
+  }, FRAME_MS);
+}
+
+module.exports = { runDemo };

package/lib/statusline.js

@@ -28,6 +28,11 @@ const execFileAsync = promisify(execFile);
 let _isDark = null;
 function isDarkMode() {
   if (_isDark !== null) return _isDark;
+  // Allow override for GIF recording without changing system settings
+  if (process.env.HOWMUCHLEFT_DARK !== undefined) {
+    _isDark = process.env.HOWMUCHLEFT_DARK === '1';
+    return _isDark;
+  }
   try {
     if (process.platform === 'darwin') {
       // Returns "Dark" in dark mode, throws in light mode (key doesn't exist)
@@ -71,25 +76,148 @@ const TIER_NAMES = {
 // -- Progress bar: left fractional block characters for sub-cell precision --
 const FRACTIONAL_CHARS = ['\u258F','\u258E','\u258D','\u258C','\u258B','\u258A','\u2589'];
 
+// -- JSONC support: strip // and /* */ comments for config file parsing --
+function stripJsonComments(text) {
+  let result = '';
+  let inString = false;
+  let escape = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (escape) { result += ch; escape = false; continue; }
+    if (inString) {
+      if (ch === '\\') escape = true;
+      else if (ch === '"') inString = false;
+      result += ch;
+      continue;
+    }
+    if (ch === '"') { inString = true; result += ch; continue; }
+    if (ch === '/' && text[i + 1] === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+      result += '\n';
+      continue;
+    }
+    if (ch === '/' && text[i + 1] === '*') {
+      i += 2;
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i++;
+      i++; // skip past closing /
+      continue;
+    }
+    result += ch;
+  }
+  // Strip trailing commas before } or ] (common JSONC foot-gun)
+  return result.replace(/,\s*([}\]])/g, '$1');
+}
+
+function parseJsonc(text) {
+  return JSON.parse(stripJsonComments(text));
+}
+
+// -- Truecolor detection --
+function isTruecolorSupported() {
+  const ct = process.env.COLORTERM;
+  return ct === 'truecolor' || ct === '24bit';
+}
+
+// -- Built-in gradient defaults for all 4 combos --
+// Each entry: optional dark-mode/true-color conditions, gradient stops.
+// RGB arrays for truecolor, integer indices for 256-color.
+const BUILTIN_COLORS = [
+  { 'dark-mode': true, 'true-color': true, bg: [48, 48, 48], gradient: [
+    [0,215,0], [95,215,0], [175,215,0], [255,255,0], [255,215,0], [255,175,0], [255,135,0], [255,95,0], [255,55,0], [255,0,0],
+  ]},
+  { 'dark-mode': false, 'true-color': true, bg: [208, 208, 208], gradient: [
+    [0,170,0], [75,170,0], [140,170,0], [200,200,0], [200,170,0], [200,135,0], [200,100,0], [200,65,0], [200,30,0], [190,0,0],
+  ]},
+  { 'dark-mode': true, 'true-color': false, bg: 236, gradient: [46, 82, 118, 154, 190, 226, 220, 214, 208, 202, 196] },
+  { 'dark-mode': false, 'true-color': false, bg: 252, gradient: [40, 76, 112, 148, 184, 178, 172, 166, 160] },
+];
+
 // Config is loaded from ~/.config/howmuchleft.json (XDG-style, install-method-agnostic).
-// Cached per-process to avoid redundant fs reads (called once per progressBar, 3x per render).
+// Supports JSONC (comments and trailing commas).
+// Cached per-process to avoid redundant fs reads.
 const CONFIG_PATH = path.join(os.homedir(), '.config', 'howmuchleft.json');
 
+// Check if a gradient stop is an RGB array [R,G,B]
+function isRgbStop(stop) {
+  return Array.isArray(stop) && stop.length === 3 &&
+    stop.every(v => Number.isInteger(v) && v >= 0 && v <= 255);
+}
+
+// Validate a gradient: non-empty array of either all ints or all RGB arrays
+function isValidGradient(arr) {
+  if (!Array.isArray(arr) || arr.length === 0) return false;
+  if (isRgbStop(arr[0])) return arr.every(isRgbStop);
+  return arr.every(v => Number.isInteger(v) && v >= 0 && v <= 255);
+}
+
+// Find first matching color entry from a colors array (returns full entry)
+function findColorMatch(colorsArr, isDark, isTruecolor) {
+  for (const entry of colorsArr) {
+    if (entry['dark-mode'] !== undefined && entry['dark-mode'] !== isDark) continue;
+    if (entry['true-color'] !== undefined && entry['true-color'] !== isTruecolor) continue;
+    if (isValidGradient(entry.gradient)) return entry;
+  }
+  return null;
+}
+
+// Format a bg value (integer 0-255 or [R,G,B]) as an ANSI background escape
+function formatBgEscape(bg, truecolor) {
+  if (isRgbStop(bg)) {
+    if (truecolor) return `\x1b[48;2;${bg[0]};${bg[1]};${bg[2]}m`;
+    return `\x1b[48;5;${rgbTo256(bg)}m`;
+  }
+  if (Number.isInteger(bg) && bg >= 0 && bg <= 255) return `\x1b[48;5;${bg}m`;
+  return null;
+}
+
+// Convert RGB [R,G,B] to nearest 256-color cube index
+function rgbTo256(rgb) {
+  return 16 + 36 * Math.round(rgb[0] / 255 * 5) + 6 * Math.round(rgb[1] / 255 * 5) + Math.round(rgb[2] / 255 * 5);
+}
+
+// Linearly interpolate between RGB gradient stops for smooth truecolor
+function interpolateRgb(stops, t) {
+  const pos = t * (stops.length - 1);
+  const lo = Math.floor(pos);
+  const hi = Math.min(lo + 1, stops.length - 1);
+  const frac = pos - lo;
+  return [
+    Math.round(stops[lo][0] + (stops[hi][0] - stops[lo][0]) * frac),
+    Math.round(stops[lo][1] + (stops[hi][1] - stops[lo][1]) * frac),
+    Math.round(stops[lo][2] + (stops[hi][2] - stops[lo][2]) * frac),
+  ];
+}
+
 let _barConfig = null;
 function getBarConfig() {
   if (_barConfig) return _barConfig;
+
+  const dark = isDarkMode();
+  let colorMode = 'auto';
+  let width = 12;
+  let userColors = [];
+
   try {
-    const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+    const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
+    const config = parseJsonc(raw);
     const w = Number(config.progressLength);
-    const dark = isDarkMode();
-    const rawBg = Number(dark ? config.emptyBgDark : config.emptyBgLight);
-    _barConfig = {
-      width: (Number.isInteger(w) && w >= 3 && w <= 40) ? w : 12,
-      emptyBg: (Number.isInteger(rawBg) && rawBg >= 0 && rawBg <= 255) ? rawBg : (dark ? 236 : 252),
-    };
-  } catch {
-    _barConfig = { width: 12, emptyBg: isDarkMode() ? 236 : 252 };
-  }
+    if (Number.isInteger(w) && w >= 3 && w <= 40) width = w;
+    if (config.colorMode === 'truecolor' || config.colorMode === '256') colorMode = config.colorMode;
+    if (Array.isArray(config.colors)) userColors = config.colors;
+  } catch {}
+
+  const truecolor = colorMode === 'truecolor' || (colorMode === 'auto' && isTruecolorSupported());
+  const userMatch = findColorMatch(userColors, dark, truecolor);
+  const builtinMatch = findColorMatch(BUILTIN_COLORS, dark, truecolor);
+  const gradient = userMatch?.gradient || builtinMatch.gradient;
+  const isRgb = isRgbStop(gradient[0]);
+
+  // bg: user entry wins, then builtin, then hardcoded fallback
+  const emptyBg = formatBgEscape(userMatch?.bg, truecolor) ||
+                  formatBgEscape(builtinMatch?.bg, truecolor) ||
+                  `\x1b[48;5;${dark ? 236 : 252}m`;
+
+  _barConfig = { width, emptyBg, gradient, truecolor, isRgb };
   return _barConfig;
 }
 
@@ -422,26 +550,41 @@ async function readStdin() {
     process.stdin.setEncoding('utf8');
     process.stdin.on('data', (chunk) => { data += chunk; });
     process.stdin.on('end', () => {
-      try { resolve(JSON.parse(data)); }
-      catch { resolve({}); }
+      try {
+        resolve(data.trim() ? JSON.parse(data) : {});
+      } catch (err) {
+        console.warn(`howmuchleft: failed to parse stdin JSON: ${err.message}`);
+        resolve({});
+      }
     });
   });
 }
 
-// Color buckets: green -> yellow -> orange -> red
-function getProgressColor(percent) {
-  if (percent < 40) return colors.green;
-  if (percent < 60) return colors.yellow;
-  if (percent < 80) return colors.orange;
-  return colors.red;
-}
+/**
+ * Get foreground and background ANSI escape codes for a given percent.
+ * Uses smooth RGB interpolation for truecolor, nearest-stop for 256-color.
+ */
+function getGradientStop(percent) {
+  const { gradient, truecolor, isRgb } = getBarConfig();
+  const t = Math.max(0, Math.min(1, percent / 100));
 
-// Background color variant for filled bar cells
-function getProgressBgColor(percent) {
-  if (percent < 40) return '\x1b[42m';
-  if (percent < 60) return '\x1b[43m';
-  if (percent < 80) return '\x1b[48;5;208m';
-  return '\x1b[41m';
+  if (isRgb) {
+    const rgb = interpolateRgb(gradient, t);
+    if (truecolor) {
+      return {
+        fg: `\x1b[38;2;${rgb[0]};${rgb[1]};${rgb[2]}m`,
+        bg: `\x1b[48;2;${rgb[0]};${rgb[1]};${rgb[2]}m`,
+      };
+    }
+    // RGB gradient on 256-color terminal: convert to nearest index
+    const idx = rgbTo256(rgb);
+    return { fg: `\x1b[38;5;${idx}m`, bg: `\x1b[48;5;${idx}m` };
+  }
+
+  // 256-color gradient: snap to nearest stop
+  const idx = Math.round(t * (gradient.length - 1));
+  const colorIdx = gradient[idx];
+  return { fg: `\x1b[38;5;${colorIdx}m`, bg: `\x1b[48;5;${colorIdx}m` };
 }
 
 /**
@@ -452,27 +595,26 @@ function getProgressBgColor(percent) {
 function progressBar(percent, width) {
   const config = getBarConfig();
   if (width == null) width = config.width;
-  const emptyBg = `\x1b[48;5;${config.emptyBg}m`;
+  const emptyBg = config.emptyBg;
 
   if (percent === null || percent === undefined) {
     return `${emptyBg}${' '.repeat(width)}${colors.reset}`;
   }
   const clamped = Math.max(0, Math.min(100, percent));
-  const color = getProgressColor(clamped);
-  const bgColor = getProgressBgColor(clamped);
+  const { fg, bg } = getGradientStop(clamped);
   const fillFrac = clamped / 100;
   let out = '';
   for (let i = 0; i < width; i++) {
     const cellStart = i / width;
     const cellEnd = (i + 1) / width;
     if (cellEnd <= fillFrac) {
-      out += bgColor + ' ';
+      out += bg + ' ';
     } else if (cellStart >= fillFrac) {
       out += emptyBg + ' ';
     } else {
       const cellFill = (fillFrac - cellStart) / (1 / width);
       const idx = Math.max(0, Math.min(FRACTIONAL_CHARS.length - 1, Math.floor(cellFill * FRACTIONAL_CHARS.length)));
-      out += emptyBg + color + FRACTIONAL_CHARS[idx];
+      out += emptyBg + fg + FRACTIONAL_CHARS[idx];
     }
   }
   return out + colors.reset;
@@ -608,7 +750,38 @@ async function main() {
   console.log(lines.join('\n'));
 }
 
-module.exports = { main, CONFIG_PATH };
+/**
+ * Render a gradient swatch so users can preview their color config.
+ * Shows bars at 0%, 25%, 50%, 75%, 100% plus a continuous gradient strip.
+ */
+function testColors() {
+  const config = getBarConfig();
+  const dark = isDarkMode();
+  const tc = config.truecolor;
+
+  console.log(`Mode: ${dark ? 'dark' : 'light'}, Color: ${tc ? 'truecolor' : '256-color'}, Width: ${config.width}`);
+  console.log();
+
+  // Sample bars at key percentages
+  for (const pct of [5, 20, 35, 50, 65, 80, 95]) {
+    const bar = progressBar(pct);
+    console.log(`${bar} ${pct}%`);
+  }
+
+  console.log();
+
+  // Continuous gradient strip (40 cells, each colored by position)
+  const stripWidth = 40;
+  let strip = '';
+  for (let i = 0; i < stripWidth; i++) {
+    const pct = (i / (stripWidth - 1)) * 100;
+    const { bg } = getGradientStop(pct);
+    strip += bg + ' ';
+  }
+  console.log(strip + colors.reset + '  gradient');
+}
+
+module.exports = { main, CONFIG_PATH, progressBar, formatPercent, formatTimeRemaining, colors, testColors };
 
 // Run directly when invoked as a script (not when required by cli.js)
 if (require.main === module) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "howmuchleft",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Pixel-perfect progress bars showing how much context and usage you have left, right in your Claude Code statusline",
   "bin": {
     "howmuchleft": "bin/cli.js"