pi-lean-ctx 3.4.6 → 3.5.0

package/README.md

@@ -1,6 +1,9 @@
 # pi-lean-ctx
 
-[Pi Coding Agent](https://github.com/badlogic/pi-mono) extension with **first-class MCP support** — routes all tool output through [lean-ctx](https://leanctx.com) for **60–90% token savings** and exposes **25+ MCP tools** natively in Pi.
+CLI-first [Pi Coding Agent](https://github.com/badlogic/pi-mono) extension that routes Pi’s built-in tools through [lean-ctx](https://leanctx.com) for **60–90% token savings**.
+
+- **Default**: CLI-only (no MCP required)
+- **Optional**: enable MCP tools (`LEAN_CTX_PI_ENABLE_MCP=1`) or run `lean-ctx init --agent pi --mode mcp`
 
 ## What it does
 
@@ -10,15 +13,27 @@ Overrides Pi's built-in tools to route them through `lean-ctx`:
 
 | Tool | Compression |
 |------|------------|
-| `bash` | All shell commands compressed via lean-ctx's 90+ patterns |
+| `bash` | All shell commands compressed via lean-ctx's 95+ patterns |
 | `read` | Smart mode selection (full/map/signatures) based on file type and size |
 | `grep` | Results grouped and compressed via ripgrep + lean-ctx |
 | `find` | File listings compressed and .gitignore-aware |
 | `ls` | Directory output compressed |
 
-### MCP Tools (Embedded Bridge)
+### Direct lean-ctx CLI tool
+
+The extension registers a `lean_ctx` tool that runs `lean-ctx` directly (no nested compression).
+Use it for commands like:
+
+- `lean-ctx overview`
+- `lean-ctx session …`
+- `lean-ctx knowledge …`
+- `lean-ctx gain` / `lean-ctx stats`
+- `lean-ctx index …`
+
+### Optional MCP Tools (Embedded Bridge)
 
-Additionally, pi-lean-ctx spawns lean-ctx as an MCP server and registers all advanced tools directly in Pi:
+By default, pi-lean-ctx does **not** start an MCP server. If enabled, it spawns `lean-ctx` as an MCP
+server and registers advanced tools directly in Pi:
 
 | Tool | Purpose |
 |------|---------|
@@ -45,7 +60,7 @@ Additionally, pi-lean-ctx spawns lean-ctx as an MCP server and registers all adv
 | `ctx_cache` | Cache management |
 | `ctx_execute` | Direct command execution |
 
-These MCP tools are the same ones available in Cursor, Claude Code, VS Code, and all other supported editors — now first-class in Pi.
+If you don’t want MCP: keep it disabled and use the CLI overrides + `lean_ctx` tool only.
 
 ## Install
 
@@ -72,9 +87,10 @@ lean-ctx init --agent pi
 
 These tools invoke the `lean-ctx` binary via CLI with `LEAN_CTX_COMPRESS=1`. The output is parsed for compression stats and displayed with a token savings footer.
 
-### MCP bridge (all other tools)
+### Optional MCP bridge (all other tools)
 
-On startup, pi-lean-ctx spawns the `lean-ctx` binary as an MCP server (JSON-RPC over stdio). It discovers available tools via `list_tools`, filters out those already covered by CLI overrides, and registers the rest as native Pi tools.
+If you enable the MCP bridge, pi-lean-ctx spawns the `lean-ctx` binary as an MCP server (JSON-RPC over stdio).
+It discovers available tools via `list_tools`, filters out those already covered by CLI overrides, and registers the rest as native Pi tools.
 
 If `lean-ctx` is already configured as an MCP server via [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) in `~/.pi/agent/mcp.json`, the embedded bridge is skipped to avoid duplicate tools.
 
@@ -82,6 +98,21 @@ If `lean-ctx` is already configured as an MCP server via [pi-mcp-adapter](https:
 
 If the MCP server process crashes, the bridge automatically reconnects (up to 3 attempts with exponential backoff). If reconnection fails, CLI-based tools continue working normally — only the advanced MCP tools become unavailable.
 
+## Enabling MCP (optional)
+
+Set an environment variable and restart Pi:
+
+```bash
+export LEAN_CTX_PI_ENABLE_MCP=1
+pi
+```
+
+Or configure MCP via `lean-ctx init`:
+
+```bash
+lean-ctx init --agent pi --mode mcp
+```
+
 ## pi-mcp-adapter compatibility
 
 If you prefer using [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) to manage your MCP servers, lean-ctx integrates automatically:
@@ -134,7 +165,7 @@ The `read` tool automatically selects the optimal lean-ctx mode:
 
 Use `/lean-ctx` in Pi to check:
 - Which binary is being used
-- MCP bridge status (embedded vs. adapter, connected/disconnected)
+- MCP bridge status (disabled / embedded / adapter)
 - Number and names of registered MCP tools
 
 ## Disabling specific tools

package/extensions/index.ts

@@ -63,12 +63,28 @@ const grepSchema = Type.Object({
   limit: Type.Optional(Type.Number({ description: "Maximum number of matches (default: 100)" })),
 });
 
+const leanCtxSchema = Type.Object({
+  args: Type.Array(
+    Type.String({
+      description:
+        "Arguments after 'lean-ctx'. Example: ['overview'] or ['knowledge','recall','Pi']",
+    }),
+  ),
+});
+
 function shellQuote(value: string): string {
   if (!value) return "''";
   if (/^[A-Za-z0-9_./=:@,+%^-]+$/.test(value)) return value;
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+function envFlag(name: string): boolean {
+  const raw = process.env[name];
+  if (!raw) return false;
+  const v = raw.trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+
 function resolveBinary(): string {
   const envBin = process.env.LEAN_CTX_BIN;
   if (envBin && existsSync(envBin)) return envBin;
@@ -259,7 +275,7 @@ async function execLeanCtx(pi: ExtensionAPI, args: string[]) {
   return result.stdout;
 }
 
-export default function (pi: ExtensionAPI) {
+export default async function (pi: ExtensionAPI) {
   const baseBashTool = createBashToolDefinition(process.cwd(), {
     spawnHook: ({ command, cwd, env }) => {
       const bin = resolveBinary();
@@ -490,12 +506,33 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
-  const mcpBridge = new McpBridge(resolveBinary());
+  pi.registerTool({
+    name: "lean_ctx",
+    label: "lean_ctx",
+    description:
+      "Run lean-ctx CLI directly (CLI-first; no MCP required). "
+      + "Use this for advanced commands like session/knowledge/overview/gain/stats/index/pack.",
+    promptSnippet: "Run lean-ctx CLI directly",
+    parameters: leanCtxSchema,
+    async execute(_toolCallId, params) {
+      const output = await execLeanCtx(pi, params.args);
+      return {
+        content: [{ type: "text", text: output.trimEnd() }],
+        details: { source: "lean-ctx", args: params.args },
+      };
+    },
+  });
+
+  const enableMcpBridge = envFlag("LEAN_CTX_PI_ENABLE_MCP");
+  const adapterConfigured = isMcpAdapterConfigured();
+  const mcpBridge = enableMcpBridge && !adapterConfigured ? new McpBridge(resolveBinary()) : null;
 
-  if (!isMcpAdapterConfigured()) {
-    mcpBridge.start(pi).catch((err) => {
+  if (mcpBridge) {
+    try {
+      await mcpBridge.start(pi);
+    } catch (err) {
       console.error(`[pi-lean-ctx] MCP bridge startup failed: ${err}`);
-    });
+    }
   }
 
   pi.registerCommand("lean-ctx", {
@@ -503,29 +540,37 @@ export default function (pi: ExtensionAPI) {
     handler: async (_args, ctx) => {
       const bin = resolveBinary();
       const found = existsSync(bin);
-      const status = mcpBridge.getStatus();
+      const status = mcpBridge?.getStatus();
 
       const lines: string[] = [];
       lines.push(found ? `Binary: ${bin}` : "Binary: NOT FOUND — install: cargo install lean-ctx");
-      lines.push(`MCP bridge: ${status.mode} (${status.connected ? "connected" : "disconnected"})`);
-      lines.push(`Reconnect attempts: ${status.reconnectAttempts}`);
-      lines.push(`MCP tools: ${status.toolCount} registered`);
-      if (status.toolNames.length > 0) {
-        lines.push(`  ${status.toolNames.join(", ")}`);
-      }
-      if (status.lastHungTool) {
-        lines.push(`Last hung tool: ${status.lastHungTool}`);
-      }
-      if (status.lastRetry) {
-        lines.push(
-          `Last retry: ${status.lastRetry.toolName} (${status.lastRetry.reason}) at ${status.lastRetry.timestamp}`,
-        );
-      }
-      if (status.lastError) {
-        lines.push(`Last bridge error: ${status.lastError}`);
+      if (adapterConfigured) {
+        lines.push("MCP bridge: adapter-configured (extension bridge disabled)");
+      } else if (!enableMcpBridge) {
+        lines.push("MCP bridge: disabled (CLI-first)");
+        lines.push("  Enable: set LEAN_CTX_PI_ENABLE_MCP=1 and restart Pi");
+      } else if (status) {
+        lines.push(`MCP bridge: ${status.mode} (${status.connected ? "connected" : "disconnected"})`);
+        lines.push(`Reconnect attempts: ${status.reconnectAttempts}`);
+        lines.push(`MCP tools: ${status.toolCount} registered`);
+        if (status.toolNames.length > 0) {
+          lines.push(`  ${status.toolNames.join(", ")}`);
+        }
+        if (status.lastHungTool) {
+          lines.push(`Last hung tool: ${status.lastHungTool}`);
+        }
+        if (status.lastRetry) {
+          lines.push(
+            `Last retry: ${status.lastRetry.toolName} (${status.lastRetry.reason}) at ${status.lastRetry.timestamp}`,
+          );
+        }
+        if (status.lastError) {
+          lines.push(`Last bridge error: ${status.lastError}`);
+        }
       }
 
-      ctx.ui.notify(lines.join("\n"), found && status.connected ? "info" : "warning");
+      const ok = found && (adapterConfigured || !enableMcpBridge || (status?.connected ?? false));
+      ctx.ui.notify(lines.join("\n"), ok ? "info" : "warning");
     },
   });
 }

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "pi-lean-ctx",
-  "version": "3.4.6",
-  "description": "Pi Coding Agent extension with first-class MCP support \u2014 routes bash, read, grep, find, and ls through lean-ctx CLI, and exposes all 49 lean-ctx MCP tools (ctx_session, ctx_knowledge, ctx_semantic_search, ctx_impact, ctx_architecture, ctx_workflow, ctx_gain, etc.) natively in Pi",
+  "version": "3.5.0",
+  "description": "Pi Coding Agent extension (CLI-first) \u2014 routes bash/read/grep/find/ls through lean-ctx CLI for strong token savings. Optional MCP bridge can register advanced tools.",
   "keywords": [
     "pi-package",
     "lean-ctx",
+    "cli",
     "token-optimization",
     "compression",
     "mcp"