@takara-ai/miru-code 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# Miru (見る)
+
+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.
+
+Indexes a local directory, combines semantic search with BM25, RRF fusion, and code-tuned reranking.
+
+## Install
+
+Miru ships **Bun as a dependency** so `miru` uses a compatible runtime after install. You still need [Node.js](https://nodejs.org) on your PATH for the install step (Bun’s `postinstall`); do not use `--ignore-scripts`.
+
+```bash
+# Run once without installing
+bunx @takara-ai/miru-code search "auth middleware" ./src
+
+# Global CLI (npm or bun)
+bun add -g @takara-ai/miru-code
+# or: npm install -g @takara-ai/miru-code
+miru search "auth middleware" ./src
+
+# Library
+bun add @takara-ai/miru-code
+```
+
+```ts
+import { MiruIndex } from "@takara-ai/miru-code";
+
+const index = await MiruIndex.fromPath("./src");
+```
+
+## Setup
+
+```bash
+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).
+
+| Variable | Default |
+|----------|---------|
+| `TAKARA_API_KEY` / `OPENAI_API_KEY` / `MIRU_OPENAI_API_KEY` | (required) Bearer token for Takara |
+| `MIRU_OPENAI_BASE_URL` | `https://infer.dev.takara.ai/v1` |
+| `MIRU_OPENAI_EMBEDDING_MODEL` | `ds1-potion-code-16m` |
+| `MIRU_EMBEDDING_DIMENSIONS` | `256` (auto for potion) |
+| `MIRU_FLOAT_VECTORS` | unset (default **int8** quantized vectors); set `1` for float32 |
+| `MIRU_EMBEDDING_BATCH_SIZE` | `32` (max for this model) |
+| `MIRU_CONCURRENCY` | logical CPUs **minus 2** (min 1) |
+
+`SEMBLE_*` env names are still accepted as aliases for migration.
+
+Parallelism: file reads/chunking, embedding batches (up to concurrency in flight), query embed overlapping BM25, and **BM25 scoring in Bun workers** (shards by doc range when index has 256+ chunks). BM25 uses an inverted postings list for fast single-threaded search on small indexes. Override with `MIRU_CONCURRENCY`.
+
+`OPENAI_*` env aliases are also accepted where noted in the CLI help.
+
+## 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 Cursor / Claude / etc.
+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).
+
+## MCP server
+
+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.
+
+```bash
+bun /path/to/miru/src/cli.ts
+# or after bun add -g @takara-ai/miru-code:  miru
+# or without installing:           bunx @takara-ai/miru-code
+```
+
+**Tools:** `search`, `find_related` — pass `repo` only when querying a different path or git URL.
+
+Cursor `~/.cursor/mcp.json` (or project `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "miru": {
+      "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"
+      }
+    }
+  }
+}
+```
+
+Alternatively, after `bun add -g @takara-ai/miru-code`:
+
+```json
+{
+  "mcpServers": {
+    "miru": {
+      "command": "miru",
+      "env": {
+        "TAKARA_API_KEY": "your-takara-bearer-token"
+      }
+    }
+  }
+}
+```
+
+Local development (path to this repo):
+
+```json
+{
+  "mcpServers": {
+    "miru": {
+      "command": "bun",
+      "args": ["/absolute/path/to/miru/src/cli.ts"],
+      "env": {
+        "TAKARA_API_KEY": "your-takara-bearer-token"
+      }
+    }
+  }
+}
+```
+
+No project path in `args` for `bunx` / 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.
+
+## Library
+
+```ts
+import { MiruIndex } from "@takara-ai/miru-code";
+
+const index = await MiruIndex.fromPath("./src");
+const results = await index.search({ query: "BM25 tokenize", topK: 10 });
+```
+
+## Tests
+
+```bash
+bun test
+bun run typecheck
+```
+
+## Publishing
+
+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):
+
+```bash
+bun publish --access public
+```
+
+**CI** (after Trusted Publisher is configured on npm):
+
+```bash
+npm version patch
+git push && git push --tags
+gh release create v0.1.1 --generate-notes
+```
+
+The `release.yml` workflow runs when the GitHub Release is published.
+
+## License
+
+MIT

package/bin/miru.cjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const packageRoot = path.join(__dirname, "..");
+
+function resolveBunExecutable() {
+  const binName = process.platform === "win32" ? "bun.cmd" : "bun";
+  const candidates = [
+    path.join(packageRoot, "node_modules", ".bin", binName),
+    path.join(packageRoot, "node_modules", "bun", "bin", process.platform === "win32" ? "bun.exe" : "bun"),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return binName;
+}
+
+const cli = path.join(packageRoot, "src", "cli.ts");
+const bun = resolveBunExecutable();
+const result = spawnSync(bun, [cli, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+  env: process.env,
+  shell: process.platform === "win32",
+});
+
+if (result.error) {
+  console.error(
+    "miru: failed to run Bun. Reinstall with lifecycle scripts enabled (do not use --ignore-scripts).",
+  );
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@takara-ai/miru-code",
+  "version": "0.1.0",
+  "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Takara",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/takara-ai/miru-code.git"
+  },
+  "homepage": "https://takara.ai",
+  "bugs": "https://github.com/takara-ai/miru-code/issues",
+  "keywords": [
+    "code-search",
+    "semantic-search",
+    "hybrid-search",
+    "mcp",
+    "embeddings",
+    "bm25",
+    "bun",
+    "agents",
+    "cursor",
+    "takara"
+  ],
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "trustedDependencies": [
+    "bun"
+  ],
+  "bin": {
+    "miru": "bin/miru.cjs"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "miru": "bun run src/cli.ts",
+    "mcp": "bun run src/cli.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "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"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "bun": "^1.1.0",
+    "ignore": "^7.0.5",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.16",
+    "@types/bun": "latest",
+    "typescript": "^5.9.3"
+  }
+}

package/src/agents/claude.md

@@ -0,0 +1,41 @@
+---
+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
+---
+
+Use `miru search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
+
+```bash
+miru search "authentication flow" ./my-project
+miru search "save_pretrained" ./my-project
+miru search "save model to disk" ./my-project --top-k 10
+```
+
+Results are cached automatically on first run and invalidated when files change.
+
+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.

package/src/agents/copilot.md

@@ -0,0 +1,41 @@
+---
+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
+---
+
+Use `miru search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
+
+```bash
+miru search "authentication flow" ./my-project
+miru search "save_pretrained" ./my-project
+miru search "save model to disk" ./my-project --top-k 10
+```
+
+Results are cached automatically on first run and invalidated when files change.
+
+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.

package/src/agents/cursor.md

@@ -0,0 +1,40 @@
+---
+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.
+---
+
+Use `miru search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
+
+```bash
+miru search "authentication flow" ./my-project
+miru search "save_pretrained" ./my-project
+miru search "save model to disk" ./my-project --top-k 10
+```
+
+Results are cached automatically on first run and invalidated when files change.
+
+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.

package/src/agents/gemini.md

@@ -0,0 +1,43 @@
+---
+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
+---
+
+Use `miru search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
+
+```bash
+miru search "authentication flow" ./my-project
+miru search "save_pretrained" ./my-project
+miru search "save model to disk" ./my-project --top-k 10
+```
+
+Results are cached automatically on first run and invalidated when files change.
+
+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.

package/src/agents/kiro.md

@@ -0,0 +1,43 @@
+---
+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
+---
+
+Use `miru search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
+
+```bash
+miru search "authentication flow" ./my-project
+miru search "save_pretrained" ./my-project
+miru search "save model to disk" ./my-project --top-k 10
+```
+
+Results are cached automatically on first run and invalidated when files change.
+
+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.

package/src/agents/opencode.md

@@ -0,0 +1,44 @@
+---
+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.
+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:
+
+```bash
+miru search "authentication flow" ./my-project
+miru search "save_pretrained" ./my-project
+miru search "save model to disk" ./my-project --top-k 10
+```
+
+Results are cached automatically on first run and invalidated when files change.
+
+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.

package/src/agents.ts

@@ -0,0 +1,30 @@
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export type AgentId = "claude" | "copilot" | "cursor" | "gemini" | "kiro" | "opencode";
+
+const AGENTS_DIR = join(import.meta.dir, "agents");
+
+export function agentDestination(agent: AgentId): string {
+  const baseDir = agent === "copilot" ? ".github" : `.${agent}`;
+  return join(baseDir, "agents", "miru-code.md");
+}
+
+export async function loadAgentTemplate(agent: AgentId): Promise<string> {
+  return readFile(join(AGENTS_DIR, `${agent}.md`), "utf-8");
+}
+
+export async function writeAgentFile(
+  agent: AgentId,
+  options: { force?: boolean } = {},
+): Promise<string> {
+  const dest = agentDestination(agent);
+  const existing = await Bun.file(dest).exists();
+  if (existing && !options.force) {
+    throw new Error(`${dest} already exists. Run with --force to overwrite.`);
+  }
+  await mkdir(dirname(dest), { recursive: true });
+  const content = await loadAgentTemplate(agent);
+  await Bun.write(dest, content);
+  return dest;
+}