@takara-ai/miru-code 1.1.3 → 1.2.1

package/src/cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { type AgentId, writeAgentFile } from "./agents.ts";
+import { clearBenchmarkHistory, resolveBenchmarkHistoryPath } from "./benchmark/history.ts";
 import { clearCache } from "./cache.ts";
 import {
   fail,
@@ -7,8 +8,10 @@ import {
   formatSearchErrorPretty,
   formatSearchResultsPretty,
   hint,
+  info,
   prefersJsonOutput,
   success,
+  writeStdout,
 } from "./cli-ui.ts";
 import { loadStoredCredentials } from "./credentials.ts";
 import { normalizeTakaraApiKeyEnv } from "./env.ts";
@@ -20,9 +23,11 @@ import {
   printFullHelp,
   printMainHelp,
 } from "./help.ts";
+import { getBenchmarkModeStatus, setBenchmarkMode } from "./installer/benchmark-mode.ts";
 import { runSearchGuardFromStdin } from "./installer/hooks/search-guard.ts";
 import { runInstaller } from "./installer/installer.ts";
 import { promptConfirm } from "./installer/prompt.ts";
+import { formatLiteralLocate, type LiteralMode } from "./literal.ts";
 import { serveMcp } from "./mcp/serve.ts";
 import { MiruIndex } from "./miru-index.ts";
 import {
@@ -34,6 +39,8 @@ import {
 import { withSpinner } from "./spinner.ts";
 import type { ContentType, SearchResult } from "./types.ts";
 import {
+  DEFAULT_EXPAND_AFTER,
+  DEFAULT_EXPAND_BEFORE,
   expandChunksAtLine,
   formatExpandResults,
   formatResults,
@@ -52,6 +59,7 @@ await loadStoredCredentials();
 
 const CLI_COMMANDS = new Set([
   "search",
+  "locate",
   "expand",
   "find-related",
   "init",
@@ -59,6 +67,7 @@ const CLI_COMMANDS = new Set([
   "uninstall",
   "setup",
   "clear",
+  "benchmark",
   "hook-guard",
   "help",
   "-h",
@@ -104,7 +113,7 @@ function parseContentArgv(argv: string[]): { content: ContentType[]; rest: strin
       rest.push(arg);
     }
   }
-  return { content: resolveContent(content.length > 0 ? content : ["code"]), rest };
+  return { content: resolveContent(content), rest };
 }
 
 function parseTopK(argv: string[]): { topK: number; rest: string[] } {
@@ -250,6 +259,53 @@ class RelatedChunkNotFoundError extends Error {
   }
 }
 
+async function runLocate(
+  path: string,
+  literal: string,
+  content: ContentType[],
+  jsonFlag: boolean,
+  mode: LiteralMode,
+  limit: number | undefined,
+  ignoreCase: boolean,
+): Promise<void> {
+  await ensureCredentials({ interactive: true });
+
+  const payload = await withSpinner("Locating literal", async () => {
+    const built = await MiruIndex.fromSource(path, content);
+    await built.saveToCache(path);
+    return formatLiteralLocate(
+      built.locateLiteral(literal, {
+        mode,
+        ignore_case: ignoreCase,
+        ...(limit != null ? { limit } : {}),
+      }),
+    );
+  });
+
+  if (prefersJsonOutput(jsonFlag)) {
+    console.log(JSON.stringify(payload));
+    return;
+  }
+
+  const n = Number(payload.n ?? 0);
+  const files = Number(payload.files ?? 0);
+  writeStdout(`literal=${literal}  n=${n}  files=${files}  mode=${mode}`);
+  const hits = payload.hits as Array<{ f: string; l: number; t?: string }> | undefined;
+  if (hits) {
+    for (const hit of hits) {
+      if (hit.t !== undefined) {
+        writeStdout(`  ${hit.f}:${hit.l}: ${hit.t}`);
+      } else {
+        writeStdout(`  ${hit.f}:${hit.l}`);
+      }
+    }
+    if (payload.truncated) {
+      writeStdout(`  … truncated (showing ${hits.length} of ${n})`);
+    }
+  }
+  writeStdout("");
+}
+
 async function runInit(agent: AgentId, force: boolean): Promise<void> {
   try {
     const dest = await writeAgentFile(agent, { force });
@@ -267,6 +323,75 @@ async function runClear(path: string): Promise<void> {
   success(`Cleared cached index for ${path}`);
 }
 
+async function runBenchmarkCommand(rest: string[]): Promise<void> {
+  const action = rest[0];
+  if (!action || action === "-h" || action === "--help") {
+    printCommandHelp("benchmark");
+    return;
+  }
+
+  if (action === "status") {
+    const rows = await getBenchmarkModeStatus();
+    const installed = rows.filter((row) => row.action !== "missing");
+    if (installed.length === 0) {
+      info("No Miru MCP installs found. Run `miru install` first.");
+      return;
+    }
+    for (const row of installed) {
+      writeStdout(`  ${row.enabled ? "on " : "off"}  ${row.agent.padEnd(16)} ${row.path}`);
+    }
+    const onCount = installed.filter((row) => row.enabled).length;
+    writeStdout("");
+    if (onCount > 0) {
+      hint(
+        `Benchmark mode on for ${onCount}/${installed.length}. Run \`miru benchmark off\` to leave.`,
+      );
+    } else {
+      hint("Benchmark mode is off for all installed agents.");
+    }
+    return;
+  }
+
+  if (action === "on" || action === "off") {
+    const enabled = action === "on";
+    const rows = await setBenchmarkMode(enabled);
+    const touched = rows.filter((row) => row.action === "updated" || row.action === "unchanged");
+    if (touched.length === 0) {
+      info("No Miru MCP installs found. Run `miru install` first.");
+      return;
+    }
+    for (const row of touched) {
+      const label = row.action === "updated" ? (enabled ? "enabled" : "disabled") : "unchanged";
+      writeStdout(`  ${label.padEnd(9)} ${row.agent.padEnd(16)} ${row.path}`);
+    }
+    writeStdout("");
+    success(
+      enabled
+        ? "Benchmark mode on. Restart agents to apply."
+        : "Benchmark mode off. Restart agents to apply.",
+    );
+    if (enabled) {
+      hint("Leave anytime with `miru benchmark off`.");
+    }
+    return;
+  }
+
+  if (action === "clear") {
+    const path = resolveBenchmarkHistoryPath();
+    const result = await clearBenchmarkHistory(path);
+    if (result.cleared) {
+      success(`Cleared benchmark report ${result.path}`);
+    } else {
+      info(`No benchmark report at ${result.path}`);
+    }
+    return;
+  }
+
+  fail(`Unknown benchmark action "${action}". Use on, off, status, or clear.`);
+  printCommandHelp("benchmark");
+  process.exit(1);
+}
+
 async function runCli(argv: string[]): Promise<void> {
   const [command, ...rest] = argv;
 
@@ -304,6 +429,11 @@ async function runCli(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === "benchmark") {
+    await runBenchmarkCommand(rest);
+    return;
+  }
+
   if (command === "init") {
     let agent: AgentId | undefined;
     let force = false;
@@ -392,6 +522,49 @@ async function runCli(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === "locate") {
+    const literal = sizedRest[0];
+    if (!literal) {
+      printCommandHelp("locate");
+      process.exit(1);
+    }
+    let mode: LiteralMode = "lines";
+    let limit: number | undefined;
+    let ignoreCase = false;
+    const pathArgs: string[] = [];
+    for (let i = 1; i < sizedRest.length; i++) {
+      const arg = sizedRest[i];
+      if (arg === "--mode" && sizedRest[i + 1]) {
+        const value = sizedRest[++i];
+        if (value !== "count" && value !== "locations" && value !== "lines") {
+          fail(`Unknown locate mode "${value}". Use count, locations, or lines.`);
+          process.exit(1);
+        }
+        mode = value;
+        continue;
+      }
+      if (arg === "--limit" && sizedRest[i + 1]) {
+        const raw = Number(sizedRest[++i]);
+        if (!Number.isFinite(raw) || raw < 1) {
+          fail("locate --limit must be a positive integer.");
+          process.exit(1);
+        }
+        limit = Math.floor(raw);
+        continue;
+      }
+      if (arg === "--ignore-case") {
+        ignoreCase = true;
+        continue;
+      }
+      if (arg !== undefined) {
+        pathArgs.push(arg);
+      }
+    }
+    const path = resolveSearchPath(pathArgs[0] ?? process.cwd());
+    await runLocate(path, literal, content, jsonFlag, mode, limit, ignoreCase);
+    return;
+  }
+
   if (command === "expand") {
     const filePath = sizedRest[0];
     const lineRaw = sizedRest[1];
@@ -401,8 +574,8 @@ async function runCli(argv: string[]): Promise<void> {
     }
     const line = Number(lineRaw);
     const path = resolveSearchPath(sizedRest[2] ?? process.cwd());
-    let before = 1;
-    let after = 1;
+    let before = DEFAULT_EXPAND_BEFORE;
+    let after = DEFAULT_EXPAND_AFTER;
     for (let i = 3; i < sizedRest.length; i++) {
       const arg = sizedRest[i];
       if (arg === "--before" && sizedRest[i + 1]) {
@@ -435,10 +608,15 @@ async function runCli(argv: string[]): Promise<void> {
 
 async function runMcp(argv: string[]): Promise<void> {
   let ref: string | null = null;
+  let benchmark = false;
   const contentTokens: string[] = [];
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
+    if (arg === "--benchmark") {
+      benchmark = true;
+      continue;
+    }
     if (arg === "--ref" && argv[i + 1]) {
       ref = argv[++i] ?? null;
       continue;
@@ -459,7 +637,8 @@ async function runMcp(argv: string[]): Promise<void> {
 
   await serveMcp({
     ref,
-    content: resolveContent(contentTokens.length > 0 ? contentTokens : ["code"]),
+    content: resolveContent(contentTokens),
+    benchmark,
   });
 }
 

package/src/credentials.ts

@@ -27,6 +27,14 @@ export function resolveCredentialsDir(): string {
   return join(xdg, "miru");
 }
 
+/**
+ * Global Miru state directory (credentials, benchmark history, etc.).
+ * Same location as `resolveCredentialsDir()`; prefer this name for non-secret files.
+ */
+export function resolveMiruStateDir(): string {
+  return resolveCredentialsDir();
+}
+
 export function resolveCredentialsPath(): string {
   return join(resolveCredentialsDir(), CREDENTIALS_FILENAME);
 }

package/src/help.ts

@@ -34,11 +34,13 @@ export function printMainHelp(): void {
 
   section("Commands");
   commandRow("search", "Hybrid search over a codebase");
+  commandRow("locate", "Exact substring location in the index");
   commandRow("expand", "Adjacent chunks in the same file as a hit");
   commandRow("find-related", "Find chunks related to a file:line");
   commandRow("setup", "Save your Takara API key locally");
   commandRow("install", "Configure miru across coding agents");
   commandRow("uninstall", "Remove miru agent configuration");
+  commandRow("benchmark", "Turn MCP benchmark mode on or off");
   commandRow("init", "Write a project-local sub-agent file");
   commandRow("clear", "Remove cached index for a path");
   commandRow("help", "Show help for a command");
@@ -62,6 +64,8 @@ export function printEnvHelp(): void {
   writeStdout(`      Default: ${DEFAULT_EMBEDDING_MODEL}`);
   writeStdout("  MIRU_CONCURRENCY");
   writeStdout(`      Parallel workers (default: CPUs − ${DEFAULT_RESERVE_CORES})`);
+  writeStdout("  MIRU_TOKENIZER_JSON");
+  writeStdout("      Path to tokenizer.json (default: <package>/tokenizer/tokenizer.json)");
   writeStdout("");
 }
 
@@ -78,12 +82,26 @@ export function printCommandHelp(command: string): void {
       writeStdout("  miru search <query> [path] [options]");
       section("Options");
       writeStdout("  -k, --top-k N       Number of results (default: 5)");
-      writeStdout("  --content TYPE      code | docs | config | all");
+      writeStdout("  --content TYPE      code | docs | config | all (default: code config)");
       writeStdout("  --json              JSON output (default when piped)");
       section("Example");
       writeStdout('  miru search "where is auth" ./src -k 10 --content code docs');
       writeStdout("");
       return;
+    case "locate":
+      commandHeader("locate", "Exact substring location over the Miru index.");
+      section("Usage");
+      writeStdout("  miru locate <literal> [path] [options]");
+      section("Options");
+      writeStdout("  --mode MODE         count | locations | lines (default: lines)");
+      writeStdout("  --limit N           Optional hit cap (default: all matches)");
+      writeStdout("  --ignore-case       Case-insensitive match");
+      writeStdout("  --content TYPE      code | docs | config | all (default: code config)");
+      writeStdout("  --json              JSON output (default when piped)");
+      section("Example");
+      writeStdout("  miru locate MIRU_BENCHMARK_HISTORY_PATH . --mode locations");
+      writeStdout("");
+      return;
     case "expand":
       commandHeader("expand", "More context in the same file as a search hit.");
       section("Usage");
@@ -121,6 +139,28 @@ export function printCommandHelp(command: string): void {
     case "uninstall":
       commandHeader("uninstall", "Remove miru configuration from agents.");
       writeStdout("Removes MCP entries, marked instruction blocks, and global sub-agents.");
+      writeStdout("Also deletes the global benchmark report from Miru's state directory.");
+      writeStdout("");
+      return;
+    case "benchmark":
+      commandHeader("benchmark", "Toggle MCP benchmark mode on installed agents.");
+      section("Usage");
+      writeStdout("  miru benchmark on");
+      writeStdout("  miru benchmark off");
+      writeStdout("  miru benchmark status");
+      writeStdout("  miru benchmark clear");
+      writeStdout("");
+      writeStdout("Adds or removes `--benchmark` from Miru MCP args in agent configs.");
+      writeStdout("If `--benchmark` is present, benchmark mode is on — no env overrides.");
+      writeStdout("Restart agents after changing mode. Prefer `off` when finished measuring.");
+      writeStdout("");
+      writeStdout("History is a global report (not per-repo) under Miru's state directory.");
+      writeStdout("Override path with MIRU_BENCHMARK_HISTORY_PATH. Append-only JSONL of savings.");
+      writeStdout("Repo paths in the report are plaintext — use `clear` on shared machines.");
+      writeStdout("");
+      writeStdout("Savings compare Miru workflow tokens to a Grep baseline");
+      writeStdout("(rg search + read of the top matched file), not the agent's full tool chain.");
+      writeStdout("Local paths only — git URL repos skip comparison with benchmark_skipped.");
       writeStdout("");
       return;
     case "init":
@@ -145,9 +185,12 @@ export function printCommandHelp(command: string): void {
     case "mcp":
       commandHeader("mcp", "Stdio MCP server (default with no subcommand).");
       section("Usage");
-      writeStdout("  miru [--ref BRANCH] [--content TYPE ...]");
+      writeStdout("  miru [--ref BRANCH] [--content TYPE ...] [--benchmark]");
+      writeStdout("  Default content: code config");
       writeStdout("");
       writeStdout("Indexes on the first search/expand/find_related tool call (repo argument).");
+      writeStdout("Use --benchmark (or `miru benchmark on`) for token-savings comparisons.");
+      writeStdout("Leave with `miru benchmark off` and restart the agent.");
       writeStdout("");
       return;
     default:

package/src/index/create.ts

@@ -6,7 +6,7 @@ import type { EmbeddingBackend } from "../embeddings/openai.ts";
 import { envOptionalInt } from "../env.ts";
 import { searchImprovementsEnabled } from "../ranking/features.ts";
 import { tokenize } from "../tokens.ts";
-import type { Chunk, ContentType } from "../types.ts";
+import { type Chunk, type ContentType, defaultContentTypes } from "../types.ts";
 import { BM25Index } from "./bm25.ts";
 import { loadRootEntryChunks } from "./entry-chunks.ts";
 import { walkFiles } from "./file-walker.ts";
@@ -33,7 +33,7 @@ function resolveMaxIndexFiles(): number | undefined {
 export async function createIndexFromPath(
   path: string,
   embeddings: EmbeddingBackend,
-  content: ContentType[] = ["code"],
+  content: ContentType[] = defaultContentTypes(),
   displayRoot?: string,
 ): Promise<{ bm25: BM25Index; semantic: SemanticIndex; chunks: Chunk[] }> {
   const profile = process.env.MIRU_PROFILE === "1";

package/src/index/incremental.ts

@@ -1,4 +1,4 @@
-import { join, relative, resolve } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { chunkSource } from "../chunking/chunking.ts";
 import type { EmbeddingBackend } from "../embeddings/openai.ts";
 import { tokenize } from "../tokens.ts";
@@ -123,8 +123,9 @@ function rebuildBm25(chunks: Chunk[]): BM25Index {
 export function relativePathFromRoot(root: string, absoluteOrRelative: string): string {
   const resolvedRoot = resolve(root);
   const candidate = resolve(resolvedRoot, absoluteOrRelative);
-  if (candidate.startsWith(`${resolvedRoot}/`) || candidate === resolvedRoot) {
-    return normalizeRelativePath(relative(resolvedRoot, candidate));
+  const rel = normalizeRelativePath(relative(resolvedRoot, candidate));
+  if (rel === "" || (!rel.startsWith("../") && rel !== ".." && !isAbsolute(rel))) {
+    return rel;
   }
   return normalizeRelativePath(absoluteOrRelative);
 }

package/src/index.ts

@@ -18,8 +18,10 @@ export { MiruIndex } from "./miru-index.ts";
 export type {
   /** A searchable text span from a source file (path, line range, content). */
   Chunk,
-  /** What to index: source code, markdown docs, or both. */
+  /** What to index: source code, docs, and/or config. */
   ContentType,
   /** Ranked hit returned by `search` or `findRelated`. */
   SearchResult,
 } from "./types.ts";
+
+export { DEFAULT_CONTENT_TYPES, defaultContentTypes } from "./types.ts";

package/src/installer/benchmark-mode.ts

@@ -0,0 +1,248 @@
+import { AGENT_TARGETS, type AgentTarget, type InstallAction } from "./agents.ts";
+import { removeTomlBlock, stripJsonComments } from "./config.ts";
+
+export const MCP_BENCHMARK_FLAG = "--benchmark";
+
+const CODEX_MCP_HEADER = "[mcp_servers.miru]";
+
+function codexMcpBlock(enabled: boolean): string {
+  const args = enabled
+    ? `["@takara-ai/miru-code", "${MCP_BENCHMARK_FLAG}"]`
+    : '["@takara-ai/miru-code"]';
+  return `${CODEX_MCP_HEADER}\ncommand = "bunx"\nargs = ${args}\n`;
+}
+
+export function withBenchmarkFlag(list: string[], enabled: boolean): string[] {
+  const without = list.filter((item) => item !== MCP_BENCHMARK_FLAG);
+  return enabled ? [...without, MCP_BENCHMARK_FLAG] : without;
+}
+
+export function listHasBenchmarkFlag(list: unknown): boolean {
+  return Array.isArray(list) && list.some((item) => item === MCP_BENCHMARK_FLAG);
+}
+
+/** Toggle `--benchmark` on a JSON MCP server entry (`args` and/or array `command`). */
+export function applyBenchmarkFlagToMcpEntry(
+  entry: Record<string, unknown>,
+  enabled: boolean,
+): { entry: Record<string, unknown>; changed: boolean; enabled: boolean } {
+  const next: Record<string, unknown> = { ...entry };
+  let changed = false;
+
+  if (Array.isArray(next.args)) {
+    const args = next.args.filter((item): item is string => typeof item === "string");
+    const updated = withBenchmarkFlag(args, enabled);
+    if (JSON.stringify(updated) !== JSON.stringify(args)) {
+      next.args = updated;
+      changed = true;
+    }
+  }
+
+  if (Array.isArray(next.command)) {
+    const command = next.command.filter((item): item is string => typeof item === "string");
+    const updated = withBenchmarkFlag(command, enabled);
+    if (JSON.stringify(updated) !== JSON.stringify(command)) {
+      next.command = updated;
+      changed = true;
+    }
+  }
+
+  return {
+    entry: next,
+    changed,
+    enabled: mcpEntryHasBenchmark(next),
+  };
+}
+
+export function mcpEntryHasBenchmark(entry: Record<string, unknown>): boolean {
+  return listHasBenchmarkFlag(entry.args) || listHasBenchmarkFlag(entry.command);
+}
+
+/**
+ * Keep `--benchmark` on the canonical install entry when the existing MCP
+ * entry already had it (so `miru install` does not silently turn mode off).
+ */
+export function withPreservedBenchmarkFlag(
+  canonical: Record<string, unknown>,
+  existing: Record<string, unknown> | null | undefined,
+): Record<string, unknown> {
+  if (!existing || !mcpEntryHasBenchmark(existing)) {
+    return canonical;
+  }
+  return applyBenchmarkFlagToMcpEntry(canonical, true).entry;
+}
+
+export interface BenchmarkModeTargetResult {
+  agent: string;
+  path: string;
+  action: InstallAction | "enabled" | "disabled" | "missing";
+  enabled: boolean;
+}
+
+async function readJsonObject(path: string): Promise<Record<string, unknown> | null> {
+  if (!(await Bun.file(path).exists())) {
+    return null;
+  }
+  try {
+    const text = stripJsonComments(await Bun.file(path).text());
+    const parsed = JSON.parse(text) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+async function writeJsonObject(path: string, value: Record<string, unknown>): Promise<void> {
+  await Bun.write(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+async function statusForToml(path: string): Promise<boolean | null> {
+  if (!(await Bun.file(path).exists())) {
+    return null;
+  }
+  const text = await Bun.file(path).text();
+  if (!text.includes(CODEX_MCP_HEADER)) {
+    return null;
+  }
+  return text.includes(`"${MCP_BENCHMARK_FLAG}"`) || text.includes(`'${MCP_BENCHMARK_FLAG}'`);
+}
+
+async function setTomlBenchmark(
+  path: string,
+  enabled: boolean,
+): Promise<InstallAction | "missing"> {
+  if (!(await Bun.file(path).exists())) {
+    return "missing";
+  }
+  const text = await Bun.file(path).text();
+  if (!text.includes(CODEX_MCP_HEADER)) {
+    return "missing";
+  }
+  const current = await statusForToml(path);
+  if (current === enabled) {
+    return "unchanged";
+  }
+
+  // Replace the miru block with the desired args, preserving the rest of the file.
+  await removeTomlBlock(path);
+  const existed = await Bun.file(path).exists();
+  const existing = existed ? await Bun.file(path).text() : "";
+  const base = existing.replace(/\n+$/, "");
+  const block = codexMcpBlock(enabled);
+  const next = base.length > 0 ? `${base}\n\n${block}` : block;
+  await Bun.write(path, next.endsWith("\n") ? next : `${next}\n`);
+  return "updated";
+}
+
+async function statusForJson(agent: AgentTarget): Promise<boolean | null> {
+  const mcp = agent.mcp;
+  if (mcp?.format !== "json") {
+    return null;
+  }
+  const parsed = await readJsonObject(mcp.path);
+  if (!parsed) {
+    return null;
+  }
+  const section = parsed[mcp.key];
+  if (!section || typeof section !== "object" || Array.isArray(section)) {
+    return null;
+  }
+  const entry = (section as Record<string, unknown>)[mcp.memberKey];
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    return null;
+  }
+  return mcpEntryHasBenchmark(entry as Record<string, unknown>);
+}
+
+async function setJsonBenchmark(
+  agent: AgentTarget,
+  enabled: boolean,
+): Promise<InstallAction | "missing"> {
+  const mcp = agent.mcp;
+  if (mcp?.format !== "json") {
+    return "missing";
+  }
+  const parsed = await readJsonObject(mcp.path);
+  if (!parsed) {
+    return "missing";
+  }
+  const sectionRaw = parsed[mcp.key];
+  if (!sectionRaw || typeof sectionRaw !== "object" || Array.isArray(sectionRaw)) {
+    return "missing";
+  }
+  const section = sectionRaw as Record<string, unknown>;
+  const entryRaw = section[mcp.memberKey];
+  if (!entryRaw || typeof entryRaw !== "object" || Array.isArray(entryRaw)) {
+    return "missing";
+  }
+
+  const applied = applyBenchmarkFlagToMcpEntry(entryRaw as Record<string, unknown>, enabled);
+  if (!applied.changed) {
+    return "unchanged";
+  }
+  section[mcp.memberKey] = applied.entry;
+  parsed[mcp.key] = section;
+  await writeJsonObject(mcp.path, parsed);
+  return "updated";
+}
+
+/** Inspect installed Miru MCP configs for `--benchmark`. */
+export async function getBenchmarkModeStatus(): Promise<BenchmarkModeTargetResult[]> {
+  const results: BenchmarkModeTargetResult[] = [];
+  for (const agent of AGENT_TARGETS) {
+    const mcp = agent.mcp;
+    if (!mcp) {
+      continue;
+    }
+    if (mcp.format === "toml") {
+      const enabled = await statusForToml(mcp.path);
+      results.push({
+        agent: agent.displayName,
+        path: mcp.path,
+        action: enabled == null ? "missing" : enabled ? "enabled" : "disabled",
+        enabled: enabled === true,
+      });
+      continue;
+    }
+    const enabled = await statusForJson(agent);
+    results.push({
+      agent: agent.displayName,
+      path: mcp.path,
+      action: enabled == null ? "missing" : enabled ? "enabled" : "disabled",
+      enabled: enabled === true,
+    });
+  }
+  return results;
+}
+
+/** Enable or disable `--benchmark` on every installed Miru MCP entry. */
+export async function setBenchmarkMode(enabled: boolean): Promise<BenchmarkModeTargetResult[]> {
+  const results: BenchmarkModeTargetResult[] = [];
+  for (const agent of AGENT_TARGETS) {
+    const mcp = agent.mcp;
+    if (!mcp) {
+      continue;
+    }
+    if (mcp.format === "toml") {
+      const action = await setTomlBenchmark(mcp.path, enabled);
+      results.push({
+        agent: agent.displayName,
+        path: mcp.path,
+        action,
+        enabled: action === "missing" ? false : enabled,
+      });
+      continue;
+    }
+    const action = await setJsonBenchmark(agent, enabled);
+    results.push({
+      agent: agent.displayName,
+      path: mcp.path,
+      action,
+      enabled: action === "missing" ? false : enabled,
+    });
+  }
+  return results;
+}