codegraph
Index a TypeScript / Python codebase into a Neo4j property graph, then query architecture in Cypher. Designed as always-on context for Claude Code, Cursor, Codex, Aider, and other AI coding agents.
PyPI: cognitx-codegraph — install with pipx install cognitx-codegraph.
Recognises NestJS controllers / injectables / modules, React components and hooks, TypeORM entities, GraphQL operations, FastAPI / Flask / Django routes, SQLAlchemy models, plus generic Python classes / decorators. Loads typed nodes + edges into Neo4j with no LLM in the pipeline — everything is AST + deterministic resolution.
Quick start
pipx install cognitx-codegraph # core; or `pipx install "cognitx-codegraph[python,mcp,watch,analyze]"` for all extras
cd /path/to/your/repo
codegraph init # scaffolds Neo4j docker-compose, slash commands, CI gate, .arch-policies.toml; runs first index
codegraph query "MATCH (c:Class) RETURN c.name LIMIT 5"
codegraph arch-check # exit 1 on architecture violations
codegraph init is the supported onboarding path — it asks 4-5 questions, writes everything you need, starts Neo4j, and runs the first index. See docs/init.md for the full flow and flags.
CLI
| Command | Purpose |
|---|---|
codegraph init |
Scaffold codegraph into a repo (interactive). Auto-detects + reuses the shared codegraph-neo4j container (starts it if stopped, creates it if missing). Pre-flights Docker presence + version with OS-aware install / upgrade suggestions. --yes for non-interactive, --bolt-port / --http-port for custom Neo4j ports, --skip-docker, --skip-index. |
codegraph index <repo> |
Walk the source, parse with tree-sitter, write the graph. Flags: -p/--package (repeatable), --update (SHA256 incremental), --since <git-ref> (diff-based), --no-wipe, --no-export, --no-benchmark, --no-analyze, --skip-ownership, --max-files, --ignore-file, --json. |
codegraph query <cypher> |
Run a Cypher query. -n/--limit, --json. |
codegraph arch-check |
Run architecture-conformance policies. Auto-scopes to configured packages; --scope / --no-scope overrides. Exits 1 on violations, 2 on config errors. |
codegraph validate |
Sanity-check the loaded graph (counts, orphans, schema). |
codegraph audit |
Agent-driven extraction self-check. Launches claude / codex / gemini / aider / opencode / droid (or writes a cursor rules file as fallback) in headless + permission-bypass mode against the live graph; the agent flags places where codegraph claims to extract X but missed it on this repo. Output is codegraph-out/audit-report.md plus an optional gh issue create. Prompt templates protected by CODEOWNERS, a CI workflow, and a runtime SHA-256 lock. Flags: --agent, --list-agents, --print-prompt-only, --gh-issue, --bypass/--no-bypass, --unsafe, --timeout, --recompute-lock, --yes, --json. Full reference: docs/cli.md#audit. |
codegraph wipe |
MATCH (n) DETACH DELETE n. |
codegraph stats |
Quick node / edge counts. |
codegraph export |
Produce graph.html (interactive vis-network), graph.json, optional graph.graphml and graph.cypher. Runs after index unless --no-export. |
codegraph benchmark |
Token-reduction benchmark vs. raw source. Optional --min-reduction for CI gating. |
codegraph report |
Generate GRAPH_REPORT.md from Leiden community detection. Runs after index unless --no-analyze. |
codegraph watch |
File-system watcher; rebuilds on save. --debounce, -p. Requires the [watch] extra. |
codegraph hook install / uninstall / status |
Manage post-commit + post-checkout git hooks that re-index automatically. |
codegraph install <platform> |
Wire codegraph into an AI agent platform (writes rules file, registers MCP server, etc.). 14 platforms supported — see below. --all installs for every detected platform. |
codegraph uninstall <platform> |
Remove integration. Preserves shared rules sections (e.g. AGENTS.md) when other platforms still need them. |
codegraph repl |
Interactive Cypher REPL. Same as running codegraph with no args. |
MCP server
Optional extra: pipx install "cognitx-codegraph[mcp]". Console script codegraph-mcp runs a stdio FastMCP server with 16 tools. Read-only by default; the two write tools (wipe_graph, reindex_file) require --allow-write.
| Tool | Purpose |
|---|---|
query_graph(cypher, limit=20) |
Read-only Cypher (limit pushed into the query). |
describe_schema() |
Node labels, edge types, property keys. |
list_packages() |
All :Package nodes with file counts. |
find_class(name_pattern, limit=50) |
Substring search over :Class.name. |
find_function(name_pattern, limit=50) |
Substring search over :Function/:Method. Returns containing class for methods. |
describe_function(name, file=None, limit=50) |
Signature, file, callers/callees summary. |
callers_of_class(class_name, file=None, limit=50) |
Who instantiates / extends / injects a class. |
calls_from(name, max_depth=2) |
Outgoing CALLS graph from a method. |
callers_of(name, max_depth=2) |
Reverse CALLS graph. |
endpoints_for_controller(controller_name) |
NestJS / FastAPI / Flask / Django routes. |
files_in_package(name, limit=50) |
All files in a package. |
hook_usage(hook_name, limit=50) |
React components calling a hook. |
gql_operation_callers(operation_name, …) |
Who triggers a GraphQL query / mutation. |
most_injected_services(limit=20) |
Top NestJS DI providers. |
describe_group(name_or_id, kind=None, limit=50) |
Inspect :EdgeGroup hyperedges (protocol implementers, communities). |
wipe_graph(confirm=False) |
Destructive — requires --allow-write and confirm=True. |
reindex_file(path, package=None) |
Re-parse and upsert a single file. Requires --allow-write. |
Plus 29 prompt templates auto-registered from queries.md (one per Cypher example block).
Schema
Nodes: Package, File, Class, Method, Function, Interface, Endpoint, Column, GraphQLOperation, Event, Atom, EnvVar, Route, External, EdgeGroup.
Edges (selected): IMPORTS, IMPORTS_SYMBOL, IMPORTS_EXTERNAL, DEFINES_CLASS, DEFINES_FUNC, DEFINES_IFACE, HAS_METHOD, HAS_COLUMN, EXPOSES, INJECTS, PROVIDES, EXPORTS_PROVIDER, EXTENDS, IMPLEMENTS, RENDERS, USES_HOOK, DECORATED_BY, CALLS, CALLS_ENDPOINT, HANDLES, HANDLES_EVENT, EMITS_EVENT, READS_ATOM, WRITES_ATOM, READS_ENV, RESOLVES, BELONGS_TO, MEMBER_OF, OWNED_BY, LAST_MODIFIED_BY, CONTRIBUTED_BY, TESTS, TESTS_CLASS.
Every relationship carries confidence (EXTRACTED / INFERRED / AMBIGUOUS) and confidence_score (0.0-1.0). Filter low-confidence edges out of strict checks. See docs/confidence.md.
:EdgeGroup nodes model N-ary "hyperedges" — used for protocol implementers (auto-emitted during indexing) and Leiden communities (codegraph report). Members link via MEMBER_OF. See docs/hyperedges.md.
Architecture conformance
codegraph arch-check runs five built-in policies plus any [[policies.custom]] Cypher you add to .arch-policies.toml:
import_cycles— file-level cycles of length 2-6.cross_package— forbidden directional imports between packages.layer_bypass— Controllers reaching Repositories without a Service in between.coupling_ceiling— files importing more than N other files (default 20).orphan_detection— functions / classes / atoms / endpoints with no inbound references. Configurableexclude_prefixes/exclude_namesfor test framework conventions.
Suppress individual violations with [[suppress]] entries (each requires a reason). Stale suppressions are flagged. CI integration: .github/workflows/arch-check.yml (scaffolded by codegraph init). Full reference in docs/arch-policies.md.
AI platform integrations
codegraph install <platform> writes the appropriate rules file (e.g. CLAUDE.md, AGENTS.md, GEMINI.md, .cursor/rules/codegraph.mdc, .github/copilot-instructions.md), registers the MCP server, and tracks the install in .codegraph/platforms.json so partial uninstalls preserve shared sections.
| Platform | Subcommand | Rules file |
|---|---|---|
| Claude Code | claude |
CLAUDE.md |
| Codex | codex |
AGENTS.md |
| OpenCode | opencode |
AGENTS.md |
| Cursor | cursor |
.cursor/rules/codegraph.mdc |
| Gemini CLI | gemini |
GEMINI.md |
| GitHub Copilot CLI | copilot |
(MCP only) |
| VS Code Copilot Chat | vscode |
.github/copilot-instructions.md |
| Aider | aider |
AGENTS.md |
| OpenClaw | claw |
AGENTS.md |
| Factory Droid | droid |
AGENTS.md |
| Trae | trae |
AGENTS.md |
| Kiro IDE | kiro |
AGENTS.md |
| Google Antigravity | antigravity |
AGENTS.md |
| Hermes | hermes |
AGENTS.md |
Templates resolve $NEO4J_BOLT_PORT, $NEO4J_HTTP_PORT, $PACKAGE_PATHS_FLAGS, $CONTAINER_NAME, $DEFAULT_PACKAGE_PREFIX, $CROSS_PAIRS_TOML, $PIPX_VERSION to per-repo values.
Incremental indexing
Two modes:
--update— SHA256 content-addressed cache in.codegraph-cache/(auto-added to.gitignorebyinit). Files whose hash is unchanged are skipped. Stale entries are pruned on save. Cache is invalidated automatically on a package version bump.--since <git-ref>— re-index only files changed since the ref (HEAD~1, a tag, a SHA). Diffs the working tree, removes stale subgraphs for deleted/changed files, upserts the rest. Implies--no-wipe. Non-code files are filtered out before processing.
codegraph watch (debounced file-system watcher) and codegraph hook install (post-commit + post-checkout) both layer on top of --update.
File extras
| Extra | Adds |
|---|---|
[python] |
tree-sitter-python — enables Python frontend. |
[mcp] |
mcp — enables codegraph-mcp stdio server. |
[watch] |
watchdog — enables codegraph watch. |
[analyze] |
networkx, graspologic — Leiden community detection for codegraph report. |
[benchmark] |
tiktoken — exact BPE counting for codegraph benchmark (otherwise chars/4 approximation). |
[repl] |
prompt_toolkit — history + tab-completion in REPL. |
[all] |
All of the above. |
Configuration
codegraph.toml (or [tool.codegraph] in pyproject.toml) at the repo root:
[tool.codegraph]
packages = ["packages/twenty-server", "packages/twenty-front"]
ignore_file = ".codegraphignore" # optional; auto-detected at repo root
neo4j_uri = "bolt://localhost:7688"
neo4j_user = "neo4j"
neo4j_password = "codegraph123"
.codegraphignore uses gitignore syntax with two extensions: @route:<glob> and @component:<glob> for path-based framework-feature suppression.
.arch-policies.toml configures arch-check — full schema in docs/arch-policies.md.
Documentation
docs/cli.md— full per-command reference: every flag,--jsonshape, exit codes, examples.docs/mcp.md— full per-tool reference for the MCP server (17 tools).docs/schema.md— complete graph schema: 15 node types, 33 edge types, properties, indexing phases.docs/incremental.md—--update,--since,codegraph watch,codegraph hook install.docs/platforms.md— the 14 AI agent platform integrations.docs/init.md—codegraph initflow, port flags, prompts, troubleshooting.docs/arch-policies.md— policy reference, suppression syntax, custom-policy authoring.docs/confidence.md— edge-level confidence labels and scores.docs/hyperedges.md—:EdgeGroupmodel and thedescribe_groupMCP tool.queries.md— canonical Cypher query catalogue (also auto-loaded as MCP prompt templates).../CHANGELOG.md— version-by-version shipped-feature log.../ROADMAP.md— session-to-session engineering handoff.
Development
git clone https://github.com/cognitx-leyton/codegraph
cd codegraph/codegraph
python3 -m venv .venv
.venv/bin/pip install -e ".[python,mcp,watch,analyze,benchmark,repl,test]"
docker compose up -d
.venv/bin/python -m pytest tests/ -q # 800+ tests, ~15s
Tests target 100% passing, zero warnings. Conventional commits (feat(scope), fix(scope), docs(scope), test(scope)). Work lands on dev; main / release / hotfix are protected.
License: Apache-2.0.
1 maintainer
Metadata
1 maintainer
Release files for cognitx-codegraph 0.1.118
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cognitx_codegraph-0.1.118.tar.gz | 483.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cognitx_codegraph-0.1.118-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 885.1 kB
Release files / cognitx_codegraph-0.1.118.tar.gz
| Download URL | cognitx_codegraph-0.1.118.tar.gz |
|---|---|
| Size | 483.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
79ebd86221c7a49ce0c451fad790199715f09adfbb4c3076478a10800efbc8b1
|
|
BLAKE2b-256 checksum How to use checksums |
85fb3c738f951cf6ef786f4480be6ab5d7465aa88de2296ccff1a090adba379e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / cognitx_codegraph-0.1.118-py3-none-any.whl
| Download URL | cognitx_codegraph-0.1.118-py3-none-any.whl |
|---|---|
| Size | 402.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7dfba4089b846f960bb33d05ee561988bc7b6ef524996ae0e6982bb662df0ef9
|
|
BLAKE2b-256 checksum How to use checksums |
1c5db20398b2af840e624fd76ef131de143d4507e99126110b9c3e2a4f3af3a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
