codeintel

codeintel is a uv-managed Python 3.12 code-intelligence platform. It reads configured repositories without modifying them, extracts deterministic fact JSON, and loads those facts into an embedded Kuzu graph for canned queries, raw Cypher, drift checks, maps, and MCP access.

Outputs live under out/<target>/; target repositories stay read-only.

Install (system-wide)

uv tool install --editable /home/hermes/code-intel

Puts codeintel on PATH (~/.local/bin), runnable from any directory. Editable: platform changes take effect without reinstalling. Targets can be referenced by name or root path:

codeintel findings ~/beancounter
codeintel brief ~/beancounter --about classify_scan_type

Quickstart

codeintel targets
codeintel index beancounter          # or: codeintel index ~/beancounter
codeintel query beancounter files-by-component
codeintel refresh beancounter
codeintel findings beancounter
codeintel mcp beancounter

(Inside the repo, uv run codeintel … works too and always uses the project venv.)

The query graph uses one Node table and one Edge relationship table. Contract kinds such as File, Route, Dependency, CALLS, and HANDLED_BY are stored in the kind property.

Docs

• Usage: install, index, refresh, and validated Cypher examples.
• New Target: target YAML schema and component guidance.
• Extending: adding extractors and deterministic fact rules.
• Schema: implemented node and edge kinds.

v1 Status

The v1 surface is intentionally thin: extractors write facts, the loader rebuilds a local Kuzu graph, and query tools read that graph. The richer extractors are optional registry modules, so a target can still index when a specific extractor is absent or fails. Drift snapshots are written by refresh; facts themselves remain timestamp-free for deterministic diffs.