ctxline-claude 1.1.0 → 1.2.1

package/README.md

@@ -29,6 +29,15 @@
 
 See your **current directory**, **active model**, **context window usage**, and **Claude usage limits** at a glance — including both your **current 5-hour session** and **weekly allowance**.
 
+## Contents
+
+- [Install](#install)
+- [Uninstall](#uninstall)
+- [What it shows](#what-it-shows)
+- [Configuration](#configuration)
+- [How it works](#how-it-works)
+- [FAQ](#faq)
+
 ## Install
 
 ```bash
@@ -67,6 +76,14 @@ chmod +x ~/.claude/hooks/statusline.js
 
 </details>
 
+## Update
+
+```bash
+npx ctxline-claude@latest
+```
+
+Re-runs the installer with the latest published version. Restart Claude Code or start a new session for the update to take effect.
+
 ## Uninstall
 
 ```bash
@@ -99,6 +116,7 @@ Remove-Item "$env:USERPROFILE\.claude\cache\usage-cache.json" -ErrorAction Silen
 | Segment | Detail |
 |---|---|
 | **Directory** | Current working directory |
+| **Branch** | Active git branch, with `↑N↓M` commits ahead / behind your upstream when it diverges |
 | **Model** | Active Claude model (Opus / Sonnet / Haiku) |
 | **Context** | Visual bar of context-window usage |
 | **Current** | Live 5-hour session limit + reset countdown (subscription users) |
@@ -112,6 +130,55 @@ Remove-Item "$env:USERPROFILE\.claude\cache\usage-cache.json" -ErrorAction Silen
 > [!NOTE]
 > **Responsive.** On a narrow terminal the line wraps to two — directory, model, and context on the first line; usage, cost, and task on the second. Wide terminals stay on a single line. (Auto-sizing needs Claude Code v2.1.153+.)
 
+> [!TIP]
+> Don't want every segment? You can hide any of them — see [Configuration](#configuration).
+
+## Configuration
+
+The statusline is zero-config by default. To **hide segments you don't want**, set the `CTXLINE_DISABLE` environment variable to a comma-separated list of any of:
+
+`branch` · `effort` · `cost` · `task` · `usage` (5-hour + weekly)
+
+Directory, model, and context always show; unknown names are ignored. Example below hides cost and the current task.
+
+### Option A — `settings.json` (recommended)
+
+Works on every OS and survives restarts. Add a top-level `env` block to `~/.claude/settings.json` — Claude Code passes it to every command it spawns, including the statusline:
+
+```json
+{
+  "env": {
+    "CTXLINE_DISABLE": "cost,task"
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "node ~/.claude/hooks/statusline.js"
+  }
+}
+```
+
+Restart Claude Code (or start a new session) to apply.
+
+### Option B — shell environment
+
+Set the variable **before** launching `claude` (the statusline inherits Claude Code's environment):
+
+```bash
+# macOS / Linux
+export CTXLINE_DISABLE="cost,task"
+claude
+```
+
+```powershell
+# Windows (PowerShell) — this terminal only
+$env:CTXLINE_DISABLE = "cost,task"; claude
+
+# Windows — persist for future sessions (then open a NEW terminal)
+setx CTXLINE_DISABLE "cost,task"
+```
+
+To re-enable a segment, remove it from the list (or delete the variable) and restart Claude Code.
+
 ## How it works
 
 - **Source** — context comes from Claude Code's session data. Usage bars are read straight from the `rate_limits` field Claude Code pipes in (no network), falling back to `https://api.anthropic.com/api/oauth/usage` (the same `/usage` data — 5-hour and weekly limits) when that field isn't present yet. API-key users skip usage entirely.
@@ -122,6 +189,20 @@ Remove-Item "$env:USERPROFILE\.claude\cache\usage-cache.json" -ErrorAction Silen
 
 ## FAQ
 
+<details>
+<summary>Does it use extra tokens?</summary>
+
+No — zero tokens, ever. The statusline is part of Claude Code's UI; its output is drawn in your terminal and is **never sent to the model**. Nothing it shows (context, usage, cost, git status) enters the conversation or counts toward your context window.
+
+</details>
+
+<details>
+<summary>Does fetching data slow down Claude Code?</summary>
+
+No, it's imperceptible. Almost every render reads a small local cache (sub-millisecond) instead of fetching. The usage API only runs as a fallback (and is cached); the git ahead/behind check runs at most once every ~5s and is hard-capped so it can never hang. The statusline runs as its own background command, so it never blocks your typing or Claude's responses — and in a non-git folder the git check doesn't run at all.
+
+</details>
+
 <details>
 <summary>Does this use the same data as /usage?</summary>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctxline-claude",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "A customizable statusline for Claude Code that tracks context usage and session limits",
   "bin": {
     "ctxline-claude": "bin/install.js"

package/statusline.js

@@ -8,10 +8,21 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const https = require('https');
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
 
 const IS_API_KEY = !!process.env.ANTHROPIC_API_KEY;
 
+// Optional segment opt-out: CTXLINE_DISABLE is a comma list of segments to hide.
+// Recognized: branch, effort, cost, task, usage (H+W). dir/model/context always render.
+// Unknown names are ignored. Disabling a segment also skips its work (git, todo read,
+// usage fetch).
+const DISABLED = new Set(
+  (process.env.CTXLINE_DISABLE || '')
+    .split(',')
+    .map(s => s.trim().toLowerCase())
+    .filter(Boolean)
+);
+
 // Shared width (cells) for all progress bars: context, current, weekly.
 const BAR_WIDTH = 6;
 
@@ -36,6 +47,13 @@ const FRESH_TTL_MS = 30000;            // 30 seconds
 // visible through transient timeouts/errors instead of disappearing.
 const STALE_TTL_MS = 10 * 60 * 1000;   // 10 minutes
 
+// Git ahead/behind cache (single repo entry, keyed by git dir). Throttles the one
+// `git rev-list` subprocess so a burst of renders in a turn runs it once, not per render.
+const GIT_CACHE_FILE = path.join(CACHE_DIR, 'git-cache.json');
+const GIT_FRESH_TTL_MS = 5000;          // 5s: reuse counts within a render burst
+const GIT_STALE_TTL_MS = 60000;         // 60s: fall back to last counts if git fails
+const GIT_TIMEOUT_MS = 500;             // hard cap on the rev-list subprocess (warm ~130ms)
+
 // ANSI color codes
 const colors = {
   reset: '\x1b[0m',
@@ -76,30 +94,35 @@ function truncateBranch(name) {
   return name.length > MAX_BRANCH_LEN ? name.slice(0, MAX_BRANCH_LEN - 1) + '…' : name;
 }
 
-// Resolve the current git branch by reading .git/HEAD directly (no `git` subprocess —
-// keeps the render fast and dependency-free). Walks up from `dir` to find the repo,
-// handles worktrees (.git as a file) and detached HEAD (short sha). Best-effort: '' on any failure.
+// Resolve the repo's git dir by walking up from `dir` (no `git` subprocess). Handles
+// worktrees/submodules (".git" as a file pointing at the real dir). '' on any failure.
+function resolveGitDir(dir) {
+  let cur = dir;
+  let gitPath = '';
+  for (let i = 0; i < 50 && cur; i++) {
+    const candidate = path.join(cur, '.git');
+    if (fs.existsSync(candidate)) { gitPath = candidate; break; }
+    const parent = path.dirname(cur);
+    if (parent === cur) break;          // reached filesystem root
+    cur = parent;
+  }
+  if (!gitPath) return '';
+
+  if (fs.statSync(gitPath).isFile()) {
+    // ".git" is a file like "gitdir: /path/to/.git/worktrees/x".
+    const m = fs.readFileSync(gitPath, 'utf8').match(/gitdir:\s*(.+)/);
+    if (!m) return '';
+    return path.resolve(path.dirname(gitPath), m[1].trim());
+  }
+  return gitPath;
+}
+
+// Current git branch, read straight from .git/HEAD (no `git` subprocess — fast,
+// dependency-free). Detached HEAD -> short sha. Best-effort: '' on any failure.
 function getGitBranch(dir) {
   try {
-    let cur = dir;
-    let gitPath = '';
-    for (let i = 0; i < 50 && cur; i++) {
-      const candidate = path.join(cur, '.git');
-      if (fs.existsSync(candidate)) { gitPath = candidate; break; }
-      const parent = path.dirname(cur);
-      if (parent === cur) break;        // reached filesystem root
-      cur = parent;
-    }
-    if (!gitPath) return '';
-
-    let gitDir = gitPath;
-    if (fs.statSync(gitPath).isFile()) {
-      // Worktree/submodule: ".git" is a file like "gitdir: /path/to/.git/worktrees/x".
-      const m = fs.readFileSync(gitPath, 'utf8').match(/gitdir:\s*(.+)/);
-      if (!m) return '';
-      gitDir = path.resolve(path.dirname(gitPath), m[1].trim());
-    }
-
+    const gitDir = resolveGitDir(dir);
+    if (!gitDir) return '';
     const head = fs.readFileSync(path.join(gitDir, 'HEAD'), 'utf8').trim();
     const ref = head.match(/^ref:\s*refs\/heads\/(.+)$/);
     if (ref) return truncateBranch(ref[1]);
@@ -110,6 +133,72 @@ function getGitBranch(dir) {
   }
 }
 
+// Read the cached ahead/behind for `gitDir`. Single-entry file: a different repo
+// invalidates it. Returns { age, ahead, behind } or null.
+function readGitCache(gitDir) {
+  try {
+    const c = JSON.parse(fs.readFileSync(GIT_CACHE_FILE, 'utf8'));
+    if (!c || c.gitDir !== gitDir || !Number.isFinite(c.timestamp)) return null;
+    if (!Number.isFinite(c.ahead) || !Number.isFinite(c.behind)) return null;
+    return { age: Date.now() - c.timestamp, ahead: c.ahead, behind: c.behind };
+  } catch (e) {
+    return null;
+  }
+}
+
+function writeGitCache(gitDir, ahead, behind) {
+  try {
+    if (!fs.existsSync(CACHE_DIR)) fs.mkdirSync(CACHE_DIR, { recursive: true });
+    fs.writeFileSync(GIT_CACHE_FILE, JSON.stringify({ gitDir, timestamp: Date.now(), ahead, behind }), 'utf8');
+  } catch (e) {}
+}
+
+// Commits ahead/behind the upstream (@{u}), cache-fronted. The single `git` call in the
+// whole script — gated by GIT_FRESH_TTL_MS so a render burst runs it once. No upstream /
+// detached / no git -> the subprocess errors -> null (segment omitted). On a slow/failed
+// call, falls back to the last counts up to GIT_STALE_TTL_MS so they don't flicker.
+function getGitAheadBehind(dir) {
+  const gitDir = resolveGitDir(dir);
+  if (!gitDir) return null;
+
+  const cached = readGitCache(gitDir);
+  if (cached && cached.age < GIT_FRESH_TTL_MS) {
+    return { ahead: cached.ahead, behind: cached.behind };
+  }
+
+  try {
+    // execFileSync (no shell): faster cold spawn than execSync and passes `@{u}` literally.
+    // `@{u}...HEAD` with --left-right --count prints "<behind>\t<ahead>" (left = upstream).
+    const out = execFileSync('git', ['rev-list', '--left-right', '--count', '@{u}...HEAD'], {
+      cwd: dir, encoding: 'utf8', timeout: GIT_TIMEOUT_MS, stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+    const parts = out.split(/\s+/);
+    const behind = parseInt(parts[0], 10);
+    const ahead = parseInt(parts[1], 10);
+    if (Number.isFinite(ahead) && Number.isFinite(behind)) {
+      writeGitCache(gitDir, ahead, behind);
+      return { ahead, behind };
+    }
+    return null;
+  } catch (e) {
+    if (cached && cached.age < GIT_STALE_TTL_MS) {
+      return { ahead: cached.ahead, behind: cached.behind };
+    }
+    return null;
+  }
+}
+
+// "↑N↓M" from ahead/behind counts: ahead green (commits to push), behind red (missing
+// commits). Each part self-resets so it doesn't inherit the dim branch color. Omit a zero
+// side; '' when in sync or null.
+function formatAheadBehind(ab) {
+  if (!ab) return '';
+  let s = '';
+  if (ab.ahead) s += `${colors.green}↑${ab.ahead}${colors.reset}`;
+  if (ab.behind) s += `${colors.red}↓${ab.behind}${colors.reset}`;
+  return s;
+}
+
 function getContextBar(remaining) {
   const effectiveRemaining = remaining ?? 100;
   const used = Math.max(0, Math.min(100, 100 - Math.round(effectiveRemaining)));
@@ -425,18 +514,21 @@ function outputStatus(data, usage) {
     const model = shortenModel(data?.model?.display_name || 'Claude');
     const dir = data?.workspace?.current_dir || process.cwd();
     const dirname = path.basename(dir);
-    const branch = getGitBranch(dir);
-    const effort = data?.effort?.level || '';
+    const branch = DISABLED.has('branch') ? '' : getGitBranch(dir);
+    const sync = branch ? formatAheadBehind(getGitAheadBehind(dir)) : '';
+    const effort = DISABLED.has('effort') ? '' : (data?.effort?.level || '');
     const sessionId = data?.session_id || '';
     const remaining = data?.context_window?.remaining_percentage;
 
     const contextBar = getContextBar(remaining);
-    const cost = getCostSegment(data);
-    const task = getCurrentTask(sessionId);
+    const cost = DISABLED.has('cost') ? '' : getCostSegment(data);
+    const task = DISABLED.has('task') ? '' : getCurrentTask(sessionId);
 
     // line1 = identity + context (always); line2 = usage/cost/task (wrap target).
     const line1 = [];
-    line1.push(branch ? `${dirname} ${colors.dim}⎇ ${branch}${colors.reset}` : dirname);
+    line1.push(branch
+      ? `${dirname} ${colors.dim}⎇ ${branch}${colors.reset}${sync ? ' ' + sync : ''}`
+      : dirname);
     line1.push(effort ? `${model}${getEffortColor(effort)} · ${effort}${colors.reset}` : model);
     line1.push(contextBar);
 
@@ -464,7 +556,7 @@ function outputFallback(usage) {
 // Order: API-key users get none; otherwise prefer stdin `rate_limits` (no network),
 // then fall back to the cache+API flow when stdin lacks it (cold start / non-Pro/Max).
 function resolveUsage(data, callback) {
-  if (IS_API_KEY) {
+  if (IS_API_KEY || DISABLED.has('usage')) {
     return callback(null);
   }
   const fromStdin = buildUsageFromStdin(data);