codingest

CI crates.io PyPI Docs License: MIT

Give AI agents a live, queryable map of any codebase — locally, privately, and without running the code you are analysing.

codingest turns polyglot source into a KGLite knowledge graph of functions, types, calls, imports, inheritance, routes, documentation, and git revisions. Use it from Python, the command line, or as an MCP server for coding agents.

pip install codingest

import codingest

graph = codingest.build(".")
graph.cypher("MATCH (f:Function) RETURN f.name LIMIT 10")

No language servers, databases, or repository-specific build steps are required. The native Rust builder bundles parsers for 15 languages and returns a real kglite.KnowledgeGraph, ready for Cypher queries.

Built for agents and code analysis

  • Agent-ready MCP: give an MCP client graph_overview, cypher_query, read_code_source, repository switching, and automatic graph refresh.
  • Fast local review: map definitions, callers, dependencies, routes, inheritance, and affected tests without uploading or executing the project.
  • Open-source intelligence: clone and analyse a GitHub repository with one Python call, or let an agent manage cached public repositories through MCP.
  • Polyglot by default: one graph across Python, Rust, TypeScript, JavaScript, Java, Go, C/C++, C#, Swift, PHP, HTML, CSS, Dart, and AGC assembly.
  • Revision-aware: analyse a tag, branch, commit, or multiple revisions in one graph and query what changed.

AGC assembly receives architecture-aware control and data relationships rather than a generic text-level call graph; see the AGC graph model.

Give your agent a code-review MCP server

pip install codingest
codingest-mcp --watch /absolute/path/to/repo

Point an MCP client at the same command:

{
  "mcpServers": {
    "code-review": {
      "command": "codingest-mcp",
      "args": ["--watch", "/absolute/path/to/repo"]
    }
  }
}

The server builds the graph at startup, refreshes it when source files change, and gives the agent schema discovery, Cypher, and source-reading tools over stdio. For a multi-repository agent sandbox with runtime set_root_dir, use the local-workspace manifest described in the MCP guide.

For a zero-configuration CLI workflow, install the packaged code-review Agent Skill instead:

pip install codingest
codingest skill install

The skill teaches compatible agents to build a fresh graph, discover its schema before querying, combine Cypher with the git diff, and verify findings against source lines. See the MCP guide and CLI guide.

Analyse a local codebase

import codingest

graph = codingest.build(
    ".",
    include_docs=True,
)

rows = graph.cypher("""
MATCH (caller:Function)-[:CALLS]->(target:Function)
RETURN target.qualified_name, count(caller) AS callers
ORDER BY callers DESC
LIMIT 10
""")

codingest.build(".", save_to="code-review.kgl")

The bundled terminal command offers the same workflow:

codingest build /path/to/repo
codingest status --output /path/to/repo/.kglite/code-review.kgl
kglite describe /path/to/repo/.kglite/code-review.kgl --connections

Analyse an open-source repository

import codingest

graph = codingest.repo_tree("pallets/flask")
graph.cypher("""
MATCH (route:Function)-[:CALLS]->(dependency:Function)
RETURN route.qualified_name, dependency.qualified_name
LIMIT 25
""")

repo_tree() shallow-clones the requested repository into a temporary directory, builds the graph, and cleans up afterward. Pass branch=, clone_to=, or token= for a specific revision, a reusable cache, or a private repository.

Compare revisions

graph = codingest.build(".", revs=["v1.0", "v2.0"])
graph.cypher("""
MATCH (f:Function)
WHERE 'v2.0' IN f.revs AND NOT 'v1.0' IN f.revs
RETURN f.qualified_name
""")

Revision builds use tracked git content without changing the working tree. Multi-revision graphs store shared entities once and expose revision membership for direct Cypher analysis.

Install options

pip install codingest          # Python API + CLI + MCP server + KGLite runtime
codingest skill install        # code-review Agent Skill

The wheel bundles every grammar plus the codingest and codingest-mcp commands. KGLite ≥0.15.3 is installed automatically as the query/storage engine; its MCP server and the transitive mcp-methods framework power the builder-aware Codingest server. Nothing else needs to be installed.

Rust-only environments can instead use cargo install codingest-cli codingest-mcp; these are alternative distributions of the same commands, not Python prerequisites.

Rust crate

[dependencies]
codingest = "0.1"
kglite = "0.15.3"

use codingest::build_code_tree;

let graph = build_code_tree(
    dir,
    false, // verbose
    true,  // include tests
    None,  // save path
    None,  // max lines per file
    false, // include docs
)?;

How it fits together

codingest owns code-graph construction, the Python/CLI interfaces, the builder-backed MCP executable, and the code-review Agent Skill. KGLite provides the graph engine, Cypher, persistence, and reusable query/read tools. Keeping that boundary explicit lets codingest focus on accurate code understanding while reusing a dedicated graph engine.

Documentation: codingest.readthedocs.io

Workspace layout

Crate What it is
crates/codingest The component library (codingest): builder, parsers, manifest reader, docs pass, multi-rev merge, cross-language edges. Extracted from the former KGLite/crates/kglite/src/code_tree/ (removed upstream 2026-07-16) and re-targeted at the public kglite::api facade. Ships the codingest_stats + codingest_bench binaries.
crates/codingest-cli codingest binary — build a checkout or git revision(s) into a .kgl graph, status to check staleness, and skill to install Codingest's code-review Agent Skill.
crates/codingest-mcp codingest-mcp binary — the full MCP tool surface imported from the kglite-mcp-server library, with the codingest builder injected.
crates/codingest-py PyO3 wrapper built by maturin into the codingest wheel (pip install codingest). Python package source is codingest/; pyproject.toml drives the maturin build. Not published to crates.io (publish = false).

CI-equivalent local gate

cargo build --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo test -p codingest --test parity

The golden-digest oracle (also the determinism gate)

KGLite deleted its in-tree code_tree builder on 2026-07-16, so the old two-builder parity sweep is gone. The authority it enforced was frozen while the builders were still verified identical, into per-corpus SHA-256 digests under crates/codingest/tests/goldens/ (committed fixtures — no network). The golden_parity test builds each corpus three times with only the codingest builder, digests a canonical exhaustive graph rendering, and requires every build to match every other build and the frozen golden. Repeating the build is what makes this the determinism gate: hash iteration order is randomized per HashMap, so an order-dependent builder fails it (the tests/corpus/dup_minified_assets fixture reproduces the original DEFINES-edge nondeterminism bug). Disagreement between builds is reported as NONDETERMINISM; agreement between builds but not with the golden is reported as a behaviour change. The multi-rev fixture is guarded instead by rev_self_consistency. Regenerate goldens only for deliberate builder-behavior changes: cargo test -p codingest --test parity -- --ignored capture_goldens (details in crates/codingest/tests/goldens/README.md).

Everything the gate needs is committed to this repository, so it is hermetic and runs in CI. It replaced a local-only make step that asserted an exact edge count against a sibling checkout — a verdict this project did not control. make determinism-soak REPO=… keeps the large-repo reproducer available as a diagnostic.

Dependency policy

kglite and kglite-mcp-server use matching crates.io requirements with a 0.15.3 minimum and a shared lockfile. This keeps the builder, persistence handoff, and embedded MCP server on one compatible engine patch line.

Parity with the (now-removed) in-tree component

codingest was extracted to be feature- and performance-identical to kglite's in-tree code_tree. KGLite removed that module on 2026-07-16, so parity is now enforced against a frozen record of its last-known-good output rather than live cross-comparison. See PARITY.md (stats-diff + timing), BENCHMARKS.md (build-time + Cypher benchmarks), crates/codingest/tests/parity.rs (the golden oracle), and docs/mcp-parity.md (the MCP↔builder coupling and the hook).

tests/python-legacy/ preserves KGLite's full 47-file kglite.code_tree behavioral suite verbatim as the dormant behavioral spec — the source of truth for what the Python builder guaranteed (see its README).

License

MIT © Kristian dF Kollsgård. codingest is an independent project; it depends on kglite at runtime but is not otherwise affiliated with it.

Project links

Data verified by PyPI on Jul 30, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for kkollsg from gravatar.com kkollsg

Credits

Author: Kristian dF Kollsgård

GitHub Statistics

Data verified by PyPI on Jul 30, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Tags

ai-agents mcp code-review knowledge-graph code-analysis github tree-sitter cypher

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

codingest-0.1.4.tar.gz (280.3 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

codingest-0.1.4-cp310-abi3-win_amd64.whl (11.2 MB view details)

Uploaded CPython 3.10+Windows x86-64

codingest-0.1.4-cp310-abi3-manylinux_2_28_aarch64.whl (10.3 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

codingest-0.1.4-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (11.1 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

codingest-0.1.4-cp310-abi3-macosx_11_0_arm64.whl (10.2 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

codingest-0.1.4-cp310-abi3-macosx_10_12_x86_64.whl (10.7 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file codingest-0.1.4.tar.gz.

File metadata

  • Download URL: codingest-0.1.4.tar.gz
  • Upload date:
  • Size: 280.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for codingest-0.1.4.tar.gz
Algorithm Hash digest
SHA256 7cabb125115bece13b70e0847cc3c7a90cd7f16c3375d3282db36a21d0af2603
MD5 e115ed4acf9681750d8edcf17a3924a0
BLAKE2b-256 d5595a6dd6e8e42602eca13be83f03d2014fb81674e78819c4a0f7eee1983894

See more details on using hashes here.

Provenance

The following attestation bundles were made for codingest-0.1.4.tar.gz:

Publisher: release.yml on kkollsga/codingest

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codingest-0.1.4-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: codingest-0.1.4-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 11.2 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for codingest-0.1.4-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 98a40af671419b86ebfba4002f22679989bf068f6900cf8b493a5c6f272fa952
MD5 23c4d0c35bd20ca4cb7cdaba767b03ea
BLAKE2b-256 2cfd011bfc2199b902255fb1406de4420faecf08b6cb346cdf120faecf8e480c

See more details on using hashes here.

Provenance

The following attestation bundles were made for codingest-0.1.4-cp310-abi3-win_amd64.whl:

Publisher: release.yml on kkollsga/codingest

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codingest-0.1.4-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for codingest-0.1.4-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 9a396033360aac8459d15e203ca6c5970cca9ee55e628103fb3ce124d53bfc9c
MD5 c55effb8d38f5fdaba8217bc5c232456
BLAKE2b-256 0fd99020f7759334c594ab10719e6c8995aa08a64c3b4df8f0e9aa07cd436003

See more details on using hashes here.

Provenance

The following attestation bundles were made for codingest-0.1.4-cp310-abi3-manylinux_2_28_aarch64.whl:

Publisher: release.yml on kkollsga/codingest

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codingest-0.1.4-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for codingest-0.1.4-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 b1b928f17a7eef44a3cf36ff459397f4a28735a410236f6b96123ea3d99951eb
MD5 9d92dca30d9ea3afd970762c80e3d994
BLAKE2b-256 dd152ea46a73370f449de2d8fbb128e0fca104e2a0b6dd46d9bc11e3ca2af5df

See more details on using hashes here.

Provenance

The following attestation bundles were made for codingest-0.1.4-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on kkollsga/codingest

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codingest-0.1.4-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for codingest-0.1.4-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 91c09663197ec1b74139d235a6c068434a18f5ada9b5f21f8c7541477903109b
MD5 3c3a234413e9c73405e7bd3b05995a67
BLAKE2b-256 7d78c0847fde42af1adeed14aa0448b5488a29c74a9b352d7950c3203b824752

See more details on using hashes here.

Provenance

The following attestation bundles were made for codingest-0.1.4-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on kkollsga/codingest

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file codingest-0.1.4-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for codingest-0.1.4-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 38bcda347a382fc9a628a6f624c2f11dd8ebcc59d66b88f94dce3aa59460934a
MD5 53920e64ce18cc7a9e7f954fd7e51530
BLAKE2b-256 fa1e0605d246f731f455885ebd8ae6b1d997d49ca3ded1af992368a82e0fb00c

See more details on using hashes here.

Provenance

The following attestation bundles were made for codingest-0.1.4-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on kkollsga/codingest

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page