claudectx 1.1.0 → 1.1.1

package/README.md

@@ -28,6 +28,10 @@ A typical Claude Code session costs **$2–$15 in tokens**. Most of it is wasted
 | Full file reads for small questions | 70% overhead from unnecessary lines | `claudectx mcp` |
 | No prompt caching configured | Paying 10× for static context | `claudectx optimize --cache` |
 | No cross-session memory | Repeating the same context every session | `claudectx compress` |
+| Dead `@refs` and stale sections in CLAUDE.md | Silent token waste on every request | `claudectx drift` |
+| Unknown cost before running a big task | Surprise bills after the fact | `claudectx budget` |
+| Cache cold at session start | First request always a full miss | `claudectx warmup` |
+| No visibility into team-wide spend | Can't attribute cost across devs | `claudectx teams` |
 
 ### Where your tokens actually go
 
@@ -59,6 +63,23 @@ claudectx compress
 
 # Review your token spend for the last 7 days
 claudectx report
+
+# --- v1.1.0 additions ---
+
+# Know the cost before you start a task
+claudectx budget "src/**/*.ts" "tests/**/*.ts"
+
+# Pre-warm your prompt cache so the first request is free
+claudectx warmup --api-key $ANTHROPIC_API_KEY
+
+# Find dead references and stale sections in CLAUDE.md
+claudectx drift
+
+# Convert CLAUDE.md to Cursor / Copilot / Windsurf format
+claudectx convert --to cursor
+
+# Export your usage data for team-wide cost attribution
+claudectx teams export
 ```
 
 ## Installation
@@ -229,6 +250,116 @@ DAILY USAGE
 
 ---
 
+### `claudectx budget` — Know the cost before you start
+
+Before running a big task, see exactly which files will be read, how many tokens they'll consume, and what it'll cost.
+
+```bash
+claudectx budget "src/**/*.ts"                        # Estimate all TypeScript files
+claudectx budget "**/*.py" --threshold 20000          # Warn if total exceeds 20K tokens
+claudectx budget "src/**" --model opus --json         # JSON output for scripting
+```
+
+Output shows per-file token counts, cache hit likelihood (based on your recent reads), total cost estimate, and `.claudeignore` recommendations for files that are large but rarely useful.
+
+---
+
+### `claudectx warmup` — Pre-warm the prompt cache
+
+Start each session with a cache hit instead of a full miss. Sends a silent priming request to Anthropic so your CLAUDE.md is cached before Claude Code touches it.
+
+```bash
+claudectx warmup --api-key $ANTHROPIC_API_KEY         # 5-min cache TTL (default)
+claudectx warmup --ttl 60 --api-key $ANTHROPIC_API_KEY  # 60-min extended TTL
+claudectx warmup --cron "0 9 * * 1-5" --api-key ...  # Install as daily cron job
+claudectx warmup --json                               # Output result as JSON
+```
+
+Reports tokens warmed, write cost, savings per cache hit, and break-even request count.
+
+---
+
+### `claudectx drift` — CLAUDE.md stays fresh, not stale
+
+Over time CLAUDE.md accumulates dead references and sections nobody reads. `drift` finds them.
+
+```bash
+claudectx drift                      # Scan current project
+claudectx drift --days 14            # Use 14-day read window (default: 30)
+claudectx drift --fix                # Interactively remove flagged lines
+claudectx drift --json               # JSON output
+```
+
+Detects 4 types of drift:
+
+| Type | Example |
+|---|---|
+| **Dead `@ref`** | `@src/old-service.ts` — file deleted |
+| **Git-deleted mention** | `legacy-auth.py` appears in prose but was removed in git |
+| **Stale section** | `## Android Setup` — zero reads in 30 days |
+| **Dead inline path** | `src/utils/helper.py` mentioned in text, no longer exists |
+
+---
+
+### `claudectx hooks` — Hook marketplace
+
+Install named, pre-configured hooks beyond the basic read logger.
+
+```bash
+claudectx hooks list                                  # Show all available hooks
+claudectx hooks add auto-compress --config apiKey=sk-...  # Install a hook
+claudectx hooks remove slack-digest                   # Remove an installed hook
+claudectx hooks status                                # Show what's installed
+```
+
+**Built-in hooks:**
+
+| Hook | Trigger | What it does |
+|---|---|---|
+| `auto-compress` | PostToolUse (Read) | Runs `claudectx compress` after each session |
+| `daily-budget` | PreToolUse | Checks token budget before each tool call |
+| `slack-digest` | Stop | Posts session report to a Slack webhook |
+| `session-warmup` | PostToolUse (Read) | Re-warms the cache after each read |
+
+---
+
+### `claudectx convert` — Use your CLAUDE.md everywhere
+
+You wrote great instructions for Claude. Use them with Cursor, Copilot, or Windsurf too.
+
+```bash
+claudectx convert --to cursor         # → .cursor/rules/<section>.mdc (one per ## section)
+claudectx convert --to copilot        # → .github/copilot-instructions.md
+claudectx convert --to windsurf       # → .windsurfrules
+claudectx convert --to cursor --dry-run  # Preview without writing
+```
+
+Each `##` section in CLAUDE.md becomes a separate Cursor `.mdc` file with `alwaysApply: true` frontmatter. `@file` references are stripped for assistants that don't support them.
+
+---
+
+### `claudectx teams` — Multi-developer cost attribution
+
+See where the money goes across your whole team — without sharing session content.
+
+```bash
+# Step 1: each developer runs this on their own machine
+claudectx teams export
+
+# Step 2: collect the JSON files in a shared directory, then aggregate
+claudectx teams aggregate --dir ./reports/
+
+# Optional: copy your export to a shared location
+claudectx teams share --to /shared/reports/
+
+# Anonymize for review
+claudectx teams aggregate --dir ./reports/ --anonymize
+```
+
+Output shows per-developer spend, cache hit rate, avg request size, and top shared files. Exports are lightweight JSON — no session content, no prompts, just aggregated token counts.
+
+---
+
 ## How it all fits together
 
 ```
@@ -261,7 +392,7 @@ git clone https://github.com/Horilla/claudectx.git
 cd claudectx
 npm install
 npm run build
-npm test          # 199 tests, should all pass
+npm test          # 278 tests, should all pass
 npm run lint      # 0 errors expected
 ```
 

package/dist/index.js

@@ -2243,12 +2243,12 @@ async function handleLogStdin() {
   }
 }
 function readStdin() {
-  return new Promise((resolve11) => {
+  return new Promise((resolve12) => {
     let data = "";
     process.stdin.setEncoding("utf-8");
     process.stdin.on("data", (chunk) => data += chunk);
-    process.stdin.on("end", () => resolve11(data));
-    setTimeout(() => resolve11(data), 500);
+    process.stdin.on("end", () => resolve12(data));
+    setTimeout(() => resolve12(data), 500);
   });
 }
 
@@ -3241,29 +3241,65 @@ async function executeWarmup(claudeMdContent, model, ttl, client) {
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-async function installCron(cronExpr, apiKey) {
+function isValidCronExpr(expr) {
+  const parts = expr.trim().split(/\s+/);
+  if (parts.length < 5 || parts.length > 6) return false;
+  return parts.every((p) => /^[0-9*,/\-]+$/.test(p));
+}
+async function installCron(cronExpr) {
+  if (!isValidCronExpr(cronExpr)) {
+    process.stderr.write(
+      `Error: invalid cron expression "${cronExpr}".
+  Example: "0 9 * * 1-5" (weekdays at 9am)
+`
+    );
+    process.exit(1);
+  }
   const { execSync: execSync3 } = await import("child_process");
-  const command = `claudectx warmup --api-key ${apiKey}`;
+  const command = `claudectx warmup`;
   const cronLine = `${cronExpr} ${command}`;
+  const marker = "# claudectx warmup";
   try {
     let existing = "";
     try {
-      existing = execSync3("crontab -l 2>/dev/null", { encoding: "utf-8" });
+      existing = execSync3("crontab -l", {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"]
+      });
     } catch {
       existing = "";
     }
-    if (existing.includes("claudectx warmup")) {
-      process.stdout.write("Cron job already installed for claudectx warmup.\n");
+    if (existing.includes(marker)) {
+      process.stdout.write("  Cron job already installed for claudectx warmup.\n");
       return;
     }
-    const newCrontab = existing.trimEnd() + "\n" + cronLine + "\n";
-    execSync3(`echo ${JSON.stringify(newCrontab)} | crontab -`);
-    process.stdout.write(`\u2713 Cron job installed: ${cronLine}
+    const newCrontab = existing.trimEnd() + `
+${marker}
+${cronLine}
+`;
+    const { writeFileSync: writeFileSync11, unlinkSync: unlinkSync2 } = await import("fs");
+    const { tmpdir } = await import("os");
+    const { join: join17 } = await import("path");
+    const tmpFile = join17(tmpdir(), `claudectx-cron-${Date.now()}.txt`);
+    try {
+      writeFileSync11(tmpFile, newCrontab, "utf-8");
+      execSync3(`crontab ${tmpFile}`, { stdio: ["pipe", "pipe", "pipe"] });
+    } finally {
+      try {
+        unlinkSync2(tmpFile);
+      } catch {
+      }
+    }
+    process.stdout.write(`  \u2713 Cron job installed: ${cronLine}
 `);
+    process.stdout.write("  Note: Set ANTHROPIC_API_KEY in your cron environment (e.g. via ~/.profile).\n");
   } catch {
-    process.stdout.write(`Could not install cron automatically. Add manually:
+    process.stdout.write(
+      `  Could not install cron automatically. Add this line manually with "crontab -e":
+  ANTHROPIC_API_KEY=<your-key>
   ${cronLine}
-`);
+`
+    );
   }
 }
 async function warmupCommand(options) {
@@ -3333,7 +3369,7 @@ async function warmupCommand(options) {
   }
   process.stdout.write("\n");
   if (options.cron) {
-    await installCron(options.cron, apiKey);
+    await installCron(options.cron);
   }
 }
 
@@ -3392,15 +3428,15 @@ async function findGitDeletedMentions(content, projectRoot) {
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
     for (const deleted of deletedFiles) {
-      const basename7 = path22.basename(deleted);
-      if (line.includes(basename7) || line.includes(deleted)) {
+      const basename8 = path22.basename(deleted);
+      if (line.includes(basename8) || line.includes(deleted)) {
         issues.push({
           type: "git-deleted",
           line: i + 1,
           text: line.trim(),
           severity: "warning",
           estimatedTokenWaste: countTokens(line),
-          suggestion: `References "${basename7}" which was deleted from git. Consider removing this mention.`
+          suggestion: `References "${basename8}" which was deleted from git. Consider removing this mention.`
         });
         break;
       }
@@ -3607,11 +3643,34 @@ async function applyFix(claudeMdPath, issues) {
   const lines = content.split("\n");
   const lineSet = new Set(selectedLines.map((l) => l - 1));
   const newLines = lines.filter((_, i) => !lineSet.has(i));
-  fs20.writeFileSync(claudeMdPath, newLines.join("\n"), "utf-8");
+  const newContent = newLines.join("\n");
+  const backupPath = `${claudeMdPath}.bak`;
+  fs20.writeFileSync(backupPath, content, "utf-8");
+  const os5 = await import("os");
+  const tmpPath = `${claudeMdPath}.tmp-${Date.now()}`;
+  try {
+    fs20.writeFileSync(tmpPath, newContent, "utf-8");
+    fs20.renameSync(tmpPath, claudeMdPath);
+  } catch (err) {
+    try {
+      fs20.copyFileSync(backupPath, claudeMdPath);
+    } catch {
+    }
+    try {
+      fs20.unlinkSync(tmpPath);
+    } catch {
+    }
+    process.stderr.write(`Error writing CLAUDE.md: ${err instanceof Error ? err.message : String(err)}
+`);
+    process.exit(1);
+  }
   process.stdout.write(`
-  \u2713 Removed ${selectedLines.length} line(s) from ${claudeMdPath}
+  \u2713 Removed ${selectedLines.length} line(s) from ${path23.basename(claudeMdPath)}
+`);
+  process.stdout.write(`  \u2713 Backup saved to ${backupPath}
 
 `);
+  void os5;
 }
 
 // src/commands/hooks.ts
@@ -3627,10 +3686,10 @@ var HOOK_REGISTRY = [
     description: "Compress session when token count exceeds threshold",
     triggerEvent: "PostToolUse",
     matcher: "Read",
-    commandTemplate: "claudectx compress --auto --api-key {{config.apiKey}}",
+    // API key is read from ANTHROPIC_API_KEY env var — never stored in settings.json
+    commandTemplate: "claudectx compress --auto",
     configSchema: {
-      threshold: { type: "number", default: 5e4, description: "Token threshold to trigger compression" },
-      apiKey: { type: "string", description: "Anthropic API key for AI summarization", required: true }
+      threshold: { type: "number", default: 5e4, description: "Token threshold to trigger compression" }
     },
     category: "compression"
   },
@@ -3663,10 +3722,9 @@ var HOOK_REGISTRY = [
     description: "Pre-warm the Anthropic prompt cache on each session start",
     triggerEvent: "PostToolUse",
     matcher: "Read",
-    commandTemplate: "claudectx warmup --api-key {{config.apiKey}}",
-    configSchema: {
-      apiKey: { type: "string", description: "Anthropic API key", required: true }
-    },
+    // API key is read from ANTHROPIC_API_KEY env var — never stored in settings.json
+    commandTemplate: "claudectx warmup",
+    configSchema: {},
     category: "warmup"
   }
 ];
@@ -3695,9 +3753,18 @@ function buildHookEntry(def, config) {
 // src/commands/hooks.ts
 function readInstalledHooks(projectRoot) {
   const settingsPath = path24.join(projectRoot, ".claude", "settings.local.json");
+  if (!fs21.existsSync(settingsPath)) return {};
   try {
     return JSON.parse(fs21.readFileSync(settingsPath, "utf-8"));
   } catch {
+    process.stderr.write(
+      `Warning: ${settingsPath} exists but contains invalid JSON. Existing settings will be preserved as a backup.
+`
+    );
+    try {
+      fs21.copyFileSync(settingsPath, `${settingsPath}.bak`);
+    } catch {
+    }
     return {};
   }
 }
@@ -3784,6 +3851,16 @@ async function hooksAdd(name, projectRoot, configPairs) {
 `);
     process.exit(1);
   }
+  const sensitiveKeys = Object.keys(config).filter(
+    (k) => /key|token|secret|password|webhook/i.test(k)
+  );
+  if (sensitiveKeys.length > 0) {
+    process.stderr.write(
+      `Warning: config field(s) [${sensitiveKeys.join(", ")}] will be stored in plain text in
+  .claude/settings.local.json \u2014 ensure this file is in your .gitignore.
+`
+    );
+  }
   const entry = { ...buildHookEntry(def, config), name };
   const settings = readInstalledHooks(projectRoot);
   const hooksObj = settings.hooks ?? {};
@@ -3948,7 +4025,9 @@ Converting CLAUDE.md \u2192 ${files.length} Cursor rule file(s)
 `);
     for (const file of files) {
       const filePath = path25.join(targetDir, file.filename);
-      process.stdout.write(`  ${options.dryRun ? "[dry-run] " : ""}\u2192 .cursor/rules/${file.filename}
+      const exists = fs22.existsSync(filePath);
+      const prefix = options.dryRun ? "[dry-run] " : exists ? "[overwrite] " : "";
+      process.stdout.write(`  ${prefix}\u2192 .cursor/rules/${file.filename}
 `);
       if (!options.dryRun) {
         fs22.mkdirSync(targetDir, { recursive: true });
@@ -3959,8 +4038,9 @@ Converting CLAUDE.md \u2192 ${files.length} Cursor rule file(s)
   } else if (to === "copilot") {
     const converted = claudeMdToCopilot(content);
     const targetPath = path25.join(projectRoot, ".github", "copilot-instructions.md");
+    const exists = fs22.existsSync(targetPath);
     process.stdout.write(`
-Converting CLAUDE.md \u2192 .github/copilot-instructions.md
+Converting CLAUDE.md \u2192 .github/copilot-instructions.md${exists ? " [overwrite]" : ""}
 `);
     if (!options.dryRun) {
       fs22.mkdirSync(path25.dirname(targetPath), { recursive: true });
@@ -3976,8 +4056,9 @@ Converting CLAUDE.md \u2192 .github/copilot-instructions.md
   } else if (to === "windsurf") {
     const converted = claudeMdToWindsurf(content);
     const targetPath = path25.join(projectRoot, ".windsurfrules");
+    const exists = fs22.existsSync(targetPath);
     process.stdout.write(`
-Converting CLAUDE.md \u2192 .windsurfrules
+Converting CLAUDE.md \u2192 .windsurfrules${exists ? " [overwrite]" : ""}
 `);
     if (!options.dryRun) {
       fs22.writeFileSync(targetPath, converted, "utf-8");
@@ -4251,7 +4332,26 @@ async function teamsShare(options) {
   }
   const latest = exportFiles[0];
   const src = path27.join(storeDir, latest);
-  const destPath = fs24.statSync(dest).isDirectory() ? path27.join(dest, latest) : dest;
+  let destPath;
+  try {
+    const stat = fs24.statSync(dest);
+    destPath = stat.isDirectory() ? path27.join(dest, latest) : dest;
+  } catch {
+    destPath = dest;
+  }
+  const destDir = path27.dirname(path27.resolve(destPath));
+  let resolvedDir;
+  try {
+    resolvedDir = fs24.realpathSync(destDir);
+  } catch {
+    resolvedDir = destDir;
+  }
+  const systemDirs = ["/etc", "/bin", "/sbin", "/usr", "/var", "/proc", "/sys"];
+  if (systemDirs.some((d) => resolvedDir === d || resolvedDir.startsWith(d + "/"))) {
+    process.stderr.write(`Error: destination path resolves to a system directory (${resolvedDir}). Aborting.
+`);
+    process.exit(1);
+  }
   fs24.copyFileSync(src, destPath);
   process.stdout.write(`  \u2713 Copied ${latest} \u2192 ${destPath}