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

Related MCP server: graphward

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.

Maintained project documentation

Before development or independent review, read this README for the project workflow, PLAN.md for requirements and design decisions, CONTRACTS.md for shared interfaces and invariants, and the affected usage, extension or schema guide. These existing documents are the maintained repository documentation; an issue tracks work and links the relevant documents rather than replacing them.

Update affected workflows, requirements, contracts and design decisions in the same change as the behavior they describe. Record a changed decision and its reason in the existing plan or affected contract, preserving dated evidence and explicitly separating proposed, implemented and exercised behavior. Independent review checks that documentation matches the exact change and retains intended behavior that has not shipped. Reuse these documents instead of adding another specification or task backlog.

Historical shipped labels, paths and command examples require confirmation against the selected source/runtime before use. Recovered local branches, draft designs, indexes and qualification receipts remain separate evidence until they are explicitly reviewed and integrated. Publishing these instructions does not install a runtime, connect MCP, refresh a graph or establish that a loader has included the complete text in an existing session.

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.