# repofind

Finding code in a repository you have never opened
usually starts with a guess: a word to grep, a filename
to try. repofind replaces the guessing with an index.
Point it at a local directory and it walks the tree —
skipping `.git`, `node_modules`, files over a megabyte,
and anything outside a source-and-text extension
allowlist — splits each file into consecutive 40-line
chunks, and ranks those chunks against your question.
One call returns the five best places to look, each with
its file, line range, the chunk text, and a score.

Ranking is hybrid. A pinned BM25 scorer (k1 = 1.2,
b = 0.75) over the chunk texts always runs. When a
`TAKARA_API_KEY` is present in the environment, an
embeddings step joins in: the query and the chunks are
embedded through an OpenAI-compatible endpoint and each
chunk's final score becomes `bm25 + 10 * max(0,
cosine)`. Without a key — or if the embedder fails —
the result says so plainly in its `notes` and ranks by
keyword alone. By default only the best hit per file is
kept, so five hits mean five different files to open.

The other tools cover the rest of the exploration loop.
`locate` finds an exact substring — an env var, a
symbol, an error code — and reports it as a count, a
file list, bare locations, or full lines. `expand`
takes a hit you already have and returns its chunk plus
the neighbouring chunks in the same file. `find_related`
takes the same anchor and ranks chunks from every other
file against it. `read_benchmark` rolls up saved
benchmark-mode queries into a token-savings total. The
original product's `auth` tool is not part of this
rebuild: its interactive device login and AWS-profile
validation cannot be reproduced from the published
spec, so the surface here is five of the six tools.

## CLI

```bash
npx @reneturcios/repofind search '{"query": "retry backoff logic", "repo": "."}'
npx @reneturcios/repofind locate '{"literal": "DATABASE_URL", "mode": "locations"}'
npx @reneturcios/repofind expand '{"file_path": "src/client.ts", "anchor_line": 83}'
npx @reneturcios/repofind find_related '{"file_path": "src/client.ts", "anchor_line": 83}'
npx @reneturcios/repofind read_benchmark '{}'
npx @reneturcios/repofind --version
```

Each tool subcommand takes the tool's arguments as one
JSON string and prints the result as JSON. Exit codes:
`0` on success, `1` on a runtime error, `2` on a usage
error.

Environment variables: `TAKARA_API_KEY` enables the
semantic half; `MIRU_OPENAI_BASE_URL` (default
`https://infer.takara.ai/v1`) and
`MIRU_OPENAI_EMBEDDING_MODEL` (default `ds1-miru-int8`)
configure the embeddings endpoint;
`MIRU_MAX_INDEX_FILES` caps the index (default 10000);
`MIRU_BENCHMARK_HISTORY_PATH` overrides the benchmark
history location.

## MCP server

```bash
npx -y @reneturcios/repofind mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "repofind": {
      "command": "npx",
      "args": ["-y", "@reneturcios/repofind", "mcp"]
    }
  }
}
```

### Tools

- `search` — Hybrid semantic + keyword search over an
  indexed local codebase. Default for code exploration
  — one call per question.
  - `query` (string, required) — natural language or
    code query
  - `repo` (string, optional) — local directory to
    index; defaults to the working directory
  - `include` / `exclude` (string arrays, optional) —
    gitignore-style glob patterns against repo-relative
    paths
  - `dedupe_by_file` (boolean, default true) — keep
    the best hit per file

  Returns `{hits, ranking, notes}` with at most 5
  hits; each hit is `{file_path, absolute_path,
  start_line, end_line, anchor_line, truncated,
  snippet, score}` with the score rounded to 4
  decimals.
- `locate` — Find exact substrings (env vars, symbols,
  error codes) in an indexed local codebase.
  - `literal` (string, required); `mode` one of
    `count`, `files`, `locations`, `lines` (default
    `lines`); `limit` caps locations/lines;
    `ignore_case` (default false); `repo`, `include`,
    `exclude` as in `search`.
- `expand` — Return more context in the same file
  around a search hit: the anchor chunk plus
  neighbouring chunks.
  - `file_path` and `anchor_line` (required);
    `before` / `after` chunk counts (default 1 each).
- `find_related` — Find similar code in other files,
  from a hit's file_path and anchor_line. Returns the
  same `{hits, ranking, notes}` shape as `search`,
  with the source file excluded.
- `read_benchmark` — Cumulative token-savings rollup
  from saved benchmark-mode queries. Returns
  `{queries, total_tokens_saved,
  average_tokens_saved}`; a missing history file is a
  zero rollup, not an error.

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/repofind
docker run --rm ghcr.io/cloudcorprecords/repofind locate '{"literal": "TODO"}'
```

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (temp fixture repos, fake embedder, no network)
npm run dev     # run the CLI from source
```

## License

MIT — Copyright (c) 2026 Rene Turcios