supipowers 1.0.0 → 1.1.0

package/README.md

@@ -1,8 +1,18 @@
-<img width="1584" height="672" alt="image" src="https://github.com/user-attachments/assets/ec0f3658-54d7-4471-91ba-39297191f055" />
+<img width="1584" height="672" alt="supipowers" src="https://github.com/user-attachments/assets/ec0f3658-54d7-4471-91ba-39297191f055" />
+
+<div align="center">
 
 # Supipowers
 
-Agentic workflows for [OMP](https://github.com/can1357/oh-my-pi). Plan features, orchestrate sub-agents, run quality gates, and ship releases — all from slash commands.
+[![npm version](https://img.shields.io/npm/v/supipowers?style=flat-square)](https://www.npmjs.com/package/supipowers)
+[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
+
+Agentic workflows for [Pi](https://github.com/mariozechner/pi-coding-agent) and [OMP](https://github.com/can1357/oh-my-pi) coding agents.
+Plan features, orchestrate sub-agents, run quality gates, fix PRs, manage MCP servers, and ship releases. All from slash commands.
+
+[Install](#install) · [Commands](#commands) · [How it works](#how-it-works) · [Configuration](#configuration) · [Development](#development)
+
+</div>
 
 ## Install
 
@@ -10,33 +20,64 @@ Agentic workflows for [OMP](https://github.com/can1357/oh-my-pi). Plan features,
 bunx supipowers@latest
 ```
 
-The installer checks for OMP, helps you install it if needed, copies supipowers into `~/.omp/agent/`, and optionally installs LSP servers for better code intelligence.
-
-Re-running the installer updates supipowers if a newer version is available. Already up-to-date installs are detected and skipped.
+The installer detects which agent you're running (Pi or OMP), copies supipowers into the right directory, and optionally sets up LSP servers for better code intelligence. Re-running the installer upgrades to the latest version if one is available.
 
-### Update from inside OMP
+### Update from inside your agent
 
 ```
 /supi:update
 ```
 
-Checks npm for the latest version, downloads and installs it — no prompts, no restart needed.
+Checks npm for the latest version, downloads and installs it. No prompts, no restart needed.
 
-## Commands
+## Requirements
+
+### Required
+
+| Dependency | What it's for |
+| --- | --- |
+| [Pi](https://github.com/mariozechner/pi-coding-agent) or [OMP](https://github.com/can1357/oh-my-pi) | The coding agent that supipowers extends |
+| [Bun](https://bun.sh) | Runtime (provides bun:sqlite with FTS5 for full-text search) |
+| [Git](https://git-scm.com) | Version control (used by the installer and context-mode setup) |
+
+### Optional
+
+The installer scans for these and offers to install any that are missing. Everything works without them, but each one unlocks additional capabilities.
+
+| Dependency | Category | What it enables | Install command |
+| --- | --- | --- | --- |
+| [mcpc](https://github.com/apify/mcpc) | MCP | MCP server management via `/supi:mcp` | `npm install -g @apify/mcpc` |
+| [context-mode](https://github.com/mksglu/context-mode) | MCP | Context window protection (auto-routes large outputs through sandboxed execution) | Installed as extension via `git clone` + `npm install` |
+| [typescript-language-server](https://github.com/typescript-language-server/typescript-language-server) | LSP | TypeScript/JavaScript diagnostics, references, completions | `bun add -g typescript-language-server typescript` |
+| [Pyright](https://github.com/microsoft/pyright) | LSP | Python type checking and language features | `pip install pyright` |
+| [rust-analyzer](https://rust-analyzer.github.io) | LSP | Rust language server | `rustup component add rust-analyzer` |
+| [gopls](https://pkg.go.dev/golang.org/x/tools/gopls) | LSP | Go language server | `go install golang.org/x/tools/gopls@latest` |
+| [playwright-cli](https://github.com/microsoft/playwright-cli) | Testing | Interactive browser exploration for E2E flow discovery via `/supi:qa --e2e` | `npm install -g @playwright/cli@latest` |
+| [Playwright Test](https://playwright.dev) | Testing | Test runner for E2E test execution via `run-e2e-tests.sh` | `npm install -g @playwright/cli@latest` |
 
-| Command          | What it does                                     |
-| ---------------- | ------------------------------------------------ |
-| `/supi`          | Interactive menu — commands and project status   |
-| `/supi:plan`     | Collaborative planning with task breakdown       |
-| `/supi:run`      | Execute a plan with parallel sub-agents          |
-| `/supi:review`   | Quality gates at chosen depth                    |
-| `/supi:qa`       | Run test suite and E2E pipeline                  |
-| `/supi:release`  | Version bump, release notes, publish             |
-| `/supi:config`   | Interactive settings (TUI)                       |
-| `/supi:status`   | Check running sub-agents and progress            |
-| `/supi:update`   | Update supipowers to latest version              |
+LSP servers are language-specific. You only need the ones matching the languages in your project. Sub-agents use them to check diagnostics and find references before making changes.
 
-Commands like `/supi`, `/supi:config`, `/supi:status`, and `/supi:update` open native OMP TUI dialogs — they don't send chat messages or trigger the AI.
+> [!TIP]
+> Run `/supi:doctor` at any time to check which dependencies are installed and which are missing.
+
+## Commands
+
+| Command         | What it does                                          |
+| --------------- | ----------------------------------------------------- |
+| `/supi`         | Interactive menu with commands and project status     |
+| `/supi:plan`    | Collaborative planning with structured task breakdown |
+| `/supi:run`     | Execute a plan with parallel sub-agents               |
+| `/supi:review`  | Quality gates at chosen depth                         |
+| `/supi:qa`      | E2E testing pipeline with playwright-cli               |
+| `/supi:release` | Version bump, release notes, publish                  |
+| `/supi:fix-pr`  | Assess and fix PR review comments                     |
+| `/supi:mcp`     | Manage MCP servers (connect, disconnect, list)        |
+| `/supi:config`  | Interactive settings (TUI)                            |
+| `/supi:status`  | Check running sub-agents and progress                 |
+| `/supi:doctor`  | Diagnose extension health and configuration           |
+| `/supi:update`  | Update supipowers to latest version                   |
+
+Commands like `/supi`, `/supi:config`, `/supi:status`, and `/supi:update` open native TUI dialogs. They don't send chat messages or trigger the AI.
 
 ### Planning
 
@@ -44,7 +85,7 @@ Commands like `/supi`, `/supi:config`, `/supi:status`, and `/supi:update` open n
 /supi:plan add authentication to the API
 ```
 
-Starts an interactive planning session: clarifying questions, approach proposals, then a structured task breakdown saved to `.omp/supipowers/plans/`.
+Starts an interactive session: clarifying questions, approach proposals, then a structured task breakdown saved to `.omp/supipowers/plans/` (or the Pi equivalent).
 
 For simple tasks, skip the brainstorming:
 
@@ -60,7 +101,7 @@ For simple tasks, skip the brainstorming:
 
 Loads the latest plan and executes it with sub-agent orchestration. Tasks marked `[parallel-safe]` run concurrently (up to the configured limit). Sequential tasks respect their dependency chains.
 
-The orchestration loop: dispatch batch → collect results → detect conflicts → retry failures → next batch. If interrupted, re-running picks up where it left off.
+The orchestration loop: dispatch batch, collect results, detect conflicts, retry failures, next batch. If interrupted, re-running picks up where it left off.
 
 ### Quality review
 
@@ -81,7 +122,16 @@ When no flag is provided, a TUI picker lets you choose the review profile intera
 /supi:qa --e2e        # Playwright / E2E only
 ```
 
-Detects your test framework on first run (vitest, jest, pytest, cargo test, go test) and caches it. When no flag is provided, a TUI picker lets you choose the scope.
+Detects your test framework on first run (vitest, jest, pytest, cargo test, go test) and caches it. E2E mode (`--e2e`) uses `playwright-cli` to run browser tests autonomously. When no flag is provided, a TUI picker lets you choose the scope.
+
+### Fix PR
+
+```
+/supi:fix-pr          # auto-detects current branch PR
+/supi:fix-pr 42       # targets PR #42
+```
+
+Pulls review comments from GitHub, assesses each one (some comments deserve pushback, not code changes), then fixes what needs fixing. Tracks sessions so you can pick up where you left off.
 
 ### Release
 
@@ -91,13 +141,35 @@ Detects your test framework on first run (vitest, jest, pytest, cargo test, go t
 
 Analyzes commits since last tag, suggests a version bump, generates release notes, and publishes. On first run, a TUI picker lets you choose your pipeline (npm, GitHub release, or manual).
 
+### MCP servers
+
+```
+/supi:mcp
+```
+
+Register, connect, and manage MCP (Model Context Protocol) servers through supipowers. Each server gets auto-generated trigger rules so the agent knows when to use its tools without being told explicitly.
+
+## How it works
+
+Supipowers runs as an extension inside Pi or OMP. A platform abstraction layer handles the API differences between the two agents, so every command works the same regardless of which agent you're using.
+
+**Sub-agent orchestration.** Plans are broken into batches of parallel-safe tasks. Each batch dispatches sub-agents with full tool access (file editing, bash, LSP). After a batch completes, the orchestrator checks for file conflicts, retries failures, and moves to the next batch.
+
+**Quality gates.** Composable checks selected by profile. LSP diagnostics surface real type errors. AI review catches logic issues. Test gates run your actual test suite. Gates report issues with severity levels (error, warning, info).
+
+**LSP integration.** Sub-agents query LSP before making changes (find references, check diagnostics). If no LSP is active, everything still works, just with less precision. The installer offers to set up LSP servers during installation.
+
+**Context-mode integration.** When the [context-mode](https://github.com/ogrodev/context-mode) MCP server is detected, supipowers injects routing hooks that protect the agent's context window. Large command outputs, file reads, and HTTP calls are automatically routed through sandboxed execution so only summaries enter the conversation.
+
+**Update checking.** On session start, supipowers checks npm for a newer version in the background. If one is available, a notification tells you to run `/supi:update`.
+
 ## Configuration
 
 ```
 /supi:config
 ```
 
-Opens an interactive settings screen with all configuration options. Select a setting to change its value — toggles flip instantly, selects open a picker, text fields open an input dialog.
+Opens an interactive settings screen. Select a setting to change its value: toggles flip instantly, selects open a picker, text fields open an input dialog.
 
 ### Profiles
 
@@ -118,65 +190,83 @@ Create custom profiles in `.omp/supipowers/profiles/`.
   "defaultProfile": "thorough",
   "orchestration": {
     "maxParallelAgents": 3, // concurrent sub-agents per batch
-    "maxFixRetries": 2,     // retry failed tasks
-    "maxNestingDepth": 2,   // sub-agent nesting limit
-    "modelPreference": "auto"
+    "maxFixRetries": 2, // retry failed tasks
+    "maxNestingDepth": 2, // sub-agent nesting limit
+    "modelPreference": "auto",
   },
   "lsp": {
-    "setupGuide": true
+    "setupGuide": true,
   },
   "qa": {
     "framework": null, // auto-detected and cached
-    "command": null
-  }
+    "command": null,
+  },
 }
 ```
 
-Config is stored in `~/.omp/agent/extensions/supipowers/` and managed entirely through `/supi:config`.
-
-## How it works
+Config lives in `~/.omp/agent/extensions/supipowers/` (OMP) or `~/.pi/agent/extensions/supipowers/` (Pi) and is managed entirely through `/supi:config`.
 
-Supipowers is built on OMP's extension API. Every command is an immediate action — no state machine, no workflow phases.
+## Skills
 
-**Sub-agent orchestration**: Plans are broken into batches of parallel-safe tasks. Each batch dispatches sub-agents with full OMP tool access (file editing, bash, LSP). After a batch completes, the orchestrator checks for file conflicts, retries failures, and moves to the next batch.
+Supipowers ships with prompt skills that commands load at runtime to steer AI sessions:
 
-**Quality gates**: Composable checks selected by profile. LSP diagnostics feed real type errors. AI review catches logic issues. Test gates run your actual test suite. Gates report issues with severity levels (error/warning/info).
+| Skill                   | Used by                                |
+| ----------------------- | -------------------------------------- |
+| `planning`              | `/supi:plan`                           |
+| `code-review`           | `/supi:review`                         |
+| `debugging`             | Failure retry loop                     |
+| `qa-strategy`           | `/supi:qa`                             |
+| `fix-pr`                | `/supi:fix-pr`                         |
+| `tdd`                   | Plan tasks with test-first annotations |
+| `verification`          | Pre-completion checks                  |
+| `receiving-code-review` | Review comment assessment              |
+| `context-mode`          | Context-mode routing hooks             |
 
-**LSP integration**: Sub-agents query LSP before making changes (find references, check diagnostics). If no LSP is active, everything still works — just better with it. The installer offers to set up LSP servers during installation.
-
-**Update checking**: On session start, supipowers checks npm for a newer version in the background. If one is available, a notification tells you to run `/supi:update`.
+Skills are markdown files in `skills/`. They're loaded on demand, not bundled at build time.
 
 ## Project structure
 
 ```
 src/
-  index.ts                     # extension entry point + update checker
-  commands/                    # slash command handlers
+  index.ts                     # extension entry + platform detection
+  bootstrap.ts                 # command registration orchestrator
+  platform/                    # dual-platform abstraction (Pi + OMP)
+    detect.ts, types.ts, pi.ts, omp.ts
+  commands/                    # one file per slash command
     supi.ts, plan.ts, run.ts, review.ts, qa.ts, release.ts,
-    config.ts, status.ts, update.ts
+    fix-pr.ts, mcp.ts, config.ts, status.ts, doctor.ts, update.ts
   orchestrator/                # sub-agent dispatch & coordination
     batch-scheduler.ts, dispatcher.ts, result-collector.ts,
     conflict-resolver.ts, prompts.ts
+  planning/                    # plan writing & review prompts
+    plan-writer-prompt.ts, plan-reviewer.ts,
+    spec-reviewer.ts, prompt-builder.ts
   quality/                     # composable quality gates
     gate-runner.ts, lsp-gate.ts, ai-review-gate.ts, test-gate.ts
   qa/                          # QA pipeline
-    detector.ts, runner.ts, report.ts
+    session.ts, matrix.ts, prompt-builder.ts, config.ts
+  fix-pr/                      # PR comment assessment & fixing
+    prompt-builder.ts, config.ts, types.ts
+  mcp/                         # MCP server gateway
+    gateway.ts, registry.ts, activation.ts, triggers.ts,
+    lifecycle.ts, manager-tool.ts, mcpc.ts, config.ts
+  context-mode/                # context-mode integration
+    hooks.ts, routing.ts, detector.ts, installer.ts,
+    compressor.ts, event-store.ts, event-extractor.ts,
+    snapshot-builder.ts
   lsp/                         # LSP integration
     detector.ts, bridge.ts, setup-guide.ts
-  notifications/               # rich inline notifications
-    renderer.ts, types.ts
-  config/                      # configuration & profiles
-    loader.ts, profiles.ts, defaults.ts, schema.ts
-  storage/                     # persistence
-    plans.ts, runs.ts, reports.ts
   release/                     # release automation
     analyzer.ts, notes.ts, publisher.ts
+  config/                      # configuration & profiles
+    loader.ts, profiles.ts, defaults.ts, schema.ts
+  storage/                     # persistence layer
+    plans.ts, runs.ts, reports.ts, specs.ts,
+    qa-sessions.ts, fix-pr-sessions.ts
+  notifications/               # rich inline notifications
+    renderer.ts, types.ts
   types.ts                     # shared type definitions
-skills/
-  planning/SKILL.md
-  code-review/SKILL.md
-  debugging/SKILL.md
-  qa-strategy/SKILL.md
+skills/                        # runtime-loaded prompt skills
 bin/
   install.mjs                  # bunx installer
 ```
@@ -187,15 +277,17 @@ bin/
 git clone https://github.com/ogrodev/supipowers.git
 cd supipowers
 bun install
-bun run test        # run tests
-bun run typecheck   # type checking
-bun run test:watch  # watch mode
+bun test              # run all tests
+bun run typecheck     # type checking
+bun run test:watch    # watch mode
+bun run build         # emit to dist/
 ```
 
-## Requirements
+The test suite mirrors the `src/` structure under `tests/`. Tests use Vitest with global imports and inline mocks (no module-level `vi.mock` calls). Filesystem tests use temp directories created in `beforeEach`.
+
+> [!NOTE]
+> Supipowers works with both Pi and OMP. The platform abstraction in `src/platform/` normalizes API differences (event names, tool registration, message delivery) so you can develop against either agent.
 
-- [OMP](https://github.com/can1357/oh-my-pi) (oh-my-pi)
-- [Bun](https://bun.sh) runtime
 
 ## License
 

package/bin/.omp/SYSTEM.md

@@ -0,0 +1,77 @@
+# context-mode — MANDATORY routing rules
+
+You have context-mode MCP tools available. These rules are NOT optional — they protect your context window from flooding. A single unrouted command can dump 56 KB into context and waste the entire session.
+
+## BLOCKED commands — do NOT attempt these
+
+### curl / wget — BLOCKED
+Any Bash command containing `curl` or `wget` is intercepted and replaced with an error message. Do NOT retry.
+Instead use:
+- `ctx_fetch_and_index(url, source)` to fetch and index web pages
+- `ctx_execute(language: "javascript", code: "const r = await fetch(...)")` to run HTTP calls in sandbox
+
+### Inline HTTP — BLOCKED
+Any Bash command containing `fetch('http`, `requests.get(`, `requests.post(`, `http.get(`, or `http.request(` is intercepted and replaced with an error message. Do NOT retry with Bash.
+Instead use:
+- `ctx_execute(language, code)` to run HTTP calls in sandbox — only stdout enters context
+
+### WebFetch / Fetch — BLOCKED
+WebFetch and Fetch calls are denied entirely.
+Instead use:
+- `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` to query the indexed content
+
+### Grep — BLOCKED
+Grep calls are intercepted and blocked. Do NOT retry with Grep.
+Instead use:
+- `ctx_search(queries: ["<pattern>"])` to search indexed content
+- `ctx_batch_execute(commands, queries)` to run searches and return compressed results
+- `ctx_execute(language: "shell", code: "grep ...")` to run searches in sandbox
+
+### Find / Glob — BLOCKED
+Find/Glob calls are intercepted and blocked. Do NOT retry with Find/Glob.
+Instead use:
+- `ctx_execute(language: "shell", code: "find ...")` to run in sandbox
+- `ctx_batch_execute(commands, queries)` for multiple searches
+
+### Read (full-file, no limit) — BLOCKED
+Reading an entire file without a `limit` parameter is blocked.
+- If you need to **Edit** the file → re-call Read with `limit` parameter (e.g., `limit: 200`)
+- If you need to **analyze or explore** → use `ctx_execute_file(path, language, code)` instead. Only your printed summary enters context.
+
+## REDIRECTED tools — use sandbox equivalents
+
+### Bash (>20 lines output)
+Bash is ONLY for: `git`, `mkdir`, `rm`, `mv`, `cd`, `ls`, `npm install`, `pip install`, and other short-output commands.
+For everything else, use:
+- `ctx_batch_execute(commands, queries)` — run multiple commands + search in ONE call
+- `ctx_execute(language: "shell", code: "...")` — run in sandbox, only stdout enters context
+
+### Read (for analysis)
+If you are reading a file to **Edit** it → Read with `limit` is correct (Edit needs content in context).
+If you are reading to **analyze, explore, or summarize** → use `ctx_execute_file(path, language, code)` instead. Only your printed summary enters context. The raw file content stays in the sandbox.
+
+## Tool selection hierarchy
+
+1. **GATHER**: `ctx_batch_execute(commands, queries)` — Primary tool. Runs all commands, auto-indexes output, returns search results. ONE call replaces 30+ individual calls.
+2. **FOLLOW-UP**: `ctx_search(queries: ["q1", "q2", ...])` — Query indexed content. Pass ALL questions as array in ONE call.
+3. **PROCESSING**: `ctx_execute(language, code)` | `ctx_execute_file(path, language, code)` — Sandbox execution. Only stdout enters context.
+4. **WEB**: `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` — Fetch, chunk, index, query. Raw HTML never enters context.
+5. **INDEX**: `ctx_index(content, source)` — Store content in FTS5 knowledge base for later search.
+
+## Subagent routing
+
+When spawning subagents (Agent/Task tool), the routing block is automatically injected into their prompt. Bash-type subagents are upgraded to general-purpose so they have access to MCP tools. You do NOT need to manually instruct subagents about context-mode.
+
+## Output constraints
+
+- Keep responses under 500 words.
+- Write artifacts (code, configs, PRDs) to FILES — never return them as inline text. Return only: file path + 1-line description.
+- When indexing content, use descriptive source labels so others can `ctx_search(source: "label")` later.
+
+## ctx commands
+
+| Command | Action |
+|---------|--------|
+| `ctx stats` | Call the `ctx_stats` MCP tool and display the full output verbatim |
+| `ctx doctor` | Call the `ctx_doctor` MCP tool, run the returned shell command, display as checklist |
+| `ctx upgrade` | Call the `ctx_upgrade` MCP tool, run the returned shell command, display as checklist |

package/bin/install.ts

@@ -186,65 +186,139 @@ function installToPlatform(platformDir: string, packageRoot: string): string {
 }
 
 /**
- * Register context-mode MCP server in the given platform's mcp.json.
+ * Install context-mode as a platform extension and register MCP server.
+ *
+ * Per upstream docs (Pi Coding Agent):
+ *   1. git clone → ~/<platformDir>/extensions/context-mode
+ *   2. npm install && npm run build
+ *   3. Register MCP in ~/<platformDir>/settings/mcp.json
+ *
+ * Build requires Node.js 18+ (tsc, esbuild, node -e in build script).
+ * Runtime uses bun to leverage bun:sqlite — context-mode auto-detects
+ * Bun and skips better-sqlite3 entirely.
  */
-function registerContextMode(platformDir: string, extDir: string): void {
-  const ctxSpinner = spinner();
-  ctxSpinner.start(`Checking for context-mode (${platformDir})...`);
-
-  // Find context-mode installation (Claude Code plugin cache)
-  const ctxCacheBase = join(
-    homedir(),
-    ".claude",
-    "plugins",
-    "cache",
-    "context-mode",
-    "context-mode",
-  );
-  let ctxInstallPath: string | null = null;
-  if (existsSync(ctxCacheBase)) {
-    const versions = readdirSync(ctxCacheBase, { withFileTypes: true })
-      .filter((d) => d.isDirectory())
-      .map((d) => d.name)
-      .sort()
-      .reverse();
-    if (versions.length > 0) {
-      const candidate = join(ctxCacheBase, versions[0], "start.mjs");
-      if (existsSync(candidate)) {
-        ctxInstallPath = join(ctxCacheBase, versions[0]);
-      }
-    }
+async function installContextMode(platformDir: string): Promise<void> {
+  const extDir = join(homedir(), platformDir, "extensions", "context-mode");
+  const startMjs = join(extDir, "start.mjs");
+
+  // Check if already installed and built
+  if (existsSync(startMjs)) {
+    // Already installed — just ensure MCP registration is up to date
+    registerContextModeMcp(platformDir, startMjs);
+    return;
   }
 
-  if (ctxInstallPath) {
-    const mcpConfigPath = join(homedir(), platformDir, "agent", "mcp.json");
-    let mcpConfig: { mcpServers: Record<string, unknown> } = { mcpServers: {} };
-    if (existsSync(mcpConfigPath)) {
-      try {
-        mcpConfig = JSON.parse(readFileSync(mcpConfigPath, "utf8"));
-        if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
-      } catch {
-        mcpConfig = { mcpServers: {} };
-      }
-    }
+  const shouldInstall = await confirm({
+    message: `Install context-mode extension for context window protection? (${platformDir})`,
+  });
+  if (isCancel(shouldInstall) || !shouldInstall) {
+    note(
+      `Skipped. You can install later:\n` +
+        `  git clone https://github.com/mksglu/context-mode.git ~/${platformDir}/extensions/context-mode\n` +
+        `  cd ~/${platformDir}/extensions/context-mode && npm install && npm run build`,
+      `context-mode (${platformDir})`,
+    );
+    return;
+  }
 
-    const startMjs = join(ctxInstallPath, "start.mjs");
-    // Use our wrapper script that captures cwd as CLAUDE_PROJECT_DIR
-    // before context-mode's start.mjs clobbers it with process.chdir(__dirname)
-    const wrapperMjs = join(extDir, "bin", "ctx-mode-wrapper.mjs");
-    mcpConfig.mcpServers["context-mode"] = {
-      command: "node",
-      args: [wrapperMjs, startMjs],
-    };
-
-    mkdirSync(join(homedir(), platformDir, "agent"), { recursive: true });
-    writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
-    ctxSpinner.stop(`context-mode registered in ~/${platformDir}/agent/mcp.json`);
-  } else {
-    ctxSpinner.stop(
-      `context-mode not found — install it as a Claude Code plugin for context window protection (${platformDir})`,
+  // Check Node.js 18+ (required for build: tsc, esbuild, node -e in build script)
+  const nodeCheck = run("node", ["--version"]);
+  if (nodeCheck.error || nodeCheck.status !== 0) {
+    note(
+      "Node.js 18+ is required to build context-mode.\n" +
+        "Install from https://nodejs.org then re-run the installer.",
+      "context-mode requires Node.js",
+    );
+    return;
+  }
+  const nodeVersion = parseInt((nodeCheck.stdout ?? "").replace(/^v/, ""), 10);
+  if (nodeVersion < 18) {
+    note(
+      `Found Node.js v${nodeCheck.stdout?.trim()} but context-mode requires v18+.\n` +
+        "Update Node.js from https://nodejs.org then re-run the installer.",
+      "context-mode requires Node.js 18+",
+    );
+    return;
+  }
+
+  const s = spinner();
+  s.start(`Cloning context-mode to ~/${platformDir}/extensions/context-mode...`);
+
+  // Clone
+  const cloneResult = run("git", [
+    "clone",
+    "https://github.com/mksglu/context-mode.git",
+    extDir,
+  ]);
+  if (cloneResult.status !== 0) {
+    s.stop(`Failed to clone context-mode`);
+    note(
+      cloneResult.stderr?.trim() || "Unknown git clone error",
+      "context-mode install failed",
+    );
+    return;
+  }
+
+  // npm install (builds better-sqlite3 native bindings for Node.js fallback;
+  // at runtime under Bun, bun:sqlite is used instead via auto-detection)
+  s.message("Installing context-mode dependencies...");
+  const npmInstall = run("npm", ["install"], { cwd: extDir });
+  if (npmInstall.status !== 0) {
+    s.stop(`Failed to install context-mode dependencies`);
+    note(
+      npmInstall.stderr?.trim() || "Unknown npm install error",
+      "context-mode install failed",
+    );
+    return;
+  }
+
+  // npm run build (requires tsc + esbuild from devDeps, runs under Node.js)
+  s.message("Building context-mode...");
+  const npmBuild = run("npm", ["run", "build"], { cwd: extDir });
+  if (npmBuild.status !== 0) {
+    s.stop(`Failed to build context-mode`);
+    note(
+      npmBuild.stderr?.trim() || "Unknown build error",
+      "context-mode install failed",
     );
+    return;
+  }
+
+  s.stop(`context-mode installed to ~/${platformDir}/extensions/context-mode`);
+
+  // Register MCP server
+  registerContextModeMcp(platformDir, startMjs);
+}
+
+/**
+ * Register context-mode MCP entry in the platform's settings/mcp.json.
+ *
+ * Uses "bun" as the command so context-mode auto-detects Bun runtime
+ * and uses bun:sqlite — no better-sqlite3 native bindings needed at runtime.
+ */
+function registerContextModeMcp(platformDir: string, startMjs: string): void {
+  const mcpConfigPath = join(homedir(), platformDir, "settings", "mcp.json");
+  let mcpConfig: { mcpServers: Record<string, unknown> } = { mcpServers: {} };
+  if (existsSync(mcpConfigPath)) {
+    try {
+      mcpConfig = JSON.parse(readFileSync(mcpConfigPath, "utf8"));
+      if (!mcpConfig.mcpServers) mcpConfig.mcpServers = {};
+    } catch {
+      mcpConfig = { mcpServers: {} };
+    }
   }
+
+  mcpConfig.mcpServers["context-mode"] = {
+    command: "bun",
+    args: [startMjs],
+  };
+
+  mkdirSync(dirname(mcpConfigPath), { recursive: true });
+  writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
+  note(
+    `Registered in ~/${platformDir}/settings/mcp.json`,
+    `context-mode (${platformDir})`,
+  );
 }
 
 // ── Main ─────────────────────────────────────────────────────
@@ -332,10 +406,10 @@ async function main(): Promise<void> {
   const packageRoot = resolve(__dirname, "..");
 
   for (const target of targets) {
-    const extDir = installToPlatform(target.dir, packageRoot);
+    installToPlatform(target.dir, packageRoot);
 
-    // ── Step 3b: Register context-mode MCP server ───────────
-    registerContextMode(target.dir, extDir);
+    // ── Step 3b: Install context-mode extension + register MCP ──
+    await installContextMode(target.dir);
   }
 
   // ── Step 4: Unified dependency check (--skip-deps to skip) ──
@@ -365,21 +439,33 @@ async function main(): Promise<void> {
       );
     }
 
-    // Offer to install missing deps that have an installCmd
+    // Offer to install missing deps — let user choose which ones
     const installable = statuses.filter(
       (s) => !s.installed && s.installCmd !== null,
     );
 
     if (installable.length > 0) {
-      const depList = installable
-        .map((s) => `  • ${s.name} (${s.installCmd})`)
-        .join("\n");
-      const shouldInstall = await confirm({
-        message: `Install ${installable.length} missing tool(s)?\n${depList}`,
+      const categoryLabels: Record<string, string> = {
+        core: "Core",
+        mcp: "MCP",
+        lsp: "Language Server",
+      };
+
+      const selected = await multiselect({
+        message: "Select tools to install (space to toggle, enter to confirm):",
+        options: installable.map((s) => ({
+          value: s.name,
+          label: s.name,
+          hint: `${categoryLabels[s.category] ?? s.category} — ${s.description}`,
+        })),
+        required: false,
       });
 
-      if (!isCancel(shouldInstall) && shouldInstall) {
-        for (const dep of installable) {
+      if (!isCancel(selected) && (selected as string[]).length > 0) {
+        const toInstall = installable.filter((s) =>
+          (selected as string[]).includes(s.name),
+        );
+        for (const dep of toInstall) {
           const s = spinner();
           s.start(`Installing ${dep.name}...`);
           const result = await installDep(exec, dep.name);