composto-ai 0.6.0 → 0.7.0

package/README.md

@@ -1,24 +1,23 @@
 # Composto
 
-**Send meaning to your LLM, not code. 89% fewer tokens, same understanding.**
+**Causal memory layer for coding agents. Catches the bug your agent is about to reintroduce.**
 
-Composto parses your code into an AST, classifies every node by importance, and drops the noise. Your LLM gets the signal — function signatures, control flow, dependencies — without the braces, semicolons, and string literals it already knows.
+Composto is a repo-local graph of your git history that your AI coding agent consults before every edit. When a file was reverted recently, has a fix cluster in its history, or was last touched by someone who left the team, Composto surfaces that signal as in-context guidance before the agent writes the code. Hook-enforced on Claude Code, Cursor, and Gemini CLI. Local-first, MIT.
 
 ```
-Raw source:  3,782 tokens    →    Composto IR:  663 tokens (82.5% savings)
-
-USE:[../types.js, ./structure.js, ./fingerprint.js, ./health.js]
-OUT FN:generateL0(code: string, filePath: string)
-    RET `${filePath}\n${declarations.join("\n")}`
-OUT ASYNC FN:generateL1(code: string, filePath: string, health: HealthAnnotation...)
-    IF:health → RET annotateIR(ir, health)
-    RET ir
-OUT FN:generateLayer(layer: IRLayer, options: {...})
-    SWITCH:layer
-        CASE:"L0" → RET generateL0(...)
-        CASE:"L1" → RET generateL1(...)
-        CASE:"L2" → RET generateL2(...)
-        CASE:"L3" → RET options.code
+$ composto impact src/memory/signals/hotspot.ts
+
+verdict:    medium
+score:      0.52
+confidence: 0.50
+signals:
+  revert_match       ■■■■■■■■■■ strength=1.00 precision=1.00
+  hotspot            ■          strength=0.10 precision=0.54
+  fix_ratio          ■          strength=0.07 precision=0.54
+  author_churn       ·          strength=0.00 precision=0.16
+
+# This file was touched by a Revert commit in history.
+# blastradius remembers. Your LLM couldn't.
 ```
 
 ---
@@ -29,21 +28,35 @@ OUT FN:generateLayer(layer: IRLayer, options: {...})
 # Install
 npm install -g composto-ai
 
-# See how much you save
-composto benchmark .
+# One-command setup, wires MCP + PreToolUse hook into your AI client
+cd your-project
+composto init --client=claude-code     # or cursor, or gemini-cli
 
-# Generate IR for a file
-composto ir src/app.ts
+# Restart your AI client. Hook fires on every Edit / Write / MultiEdit.
+# On medium|high|unknown verdicts, the agent gets a composto_blastradius
+# block in context before it acts. Passthrough on low.
 
-# Smart context within a token budget
-composto context src/ --budget 2000
+# Observe
+composto stats              # hook invocations, verdict distribution, latency
+composto stats --disable    # local-only opt-out (writes .composto/telemetry-disabled)
 
-# Historical blast radius for a file (beta, feature-flagged)
-COMPOSTO_BLASTRADIUS=1 composto index
+# Query on demand
 composto impact src/auth/login.ts
-composto index --status
+composto index --status     # diagnostics: schema, freshness, calibration
 ```
 
+### Also in the box: AST compression tools
+
+Composto also ships a tree-sitter based AST compressor (about 89% token savings) and a smart context packer for bug-fix tasks. These are separate from the causal layer but live in the same binary.
+
+```bash
+composto ir src/app.ts                 # compress a file to IR (L0/L1/L2/L3)
+composto context src/ --budget 2000    # smart context within a token budget
+composto benchmark .                   # see compression stats
+```
+
+See the [IR Layers](#ir-layers), [Health-Aware IR](#health-aware-ir), and [Context Budget](#context-budget) sections below for details.
+
 ### MCP plugin (Claude Code, Cursor, Claude Desktop)
 
 The MCP server is bundled inside `composto-ai`. Install the package globally first, then register the server with your client:
@@ -175,7 +188,7 @@ composto index --status        # diagnostics: schema, freshness, calibration
 
 ---
 
-## BlastRadius (beta)
+## BlastRadius
 
 Beyond compression, Composto indexes your repo's git history into a local SQLite graph and exposes it as a queryable risk surface. Before your agent edits a file, it can ask: *"has this region been reverted? who fixed the last similar bug? is the last author still around?"* — signals no LLM can infer from current code alone.
 

package/dist/index.js

@@ -3062,30 +3062,45 @@ function writeCursorHooks(projectPath, result) {
   if (existed) result.merged.push(relPath);
   else result.written.push(relPath);
 }
-function initCursor(projectPath, result) {
-  writeJsonMerged(
-    join7(projectPath, ".cursor", "mcp.json"),
-    { mcpServers: { composto: { command: "composto-mcp" } } },
-    result,
-    ".cursor/mcp.json"
-  );
-  writeFileSkipIfExists(
-    join7(projectPath, ".cursor", "rules", "composto.mdc"),
-    CURSOR_RULES_MDC,
-    result,
-    ".cursor/rules/composto.mdc"
-  );
+function initCursor(projectPath, result, options) {
+  if (options.withMcp) {
+    writeJsonMerged(
+      join7(projectPath, ".cursor", "mcp.json"),
+      {
+        mcpServers: {
+          composto: {
+            command: "composto-mcp",
+            env: { COMPOSTO_BLASTRADIUS: "1" }
+          }
+        }
+      },
+      result,
+      ".cursor/mcp.json"
+    );
+  }
+  if (options.withRules) {
+    writeFileSkipIfExists(
+      join7(projectPath, ".cursor", "rules", "composto.mdc"),
+      CURSOR_RULES_MDC,
+      result,
+      ".cursor/rules/composto.mdc"
+    );
+  }
   writeCursorHooks(projectPath, result);
 }
-function initClaudeCode(projectPath, result) {
+function initClaudeCode(projectPath, result, options) {
   const settingsPath = join7(projectPath, ".claude", "settings.json");
   const relPath = ".claude/settings.json";
   const existed = existsSync4(settingsPath);
   const existing = readJsonIfExists(settingsPath);
-  const mcpServers = {
-    ...existing.mcpServers ?? {},
-    composto: { command: "composto-mcp" }
-  };
+  const baseExistingMcp = existing.mcpServers ?? {};
+  const mcpServers = options.withMcp ? {
+    ...baseExistingMcp,
+    composto: {
+      command: "composto-mcp",
+      env: { COMPOSTO_BLASTRADIUS: "1" }
+    }
+  } : baseExistingMcp;
   const compostoHookEntry = {
     matcher: "Edit|Write|MultiEdit",
     hooks: [
@@ -3100,9 +3115,11 @@ function initClaudeCode(projectPath, result) {
   );
   const merged = {
     ...existing,
-    mcpServers,
     hooks: { ...existingHooks, PreToolUse: preToolUse }
   };
+  if (Object.keys(mcpServers).length > 0) {
+    merged.mcpServers = mcpServers;
+  }
   ensureDir(settingsPath);
   writeFileSync2(settingsPath, JSON.stringify(merged, null, 2) + "\n");
   if (existed) result.merged.push(relPath);
@@ -3114,10 +3131,14 @@ function initGeminiCli(_projectPath, result, options) {
   try {
     const existed = existsSync4(settingsPath);
     const existing = readJsonIfExists(settingsPath);
-    const mcpServers = {
-      ...existing.mcpServers ?? {},
-      composto: { command: "composto-mcp" }
-    };
+    const baseExistingMcp = existing.mcpServers ?? {};
+    const mcpServers = options.withMcp ? {
+      ...baseExistingMcp,
+      composto: {
+        command: "composto-mcp",
+        env: { COMPOSTO_BLASTRADIUS: "1" }
+      }
+    } : baseExistingMcp;
     const compostoHookEntry = {
       matcher: "edit_file|write_file|replace",
       hooks: [
@@ -3132,9 +3153,11 @@ function initGeminiCli(_projectPath, result, options) {
     );
     const merged = {
       ...existing,
-      mcpServers,
       hooks: { ...existingHooks, BeforeTool: beforeTool }
     };
+    if (Object.keys(mcpServers).length > 0) {
+      merged.mcpServers = mcpServers;
+    }
     ensureDir(settingsPath);
     writeFileSync2(settingsPath, JSON.stringify(merged, null, 2) + "\n");
     if (existed) result.merged.push(relPath);
@@ -3147,9 +3170,9 @@ function initGeminiCli(_projectPath, result, options) {
 function runInit(projectPath, options) {
   const client = options.client ?? "cursor";
   const result = { client, written: [], skipped: [], merged: [] };
-  if (client === "claude-code") initClaudeCode(projectPath, result);
+  if (client === "claude-code") initClaudeCode(projectPath, result, options);
   else if (client === "gemini-cli") initGeminiCli(projectPath, result, options);
-  else initCursor(projectPath, result);
+  else initCursor(projectPath, result, options);
   return result;
 }
 
@@ -3662,7 +3685,13 @@ switch (command) {
       console.error(`Unknown --client=${clientArg}. Valid: ${valid.join(", ")}`);
       process.exit(1);
     }
-    const result = runInit(resolve2("."), { client: clientArg });
+    const withRules = args.includes("--with-rules");
+    const withMcp = args.includes("--with-mcp");
+    const result = runInit(resolve2("."), {
+      client: clientArg,
+      withRules,
+      withMcp
+    });
     console.log(`composto init \u2014 configured for ${result.client}
 `);
     for (const f of result.written) console.log(`  wrote   ${f}`);
@@ -3740,8 +3769,10 @@ switch (command) {
     console.log("  impact <file>                         Show historical blast radius for a file");
     console.log("  index [--since=YYYY-MM-DD]            Build or refresh the memory index (--since bounds work for huge repos)");
     console.log("  index --status                        Show memory index diagnostics");
-    console.log("  init [--client=<name>]                Configure Composto MCP + hooks for an AI client");
-    console.log("                                          (clients: cursor, claude-code, gemini-cli)");
+    console.log("  init [--client=<name>] [--with-mcp] [--with-rules]");
+    console.log("                                        Lean Hook init (clients: cursor, claude-code, gemini-cli)");
+    console.log("                                          --with-mcp   register the composto MCP server (5 tools)");
+    console.log("                                          --with-rules write .cursor/rules/composto.mdc (cursor only)");
     console.log("  hook <platform> <event>               Run BlastRadius hook (reads tool JSON from stdin)");
     console.log("  stats [--json] [--disable]            Show hook telemetry (last 7d); --disable opts out");
     console.log("  version                               Show version");

package/dist/mcp/server.js

@@ -2387,7 +2387,7 @@ var server = new McpServer({
 });
 server.tool(
   "composto_ir",
-  "Generate compressed IR (Intermediate Representation) for a source file. Uses AST parsing to keep function signatures, control flow, and dependencies while dropping 89% of noise tokens. Use this instead of reading raw files when you need to understand what a file does.",
+  "Compressed AST-based IR for a file. ~89% fewer tokens than raw read.",
   {
     file: z.string().describe("Path to the source file"),
     layer: z.enum(["L0", "L1", "L2", "L3"]).default("L1").describe("L0=structure only, L1=full IR (default), L2=delta context, L3=raw source")
@@ -2423,7 +2423,7 @@ ${result}` }]
 );
 server.tool(
   "composto_benchmark",
-  "Benchmark how much Composto saves across a directory. Shows per-file token savings comparing raw code vs compressed IR.",
+  "Per-file token-savings benchmark across a directory.",
   {
     path: z.string().default(".").describe("Directory to benchmark")
   },
@@ -2455,7 +2455,7 @@ server.tool(
 );
 server.tool(
   "composto_context",
-  "Pack maximum code context into a token budget. When target symbol is provided, its file is included as raw code (L3) while surrounding files get compressed IR. Perfect for 'fix this bug in X' or 'why does X return wrong value' \u2014 LLM sees exact code of target plus compressed context. Without target, hotspot files get L1, rest get L0.",
+  "Pack code into a token budget; target raw, neighbors as IR.",
   {
     path: z.string().default(".").describe("Directory to pack"),
     budget: z.number().default(4e3).describe("Maximum tokens to use"),
@@ -2518,7 +2518,7 @@ Files: ${parts.join(", ")}`);
 );
 server.tool(
   "composto_scan",
-  "Scan codebase for security issues (hardcoded secrets, API keys) and debug artifacts (console.log). Zero token cost \u2014 pure local analysis.",
+  "Scan for hardcoded secrets and debug artifacts. Local-only.",
   {
     path: z.string().default(".").describe("Directory to scan")
   },
@@ -2551,7 +2551,7 @@ server.tool(
 );
 server.tool(
   "composto_blastradius",
-  'Predict the historical blast radius of a code change before applying it. Returns a risk verdict (low/medium/high/unknown), confidence, and the git-derived signals behind it (revert history, hotspots, fix ratio, coverage decline, ownership churn). Call BEFORE proposing significant edits to files with non-trivial history. Honest about uncertainty \u2014 returns "unknown" when confidence is low instead of guessing. Degraded modes (empty repo, shallow clone, indexing) are explicit in the `status` field.',
+  "Risk verdict (low/medium/high/unknown) for editing a file, from git history.",
   {
     file: z.string().describe("Repo-relative path of the file the agent intends to modify."),
     intent: z.enum(["refactor", "bugfix", "feature", "test", "docs", "unknown"]).default("unknown").optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "composto-ai",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Proactive AI team companion — less tokens, more insight",
   "type": "module",
   "bin": {