Miru (見る)

Hybrid code search for AI coding agents. Find code by meaning, not grep.

Your AI agent finds the code it needs with up to 50% fewer tokens.

Miru returns the best chunks (path, lines, snippet) for questions like "where is auth middleware configured?" — plugged directly into Claude Code, Cursor, Copilot, Codex, and 9+ other agents via MCP.

Miru replaces the grep/glob-style search agents fall back on today. Install once, and every connected agent gets search and find_related MCP tools automatically.

Prefer this when your IDE has a plugin marketplace — no bun add -g step, and updates go through the IDE's own plugin flow. Run miru setup first if you have not authenticated yet (see Set up credentials).

Claude Code:

/plugin marketplace add takara-ai/miru-code
/plugin install miru

Restart Claude Code (or reload plugins) when prompted. Update: /plugin marketplace update miru then reinstall. Remove: /plugin uninstall miru.

Cursor:

1. Dashboard → Plugins → Team Marketplaces → Add Marketplace → Import from Repo → takara-ai/miru-code
2. Customize (sidebar) → find miru → Install → choose project or user scope

Any other IDE, or if marketplace install isn't available: use the CLI install below.

Plugin installs don't carry full CLI parity — what each one gives you depends on the IDE's own plugin capabilities, not just Miru's packaging:

— means the IDE's plugin schema has no equivalent mechanism to port these to (not a packaging gap we can close): Codex's and Cursor's plugin manifests have no agents or userConfig fields, so the dedicated sub-agent and the benchmark toggle are Claude-Code-only.

Credentials are plugin-scoped, not shared with your CLI install. Claude Code and Codex plugins each store auth in their own IDE-managed data directory (survives plugin updates, removed on uninstall). This means miru setup done via the CLI does not carry over to a plugin install, or vice versa — each authenticates independently on first use (interactive device-code login bootstraps automatically). If you use both the CLI and a plugin, you'll sign in twice.

bun add -g @takara-ai/miru-code

miru setup

Interactive miru setup defaults to device-code login and saves the resulting credentials locally. Manual bearer-token entry is still available with --key. If credentials are missing, the interactive MCP/plugin path can bootstrap the same device flow automatically on first use.

miru setup --device           # explicit device-code login
miru setup --key YOUR_TOKEN   # store a bearer token directly
miru setup --clear            # remove stored credentials

Miru stores versioned credentials in credentials.json and automatically loads or refreshes them for MCP and CLI use. TAKARA_API_KEY still overrides stored credentials when set explicitly.

miru install

Interactive TUI — ↑↓ move, space toggle, a all, enter confirm. Pick agents and integrations:

Restart the IDE when done.

miru uninstall   # remove miru config

Supported: Cursor · Claude Code · Gemini CLI · Kiro · OpenCode · GitHub Copilot · Codex · VS Code · Visual Studio (Windows) · Windsurf / Devin Desktop

• Codex: .codex-plugin/plugin.json, .agents/plugins/marketplace.json, shares the root mcp.json
• Claude Code: .claude-plugin/plugin.json, .claude-plugin/marketplace.json, its own .claude-plugin/mcp.json (needed for the userConfig benchmark toggle — see What you get from a plugin install vs the CLI)
• Cursor: plugin.json and .cursor/rules/miru-code-search.mdc

To switch the Codex plugin to self-hosted embeddings, ask Miru to use your SageMaker endpoint ARN and an existing AWS profile. The auth MCP tool with action: "sagemaker" validates the endpoint, then saves the configuration in the installed plugin's data directory and reloads the index on the next search. It replaces that plugin's stored Takara credentials. See SageMaker setup.

This repository's Codex project configuration automatically approves Miru's search tools and benchmark rollup, while prompting for auth and any additional tools. It applies when this repository is trusted and Miru is installed as miru@personal; use the matching plugin identity for other marketplaces. This policy does not change sandbox permissions or configure other projects that install Miru.

Current limitation:

• these plugin manifests launch the published Miru runtime through bunx @takara-ai/miru-code@latest mcp
• that means local source edits do not affect plugin behavior until a package version is published
• and a fully self-contained “no Bun required” plugin install is still future work

Sub-agent files are also written where supported (see miru install plan). Windsurf hooks only (experimental) — no MCP entry yet. Caveman is an on-demand Agent Skill (default off): invoke with /caveman or “talk like caveman”; stop with “normal mode”. Invocation UI varies by IDE (/caveman, $caveman, @caveman, etc.). Most IDEs share ~/.agents/skills/caveman/SKILL.md (including Copilot / VS Code / Visual Studio); Claude Code and Kiro keep vendor-native skill dirs. Ownership is tracked on the shared path so uninstalling one IDE keeps the skill while another still owns it; selecting all owners removes it once. STE is an on-demand Agent Skill (default off): invoke with /ste or “de-slop this”; keep articles and complete sentences. Most IDEs share ~/.agents/skills/ste/ the same way (ownership via miru-owners.json); Claude Code and Kiro keep vendor-native STE dirs.

Team sub-agent in a repo (optional):

miru init --agent claude --force

Meaning-based questions → search. Exact strings (env vars, symbols, error codes) → locate.

miru search "auth middleware" ./src
miru locate REDIS_HOST ./src
miru expand src/auth.ts 42 ./src
miru find-related src/auth.ts 42 ./src

Terminal output is human-readable; use --json for scripts. One-off without installing:

bunx @takara-ai/miru-code@latest search "auth middleware" ./src

When wired via miru install, the MCP server exposes search, locate, expand, and find_related. read_benchmark appears only in benchmark mode. repo is optional: it defaults to the server's startup directory. Set it for another repo, or if your MCP client starts elsewhere. The index is built on the first call and cached for the session.

1. search with query — returns short numbered source excerpts (±2 lines around the match by default) and relevance scores. MIRU_SNIPPET_LINES sets the number of lines on each side; 0 returns only the matched line.
2. If a hit has truncated: true, its header gives the matched file range (path:start-end) and anchor_line. Read just that range with a ranged Read (offset/limit) — not another search or a full-file read. Excerpts use the same source-line window for every language, without inferred symbol names or declaration outlines.
3. If that range lacks context, call expand with file_path and anchor_line for neighbouring chunks. To trace similar patterns elsewhere, call find_related with the same file_path and anchor_line.
4. Use your editor's Read on absolute_path only for a hit's line range, to see a truncated body or edit it.

Keep repo on follow-up calls when set.

Prefer these tools over Grep, Glob, or SemanticSearch when Miru MCP is connected — hooks and instructions enforce that when enabled.

Local repo hits include absolute_path for one-click navigation. Parameter reference is below under MCP parameters.

Miru combines Takara embeddings and BM25 with linear fusion and code-aware ranking. Index code, docs, config, or all with --content. Set MIRU_RANK_FUSION=rrf for reciprocal rank fusion.

MCP watches local files and updates the index incrementally. Package upgrades invalidate stale caches via the version epoch.

Miru chunks source in tiers: AST (tree-sitter, default) → structural heuristics → line splits.

AST chunking — 26 languages (syntax-aware boundaries via vendored web-tree-sitter grammars):

Structural fallback (brace/indent heuristics when AST is unavailable): python, go, typescript, javascript, cpp, c.

Line fallback: everything else that gets indexed (kotlin, swift, etc.) — still searchable, coarser chunks.

Set MIRU_AST_CHUNKING=0 to disable AST and use structural → lines only.

Run miru in a terminal or miru -h for the command list, or miru <command> -h for details.

CLI uses hyphens (find-related); MCP tool names use underscores (find_related).

bun add @takara-ai/miru-code

import { MiruIndex } from "@takara-ai/miru-code";

const index = await MiruIndex.fromPath("./src");
const results = await index.search({ query: "BM25 tokenize" });

CLI and MCP code searches using ds1-miru-int8 return the top four distinct files by default. A bundled CPU tree reranker refines int8 + BM25 scores and existing symbol boosts for every query, including symbols, paths and non-English text. It needs no additional model download or inference API call. See the evaluation and serving policy for results and tradeoffs.

See .env.example for more.

Miru sends file contents to the Takara inference API when building an index and when embedding search queries. Chunks from your repo are transmitted over HTTPS to generate embeddings. API usage may incur cost depending on your Takara plan.

If you index proprietary code, make sure that sending snippets to Takara's endpoint fits your security and compliance requirements. MIRU_WORKSPACE_ROOT is an opt-in boundary for MCP local repo paths only, and restricts indexing to a single workspace directory when set.

Enterprise self-hosted embeddings (no Takara egress): see docs/self-hosted-sagemaker.md, including the Claude Code plugin settings.

Optional measurement of how many tokens Miru saves versus a simple Grep workflow (ripgrep + reading the top matched file). Useful when evaluating Miru; leave it off day-to-day. Only local repo paths are compared — git URL repos skip the comparison and return benchmark_skipped: "local_repo_only".

miru benchmark on       # add --benchmark to installed MCP configs
miru benchmark status
miru benchmark off      # prefer off when finished measuring
miru benchmark clear    # delete the global report

Restart agents after changing mode. miru install keeps --benchmark if it was already enabled.

While on, each search / locate response includes a compact benchmark block (save_pct, miru_tok, grep_tok, saved_tok, rank1). Call read_benchmark for a cumulative rollup (or ask the agent when you want totals).

History is global (not per-repo) under Miru's state directory:

Override with MIRU_BENCHMARK_HISTORY_PATH. Append-only JSONL of compact token deltas (no query text); read_benchmark returns cumulative totals. Stored in plaintext — miru benchmark clear or uninstall on shared machines.

**search**

**locate**

**expand**

**find_related**

**read_benchmark** (benchmark mode only)

{
  "miru": {
    "command": "miru",
    "args": ["mcp"]
  }
}

For benchmark mode, set "args": ["mcp", "--benchmark"] (or append the flag). Prefer miru benchmark on after a normal install — it updates every agent config.

Run miru setup once so the server can load credentials from credentials.json. If the MCP server starts in an interactive terminal without stored credentials, it will start device login automatically.

Use bunx + @takara-ai/miru-code@latest if miru is not global. The installer uses this command so each new MCP server launch can pick up a published version without a global update. A running server keeps its current version until restarted. Wrapper key varies by IDE (mcpServers, servers, or mcp).

Older headless MCP configs that launch miru without a subcommand, with or without MCP flags, continue to work. Run miru install again to update managed entries to the explicit mcp subcommand, then restart your coding agent. For manual MCP configs, add mcp after the executable or package name.

git clone https://github.com/takara-ai/miru-code.git && cd miru-code
bun install && cp .env.example .env.local
bun test && bun run typecheck

See CONTRIBUTING.md for pre-commit hooks, commit message conventions, and the PR process.

Local MCP: "command": "bun", "args": ["/path/to/miru-code/src/cli.ts"]

miru -h / setup print a framed wordmark on color terminals (MIRU_QUIET=1 for subtitle only). Crane art lives in src/brand-banner.ts; regenerate with bun run scripts/render-crane-art.ts (ImageMagick). The crane is a registered mark of Takara.ai Ltd.

Each GitHub release gets a 1200 × 1200 SVG and PNG card as release assets. The generator reuses the Takara release-card design and takes up to three highlights from the published release notes, prioritizing features, security changes, and performance improvements. Routine maintenance is omitted when user-facing changes are available. No additional API key is needed.

Release Please calls the card workflow directly; manually published releases also trigger it. To regenerate cards for an older release, run the Release card workflow with its tag (leave the tag blank for the latest release):

gh workflow run release-card.yml -f tag=v1.14.4

For a local preview, install librsvg (brew install librsvg on macOS, apt-get install librsvg2-bin fonts-liberation on Ubuntu), then run:

gh release view v1.14.4 --repo takara-ai/miru-code --json tagName,body,isDraft > /tmp/miru-release.json
bun scripts/generate-release-card.ts --release-json /tmp/miru-release.json

Cards are written to dist/release-card/. CI renders a preview and saves it as the release-card-preview artifact.

Miru uses work by MinishLab. Thank you to its authors.

• semble (MIT). Miru ports parts of semble. These parts include the file walker, the index layout, the BM25 tokenizer, the hybrid search pipeline, and the ranking signals.
• potion-code and Model2Vec (MIT). The WordPiece tokenizer in tokenizer/tokenizer.json comes from potion-code.

See NOTICE for the licence text and the Model2Vec citation.

MIT