Skip to main content

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 17 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, automatic graph refresh, and the code-review methodology itself — a code_review skill and a catalogue of parameter-checked review recipes (run_recipe_query) served for every graph. opencode is set up and verified end to end — including a config that needs no absolute paths — and codingest skill install packages the review skill for Claude Code and Codex, which opencode also discovers with no extra step.
  • 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, Julia, R, and AGC assembly — capabilities per language in docs/languages.md.
  • 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
codingest query -g /path/to/repo/.kglite/code-review.kgl \
  "MATCH (f:Function)-[:CALLS]->(g:Function) RETURN f.name, g.name LIMIT 20"
kglite describe /path/to/repo/.kglite/code-review.kgl --connections

codingest query prints unbounded TSV to stdout (use --format csv|json, or Cypher LIMIT to bound rows), warns on stderr when the graph has gone stale, and with --require-fresh refuses a stale graph with exit code 3 — see docs/cli.md.

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.21.4 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.2"
kglite = "0.21.4"
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 and codingest's code_review skill + recipe catalogue registered as the producer's methodology.
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 --workspace --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 --workspace --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.21.4 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.

Metadata

Release files for codingest 0.2.34

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for codingest 0.2.34
File Size Uploaded Provenance Actions
codingest-0.2.34.tar.gz 508.1 kB With provenance Details for codingest-0.2.34.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for codingest 0.2.34
File Actions
codingest-0.2.34-cp312-abi3-win_amd64.whl CPython 3.12 abi3 Windows x86-64 Details for codingest-0.2.34-cp312-abi3-win_amd64.whl
codingest-0.2.34-cp312-abi3-manylinux_2_28_aarch64.whl CPython 3.12 abi3 Linux glibc 2.28+ ARM64 Details for codingest-0.2.34-cp312-abi3-manylinux_2_28_aarch64.whl
codingest-0.2.34-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.12 abi3 Linux glibc 2.17+ x86-64 Details for codingest-0.2.34-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
codingest-0.2.34-cp312-abi3-macosx_11_0_arm64.whl CPython 3.12 abi3 macOS 11.0+ ARM64 Details for codingest-0.2.34-cp312-abi3-macosx_11_0_arm64.whl
codingest-0.2.34-cp312-abi3-macosx_10_12_x86_64.whl CPython 3.12 abi3 macOS 10.12+ x86-64 Details for codingest-0.2.34-cp312-abi3-macosx_10_12_x86_64.whl

Total release size: 82.3 MB

Release files / codingest-0.2.34.tar.gz

Download URL codingest-0.2.34.tar.gz
Size 508.1 kB
Tags Source
SHA-256 checksum
How to use checksums
9a5bfe968f241b507fdfda9a8250f746e502b3cb73cc8dff2a00fc5f8fb3ffb9
BLAKE2b-256 checksum
How to use checksums
ec2e8a0c2a3ae933f2315caec0e19ea4df9bc33697fb7f3be2e5b0192878e065
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / codingest-0.2.34-cp312-abi3-win_amd64.whl

Download URL codingest-0.2.34-cp312-abi3-win_amd64.whl
Size 17.3 MB
Tags CPython 3.12 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
5e332d510f43b1e3802c726f225f2382768d544c2228319c712993a17dfa412e
BLAKE2b-256 checksum
How to use checksums
2d1b97469ffda4ce0136d079f5868f2db56d44b5351d16007a7a733cfc9947a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / codingest-0.2.34-cp312-abi3-manylinux_2_28_aarch64.whl

Download URL codingest-0.2.34-cp312-abi3-manylinux_2_28_aarch64.whl
Size 15.8 MB
Tags CPython 3.12 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
ef52f07ca7ad761536dd39ad749d7ce914951a630b08374260f59e107ee9468f
BLAKE2b-256 checksum
How to use checksums
ebfcabc88c6641e69ce1b44cc49c262294a85fec8da2eb2d5b83e478b19b25d0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / codingest-0.2.34-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL codingest-0.2.34-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 16.9 MB
Tags CPython 3.12 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
187030131b2d3d03d4c943ede6188d13c67379ffa74c927b0f73cfc6204276f5
BLAKE2b-256 checksum
How to use checksums
f00452c2d22fe0a44c29621a1b7af2233a83480cd21eb3cf9ee36d10108f3c09
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / codingest-0.2.34-cp312-abi3-macosx_11_0_arm64.whl

Download URL codingest-0.2.34-cp312-abi3-macosx_11_0_arm64.whl
Size 15.5 MB
Tags CPython 3.12 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
047d9575f7a48e86e7b266df20047196ce8531fb6f54038dd681031dfe46c807
BLAKE2b-256 checksum
How to use checksums
46e492eb06afe8daaeecaafd0a258881b850bc12032b61d5c7d6501bd84c3116
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Release files / codingest-0.2.34-cp312-abi3-macosx_10_12_x86_64.whl

Download URL codingest-0.2.34-cp312-abi3-macosx_10_12_x86_64.whl
Size 16.3 MB
Tags CPython 3.12 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
3425d607b75bbceba05a95f4ce19176efbfa301c1a70e23343aabf675d672bee
BLAKE2b-256 checksum
How to use checksums
073aea49653a16da911e001ba06710984ad83ce79874b21e0e55ba29c8c02a1c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

Security for codingest 0.2.34

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for codingest-0.2.34.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 29, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.34 This release

6 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page