Codicil

Durable, searchable documentation for MCP-compatible coding assistants.

Codicil indexes the documentation already in a repository and exposes two MCP tools:

`query_docs` for retrieval and `reindex_docs` for 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.

What It Does

• Indexes `.md`, `.mdx`, `.rst`, `.txt`, `.yaml`, `.yml`, and `.toml` files.
• 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 `.codicil` are

excluded. Files with no indexable content are recorded as empty and remove any older chunks.

Quick Start

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 .

`serve` starts 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 and `query_docs` still searches the files directly.

Run the offline test suite with:

./.venv/bin/python -m pytest -q

Connect an MCP Client

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, adjusting `command` to the

absolute path of the installed `codicil` executable when necessary. The path passed to `serve`

is the repository Codicil indexes.

Your client can then call:

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 same `query_docs` function 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_results` should be between 1 and 10. `reindex_docs()` is the supported way to refresh an

index while the MCP server owns the store.

Embeddings and Fallback

By default Codicil calls `http://localhost:11434/api/embeddings` with the

`nomic-embed-text` model. 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 .

For `nomic` models, 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_docs`

uses 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

Configuration is read when the server module starts, so set environment variables before

running `codicil` or launching your MCP client.

Changing `CODICIL_EMBED_MODEL` selects a separate collection and state file, avoiding

incompatible vector dimensions. Run `codicil index` after changing models; existing collections

remain in the store until you deliberately remove the store while no Codicil process is running.

Operations and Limitations

`codicil index [path]` indexes a repository and exits. Add `--force` to 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. Starting `codicil index` while `codicil

serve` owns the same store fails intentionally. Use `reindex_docs` from 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.

Troubleshooting

• “store is already in use”: another Codicil process owns `CODICIL_STORE`. Stop it, or call

`reindex_docs` through that running MCP server.

• Keyword results instead of scores: the embedding endpoint is unavailable or the selected

model has not been indexed yet. Check `CODICIL_EMBED_URL`, then run `codicil 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 run

`codicil index`. This permanently removes all local collections for that store.

For development details and reliability invariants, see CLAUDE.md. For a more

detailed installation guide, see docs/SETUP.md.

License

Released under the MIT License.