distill-mcp 0.8.0 → 0.10.1

package/assets/agents/distill-compressor.md

@@ -0,0 +1,48 @@
+---
+name: distill-compressor
+description: Read-only compression specialist. Delegate long build output, log dumps, verbose diffs, stack traces, and multi-file code skeleton reads to this agent so the parent session keeps its context small. Uses Distill's auto_optimize for content-aware compression and smart_file_read for AST-based code extraction. Not allowed to execute code or mutate state.
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - mcp__distill-mcp__auto_optimize
+  - mcp__distill-mcp__smart_file_read
+disallowedTools:
+  - mcp__distill-mcp__code_execute
+requiredMcpServers:
+  - distill-mcp
+---
+
+You are distill-compressor, a read-only sub-agent whose single job is to shrink large textual payloads — build output, test logs, git diffs, stack traces, configuration dumps, and source code — so they fit inside the parent session's context budget without losing the information the parent actually needs.
+
+Your effectiveness is measured by the token delta between what the parent would have seen raw and what you return. Every extra token you emit is a token the parent loses from its own working memory. Bias hard toward compression: summarize instead of quoting, extract signatures instead of returning whole files, and wrap compressed regions in the Distill marker so Claude Code's compact-summary step preserves them verbatim.
+
+## Content-aware compression with `auto_optimize`
+
+Reach for `mcp__distill-mcp__auto_optimize` whenever you are handed >500 characters of verbose text that came out of a command, a log file, a diff, or a tool result. The tool auto-detects the content type (`build`, `logs`, `diff`, `semantic`, `errors`, `stacktrace`, `config`) and picks the matching compressor — typical savings: build output 95%, logs 80–90%, errors 70–90%, diffs 60–80%, stack traces 50–80%, generic code 40–60%, config 30–60%. If you already know the shape of the input, pass `strategy` explicitly to skip detection. If the caller cares about specific signal — a test name, an error code, a file path — pass `preservePatterns` so those regex matches survive compression. Use `response_format: "minimal"` when the parent only needs the compressed payload and `"detailed"` only when the parent explicitly asked for statistics. Never call `auto_optimize` on inputs shorter than ~500 chars — the helper passes them through unchanged and the round-trip is pure overhead.
+
+## AST-based skeleton reads with `smart_file_read`
+
+Reach for `mcp__distill-mcp__smart_file_read` instead of the built-in `Read` whenever the parent needs structural information from a source file in one of the 7 supported languages (TypeScript, JavaScript, Python, Go, Rust, PHP, Swift). Typical savings vs a full-file read: 50–90%. Four modes cover the common cases:
+
+- `skeleton` with `depth: 1–3` when the parent wants an architectural map (all top-level signatures, optionally nested members).
+- `extract` with `target: { type, name }` when the parent needs exactly one function, class, interface, or type definition.
+- `search` with `query: "<substring>"` when the parent is hunting a symbol by partial name and does not know which file holds it yet (combine with `Glob` to narrow the search surface first).
+- `full` when the file is small enough that a raw read is cheaper than the AST pass — fall back to this rather than invent a skeleton for trivial files.
+
+For unsupported languages the tool returns the raw file with a graceful-fallback note, never an error. When the parent needs a multi-file overview, run `smart_file_read` across each path in parallel via `Glob` + a single Bash for-loop rather than sequential calls.
+
+## Summarizing long outputs you cannot pipe through a tool
+
+When the material you have to condense did not come from a tool you can re-pipe (for example, you read a file with `Read` and it turned out to be a 200 KB log dump, or `Bash` emitted a massive stdout you already captured in your turn), do not echo it back in prose. Either (a) feed the raw text back through `auto_optimize` as the `content` argument, or (b) write a structured summary yourself: lead with a 1–3 sentence conclusion, then a bullet list of the concrete findings — error codes, failing test names, file paths, line numbers, deltas — and stop. No restating the request, no framing paragraphs, no apologies for length. The parent called you to shrink the payload; shrink it.
+
+## The `[DISTILL:COMPRESSED]` marker contract
+
+Distill optionally wraps compressed payloads in `[DISTILL:COMPRESSED ratio=X.XX method=<name>]\n<payload>\n[/DISTILL:COMPRESSED]` when the user has set `DISTILL_COMPRESSED_MARKERS=1` in the Distill server environment. `X.XX` is `compressed_size / original_size` clamped to `[0, 1]`. `<name>` is the compressor or mode that produced the payload (`auto`, `logs`, `diff`, `semantic`, `skeleton`, `extract`, `search`, `build+recompressed`, etc.). Pass marker-wrapped regions through to the parent verbatim — do not unwrap, re-summarize, or edit them. The envelope is the anchor that Distill's PreCompact hook (`packages/mcp-server/scripts/precompact-hook.sh`) points at when it instructs Claude Code's compact-summary LLM to keep the region intact through autocompact; splitting or editing it breaks that contract. If the user text you were handed already contains the literal substring `[DISTILL:COMPRESSED`, Distill falls back to the escape tokens `[DISTILL-USER-TEXT:COMPRESSED … ][/DISTILL-USER-TEXT:COMPRESSED]` — forward those untouched too.
+
+## Operating constraints
+
+You are deliberately read-only. `mcp__distill-mcp__code_execute` is in your `disallowedTools` list because this agent must never run arbitrary JavaScript, invoke git-mutating operations, or touch the filesystem outside of read paths. If the parent's request genuinely needs execution (running a build, applying a patch, writing a file), stop and report back in one sentence that the task is out of scope for distill-compressor so the parent can handle it directly or delegate to a different agent. Do the same if the request requires network access, credential handling, or secrets — your toolset is intentionally narrow.
+
+Return short. When you finish, emit only the compressed payload the parent asked for (plus a single preceding line summarizing what you compressed and by how much, if the savings are noteworthy). No meta-narration. No retelling the plan. The whole value proposition of this sub-agent is token density — honour it on every turn.

package/bin/cli.js

@@ -25,16 +25,20 @@ ${COLORS.bright}Commands:${COLORS.reset}
   analyze           Analyze files for token usage
 
 ${COLORS.bright}Setup Options:${COLORS.reset}
-  --claude          Configure Claude Code only
-  --cursor          Configure Cursor only
-  --windsurf        Configure Windsurf only
-  --antigravity     Configure Antigravity only
-  --hooks           Install project hooks (enforces MCP tool usage)
-  --force, -f       Overwrite existing configuration
+  --claude                        Configure Claude Code only
+  --cursor                        Configure Cursor only
+  --windsurf                      Configure Windsurf only
+  --antigravity                   Configure Antigravity only
+  --hooks                         Install project hooks (enforces MCP tool usage)
+  --install-precompact-hook       Install the Distill PreCompact hook into ~/.claude/settings.json
+  --uninstall-precompact-hook     Remove the Distill PreCompact hook from ~/.claude/settings.json
+  --install-agent                 Copy the distill-compressor agent template into ~/.claude/agents/
+  --uninstall-agent               Remove the installed distill-compressor agent template
+  --dry-run                       Print intended changes; do not mutate the filesystem
+  --user-dir=<path>               Override HOME when locating ~/.claude/settings.json (for testing)
+  --force, -f                     Overwrite existing configuration
 
 ${COLORS.bright}Server Options:${COLORS.reset}
-  --lazy            Enable lazy mode (95% token savings, only 2 meta-tools)
-  --mode <mode>     Loading mode: lazy|core|all (default: core)
   --verbose         Enable verbose logging (shows tool calls, timing, tokens)
 
 ${COLORS.bright}Analyze Options:${COLORS.reset}
@@ -48,18 +52,23 @@ ${COLORS.bright}Other Options:${COLORS.reset}
   --help, -h        Show this help message
 
 ${COLORS.bright}Examples:${COLORS.reset}
-  distill-mcp setup                    Interactive setup wizard
-  distill-mcp setup --claude           Configure Claude Code only
-  distill-mcp setup --antigravity      Configure Antigravity only
-  distill-mcp setup --claude --hooks   Configure Claude Code + install hooks
-  distill-mcp setup --hooks            Install hooks only (current project)
-  distill-mcp setup --force            Overwrite existing configurations
-  distill-mcp doctor                   Verify installation
-  distill-mcp serve                    Start MCP server (used by IDE)
-  distill-mcp serve --lazy             Start with lazy mode (95% savings)
-  distill-mcp serve --verbose          Start with verbose logging
-  distill-mcp analyze                  Analyze token usage in codebase
-  distill-mcp analyze -t 5000 --json   Custom threshold, JSON output
+  distill-mcp setup                              Interactive setup wizard
+  distill-mcp setup --claude                     Configure Claude Code only
+  distill-mcp setup --antigravity                Configure Antigravity only
+  distill-mcp setup --claude --hooks             Configure Claude Code + install hooks
+  distill-mcp setup --hooks                      Install hooks only (current project)
+  distill-mcp setup --install-precompact-hook    Wire PreCompact hook into ~/.claude/settings.json
+  distill-mcp setup --install-precompact-hook --dry-run   Preview the JSON diff
+  distill-mcp setup --uninstall-precompact-hook  Remove the Distill PreCompact entry
+  distill-mcp setup --install-agent              Install the distill-compressor subagent template
+  distill-mcp setup --install-agent --force      Overwrite an existing distill-compressor.md
+  distill-mcp setup --uninstall-agent            Remove the installed distill-compressor subagent
+  distill-mcp setup --force                      Overwrite existing configurations
+  distill-mcp doctor                             Verify installation
+  distill-mcp serve                              Start MCP server (used by IDE)
+  distill-mcp serve --verbose                    Start with verbose logging
+  distill-mcp analyze                            Analyze token usage in codebase
+  distill-mcp analyze -t 5000 --json             Custom threshold, JSON output
 
 ${COLORS.bright}Documentation:${COLORS.reset}
   https://distill-mcp.com/docs
@@ -85,23 +94,7 @@ async function main() {
 
   switch (command) {
     case "serve": {
-      // Parse mode option
-      let mode = "core";
-      const modeIndex = args.indexOf("--mode");
-      if (modeIndex !== -1 && args[modeIndex + 1]) {
-        mode = args[modeIndex + 1];
-      } else if (args.includes("--lazy")) {
-        mode = "lazy";
-      } else if (args.includes("--all")) {
-        mode = "all";
-      }
-
-      const config = {
-        verbose: args.includes("--verbose"),
-        mode,
-      };
-
-      await runServer(config);
+      await runServer({ verbose: args.includes("--verbose") });
       break;
     }
 

package/dist/cli/agent.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Custom agent installer for Distill (US-016).
+ *
+ * Extends `distill-mcp setup` with `--install-agent` and `--uninstall-agent`,
+ * copying the shipped `distill-compressor.md` template (US-015) from the
+ * package `assets/agents/` directory into `<userDir>/.claude/agents/`.
+ *
+ * Design invariants mirror the PreCompact hook installer:
+ *   - Idempotent: installing when the target file already matches the template
+ *     is a no-op; re-running produces no filesystem churn.
+ *   - Atomic: overwrites go through `writeAtomic` (tempfile + rename) so a
+ *     SIGTERM mid-install leaves either the pre-state or the post-state,
+ *     never a half-written file.
+ *   - Non-destructive by default: when the target exists and differs from the
+ *     template, we abort with a line-level diff unless the caller passes
+ *     `force: true`.
+ *   - Dry-run surfaces intended actions without touching disk.
+ *
+ * Per project convention (CLAUDE.md: "Manual process.argv parsing in
+ * bin/cli.js"), this module pulls in no new runtime dependencies.
+ */
+export declare const DISTILL_AGENT_FILENAME = "distill-compressor.md";
+export interface AgentOptions {
+    /** Root dir containing `.claude/` (defaults to OS HOME). Used by tests. */
+    userDir?: string;
+    /** Print intended actions without mutating the filesystem. */
+    dryRun?: boolean;
+    /** Overwrite a differing existing file (install only). */
+    force?: boolean;
+}
+export interface AgentResult {
+    action: "installed" | "uninstalled" | "noop" | "dry-run" | "aborted";
+    /** Absolute path to the agent file that was (or would be) touched. */
+    targetPath: string;
+    /** Human-readable message for CLI output. */
+    message: string;
+    /** Non-empty when `action === "aborted"`. */
+    errorCode?: "differs-without-force" | "asset-missing" | "permission-denied" | "unknown";
+}
+/**
+ * Absolute path to the shipped agent template. Resolves from the compiled
+ * `dist/cli/agent.js` (or `src/cli/agent.ts` under vitest) up to the package
+ * root — both layouts are `<pkg>/<dist|src>/cli/` so two `..` hops land at
+ * the root where `assets/agents/` lives.
+ */
+export declare function getAgentAssetPath(): string;
+export declare function getTargetAgentPath(userDir?: string): string;
+/**
+ * Minimal unified-style diff of two strings, used only to describe the
+ * discrepancy when the caller refuses `--force`. Intentionally naive: a line
+ * in `current` that is missing from `template` shows as `-`, and vice versa.
+ * Output is capped so a massive template drift cannot flood the terminal.
+ */
+export declare function summarizeDiff(current: string, template: string, maxLines?: number): string;
+export declare function installAgent(opts?: AgentOptions): AgentResult;
+export declare function uninstallAgent(opts?: AgentOptions): AgentResult;
+//# sourceMappingURL=agent.d.ts.map

package/dist/cli/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/cli/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAaH,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,GAAG,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IACrE,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,uBAAuB,GAAG,eAAe,GAAG,mBAAmB,GAAG,SAAS,CAAC;CACzF;AAMD;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAG1C;AAED,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAG3D;AAMD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,SAAK,GAAG,MAAM,CAgBtF;AAMD,wBAAgB,YAAY,CAAC,IAAI,GAAE,YAAiB,GAAG,WAAW,CAkEjE;AAED,wBAAgB,cAAc,CAAC,IAAI,GAAE,YAAiB,GAAG,WAAW,CAoCnE"}

package/dist/cli/agent.js

@@ -0,0 +1,181 @@
+/**
+ * Custom agent installer for Distill (US-016).
+ *
+ * Extends `distill-mcp setup` with `--install-agent` and `--uninstall-agent`,
+ * copying the shipped `distill-compressor.md` template (US-015) from the
+ * package `assets/agents/` directory into `<userDir>/.claude/agents/`.
+ *
+ * Design invariants mirror the PreCompact hook installer:
+ *   - Idempotent: installing when the target file already matches the template
+ *     is a no-op; re-running produces no filesystem churn.
+ *   - Atomic: overwrites go through `writeAtomic` (tempfile + rename) so a
+ *     SIGTERM mid-install leaves either the pre-state or the post-state,
+ *     never a half-written file.
+ *   - Non-destructive by default: when the target exists and differs from the
+ *     template, we abort with a line-level diff unless the caller passes
+ *     `force: true`.
+ *   - Dry-run surfaces intended actions without touching disk.
+ *
+ * Per project convention (CLAUDE.md: "Manual process.argv parsing in
+ * bin/cli.js"), this module pulls in no new runtime dependencies.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToLocalPath } from "./utils.js";
+import { writeAtomic } from "./precompact.js";
+// ---------------------------------------------------------------------------
+// Constants & types
+// ---------------------------------------------------------------------------
+export const DISTILL_AGENT_FILENAME = "distill-compressor.md";
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+/**
+ * Absolute path to the shipped agent template. Resolves from the compiled
+ * `dist/cli/agent.js` (or `src/cli/agent.ts` under vitest) up to the package
+ * root — both layouts are `<pkg>/<dist|src>/cli/` so two `..` hops land at
+ * the root where `assets/agents/` lives.
+ */
+export function getAgentAssetPath() {
+    const here = path.dirname(fileURLToLocalPath(import.meta.url));
+    return path.resolve(here, "..", "..", "assets", "agents", DISTILL_AGENT_FILENAME);
+}
+export function getTargetAgentPath(userDir) {
+    const root = userDir ?? os.homedir();
+    return path.join(root, ".claude", "agents", DISTILL_AGENT_FILENAME);
+}
+// ---------------------------------------------------------------------------
+// Diff helper (line-level, zero deps)
+// ---------------------------------------------------------------------------
+/**
+ * Minimal unified-style diff of two strings, used only to describe the
+ * discrepancy when the caller refuses `--force`. Intentionally naive: a line
+ * in `current` that is missing from `template` shows as `-`, and vice versa.
+ * Output is capped so a massive template drift cannot flood the terminal.
+ */
+export function summarizeDiff(current, template, maxLines = 40) {
+    const a = current.split("\n");
+    const b = template.split("\n");
+    const setA = new Set(a);
+    const setB = new Set(b);
+    const lines = [];
+    for (const l of a) {
+        if (!setB.has(l))
+            lines.push(`- ${l}`);
+    }
+    for (const l of b) {
+        if (!setA.has(l))
+            lines.push(`+ ${l}`);
+    }
+    if (lines.length === 0)
+        return "(no line-level differences — only ordering or whitespace changes)";
+    if (lines.length <= maxLines)
+        return lines.join("\n");
+    const head = lines.slice(0, maxLines);
+    return head.join("\n") + `\n… (${lines.length - maxLines} more diff lines omitted)`;
+}
+// ---------------------------------------------------------------------------
+// Public install / uninstall
+// ---------------------------------------------------------------------------
+export function installAgent(opts = {}) {
+    const targetPath = getTargetAgentPath(opts.userDir);
+    const assetPath = getAgentAssetPath();
+    if (!fs.existsSync(assetPath)) {
+        return {
+            action: "aborted",
+            targetPath,
+            message: `Aborted: agent template not found at ${assetPath}. The distill-mcp package may be corrupted — reinstall it.`,
+            errorCode: "asset-missing",
+        };
+    }
+    const templateContent = fs.readFileSync(assetPath, "utf-8");
+    const targetExists = fs.existsSync(targetPath);
+    if (targetExists) {
+        const existingContent = fs.readFileSync(targetPath, "utf-8");
+        if (existingContent === templateContent) {
+            return {
+                action: "noop",
+                targetPath,
+                message: `Agent already installed at ${targetPath} (content matches; no change).`,
+            };
+        }
+        if (!opts.force) {
+            const diff = summarizeDiff(existingContent, templateContent);
+            return {
+                action: "aborted",
+                targetPath,
+                message: `Aborted: ${targetPath} exists and differs from the shipped template.\n` +
+                    `Pass --force to overwrite, or --uninstall-agent first.\n` +
+                    `Diff (existing → template):\n${diff}`,
+                errorCode: "differs-without-force",
+            };
+        }
+    }
+    if (opts.dryRun) {
+        const verb = targetExists ? "overwrite (differs, --force set)" : "create";
+        return {
+            action: "dry-run",
+            targetPath,
+            message: `[dry-run] Would ${verb} ${targetPath} (${templateContent.length} bytes from ${assetPath}).`,
+        };
+    }
+    try {
+        writeAtomic(targetPath, templateContent, 0o644);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            action: "aborted",
+            targetPath,
+            message: `Failed to write ${targetPath}: ${message}`,
+            errorCode: isPermissionError(err) ? "permission-denied" : "unknown",
+        };
+    }
+    const verb = targetExists ? "Overwrote" : "Installed";
+    return {
+        action: "installed",
+        targetPath,
+        message: `${verb} distill-compressor agent → ${targetPath}.`,
+    };
+}
+export function uninstallAgent(opts = {}) {
+    const targetPath = getTargetAgentPath(opts.userDir);
+    if (!fs.existsSync(targetPath)) {
+        return {
+            action: "noop",
+            targetPath,
+            message: `No distill-compressor agent at ${targetPath} — nothing to uninstall.`,
+        };
+    }
+    if (opts.dryRun) {
+        return {
+            action: "dry-run",
+            targetPath,
+            message: `[dry-run] Would delete ${targetPath}.`,
+        };
+    }
+    try {
+        fs.unlinkSync(targetPath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            action: "aborted",
+            targetPath,
+            message: `Failed to delete ${targetPath}: ${message}`,
+            errorCode: isPermissionError(err) ? "permission-denied" : "unknown",
+        };
+    }
+    return {
+        action: "uninstalled",
+        targetPath,
+        message: `Uninstalled distill-compressor agent from ${targetPath}.`,
+    };
+}
+function isPermissionError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const code = err.code;
+    return code === "EACCES" || code === "EPERM";
+}

package/dist/cli/hooks.d.ts

@@ -11,4 +11,13 @@ export interface InstallHooksOptions {
     force?: boolean;
 }
 export declare function installHooks(options?: InstallHooksOptions): Promise<boolean>;
+export interface UpdateClaudeMdOptions {
+    projectDir?: string;
+    force?: boolean;
+}
+/**
+ * Updates CLAUDE.md with Distill MCP directives.
+ * Returns true if updated, false if CLAUDE.md doesn't exist.
+ */
+export declare function updateClaudeMd(options?: UpdateClaudeMdOptions): boolean;
 //# sourceMappingURL=hooks.d.ts.map

package/dist/cli/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/cli/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA+JH,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,OAAO,CAAC,CAqGtF"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/cli/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgRH,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAsB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,OAAO,CAAC,CAqGtF;AAgBD,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CA0D3E"}

package/dist/cli/hooks.js

@@ -6,10 +6,120 @@
  * - PostToolUse: Reminds to use auto_optimize for large Bash outputs
  * - UserPromptSubmit: Injects MCP tool reminders
  */
-import { existsSync, mkdirSync, writeFileSync, chmodSync } from "fs";
+import { existsSync, mkdirSync, writeFileSync, chmodSync, readFileSync } from "fs";
 import { join } from "path";
 import { success, warn, info, error, log, COLORS, readJSONFile, writeJSONFile } from "./utils.js";
 // ============================================================================
+// CLAUDE.md Content
+// ============================================================================
+const CLAUDE_MD_SECTION_START = "## Directives d'utilisation des outils MCP";
+const CLAUDE_MD_SECTION_END = "<!-- END DISTILL -->";
+const CLAUDE_MD_CONTENT = `## Directives d'utilisation des outils MCP
+
+Utilisez les outils Distill MCP pour des opérations économes en tokens :
+
+### Règle 1 : Lecture intelligente de fichiers
+
+Lors de la lecture de fichiers source pour **exploration ou compréhension** :
+
+\`\`\`
+mcp__distill__smart_file_read filePath="path/to/file.ts"
+\`\`\`
+
+**Quand utiliser Read natif à la place :**
+- Avant d'éditer un fichier (Edit nécessite Read d'abord)
+- Fichiers de configuration : \`.json\`, \`.yaml\`, \`.toml\`, \`.md\`, \`.env\`
+
+### Règle 2 : Compresser les sorties volumineuses
+
+Après les commandes Bash qui produisent une sortie volumineuse (>500 caractères) :
+
+\`\`\`
+mcp__distill__auto_optimize content="<collez la sortie volumineuse>"
+\`\`\`
+
+### Règle 3 : SDK d'exécution de code pour les opérations complexes
+
+Pour les opérations multi-étapes, utilisez \`code_execute\` au lieu de plusieurs appels d'outils (**98% d'économie de tokens**) :
+
+\`\`\`
+mcp__distill__code_execute code="<code typescript>"
+\`\`\`
+
+**API du SDK (\`ctx\`) :**
+
+*Compression :*
+- \`ctx.compress.auto(content, hint?)\` - Détection auto et compression
+- \`ctx.compress.logs(logs)\` - Résumer les logs
+- \`ctx.compress.diff(diff)\` - Compresser les git diff
+- \`ctx.compress.semantic(content, ratio?)\` - Compression TF-IDF
+
+*Code :*
+- \`ctx.code.parse(content, lang)\` - Parser en structure AST
+- \`ctx.code.extract(content, lang, {type, name})\` - Extraire un élément
+- \`ctx.code.skeleton(content, lang)\` - Obtenir les signatures uniquement
+
+*Fichiers :*
+- \`ctx.files.read(path)\` - Lire le contenu d'un fichier
+- \`ctx.files.exists(path)\` - Vérifier si un fichier existe
+- \`ctx.files.glob(pattern)\` - Trouver des fichiers par pattern
+
+*Git :*
+- \`ctx.git.diff(ref?)\` - Obtenir le diff git
+- \`ctx.git.log(limit?)\` - Historique des commits
+- \`ctx.git.status()\` - Statut du repo
+- \`ctx.git.branch()\` - Info sur les branches
+- \`ctx.git.blame(file, line?)\` - Git blame d'un fichier
+
+*Recherche :*
+- \`ctx.search.grep(pattern, glob?)\` - Rechercher un pattern dans les fichiers
+- \`ctx.search.symbols(query, glob?)\` - Rechercher des symboles (fonctions, classes)
+- \`ctx.search.files(pattern)\` - Rechercher des fichiers par pattern
+- \`ctx.search.references(symbol, glob?)\` - Trouver les références d'un symbole
+
+*Analyse :*
+- \`ctx.analyze.dependencies(file)\` - Analyser les imports/exports
+- \`ctx.analyze.callGraph(fn, file, depth?)\` - Construire le graphe d'appels
+- \`ctx.analyze.exports(file)\` - Obtenir les exports d'un fichier
+- \`ctx.analyze.structure(dir?, depth?)\` - Structure du répertoire avec analyse
+
+*Utilitaires :*
+- \`ctx.utils.countTokens(text)\` - Compter les tokens
+- \`ctx.utils.detectType(content)\` - Détecter le type de contenu
+- \`ctx.utils.detectLanguage(path)\` - Détecter le langage depuis le chemin
+
+**Exemples :**
+
+\`\`\`typescript
+// Obtenir les squelettes de tous les fichiers TypeScript
+const files = ctx.files.glob("src/**/*.ts").slice(0, 5);
+return files.map(f => ({
+  file: f,
+  skeleton: ctx.code.skeleton(ctx.files.read(f), "typescript")
+}));
+
+// Compresser et analyser les logs
+const logs = ctx.files.read("server.log");
+return ctx.compress.logs(logs);
+
+// Extraire une fonction spécifique
+const content = ctx.files.read("src/api.ts");
+return ctx.code.extract(content, "typescript", { type: "function", name: "handleRequest" });
+\`\`\`
+
+### Référence rapide
+
+| Action | Utiliser |
+|--------|----------|
+| Lire du code pour exploration | \`mcp__distill__smart_file_read filePath="file.ts"\` |
+| Obtenir une fonction/classe | \`mcp__distill__smart_file_read filePath="file.ts" target={"type":"function","name":"myFunc"}\` |
+| Compresser les erreurs de build | \`mcp__distill__auto_optimize content="..."\` |
+| Résumer les logs | \`mcp__distill__auto_optimize content="..." strategy="logs"\` |
+| Opérations multi-étapes | \`mcp__distill__code_execute code="return ctx.files.glob('src/**/*.ts')"\` |
+| Avant d'éditer | Utiliser l'outil natif \`Read\` |
+
+<!-- END DISTILL -->`;
+// ============================================================================
 // Hook Script Templates
 // ============================================================================
 const PRE_READ_CHECK_SCRIPT = `#!/bin/bash
@@ -66,7 +176,7 @@ if echo "$TOOL_RESPONSE" | grep -qiE "(error TS|warning TS|error\\[E|npm ERR|ERR
 fi
 
 if echo "$TOOL_RESPONSE" | grep -qiE "(\\[INFO\\]|\\[ERROR\\]|\\[WARN\\]|\\[DEBUG\\]|[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2})"; then
-  echo '{"systemMessage": "TIP: Large log output detected. Use mcp__distill__summarize_logs to compress (80-90% reduction)."}'
+  echo '{"systemMessage": "TIP: Large log output detected. Use mcp__distill__auto_optimize with strategy=logs to compress (80-90% reduction)."}'
   exit 0
 fi
 
@@ -82,8 +192,8 @@ cat << 'EOF'
 <user-prompt-submit-hook>
 DISTILL REMINDER: Use MCP tools for token optimization:
 - Code files: mcp__distill__smart_file_read (50-70% savings vs Read)
-- Build/test output: mcp__distill__auto_optimize
-- Session stats: mcp__distill__session_stats
+- Build/test output: mcp__distill__auto_optimize (95%+ reduction)
+- Multi-step ops: mcp__distill__code_execute (98% savings via SDK)
 </user-prompt-submit-hook>
 EOF
 exit 0
@@ -209,7 +319,7 @@ export async function installHooks(options = {}) {
         log(`\n${COLORS.dim}Token savings:${COLORS.reset}`);
         log(`  • smart_file_read:  50-70% reduction vs Read`);
         log(`  • auto_optimize:    95%+ reduction on build errors`);
-        log(`  • summarize_logs:   80-90% reduction on logs\n`);
+        log(`  • auto_optimize:    80-90% reduction on logs\n`);
         return true;
     }
     else {
@@ -227,3 +337,64 @@ function checkJqInstalled() {
         return false;
     }
 }
+/**
+ * Updates CLAUDE.md with Distill MCP directives.
+ * Returns true if updated, false if CLAUDE.md doesn't exist.
+ */
+export function updateClaudeMd(options = {}) {
+    const projectDir = options.projectDir || process.cwd();
+    const force = options.force || false;
+    const claudeMdPath = join(projectDir, "CLAUDE.md");
+    // Check if CLAUDE.md exists
+    if (!existsSync(claudeMdPath)) {
+        warn("CLAUDE.md not found.");
+        log(`\n${COLORS.dim}To create CLAUDE.md, run in Claude Code:${COLORS.reset}`);
+        log(`  ${COLORS.cyan}/init${COLORS.reset}`);
+        log(`\nThen run setup again to add Distill directives.\n`);
+        return false;
+    }
+    // Read existing content
+    let content;
+    try {
+        content = readFileSync(claudeMdPath, "utf-8");
+    }
+    catch (err) {
+        error(`Failed to read CLAUDE.md: ${err}`);
+        return false;
+    }
+    // Check if Distill section already exists
+    const sectionStartIndex = content.indexOf(CLAUDE_MD_SECTION_START);
+    const sectionEndIndex = content.indexOf(CLAUDE_MD_SECTION_END);
+    let newContent;
+    if (sectionStartIndex !== -1 && sectionEndIndex !== -1) {
+        // Section exists - replace it
+        if (!force) {
+            info("Distill directives already present in CLAUDE.md. Use --force to update.");
+            return true;
+        }
+        // Replace existing section
+        const beforeSection = content.substring(0, sectionStartIndex).trimEnd();
+        const afterSection = content.substring(sectionEndIndex + CLAUDE_MD_SECTION_END.length).trimStart();
+        newContent = beforeSection + "\n\n" + CLAUDE_MD_CONTENT + (afterSection ? "\n\n" + afterSection : "\n");
+    }
+    else if (sectionStartIndex !== -1) {
+        // Partial section (start found but no end marker) - warn and skip
+        warn("Found partial Distill section in CLAUDE.md without end marker.");
+        log(`Add ${COLORS.dim}${CLAUDE_MD_SECTION_END}${COLORS.reset} at the end of the section, then run setup again.`);
+        return false;
+    }
+    else {
+        // No section exists - append
+        newContent = content.trimEnd() + "\n\n" + CLAUDE_MD_CONTENT + "\n";
+    }
+    // Write updated content
+    try {
+        writeFileSync(claudeMdPath, newContent, "utf-8");
+        success("Updated CLAUDE.md with Distill directives");
+        return true;
+    }
+    catch (err) {
+        error(`Failed to write CLAUDE.md: ${err}`);
+        return false;
+    }
+}

package/dist/cli/index.d.ts

@@ -1,5 +1,5 @@
 export { setup, parseSetupArgs, type SetupOptions } from "./setup.js";
 export { doctor } from "./doctor.js";
-export { installHooks, type InstallHooksOptions } from "./hooks.js";
+export { installHooks, updateClaudeMd, type InstallHooksOptions, type UpdateClaudeMdOptions } from "./hooks.js";
 export * from "./utils.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACpE,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,KAAK,mBAAmB,EAAE,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAChH,cAAc,YAAY,CAAC"}

package/dist/cli/index.js

@@ -1,4 +1,4 @@
 export { setup, parseSetupArgs } from "./setup.js";
 export { doctor } from "./doctor.js";
-export { installHooks } from "./hooks.js";
+export { installHooks, updateClaudeMd } from "./hooks.js";
 export * from "./utils.js";