ctxdiet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Merlijn de Groot
+
+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,66 @@
+# ctxdiet
+
+[![npm version](https://img.shields.io/npm/v/ctxdiet.svg)](https://www.npmjs.com/package/ctxdiet)
+[![CI](https://github.com/Merlijnos/ctxdiet/actions/workflows/ci.yml/badge.svg)](https://github.com/Merlijnos/ctxdiet/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+
+Your AI coding agents reload the same context every session. ctxdiet finds the
+waste, fixes it with diffs you approve, and shows what you saved. Local, no account.
+
+```
+npx ctxdiet        # scan, read-only
+npx ctxdiet fix    # show diffs, confirm, apply, measure
+```
+
+## What one fix looks like
+
+```
+Before vs after
+┌────────────────────────┬────────┬───┬───────┬────────┐
+│                        │ Before │   │ After │  Saved │
+├────────────────────────┼────────┼───┼───────┼────────┤
+│ Context tokens/session │ 21,346 │ → │ 1,227 │ 20,119 │
+│ $/month                │  $6.40 │ → │ $0.37 │  $6.04 │
+│ Grade                  │     F  │ → │    A  │        │
+└────────────────────────┴────────┴───┴───────┴────────┘
+```
+
+Real run on a repo using Claude Code + Cursor: trimmed duplicate memory lines,
+created `.claudeignore` and `.cursorignore`, archived dead `~/.claude` files.
+
+## Agents
+
+Auto-detected; only the ones you use are scanned.
+
+| Agent          | Memory                                  | Ignore           |
+| -------------- | --------------------------------------- | ---------------- |
+| Claude Code    | `CLAUDE.md`, `~/.claude/CLAUDE.md`      | `.claudeignore`  |
+| Codex          | `AGENTS.md`                             | —                |
+| Cursor         | `.cursorrules`, `.cursor/rules/*.mdc`   | `.cursorignore`  |
+| Gemini CLI     | `GEMINI.md`                             | `.geminiignore`  |
+| Windsurf       | `.windsurfrules`                        | `.codeiumignore` |
+| GitHub Copilot | `.github/copilot-instructions.md`       | —                |
+
+## What it does
+
+- **Finds:** duplicate memory lines, missing ignore files, MCP tool schemas, and
+  dead `~/.claude` files (empty, `.bak`, broken skills).
+- **Fixes** each with a diff you confirm. Never deletes (archives instead), always
+  writes a `.bak`, and `--yes` only touches provably-dead waste.
+- **Leaves alone** anything whose usage it can't verify (MCP servers, real skills).
+  It doesn't read your history, so those are listed for review, never auto-removed.
+
+Token numbers are a `chars / 4` estimate, not a tokenizer — close enough to rank waste.
+
+## Flags
+
+```
+--path <dir>                directory to scan (default: current)
+--model <opus|sonnet|haiku> pricing for the $ estimate (default: sonnet)
+--sessions-per-month <n>    default 100
+--dry-run                   show diffs, write nothing
+--yes                       apply without prompting
+--json                      machine-readable output
+```
+
+Node 20+. MIT. Sponsor: https://github.com/sponsors/Merlijnos

package/dist/src/agents.js

@@ -0,0 +1,81 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENTS = void 0;
+exports.detectAgents = detectAgents;
+const node_path_1 = __importDefault(require("node:path"));
+const sources_1 = require("./sources");
+const P = (o, ...parts) => node_path_1.default.join(o.path, ...parts);
+const H = (o, ...parts) => node_path_1.default.join(o.home, ...parts);
+exports.AGENTS = [
+    {
+        id: "claude",
+        label: "Claude Code",
+        ownsDefinitions: true,
+        memoryFiles: (o) => (0, sources_1.uniq)([P(o, "CLAUDE.md"), P(o, ".claude", "CLAUDE.md"), H(o, ".claude", "CLAUDE.md")]),
+        ignoreFile: ".claudeignore",
+        mcpFiles: (o) => (0, sources_1.uniq)([
+            P(o, ".mcp.json"),
+            P(o, ".claude", "settings.json"),
+            H(o, ".claude.json"),
+            H(o, ".claude", "settings.json"),
+        ]),
+        detectSignals: (o) => [
+            P(o, "CLAUDE.md"),
+            P(o, ".claude"),
+            P(o, ".claudeignore"),
+            P(o, ".mcp.json"),
+            H(o, ".claude"),
+        ],
+    },
+    {
+        id: "codex",
+        label: "Codex / AGENTS.md",
+        memoryFiles: (o) => (0, sources_1.uniq)([P(o, "AGENTS.md"), H(o, ".codex", "AGENTS.md")]),
+        mcpFiles: () => [],
+        detectSignals: (o) => [P(o, "AGENTS.md"), H(o, ".codex")],
+    },
+    {
+        id: "cursor",
+        label: "Cursor",
+        memoryFiles: (o) => (0, sources_1.uniq)([P(o, ".cursorrules"), ...(0, sources_1.walkFiles)(P(o, ".cursor", "rules"), [".mdc", ".md"])]),
+        ignoreFile: ".cursorignore",
+        mcpFiles: (o) => (0, sources_1.uniq)([P(o, ".cursor", "mcp.json"), H(o, ".cursor", "mcp.json")]),
+        detectSignals: (o) => [P(o, ".cursorrules"), P(o, ".cursor"), P(o, ".cursorignore")],
+    },
+    {
+        id: "gemini",
+        label: "Gemini CLI",
+        memoryFiles: (o) => (0, sources_1.uniq)([P(o, "GEMINI.md"), H(o, ".gemini", "GEMINI.md")]),
+        ignoreFile: ".geminiignore",
+        mcpFiles: (o) => (0, sources_1.uniq)([H(o, ".gemini", "settings.json"), P(o, ".gemini", "settings.json")]),
+        detectSignals: (o) => [P(o, "GEMINI.md"), P(o, ".gemini"), H(o, ".gemini")],
+    },
+    {
+        id: "windsurf",
+        label: "Windsurf",
+        memoryFiles: (o) => (0, sources_1.uniq)([P(o, ".windsurfrules"), ...(0, sources_1.walkFiles)(P(o, ".windsurf", "rules"), [".md"])]),
+        ignoreFile: ".codeiumignore",
+        mcpFiles: () => [],
+        detectSignals: (o) => [P(o, ".windsurfrules"), P(o, ".windsurf")],
+    },
+    {
+        id: "copilot",
+        label: "GitHub Copilot",
+        memoryFiles: (o) => (0, sources_1.uniq)([
+            P(o, ".github", "copilot-instructions.md"),
+            ...(0, sources_1.walkFiles)(P(o, ".github", "instructions"), [".instructions.md", ".md"]),
+        ]),
+        mcpFiles: (o) => [P(o, ".vscode", "mcp.json")],
+        detectSignals: (o) => [
+            P(o, ".github", "copilot-instructions.md"),
+            P(o, ".github", "instructions"),
+        ],
+    },
+];
+/** Agents with at least one existing signal (project- or home-level). */
+function detectAgents(o) {
+    return exports.AGENTS.filter((a) => a.detectSignals(o).some((sig) => (0, sources_1.exists)(sig) && ((0, sources_1.isFile)(sig) || (0, sources_1.isDir)(sig))));
+}

package/dist/src/constants.js

@@ -0,0 +1,31 @@
+"use strict";
+// All numbers here are deliberate, documented heuristics — see README "How it
+// estimates tokens". ctxdiet never claims exactness.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LARGE_CLAUDEMD_TOKENS = exports.HEAVY_WALK_MAX_BYTES = exports.HEAVY_WALK_MAX_FILES = exports.HEAVY_PATH_TOKEN_CAP = exports.MCP_SERVER_TOKEN_EST = exports.CHARS_PER_TOKEN = void 0;
+exports.grade = grade;
+/** The one and only token heuristic: ~4 chars per token. */
+exports.CHARS_PER_TOKEN = 4;
+/** Rough average token cost of one MCP server's injected tool schemas. */
+exports.MCP_SERVER_TOKEN_EST = 550;
+/** A session reads only a fraction of a heavy dir; cap the per-path estimate. */
+exports.HEAVY_PATH_TOKEN_CAP = 5000;
+/** Bound the directory walk so scanning stays fast on huge trees. */
+exports.HEAVY_WALK_MAX_FILES = 2000;
+exports.HEAVY_WALK_MAX_BYTES = 8 * 1024 * 1024;
+/** A CLAUDE.md above this with no trimmable redundancy is flagged for manual review. */
+exports.LARGE_CLAUDEMD_TOKENS = 3000;
+/** Grade thresholds on HIGH-confidence waste tokens/session. */
+const GRADE_THRESHOLDS = [
+    [500, "A"],
+    [2000, "B"],
+    [5000, "C"],
+    [10000, "D"],
+];
+function grade(wasteTokens) {
+    for (const [limit, letter] of GRADE_THRESHOLDS) {
+        if (wasteTokens < limit)
+            return letter;
+    }
+    return "F";
+}

package/dist/src/fix.js

@@ -0,0 +1,270 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFix = runFix;
+const diff_1 = require("diff");
+const chalk_1 = __importDefault(require("chalk"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_readline_1 = __importDefault(require("node:readline"));
+const report_1 = require("./report");
+const scan_1 = require("./scan");
+const sources_1 = require("./sources");
+const trim_1 = require("./trim");
+/** Build the concrete change from fresh on-disk state (reflects prior edits). */
+function buildChange(action) {
+    switch (action.type) {
+        case "trim": {
+            const before = (0, sources_1.readFileSafe)(action.path);
+            const after = (0, trim_1.trimMarkdown)(before);
+            if (before === after)
+                return null;
+            return { kind: "write", path: action.path, before, after, isNew: false };
+        }
+        case "ignore-create": {
+            return {
+                kind: "write",
+                path: action.path,
+                before: "",
+                after: action.content,
+                isNew: true,
+            };
+        }
+        case "ignore-augment": {
+            const before = (0, sources_1.readFileSafe)(action.path);
+            const body = before.replace(/\n*$/, "\n");
+            const after = body + "\n# added by ctxdiet\n" + action.added.join("\n") + "\n";
+            return { kind: "write", path: action.path, before, after, isNew: false };
+        }
+        case "mcp-disable": {
+            const before = (0, sources_1.readFileSafe)(action.path);
+            const after = disableMcpServer(before, action.server);
+            if (after === null || after === before)
+                return null;
+            return { kind: "mcp", path: action.path, before, after, server: action.server };
+        }
+        case "archive": {
+            return { kind: "move", path: action.path, to: action.archiveTo };
+        }
+    }
+}
+function disableMcpServer(content, server) {
+    let json;
+    try {
+        json = JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+    const servers = json.mcpServers;
+    if (!servers || !(server in servers))
+        return null;
+    const disabled = json.mcpServers_disabledByCtxdiet ?? {};
+    disabled[server] = servers[server];
+    delete servers[server];
+    json.mcpServers_disabledByCtxdiet = disabled;
+    return JSON.stringify(json, null, 2) + "\n";
+}
+// ---------------------------------------------------------------------------
+// rendering + applying
+// ---------------------------------------------------------------------------
+function colorizeDiff(patch) {
+    return patch
+        .split("\n")
+        .map((line) => {
+        if (line.startsWith("+++") || line.startsWith("---"))
+            return chalk_1.default.dim(line);
+        if (line.startsWith("@@"))
+            return chalk_1.default.cyan(line);
+        if (line.startsWith("+"))
+            return chalk_1.default.green(line);
+        if (line.startsWith("-"))
+            return chalk_1.default.red(line);
+        return line;
+    })
+        .join("\n");
+}
+function printChange(change, o) {
+    const rel = (0, sources_1.displayPath)(change.path, o.path, o.home);
+    if (change.kind === "move") {
+        console.log("  " +
+            chalk_1.default.red("archive ") +
+            rel +
+            chalk_1.default.dim("  →  ") +
+            (0, sources_1.displayPath)(change.to, o.path, o.home));
+        return;
+    }
+    if (change.kind === "mcp") {
+        console.log("  " + chalk_1.default.bold(rel));
+        console.log("    " +
+            chalk_1.default.red(`- mcpServers.${change.server}`) +
+            chalk_1.default.dim("  (kept under ") +
+            chalk_1.default.green(`mcpServers_disabledByCtxdiet.${change.server}`) +
+            chalk_1.default.dim(", reversible — JSON is reserialized, .bak saved)"));
+        return;
+    }
+    const label = change.isNew ? `${rel} (new file)` : rel;
+    const patch = (0, diff_1.createTwoFilesPatch)(label, label, change.before, change.after, "", "", {
+        context: 2,
+    });
+    // Drop the noisy "Index:"/"===" header lines and trailing tabs the diff lib adds.
+    const cleaned = patch
+        .split("\n")
+        .filter((l) => !l.startsWith("Index: ") && !/^=+$/.test(l))
+        .map((l) => (l.startsWith("--- ") || l.startsWith("+++ ") ? l.replace(/\s+$/, "") : l))
+        .join("\n");
+    console.log(colorizeDiff(cleaned));
+}
+function backup(p) {
+    if (!node_fs_1.default.existsSync(p))
+        return;
+    let bak = p + ".bak";
+    if (node_fs_1.default.existsSync(bak))
+        bak = `${p}.bak.${Date.now()}`;
+    node_fs_1.default.copyFileSync(p, bak);
+}
+function applyChange(change) {
+    if (change.kind === "move") {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(change.to), { recursive: true });
+        try {
+            node_fs_1.default.renameSync(change.path, change.to);
+        }
+        catch {
+            // cross-device or dir move fallback: copy then remove.
+            node_fs_1.default.cpSync(change.path, change.to, { recursive: true });
+            node_fs_1.default.rmSync(change.path, { recursive: true, force: true });
+        }
+        return;
+    }
+    // write / mcp — back up any existing file before overwriting.
+    const isNewFile = change.kind === "write" && change.isNew;
+    if (!isNewFile && node_fs_1.default.existsSync(change.path))
+        backup(change.path);
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(change.path), { recursive: true });
+    node_fs_1.default.writeFileSync(change.path, change.after, "utf8");
+}
+// ---------------------------------------------------------------------------
+// prompt
+// ---------------------------------------------------------------------------
+function confirm(question) {
+    if (!process.stdin.isTTY)
+        return Promise.resolve(false);
+    const rl = node_readline_1.default.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(`${question} [y/N] `, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// runFix
+// ---------------------------------------------------------------------------
+async function runFix(o) {
+    const before = (0, scan_1.scan)(o);
+    const high = before.findings.filter((f) => f.confidence === "high" && f.fixable && f.action);
+    const low = before.findings.filter((f) => f.confidence === "low" && f.fixable && f.action);
+    if (high.length === 0 && low.length === 0) {
+        if (o.json) {
+            console.log(JSON.stringify({ message: "nothing to fix", before: (0, report_1.toJson)(before) }, null, 2));
+        }
+        else {
+            console.log(chalk_1.default.green("\nNothing to fix — your setup is already lean.\n"));
+        }
+        return;
+    }
+    let lowApplied = 0;
+    // ---- HIGH-confidence: normal [y/N] / --yes / --dry-run flow ----
+    if (high.length > 0 && !o.json) {
+        console.log(chalk_1.default.bold("\nHigh-confidence fixes\n"));
+    }
+    for (const f of high) {
+        const change = buildChange(f.action);
+        if (!change)
+            continue;
+        if (!o.json) {
+            console.log(chalk_1.default.bold(`• ${f.agent} · ${f.category} — ${f.title}`));
+            printChange(change, o);
+        }
+        const go = decideHigh(o, () => confirm("Apply this change?"));
+        await applyIf(go, change, o);
+    }
+    // ---- LOW-confidence: explicit interactive prompt only, never --yes ----
+    if (low.length > 0) {
+        if (o.yes) {
+            if (!o.json) {
+                console.log(chalk_1.default.yellow(`\nSkipped ${low.length} usage-unconfirmed item(s) (MCP servers / definitions). ` +
+                    `--yes never touches these — re-run \`ctxdiet fix\` without --yes to review them.`));
+            }
+        }
+        else if (o.json) {
+            // non-interactive: cannot prompt, leave for interactive review.
+        }
+        else {
+            console.log(chalk_1.default.yellow.bold("\nReview items — usage not confirmed\n"));
+            console.log(chalk_1.default.dim("ctxdiet can't see your history. Only disable what you know you don't use.\n"));
+            for (const f of low) {
+                const change = buildChange(f.action);
+                if (!change)
+                    continue;
+                console.log(chalk_1.default.bold(`• ${f.agent} · ${f.category} — ${f.title}`));
+                printChange(change, o);
+                const verb = f.action.type === "mcp-disable" ? "Disable" : "Archive";
+                const go = o.dryRun
+                    ? false
+                    : await confirm(`${verb} this? Only do this if you know it's unused.`);
+                if (go && !o.dryRun) {
+                    applyChange(change);
+                    lowApplied += f.tokensPerSession;
+                    console.log(chalk_1.default.green("  applied\n"));
+                }
+                else {
+                    console.log(chalk_1.default.dim("  skipped\n"));
+                }
+            }
+        }
+    }
+    // ---- measure ----
+    const after = (0, scan_1.scan)(o);
+    if (o.json) {
+        console.log(JSON.stringify({
+            dryRun: o.dryRun,
+            before: (0, report_1.toJson)(before),
+            after: (0, report_1.toJson)(after),
+            savedTokens: before.baselineTokens - after.baselineTokens,
+        }, null, 2));
+        return;
+    }
+    if (o.dryRun) {
+        console.log(chalk_1.default.yellow("\nDry run — no files were written."));
+    }
+    (0, report_1.printBeforeAfter)(before, after, o, lowApplied);
+}
+function decideHigh(o, ask) {
+    if (o.dryRun)
+        return Promise.resolve(false);
+    if (o.yes)
+        return Promise.resolve(true);
+    if (o.json)
+        return Promise.resolve(false); // json non-interactive
+    return ask();
+}
+async function applyIf(go, change, o) {
+    const ok = await go;
+    if (ok && !o.dryRun) {
+        applyChange(change);
+        if (!o.json)
+            console.log(chalk_1.default.green("  applied\n"));
+    }
+    else if (!o.json && !o.dryRun) {
+        console.log(chalk_1.default.dim("  skipped\n"));
+    }
+    else if (!o.json) {
+        console.log();
+    }
+}

package/dist/src/index.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const fix_1 = require("./fix");
+const report_1 = require("./report");
+const scan_1 = require("./scan");
+const sources_1 = require("./sources");
+function resolveOptions(raw, modelFromCli) {
+    const home = node_os_1.default.homedir();
+    let model;
+    let modelDetected = false;
+    if (modelFromCli) {
+        const m = (raw.model ?? "sonnet").toLowerCase();
+        if (m !== "opus" && m !== "sonnet" && m !== "haiku") {
+            console.error(`Invalid --model "${raw.model}". Use opus, sonnet, or haiku.`);
+            process.exit(1);
+        }
+        model = m;
+    }
+    else {
+        const detected = (0, sources_1.detectModel)(home);
+        model = detected ?? "sonnet";
+        modelDetected = detected !== null;
+    }
+    const parsed = Number.parseInt(raw.sessionsPerMonth ?? "100", 10);
+    const sessionsPerMonth = Number.isFinite(parsed) && parsed > 0 ? parsed : 100;
+    return {
+        path: node_path_1.default.resolve(raw.path ?? process.cwd()),
+        home,
+        sessionsPerMonth,
+        model,
+        modelDetected,
+        json: Boolean(raw.json),
+        dryRun: Boolean(raw.dryRun),
+        yes: Boolean(raw.yes),
+    };
+}
+function addCommonOptions(cmd) {
+    return cmd
+        .option("--path <dir>", "project directory to scan", process.cwd())
+        .option("--sessions-per-month <n>", "sessions/month for cost estimate", "100")
+        .option("--model <model>", "pricing model: opus|sonnet|haiku", "sonnet")
+        .option("--json", "machine-readable JSON output")
+        .option("--dry-run", "show changes but write nothing")
+        .option("--yes", "apply all high-confidence fixes without prompting");
+}
+const program = new commander_1.Command();
+program
+    .name("ctxdiet")
+    .description("Detect, fix, and measure AI agent context-token waste.")
+    .version("0.1.0");
+addCommonOptions(program);
+program.action(() => {
+    const fromCli = program.getOptionValueSource("model") === "cli";
+    const o = resolveOptions(program.opts(), fromCli);
+    (0, report_1.printScanResult)((0, scan_1.scan)(o), o);
+});
+const fix = program
+    .command("fix")
+    .description("Generate fixes, show diffs, apply on confirmation, then show before/after.");
+addCommonOptions(fix);
+fix.action(async () => {
+    const fromCli = fix.getOptionValueSource("model") === "cli" ||
+        program.getOptionValueSource("model") === "cli";
+    await (0, fix_1.runFix)(resolveOptions(fix.optsWithGlobals(), fromCli));
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/src/pricing.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRICE_PER_MTOK = void 0;
+exports.monthlyCost = monthlyCost;
+/** Input price in USD per million tokens. Estimates for cost projection only. */
+exports.PRICE_PER_MTOK = {
+    opus: 15,
+    sonnet: 3,
+    haiku: 0.8,
+};
+function monthlyCost(tokensPerSession, sessionsPerMonth, model) {
+    return (tokensPerSession * sessionsPerMonth) / 1_000_000 * exports.PRICE_PER_MTOK[model];
+}