CIDX — CODE INDEX FOR AI CODING AGENTS

THE PROBLEM

AI coding assistants answer questions about a codebase by reading raw files into their context window. On a large repository this is slow, expensive and lossy: the assistant sees a wall of text instead of structure, and often misses where a function is actually defined or used.

cidx solves this by building a local, structured index of the code and answering questions from that index instead.

WHAT IT DOES

- Indexes a repository with zero configuration. No setup files, no server, no cloud service.

- Answers carry locations and signatures rather than file contents, so an agent gets precise, compact answers.

- Each reference is tagged by how it resolved, so the agent knows how much to trust a given match.

- Runs entirely on the developer's own machine. No code leaves the laptop.

HOW IT WORKS

1. Parsing. tree-sitter parses Python and TypeScript/JavaScript source into syntax trees.

2. Extraction. Symbols and references are extracted per file and written into a SQLite index.

3. Resolution. Reference resolution runs across the whole repository, kept deliberately separate from per-file extraction.

4. Serving. Five read-only tools are exposed over the Model Context Protocol (MCP), the standard interface AI coding assistants use to call external tools. Responses are token-budgeted, carry freshness stamps, and fall back to grep on every miss so the agent is never left with nothing.

CORRECTNESS

The core engineering guarantee is a convergence invariant: an index updated incrementally is identical to one rebuilt from scratch.

Enforced with:

- content-hash invalidation

- one SQLite transaction per file

- a debounced file watcher with a reconciliation sweep to recover dropped OS events

Verified with:

- a Hypothesis property-based test suite over randomly generated edit, delete and rename sequences

- a crash-injection test demonstrating that no half-written index is ever left behind

VALIDATION AT SCALE

Tested against the Django codebase:

- 3,038 files indexed

- 75,787 symbols

- 205,506 references

Output is identical on Linux and Windows, and the test suite runs on a 3-OS by 3-Python continuous integration matrix on every commit.

TECH STACK

Python, tree-sitter, SQLite, Model Context Protocol, pytest, Hypothesis, GitHub Actions

STATUS AND LINKS

Published to PyPI as an open-source project under the Apache-2.0 licence, currently an alpha release under active development.

Source: https://github.com/gativarshney/cidx

Package: https://pypi.org/project/cidx