codicil

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.

Variable	Default	Meaning
CODICIL_REPO	.	Repository to index. The CLI sets this from its path argument.
CODICIL_STORE	<repo>/.codicil	Local Chroma data, index state, and lock file.
CODICIL_EMBED_URL	http://localhost:11434	Base URL of the Ollama-compatible embedding host.
CODICIL_EMBED_MODEL	nomic-embed-text	Embedding model requested from the host.
CODICIL_EMBED_WORKERS	3	Concurrent embedding requests during indexing.
CODICIL_MIN_SCORE	0.5	Minimum semantic similarity score returned by query_docs.

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.