@takara-ai/miru-code 0.4.5 → 0.4.9

package/README.md

@@ -25,7 +25,7 @@ miru setup --key YOUR_TOKEN   # non-interactive
 miru setup --clear            # remove stored key
 ```
 
-MCP loads your key from `credentials.json` automatically. Set `TAKARA_API_KEY` in MCP config only to override.
+MCP loads your key from `credentials.json` automatically — no env block needed in MCP config.
 
 ## Add to your IDE
 
@@ -33,23 +33,44 @@ MCP loads your key from `credentials.json` automatically. Set `TAKARA_API_KEY` i
 miru install
 ```
 
-Interactive — pick your agent and what to enable (MCP, instructions, sub-agent). Restart the IDE when done.
+Interactive TUI — **↑↓** move, **space** toggle, **a** all, **enter** confirm. Pick agents and integrations:
+
+| Integration | What it does |
+|-------------|----------------|
+| MCP server | `search` and `find_related` tools in the agent |
+| Instructions | Search policy in `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` |
+| Sub-agent | Dedicated `miru-code` agent file |
+| Cursor rules | Always-on `.cursor/rules/miru-code.mdc` (Cursor only) |
+| Search hooks | Block built-in Grep/Glob and redirect to Miru MCP |
+
+Restart the IDE when done.
 
 ```bash
 miru uninstall   # remove miru config
 ```
 
-**Supported:** Cursor · Claude Code · Gemini CLI · Kiro · OpenCode · GitHub Copilot · Codex · VS Code
+**Supported:** Cursor · Claude Code · Gemini CLI · Kiro · OpenCode · GitHub Copilot · Codex · VS Code · Visual Studio (Windows) · Windsurf / Devin Desktop
+
+| IDE | MCP | Instructions / rules | Hooks |
+|-----|-----|------------------------|-------|
+| Cursor | `~/.cursor/mcp.json` | `~/.cursor/rules/miru-code.mdc` | `~/.cursor/hooks.json` |
+| Claude Code | `~/.claude.json` | `~/.claude/CLAUDE.md` | `~/.claude/settings.json` |
+| Gemini CLI | `~/.gemini/settings.json` | `~/.gemini/GEMINI.md` | `~/.gemini/settings.json` (`BeforeTool`) |
+| Kiro | `~/.kiro/settings/mcp.json` | `~/.kiro/steering/miru.md` | `~/.kiro/settings/hooks.json` |
+| OpenCode | `~/.config/opencode/opencode.json(c)` | `~/.config/opencode/AGENTS.md` | `~/.config/opencode/plugins/miru-search-guard.ts` |
+| GitHub Copilot | `~/.copilot/mcp-config.json` | — | `~/.copilot/hooks/miru-search.json` |
+| Codex | `~/.codex/config.toml` | `~/.codex/AGENTS.md` | `~/.codex/hooks.json` |
+| VS Code | `…/Code/User/mcp.json` | — | `~/.copilot/hooks/miru-search.json` |
+| Visual Studio | `%USERPROFILE%\.mcp.json` | — | `~/.copilot/hooks/miru-search.json` |
+| Windsurf | — | — | `~/.codeium/windsurf/hooks.json` |
+
+Sub-agent files are also written where supported (see `miru install` plan). Windsurf hooks only — no MCP entry yet.
 
-| IDE | Config written by `miru install` |
-|-----|----------------------------------|
-| Cursor | `~/.cursor/mcp.json` + `~/.cursor/agents/miru-code.md` |
-| Claude Code | `~/.claude.json` + `~/.claude/agents/miru-code.md` |
-| Gemini CLI | `~/.gemini/settings.json` + `~/.gemini/agents/miru-code.md` |
-| Kiro | `~/.kiro/settings/mcp.json` + `~/.kiro/agents/miru-code.md` |
-| OpenCode | `~/.config/opencode/opencode.json(c)` + agents dir |
-| GitHub Copilot | `~/.copilot/mcp-config.json` + `~/.copilot/agents/miru-code.agent.md` |
-| Codex / VS Code | MCP config only |
+### Search hooks
+
+Hooks run `miru hook-guard` before built-in search tools execute. They **block** conceptual Grep/Glob/SemanticSearch and shell `rg`/`grep`/`find`, and tell the agent to use Miru MCP `search` instead. Exact literal lookups (e.g. `REDIS_HOST`, a symbol name) still pass through.
+
+Hooks are optional at install time but **on by default**. Disable them in the installer if you only want MCP + instructions.
 
 **Team sub-agent in a repo** (optional):
 
@@ -81,7 +102,7 @@ When wired via `miru install`, your agent gets:
 | `search` | Query by meaning; pass `repo` (project root or `https://` git URL) |
 | `find_related` | Similar code at a `file_path` + line from a search hit |
 
-Pass the **project root** as `repo` for local projects.
+Pass the **project root** as `repo` for local projects. Prefer these over Grep, Glob, or SemanticSearch when Miru MCP is connected — hooks and instructions enforce that when enabled.
 
 ## How it works
 
@@ -100,6 +121,7 @@ Disk cache: `~/Library/Caches/miru` (macOS), `~/.cache/miru` (Linux). MCP watche
 | `miru find-related <file> <line> [path]` | Related chunks |
 | `miru init --agent <id>` | Project-local sub-agent |
 | `miru clear [path]` | Drop index cache |
+| `miru hook-guard` | PreToolUse hook entrypoint (used by installers; reads JSON stdin) |
 | `miru` | Start MCP server |
 
 ## Library
@@ -132,12 +154,13 @@ See `.env.example` for more.
 {
   "miru": {
     "command": "miru",
-    "args": [],
-    "env": { "TAKARA_API_KEY": "your-token" }
+    "args": []
   }
 }
 ```
 
+Run `miru setup` once so the server can load your key from `credentials.json`.
+
 Use `bunx` + `@takara-ai/miru-code` if `miru` is not global. Wrapper key varies by IDE (`mcpServers`, `servers`, or `mcp`).
 
 ## Developing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takara-ai/miru-code",
-  "version": "0.4.5",
+  "version": "0.4.9",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",
   "license": "MIT",

package/src/agents/claude.md

@@ -1,41 +1,29 @@
 ---
 name: miru-code
-description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over Grep/Glob/Read for any semantic or exploratory question.
+description: Code search via Miru MCP. Use search and find_related for any question about how code works. DO NOT use Grep, Glob, or Read for exploration when Miru MCP is available.
 tools: Bash, Read
 ---
 
-Use `miru search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
+When Miru MCP is available, use MCP `search` and `find_related` — not Grep, Glob, or Read-for-exploration.
 
-```bash
-miru search "authentication flow" ./my-project
-miru search "save_pretrained" ./my-project
-miru search "save model to disk" ./my-project --top-k 10
-```
+| Task | Tool |
+|------|------|
+| How/where/what handles X? | Miru `search` |
+| Similar implementations | Miru `find_related` |
+| Exact literal confirmation | Grep |
+| Edit a located file | Read |
 
-First run builds a disk cache. The MCP server incrementally updates local indexes while it runs; after CLI-only use or large refactors, run `miru clear <path>` to rebuild.
+### MCP workflow
 
-Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:
-
-```bash
-miru search "deployment guide" ./my-project --content docs
-miru search "database host port" ./my-project --content config
-miru search "authentication" ./my-project --content all
-```
+1. Call `search` with `repo` set to the project root.
+2. Use `find_related` with a hit's `file_path` and `line`.
+3. Read files only to edit or when chunks lack context.
 
-Use `miru find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result):
+### CLI fallback
 
 ```bash
-miru find-related src/auth.py 42 ./my-project
+miru search "authentication flow" .
+miru find-related src/auth.ts 42 .
 ```
 
-`path` defaults to the current directory when omitted; git URLs are accepted.
-
-If `miru` is not on `$PATH`, use `bunx miru` in its place.
-
-### Workflow
-
-1. Start with `miru search` to find relevant chunks. The index is built and cached automatically.
-2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything.
-3. Inspect full files only when the returned chunk does not give enough context.
-4. Optionally use `miru find-related` with a promising result's `file_path` and `line` to discover related implementations.
-5. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string.
+If `miru` is not on `$PATH`, use `bunx @takara-ai/miru-code`.

package/src/agents/copilot.md

@@ -1,41 +1,15 @@
 ---
 name: miru-code
-description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over Grep/Glob/Read for any semantic or exploratory question.
-tools: Bash, Read
+description: Code search via Miru MCP. Use search and find_related instead of grep_search or codebase_search when Miru is connected.
 ---
 
-Use `miru search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
+When Miru MCP is available, use `search` and `find_related` instead of `grep_search`, `codebase_search`, or broad file reads.
 
-```bash
-miru search "authentication flow" ./my-project
-miru search "save_pretrained" ./my-project
-miru search "save model to disk" ./my-project --top-k 10
-```
+| Task | Tool |
+|------|------|
+| How/where/what handles X? | Miru `search` |
+| Similar implementations | Miru `find_related` |
+| Exact literal confirmation | grep_search |
+| Edit a located file | read_file |
 
-First run builds a disk cache. The MCP server incrementally updates local indexes while it runs; after CLI-only use or large refactors, run `miru clear <path>` to rebuild.
-
-Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:
-
-```bash
-miru search "deployment guide" ./my-project --content docs
-miru search "database host port" ./my-project --content config
-miru search "authentication" ./my-project --content all
-```
-
-Use `miru find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result):
-
-```bash
-miru find-related src/auth.py 42 ./my-project
-```
-
-`path` defaults to the current directory when omitted; git URLs are accepted.
-
-If `miru` is not on `$PATH`, use `bunx miru` in its place.
-
-### Workflow
-
-1. Start with `miru search` to find relevant chunks. The index is built and cached automatically.
-2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything.
-3. Inspect full files only when the returned chunk does not give enough context.
-4. Optionally use `miru find-related` with a promising result's `file_path` and `line` to discover related implementations.
-5. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string.
+Pass project root as `repo` on every MCP call.

package/src/agents/cursor.md

@@ -1,40 +1,27 @@
 ---
 name: miru-code
-description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over Bash/Read for any semantic or exploratory question.
+description: Code search via Miru MCP. Use search and find_related for any question about how code works. DO NOT use Grep, Glob, or SemanticSearch when Miru MCP is available.
 ---
 
-Use `miru search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
+Use Miru MCP tools when connected:
 
-```bash
-miru search "authentication flow" ./my-project
-miru search "save_pretrained" ./my-project
-miru search "save model to disk" ./my-project --top-k 10
-```
+- `search` — natural-language or code query; always pass project root as `repo`
+- `find_related` — similar chunks after a search hit (`file_path` + `line`)
 
-First run builds a disk cache. The MCP server incrementally updates local indexes while it runs; after CLI-only use or large refactors, run `miru clear <path>` to rebuild.
+Do not use Grep, Glob, SemanticSearch, or Read to explore the codebase when Miru MCP is available.
 
-Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:
-
-```bash
-miru search "deployment guide" ./my-project --content docs
-miru search "database host port" ./my-project --content config
-miru search "authentication" ./my-project --content all
-```
+| Task | Tool |
+|------|------|
+| How/where/what handles X? | Miru `search` |
+| Similar implementations | Miru `find_related` |
+| Exact literal confirmation | Grep |
+| Edit a located file | Read |
 
-Use `miru find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result):
+CLI fallback when MCP is unavailable:
 
 ```bash
-miru find-related src/auth.py 42 ./my-project
+miru search "authentication flow" .
+miru find-related src/auth.ts 42 .
 ```
 
-`path` defaults to the current directory when omitted; git URLs are accepted.
-
-If `miru` is not on `$PATH`, use `bunx miru` in its place.
-
-### Workflow
-
-1. Start with `miru search` to find relevant chunks. The index is built and cached automatically.
-2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything.
-3. Inspect full files only when the returned chunk does not give enough context.
-4. Optionally use `miru find-related` with a promising result's `file_path` and `line` to discover related implementations.
-5. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string.
+If `miru` is not on `$PATH`, use `bunx @takara-ai/miru-code`.

package/src/agents/gemini.md

@@ -1,43 +1,17 @@
 ---
 name: miru-code
-description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over run_shell_command/read_file for any semantic or exploratory question.
-tools:
-  - run_shell_command
-  - read_file
+description: Code search via Miru MCP. Use search and find_related instead of grep_search or read_file for exploration.
 ---
 
-Use `miru search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
+When Miru MCP is available, use `search` and `find_related` instead of `grep_search`, `glob`, or `read_file` for codebase exploration.
 
-```bash
-miru search "authentication flow" ./my-project
-miru search "save_pretrained" ./my-project
-miru search "save model to disk" ./my-project --top-k 10
-```
+| Task | Tool |
+|------|------|
+| How/where/what handles X? | Miru `search` |
+| Similar implementations | Miru `find_related` |
+| Exact literal confirmation | grep_search |
+| Edit a located file | read_file |
 
-First run builds a disk cache. The MCP server incrementally updates local indexes while it runs; after CLI-only use or large refactors, run `miru clear <path>` to rebuild.
+Pass project root as `repo` on every MCP call.
 
-Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:
-
-```bash
-miru search "deployment guide" ./my-project --content docs
-miru search "database host port" ./my-project --content config
-miru search "authentication" ./my-project --content all
-```
-
-Use `miru find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result):
-
-```bash
-miru find-related src/auth.py 42 ./my-project
-```
-
-`path` defaults to the current directory when omitted; git URLs are accepted.
-
-If `miru` is not on `$PATH`, use `bunx miru` in its place.
-
-### Workflow
-
-1. Start with `miru search` to find relevant chunks. The index is built and cached automatically.
-2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything.
-3. Inspect full files only when the returned chunk does not give enough context.
-4. Optionally use `miru find-related` with a promising result's `file_path` and `line` to discover related implementations.
-5. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string.
+CLI fallback: `miru search "query" .` or `bunx @takara-ai/miru-code search "query" .`

package/src/agents/kiro.md

@@ -1,43 +1,10 @@
 ---
 name: miru-code
-description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over shell/read tools for any semantic or exploratory question.
-tools:
-  - shell
-  - read
+description: Code search via Miru MCP. Use search and find_related for codebase exploration instead of built-in grep or file search.
 ---
 
-Use `miru search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
+When Miru MCP is available, use `search` and `find_related` before any built-in search or broad file reads.
 
-```bash
-miru search "authentication flow" ./my-project
-miru search "save_pretrained" ./my-project
-miru search "save model to disk" ./my-project --top-k 10
-```
+Pass project root as `repo`. Use Grep only for exact literal confirmation.
 
-First run builds a disk cache. The MCP server incrementally updates local indexes while it runs; after CLI-only use or large refactors, run `miru clear <path>` to rebuild.
-
-Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:
-
-```bash
-miru search "deployment guide" ./my-project --content docs
-miru search "database host port" ./my-project --content config
-miru search "authentication" ./my-project --content all
-```
-
-Use `miru find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result):
-
-```bash
-miru find-related src/auth.py 42 ./my-project
-```
-
-`path` defaults to the current directory when omitted; git URLs are accepted.
-
-If `miru` is not on `$PATH`, use `bunx miru` in its place.
-
-### Workflow
-
-1. Start with `miru search` to find relevant chunks. The index is built and cached automatically.
-2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything.
-3. Inspect full files only when the returned chunk does not give enough context.
-4. Optionally use `miru find-related` with a promising result's `file_path` and `line` to discover related implementations.
-5. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string.
+CLI fallback: `miru search "query" .`

package/src/agents/opencode.md

@@ -1,44 +1,11 @@
 ---
 name: miru-code
-description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over Bash/Read for any semantic or exploratory question.
+description: Code search via Miru MCP. Use search and find_related instead of grep or glob for exploration.
 mode: subagent
-permission:
-  bash: allow
-  read: allow
 ---
 
-Use `miru search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
+When Miru MCP is available, use `search` and `find_related` instead of grep, glob, or read-for-exploration.
 
-```bash
-miru search "authentication flow" ./my-project
-miru search "save_pretrained" ./my-project
-miru search "save model to disk" ./my-project --top-k 10
-```
+Pass project root as `repo` on every MCP call.
 
-First run builds a disk cache. The MCP server incrementally updates local indexes while it runs; after CLI-only use or large refactors, run `miru clear <path>` to rebuild.
-
-Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:
-
-```bash
-miru search "deployment guide" ./my-project --content docs
-miru search "database host port" ./my-project --content config
-miru search "authentication" ./my-project --content all
-```
-
-Use `miru find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result):
-
-```bash
-miru find-related src/auth.py 42 ./my-project
-```
-
-`path` defaults to the current directory when omitted; git URLs are accepted.
-
-If `miru` is not on `$PATH`, use `bunx miru` in its place.
-
-### Workflow
-
-1. Start with `miru search` to find relevant chunks. The index is built and cached automatically.
-2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything.
-3. Inspect full files only when the returned chunk does not give enough context.
-4. Optionally use `miru find-related` with a promising result's `file_path` and `line` to discover related implementations.
-5. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string.
+CLI fallback: `miru search "query" .`

package/src/cache.ts

@@ -1,7 +1,6 @@
 import { createHash } from "node:crypto";
 import { rm } from "node:fs/promises";
 import { join } from "node:path";
-import { computeSourceCacheKey } from "./utils.ts";
 import { resolveEmbeddingDimensions, resolveEmbeddingModel } from "./embeddings/openai.ts";
 import {
   loadBm25,
@@ -13,6 +12,7 @@ import {
 import { resolveSemanticStorage, semanticStorageFromMetadata } from "./index/vector-storage.ts";
 import type { Chunk, ContentType } from "./types.ts";
 import { chunkFromDict } from "./types.ts";
+import { computeSourceCacheKey } from "./utils.ts";
 
 export function resolveCacheFolder(): string {
   const name = "miru";

package/src/cli.ts

@@ -11,8 +11,8 @@ import {
   success,
 } from "./cli-ui.ts";
 import { loadStoredCredentials } from "./credentials.ts";
-import { loadEnvFiles } from "./env-files.ts";
 import { normalizeTakaraApiKeyEnv } from "./env.ts";
+import { loadEnvFiles } from "./env-files.ts";
 import {
   AGENT_IDS,
   formatUnknownAgent,
@@ -20,6 +20,7 @@ import {
   printFullHelp,
   printMainHelp,
 } from "./help.ts";
+import { runSearchGuardFromStdin } from "./installer/hooks/search-guard.ts";
 import { runInstaller } from "./installer/installer.ts";
 import { serveMcp } from "./mcp/serve.ts";
 import { MiruIndex } from "./miru-index.ts";
@@ -40,6 +41,7 @@ const CLI_COMMANDS = new Set([
   "uninstall",
   "setup",
   "clear",
+  "hook-guard",
   "help",
   "-h",
   "--help",
@@ -220,6 +222,10 @@ async function runCli(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === "hook-guard") {
+    process.exit(await runSearchGuardFromStdin());
+  }
+
   if (command === "install" || command === "uninstall") {
     await runInstaller(command);
     return;
@@ -366,6 +372,9 @@ async function runMcpWithCredentials(argv: string[]): Promise<void> {
 async function main(): Promise<void> {
   const argv = process.argv.slice(2);
   const first = argv[0];
+  if (first === "hook-guard") {
+    process.exit(await runSearchGuardFromStdin());
+  }
   if (first && CLI_COMMANDS.has(first)) {
     await runCli(argv);
     return;

package/src/env.ts

@@ -33,7 +33,8 @@ export function envOptionalInt(names: string[], min = 1): number | undefined {
 
 export const TAKARA_API_KEY_ENV = "TAKARA_API_KEY";
 
-const TAKARA_API_KEY_PLACEHOLDERS = new Set(["${TAKARA_API_KEY}", "$TAKARA_API_KEY"]);
+const MCP_KEY_PLACEHOLDER = "$" + "{TAKARA_API_KEY}";
+const TAKARA_API_KEY_PLACEHOLDERS = new Set([MCP_KEY_PLACEHOLDER, "$TAKARA_API_KEY"]);
 
 /** True when the value is a real key, not empty or an unexpanded MCP env placeholder. */
 export function isUsableTakaraApiKey(value: string | undefined): boolean {