totopo 3.4.0 → 3.5.0

package/README.md

@@ -189,6 +189,16 @@ Agents are self-aware — sandbox constraints, git remote block, and any active
 
 totopo keeps all three CLIs on their latest published versions, checking for updates automatically.
 
+#### Claude status line
+
+For convenience, every Claude session opens with a status line at the bottom of the terminal:
+
+```
+Opus 4.7 high · 174k / 1M (17%) · ▓░░░░░░░░░ (13% used, resets in 3 hr 35 min)
+```
+
+Model and reasoning effort, current context usage with token count colored by absolute size (green below 100k, yellow up to 500k, red beyond), and a 10-block gauge of the 5-hour rate-limit window with current usage and time-to-reset (subscriber accounts only). Ask Claude `/totopo-statusline` to customize or restore the default.
+
 ### Persistent Agent Memory
 
 Agent session data (conversation history, settings) is stored per workspace and survives container restarts and rebuilds.

package/dist/lib/agent-context.js

@@ -8,10 +8,9 @@
 //   Claude Code: https://docs.anthropic.com/en/docs/claude-code
 //   OpenCode:    https://github.com/opencode-ai/opencode
 //   Codex:       https://github.com/openai/codex
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { AGENTS_DIR, CONTAINER_HOME, GIT_MODE } from "./constants.js";
+import { AGENTS_DIR, CLAUDE_STATUSLINE_PATH, CONTAINER_HOME, GIT_MODE, PACKAGE_ROOT } from "./constants.js";
 export const AGENT_MOUNTS = [
     {
         agent: "claude",
@@ -75,13 +74,16 @@ export function buildAgentMountArgs(workspaceDir) {
     ];
 }
 // --- Template helpers --------------------------------------------------------------------------------------------------------------------
-const packageRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 function loadTemplate(name) {
-    return readFileSync(join(packageRoot, "templates", "context", `${name}.md`), "utf8").trimEnd();
+    return readFileSync(join(PACKAGE_ROOT, "templates", "context", `${name}.md`), "utf8").trimEnd();
 }
 function renderTemplate(template, vars) {
     return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? `{{${key}}}`);
 }
+function writeFileEnsuringDir(filePath, content) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content);
+}
 // --- Build agent context documents -------------------------------------------------------------------------------------------------------
 /**
  * Assembles the agent context markdown injected into each supported agent's config dir at session start.
@@ -111,6 +113,48 @@ export function buildAgentContextDocs(hasGit, shadowPatterns, gitMode = GIT_MODE
         codex: build("~/.codex/AGENTS.md"),
     };
 }
+// --- Claude settings.json bootstrap ------------------------------------------------------------------------------------------------------
+function readSettingsObject(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Missing file or malformed JSON: caller proceeds with an empty object.
+    }
+    return {};
+}
+// Sets ~/.claude/settings.json -> statusLine to the totopo default if no value is set.
+// Non-destructive: preserves other fields and never overwrites a user-set statusLine.
+export function ensureClaudeStatusLine(workspaceDir) {
+    const settingsPath = join(workspaceDir, AGENTS_DIR, "claude", "settings.json");
+    const settings = readSettingsObject(settingsPath);
+    if (settings.statusLine === undefined) {
+        settings.statusLine = { type: "command", command: CLAUDE_STATUSLINE_PATH };
+        writeFileEnsuringDir(settingsPath, `${JSON.stringify(settings, null, 2)}\n`);
+    }
+}
+// --- Claude skills injection -------------------------------------------------------------------------------------------------------------
+// Renders every templates/skills/<name>/SKILL.md into agents/claude/skills/<name>/SKILL.md. Drop a
+// new directory under templates/skills/ to ship a new skill - no other code changes needed.
+export function injectClaudeSkills(workspaceDir) {
+    const templatesSkillsDir = join(PACKAGE_ROOT, "templates", "skills");
+    if (!existsSync(templatesSkillsDir))
+        return;
+    const targetSkillsDir = join(workspaceDir, AGENTS_DIR, "claude", "skills");
+    const vars = { statusline_path: CLAUDE_STATUSLINE_PATH };
+    for (const entry of readdirSync(templatesSkillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const sourcePath = join(templatesSkillsDir, entry.name, "SKILL.md");
+        if (!existsSync(sourcePath))
+            continue;
+        const rendered = renderTemplate(readFileSync(sourcePath, "utf8"), vars);
+        writeFileEnsuringDir(join(targetSkillsDir, entry.name, "SKILL.md"), rendered);
+    }
+}
 // --- Inject agent context ----------------------------------------------------------------------------------------------------------------
 /**
  * Writes agent context markdown files into the workspace's agents/ directory.
@@ -123,7 +167,8 @@ export function injectAgentContext(workspaceDir, docs) {
         { path: join(a, "codex", "AGENTS.md"), content: docs.codex },
     ];
     for (const { path: filePath, content } of files) {
-        mkdirSync(dirname(filePath), { recursive: true });
-        writeFileSync(filePath, content);
+        writeFileEnsuringDir(filePath, content);
     }
+    ensureClaudeStatusLine(workspaceDir);
+    injectClaudeSkills(workspaceDir);
 }

package/dist/lib/constants.js

@@ -1,6 +1,11 @@
 // =========================================================================================================================================
 // src/lib/constants.ts - Canonical constants used across the totopo codebase
 // =========================================================================================================================================
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+// Resolve the package root (repo root in dev, npm package root when installed).
+// All compiled lib modules sit at dist/lib/*.js, so dirname x3 from this file lands at the package root.
+export const PACKAGE_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 // ~/.totopo/ structure
 export const TOTOPO_DIR = ".totopo";
 export const WORKSPACES_DIR = "workspaces";
@@ -22,6 +27,8 @@ export const CONTAINER_USER = "devuser";
 export const CONTAINER_HOME = `/home/${CONTAINER_USER}`;
 export const CONTAINER_WORKSPACE = "/workspace";
 export const CONTAINER_STARTUP = `${CONTAINER_HOME}/startup.mjs`;
+// Claude Code default status line script - baked into the image, referenced from ~/.claude/settings.json
+export const CLAUDE_STATUSLINE_PATH = "/usr/local/share/totopo/claude-statusline.sh";
 // Docker container/image naming
 export const CONTAINER_NAME_PREFIX = "totopo-";
 // Docker label keys
@@ -43,7 +50,11 @@ export const PROFILE = {
 import { GIT_MODE, GIT_WRAPPER_PATH, GIT_WRAPPER_SOURCE } from "../../templates/runtime-constants.mjs";
 export { GIT_MODE, GIT_WRAPPER_PATH, GIT_WRAPPER_SOURCE };
 export const GIT_MODES = Object.values(GIT_MODE);
-// Runtime env vars injected into every container via docker run -e
+// Runtime env vars injected into every container via docker run -e.
+// DISABLE_AUTOUPDATER suppresses Claude Code's in-process auto-updater, which always fails inside
+// the container (devuser can't write to the root-owned global npm prefix). totopo's startup script
+// already keeps Claude on the latest version - see templates/startup.mjs.
 export const RUNTIME_ENV = {
     CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY: "1",
+    DISABLE_AUTOUPDATER: "1",
 };

package/dist/lib/migrate-to-latest.js

@@ -22,12 +22,13 @@
 // All migrations are idempotent - each checks if needed and skips if not.
 // =========================================================================================================================================
 import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { confirm, isCancel, log, note } from "@clack/prompts";
 import { load as loadYaml } from "js-yaml";
-import { AGENTS_DIR, CONTAINER_STARTUP, GIT_MODE, GIT_WRAPPER_SOURCE, LOCK_FILE, PROFILE, SHADOWS_DIR, TOTOPO_DIR, TOTOPO_YAML, WORKSPACES_DIR, } from "./constants.js";
+import { AGENTS_DIR, CLAUDE_STATUSLINE_PATH, CONTAINER_STARTUP, GIT_MODE, GIT_WRAPPER_SOURCE, LOCK_FILE, PACKAGE_ROOT, PROFILE, SHADOWS_DIR, TOTOPO_DIR, TOTOPO_YAML, WORKSPACES_DIR, } from "./constants.js";
 import { safeRmSync } from "./safe-rm.js";
 import { buildDefaultTotopoYaml, readTotopoYaml, slugifyForWorkspaceId, validateWorkspaceId, writeTotopoYaml, } from "./totopo-yaml.js";
 import { findTotopoYamlDir, getWorkspacesBaseDir, initWorkspaceDir, LOCK_KEYS } from "./workspace-identity.js";
@@ -532,5 +533,20 @@ export function isImageStale(containerName) {
     });
     if (constantsCheck.status !== 0)
         return true;
+    // SHA-256 of the host claude-statusline.sh vs the file inside the container - any refinement to
+    // the shipped script triggers an automatic rebuild prompt on next session.
+    const hostScriptPath = join(PACKAGE_ROOT, "templates", "claude-statusline.sh");
+    if (existsSync(hostScriptPath)) {
+        const expectedHash = createHash("sha256").update(readFileSync(hostScriptPath)).digest("hex");
+        const sumResult = spawnSync("docker", ["exec", containerName, "sha256sum", CLAUDE_STATUSLINE_PATH], {
+            encoding: "utf8",
+            stdio: "pipe",
+        });
+        if (sumResult.status !== 0)
+            return true;
+        const actualHash = sumResult.stdout.trim().split(/\s+/)[0] ?? "";
+        if (actualHash !== expectedHash)
+            return true;
+    }
     return false;
 }

package/dist/lib/totopo-yaml.js

@@ -2,11 +2,10 @@
 // src/lib/totopo-yaml.ts - Read, write, and validate totopo.yaml
 // =========================================================================================================================================
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { basename, join } from "node:path";
 import AjvModule from "ajv";
 import { dump as dumpYaml, load as loadYaml } from "js-yaml";
-import { DEFAULT_SHADOW_PATHS, TOTOPO_YAML, WORKSPACE_ID_MAX, WORKSPACE_ID_MIN } from "./constants.js";
+import { DEFAULT_SHADOW_PATHS, PACKAGE_ROOT, TOTOPO_YAML, WORKSPACE_ID_MAX, WORKSPACE_ID_MIN } from "./constants.js";
 // --- Validation --------------------------------------------------------------------------------------------------------------------------
 // Must match the pattern, minLength, and maxLength in schema/totopo.schema.json
 const WORKSPACE_ID_PATTERN = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/;
@@ -29,8 +28,7 @@ export function slugifyForWorkspaceId(name) {
         .slice(0, WORKSPACE_ID_MAX) || "my-workspace");
 }
 // --- Schema validation -------------------------------------------------------------------------------------------------------------------
-const packageRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
-const schemaPath = join(packageRoot, "schema", "totopo.schema.json");
+const schemaPath = join(PACKAGE_ROOT, "schema", "totopo.schema.json");
 // ajv is a CJS module - under nodenext resolution the class is nested under .default
 const Ajv = AjvModule.default ?? AjvModule;
 let _validate = null;
@@ -77,7 +75,7 @@ export function readTotopoYaml(dir) {
 // --- Write -------------------------------------------------------------------------------------------------------------------------------
 // Every published version (rc or release) has a corresponding git tag created by pnpm rc / pnpm rc:promote.
 // We rely on that tag existing so these URLs resolve correctly for every installed version.
-const { version } = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+const { version } = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
 export const GITHUB_README_URL = `https://github.com/asafratzon/totopo/blob/v${version}/README.md`;
 // Inline comments injected before specific YAML keys (preceded by a blank line)
 const YAML_COMMENTS = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "totopo",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Run AI coding agents safely in your local codebase",
   "type": "module",
   "bin": {

package/templates/Dockerfile

@@ -105,6 +105,13 @@ RUN mkdir -p /usr/local/share/totopo
 COPY git-readonly-wrapper.mjs /usr/local/share/totopo/git-readonly
 RUN chmod +x /usr/local/share/totopo/git-readonly
 
+# ---------------------------------------------------------------------------
+# Layer 11 — Bake Claude default status line script
+# Referenced from ~/.claude/settings.json (statusLine.command) at session start.
+# ---------------------------------------------------------------------------
+COPY claude-statusline.sh /usr/local/share/totopo/claude-statusline.sh
+RUN chmod +x /usr/local/share/totopo/claude-statusline.sh
+
 WORKDIR /workspace
 
 # ---------------------------------------------------------------------------

package/templates/claude-statusline.sh

@@ -0,0 +1,172 @@
+#!/bin/sh
+# =============================================================================
+# Default Claude Code status line shipped by totopo.
+# Baked into the container image at /usr/local/share/totopo/claude-statusline.sh
+# Referenced from ~/.claude/settings.json -> statusLine.command
+#
+# Render pattern:
+#   <model> <effort> · <tokens>k / <ctx> (<pct>%) · <bar> (<rate>% used, resets in <hr> hr <min> min)
+#
+# Designed to degrade gracefully: every field uses jq's // fallback, and any field that goes
+# missing in a future Claude Code release is silently skipped rather than failing the script.
+#
+# To customize or revert, ask Claude: /totopo-statusline
+# =============================================================================
+
+# Single jq invocation for all fields, separated by newlines. Every path uses // fallbacks so a
+# missing or renamed field becomes an empty string, which downstream branches handle as "skip".
+# jq itself returns no output (empty parsed) on malformed input, which still produces a valid line.
+# Tokens floor-rounded; percentages rounded to integers so downstream shell uses them as-is.
+parsed=$(jq -r '
+    .model.display_name // "",
+    ((.context_window.used_percentage // 0) | round),
+    (((.context_window.current_usage.input_tokens // 0)
+      + (.context_window.current_usage.cache_creation_input_tokens // 0)
+      + (.context_window.current_usage.cache_read_input_tokens // 0)) | floor),
+    .effort.level // "",
+    (.rate_limits.five_hour.used_percentage | if . == null then "" else round end),
+    (.rate_limits.five_hour.resets_at // "")
+' 2>/dev/null)
+
+{
+  IFS= read -r model_full
+  IFS= read -r used_pct
+  IFS= read -r used_tokens
+  IFS= read -r effort
+  IFS= read -r rate_pct
+  IFS= read -r rate_resets_at
+} <<EOF
+$parsed
+EOF
+
+# Split "Opus 4.7 (1M context)" into model "Opus 4.7" + ctx_size "1M" via POSIX parameter expansion.
+ctx_size=""
+model_display="$model_full"
+case "$model_full" in
+  *"("*")"*)
+    inside=${model_full#*\(}
+    inside=${inside%%\)*}
+    ctx_size=${inside% context}
+    model_display=${model_full%% \(*}
+    ;;
+esac
+
+# Colors
+GREEN='\033[32m'
+YELLOW='\033[33m'
+RED='\033[31m'
+BLUE='\033[34m'
+GREY='\033[90m'
+RESET='\033[0m'
+
+# Normalize tokens & pct (may arrive empty when current_usage is null).
+[ -z "$used_tokens" ] && used_tokens=0
+[ -z "$used_pct" ] && used_pct=0
+
+# Token color by absolute count: <100k green, 100k-500k yellow, >500k red.
+if [ "$used_tokens" -lt 100000 ]; then
+  tokens_color="$GREEN"
+elif [ "$used_tokens" -le 500000 ]; then
+  tokens_color="$YELLOW"
+else
+  tokens_color="$RED"
+fi
+
+# Format tokens label + 10-char quota bar in a single awk pass. Each bar block = 10% of the window.
+# rate_pct arrives pre-rounded from jq (or empty string when the field is absent).
+awk_out=$(awk -v t="$used_tokens" -v r="$rate_pct" 'BEGIN {
+  if (t == 0) printf "0k\n";
+  else if (t >= 100000) printf "%dk\n", int(t/1000 + 0.5);
+  else printf "%.1fk\n", t/1000;
+
+  if (r != "") {
+    if (r > 100) r = 100;
+    if (r < 0) r = 0;
+    filled = int(r / 10);
+    bar = "";
+    for (i = 0; i < filled; i++) bar = bar "▓";
+    for (i = filled; i < 10; i++) bar = bar "░";
+    printf "%s\n", bar;
+  } else {
+    printf "\n";
+  }
+}')
+
+{
+  IFS= read -r tokens_label
+  IFS= read -r bar
+} <<EOF
+$awk_out
+EOF
+
+# Bar color by rate-limit usage: <50% green, <80% yellow, >=80% red.
+bar_color="$GREEN"
+if [ -n "$rate_pct" ]; then
+  if [ "$rate_pct" -lt 50 ]; then
+    bar_color="$GREEN"
+  elif [ "$rate_pct" -lt 80 ]; then
+    bar_color="$YELLOW"
+  else
+    bar_color="$RED"
+  fi
+fi
+
+# Time until the rate-limit window resets, formatted as "X hr Y min" / "Y min" / "X day Y hr".
+# Skipped silently when resets_at is missing or non-numeric (forward compat with future schemas).
+reset_label=""
+case "$rate_resets_at" in
+  '' | *[!0-9]*) ;;
+  *)
+    now=$(date +%s)
+    secs=$((rate_resets_at - now))
+    [ "$secs" -lt 60 ] && secs=60
+    total_min=$(((secs + 30) / 60))
+    if [ "$total_min" -lt 60 ]; then
+      reset_label="${total_min} min"
+    elif [ "$total_min" -lt 1440 ]; then
+      hr=$((total_min / 60))
+      min=$((total_min % 60))
+      if [ "$min" -eq 0 ]; then
+        reset_label="${hr} hr"
+      else
+        reset_label="${hr} hr ${min} min"
+      fi
+    else
+      day=$((total_min / 1440))
+      hr=$(((total_min % 1440) / 60))
+      if [ "$hr" -eq 0 ]; then
+        reset_label="${day} day"
+      else
+        reset_label="${day} day ${hr} hr"
+      fi
+    fi
+    ;;
+esac
+
+# Mid-dot separator between segments.
+SEP=" ${GREY}·${RESET} "
+
+# Model + effort
+out=""
+if [ -n "$model_display" ]; then
+  out="${BLUE}${model_display}${RESET}"
+  [ -n "$effort" ] && out="${out} ${GREY}${effort}${RESET}"
+fi
+
+# <tokens> [/ <ctx>] (<pct>%)
+ctx_seg="${tokens_color}${tokens_label}${RESET}"
+[ -n "$ctx_size" ] && ctx_seg="${ctx_seg} ${GREY}/ ${ctx_size}${RESET}"
+ctx_seg="${ctx_seg} ${GREY}(${used_pct}%)${RESET}"
+if [ -n "$out" ]; then
+  out="${out}${SEP}${ctx_seg}"
+else
+  out="${ctx_seg}"
+fi
+
+# <bar> (<rate>% used, resets in <hr> hr <min> min)  -- only when rate-limit data is present
+if [ -n "$bar" ] && [ -n "$reset_label" ]; then
+  quota_seg="${bar_color}${bar}${RESET} ${GREY}(${rate_pct}% used, resets in ${reset_label})${RESET}"
+  out="${out}${SEP}${quota_seg}"
+fi
+
+printf '%b\n' "$out"

package/templates/skills/totopo-statusline/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: totopo-statusline
+description: View, customize, or revert the Claude status line in a totopo container. Use when the user mentions the status line, asks what their token count or model display means, wants to change colors or thresholds, or wants to restore the totopo default.
+---
+
+# totopo-statusline: Manage the Claude status line
+
+This skill helps the user inspect, customize, or revert the Claude Code status line shipped with totopo.
+
+**Important constants:**
+- The totopo default script is baked into the image at `{{statusline_path}}` (read-only, root-owned).
+- Claude reads its config from `~/.claude/settings.json` (`statusLine.command`).
+- After any change, the user must **restart Claude** for the new status line to take effect.
+
+## Step 1 - Inspect current state
+
+Read `~/.claude/settings.json` (treat a missing file or unparseable JSON as `{}`). Look at `.statusLine.command` and classify:
+
+- **default-by-omit** - `statusLine` field is absent. totopo will inject the default on the next session start, but it is not active in the running session yet.
+- **totopo-default** - `statusLine.command` equals `{{statusline_path}}`.
+- **custom** - `statusLine.command` is any other value.
+
+Tell the user which state they are in, and the exact command path if custom.
+
+## Step 2 - Explain the totopo default render pattern
+
+Three segments separated by a mid-dot. Example:
+
+```
+Opus 4.7 high · 174k / 1M (17%) · ▓░░░░░░░░░ (13% used, resets in 3 hr 35 min)
+```
+
+- Model name (blue) + reasoning effort (grey, hidden if unsupported).
+- Tokens used / context window size / percentage. Token count is colored: green below 100k, yellow up to 500k, red beyond.
+- 10-block gauge of the 5-hour rate-limit window (each block = 10%; green below 50%, yellow below 80%, red at or above 80%) followed by current usage and time until reset. Whole segment is hidden for free accounts and before the first API response.
+
+## Step 3 - Ask the user what they want
+
+Based on the current state:
+
+**If default-by-omit:**
+"Your status line will be the totopo default once the session restarts. Want to install it explicitly now, or customize before next session?"
+
+**If totopo-default:**
+"You are using the totopo default. Want to (1) keep it, (2) fork-and-edit a copy to tweak something, or (3) write a new one from scratch?"
+
+**If custom:**
+"You have a custom status line at `<command>`. Want to (1) keep it, (2) revert to the totopo default, or (3) modify further?"
+
+## Step 4 - Apply the chosen action
+
+### Install the default explicitly
+
+Edit `~/.claude/settings.json` so it contains:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "{{statusline_path}}"
+  }
+}
+```
+
+Preserve any other top-level fields the file already has. Tell the user to restart Claude.
+
+### Revert from custom to totopo default
+
+Same as install: set `statusLine.command` to `{{statusline_path}}`. Do not delete the user's custom script (it may be at a path like `~/.claude/statusline.sh`); just stop pointing at it. Mention to the user that the old script file is still on disk if they want to keep it for later.
+
+### Fork and edit (customize from the totopo default)
+
+Never edit `{{statusline_path}}` directly - it is root-owned and read-only inside the container.
+
+1. Copy the script to a writable location:
+   ```bash
+   cp {{statusline_path}} ~/.claude/statusline.sh
+   chmod +x ~/.claude/statusline.sh
+   ```
+2. Ask the user what they want to change (colors, thresholds, segment order, what to show, what to hide).
+3. Edit `~/.claude/statusline.sh` per their request.
+4. Update `~/.claude/settings.json` so `statusLine.command` points to `~/.claude/statusline.sh`.
+5. Tell the user to restart Claude.
+
+### Write from scratch
+
+If the user wants something completely different:
+
+1. Confirm the spec with them - what segments, what colors, what data sources from the input JSON Claude pipes to the script.
+2. Write a new script to `~/.claude/statusline-<descriptive-name>.sh`, `chmod +x` it.
+3. Update `~/.claude/settings.json` to point at it.
+4. Tell the user to restart Claude.
+
+## Notes
+
+- Always preserve other fields in `settings.json` when editing. The file may contain unrelated user settings.
+- If `settings.json` does not exist or is unparseable, create it fresh as `{ "statusLine": { ... } }`.
+- The format Claude Code passes via stdin includes `workspace.current_dir`, `model.display_name`, `context_window.used_percentage`, and `context_window.current_usage.{input_tokens, cache_creation_input_tokens, cache_read_input_tokens}`. Use these as the data sources for any custom script.