mimry 0.6.1

Finds the files a coding task touches, so your agent reads less.

On 92 real pull requests, agents read 50% fewer tokens with MIMRY.

If MIMRY saves your agent tokens, please star it.

MIMRY is a command-line tool that tells AI coding agents which files, and which lines in them, to read for a task. It parses a repository into symbols and a dependency graph, keeps the index on your machine, and ranks the files that matter for a task described in plain words. The index is deterministic: the same code gives the same graph, rankings and context pack on Windows, Linux and macOS, and no LLM is involved in building it. Agents call it from the shell or through its MCP server.

Installation

uv tool install mimry

Requires Python 3.11 or newer on Windows, Linux or macOS. pipx install mimry and pip install mimry also work.

The first index downloads the tree-sitter grammars it needs, once per user, and keeps them in a cache.

Docker

The image ghcr.io/jbacalso24/mimry has every tree-sitter grammar built in, so indexing needs no network. Tags are latest, the full version such as 0.5.0, and the minor line such as 0.5.

Mount your repo at /repo and keep the index in a named volume at /cache. Without the volume, each container starts with no index. On Linux, add --user "$(id -u):$(id -g)" so the .mimry/ folder MIMRY writes in your repo belongs to you.

docker run --rm -v "$PWD:/repo" -v mimry-cache:/cache ghcr.io/jbacalso24/mimry init
docker run --rm -v "$PWD:/repo" -v mimry-cache:/cache ghcr.io/jbacalso24/mimry index
docker run --rm -v "$PWD:/repo" -v mimry-cache:/cache ghcr.io/jbacalso24/mimry find "<query>"

For an agent, run the MCP server over stdio with the same mounts:

docker run -i --rm -v "$PWD:/repo" -v mimry-cache:/cache ghcr.io/jbacalso24/mimry mcp

In an MCP client config, use the repo's absolute path, because $PWD is not expanded there:

{
  "mcpServers": {
    "mimry": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "/absolute/path/to/repo:/repo", "-v", "mimry-cache:/cache", "ghcr.io/jbacalso24/mimry", "mcp"]
    }
  }
}

Claude Code plugin

In Claude Code, the plugin gives the agent the MIMRY skill, the hooks and the MCP server in one step. It needs uv on your PATH and nothing else.

/plugin marketplace add jbacalso24/mimry
/plugin install mimry@mimry

It replaces mimry install --platform claude-code, so use one or the other.

Other agents: npx skills

It installs the skill only; for the MCP server and hooks, run mimry install --platform <name> (see Supported agents).

npx skills add jbacalso24/mimry

Quick start

Run mimry preflight in your repository with a task description. The first run builds the index.

mimry preflight "Fix session cookie not refreshed when SESSION_REFRESH_EACH_REQUEST is set"

Output on the Flask repository:

Start with
   1  src/flask/sessions.py
      name matches · path matches · connected to other matches
      read first: lines 202-206 (get_cookie_secure), 233-247 (should_set_cookie)
   2  src/flask/ctx.py
      name matches · connected to other matches
      read first: lines 154-206 (copy_current_request_context), 395-403 (session)
   3  src/flask/testing.py
      name matches · connected to other matches
      read first: lines 135-183 (session_transaction), 193-202 (_request_from_builder_args)

The same result is written to .mimry/mimry-out/context/latest.md as a context pack for the agent, with the matched symbols, related files and the project's test commands.

To have your agent use MIMRY on its own, install it for that agent:

mimry install --platform claude-code

Features

Supported languages

MIMRY parses these languages with tree-sitter for symbols, imports, calls and inheritance.

Fortran is read in free form only. Fixed-form .f and .for files do not parse with the grammar MIMRY uses, so they get no symbols or edges.

.pp and .m are checked first, because most .pp files are Puppet and most .m files are MATLAB. A .pp file is Pascal only when it has a unit, program or library line, and a .m file is Objective-C only when it has an @interface, @implementation, @protocol or #import line. Any other .pp or .m file is indexed as searchable text with no symbols.

The markup and style languages get what an agent searches them by. CSS and SCSS give their class and id selectors, custom properties, keyframes, Sass mixins, functions, placeholders and variables, with @import, @use and @forward as imports. HTML gives each element id and the local stylesheets and scripts it loads. Vue and Svelte give each component (named after its file) and run the JavaScript or TypeScript and CSS or SCSS passes over their <script> and <style> blocks, so their line numbers match the file.

MIMRY also indexes Markdown (headings, links, frontmatter), plain text, PDF, Word, Excel and PowerPoint files. Results name the page, section, sheet or slide that matches.

Some files get more structure than their text:

• SQL: .sql files give their schema objects and the tables they touch, see below. Python string literals keep their CREATE TABLE names, and Alembic migrations keep their revision lineage.
• Groovy and Gradle: .groovy, .gradle and .gvy files give their classes, interfaces, traits, enums, methods and functions, and the task entries of a Gradle build, see below.
• Manifests: package.json, pyproject.toml, tsconfig.json, vite.config.*, next.config.*, app.json, app.config.*, .env.example, CLAUDE.md, AGENTS.md and README.md give their commands, frameworks, entry points and env variable names, never values.

The data formats get the names an agent looks them up by. JSON, YAML and TOML give their keys to depth two, named by path, such as services.web or tool.ruff.line-length, and TOML also gives each table header. A YAML document that is a Kubernetes object also gives a <kind>/<name> resource, such as Deployment/web. XML gives each element with an id or name attribute, and a Maven pom.xml gives its groupId:artifactId. Terraform gives each resource, data, module, variable, output, provider and locals entry under the name it is referenced by, such as aws_s3_bucket.b, data.aws_iam_policy_document.p, module.bucket, var.region and local.name. A var.region reference finds the variable in the same folder, and a module's local source links to its folder. Values are never symbols, so a secret stored as a value is never indexed. Lock files and files over 256 KB get no symbols, and manifests keep their own adapter above. Every data file is also indexed as text, so mimry find matches its content.

SQL files name each schema object as the source writes it, such as public.users: tables, views, materialized views, indexes, sequences, schemas and types, and functions, procedures and triggers. A view, function, trigger or index that reads or writes a table gets a call edge to it, and so does a foreign key's REFERENCES target. A plain query or an ALTER TABLE belongs to no object, so it adds no edge. A statement the parser does not know costs only itself, and the objects around it are kept. A trigger written with a BEGIN ... END body gives its name and table, but its body is not read. Files over 256 KB get no symbols, so a large dump stays text-searchable.

Groovy and Gradle files name each class, interface, trait, enum, method and top-level def function as the source writes it. A Spock feature method keeps its string, such as adds two numbers, as its name. A Gradle task name or tasks.register("name") gives a task, and plugins {} and dependencies {} entries are not symbols. An import of a Groovy class links exactly to the file that declares it, and a wildcard import such as a.b.* links to every file of package a.b. Calls inside a method body, and the extends and implements clauses of a type, give call and inheritance edges, and a paren-less name arg call counts only for a method of the same file. A piece of a file the parser cannot read costs only itself, so an annotated type such as @Service(Book) keeps its methods. Closure-assigned fields and operator methods such as << are not symbols.

Other extensions can be mapped to a supported language in mimry.toml, see Configuration.

Supported agents

mimry install --platform <name> installs a skill that teaches the agent when to use MIMRY, and registers the MCP server where the agent supports it.

✅ means mimry install sets it up, and manual means you add the MCP server by hand. none means the agent has no MCP support, so the skill alone covers it. not yet means mimry install does not register an MCP server for the agent yet.

See docs/agents.md for where each agent's files go and how its MCP server is registered.

claude mcp add --scope user mimry -- mimry-mcp   # Claude Code
codex mcp add mimry -- mimry-mcp                 # Codex

{
  "mcpServers": {
    "mimry": { "command": "mimry-mcp" }
  }
}

Usage

mimry preflight "<task>"            # list the files and lines to read first, and write a context pack
mimry find "<query>"                # rank files for a query
mimry symbol <name>                 # find where a function, class or heading is defined
mimry callers <name>                # list the functions that call a function, from the graph
mimry callees <name>                # list the functions a function calls, from the graph
mimry related "<query>"             # list files connected through imports and calls
mimry explain "<task>"              # show the key files and symbols, and how they connect
mimry why <file> --query "<task>"   # explain why a file ranked
mimry feedback ...                  # record which files helped
mimry status                        # check whether the index is current
mimry doctor                        # diagnose the install and the index

See docs/commands.md for every command and option. When something misbehaves, see docs/troubleshooting.md.

Configuration

A mimry.toml at the repository root controls which files are indexed. Commit it so everyone on the team gets the same index.

[index]
include = ["src/**", "docs/**"]            # index only these paths
exclude = ["**/fixtures/**", "legacy/**"]  # never index these paths
max_file_bytes = 2_000_000                 # size limit per file (default 1 MB)

[index.languages]
".inc" = "php"                             # parse .inc files as PHP
".h" = "cpp"                               # parse .h headers as C++ instead of C

Benchmarks

Tokens an agent read before it found the code each pull request changed, measured on 92 merged pull requests from 12 open-source projects.

See benchmarks/tokens for the method, per-project results and how to reproduce them.

On the 500 issues of SWE-bench Verified, one mimry find with the issue text puts every file the fix changes in the top 10 for 74.6% of issues, in the top 5 for 63.8%, and first for 34.8%. See benchmarks/localization for the protocol and per-repository results.

To measure MIMRY on your own repository's merged pull requests, run mimry bench; see Benchmark your repository.

One task, start to finish

Task fastapi/typer#1820 from the holdout2 run: "Respect wait=False when launching URLs with xdg-open". The fix changed typer/main.py. Its 75.3% saving is the median for that run, so it is a typical task, not the best one.

Without MIMRY

The agent runs seven keyword searches for respect, wait, false, launching, urls, xdg and open, which cost 1,927 tokens. It then reads typer/main.py from the top, up to the benchmark's 2,000-line limit per read, which costs 13,491 tokens. Total: 15,418 tokens.

With MIMRY

mimry preflight "Respect wait=False when launching URLs with xdg-open" costs 1,876 tokens. The agent then reads six line ranges in the order of the context pack, which cost 1,937 tokens:

Total: 3,813 tokens.

MIMRY opened six files instead of one and still read 75.3% fewer tokens: 3,813 against 15,418.

The numbers come from results.holdout2.ranges.0.4.1.json, measured with MIMRY 0.4.1 in token benchmark run 38884765315. To reproduce them, see Running it.

How it works

1. Index. MIMRY parses each file into symbols and edges for imports, calls and inheritance, and stores the index in your user cache directory, outside the repository.
2. Rank. MIMRY matches a task against file names, paths, content, symbols and the graph, and drops imports it cannot resolve rather than guessing.
3. Refresh. Like Git, MIMRY compares file metadata and re-reads only the files that changed.

See docs/how-it-works.md for details.

Privacy

Indexing and search run locally. Credential files are skipped, secret-looking values are redacted from feedback, and untracked files named in .gitignore are not indexed.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md for setup and checks. MIMRY is in public alpha, and its interfaces may change before 1.0.

Thanks to everyone who has contributed:

License

MIT