contextpruner 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,57 +1,18 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { execFileSync } from "node:child_process";
-import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-
-// src/args.ts
-function parseArgs(argv) {
-  const [command, ...rest] = argv;
-  if (command === void 0 || command === "--help" || command === "-h") {
-    return { command: "help", configs: [], json: false, fix: false };
-  }
-  if (command === "--version" || command === "-v") {
-    return { command: "version", configs: [], json: false, fix: false };
-  }
-  if (command !== "lint") {
-    return {
-      command: "unknown",
-      configs: [],
-      json: false,
-      fix: false,
-      problem: `unknown command "${command}"`
-    };
-  }
-  const configs = [];
-  let json = false;
-  let fix = false;
-  for (let i = 0; i < rest.length; i++) {
-    const arg = rest[i];
-    if (arg === "--json") {
-      json = true;
-    } else if (arg === "--fix") {
-      fix = true;
-    } else if (arg === "--config") {
-      const value = rest[++i];
-      if (value === void 0) {
-        return { command: "lint", configs, json, fix, problem: "--config needs a path" };
-      }
-      configs.push(value);
-    } else if (arg === "--help" || arg === "-h") {
-      return { command: "help", configs: [], json: false, fix: false };
-    } else {
-      return {
-        command: "lint",
-        configs,
-        json,
-        fix,
-        problem: `unknown option "${arg}"`
-      };
-    }
-  }
-  return { command: "lint", configs, json, fix };
-}
+import { execFile, execFileSync } from "node:child_process";
+import {
+  chmodSync,
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync2,
+  statSync,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname as dirname2, join as join3 } from "node:path";
+import { createInterface } from "node:readline";
 
 // ../../lib/shared/constants.ts
 var BYTES_PER_TOKEN_RATIO = 0.25;
@@ -63,6 +24,8 @@ var CONTEXT_SLICE_FACTOR = 0.05;
 var DEFAULT_CONTEXT_WINDOW_TOKENS = 1e6;
 var MONTHLY_SAVINGS_CAP_USD = 200;
 var MAX_MANIFEST_FILES = 2e4;
+var MAX_OVERRIDE_DECLARATIONS = 200;
+var MAX_PATH_LENGTH = 1024;
 var OVERSIZED_FILE_BYTES = 1048576;
 
 // ../../lib/engine/rules.ts
@@ -280,6 +243,478 @@ function compileGlob(glob) {
   return (path) => re.test(path);
 }
 
+// ../../lib/engine/filter.ts
+function buildKeepMatcher(declarations) {
+  const predicates = [];
+  for (const declaration of declarations) {
+    if (declaration.length === 0) continue;
+    if (declaration.includes("*")) {
+      predicates.push(compileGlob(declaration));
+    } else {
+      predicates.push(compileGlob(`**/${declaration}`));
+      predicates.push(compileGlob(`**/${declaration}/**`));
+    }
+  }
+  if (predicates.length === 0) return () => false;
+  return (path) => predicates.some((match) => match(path));
+}
+function filterPaths(paths, options = {}) {
+  if (options.pointed) {
+    const kept2 = [...paths];
+    return {
+      kept: kept2,
+      pruned: [],
+      shown: kept2.length,
+      total: paths.length,
+      prunedCount: 0
+    };
+  }
+  const isKept = buildKeepMatcher(options.keep ?? []);
+  const { sizeOf } = options;
+  const kept = [];
+  const pruned = [];
+  for (const path of paths) {
+    if (isKept(path)) {
+      kept.push(path);
+      continue;
+    }
+    const sizeInBytes = sizeOf ? sizeOf(path) || 0 : 0;
+    if (classify({ path, sizeInBytes }).verdict === "PRUNE") {
+      pruned.push(path);
+    } else {
+      kept.push(path);
+    }
+  }
+  return {
+    kept,
+    pruned,
+    shown: kept.length,
+    total: paths.length,
+    prunedCount: pruned.length
+  };
+}
+
+// ../../lib/engine/filterStream.ts
+var ENCODER = new TextEncoder();
+var byteLength = (text) => ENCODER.encode(text).length;
+function pathOfLine(line, format) {
+  if (format === "paths") {
+    const path2 = line.trim();
+    return path2 === "" ? null : path2;
+  }
+  const colon = line.indexOf(":");
+  const path = colon === -1 ? line.trim() : line.slice(0, colon);
+  return path === "" ? null : path;
+}
+var DEFAULT_BYPASS_HINT = "set CONTEXTPRUNER_ALL=1 to see them";
+function footer(shown, total, pruned, bypassHint) {
+  return `showing ${shown} of ${total} matches; ${pruned} pruned as junk \u2014 ${bypassHint}`;
+}
+function filterSearchOutput(raw, options) {
+  const lines = raw.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  const uniquePathsOf = (ls) => [
+    ...new Set(
+      ls.map((line) => pathOfLine(line, options.format)).filter((path) => path !== null)
+    )
+  ];
+  if (options.all) {
+    const bytesTotal2 = lines.reduce((sum, line) => sum + byteLength(line), 0);
+    return {
+      output: raw,
+      shown: lines.length,
+      total: lines.length,
+      pruned: 0,
+      bytesTotal: bytesTotal2,
+      bytesPruned: 0,
+      pathsConsidered: uniquePathsOf(lines).length
+    };
+  }
+  const uniquePaths = uniquePathsOf(lines);
+  const { pruned: prunedPaths } = filterPaths(uniquePaths, options);
+  const isPruned = new Set(prunedPaths);
+  const keptLines = [];
+  let prunedCount = 0;
+  let bytesTotal = 0;
+  let bytesPruned = 0;
+  for (const line of lines) {
+    const bytes = byteLength(line);
+    bytesTotal += bytes;
+    const path = pathOfLine(line, options.format);
+    if (path !== null && isPruned.has(path)) {
+      prunedCount++;
+      bytesPruned += bytes;
+    } else {
+      keptLines.push(line);
+    }
+  }
+  const shown = keptLines.length;
+  const total = lines.length;
+  const body = keptLines.join("\n");
+  const bypassHint = options.bypassHint ?? DEFAULT_BYPASS_HINT;
+  const output = prunedCount === 0 ? body : body === "" ? footer(shown, total, prunedCount, bypassHint) : `${body}
+${footer(shown, total, prunedCount, bypassHint)}`;
+  return {
+    output,
+    shown,
+    total,
+    pruned: prunedCount,
+    bytesTotal,
+    bytesPruned,
+    pathsConsidered: uniquePaths.length
+  };
+}
+
+// ../../lib/engine/generators/mcpConfig.ts
+var MCP_SERVER_NAME = "contextpruner";
+function generateMcpConfig(entry) {
+  return `${JSON.stringify({ mcpServers: { [MCP_SERVER_NAME]: entry } }, null, 2)}
+`;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mergeMcpConfig(existing, entry) {
+  const unchanged = (error) => ({ content: existing, changed: false, error });
+  let root;
+  try {
+    root = JSON.parse(existing);
+  } catch {
+    return unchanged("existing MCP config is not valid JSON");
+  }
+  if (!isPlainObject(root)) {
+    return unchanged("existing MCP config is not a JSON object");
+  }
+  const servers = root.mcpServers ?? {};
+  if (!isPlainObject(servers)) {
+    return unchanged("existing `mcpServers` is not an object");
+  }
+  if (JSON.stringify(servers[MCP_SERVER_NAME]) === JSON.stringify(entry)) {
+    return { content: existing, changed: false };
+  }
+  root.mcpServers = { ...servers, [MCP_SERVER_NAME]: entry };
+  const content = `${JSON.stringify(root, null, 2)}
+`;
+  return { content, changed: true };
+}
+
+// ../../lib/engine/overridesFile.ts
+var OVERRIDES_FILENAME = ".contextpruner";
+var KEEP_LINE = /^keep:\s*(.+)$/;
+var PREFER_TOOLS_LINE = /^prefer-tools(?:\s*:\s*(?:true|on|yes))?$/i;
+function isValidDeclaration(declaration) {
+  return declaration.length > 0 && declaration.length <= MAX_PATH_LENGTH && !declaration.includes("\0") && !declaration.includes("\\") && !declaration.startsWith("/") && declaration.split("/").every((seg) => seg !== "..");
+}
+function parseOverridesFile(source) {
+  const keep = [];
+  const seen = /* @__PURE__ */ new Set();
+  const unknownLines = [];
+  let preferTools = false;
+  for (const raw of source.split("\n")) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    if (PREFER_TOOLS_LINE.test(line)) {
+      preferTools = true;
+      continue;
+    }
+    const match = KEEP_LINE.exec(line);
+    const declaration = match?.[1]?.trim();
+    if (declaration !== void 0 && isValidDeclaration(declaration)) {
+      if (!seen.has(declaration)) {
+        seen.add(declaration);
+        if (keep.length < MAX_OVERRIDE_DECLARATIONS) keep.push(declaration);
+      }
+    } else {
+      unknownLines.push(line);
+    }
+  }
+  return { keep, preferTools, unknownLines };
+}
+function representativePathsFor(declaration) {
+  const literal = declaration.replace(/\*+/g, "cpx");
+  return declaration.includes("*") ? [literal] : [literal, `${literal}/cpx`];
+}
+var PREFER_TOOLS_HEADER = [
+  "# ContextPruner overrides \u2014 https://contextpruner.app",
+  '# prefer-tools: emit the "Prefer these tools" section so agents route broad',
+  "# searches through the filtered tools `contextpruner serve` set up."
+];
+function ensurePreferToolsDirective(existing) {
+  if (existing === null) {
+    return { content: `${[...PREFER_TOOLS_HEADER, "prefer-tools"].join("\n")}
+`, changed: true };
+  }
+  if (parseOverridesFile(existing).preferTools) {
+    return { content: existing, changed: false };
+  }
+  const separator = existing === "" || existing.endsWith("\n") ? "" : "\n";
+  return { content: `${existing}${separator}prefer-tools
+`, changed: true };
+}
+
+// src/args.ts
+function base(command, problem) {
+  return { command, configs: [], json: false, fix: false, problem };
+}
+function parseArgs(argv) {
+  const [command, ...rest] = argv;
+  if (command === void 0 || command === "--help" || command === "-h") {
+    return base("help");
+  }
+  if (command === "--version" || command === "-v") {
+    return base("version");
+  }
+  if (command === "serve") {
+    for (const arg of rest) {
+      if (arg === "--help" || arg === "-h") return base("help");
+      return base("serve", `unknown option "${arg}"`);
+    }
+    return base("serve");
+  }
+  if (command === "__mcp") {
+    for (const arg of rest) {
+      return base("mcp", `unknown option "${arg}"`);
+    }
+    return base("mcp");
+  }
+  if (command === "__filter") {
+    let format;
+    let all = false;
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--all") {
+        all = true;
+      } else if (arg === "--format") {
+        const value = rest[++i];
+        if (value !== "grep" && value !== "paths") {
+          return { ...base("filter", "--format must be grep or paths"), all };
+        }
+        format = value;
+      } else {
+        return { ...base("filter", `unknown option "${arg}"`), all };
+      }
+    }
+    if (format === void 0) {
+      return { ...base("filter", "--format is required"), all };
+    }
+    return { ...base("filter"), format, all };
+  }
+  if (command !== "lint") {
+    return base("unknown", `unknown command "${command}"`);
+  }
+  const configs = [];
+  let json = false;
+  let fix = false;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--json") {
+      json = true;
+    } else if (arg === "--fix") {
+      fix = true;
+    } else if (arg === "--config") {
+      const value = rest[++i];
+      if (value === void 0) {
+        return { command: "lint", configs, json, fix, problem: "--config needs a path" };
+      }
+      configs.push(value);
+    } else if (arg === "--help" || arg === "-h") {
+      return base("help");
+    } else {
+      return { command: "lint", configs, json, fix, problem: `unknown option "${arg}"` };
+    }
+  }
+  return { command: "lint", configs, json, fix };
+}
+
+// src/mcpTargets.ts
+import { join } from "node:path";
+function mcpConfigTargets(cwd, home) {
+  return [
+    { agent: "Claude Code", file: join(cwd, ".mcp.json"), presentDirs: [], always: true },
+    {
+      agent: "Cursor",
+      file: join(cwd, ".cursor", "mcp.json"),
+      presentDirs: [join(cwd, ".cursor")],
+      always: false
+    },
+    {
+      agent: "Gemini CLI",
+      file: join(cwd, ".gemini", "settings.json"),
+      presentDirs: [join(cwd, ".gemini")],
+      always: false
+    },
+    {
+      agent: "Windsurf",
+      file: join(home, ".codeium", "mcp_config.json"),
+      presentDirs: [join(home, ".codeium")],
+      always: false
+    }
+  ];
+}
+
+// src/mcp.ts
+var MCP_TOOLS = [
+  {
+    name: "contextpruner_search",
+    description: "Search file contents across the repository for a text or regex pattern (a broad, repo-wide fan-out search). Prefer this over the built-in grep/search tool for whole-repo searches: it drops junk paths (lockfiles, fixtures, minified/compiled output, snapshots) from the results and reports how many matches it pruned.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Text or regex to search for." },
+        path: { type: "string", description: "Directory to search under (default: the repo root)." },
+        all: { type: "boolean", description: "Set true to bypass junk filtering and see every match." }
+      },
+      required: ["query"]
+    }
+  },
+  {
+    name: "contextpruner_glob",
+    description: "Find files whose name matches a glob pattern (e.g. '*.ts', 'config.*') across the repository. Prefer this over the built-in file-finder for broad matches: junk paths are dropped and the pruned count is reported.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pattern: { type: "string", description: "Filename glob, e.g. '*.ts'." },
+        path: { type: "string", description: "Directory to search under (default: the repo root)." },
+        all: { type: "boolean", description: "Set true to bypass junk filtering and see every file." }
+      },
+      required: ["pattern"]
+    }
+  },
+  {
+    name: "contextpruner_list",
+    description: "List the files directly inside a directory. Prefer this over the built-in directory listing: junk entries are dropped and the pruned count is reported.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Directory to list (default: the repo root)." },
+        all: { type: "boolean", description: "Set true to bypass junk filtering and see everything." }
+      },
+      required: []
+    }
+  }
+];
+function planToolCall(name, args) {
+  const path = typeof args.path === "string" && args.path.trim() !== "" ? args.path : ".";
+  const all = args.all === true;
+  switch (name) {
+    case "contextpruner_search": {
+      if (typeof args.query !== "string" || args.query === "") {
+        return { error: "contextpruner_search needs a non-empty 'query'." };
+      }
+      return { tool: "search", pattern: args.query, path, all };
+    }
+    case "contextpruner_glob": {
+      if (typeof args.pattern !== "string" || args.pattern === "") {
+        return { error: "contextpruner_glob needs a non-empty 'pattern'." };
+      }
+      return { tool: "glob", pattern: args.pattern, path, all };
+    }
+    case "contextpruner_list":
+      return { tool: "list", path, all };
+    default:
+      return { error: `unknown tool: ${name}` };
+  }
+}
+function resolveCommand(plan, opts) {
+  switch (plan.tool) {
+    case "search":
+      return opts.hasRg ? {
+        file: "rg",
+        argv: ["--line-number", "--no-heading", "--color=never", "--", plan.pattern, plan.path],
+        format: "grep"
+      } : {
+        file: "grep",
+        argv: [
+          "-rn",
+          "--color=never",
+          "--exclude-dir=.git",
+          "--exclude-dir=node_modules",
+          "-e",
+          plan.pattern,
+          plan.path
+        ],
+        format: "grep"
+      };
+    case "glob":
+      return {
+        file: "find",
+        argv: [
+          plan.path,
+          "(",
+          "-name",
+          ".git",
+          "-o",
+          "-name",
+          "node_modules",
+          ")",
+          "-prune",
+          "-o",
+          "-name",
+          plan.pattern,
+          "-print"
+        ],
+        format: "paths"
+      };
+    case "list":
+      return {
+        file: "find",
+        argv: [plan.path, "-maxdepth", "1", "-mindepth", "1"],
+        format: "paths"
+      };
+  }
+}
+var MCP_BYPASS_HINT = "call this tool again with all: true to see them";
+function buildToolResult(raw, opts, onStats) {
+  const { output, shown, total, pruned, pathsConsidered, bytesPruned } = filterSearchOutput(raw, {
+    format: opts.format,
+    all: opts.all,
+    bypassHint: MCP_BYPASS_HINT
+  });
+  onStats?.({ pathsConsidered, bytesPruned });
+  return {
+    content: [{ type: "text", text: output === "" ? "(no matches)" : output }],
+    structuredContent: { shown, total, pruned }
+  };
+}
+var PROTOCOL_VERSION = "2025-06-18";
+async function handleMcpMessage(msg, deps) {
+  const { id, method, params } = msg;
+  const reply = (result) => ({ jsonrpc: "2.0", id, result });
+  const fail = (code, message) => ({
+    jsonrpc: "2.0",
+    id,
+    error: { code, message }
+  });
+  switch (method) {
+    case "initialize":
+      return reply({
+        protocolVersion: typeof params?.protocolVersion === "string" ? params.protocolVersion : PROTOCOL_VERSION,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: deps.serverInfo
+      });
+    case "notifications/initialized":
+    case "initialized":
+      return null;
+    // notification — no reply
+    case "tools/list":
+      return reply({ tools: MCP_TOOLS });
+    case "tools/call": {
+      const name = typeof params?.name === "string" ? params.name : "";
+      const args = params?.arguments ?? {};
+      const result = await deps.callTool(name, args);
+      return reply(result);
+    }
+    case "ping":
+      return reply({});
+    case "resources/list":
+      return reply({ resources: [] });
+    case "prompts/list":
+      return reply({ prompts: [] });
+    default:
+      return id === void 0 || id === null ? null : fail(-32601, `method not found: ${method}`);
+  }
+}
+
 // ../../lib/engine/enforce.ts
 var UNENFORCED_BINARY_EXTENSIONS = /* @__PURE__ */ new Set(["svg", "pdf"]);
 var ENV_ENFORCED_GLOB = "**/.env*";
@@ -410,7 +845,7 @@ function generateClaudeSettings(input) {
   return `${JSON.stringify(settings, null, 2)}
 `;
 }
-function isPlainObject(value) {
+function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function mergeClaudeSettings(existing, input) {
@@ -425,11 +860,11 @@ function mergeClaudeSettings(existing, input) {
   } catch {
     return unchanged("existing settings file is not valid JSON");
   }
-  if (!isPlainObject(root)) {
+  if (!isPlainObject2(root)) {
     return unchanged("existing settings file is not a JSON object");
   }
   const permissions = root.permissions ?? {};
-  if (!isPlainObject(permissions)) {
+  if (!isPlainObject2(permissions)) {
     return unchanged("existing `permissions` is not an object");
   }
   const deny = permissions.deny ?? [];
@@ -504,6 +939,18 @@ function formatStatsLine(stats) {
 var MANAGED_BLOCK_BEGIN = "<!-- contextpruner:begin -->";
 var MANAGED_BLOCK_END = "<!-- contextpruner:end -->";
 var MANAGED_BLOCK_NOTE = "<!-- generated block \u2014 edits inside are overwritten on regeneration -->";
+function preferToolsSection() {
+  return [
+    "## Prefer these tools",
+    "",
+    "For a broad, repo-wide search \u2014 grep, glob, list, or an initial scan \u2014 use ContextPruner's filtered tools instead of the built-in ones. They run the same search on your machine and drop junk paths (lockfiles, minified or compiled output, fixtures, snapshots) from the results, so less noise reaches context:",
+    "",
+    "- MCP tools: `contextpruner_search` (file contents), `contextpruner_glob` (files by name), `contextpruner_list` (a directory's files).",
+    "- Shell shims, if `contextpruner serve` added them to your PATH: plain `grep`, `rg`, `find`, and `ls` already filter.",
+    "",
+    "Each result says what it hid, e.g. `showing 40 of 210 matches; 170 pruned as junk`. To see everything, call an MCP tool with `all: true`, or set `CONTEXTPRUNER_ALL=1` for the shims. Reading one named file is never filtered \u2014 open it directly."
+  ];
+}
 function generateMarkdownRules(filename, input) {
   const lines = [
     MANAGED_BLOCK_BEGIN,
@@ -557,6 +1004,9 @@ function generateMarkdownRules(filename, input) {
       lines.push(`- Prune (do not read): \`${path}\``);
     }
   }
+  if (input.preferTools) {
+    lines.push("", ...preferToolsSection());
+  }
   lines.push(
     "",
     MANAGED_BLOCK_END,
@@ -753,15 +1203,21 @@ function computeSavings(bytesTotal, bytesKept, options = {}) {
 // ../../lib/engine/prune.ts
 var MAX_PRIORITY_GLOBS = 5;
 function prune(files, options = {}) {
-  const overrides = options.verdictOverrides ?? {};
+  const declarations = options.keepDeclarations ?? [];
+  const overrides = {
+    ...Object.fromEntries(
+      declarations.filter((declaration) => !declaration.includes("*")).map((path) => [path, "KEEP"])
+    ),
+    ...options.verdictOverrides
+  };
   const classified = files.map((file) => {
-    const base = classify(file);
+    const base2 = classify(file);
     const pinned = Object.hasOwn(overrides, file.path) ? overrides[file.path] : void 0;
-    if (pinned === void 0 || pinned === base.verdict) {
-      return base;
+    if (pinned === void 0 || pinned === base2.verdict) {
+      return base2;
     }
     return {
-      ...base,
+      ...base2,
       verdict: pinned,
       glob: null,
       overridden: true
@@ -816,7 +1272,15 @@ function prune(files, options = {}) {
     windowClamped: pinnedSavings.windowClamped
   };
   for (const glob of options.extraExcludeGlobs ?? []) excludeGlobs.add(glob);
-  const enforced = deriveEnforcedRules(classified);
+  const pinDemoted = deriveEnforcedRules(classified);
+  const declDemoted = demoteEnforcedGlobs(
+    pinDemoted.globs,
+    declarations.flatMap(representativePathsFor)
+  );
+  const enforced = {
+    globs: declDemoted.globs,
+    demoted: [...pinDemoted.demoted, ...declDemoted.demoted]
+  };
   const priorityGlobs = [...keptBytesByDir.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, MAX_PRIORITY_GLOBS).map(([dir]) => `${dir}/**`);
   const generatorInput = {
     generatedAt: (options.now ?? /* @__PURE__ */ new Date()).toISOString(),
@@ -829,7 +1293,8 @@ function prune(files, options = {}) {
     pruneOverridePaths: classified.filter((f) => f.overridden && f.verdict === "PRUNE").map((f) => f.path).sort(),
     // Static-baseline + derived enforce-set; independent of extraExcludeGlobs
     // (the baseline already names every canonical untracked junk dir).
-    enforcedGlobs: enforced.globs
+    enforcedGlobs: enforced.globs,
+    preferTools: options.preferTools ?? false
   };
   const verdicts = classified.map(
     ({ path, verdict, reason, sizeInBytes, overridden }) => ({
@@ -914,11 +1379,14 @@ var IGNORE_GENERATOR_BY_TITLE = {
   ".codeiumignore": generateCodeiumIgnore
 };
 var IGNORE_TITLE_RE = /^# (\.[a-z]+ignore) — enforced AI context rules/m;
-function buildFixedEnforcedConfig(files, userConfig, format, pins = { keep: [], skim: [] }) {
+function buildFixedEnforcedConfig(files, userConfig, format, pins = { keep: [], skim: [] }, keepDeclarations = []) {
   const classified = files.map(classify);
   const enforcedGlobs = demoteEnforcedGlobs(
     deriveEnforcedRules(classified).globs,
-    effectivePinnedPaths(classified, pins)
+    [
+      ...effectivePinnedPaths(classified, pins),
+      ...keepDeclarations.flatMap(representativePathsFor)
+    ]
   ).globs;
   if (format === "claudeSettings") {
     if (!parseEnforcedConfig(userConfig, "claudeSettings").recognized) {
@@ -983,10 +1451,16 @@ function dialectLine(glob, format) {
 function expectedEnforcedGlobs(classified, pinnedPaths) {
   return demoteEnforcedGlobs(deriveEnforcedRules(classified).globs, pinnedPaths).globs;
 }
-function enforcedFindings(classified, paths, enforced, pinnedPaths) {
+function enforcedFindings(classified, paths, enforced, pinnedPaths, keepDeclarations) {
   const findings = [];
-  const expected = expectedEnforcedGlobs(classified, pinnedPaths);
+  const expected = expectedEnforcedGlobs(classified, [
+    ...pinnedPaths,
+    ...keepDeclarations.flatMap(representativePathsFor)
+  ]);
   const expectedSet = new Set(expected);
+  const declarationReps = keepDeclarations.map(
+    (declaration) => [declaration, representativePathsFor(declaration)]
+  );
   for (const config of enforced) {
     const have = new Set(config.engineGlobs);
     for (const glob of expected) {
@@ -1023,6 +1497,17 @@ function enforcedFindings(classified, paths, enforced, pinnedPaths) {
           });
         }
       }
+      for (const [declaration, representatives] of declarationReps) {
+        if (representatives.some(matches)) {
+          findings.push({
+            kind: "conflict",
+            severity: "high",
+            glob,
+            path: declaration,
+            message: `\`${declaration}\` is declared keep in ${OVERRIDES_FILENAME} but ${config.name} still hard-blocks it via \`${dialectLine(glob, config.format)}\``
+          });
+        }
+      }
     }
     for (const line of config.foreignLines) {
       findings.push({
@@ -1032,18 +1517,18 @@ function enforcedFindings(classified, paths, enforced, pinnedPaths) {
       });
     }
   }
-  const base = enforced[0];
-  if (base) {
-    const baseSet = new Set(base.engineGlobs);
+  const base2 = enforced[0];
+  if (base2) {
+    const baseSet = new Set(base2.engineGlobs);
     for (const other of enforced.slice(1)) {
       const otherSet = new Set(other.engineGlobs);
-      for (const glob of base.engineGlobs) {
+      for (const glob of base2.engineGlobs) {
         if (!otherSet.has(glob)) {
           findings.push({
             kind: "drift",
             severity: "medium",
             glob,
-            message: `Enforced \`${glob}\` is in ${base.name} but not ${other.name}`
+            message: `Enforced \`${glob}\` is in ${base2.name} but not ${other.name}`
           });
         }
       }
@@ -1053,7 +1538,7 @@ function enforcedFindings(classified, paths, enforced, pinnedPaths) {
             kind: "drift",
             severity: "medium",
             glob,
-            message: `Enforced \`${glob}\` is in ${other.name} but not ${base.name}`
+            message: `Enforced \`${glob}\` is in ${other.name} but not ${base2.name}`
           });
         }
       }
@@ -1101,14 +1586,25 @@ function reconcile(files, configs, options = {}) {
     keep: keepPins,
     skim: skimPins
   });
+  const declarations = options.keepDeclarations ?? [];
+  const demotionPaths = [
+    ...pinnedPaths,
+    ...declarations.flatMap(representativePathsFor)
+  ];
   if ((primary.format ?? "markdown") !== "markdown") {
     const parsedPrimary = parseEnforcedConfig(
       primary.source,
       primary.format
     );
     if (!parsedPrimary.recognized) return empty2;
-    const findings2 = enforcedFindings(classified, paths, enforced, pinnedPaths);
-    const expected = expectedEnforcedGlobs(classified, pinnedPaths);
+    const findings2 = enforcedFindings(
+      classified,
+      paths,
+      enforced,
+      pinnedPaths,
+      declarations
+    );
+    const expected = expectedEnforcedGlobs(classified, demotionPaths);
     const have = new Set(parsedPrimary.engineGlobs);
     const present = expected.filter((glob) => have.has(glob)).length;
     const coveragePct2 = expected.length === 0 ? 100 : Math.floor(present / expected.length * 100);
@@ -1241,7 +1737,9 @@ function reconcile(files, configs, options = {}) {
       }
     }
   }
-  findings.push(...enforcedFindings(classified, paths, enforced, pinnedPaths));
+  findings.push(
+    ...enforcedFindings(classified, paths, enforced, pinnedPaths, declarations)
+  );
   let junkBytes = 0;
   let prunedBytes = 0;
   for (const file of classified) {
@@ -1391,11 +1889,11 @@ var DEFAULT_CONFIG_PATHS = [
   ".claude/settings.json"
 ];
 function formatForPath(path) {
-  const base = path.split("/").pop() ?? path;
-  if (base === ".cursorignore" || base === ".geminiignore" || base === ".codeiumignore") {
+  const base2 = path.split("/").pop() ?? path;
+  if (base2 === ".cursorignore" || base2 === ".geminiignore" || base2 === ".codeiumignore") {
     return "gitignore";
   }
-  if (base === "settings.json") return "claudeSettings";
+  if (base2 === "settings.json") return "claudeSettings";
   return "markdown";
 }
 var CREATE_KEY = "Set CONTEXTPRUNER_API_KEY (create one at https://contextpruner.app/account).";
@@ -1454,6 +1952,11 @@ async function runLint(deps) {
   if (files.length === 0) {
     return { text: "No tracked files found.", exitCode: 2, channel: "stderr" };
   }
+  const overridesSource = deps.readConfig(OVERRIDES_FILENAME);
+  const parsedOverrides = parseOverridesFile(overridesSource ?? "");
+  const overridesWarning = parsedOverrides.unknownLines.length > 0 ? `
+  \u26A0 ${OVERRIDES_FILENAME}: ignored ${parsedOverrides.unknownLines.length} unrecognized line${parsedOverrides.unknownLines.length === 1 ? "" : "s"} (${parsedOverrides.unknownLines.map((l) => `"${l}"`).join(", ")}) \u2014 only \`keep: <path-or-glob>\` lines are read.
+` : "";
   if (deps.fix) {
     const pins = { keep: [], skim: [] };
     for (const c of configs) {
@@ -1474,7 +1977,13 @@ async function runLint(deps) {
         });
         result = buildFixedConfig(files, source, void 0, spared);
       } else {
-        result = buildFixedEnforcedConfig(files, source, format, pins);
+        result = buildFixedEnforcedConfig(
+          files,
+          source,
+          format,
+          pins,
+          parsedOverrides.keep
+        );
       }
       if (!result.fixable) {
         unfixable.push(name);
@@ -1485,57 +1994,470 @@ async function runLint(deps) {
     }
     if (fixed.length > 0) {
       return {
-        text: `Fixed ${fixed.join(", ")}. Re-run without --fix to confirm.`,
+        text: `${overridesWarning}Fixed ${fixed.join(", ")}. Re-run without --fix to confirm.`,
         exitCode: 0,
         channel: "stdout"
       };
     }
     if (unfixable.length === configs.length) {
       return {
-        text: `Nothing to fix \u2014 ${unfixable.join(", ")} ${unfixable.length === 1 ? "has" : "have"} no ContextPruner managed block (or, for .claude/settings.json, could not be merged safely).`,
+        text: `${overridesWarning}Nothing to fix \u2014 ${unfixable.join(", ")} ${unfixable.length === 1 ? "has" : "have"} no ContextPruner managed block (or, for .claude/settings.json, could not be merged safely).`,
         exitCode: 2,
         channel: "stderr"
       };
     }
     const skipped = unfixable.length > 0 ? ` Skipped ${unfixable.join(", ")} (no ContextPruner managed block, or unmergeable).` : "";
     return {
-      text: `Nothing to fix \u2014 your configs already match the tree.${skipped}`,
+      text: `${overridesWarning}Nothing to fix \u2014 your configs already match the tree.${skipped}`,
       exitCode: 0,
       channel: "stdout"
     };
   }
-  const report = reconcile(files, configs);
+  const report = reconcile(files, configs, {
+    keepDeclarations: parsedOverrides.keep
+  });
   const kept = report.findings.filter((f) => !isFalseDead(f));
   const filtered = { ...report, findings: kept };
-  const text = deps.json ? JSON.stringify(filtered, null, 2) : formatReport(filtered);
+  const text = deps.json ? JSON.stringify(filtered, null, 2) : `${overridesWarning}${formatReport(filtered)}`;
   return { text, exitCode: exitCodeFor(filtered), channel: "stdout" };
 }
 
+// src/shims.ts
+var SHIM_TOOLS = [
+  { name: "rg", mode: "grep" },
+  { name: "grep", mode: "grep" },
+  { name: "find", mode: "paths" },
+  { name: "ls", mode: "paths" },
+  { name: "cat", mode: "passthrough" }
+];
+function shSingleQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function sanitizePathForRealTools(pathEnv, shimDir) {
+  const normalized = shimDir.replace(/\/+$/, "");
+  return pathEnv.split(":").filter((dir) => dir.replace(/\/+$/, "") !== normalized).join(":");
+}
+function resolveRealLines(name) {
+  return [
+    'self_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)',
+    "real=",
+    "IFS=:",
+    "for d in $PATH; do",
+    // Normalize each PATH entry to its physical (symlink-resolved) path before
+    // comparing to self_dir — self_dir is already physical, so a symlinked
+    // install dir (symlinked $HOME etc.) still string-matches and is skipped.
+    // Because the chosen d_phys can never equal self_dir, the resolved real can
+    // never live in the shim's own directory and thus can never be the shim,
+    // which is what prevents the front-of-PATH self-recursion.
+    '  d_phys=$(CDPATH= cd -- "$d" 2>/dev/null && pwd) || d_phys=$d',
+    '  [ "$d_phys" = "$self_dir" ] && continue',
+    // Belt-and-suspenders: even after the physical-dir skip, a duplicate shim
+    // (a symlink/hardlink to this same file) reachable through a *different*
+    // physical dir earlier on PATH would otherwise be chosen as `real` and
+    // recurse. Skip any candidate that is the same file as this shim.
+    `  [ "$d_phys/${name}" -ef "$0" ] && continue`,
+    `  if [ -x "$d_phys/${name}" ]; then real="$d_phys/${name}"; break; fi`,
+    "done",
+    "unset IFS",
+    `if [ -z "$real" ]; then echo "contextpruner: real ${name} not found on PATH" >&2; exit 127; fi`
+  ];
+}
+function shimScript(tool, cpInvoke) {
+  const lines = ["#!/bin/sh"];
+  if (tool.mode === "passthrough") {
+    lines.push(
+      `# ContextPruner shim for ${tool.name} \u2014 a pointed read, never filtered.`,
+      "# Managed by `contextpruner serve`; safe to delete.",
+      ...resolveRealLines(tool.name),
+      'exec "$real" "$@"'
+    );
+    return `${lines.join("\n")}
+`;
+  }
+  lines.push(
+    `# ContextPruner shim for ${tool.name} \u2014 drops junk paths from broad fan-out output.`,
+    "# Managed by `contextpruner serve`; safe to delete.",
+    `# CONTEXTPRUNER_ALL=1 runs ${tool.name} unfiltered.`,
+    ...resolveRealLines(tool.name),
+    'if [ "${CONTEXTPRUNER_ALL:-}" = "1" ]; then exec "$real" "$@"; fi',
+    // Buffer to a temp file so the real tool's exit code survives the pipe
+    // (POSIX sh has no PIPESTATUS); the filter itself always exits 0.
+    "tmp=$(mktemp)",
+    `trap 'rm -f "$tmp"' EXIT`,
+    '"$real" "$@" > "$tmp"',
+    "rc=$?",
+    // Fail open: if the filter invocation is dead (stale node/CLI path) or errors,
+    // emit the raw buffered output rather than silently swallowing all results —
+    // the feature degrades toward keeping, never toward losing output.
+    `if ${cpInvoke} __filter --format ${tool.mode} < "$tmp"; then`,
+    "  :",
+    "else",
+    '  cat "$tmp"',
+    "fi",
+    "exit $rc"
+  );
+  return `${lines.join("\n")}
+`;
+}
+function shimInstallPlan(cpInvoke) {
+  return SHIM_TOOLS.map((tool) => ({
+    name: tool.name,
+    content: shimScript(tool, cpInvoke),
+    mode: 493
+  }));
+}
+
+// src/stats.ts
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync
+} from "node:fs";
+import { dirname, join as join2 } from "node:path";
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var configPath = (dir) => join2(dir, "config.json");
+var tallyPath = (dir) => join2(dir, "stats.json");
+function writeJsonAtomic(file, value) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, JSON.stringify(value), "utf8");
+  renameSync(tmp, file);
+}
+function readJson(file, fallback) {
+  try {
+    if (!existsSync(file)) return fallback;
+    return { ...fallback, ...JSON.parse(readFileSync(file, "utf8")) };
+  } catch {
+    return fallback;
+  }
+}
+function readConfig(dir) {
+  return readJson(configPath(dir), {});
+}
+function writeConfig(dir, config) {
+  writeJsonAtomic(configPath(dir), config);
+}
+function readTally(dir) {
+  const t = readJson(tallyPath(dir), {
+    filesAssessed: 0,
+    bytesSaved: 0
+  });
+  const clean = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0 ? n : 0;
+  return { filesAssessed: clean(t.filesAssessed), bytesSaved: clean(t.bytesSaved) };
+}
+function consentValue(dir) {
+  return readConfig(dir).statsConsent;
+}
+var CONSENT_PROMPT = [
+  "contextpruner: Would you mind sharing how many files were assessed and how",
+  "  many bytes saved? We'd love to display aggregate counts on the website.",
+  "  Only two numbers are ever sent \u2014 never a path, never file contents. [y/N] "
+].join("\n");
+async function ensureConsent(dir, deps) {
+  const existing = consentValue(dir);
+  if (existing) return existing;
+  if (!deps.isTTY) return void 0;
+  deps.out(CONSENT_PROMPT);
+  const answer = (await deps.ask()).trim();
+  const consent = /^y(es)?$/i.test(answer) ? "yes" : "no";
+  writeConfig(dir, { ...readConfig(dir), statsConsent: consent });
+  deps.out(
+    consent === "yes" ? "contextpruner: thanks! Two aggregate numbers will be shared, nothing else." : "contextpruner: no problem \u2014 nothing will be sent, and you won't be asked again."
+  );
+  return consent;
+}
+function accumulate(dir, pathsConsidered, bytesPruned) {
+  if (consentValue(dir) !== "yes") return;
+  try {
+    const t = readTally(dir);
+    writeJsonAtomic(tallyPath(dir), {
+      filesAssessed: t.filesAssessed + Math.max(0, Math.trunc(pathsConsidered)),
+      bytesSaved: t.bytesSaved + Math.max(0, Math.trunc(bytesPruned))
+    });
+  } catch {
+  }
+}
+async function flushStats(dir, deps) {
+  const config = readConfig(dir);
+  if (config.statsConsent !== "yes") return "skipped";
+  const now = deps.now ?? Date.now();
+  const interval = deps.minIntervalMs ?? DAY_MS;
+  if (config.statsLastFlushAt) {
+    const last = Date.parse(config.statsLastFlushAt);
+    if (Number.isFinite(last) && now - last < interval) return "skipped";
+  }
+  const tally = readTally(dir);
+  if (tally.filesAssessed === 0 && tally.bytesSaved === 0) return "nothing";
+  const doFetch = deps.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), deps.timeoutMs ?? 5e3);
+  try {
+    const res = await doFetch(`${deps.baseUrl}/api/stats/contribute`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${deps.key}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(tally),
+      signal: controller.signal
+    });
+    if (!res.ok) return "failed";
+  } catch {
+    return "failed";
+  } finally {
+    clearTimeout(timer);
+  }
+  writeJsonAtomic(tallyPath(dir), { filesAssessed: 0, bytesSaved: 0 });
+  writeConfig(dir, {
+    ...readConfig(dir),
+    statsLastFlushAt: new Date(now).toISOString()
+  });
+  return "sent";
+}
+
 // src/index.ts
-var VERSION = "0.2.0";
-var HELP = `contextpruner lint \u2014 check your AI-context config against your repo
+var cpDir = () => join3(homedir(), ".contextpruner");
+var VERSION = "0.4.0";
+var HELP = `contextpruner \u2014 keep your AI-context config honest, and junk out of search
 
 Usage:
-  contextpruner lint [--config <path>]... [--json]
+  contextpruner lint [--config <path>]... [--fix] [--json]
+  contextpruner serve
+
+Commands:
+  lint    Check your AI-context config against your repo (auto-detects the nine
+          config files; --fix rewrites each managed block in place).
+  serve   (paid) Filter search junk. Installs the grep/rg/find/ls shims,
+          writes each agent's filtered-search MCP config, and marks
+          .contextpruner so generated configs prefer the filtered tools.
+          Prints the PATH line to add.
 
 Options:
-  --config <path>   A config to lint (repeatable). Default: auto-detect
-                    AGENTS.md, CLAUDE.md, GEMINI.md, Copilot, and Cursor rules,
-                    plus the enforced .cursorignore, .geminiignore,
-                    .codeiumignore, and .claude/settings.json.
-  --fix             Rewrite each config's managed block in place to fix the
-                    issues \u2014 enforced files too, via their managed block. Your
-                    own content outside the block is left alone.
-  --json            Emit the full report as JSON.
+  --config <path>   A config to lint (repeatable). Default: auto-detect.
+  --fix             Rewrite each config's managed block in place.
+  --json            Emit the lint report as JSON.
   -h, --help        Show this help.
   -v, --version     Show the version.
 
-Auth:
+Auth (lint --fix and serve):
   export CONTEXTPRUNER_API_KEY=cp_live_...   (create one at
-  https://contextpruner.app/account). Only your key is sent \u2014 the file tree
-  never leaves your machine.
+  https://contextpruner.app/account). Your files and their contents never
+  leave your machine; only your key is sent \u2014 plus, if you opt in at serve,
+  two aggregate counts (files assessed, bytes saved).
 
-Exit codes: 0 clean \xB7 1 issues found \xB7 2 usage/auth error.`;
+Exit codes: 0 clean/ok \xB7 1 issues found \xB7 2 usage/auth error.`;
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function runServe(baseUrl) {
+  const key = process.env.CONTEXTPRUNER_API_KEY;
+  if (!key) {
+    console.error(
+      "contextpruner serve needs a key. export CONTEXTPRUNER_API_KEY=cp_live_... (create one at https://contextpruner.app/account)."
+    );
+    return 2;
+  }
+  const verify = await verifyKey({ key, baseUrl });
+  if (!verify.ok) {
+    console.error(verify.message);
+    return 2;
+  }
+  const binDir = join3(homedir(), ".contextpruner", "bin");
+  mkdirSync2(binDir, { recursive: true });
+  const cliPath = process.argv[1] ?? "contextpruner";
+  const cpOnPath = resolveOnPath("contextpruner");
+  const cpInvoke = cpOnPath ? "contextpruner" : `node ${shSingleQuote(cliPath)}`;
+  const plan = shimInstallPlan(cpInvoke);
+  for (const file of plan) {
+    const dest = join3(binDir, file.name);
+    writeFileSync2(dest, file.content, { mode: file.mode });
+    chmodSync(dest, file.mode);
+  }
+  const names = plan.map((f) => f.name).join(", ");
+  console.log(`contextpruner: installed ${plan.length} search shims (${names}) to ${binDir}`);
+  console.log(`  shims filter via: ${cpInvoke}`);
+  if (!cpOnPath) {
+    console.log(
+      "  (note: moving or reinstalling the CLI to a new path needs a re-run of `contextpruner serve`)"
+    );
+  }
+  console.log("");
+  console.log("Add it to the front of your PATH so broad searches drop junk automatically:");
+  console.log(`  export PATH="${binDir}:$PATH"`);
+  console.log("");
+  console.log(
+    "Then rg/grep/find/ls hide junk paths from fan-out results (set CONTEXTPRUNER_ALL=1 to see everything). cat is never filtered."
+  );
+  const mcpEntry = cpOnPath ? { command: "contextpruner", args: ["__mcp"] } : { command: "node", args: [cliPath, "__mcp"] };
+  console.log("");
+  for (const target of mcpConfigTargets(process.cwd(), homedir())) {
+    if (!target.always && !target.presentDirs.some((dir2) => existsSync2(dir2))) {
+      console.log(`contextpruner: ${target.agent} not detected \u2014 re-run serve once it's set up.`);
+      continue;
+    }
+    writeMcpConfig(target, mcpEntry);
+  }
+  console.log(
+    "  Restart the agent, then prefer contextpruner_search / _glob / _list for broad searches (pass all:true to see everything)."
+  );
+  const overridesPath = join3(process.cwd(), OVERRIDES_FILENAME);
+  const overrides = ensurePreferToolsDirective(
+    existsSync2(overridesPath) ? readFileSync2(overridesPath, "utf8") : null
+  );
+  console.log("");
+  if (overrides.changed) {
+    writeFileSync2(overridesPath, overrides.content, "utf8");
+    console.log(
+      `contextpruner: marked ${overridesPath} with "prefer-tools" \u2014 commit it so the config automation adds the "Prefer these tools" section for your team.`
+    );
+  } else {
+    console.log(`contextpruner: ${overridesPath} already has "prefer-tools".`);
+  }
+  const dir = cpDir();
+  console.log("");
+  try {
+    await ensureConsent(dir, {
+      isTTY: Boolean(process.stdin.isTTY),
+      ask: readLine,
+      out: (line) => console.log(line)
+    });
+    await flushStats(dir, { key, baseUrl });
+  } catch {
+  }
+  return 0;
+}
+function readLine() {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question("", (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+function writeMcpConfig(target, entry) {
+  mkdirSync2(dirname2(target.file), { recursive: true });
+  if (!existsSync2(target.file)) {
+    writeFileSync2(target.file, generateMcpConfig(entry), "utf8");
+    console.log(`contextpruner: wrote ${target.file} (${target.agent}).`);
+    return;
+  }
+  const merge = mergeMcpConfig(readFileSync2(target.file, "utf8"), entry);
+  if (merge.error) {
+    console.log(
+      `contextpruner: left ${target.file} untouched (${merge.error}). Add a "contextpruner" server to its mcpServers by hand.`
+    );
+  } else if (merge.changed) {
+    writeFileSync2(target.file, merge.content, "utf8");
+    console.log(`contextpruner: updated ${target.file} (${target.agent}).`);
+  } else {
+    console.log(`contextpruner: ${target.file} already has the "contextpruner" MCP server.`);
+  }
+}
+function resolveOnPath(name, pathEnv = process.env.PATH ?? "") {
+  for (const dir of pathEnv.split(":")) {
+    if (!dir) continue;
+    const candidate = join3(dir, name);
+    try {
+      const st = statSync(candidate);
+      if (st.isFile() && (st.mode & 73) !== 0) return candidate;
+    } catch {
+    }
+  }
+  return null;
+}
+function runSearch(file, argv, cwd, pathEnv) {
+  return new Promise((resolve, reject) => {
+    execFile(
+      file,
+      argv,
+      { cwd, maxBuffer: 256 * 1024 * 1024, encoding: "utf8", env: { ...process.env, PATH: pathEnv } },
+      (error, stdout) => {
+        if (error && typeof error.code === "string") {
+          reject(error);
+          return;
+        }
+        resolve(stdout ?? "");
+      }
+    );
+  });
+}
+async function runMcp(baseUrl) {
+  const key = process.env.CONTEXTPRUNER_API_KEY;
+  if (!key) {
+    console.error(
+      "contextpruner __mcp needs a key. export CONTEXTPRUNER_API_KEY=cp_live_... (create one at https://contextpruner.app/account)."
+    );
+    return 2;
+  }
+  const verify = await verifyKey({ key, baseUrl });
+  if (!verify.ok && (verify.kind === "invalid_key" || verify.kind === "inactive")) {
+    console.error(verify.message);
+    return 2;
+  }
+  if (!verify.ok) {
+    console.error(`contextpruner: ${verify.message} Starting anyway (filtering runs locally).`);
+  }
+  const cwd = process.cwd();
+  const shimBinDir = join3(homedir(), ".contextpruner", "bin");
+  const realToolPath = sanitizePathForRealTools(process.env.PATH ?? "", shimBinDir);
+  const hasRg = resolveOnPath("rg", realToolPath) !== null;
+  const callTool = async (name, args) => {
+    const plan = planToolCall(name, args);
+    if ("error" in plan) return { content: [{ type: "text", text: plan.error }], isError: true };
+    const { file, argv, format } = resolveCommand(plan, { hasRg });
+    try {
+      const raw = await runSearch(file, argv, cwd, realToolPath);
+      return buildToolResult(
+        raw,
+        { format, all: plan.all },
+        (s) => accumulate(cpDir(), s.pathsConsidered, s.bytesPruned)
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        content: [{ type: "text", text: `contextpruner: search failed \u2014 ${message}` }],
+        isError: true
+      };
+    }
+  };
+  const deps = { callTool, serverInfo: { name: "contextpruner", version: VERSION } };
+  const send = (msg) => process.stdout.write(`${JSON.stringify(msg)}
+`);
+  let buffer = "";
+  process.stdin.setEncoding("utf8");
+  return new Promise((resolve) => {
+    process.stdin.on("data", (chunk) => {
+      buffer += chunk;
+      let nl;
+      while ((nl = buffer.indexOf("\n")) !== -1) {
+        const line = buffer.slice(0, nl).trim();
+        buffer = buffer.slice(nl + 1);
+        if (line === "") continue;
+        let parsed;
+        try {
+          parsed = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        void handleMcpMessage(parsed, deps).then(
+          (response) => {
+            if (response !== null) send(response);
+          },
+          (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`contextpruner: message handling failed \u2014 ${message}`);
+          }
+        );
+      }
+    });
+    process.stdin.on("end", () => resolve(0));
+  });
+}
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.command === "help") {
@@ -1546,16 +2468,46 @@ async function main() {
     console.log(VERSION);
     return 0;
   }
-  if (args.command !== "lint" || args.problem) {
+  if (args.problem || args.command === "unknown") {
     console.error(`contextpruner: ${args.problem ?? "invalid usage"}
 
 ${HELP}`);
     return 2;
   }
+  const baseUrl = process.env.CONTEXTPRUNER_API_URL ?? "https://contextpruner.app";
+  if (args.command === "filter") {
+    if (!args.format) {
+      console.error("contextpruner: --format is required");
+      return 2;
+    }
+    const raw = await readStdin();
+    const { output, bytesTotal, bytesPruned, pathsConsidered } = filterSearchOutput(raw, {
+      format: args.format,
+      all: args.all
+    });
+    if (output) process.stdout.write(`${output}
+`);
+    if (bytesPruned > 0) {
+      const before = Math.round(bytesTotal * BYTES_PER_TOKEN_RATIO);
+      const saved = Math.round(bytesPruned * BYTES_PER_TOKEN_RATIO);
+      process.stderr.write(
+        `contextpruner: this search \u2014 ~${before} \u2192 ~${before - saved} tokens (~${saved} of junk pruned)
+`
+      );
+    }
+    accumulate(cpDir(), pathsConsidered, bytesPruned);
+    return 0;
+  }
+  if (args.command === "mcp") {
+    return runMcp(baseUrl);
+  }
+  if (args.command === "serve") {
+    return runServe(baseUrl);
+  }
   const cwd = process.cwd();
   const { text, exitCode, channel } = await runLint({
     key: process.env.CONTEXTPRUNER_API_KEY,
-    baseUrl: process.env.CONTEXTPRUNER_API_URL ?? "https://contextpruner.app",
+    baseUrl,
     configPaths: args.configs.length > 0 ? args.configs : DEFAULT_CONFIG_PATHS,
     json: args.json,
     fix: args.fix,
@@ -1563,9 +2515,9 @@ ${HELP}`);
       cwd,
       maxBuffer: 256 * 1024 * 1024
     }).toString("utf8").split("\0").filter(Boolean),
-    sizeOf: (path) => statSync(join(cwd, path)).size,
-    readConfig: (path) => existsSync(join(cwd, path)) ? readFileSync(join(cwd, path), "utf8") : null,
-    writeConfig: (path, content) => writeFileSync(join(cwd, path), content, "utf8")
+    sizeOf: (path) => statSync(join3(cwd, path)).size,
+    readConfig: (path) => existsSync2(join3(cwd, path)) ? readFileSync2(join3(cwd, path), "utf8") : null,
+    writeConfig: (path, content) => writeFileSync2(join3(cwd, path), content, "utf8")
   });
   if (channel === "stderr") {
     console.error(text);