@takara-ai/miru-code 0.1.3 → 0.2.0

package/README.md

@@ -2,9 +2,31 @@
 
 Hybrid code search for AI agents — **TypeScript**, **Bun**, and **Takara embeddings**.
 
-*Miru* means “to see” or “to look” in Japanese — semantic search that helps agents find code by meaning.
+## What is Miru?
 
-Indexes a local directory, combines semantic search with BM25, RRF fusion, and code-tuned reranking.
+*Miru* (見る) means “to see” or “to look” in Japanese. Miru helps coding agents **find code by meaning** instead of guessing file paths or running exhaustive greps.
+
+When an agent asks “where is auth middleware configured?” or “how do we batch embeddings?”, Miru returns the most relevant **chunks** of your codebase — file path, line range, and snippet — so the agent can read only what matters.
+
+### Why hybrid search?
+
+Pure semantic search misses exact symbol matches. Pure keyword search misses paraphrased intent. Miru combines both:
+
+1. **Dense (semantic)** — Takara code embeddings (`ds1-potion-code-16m`) over structurally chunked source files.
+2. **Sparse (BM25)** — keyword scoring with an inverted index; parallelized in Bun workers on large repos.
+3. **RRF fusion** — reciprocal rank fusion merges the two ranked lists.
+4. **Reranking** — code-tuned penalties and boosts (e.g. multi-chunk files, query-term overlap).
+
+Indexes are built on demand, cached on disk, and invalidated when files change. You can search **code**, **docs**, **config**, or **all** content types.
+
+### How agents use Miru
+
+| Mode | Best for | What the agent gets |
+|------|----------|---------------------|
+| **MCP server** | Cursor, Claude Code, VS Code Copilot, Gemini CLI, Kiro, OpenCode | Native `search` and `find_related` tools over the workspace |
+| **CLI sub-agent** | Any agent with shell access | `miru init --agent <id>` writes a specialist agent that runs `miru search` / `miru find-related` via Bash |
+
+Both modes share the same index and cache. Pick MCP when your IDE supports it; use the sub-agent when you want a dedicated exploration agent without MCP wiring.
 
 ## Install
 
@@ -12,7 +34,7 @@ Requires [Bun](https://bun.sh) 1.1+ on your PATH (`curl -fsSL https://bun.sh/ins
 
 ```bash
 # Run once without installing
-bun x @takara-ai/miru-code search "auth middleware" ./src
+bunx @takara-ai/miru-code search "auth middleware" ./src
 
 # Global CLI
 bun add -g @takara-ai/miru-code
@@ -34,7 +56,7 @@ const index = await MiruIndex.fromPath("./src");
 bun install
 ```
 
-Add credentials to `.env.local` (loaded automatically when you run from this repo), or pass them in your MCP config `env` block (recommended for Cursor — MCP does not inherit IDE env vars reliably).
+Add credentials to `.env.local` (loaded automatically when you run from this repo), or pass them in your MCP config `env` block (recommended — MCP does not inherit IDE env vars reliably).
 
 | Variable | Default |
 |----------|---------|
@@ -52,64 +74,153 @@ Parallelism: file reads/chunking, embedding batches (up to concurrency in flight
 
 `OPENAI_*` env aliases are also accepted where noted in the CLI help.
 
-## CLI
+## IDE integration
+
+Miru supports six agent platforms. For each, you can wire the **MCP server** (recommended) and/or install a **CLI sub-agent** with `miru init`.
+
+### Quick reference
+
+| IDE | MCP config file | Sub-agent command | Sub-agent output |
+|-----|-----------------|-------------------|------------------|
+| [Cursor](#cursor) | `~/.cursor/mcp.json` or `.cursor/mcp.json` | `miru init --agent cursor` | `.cursor/agents/miru-code.md` |
+| [Claude Code](#claude-code) | `.mcp.json` (project root) or `~/.claude.json` | `miru init --agent claude` | `.claude/agents/miru-code.md` |
+| [VS Code / Copilot](#vs-code--github-copilot) | `.vscode/mcp.json` or user profile `mcp.json` | `miru init --agent copilot` | `.github/agents/miru-code.md` |
+| [Gemini CLI](#gemini-cli) | `~/.gemini/settings.json` or `.gemini/settings.json` | `miru init --agent gemini` | `.gemini/agents/miru-code.md` |
+| [Kiro](#kiro) | `~/.kiro/settings/mcp.json` or `.kiro/settings/mcp.json` | `miru init --agent kiro` | `.kiro/agents/miru-code.md` |
+| [OpenCode](#opencode) | `~/.config/opencode/opencode.json` or `opencode.json` | `miru init --agent opencode` | `.opencode/agents/miru-code.md` |
+
+Run `miru init --agent <id> --force` to overwrite an existing sub-agent file.
+
+### MCP server
+
+Run with **no arguments** to start the stdio MCP server. Indexing begins on the first `search` or `find_related` call, using the `repo` path you pass. Optional `--ref` sets the default git ref for remote repos.
 
 ```bash
-# Hybrid search (positional, Python-compatible)
-bun run miru search "where are embeddings created" ./src -k 5
+bunx @takara-ai/miru-code
+# or after bun add -g @takara-ai/miru-code:  miru
+```
 
-# Find semantically related chunks
-bun run miru find-related src/embeddings/openai.ts 120 ./src
+**Tools:** `search`, `find_related` — `repo` is required (project root or https:// git URL).
 
-# Write a miru-code sub-agent for Cursor / Claude / etc.
-bun run miru init --agent cursor
+For MCP configs, use `bunx` as the command (`bun` with `x` in `args` works too — they're equivalent).
 
-# Clear disk cache
-bun run miru clear ./src
+Put the bearer token in `env`; MCP will not read `.env.local` unless those vars are unset.
+
+#### Shared env block
+
+Use this in every MCP config below (adjust the key name if your IDE uses `environment` instead of `env`):
+
+```json
+{
+  "TAKARA_API_KEY": "your-takara-bearer-token",
+  "MIRU_OPENAI_BASE_URL": "https://infer.dev.takara.ai/v1",
+  "MIRU_OPENAI_EMBEDDING_MODEL": "ds1-potion-code-16m",
+  "MIRU_EMBEDDING_DIMENSIONS": "256"
+}
 ```
 
-Indexes are cached under `~/Library/Caches/miru` (macOS) or `~/.cache/miru` (Linux).
+### Cursor
 
-## MCP server
+**MCP** — `~/.cursor/mcp.json` or project `.cursor/mcp.json`:
 
-Run with **no arguments** to start the stdio MCP server. It indexes the **current working directory** (Cursor sets this to your workspace). Optional path/ref flags pre-index a different repo.
+```json
+{
+  "mcpServers": {
+    "miru": {
+      "command": "bunx",
+      "args": ["@takara-ai/miru-code"],
+      "env": {
+        "TAKARA_API_KEY": "your-takara-bearer-token"
+      }
+    }
+  }
+}
+```
+
+After `bun add -g @takara-ai/miru-code`, you can use `"command": "miru"` instead.
+
+**Sub-agent:**
 
 ```bash
-bun /path/to/miru/src/cli.ts
-# or after bun add -g @takara-ai/miru-code:  miru
-# or without installing:           bun x @takara-ai/miru-code
+miru init --agent cursor
 ```
 
-**Tools:** `search`, `find_related` — pass `repo` only when querying a different path or git URL.
+Commit `.cursor/agents/miru-code.md` to share the exploration agent with your team.
 
-Cursor `~/.cursor/mcp.json` (or project `.cursor/mcp.json`):
+### Claude Code
 
-Use **`bun x`** (not `bunx` as the command) so Cursor does not pull the `bun` npm package postinstall, which breaks in MCP sandboxes:
+**MCP** — project `.mcp.json` (check into git) or user scope in `~/.claude.json`:
 
 ```json
 {
   "mcpServers": {
     "miru": {
-      "command": "bun",
-      "args": ["x", "@takara-ai/miru-code"],
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["@takara-ai/miru-code"],
       "env": {
-        "TAKARA_API_KEY": "your-takara-bearer-token",
-        "MIRU_OPENAI_BASE_URL": "https://infer.dev.takara.ai/v1",
-        "MIRU_OPENAI_EMBEDDING_MODEL": "ds1-potion-code-16m",
-        "MIRU_EMBEDDING_DIMENSIONS": "256"
+        "TAKARA_API_KEY": "${TAKARA_API_KEY}"
       }
     }
   }
 }
 ```
 
-Alternatively, after `bun add -g @takara-ai/miru-code`:
+Claude Code supports `${VAR}` expansion in config files. Restart the session and run `/mcp` to verify the connection.
+
+Or via CLI:
+
+```bash
+claude mcp add miru -s project -- bunx @takara-ai/miru-code
+```
+
+**Sub-agent:**
+
+```bash
+miru init --agent claude
+```
+
+Writes `.claude/agents/miru-code.md` — invoke the `miru-code` agent for semantic exploration tasks.
+
+### VS Code / GitHub Copilot
+
+**MCP** — workspace `.vscode/mcp.json` or user profile (Command Palette: **MCP: Open User Configuration**):
+
+```json
+{
+  "servers": {
+    "miru": {
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["@takara-ai/miru-code"],
+      "env": {
+        "TAKARA_API_KEY": "your-takara-bearer-token"
+      }
+    }
+  }
+}
+```
+
+VS Code uses `"servers"` (not `mcpServers`). Use **MCP: List Servers** to start or restart the server after editing the config.
+
+**Sub-agent:**
+
+```bash
+miru init --agent copilot
+```
+
+Writes `.github/agents/miru-code.md` for Copilot’s agent system.
+
+### Gemini CLI
+
+**MCP** — `~/.gemini/settings.json` or project `.gemini/settings.json`:
 
 ```json
 {
   "mcpServers": {
     "miru": {
-      "command": "miru",
+      "command": "bunx",
+      "args": ["@takara-ai/miru-code"],
       "env": {
         "TAKARA_API_KEY": "your-takara-bearer-token"
       }
@@ -118,15 +229,58 @@ Alternatively, after `bun add -g @takara-ai/miru-code`:
 }
 ```
 
-Local development (path to this repo):
+Or add interactively: `gemini mcp add`. Run `/mcp` inside a session to confirm tools are available.
+
+**Sub-agent:**
+
+```bash
+miru init --agent gemini
+```
+
+Writes `.gemini/agents/miru-code.md`.
+
+### Kiro
+
+**MCP** — `~/.kiro/settings/mcp.json` or workspace `.kiro/settings/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "miru": {
-      "command": "bun",
-      "args": ["/absolute/path/to/miru/src/cli.ts"],
+      "command": "bunx",
+      "args": ["@takara-ai/miru-code"],
       "env": {
+        "TAKARA_API_KEY": "your-takara-bearer-token",
+        "PATH": "/usr/local/bin:/usr/bin:/bin"
+      }
+    }
+  }
+}
+```
+
+Kiro runs with a minimal environment — include `PATH` if Bun is not on the default path. Approve env vars when prompted in the IDE.
+
+**Sub-agent:**
+
+```bash
+miru init --agent kiro
+```
+
+Writes `.kiro/agents/miru-code.md`.
+
+### OpenCode
+
+**MCP** — `~/.config/opencode/opencode.json` or project `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "miru": {
+      "type": "local",
+      "command": ["bunx", "@takara-ai/miru-code"],
+      "enabled": true,
+      "environment": {
         "TAKARA_API_KEY": "your-takara-bearer-token"
       }
     }
@@ -134,7 +288,49 @@ Local development (path to this repo):
 }
 ```
 
-No project path in `args` for `bun x` / global install — Cursor runs the server with `cwd` set to the open workspace, which becomes the default index. Put the bearer token in `env`; MCP will not read `.env.local` unless those vars are unset.
+OpenCode uses the `mcp` key (not `mcpServers`), requires `"type": "local"`, and uses `environment` instead of `env`. Verify with `opencode mcp list`.
+
+**Sub-agent:**
+
+```bash
+miru init --agent opencode
+```
+
+Writes `.opencode/agents/miru-code.md` (subagent mode with bash/read permissions).
+
+### Local development (any IDE)
+
+Point MCP at this repo instead of the published package:
+
+```json
+{
+  "command": "bun",
+  "args": ["/absolute/path/to/miru-code/src/cli.ts"],
+  "env": {
+    "TAKARA_API_KEY": "your-takara-bearer-token"
+  }
+}
+```
+
+Merge into the appropriate wrapper key (`mcpServers`, `servers`, or `mcp`) for your IDE.
+
+## CLI
+
+```bash
+# Hybrid search (positional, Python-compatible)
+bun run miru search "where are embeddings created" ./src -k 5
+
+# Find semantically related chunks
+bun run miru find-related src/embeddings/openai.ts 120 ./src
+
+# Write a miru-code sub-agent for your IDE
+bun run miru init --agent cursor
+
+# Clear disk cache
+bun run miru clear ./src
+```
+
+Indexes are cached under `~/Library/Caches/miru` (macOS) or `~/.cache/miru` (Linux).
 
 ## Library
 
@@ -156,12 +352,14 @@ bun run typecheck
 
 Releases use **Bun** for install, test, and `bun pm pack`. The registry upload uses **`npm publish`** on that tarball because [Bun does not yet support npm OIDC trusted publishing](https://github.com/oven-sh/bun/issues/22423) — no long-lived npm tokens in GitHub secrets.
 
-**Local first publish** (creates the package on npm):
+**Local publish** (logged in to npm; `publishConfig.access` is already `public`):
 
 ```bash
-bun publish --access public
+bun publish
 ```
 
+Runs `prepublishOnly` (typecheck + tests), then a single registry upload. Do not add a `publish` script that calls `npm publish` — Bun runs lifecycle scripts after its own upload and would publish twice.
+
 **CI** (after Trusted Publisher is configured on npm):
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takara-ai/miru-code",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",
   "license": "MIT",
@@ -50,7 +50,6 @@
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "prepublishOnly": "bun run typecheck && bun test",
-    "publish": "npm publish --access public",
     "benchmark:quality": "bun run scripts/benchmark-quality.ts",
     "benchmark:quantization": "bun run scripts/benchmark-quantization.ts"
   },

package/src/cli.ts

@@ -2,15 +2,18 @@
 import { resolve } from "node:path";
 import { type AgentId, writeAgentFile } from "./agents.ts";
 import { clearCache } from "./cache.ts";
+import { loadStoredCredentials } from "./credentials.ts";
 import { loadEnvFiles } from "./env-files.ts";
 import { serveMcp } from "./mcp/serve.ts";
 import { MiruIndex } from "./miru-index.ts";
+import { ensureCredentials, runClearCredentials, runSetup } from "./setup.ts";
 import type { ContentType } from "./types.ts";
-import { formatResults, isGitUrl, resolveChunk, resolveContent } from "./utils.ts";
+import { formatResults, resolveChunk, resolveContent } from "./utils.ts";
 
 loadEnvFiles();
+await loadStoredCredentials();
 
-const CLI_COMMANDS = new Set(["search", "find-related", "init", "clear", "-h", "--help"]);
+const CLI_COMMANDS = new Set(["search", "find-related", "init", "setup", "clear", "-h", "--help"]);
 
 const AGENTS = new Set<AgentId>(["claude", "copilot", "cursor", "gemini", "kiro", "opencode"]);
 
@@ -64,6 +67,7 @@ async function runSearch(
   topK: number,
   content: ContentType[],
 ): Promise<void> {
+  await ensureCredentials();
   const index = await MiruIndex.fromSource(path, content);
   await index.saveToDefaultCache(path);
   const results = await index.search({ query, topK });
@@ -79,6 +83,7 @@ async function runFindRelated(
   topK: number,
   content: ContentType[],
 ): Promise<void> {
+  await ensureCredentials();
   const index = await MiruIndex.fromSource(path, content);
   const chunk = resolveChunk(index.chunks, filePath, line);
   if (!chunk) {
@@ -111,14 +116,14 @@ function printHelp(): void {
 CLI:
   miru search <query> [path] [-k N] [--content code|docs|config|all]
   miru find-related <file_path> <line> [path] [-k N] [--content ...]
+  miru setup [--key KEY] [--force] [--clear]
   miru init [--agent cursor] [--force]
   miru clear [path]
 
 MCP server (default when no CLI subcommand):
-  miru
-  miru [path] [--ref BRANCH] [--content code ...]
+  miru [--ref BRANCH] [--content code ...]
 
-  With no path, indexes the process working directory (Cursor sets this to your workspace).
+  Indexes a repo on the first search/find_related call via the tool repo argument.
 
 Examples:
   miru search "auth middleware" ./src
@@ -156,6 +161,32 @@ async function runCli(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === "setup") {
+    let apiKey: string | undefined;
+    let force = false;
+    let clear = false;
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === "--force") {
+        force = true;
+      } else if (arg === "--clear") {
+        clear = true;
+      } else if ((arg === "--key" || arg === "-k") && rest[i + 1]) {
+        apiKey = rest[++i];
+      }
+    }
+    if (clear) {
+      if (apiKey) {
+        console.error("Usage: miru setup --clear cannot be combined with --key.");
+        process.exit(1);
+      }
+      await runClearCredentials();
+      return;
+    }
+    await runSetup({ apiKey, force });
+    return;
+  }
+
   if (command === "clear") {
     const path = resolve(rest[0] ?? process.cwd());
     await runClear(path);
@@ -194,7 +225,6 @@ async function runCli(argv: string[]): Promise<void> {
 }
 
 async function runMcp(argv: string[]): Promise<void> {
-  let path: string | null = null;
   let ref: string | null = null;
   const contentTokens: string[] = [];
 
@@ -215,20 +245,20 @@ async function runMcp(argv: string[]): Promise<void> {
         contentTokens.push(value);
         i++;
       }
-      continue;
-    }
-    if (arg && !arg.startsWith("-") && path === null) {
-      path = isGitUrl(arg) ? arg : resolve(arg);
     }
   }
 
   await serveMcp({
-    path,
     ref,
     content: resolveContent(contentTokens.length > 0 ? contentTokens : ["code"]),
   });
 }
 
+async function runMcpWithCredentials(argv: string[]): Promise<void> {
+  await ensureCredentials({ interactive: false });
+  await runMcp(argv);
+}
+
 async function main(): Promise<void> {
   const argv = process.argv.slice(2);
   const first = argv[0];
@@ -236,7 +266,7 @@ async function main(): Promise<void> {
     await runCli(argv);
     return;
   }
-  await runMcp(argv);
+  await runMcpWithCredentials(argv);
 }
 
 main().catch((err) => {

package/src/credentials.ts

@@ -0,0 +1,101 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { EMBEDDING_API_KEY_NAMES, envFirstString } from "./env.ts";
+
+const CREDENTIALS_FILENAME = "credentials.json";
+const CREDENTIALS_VERSION = 1;
+
+interface StoredCredentials {
+  version: number;
+  takara_api_key: string;
+}
+
+export function resolveCredentialsDir(): string {
+  const override = process.env.MIRU_CREDENTIALS_DIR;
+  if (override) {
+    return override;
+  }
+  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
+  if (process.platform === "win32") {
+    const base = process.env.APPDATA ?? join(home, "AppData", "Roaming");
+    return join(base, "miru");
+  }
+  if (process.platform === "darwin") {
+    return join(home, "Library", "Application Support", "miru");
+  }
+  const xdg = process.env.XDG_CONFIG_HOME ?? join(home, ".config");
+  return join(xdg, "miru");
+}
+
+export function resolveCredentialsPath(): string {
+  return join(resolveCredentialsDir(), CREDENTIALS_FILENAME);
+}
+
+export function hasEmbeddingApiKeyInEnv(): boolean {
+  return Boolean(envFirstString([...EMBEDDING_API_KEY_NAMES], ""));
+}
+
+export async function readStoredCredentials(): Promise<StoredCredentials | null> {
+  const path = resolveCredentialsPath();
+  if (!(await Bun.file(path).exists())) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf-8")) as StoredCredentials;
+    if (parsed.version !== CREDENTIALS_VERSION || !parsed.takara_api_key) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Set TAKARA_API_KEY from the user credentials file when env is unset. */
+export async function loadStoredCredentials(): Promise<boolean> {
+  if (hasEmbeddingApiKeyInEnv()) {
+    return false;
+  }
+  const stored = await readStoredCredentials();
+  if (!stored) {
+    return false;
+  }
+  process.env.TAKARA_API_KEY = stored.takara_api_key;
+  return true;
+}
+
+export async function saveStoredCredentials(apiKey: string): Promise<string> {
+  const dir = resolveCredentialsDir();
+  const path = resolveCredentialsPath();
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  const payload: StoredCredentials = {
+    version: CREDENTIALS_VERSION,
+    takara_api_key: apiKey,
+  };
+  await writeFile(path, `${JSON.stringify(payload, null, 2)}\n`, {
+    encoding: "utf-8",
+    mode: 0o600,
+  });
+  try {
+    await chmod(path, 0o600);
+  } catch {
+    // Windows may not support Unix mode bits on all filesystems.
+  }
+  return path;
+}
+
+export async function clearStoredCredentials(): Promise<{ cleared: boolean; path: string }> {
+  const path = resolveCredentialsPath();
+  if (!(await Bun.file(path).exists())) {
+    return { cleared: false, path };
+  }
+
+  const stored = await readStoredCredentials();
+  await rm(path, { force: true });
+
+  if (stored && process.env.TAKARA_API_KEY === stored.takara_api_key) {
+    delete process.env.TAKARA_API_KEY;
+  }
+
+  return { cleared: true, path };
+}

package/src/embeddings/openai.ts

@@ -72,7 +72,7 @@ function stripLoneSurrogates(text: string): string {
 }
 
 export function sanitizeEmbeddingInput(text: string): string {
-  let out = stripLoneSurrogates(text);
+  const out = stripLoneSurrogates(text);
   // Some OpenAI-compatible gateways mis-handle backslash escapes in JSON text
   // payloads. Keep a benchmark fallback mode to forcefully neutralize them.
   const mode = process.env.MIRU_EMBED_ESCAPE_MODE ?? process.env.SEMBLE_EMBED_ESCAPE_MODE ?? "quad";