@trouve-ai/search-plugin 2.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "trouve-search",
+  "description": "Fast, accurate code search for agents: hybrid semantic + BM25 search over any local or remote git repository, with incremental branch-aware indexing. Adds trouve search tools (MCP), a trouve-search sub-agent, and a workflow skill.",
+  "version": "2.0.0",
+  "author": {
+    "name": "Jim Simon"
+  },
+  "homepage": "https://github.com/jimsimon/trouve",
+  "repository": "https://github.com/jimsimon/trouve",
+  "license": "MIT",
+  "keywords": [
+    "code-search",
+    "semantic-search",
+    "mcp",
+    "embeddings"
+  ],
+  "hooks": "./claude-hooks.json"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,36 @@
+{
+  "name": "trouve-search",
+  "version": "2.0.0",
+  "description": "Fast, accurate code search for agents: hybrid semantic + BM25 search over any local or remote git repository, with incremental branch-aware indexing.",
+  "author": {
+    "name": "Jim Simon",
+    "url": "https://github.com/jimsimon"
+  },
+  "homepage": "https://github.com/jimsimon/trouve",
+  "repository": "https://github.com/jimsimon/trouve",
+  "license": "MIT",
+  "keywords": [
+    "code-search",
+    "semantic-search",
+    "mcp",
+    "embeddings"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Trouve Code Search",
+    "shortDescription": "Instant semantic code search for any repository",
+    "longDescription": "Trouve indexes a repository once and answers natural-language or code queries in under a second, returning exact file paths and line numbers. Hybrid model2vec + BM25 retrieval with code-tuned reranking; the index is content-addressed, so edits, branch switches, and worktrees only re-embed what actually changed. Bundles the trouve-search MCP server (search and find_related tools) and a workflow skill. Installs the native binary via npm (@trouve-ai/search-core).",
+    "developerName": "Jim Simon",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read"
+    ],
+    "websiteURL": "https://github.com/jimsimon/trouve",
+    "defaultPrompt": [
+      "Find where authentication is implemented in this repo.",
+      "Search this codebase for the retry/backoff logic.",
+      "What code is related to src/auth.py line 42?"
+    ]
+  }
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "trouve-search": {
+      "command": "npx",
+      "args": ["-y", "@trouve-ai/search-core"]
+    }
+  }
+}

package/README.md

@@ -0,0 +1,72 @@
+# @trouve-ai/search-plugin
+
+One plugin package for four agent harnesses:
+
+- **OpenCode** and **Kilo Code** — native `trouve_search` and
+  `trouve_find_related` tools (npm install).
+- **Claude Code** and **Codex** — MCP server, workflow skill, sub-agent
+  (Claude), and session-start index warming (git marketplace install).
+
+Depends on **`@trouve-ai/search-core`** for the native binary.
+
+## OpenCode
+
+```json
+{ "plugin": ["@trouve-ai/search-plugin"] }
+```
+
+## Kilo Code
+
+```bash
+kilo plugin @trouve-ai/search-plugin --global
+```
+
+Options:
+
+```json
+{ "plugin": [["@trouve-ai/search-plugin", { "content": "all", "warm": true }]] }
+```
+
+## Claude Code
+
+```text
+/plugin marketplace add jimsimon/trouve
+/plugin install trouve-search@trouve
+```
+
+Installs the trouve-search MCP server (tools surface as
+`mcp__trouve-search__search` and `mcp__trouve-search__find_related`), the
+`trouve-search` sub-agent, the workflow skill, and a `SessionStart` hook that
+warms the project index in the background.
+
+## Codex
+
+```bash
+codex plugin marketplace add 'https://github.com/jimsimon/trouve.git' --ref main
+codex plugin add trouve-search@trouve
+```
+
+## MCP / npx
+
+Run the MCP stdio server without a harness plugin:
+
+```bash
+npx -y @trouve-ai/search-core
+```
+
+See [INSTALL.md](../../INSTALL.md) for manual MCP setup and the native
+OpenCode tool-file alternative.
+
+## Development
+
+The `npm/` directory is an npm workspace, so install from there:
+
+```bash
+cd npm
+npm install     # links @trouve-ai/search-core from ../search-core
+npm run typecheck
+```
+
+## License
+
+MIT, same as trouve-search.

package/agents/trouve-search.md

@@ -0,0 +1,41 @@
+---
+name: trouve-search
+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 `trouve-search search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
+
+```bash
+trouve-search search "authentication flow" ./my-project --max-snippet-lines 10  # first 10 lines only, concise
+trouve-search search "save_pretrained" ./my-project                          # full chunk content
+trouve-search search "save model to disk" ./my-project --top-k 10           # more results
+```
+
+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
+trouve-search search "deployment guide" ./my-project --content docs
+trouve-search search "database host port" ./my-project --content config
+trouve-search search "authentication" ./my-project --content all
+```
+
+Use `trouve-search find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result):
+
+```bash
+trouve-search find-related src/auth.py 42 ./my-project
+```
+
+`path` defaults to the current directory when omitted; git URLs are accepted.
+
+If `trouve-search` is not on `$PATH`, install it with `npm i -g @trouve-ai/search-core`, `cargo install trouve-search` or download a release binary from GitHub.
+
+### Workflow
+
+1. Start with `trouve-search 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. Navigate directly to the returned file and line. Do not re-search or grep for the same content.
+4. Optionally use `trouve-search find-related` with a promising result's `file_path` and `line` to discover related implementations.
+5. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function).

package/claude-hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "command -v trouve-search >/dev/null 2>&1 || command -v npx >/dev/null 2>&1 || { echo 'trouve-search not found; install with `npm i -g @trouve-ai/search-core`, `cargo install trouve-search`, or download a release binary from https://github.com/jimsimon/trouve/releases' >&2; exit 1; }; nohup sh -c 'command -v trouve-search >/dev/null && trouve-search stats \"${CLAUDE_PROJECT_DIR:-.}\" || npx -y @trouve-ai/search-core stats \"${CLAUDE_PROJECT_DIR:-.}\"' >/dev/null 2>&1 &"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@trouve-ai/search-plugin",
+  "version": "2.0.0",
+  "description": "trouve code search plugin for OpenCode, Kilo Code, Claude Code, and Codex: native tools (OpenCode/Kilo), MCP server + skill + sub-agent (Claude/Codex).",
+  "type": "module",
+  "main": "./src/plugin.ts",
+  "exports": {
+    ".": "./src/plugin.ts",
+    "./server": "./src/plugin.ts"
+  },
+  "files": [
+    "src",
+    "agents",
+    "skills",
+    "claude-hooks.json",
+    ".mcp.json",
+    ".claude-plugin",
+    ".codex-plugin"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "kilocode",
+    "kilo",
+    "code-search",
+    "semantic-search",
+    "trouve"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jimsimon/trouve.git",
+    "directory": "npm/search-plugin"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.17.13",
+    "@trouve-ai/search-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.0",
+    "typescript": "^6.0.0"
+  }
+}

package/skills/trouve-search/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: trouve-search
+description: Search a codebase by meaning with trouve. Use when looking for where something is implemented, how a feature works, or code related to a known location — instead of grep for exploratory or semantic questions.
+---
+
+# Trouve Code Search
+
+The trouve MCP server (bundled with this plugin) provides two tools:
+
+- `search` — search a codebase with a natural-language or code query.
+- `find_related` — find code similar to a specific file and line.
+
+Use `search` to find where something is implemented — instead of grepping to
+discover files. After trouve returns the file and line, navigate there
+directly and read that file. Do not grep for the same content again.
+
+## Workflow
+
+1. Call `search` with a query describing what the code does or its name
+   (function/class names or behaviour descriptions, not error messages).
+   Pass the project root as `repo`; https:// git URLs also work. Results
+   include 10 lines of context each — signature plus first body lines,
+   enough to confirm the location.
+2. Navigate directly to the top result's file and line. Read only the
+   function or class at that location.
+3. Make the edit. Do not re-search or grep for the same content.
+4. Optionally call `find_related` with `file_path` and `line` from a search
+   result to discover similar code elsewhere (implementations of an
+   interface, callers, tests).
+5. Grep only when you need every occurrence of a literal string across the
+   whole repo (e.g., all callers of a renamed function).
+
+The index is warmed in the background at session start where the harness
+supports startup hooks (and built on first use otherwise); it is cached,
+and updates are incremental and shared across branches and worktrees.
+
+## CLI fallback
+
+Without MCP access, the `trouve-search` CLI provides the same search:
+
+```bash
+trouve-search search "authentication flow" ./my-project --max-snippet-lines 10
+trouve-search search "deployment guide" ./my-project --content docs
+trouve-search search "database host port" ./my-project --content config
+trouve-search find-related src/auth.py 42 ./my-project
+```
+
+`--content` selects what to search: `code` (default), `docs`, `config`, or
+`all`.
+
+## Requirements
+
+Install with `npm i -g @trouve-ai/search-core`, `cargo install trouve-search` or
+download a release binary from https://github.com/jimsimon/trouve/releases.

package/src/plugin.ts

@@ -0,0 +1,353 @@
+// Plugin exposing trouve code search as native tools in OpenCode and
+// Kilo Code (whose plugin runtime is identical to OpenCode's).
+//
+// Unlike the standalone tool file (src/agents/opencode-tool.ts, one CLI
+// process per call), this plugin keeps a single `trouve-search` server process
+// alive for the whole session and speaks its newline-delimited JSON-RPC
+// protocol directly. That preserves the server's in-process index cache:
+// repeat queries — including against remote git URLs — skip index reload
+// entirely.
+//
+// Binary resolution is delegated to @trouve-ai/search-core.
+import { resolveBinaryPath } from "@trouve-ai/search-core"
+import { tool, type Plugin, type PluginModule } from "@opencode-ai/plugin"
+
+import pkg from "../package.json"
+
+const PROTOCOL_VERSION = "2024-11-05"
+const CONTENT_TYPES = ["code", "docs", "config", "all"] as const
+type ContentType = (typeof CONTENT_TYPES)[number]
+
+interface Pending {
+  resolve(value: unknown): void
+  reject(error: Error): void
+}
+
+/// The initialize handshake involves no indexing and must be quick.
+const INIT_TIMEOUT_MS = 30_000
+/// A tool call may include a cold index build of a very large (or remote)
+/// repo; anything beyond this is treated as a hung server.
+const CALL_TIMEOUT_MS = 10 * 60 * 1000
+
+/** Minimal client for trouve's newline-delimited JSON-RPC stdio server. */
+class TrouveServer {
+  private proc: ReturnType<typeof Bun.spawn> | null = null
+  private pending = new Map<number, Pending>()
+  private nextId = 1
+  private starting: Promise<void> | null = null
+  private stderrTail = ""
+
+  constructor(private content: ContentType[]) {}
+
+  async callTool(name: string, args: Record<string, unknown>): Promise<string> {
+    await this.ensureStarted()
+    const result = (await this.request(
+      "tools/call",
+      { name, arguments: args },
+      CALL_TIMEOUT_MS,
+    )) as {
+      content?: Array<{ type: string; text?: string }>
+    }
+    const text = result.content
+      ?.map((part) => (part.type === "text" ? (part.text ?? "") : ""))
+      .join("")
+    return text?.trim() || "trouve-search returned no output."
+  }
+
+  private ensureStarted(): Promise<void> {
+    // `proc` is set before the initialize handshake completes, so an
+    // in-flight startup must win over the proc check: a concurrent caller
+    // would otherwise send tools/call before the server is initialized.
+    if (this.starting) return this.starting
+    if (this.proc) return Promise.resolve()
+    this.starting = this.start().finally(() => {
+      this.starting = null
+    })
+    return this.starting
+  }
+
+  private async start(): Promise<void> {
+    const binary = resolveBinaryPath()
+    const argv = [binary]
+    if (!(this.content.length === 1 && this.content[0] === "code")) {
+      argv.push("--content", ...this.content)
+    }
+    const proc = Bun.spawn(argv, {
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+    })
+    this.proc = proc
+    proc.exited.then(() => this.onExit())
+    this.readLoop(proc.stdout).catch(() => this.onExit())
+    this.readStderr(proc.stderr).catch(() => {})
+    await this.request(
+      "initialize",
+      {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: pkg.name, version: pkg.version },
+      },
+      INIT_TIMEOUT_MS,
+    )
+    this.write({ jsonrpc: "2.0", method: "notifications/initialized" })
+  }
+
+  /// Keep the tail of stderr so a crash can be diagnosed from the tool
+  /// output instead of vanishing silently.
+  private async readStderr(stderr: ReadableStream<Uint8Array>): Promise<void> {
+    const decoder = new TextDecoder()
+    for await (const chunk of stderr) {
+      this.stderrTail = (this.stderrTail + decoder.decode(chunk, { stream: true })).slice(-2000)
+    }
+  }
+
+  private onExit(): void {
+    this.proc = null
+    const pending = [...this.pending.values()]
+    this.pending.clear()
+    const detail = this.stderrTail.trim()
+    const message = detail
+      ? `trouve-search server exited unexpectedly: ${detail}`
+      : "trouve-search server exited unexpectedly"
+    for (const p of pending) p.reject(new Error(message))
+  }
+
+  private async readLoop(stdout: ReadableStream<Uint8Array>): Promise<void> {
+    const decoder = new TextDecoder()
+    let buffer = ""
+    for await (const chunk of stdout) {
+      buffer += decoder.decode(chunk, { stream: true })
+      let newline: number
+      while ((newline = buffer.indexOf("\n")) >= 0) {
+        const line = buffer.slice(0, newline).trim()
+        buffer = buffer.slice(newline + 1)
+        if (line) this.onMessage(line)
+      }
+    }
+  }
+
+  private onMessage(line: string): void {
+    let message: { id?: number; result?: unknown; error?: { message?: string } }
+    try {
+      message = JSON.parse(line)
+    } catch {
+      return
+    }
+    if (typeof message.id !== "number") return
+    const pending = this.pending.get(message.id)
+    if (!pending) return
+    this.pending.delete(message.id)
+    if (message.error) {
+      pending.reject(new Error(message.error.message ?? "trouve-search server error"))
+    } else {
+      pending.resolve(message.result)
+    }
+  }
+
+  private request(method: string, params: unknown, timeoutMs: number): Promise<unknown> {
+    const id = this.nextId++
+    const promise = new Promise((resolve, reject) => {
+      // A server that stalls without exiting would otherwise hang the
+      // agent turn forever: fail the request and kill the process so the
+      // next call starts fresh.
+      const timer = setTimeout(() => {
+        if (this.pending.delete(id)) {
+          this.proc?.kill()
+          reject(
+            new Error(
+              `trouve-search server did not respond to ${method} within ${timeoutMs / 1000}s ` +
+                "and was restarted. Index builds are incremental; retrying resumes.",
+            ),
+          )
+        }
+      }, timeoutMs)
+      this.pending.set(id, {
+        resolve: (value) => {
+          clearTimeout(timer)
+          resolve(value)
+        },
+        reject: (error) => {
+          clearTimeout(timer)
+          reject(error)
+        },
+      })
+    })
+    this.write({ jsonrpc: "2.0", id, method, params })
+    return promise
+  }
+
+  private write(message: unknown): void {
+    const stdin = this.proc?.stdin as { write(data: string): void; flush(): void } | undefined
+    if (!stdin) throw new Error("trouve-search server is not running")
+    stdin.write(JSON.stringify(message) + "\n")
+    stdin.flush()
+  }
+}
+
+function errorText(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error)
+  if (/ENOENT|executable|not.*found/i.test(message)) {
+    return (
+      "trouve-search failed: the `trouve-search` binary was not found. " +
+      "Install @trouve-ai/search-plugin (includes search-core), or `cargo install trouve-search`, " +
+      "or download a release binary from GitHub."
+    )
+  }
+  return `trouve-search failed: ${message}`
+}
+
+const REPO = tool.schema
+  .string()
+  .optional()
+  .describe(
+    "Local directory path or https:// git URL to search. Defaults to the project root. " +
+      "The index is built on first use and cached; updates are incremental.",
+  )
+
+const TOP_K = tool.schema
+  .number()
+  .int()
+  .min(1)
+  .optional()
+  .describe("Number of results to return (default 5).")
+
+const MAX_SNIPPET_LINES = tool.schema
+  .number()
+  .int()
+  .min(0)
+  .optional()
+  .describe(
+    "Lines of source per result. Default (10): signature + first body lines, enough to " +
+      "confirm the location. 0: file path and line range only. Larger values include " +
+      "more, up to the full chunk.",
+  )
+
+/** Minimum interval between background index warms. */
+const WARM_INTERVAL_MS = 60_000
+
+/**
+ * Fire-and-forget index warm: `trouve-search stats` builds (or incrementally
+ * refreshes) the on-disk index and snapshot for `directory`, so the first
+ * real search of a session mmap-loads a warm snapshot instead of paying the
+ * build. Failures (e.g. no trouve binary) are silently ignored — the tools
+ * themselves report actionable errors when actually called.
+ */
+function makeWarmer(directory: string | undefined, content: ContentType[]) {
+  let last = 0
+  return () => {
+    if (!directory) return
+    const now = Date.now()
+    if (now - last < WARM_INTERVAL_MS) return
+    last = now
+    try {
+      const binary = resolveBinaryPath()
+      const argv = [binary, "stats", directory]
+      if (!(content.length === 1 && content[0] === "code")) {
+        argv.push("--content", ...content)
+      }
+      Bun.spawn(argv, { stdin: "ignore", stdout: "ignore", stderr: "ignore" })
+    } catch {
+      // Missing binary: stay silent here; tool calls surface the real error.
+    }
+  }
+}
+
+/**
+ * Plugin options (set in opencode/kilo config as `["@trouve-ai/search-plugin", {...}]`):
+ * - `content`: what the server indexes — "code" (default), "docs",
+ *   "config", "all", or an array of those.
+ * - `warm`: build/refresh the project index in the background at session
+ *   start and after each idle turn (default true).
+ */
+export const TrouvePlugin: Plugin = async (input, options) => {
+  const opts = options as { content?: string | string[]; warm?: boolean } | undefined
+  const requested = opts?.content
+  const requestedList = Array.isArray(requested) ? requested : requested ? [requested] : ["code"]
+  const invalid = requestedList.filter(
+    (c) => !(CONTENT_TYPES as readonly string[]).includes(c),
+  )
+  if (invalid.length) {
+    console.warn(
+      `trouve-search: ignoring invalid content value(s) ${invalid.join(", ")}; ` +
+        `valid values are ${CONTENT_TYPES.join(", ")}.`,
+    )
+  }
+  const content = requestedList.filter((c): c is ContentType =>
+    (CONTENT_TYPES as readonly string[]).includes(c),
+  )
+  const resolved = content.length ? content : (["code"] as ContentType[])
+  const server = new TrouveServer(resolved)
+
+  const warm = opts?.warm === false ? () => {} : makeWarmer(input?.worktree, resolved)
+  // Warm at plugin load, so the index is ready before the first search;
+  // re-warm (throttled) whenever a session goes idle, absorbing any edits
+  // the agent made during the turn.
+  warm()
+
+  return {
+    event: async ({ event }) => {
+      if (event.type === "session.idle") warm()
+    },
+    tool: {
+      trouve_search: tool({
+        description:
+          "Search a codebase once with a focused query describing what the code does or its " +
+          "name. Write queries using function/class names or behaviour descriptions, not " +
+          "error messages. Returns file paths and line numbers — navigate directly there, " +
+          "do not grep for the same content again.",
+        args: {
+          query: tool.schema.string().describe("Natural language or code query."),
+          repo: REPO,
+          top_k: TOP_K,
+          max_snippet_lines: MAX_SNIPPET_LINES,
+        },
+        async execute(args, context) {
+          try {
+            return await server.callTool("search", {
+              query: args.query,
+              repo: args.repo ?? context.worktree,
+              top_k: args.top_k ?? 5,
+              max_snippet_lines: args.max_snippet_lines ?? 10,
+            })
+          } catch (error) {
+            return errorText(error)
+          }
+        },
+      }),
+      trouve_find_related: tool({
+        description:
+          "Find code similar to a known location. Useful for discovering all implementations " +
+          "of an interface, all callers of a function, or all tests for a class. Pass " +
+          "`file_path` and `line` from a prior trouve_search result.",
+        args: {
+          file_path: tool.schema
+            .string()
+            .describe("Path to the file as shown in a search result."),
+          line: tool.schema.number().int().min(1).describe("Line number (1-indexed)."),
+          repo: REPO,
+          top_k: TOP_K,
+          max_snippet_lines: MAX_SNIPPET_LINES,
+        },
+        async execute(args, context) {
+          try {
+            return await server.callTool("find_related", {
+              file_path: args.file_path,
+              line: args.line,
+              repo: args.repo ?? context.worktree,
+              top_k: args.top_k ?? 5,
+              max_snippet_lines: args.max_snippet_lines ?? 10,
+            })
+          } catch (error) {
+            return errorText(error)
+          }
+        },
+      }),
+    },
+  }
+}
+
+// Module descriptor: the shape both OpenCode's and Kilo Code's loaders
+// prefer. The named `TrouvePlugin` export above remains for older loaders
+// that invoke plugin function exports directly.
+export default { id: "trouve-search", server: TrouvePlugin } satisfies PluginModule