kamysh/muninn

Code search and repository knowledge for AI coding agents through MCP.
Muninn maintains a searchable code index for Codex, Claude Code and other
compatible MCP clients. Ask where a behavior is implemented, retrieve relevant
source ranges, and inspect the code before changing it.
Git worktrees share unchanged content and embeddings while keeping separate
searchable views. A search selects the checkout named by repo or cwd, so a
feature branch and the primary checkout can return their own implementations.
Combine semantic and full-text retrieval with hybrid search.
Follow recorded structural relationships and verify them against source.
Reuse unchanged indexed content across linked Git worktrees.
Store and search curated repository notes.
Muninn needs PostgreSQL with pgvector, Apache AGE and pgcrypto, an indexing
watcher, and an MCP connection. Local and hosted embedding backends are
available; hosted embeddings send selected source chunks to the provider.
Start with Getting started. Agents performing installation
use AGENTS.md.
Article: Muninn code search across Git worktrees.
## Install the binaries with Nix
With Nix installed and its nix-command and flakes features enabled, build the
CLI, watcher and MCP server without installing them:
sh
nix build github:kamysh/muninn#muninn
./result/bin/muninn --version
./result/bin/muninn-index --version
./result/bin/muninn-mcp --version
To add these programs to your user profile instead, use
nix profile add github:kamysh/muninn#muninn.
This installs binaries only. Follow Getting started to
prepare PostgreSQL and its extensions, configure embeddings, start the watcher
and connect your MCP client. No database or service is created by this package.
Use the installed absolute executable paths when configuring the watcher and
MCP client; command -v muninn-index and command -v muninn-mcp show them after
installation.
The commands follow the repository's default branch. Append a commit to the
repository address, as in github:kamysh/muninn/COMMIT#muninn, to pin a version.
## Why Muninn exists
An agent repeatedly exploring a large codebase spends context and time finding
the same implementations. Plain text search is useful when the name is known;
questions about behavior, relationships and prior repository decisions need
other entry points. Muninn maintains a searchable index and durable notes so an
agent can find relevant source, then read and verify it.
Git worktrees add a second problem: each checkout has its own files, but copying
a full chunk/vector index for every branch wastes space and embedding work.
Muninn groups linked worktrees into a repository family. It shares
unchanged file versions and embeddings, stores file differences per checkout,
and searches the checkout the caller selected. Updating the primary checkout
adjusts those differences without changing another checkout's published view.
Registration is explicit. A cheap inventory helps a human or agent choose which
files matter before the first index starts. An enabled family discovers linked
worktrees automatically and shares its configuration across them. Independent
non-Git directories can also be registered.
## What runs