@ttigger/claude-status 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ttigger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# @ttigger/claude-status
+
+A portable Claude Code statusline HUD — model, project, git, context bar, and real usage limits right in your terminal.
+
+---
+
+## Why
+
+- **Usage limits in the CLI** — brings the claude.ai Session (5 h rolling) and Weekly (7 d) usage meters and their reset countdowns into every Claude Code session; no browser tab required.
+- **One command, nothing to clone** — `npx @ttigger/claude-status install` fetches and wires everything; works on any machine with Node ≥ 18.
+- **7 styles including Claude brand** — coral `claude` default, `minimal`, `classic`, `tech` (Nerd Font), `data` (braille), `ascii` (most compatible), `emoji`.
+- **Single-line adaptive layout** — `auto` layout packs everything onto one line and gracefully wraps to two or three lines only when the terminal is narrow.
+- **Theme-aware colors** — reads `~/.claude/settings.json` and mirrors Claude Code's light/dark/system theme; no manual palette config required.
+- **`cc` launcher** — a tiny `cc` shim that forwards all args to `claude`, saving keystrokes on every invocation.
+- **Config with live preview** — `claude-status config set` and `claude-status preview` let you tweak and instantly see the result in your actual terminal colors.
+- **Pure Node, cross-OS** — CommonJS, zero runtime dependencies, works on Windows, macOS, and Linux.
+
+---
+
+## Quick Start
+
+```sh
+npx @ttigger/claude-status install
+```
+
+Then open a new Claude Code session. The HUD appears automatically at the top of every prompt.
+
+---
+
+## The HUD
+
+```
+ Opus 4.8·1M | claude-status | main
+Ctx ▰▰▱▱▱▱ 23% 47k | compact 60%
+Sess ▰▰▰▰▰▱ 52% 3h12m | Wk ▰▰▱▱▱ 31% 4d6h
+```
+
+| Element | What it shows |
+|---|---|
+| **Model** | Current model name, e.g. `Opus 4.8`. The `·1M` tag appears when the 1 M-token context window is active. |
+| **Project folder** | The base name of the current working directory. |
+| **Git branch** | Active branch name (blank when not in a git repo). |
+| **Context bar + %** | A progress bar showing how full the context window is, plus a percentage and token count in thousands (e.g. `47k`). |
+| **Auto-compact remaining** | The percentage of context headroom left before Claude Code triggers auto-compaction. **This value is approximate** — the threshold is configurable (default ~83.5 %) and may differ from Claude Code's internal trigger. |
+| **Session usage** | Rolling 5-hour usage bar + percentage + countdown to reset (e.g. `3h12m`). |
+| **Weekly usage** | 7-day usage bar + percentage + countdown to reset (e.g. `4d6h`). |
+
+---
+
+## Styles
+
+Seven styles are available. Choose with `claude-status config set style <name>`.
+
+### `claude` (default — Claude coral brand)
+
+```
+Opus 4.8·1M | claude-status | main
+Ctx ▰▰▱▱▱▱ 23% 47k | compact 60%
+Sess ▰▰▰▰▰▱ 52% 3h12m | Wk ▰▰▱▱▱ 31% 4d6h
+```
+
+### `minimal`
+
+```
+Opus 4.8·1M | claude-status | main
+ctx ▪▪░░░░ 23% 47k · compact 60%
+ses ▪▪▪░░░ 52% 3h12m · wk ▪▪░░░ 31% 4d6h
+```
+
+### `classic` (fallback default)
+
+```
+Opus 4.8·1M | claude-status | ⎇ main
+Ctx ▓▓░░░░░░ 23% · 47k | compact in 60%
+Sess ▓▓▓▓▓░ 52% · 3h12m | Wk ▓▓░░░ 31% · 4d6h
+```
+
+### `tech` (needs Nerd Font)
+
+```
+ Opus 4.8 1M │  claude-status │  main
+󰍛 ███▱▱▱▱ 23% 47k │ ♻ 60%
+ █████▱ 52% 3h12m │  ██▱▱▱ 31% 4d6h
+```
+
+### `data`
+
+```
+Opus-4.8[1M] | claude-status | git:main
+CTX ⣿⣿⣀⠀⠀ 23.4% 47.0k/200k | AC 60.0%
+5H  ⣿⣿⣿⣀⠀ 52.1% ⟳3h12m | 7D ⣿⣀⠀⠀⠀ 31.0% ⟳4d6h
+```
+
+### `ascii` (most compatible)
+
+```
+Opus 4.8 1M | claude-status | main
+Ctx [##------] 23% 47k | compact 60%
+Ses [####----] 52% 3h12m | Wk [##------] 31% 4d6h
+```
+
+### `emoji`
+
+```
+🤖 Opus 4.8·1M | 📁 claude-status | 🌿 main
+🧠 ▓▓░░░░ 23% 47k | ♻️ 60%
+⏱️ ▓▓▓▓▓░ 52% 3h12m | 📅 ▓░░░░ 31% 4d6h
+```
+
+---
+
+## Configuration
+
+Configuration is stored in `~/.claude/claude-status.config.json`. Only the keys you change are written — it is a **deep merge**, so you never need to specify the full config.
+
+### CLI
+
+| Command | Description |
+|---|---|
+| `claude-status config set <key> <value>` | Set a single config key |
+| `claude-status config get <key>` | Print the current value of a key |
+| `claude-status config list` | Print all current settings |
+| `claude-status config reset [key]` | Reset one key (or all) to defaults |
+
+### Dotted keys for nested settings
+
+```sh
+claude-status config set elements.weekly false       # hide weekly usage
+claude-status config set colorThresholds.green 40    # green up to 40 %
+claude-status config set colorThresholds.yellow 70   # yellow 40–70 %, red above
+claude-status config set autoCompact.thresholdPct 80 # approximate compaction threshold
+claude-status config set barWidth 10                 # wider bars
+claude-status config set style minimal               # switch style
+claude-status config set layout two                  # two-line layout
+```
+
+### Example config file
+
+```json
+{
+  "style": "claude",
+  "layout": "auto",
+  "barWidth": 8,
+  "colorThresholds": {
+    "green": 50,
+    "yellow": 80
+  },
+  "elements": {
+    "model": true,
+    "project": true,
+    "gitBranch": true,
+    "context": true,
+    "autoCompact": true,
+    "session": true,
+    "weekly": true
+  },
+  "autoCompact": {
+    "thresholdPct": 83.5
+  }
+}
+```
+
+Only include keys you want to override — unset keys fall back to defaults.
+
+---
+
+## Preview
+
+See the HUD rendered in your actual terminal colors before committing to a style:
+
+```sh
+claude-status preview --style tech
+claude-status preview --style emoji --layout three
+```
+
+`preview` is a live WYSIWYG render — it applies the real theme colors from `~/.claude/settings.json` and prints every layout variant side by side.
+
+---
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `npx @ttigger/claude-status install` | Install / re-install the HUD into Claude Code |
+| `claude-status uninstall` | Remove the HUD and restore `~/.claude/settings.json` from backup |
+| `claude-status config set <key> <value>` | Set a config value |
+| `claude-status config get <key>` | Get a config value |
+| `claude-status config list` | List all config values |
+| `claude-status config reset [key]` | Reset to default(s) |
+| `claude-status preview [--style s] [--layout l]` | Live WYSIWYG preview |
+| `claude-status help` | Print help |
+
+---
+
+## Updating / Uninstall
+
+**Update to the latest version:**
+
+```sh
+npx @ttigger/claude-status@latest install
+```
+
+**Uninstall:**
+
+```sh
+claude-status uninstall
+```
+
+The uninstaller restores `~/.claude/settings.json` from the `.bak` backup created during install, so your previous hooks configuration is preserved.
+
+---
+
+## `cc` Launcher
+
+The `cc` bin is a thin wrapper that calls `claude` and passes all arguments through unchanged. It saves a few keystrokes on every invocation.
+
+**Name collision on macOS / Linux:** `cc` is the POSIX name for the system C compiler. The installer detects this and warns you on macOS and Linux so you can make an informed choice. Windows has no such collision.
+
+If you would rather use a different alias, pass `--alias` during install:
+
+```sh
+npx @ttigger/claude-status install --alias clc
+```
+
+This registers `clc` instead of `cc` so there is no conflict with the system compiler.
+
+---
+
+## Security
+
+No data leaves your machine — the package only reads/writes `~/.claude/settings.json` (with a `.bak` backup), reads your config and theme, runs local `git`, and spawns `claude`. See [SECURITY.md](./SECURITY.md) for the full data boundary statement.
+
+---
+
+## License
+
+MIT © 2026 ttigger

package/bin/cc.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+const { spawn } = require('node:child_process');
+
+const target = process.env.CLAUDE_STATUS_CLAUDE_BIN || 'claude';
+const child = spawn(target, process.argv.slice(2), { stdio: 'inherit', shell: false });
+
+child.on('error', (err) => {
+  if (err.code === 'ENOENT') {
+    process.stderr.write(`cc: could not find "${target}" on PATH. Is Claude Code installed?\n`);
+    process.exit(127);
+  }
+  process.stderr.write(`cc: failed to launch claude: ${err.message}\n`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code == null ? 0 : code);
+});

package/bin/claude-status-render.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { renderHud } = require('../src/render');
+const { loadConfig } = require('../src/config');
+const { capabilities } = require('../src/detect');
+const { currentBranch } = require('../src/git');
+
+function readStdin() {
+  try { return fs.readFileSync(0, 'utf8'); } catch { return ''; }
+}
+function readTheme(settingsPath) {
+  try {
+    const s = JSON.parse(fs.readFileSync(settingsPath, 'utf8').replace(/^/, ''));
+    return /^light/.test(s.theme || '') ? 'light' : 'dark';
+  } catch { return 'dark'; }
+}
+
+function main() {
+  let stdin = {};
+  try { stdin = JSON.parse(readStdin()) || {}; } catch { stdin = {}; }
+  const claudeDir = path.join(os.homedir(), '.claude');
+  const config = loadConfig(path.join(claudeDir, 'claude-status.config.json'));
+  const theme = readTheme(path.join(claudeDir, 'settings.json'));
+  const caps = capabilities(process.env, process.platform);
+  const columns = parseInt(process.env.COLUMNS, 10) || 100;
+  const cwd = (stdin.workspace && stdin.workspace.current_dir) || process.cwd();
+  const branch = config.elements.gitBranch ? currentBranch(cwd) : null;
+  const now = Math.floor(Date.now() / 1000);
+  try {
+    process.stdout.write(renderHud({ stdin, config, theme, caps, columns, now, branch }));
+  } catch {
+    // never break the user's session; print nothing on unexpected error
+  }
+}
+main();

package/bin/claude-status.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+const os = require('node:os');
+const { execSync } = require('node:child_process');
+const { configPath } = require('../src/installer/paths');
+const { runInstall, runUninstall } = require('../src/installer/install');
+const { loadConfig, getDotted, setConfig, resetConfig } = require('../src/config');
+const { CONFIG_SCHEMA, STYLES, LAYOUTS } = require('../src/registry');
+const { renderSample, galleryLine } = require('../src/preview');
+
+function parseFlags(args) {
+  const flags = {}; const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--')) { flags[args[i].slice(2)] = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : true; }
+    else positional.push(args[i]);
+  }
+  return { flags, positional };
+}
+
+const HELP = `claude-status — Claude Code usage HUD + cc launcher
+
+Usage:
+  claude-status install [--style <name>] [--alias <name>] [--dry-run]
+  claude-status uninstall
+  claude-status config set <key> <value>
+  claude-status config get <key>
+  claude-status config list
+  claude-status config reset [<key>]
+  claude-status preview [--style <name>] [--layout <name>]
+  claude-status help [styles|layout|colors|cc|troubleshooting]
+
+Styles: ${STYLES.map(s => s.name).join(', ')}
+Layouts: ${LAYOUTS.map(l => l.name).join(', ')}`;
+
+function cmdInstall(flags) {
+  const summary = runInstall({
+    home: os.homedir(), env: process.env, platform: process.platform,
+    style: typeof flags.style === 'string' ? flags.style : null,
+    refreshInterval: 30,
+    dryRun: !!flags['dry-run'],
+    globalInstall: () => {
+      try { execSync('npm install -g @ttigger/claude-status', { stdio: 'ignore' }); } catch {}
+    },
+    resolveCc: () => { try { return execSync('command -v cc', { stdio: ['ignore','pipe','ignore'] }).toString().trim() || null; } catch { return null; } },
+  });
+  if (summary.dryRun) {
+    console.log(`[dry-run] no changes written. Would install style=${summary.chosenStyle} (recommended ${summary.recommendedStyle})`);
+    console.log(`[dry-run] would update ${summary.settingsPath} (with .bak) and write ${summary.configPath}`);
+  } else {
+    console.log(`✓ installed. style=${summary.chosenStyle} (recommended ${summary.recommendedStyle})`);
+  }
+  if (summary.ccCollision) console.log('⚠ "cc" already exists on PATH (C compiler?). Consider: claude-status install --alias clc');
+  console.log(summary.dryRun ? 'Preview:' : 'Open a new Claude Code session to see the HUD. Preview now:');
+  console.log(renderSample({ style: summary.chosenStyle, columns: parseInt(process.env.COLUMNS,10) || 100 }));
+}
+
+function cmdConfig(positional, flags) {
+  const sub = positional[0];
+  const cp = configPath(os.homedir());
+  if (sub === 'set') {
+    const [, key, value] = positional;
+    const r = setConfig(cp, key, value);
+    if (!r.ok) { console.error(r.error); process.exit(1); }
+    console.log(`✓ ${key} → ${r.value}. 目前效果：`);
+    const cfg = loadConfig(cp);
+    console.log(renderSample({ style: cfg.style, layout: cfg.layout, columns: parseInt(process.env.COLUMNS,10) || 100 }));
+    return;
+  }
+  if (sub === 'get') { console.log(getDotted(loadConfig(cp), positional[1])); return; }
+  if (sub === 'reset') { const r = resetConfig(cp, positional[1]); if (!r.ok){console.error(r.error);process.exit(1);} console.log('✓ reset'); return; }
+  if (sub === 'list') {
+    const cfg = loadConfig(cp);
+    for (const [key, spec] of Object.entries(CONFIG_SCHEMA)) {
+      const cur = getDotted(cfg, key);
+      const choices = spec.choices ? ` choices: ${spec.choices.join('|')}` : (spec.min!=null?` range: ${spec.min}-${spec.max}`:'');
+      console.log(`${key} = ${cur}${choices}`);
+    }
+    console.log('\nStyles preview:');
+    for (const s of STYLES) console.log(`  ${s.name === cfg.style ? '●' : '○'} ${s.name.padEnd(8)} ${galleryLine(s.name, 80)}`);
+    return;
+  }
+  console.error('Unknown config subcommand. See: claude-status help'); process.exit(1);
+}
+
+function cmdPreview(flags) {
+  console.log(renderSample({
+    style: typeof flags.style === 'string' ? flags.style : undefined,
+    layout: typeof flags.layout === 'string' ? flags.layout : undefined,
+    columns: parseInt(process.env.COLUMNS, 10) || 100,
+  }));
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
+    console.log(HELP); return;
+  }
+  if (argv[0] === '--version') { console.log(require('../package.json').version); return; }
+  const { flags, positional } = parseFlags(argv.slice(1));
+  switch (argv[0]) {
+    case 'install': return cmdInstall(flags);
+    case 'uninstall': runUninstall({ home: os.homedir() }); console.log('✓ uninstalled'); return;
+    case 'config': return cmdConfig(positional, flags);
+    case 'preview': return cmdPreview(flags);
+    default: console.error(`Unknown command: ${argv[0]}`); console.log(HELP); process.exit(1);
+  }
+}
+main();

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@ttigger/claude-status",
+  "version": "0.1.0",
+  "description": "A portable Claude Code statusline HUD (usage, model, git, context) with 7 styles, a cc launcher, and a config CLI with live preview.",
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "bin": {
+    "claude-status": "bin/claude-status.js",
+    "claude-status-render": "bin/claude-status-render.js",
+    "cc": "bin/cc.js"
+  },
+  "files": ["bin/", "src/", "README.md", "LICENSE"],
+  "scripts": { "test": "node --test" },
+  "keywords": ["claude", "claude-code", "statusline", "cli", "usage", "hud"],
+  "repository": { "type": "git", "url": "git+https://github.com/TTigger/claude-status.git" },
+  "homepage": "https://github.com/TTigger/claude-status#readme"
+}

package/src/config.js

@@ -0,0 +1,87 @@
+const fs = require('node:fs');
+const { DEFAULT_CONFIG, setDotted } = require('./defaults');
+const { CONFIG_SCHEMA } = require('./registry');
+
+function isObj(v) { return v && typeof v === 'object' && !Array.isArray(v); }
+
+function deepMerge(base, over) {
+  const out = Array.isArray(base) ? base.slice() : { ...base };
+  for (const [k, v] of Object.entries(over || {})) {
+    out[k] = isObj(v) && isObj(out[k]) ? deepMerge(out[k], v) : v;
+  }
+  return out;
+}
+
+function loadConfig(configPath) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(configPath, 'utf8').replace(/^/, ''));
+    return deepMerge(DEFAULT_CONFIG, raw);
+  } catch {
+    return deepMerge(DEFAULT_CONFIG, {});
+  }
+}
+
+function coerceValue(key, raw) {
+  const spec = CONFIG_SCHEMA[key];
+  if (!spec) return { ok: false, error: `Unknown setting: ${key}` };
+  switch (spec.type) {
+    case 'choice':
+      return spec.choices.includes(raw)
+        ? { ok: true, value: raw }
+        : { ok: false, error: `Invalid value "${raw}". Choices: ${spec.choices.join(', ')}` };
+    case 'string':
+      return { ok: true, value: String(raw) };
+    case 'bool':
+      if (/^(true|1|yes|on)$/i.test(raw)) return { ok: true, value: true };
+      if (/^(false|0|no|off)$/i.test(raw)) return { ok: true, value: false };
+      return { ok: false, error: `Expected boolean, got "${raw}"` };
+    case 'int':
+    case 'number': {
+      const n = spec.type === 'int' ? parseInt(raw, 10) : parseFloat(raw);
+      if (Number.isNaN(n)) return { ok: false, error: `Expected number, got "${raw}"` };
+      if (spec.min != null && n < spec.min) return { ok: false, error: `Min is ${spec.min}` };
+      if (spec.max != null && n > spec.max) return { ok: false, error: `Max is ${spec.max}` };
+      return { ok: true, value: n };
+    }
+    case 'intOrAuto':
+      if (raw === 'auto') return { ok: true, value: 'auto' };
+      return coerceValue.asInt(key, raw, spec);
+    default:
+      return { ok: false, error: `Unsupported type for ${key}` };
+  }
+}
+coerceValue.asInt = (key, raw, spec) => {
+  const n = parseInt(raw, 10);
+  if (Number.isNaN(n)) return { ok: false, error: `Expected integer or "auto"` };
+  if (spec.min != null && n < spec.min) return { ok: false, error: `Min is ${spec.min}` };
+  if (spec.max != null && n > spec.max) return { ok: false, error: `Max is ${spec.max}` };
+  return { ok: true, value: n };
+};
+
+function getDotted(obj, key) {
+  return key.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj);
+}
+
+function readRaw(configPath) {
+  try { return JSON.parse(fs.readFileSync(configPath, 'utf8')); } catch { return {}; }
+}
+
+function setConfig(configPath, key, rawValue) {
+  const c = coerceValue(key, rawValue);
+  if (!c.ok) return c;
+  const raw = readRaw(configPath);
+  setDotted(raw, key, c.value);
+  fs.writeFileSync(configPath, JSON.stringify(raw, null, 2) + '\n');
+  return { ok: true, value: c.value };
+}
+
+function resetConfig(configPath, key) {
+  const raw = readRaw(configPath);
+  if (!key) { try { fs.unlinkSync(configPath); } catch {} return { ok: true }; }
+  if (!(key in CONFIG_SCHEMA)) return { ok: false, error: `Unknown setting: ${key}` };
+  setDotted(raw, key, CONFIG_SCHEMA[key].default);
+  fs.writeFileSync(configPath, JSON.stringify(raw, null, 2) + '\n');
+  return { ok: true };
+}
+
+module.exports = { deepMerge, loadConfig, coerceValue, getDotted, setConfig, resetConfig };

package/src/defaults.js

@@ -0,0 +1,22 @@
+const { CONFIG_SCHEMA } = require('./registry');
+
+function setDotted(obj, path, value) {
+  const parts = path.split('.');
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    cur[parts[i]] = cur[parts[i]] || {};
+    cur = cur[parts[i]];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+
+function buildDefaults() {
+  const cfg = {};
+  for (const [key, spec] of Object.entries(CONFIG_SCHEMA)) {
+    setDotted(cfg, key, spec.default);
+  }
+  return cfg;
+}
+
+const DEFAULT_CONFIG = buildDefaults();
+module.exports = { DEFAULT_CONFIG, setDotted };

package/src/detect.js

@@ -0,0 +1,17 @@
+function capabilities(env, platform) {
+  const truecolor = /^(truecolor|24bit)$/i.test(env.COLORTERM || '');
+  const color256 = truecolor || /256/.test(env.TERM || '');
+  const unicode = platform !== 'win32' || !!env.WT_SESSION;
+  // Nerd Font cannot be reliably auto-detected; honor explicit opt-in.
+  const nerd = env.CLAUDE_STATUS_NERD === '1';
+  return { truecolor, color256, unicode, nerd };
+}
+
+function recommendStyle(caps) {
+  if (!caps.unicode) return 'ascii';
+  if (caps.nerd) return 'tech';
+  if (caps.truecolor || caps.color256) return 'claude';
+  return 'classic';
+}
+
+module.exports = { capabilities, recommendStyle };

package/src/elements.js

@@ -0,0 +1,46 @@
+const { clampPct } = require('./format');
+
+function basename(p) {
+  if (!p) return null;
+  const parts = String(p).split(/[\\/]/).filter(Boolean);
+  return parts.length ? parts[parts.length - 1] : null;
+}
+
+function sumUsage(u) {
+  if (!u || typeof u !== 'object') return 0;
+  let total = 0;
+  for (const v of Object.values(u)) if (typeof v === 'number') total += v;
+  return total;
+}
+
+function buildElements(stdin, opts) {
+  const cw = stdin.context_window || {};
+  const size = cw.context_window_size || 200000;
+  const usedPct = typeof cw.used_percentage === 'number' ? cw.used_percentage : 0;
+  let usedTokens = sumUsage(cw.current_usage);
+  if (!usedTokens) usedTokens = (size * usedPct) / 100;
+
+  const sizeKnown = Boolean(cw.context_window_size);
+  const model = stdin.model
+    ? { name: stdin.model.display_name || stdin.model.id || '?',
+        context1m: sizeKnown ? size === 1000000 : /\[1m\]/.test(stdin.model.id || '') }
+    : null;
+
+  const rl = stdin.rate_limits || {};
+  const mk = (r) => (r ? { pct: clampPct(r.used_percentage), resetsAt: r.resets_at } : null);
+
+  const acLeft = Math.max(0, Math.round(opts.autoCompactThresholdPct - usedPct));
+
+  return {
+    model,
+    project: basename((stdin.workspace || {}).project_dir) ||
+             basename((stdin.workspace || {}).current_dir),
+    branch: null, // resolved by render caller via git
+    context: { pct: clampPct(usedPct), tokensK: Math.round(usedTokens / 1000), sizeK: Math.round(size / 1000) },
+    autoCompact: { leftPct: acLeft },
+    session: mk(rl.five_hour),
+    weekly: mk(rl.seven_day),
+  };
+}
+
+module.exports = { buildElements, basename };

package/src/engine.js

@@ -0,0 +1,84 @@
+const { bar, tier, humanizeDuration, tokensK } = require('./format');
+const { colorize } = require('./palette');
+
+function renderMetric({ label, pct, suffix, style, palette, thresholds, barWidth }) {
+  const tierName = tier(pct, thresholds);
+  const glyphs = style.bar;
+  const [open, close] = style.barWrap;
+  const filledStr = bar(pct, barWidth, { full: glyphs.full, empty: glyphs.empty });
+  // color the whole bar interior + percent by tier; brackets/label uncolored
+  const coloredBar = open + colorize(filledStr, tierName, palette) + close;
+  const coloredPct = colorize(`${pct}%`, tierName, palette);
+  const parts = [label, coloredBar, coloredPct];
+  if (suffix) parts.push(suffix);
+  return parts.filter(Boolean).join(' ');
+}
+
+function fmtReset(resetsAt, now, precision) {
+  if (!resetsAt) return '';
+  const d = humanizeDuration(resetsAt - now);
+  if (precision === 'short') return d.replace(/^(\d+[dh])\d+[hm]$/, '$1'); // 3h12m->3h, 4d6h->4d
+  return d;
+}
+
+function buildParts({ els, style, palette, config, now, opts }) {
+  const parts = [];
+  const L = style.labels;
+  const icons = style.icons || {};
+  const lc = (s) => (style.lowercase ? s.toLowerCase() : s);
+  const push = (key, text, group) => { if (text) parts.push({ key, text, group }); };
+  const thresholds = config.colorThresholds;
+  const barWidth = config.barWidth === 'auto' ? 8 : config.barWidth;
+
+  // env group
+  if (config.elements.model && els.model) {
+    const name = els.model.name + (els.model.context1m ? '·1M' : '');
+    push('model', (icons.model ? icons.model + ' ' : '') + name, 'env');
+  }
+  if (config.elements.project && els.project) {
+    push('project', (icons.project ? icons.project + ' ' : '') + els.project, 'env');
+  }
+  if (config.elements.gitBranch && els.branch) {
+    const lbl = L.branch ? L.branch + (icons.project ? ' ' : '') : '';
+    push('branch', (lbl ? lbl + ' ' : '') + els.branch, 'env');
+  }
+
+  // context group
+  if (config.elements.context && els.context) {
+    const c = els.context;
+    let suffix = '';
+    if (opts.includeTokens) {
+      suffix = style.rawTokens
+        ? `${tokensK(c.tokensK * 1000, style.decimals)}/${c.sizeK}k`
+        : tokensK(c.tokensK * 1000, style.decimals);
+    }
+    const text = opts.bars
+      ? renderMetric({ label: lc(L.ctx), pct: c.pct, suffix, style, palette, thresholds, barWidth })
+      : `${lc(L.ctx)} ${colorizePct(c.pct, thresholds, palette)}${suffix ? ' ' + suffix : ''}`;
+    push('context', text, 'context');
+  }
+  if (config.elements.autoCompact && els.autoCompact && opts.includeAutoCompact) {
+    push('autoCompact', `${lc(L.ac)} ${els.autoCompact.leftPct}%`, 'context');
+  }
+
+  // limits group
+  const limit = (key, lbl, el) => {
+    if (!el) return;
+    const reset = fmtReset(el.resetsAt, now, opts.resetPrecision);
+    const text = opts.bars
+      ? renderMetric({ label: lc(lbl), pct: el.pct, suffix: reset, style, palette, thresholds, barWidth })
+      : `${lc(lbl)} ${colorizePct(el.pct, thresholds, palette)}${reset ? ' ' + reset : ''}`;
+    push(key, text, 'limits');
+  };
+  if (config.elements.session) limit('session', L.sess, els.session);
+  if (config.elements.weekly) limit('weekly', L.wk, els.weekly);
+
+  return parts;
+}
+
+// helper: colored "NN%" without a bar
+function colorizePct(pct, thresholds, palette) {
+  return colorize(`${pct}%`, tier(pct, thresholds), palette);
+}
+
+module.exports = { renderMetric, buildParts };

package/src/fixtures.js

@@ -0,0 +1,18 @@
+// Representative statusline stdin JSON for preview + tests.
+const SAMPLE = {
+  model: { id: 'claude-opus-4-8[1m]', display_name: 'Opus 4.8' },
+  workspace: { project_dir: '/home/u/claude-status', current_dir: '/home/u/claude-status' },
+  worktree: { branch: 'main' },
+  context_window: {
+    context_window_size: 1000000,
+    used_percentage: 23.5,
+    current_usage: { input_tokens: 40000, cache_read_input_tokens: 7000 },
+  },
+  rate_limits: {
+    five_hour: { used_percentage: 52, resets_at: 1717400000 },
+    seven_day: { used_percentage: 31, resets_at: 1717755680 },
+  },
+};
+// "now" so sample resets render as 3h12m / 4d6h deterministically:
+const SAMPLE_NOW = 1717400000 - (3 * 3600 + 12 * 60);
+module.exports = { SAMPLE, SAMPLE_NOW };

package/src/format.js

@@ -0,0 +1,38 @@
+function clampPct(n) {
+  if (typeof n !== 'number' || Number.isNaN(n)) return 0;
+  return Math.max(0, Math.min(100, Math.round(n)));
+}
+
+function tier(pct, thresholds) {
+  const { green, yellow } = thresholds;
+  if (pct <= green) return 'low';
+  if (pct <= yellow) return 'mid';
+  return 'high';
+}
+
+function bar(pct, width, glyphs) {
+  const p = clampPct(pct);
+  const filled = Math.round((p / 100) * width);
+  return glyphs.full.repeat(filled) + glyphs.empty.repeat(width - filled);
+}
+
+function humanizeDuration(seconds) {
+  let s = Math.floor(seconds);
+  if (s <= 0) return s < 0 ? '0m' : '<1m';
+  if (s < 60) return '<1m';
+  const d = Math.floor(s / 86400); s -= d * 86400;
+  const h = Math.floor(s / 3600); s -= h * 3600;
+  const m = Math.floor(s / 60);
+  if (d > 0) return `${d}d${h}h`;
+  if (h > 0) return `${h}h${m}m`;
+  return `${m}m`;
+}
+
+function tokensK(tokens, decimals = false) {
+  const k = tokens / 1000;
+  return decimals ? `${k.toFixed(1)}k` : `${Math.round(k)}k`;
+}
+
+function stripAnsi(s) { return s.replace(/\x1b\[[0-9;]*m/g, ''); }
+
+module.exports = { clampPct, tier, bar, humanizeDuration, tokensK, stripAnsi };

package/src/git.js

@@ -0,0 +1,14 @@
+const { execFileSync } = require('node:child_process');
+
+function currentBranch(cwd) {
+  try {
+    const out = execFileSync('git', ['branch', '--show-current'],
+      { cwd, timeout: 500, stdio: ['ignore', 'pipe', 'ignore'] });
+    const b = out.toString().trim();
+    return b || null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { currentBranch };

package/src/installer/alias.js

@@ -0,0 +1,12 @@
+function aliasSnippet(shell, name) {
+  if (shell === 'powershell') return `Set-Alias ${name} cc`;
+  return `alias ${name}='cc'`;
+}
+
+// resolver() returns a path string if `cc` exists on PATH, else null.
+function ccCollides(platform, resolver) {
+  if (platform === 'win32') return false; // no C-compiler `cc` collision on Windows
+  return !!resolver();
+}
+
+module.exports = { aliasSnippet, ccCollides };

package/src/installer/install.js

@@ -0,0 +1,62 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { settingsPath, configPath, backupPath, claudeDir } = require('./paths');
+const { mergeStatusLine, readSettings, writeSettingsWithBackup } = require('./settings');
+const { capabilities, recommendStyle } = require('../detect');
+const { ccCollides } = require('./alias');
+const { CONFIG_SCHEMA } = require('../registry');
+
+function runInstall(opts) {
+  const { home, env, platform, style, refreshInterval, globalInstall, resolveCc, dryRun } = opts;
+
+  const caps = capabilities(env, platform);
+  const recommended = recommendStyle(caps);
+  const chosen = style || recommended;
+  const cp = configPath(home);
+  const refresh = refreshInterval || CONFIG_SCHEMA.refreshIntervalSec.default;
+
+  // --dry-run reports what would happen but touches nothing on disk (spec §8).
+  if (!dryRun) {
+    fs.mkdirSync(claudeDir(home), { recursive: true });
+
+    if (typeof globalInstall === 'function') globalInstall(); // npm i -g (no-op in tests)
+
+    // write config only if absent, to preserve user edits
+    if (!fs.existsSync(cp)) {
+      fs.writeFileSync(cp, JSON.stringify({ style: chosen }, null, 2) + '\n');
+    } else if (style) {
+      const raw = JSON.parse(fs.readFileSync(cp, 'utf8'));
+      raw.style = chosen;
+      fs.writeFileSync(cp, JSON.stringify(raw, null, 2) + '\n');
+    }
+
+    const next = mergeStatusLine(readSettings(settingsPath(home)), 'claude-status-render', refresh);
+    writeSettingsWithBackup(settingsPath(home), backupPath(home), next);
+  }
+
+  return {
+    recommendedStyle: recommended,
+    chosenStyle: chosen,
+    caps,
+    ccCollision: ccCollides(platform, resolveCc || (() => null)),
+    settingsPath: settingsPath(home),
+    configPath: cp,
+    dryRun: !!dryRun,
+  };
+}
+
+function runUninstall(opts) {
+  const { home } = opts;
+  const sp = settingsPath(home), bp = backupPath(home);
+  if (fs.existsSync(bp)) {
+    fs.copyFileSync(bp, sp);
+    return { restored: true };
+  }
+  // no backup: just strip statusLine
+  const s = readSettings(sp);
+  delete s.statusLine;
+  fs.writeFileSync(sp, JSON.stringify(s, null, 2) + '\n');
+  return { restored: false };
+}
+
+module.exports = { runInstall, runUninstall };

package/src/installer/paths.js

@@ -0,0 +1,10 @@
+const path = require('node:path');
+const os = require('node:os');
+
+function home(h) { return h || os.homedir(); }
+function claudeDir(h) { return path.join(home(h), '.claude'); }
+function settingsPath(h) { return path.join(claudeDir(h), 'settings.json'); }
+function configPath(h) { return path.join(claudeDir(h), 'claude-status.config.json'); }
+function backupPath(h) { return path.join(claudeDir(h), 'settings.json.bak'); }
+
+module.exports = { claudeDir, settingsPath, configPath, backupPath };

package/src/installer/settings.js

@@ -0,0 +1,21 @@
+const fs = require('node:fs');
+
+function mergeStatusLine(settings, command, refreshInterval) {
+  return { ...settings, statusLine: { type: 'command', command, refreshInterval } };
+}
+
+function readSettings(p) {
+  // Strip a leading UTF-8 BOM (some editors add one) so JSON.parse doesn't throw
+  // and silently discard the user's existing settings on merge.
+  try { return JSON.parse(fs.readFileSync(p, 'utf8').replace(/^/, '')); } catch { return {}; }
+}
+
+function writeSettingsWithBackup(settingsPath, backupPath, nextObj) {
+  if (fs.existsSync(settingsPath)) {
+    fs.copyFileSync(settingsPath, backupPath);
+  }
+  fs.mkdirSync(require('node:path').dirname(settingsPath), { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(nextObj, null, 2) + '\n');
+}
+
+module.exports = { mergeStatusLine, readSettings, writeSettingsWithBackup };

package/src/layout.js

@@ -0,0 +1,51 @@
+function visibleWidth(s) { return s.replace(/\x1b\[[0-9;]*m/g, '').length; }
+
+const FULL_OPTS = { includeTokens: true, includeAutoCompact: true, resetPrecision: 'full', bars: true };
+
+const SHRINK = [
+  (o) => ({ ...o, includeTokens: false }),
+  (o) => ({ ...o, includeAutoCompact: false }),
+  (o) => ({ ...o, resetPrecision: 'short' }),
+  (o) => ({ ...o, bars: false }),
+  (o) => ({ ...o, dropBranch: true }),
+];
+
+function joinParts(parts, sep, dropBranch) {
+  return parts.filter(p => !(dropBranch && p.key === 'branch'))
+              .map(p => p.text).join(sep);
+}
+
+function byGroup(parts, group, sep) {
+  return parts.filter(p => p.group === group).map(p => p.text).join(sep);
+}
+
+function layoutLines(build, layout, columns, sep) {
+  if (layout === 'three') {
+    const p = build(FULL_OPTS);
+    return [byGroup(p, 'env', sep), byGroup(p, 'context', sep), byGroup(p, 'limits', sep)]
+      .filter(Boolean).join('\n');
+  }
+  if (layout === 'two') {
+    const p = build(FULL_OPTS);
+    const line1 = [byGroup(p, 'env', sep), byGroup(p, 'context', sep)].filter(Boolean).join(sep);
+    const line2 = byGroup(p, 'limits', sep);
+    return [line1, line2].filter(Boolean).join('\n');
+  }
+  if (layout === 'oneline') {
+    const p = build({ ...FULL_OPTS, includeTokens: false, includeAutoCompact: false });
+    return joinParts(p, sep, false);
+  }
+  let opts = { ...FULL_OPTS };
+  let line = joinParts(build(opts), sep, false);
+  for (const step of SHRINK) {
+    if (visibleWidth(line) <= columns) break;
+    opts = step(opts);
+    line = joinParts(build(opts), sep, opts.dropBranch);
+  }
+  if (visibleWidth(line) <= columns) return line;
+  const two = layoutLines(build, 'two', columns, sep);
+  if (two.split('\n').every(l => visibleWidth(l) <= columns)) return two;
+  return layoutLines(build, 'three', columns, sep);
+}
+
+module.exports = { layoutLines, visibleWidth };

package/src/palette.js

@@ -0,0 +1,36 @@
+const C256 = {
+  traffic: {
+    light: { low: 28, mid: 166, high: 160 },
+    dark: { low: 40, mid: 220, high: 196 },
+  },
+  coral: {
+    light: { low: 216, mid: 173, high: 167 },
+    dark: { low: 216, mid: 173, high: 167 },
+  },
+};
+const C8 = {
+  traffic: { low: 32, mid: 33, high: 31 },
+  coral: { low: 33, mid: 33, high: 31 },
+};
+
+function code256(n) { return `\x1b[38;5;${n}m`; }
+function code8(n) { return `\x1b[${n}m`; }
+
+function resolvePalette(mode, theme, caps) {
+  const t = theme === 'light' ? 'light' : 'dark';
+  let low, mid, high;
+  if (caps && caps.color256) {
+    const set = C256[mode][t];
+    low = code256(set.low); mid = code256(set.mid); high = code256(set.high);
+  } else {
+    const set = C8[mode];
+    low = code8(set.low); mid = code8(set.mid); high = code8(set.high);
+  }
+  return { low, mid, high, dim: '\x1b[2m', reset: '\x1b[0m' };
+}
+
+function colorize(text, tierName, palette) {
+  return palette[tierName] + text + palette.reset;
+}
+
+module.exports = { resolvePalette, colorize };

package/src/preview.js

@@ -0,0 +1,21 @@
+const { renderHud } = require('./render');
+const { DEFAULT_CONFIG } = require('./defaults');
+const { deepMerge } = require('./config');
+const { SAMPLE, SAMPLE_NOW } = require('./fixtures');
+
+function renderSample({ style, layout, columns, theme = 'dark' }) {
+  const config = deepMerge(DEFAULT_CONFIG, {
+    ...(style ? { style } : {}), ...(layout ? { layout } : {}),
+  });
+  return renderHud({
+    stdin: SAMPLE, config, theme,
+    caps: { unicode: true, color256: true, truecolor: true, nerd: true },
+    columns: columns || 100, now: SAMPLE_NOW, branch: 'main',
+  });
+}
+
+function galleryLine(style, columns) {
+  return renderSample({ style, layout: 'oneline', columns: columns || 100 });
+}
+
+module.exports = { renderSample, galleryLine };

package/src/registry.js

@@ -0,0 +1,61 @@
+const STYLES = [
+  { name: 'claude', label: 'Claude 簡潔風', bar: { full: '▰', empty: '▱' }, barWrap: ['', ''],
+    labels: { branch: '⎇', ctx: 'Ctx', sess: 'S', wk: 'W', ac: 'compact' },
+    icons: null, colorMode: 'coral', decimals: false, rawTokens: false, lowercase: false,
+    requires: 'truecolor' },
+  { name: 'minimal', label: 'Minimal 簡潔', bar: { full: '▪', empty: '░' }, barWrap: ['', ''],
+    labels: { branch: '', ctx: 'ctx', sess: 'ses', wk: 'wk', ac: 'compact' },
+    icons: null, colorMode: 'traffic', decimals: false, rawTokens: false, lowercase: true,
+    requires: 'unicode' },
+  { name: 'classic', label: 'Classic 區塊', bar: { full: '▓', empty: '░' }, barWrap: ['', ''],
+    labels: { branch: '⎇', ctx: 'Ctx', sess: 'Sess', wk: 'Wk', ac: 'compact in' },
+    icons: null, colorMode: 'traffic', decimals: false, rawTokens: false, lowercase: false,
+    requires: 'unicode' },
+  { name: 'tech', label: 'Tech 科技感', bar: { full: '█', empty: '▱' }, barWrap: ['', ''],
+    // Nerd Font glyphs as ES6 code-point escapes — plane-15 icons need \u{...}, not \uXXXX.
+    labels: { branch: '\u{E0A0}', ctx: '\u{F015B}', sess: '\u{F0CAB}', wk: '\u{F073}', ac: '\u{267B}' },
+    icons: { model: '\u{F2DB}', project: '\u{F07B}' }, colorMode: 'traffic', decimals: false,
+    rawTokens: false, lowercase: false, requires: 'nerd' },
+  { name: 'data', label: 'Data 數據控', bar: { full: '⣿', empty: '⠀' }, barWrap: ['', ''],
+    labels: { branch: 'git:', ctx: 'CTX', sess: '5H', wk: '7D', ac: 'AC' },
+    icons: null, colorMode: 'traffic', decimals: true, rawTokens: true, lowercase: false,
+    requires: 'braille' },
+  { name: 'ascii', label: 'ASCII 相容', bar: { full: '#', empty: '-' }, barWrap: ['[', ']'],
+    labels: { branch: '', ctx: 'Ctx', sess: 'Ses', wk: 'Wk', ac: 'compact' },
+    icons: null, colorMode: 'traffic', decimals: false, rawTokens: false, lowercase: false,
+    requires: 'ascii' },
+  { name: 'emoji', label: 'Emoji 活潑', bar: { full: '▓', empty: '░' }, barWrap: ['', ''],
+    labels: { branch: '🌿', ctx: '🧠', sess: '⏱️', wk: '📅', ac: '♻️' },
+    icons: { model: '🤖', project: '📁' }, colorMode: 'traffic', decimals: false,
+    rawTokens: false, lowercase: false, requires: 'emoji' },
+];
+
+const LAYOUTS = [
+  { name: 'auto', label: '單行自適應' },
+  { name: 'oneline', label: '單行精簡' },
+  { name: 'two', label: '兩行' },
+  { name: 'three', label: '三行分組' },
+];
+
+const CONFIG_SCHEMA = {
+  style: { type: 'choice', choices: STYLES.map(s => s.name), default: 'claude' },
+  layout: { type: 'choice', choices: LAYOUTS.map(l => l.name), default: 'auto' },
+  palette: { type: 'choice', choices: ['auto', 'light', 'dark'], default: 'auto' },
+  separator: { type: 'string', default: ' | ' },
+  barWidth: { type: 'intOrAuto', min: 1, max: 40, default: 8 },
+  'colorThresholds.green': { type: 'int', min: 0, max: 100, default: 50 },
+  'colorThresholds.yellow': { type: 'int', min: 0, max: 100, default: 80 },
+  'elements.model': { type: 'bool', default: true },
+  'elements.project': { type: 'bool', default: true },
+  'elements.gitBranch': { type: 'bool', default: true },
+  'elements.context': { type: 'bool', default: true },
+  'elements.autoCompact': { type: 'bool', default: true },
+  'elements.session': { type: 'bool', default: true },
+  'elements.weekly': { type: 'bool', default: true },
+  'autoCompact.thresholdPct': { type: 'number', min: 0, max: 100, default: 83.5 },
+  refreshIntervalSec: { type: 'int', min: 1, max: 3600, default: 30 },
+};
+
+function styleByName(name) { return STYLES.find(s => s.name === name) || null; }
+
+module.exports = { STYLES, LAYOUTS, CONFIG_SCHEMA, styleByName };

package/src/render.js

@@ -0,0 +1,36 @@
+const { buildElements } = require('./elements');
+const { buildParts } = require('./engine');
+const { layoutLines } = require('./layout');
+const { resolvePalette } = require('./palette');
+const { styleByName, STYLES } = require('./registry');
+
+function resolveTheme(configPalette, theme) {
+  if (configPalette === 'light' || configPalette === 'dark') return configPalette;
+  return theme === 'light' ? 'light' : 'dark';
+}
+
+function renderHud(ctx) {
+  const { stdin, config, theme, caps, columns, now, branch } = ctx;
+  const style = styleByName(config.style) || STYLES[0];
+  const els = buildElements(stdin, { autoCompactThresholdPct: config.autoCompact.thresholdPct });
+  els.branch = branch || null;
+
+  const effTheme = resolveTheme(config.palette, theme);
+  const palette = resolvePalette(style.colorMode, effTheme, caps);
+  const barWidth = config.barWidth === 'auto'
+    ? Math.max(4, Math.min(12, Math.floor((columns || 100) / 12)))
+    : config.barWidth;
+
+  const noLimits = !els.session && !els.weekly;
+  const build = (opts) => {
+    const parts = buildParts({ els, style, palette, config: { ...config, barWidth }, now, opts });
+    if (noLimits && (config.elements.session || config.elements.weekly)) {
+      parts.push({ key: 'limits-note', text: '— waiting for first message', group: 'limits' });
+    }
+    return parts;
+  };
+
+  return layoutLines(build, config.layout, columns || 100, config.separator);
+}
+
+module.exports = { renderHud };