codicil

Durable, searchable documentation for MCP-compatible coding assistants.

Codicil indexes the documentation already in a repository and exposes two MCP tools:query_docsfor retrieval andreindex_docsfor refreshes. It uses an Ollama-compatible embedding endpoint when one is available. If the endpoint is unavailable, search continues with a keyword fallback that reads the current files from disk.

Status: early, single-user software. The core index and fallback paths are tested, but the command-line interface and storage format may change before a stable release.

- Indexes.md,.mdx,.rst,.txt,.yaml,.yml, and.tomlfiles.
- Splits Markdown at H1 and H2 headings; other files use overlapping character chunks.
- Stores a local Chroma index in.codicil/by default.
- Returns semantic matches when embeddings are available, or keyword matches when they are not.
- Reindexes incrementally using file modification times.

Directories such as.git,.venv,node_modules,dist,build, and.codicilare excluded. Files with no indexable content are recorded as empty and remove any older chunks.

Requirements: Python 3.11+ and a Unix-like host. Codicil uses an advisory file lock to protect its local store.

python3.11 -m venv .venv ./.venv/bin/pip install -e ".[dev]" # Optional: works without an embedding server, using keyword fallback. ./.venv/bin/codicil index . ./.venv/bin/codicil serve .

servestarts the stdio MCP server. If its selected index is empty, it attempts an initial index automatically. With no reachable embedding endpoint, that initial index skips semantic embeddings andquery_docsstill searches the files directly.

The repository includes this local Claude Code configuration:

{ "mcpServers": { "codicil": { "command": ".venv/bin/codicil", "args": ["serve", "."] } } }

Place equivalent configuration in the repository you want to search, adjustingcommandto the absolute path of the installedcodicilexecutable when necessary. The path passed toserveis the repository Codicil indexes.

query_docs(query="How is the reverse proxy configured?", n_results=5) reindex_docs(force=false)

Illustrative — the Claude Code chat UI isn't something a terminal recording can reproduce.

The GIF above is real, unedited output — the samequery_docsfunction called directly in a terminal instead of over MCP. No local embedding host was running when this was recorded, so it's answering via keyword fallback, not semantic search — a live demonstration of the degrade-don't-fail behavior this project is actually about.

n_resultsshould be between 1 and 10.reindex_docs()is the supported way to refresh an index while the MCP server owns the store.

By default Codicil callshttp://localhost:11434/api/embeddingswith thenomic-embed-textmodel. Start a compatible local service to enable semantic search, then index the repository:

export CODICIL_EMBED_URL=http://localhost:11434 export CODICIL_EMBED_MODEL=nomic-embed-text ./.venv/bin/codicil index .

Fornomicmodels, Codicil automatically uses the recommended document and query task prefixes. Other model names are sent without prefixes.

If the embedding host cannot be reached, or the selected index has no chunks,query_docsuses keyword search over the repository. Keyword results rank files by matching query terms and include nearby lines; they are useful but do not understand synonyms or semantic similarity.

Using a remote embedding endpoint sends indexed text and search queries to that endpoint. Keep the default localhost URL or use an endpoint you trust. Do not commit private hostnames or credentials in.mcp.json.

Configuration is read when the server module starts, so set environment variables before runningcodicilor launching your MCP client.

ChangingCODICIL_EMBED_MODELselects a separate collection and state file, avoiding incompatible vector dimensions. Runcodicil indexafter changing models; existing collections remain in the store until you deliberately remove the store while no Codicil process is running.

codicil index [path]indexes a repository and exits. Add--forceto ignore recorded mtimes and re-embed every indexable file.codicil serve [path]runs the MCP server.

Only one Codicil process may use a store at a time. Startingcodicil indexwhilecodicil serveowns the same store fails intentionally. Usereindex_docsfrom the running MCP server, or stop the server before running the CLI indexer.

Codicil is currently designed for one local repository and one user. It does not provide file watching, git hooks, multi-user access, or cross-repository retrieval.

- “store is already in use”: another Codicil process ownsCODICIL_STORE. Stop it, or callreindex_docsthrough that running MCP server.
- Keyword results instead of scores: the embedding endpoint is unavailable or the selected model has not been indexed yet. CheckCODICIL_EMBED_URL, then runcodicil index.
- No matching files: confirm the file extension is supported and it is not in an excluded directory. Queries with only words of two characters or fewer have no fallback search terms.
- Need a clean rebuild: stop every Codicil process, then remove the local store and runcodicil index. This permanently removes all local collections for that store.

For development details and reliability invariants, seeCLAUDE.md. For a more detailed installation guide, seedocs/SETUP.md.

Local-first MCP server that indexes folders, PDFs, code, and past AI conversations — and exposes them as a single grounded-search tool. Runs fully offline.