Codegraph

Turn any codebase into a queryable knowledge graph. Health scores, drift detection, impact analysis, onboarding guides -- all from your AST.

Why Codegraph?

Most code intelligence tools need embeddings, vector stores, or LLM API keys before they do anything useful. Codegraph builds a real graph from your source code using tree-sitter AST parsing -- 25+ languages, zero configuration, no API keys required. The graph is a NetworkX DiGraph: nodes are symbols (functions, classes, modules), edges are relationships (imports, calls, inheritance). Every analysis command operates on this graph directly.

It works standalone or as a force multiplier for AI coding assistants (Claude Code, Cursor, Gemini CLI, Codex, and more).

Quick Start

pip install codegraph

cd your-project/
codegraph .

That's it. Open codegraph-out/graph.html for the interactive visualization, or codegraph-out/GRAPH_REPORT.md for the architectural report.

Core Commands

Example: codegraph debt

  ARCHITECTURAL DEBT SCORE
  ========================================

    72.4 / 100   [B]

  Graph: 1,247 nodes, 3,891 edges, 18 communities

  BREAKDOWN
  ----------------------------------------
  [========      ]  God Node Concentration (25%)
                    Top nodes: Router(47), Database(38), Config(31)
  [===========   ]  Cross-Community Coupling (25%)
                    412/3891 edges cross boundaries
  [=============]   Import Cycles (20%)
                    0 cycle(s) detected
  [=========     ]  Community Cohesion (20%)
                    Avg density: 34% across 18 communities
  [============  ]  Dead Code (10%)
                    89/1247 nodes unreferenced (7%)

  RECOMMENDATIONS
  ----------------------------------------
  1. Split Router (degree 47) -- extract route groups into sub-modules
  2. Reduce coupling between Community 3 <-> Community 7 (28 edges)

All Commands

All commands support --json for machine-readable output.

Supported Languages (25+)

Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, C#, Ruby, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Objective-C, Julia, Verilog, Fortran, Bash, Groovy, Apex, Dart, Pascal, OCaml, Common Lisp, Terraform (HCL), Robot Framework, DM (BYOND), Razor, Blade, SQL, JSON/config, Markdown

Language detection is automatic. Each language has a dedicated tree-sitter extractor.

How It Works

Source Code
    |
    v
[tree-sitter AST parsing] -- per-language extractors for 25+ languages
    |
    v
[Symbol extraction] -- functions, classes, modules, imports, calls
    |
    v
[Cross-file resolution] -- resolve imports, inheritance, call chains
    |
    v
[NetworkX DiGraph] -- nodes = symbols, edges = relationships
    |
    v
[Analysis / Simulation / Visualization]
    |--- Debt scoring (health grade 0-100)
    |--- Drift detection (baseline snapshots)
    |--- Impact & test-impact analysis
    |--- Security (source-to-sink tracing)
    |--- Simulation engine (remove, merge, refactor)
    |--- Discovery engine (latent connections, features, patterns)
    |--- Interactive HTML + TUI + dashboard
    |--- Export (Neo4j, Obsidian, SVG, GraphML)

Zero-LLM default mode: The core pipeline (parse, build, analyze, simulate, discover, debt, drift, onboard, security, test-impact, owners, refactor-plan) works without any API key. LLM integration is optional for natural language queries, enriched reports, and community labeling.

AI Agent Integration

codegraph install claude              # Claude Code
codegraph install cursor              # Cursor
codegraph install gemini              # Gemini CLI
codegraph install codex               # OpenAI Codex
codegraph install kilo                # Kilo Code
codegraph install vscode              # VS Code Copilot Chat
codegraph install antigravity         # Google Antigravity
codegraph install kiro                # Kiro IDE/CLI

An MCP server is also available:

pip install "codegraph[mcp]"
codegraph-mcp                        # exposes suggest_refactoring + impact_analysis tools

CI Integration

Use codegraph debt --threshold as a CI quality gate:

# .github/workflows/codegraph.yml
- name: Architecture health check
  run: |
    pip install codegraph
    codegraph . --code-only
    codegraph debt --threshold 60

Use codegraph test-impact --changed to run only affected tests:

- name: Smart test selection
  run: |
    codegraph test-impact --changed | xargs pytest

Optional Extras

pip install "codegraph[mcp]"          # MCP server for AI coding assistants
pip install "codegraph[openai]"       # OpenAI LLM integration
pip install "codegraph[anthropic]"    # Anthropic LLM integration
pip install "codegraph[ollama]"       # Ollama (local LLM) integration
pip install "codegraph[neo4j]"        # Neo4j graph database export
pip install "codegraph[falkordb]"     # FalkorDB graph database export
pip install "codegraph[pdf]"          # PDF document ingestion
pip install "codegraph[watch]"        # File watcher for live rebuilds
pip install "codegraph[svg]"          # Static SVG diagram export
pip install "codegraph[office]"       # Word/Excel document ingestion
pip install "codegraph[video]"        # Video transcription ingestion
pip install "codegraph[postgres]"     # PostgreSQL schema introspection
pip install "codegraph[all]"          # Everything

Requirements

• Python 3.10+
• No API keys required for core functionality

License

MIT License. See LICENSE for details.