codegraph

name codegraph description Analyze indexed codebases via graph database (neug) and vector index (zvec). Covers call graphs, dependencies, dead code, hotspots, module coupling, architecture reports, semantic search, impact analysis, bug root cause from GitHub issues, class diagrams (UML), and PR review (risk scoring, conflict detection, auto-merge candidates, labeling). Also covers creating, inspecting, and repairing a CodeScope index. Use for: code structure, who calls what, why something changed, similar functions, module boundaries, bug tracing, class relationships, PR risk/conflicts, or any question benefiting from a code knowledge graph. Applies when a `.codegraph` index exists in the workspace, or when the user wants to create one. CodeScope Q&A CodeScope indexes source code into a two-layer knowledge graph — structure (functions, calls, imports, classes, modules) and evolution (commits, file changes, function modifications) — plus semantic embeddings for every function. Supports Python, JavaScript/TypeScript, C, and Java (including Hadoop-scale repositories with 8K+ files). This combination enables analyses that grep, LSP, or pure vector search cannot do alone. It can also fetch GitHub issues and trace bugs to code , and review open PRs — scoring per-PR risk, detecting cross-PR conflicts, identifying auto-merge candidates, and applying GitHub labels. When to Use This Skill User asks about call chains, callers, callees, or dependencies User wants to find dead code, hotspots, or architectural layers User asks about code history, who changed what, or why something was modified User wants to find semantically similar functions across a codebase User wants a full architecture analysis or report User asks about module coupling, circular dependencies, or bridge functions User wants to index or analyze a Java project (Maven, Gradle, plain Java) User wants to analyze GitHub issues or bug reports to find root causes User asks "why does this project have so many bugs" or "what code is most buggy" User wants to trace a bug report to the most relevant code locations User asks about class relationships, ownership, composition, or wants a class diagram / UML User wants to understand which classes own or depend on other classes User wants to review PRs, assess PR risk, or prioritize PR reviews User asks about cross-PR conflicts or which PRs can be merged independently User wants to find auto-merge candidates or generate a PR review report User asks about the blast radius or impact scope of a PR User wants to apply labels to PRs from analysis results User wants to explore PR-specific follow-up questions for a given PR A .codegraph directory (or similar index) exists in the workspace Getting Started Installation pip install codegraph-ai Environment Variables (optional) # Create Python virtural environment python -m venv .venv source .venv/bin/activate # Point to a pre-built database (skip indexing) export CODESCOPE_DB_DIR= "/path/to/.linux_db" # Offline mode for HuggingFace models export HF_HUB_OFFLINE= "1" Tip: If the all-MiniLM-L6-v2 model fails to download (network issues, firewall, etc.): HuggingFace mirror : export HF_ENDPOINT="https://hf-mirror.com" then retry download ModelScope (China-friendly): download from https://www.modelscope.cn/models/sentence-transformers/all-MiniLM-L6-v2 to a local path, then load by path instead of model name: pip install modelscope modelscope download --model sentence-transformers/all-MiniLM-L6-v2 --local_dir /path/to/all-MiniLM-L6-v2 # Then use the local path in Python API: # cs = CodeScope(db_dir, embedding_model="/path/to/all-MiniLM-L6-v2") Check Index Status codegraph status --db $CODESCOPE_DB_DIR If no index exists, create one: codegraph init --repo . --lang auto --commits 500 Supported languages: python , c , javascript , typescript , java , or auto (auto-detects from file extensions). The --commits flag ingests git history (for evolution queries). Without it, only structural analysis is available. Add --backfill-limit 200 to also compute function-level MODIFIES edges (slower but enables change_attribution and co_change ). To add git history to an existing index (without re-indexing structure): codegraph ingest --repo . --db $CODESCOPE_DB_DIR --commits 500 codegraph ingest --repo . --db $CODESCOPE_DB_DIR --backfill-limit 200 # add MODIFIES edges only Two Interfaces: CLI vs Python Use the CLI for status and reports: codegraph status --db $CODESCOPE_DB_DIR codegraph analyze --db $CODESCOPE_DB_DIR --output report.md Use the Python API for queries and custom analyses: import os os.environ[ 'HF_HUB_OFFLINE' ] = '1' # required from codegraph.core import CodeScope cs = CodeScope(os.environ[ 'CODESCOPE_DB_DIR' ]) # Cypher query rows = list (cs.conn.execute( ''' MATCH (caller:Function)-[:CALLS]->(f:Function {name: "free_irq"}) RETURN caller.name, caller.file_path LIMIT 10 ''' )) for r in rows: print (r) cs.close() # always close when done The Python API is more powerful — it gives you raw Cypher access and lets you chain queries. Core Python API Raw Queries These are the building blocks for any custom analysis: Method What it does cs.conn.execute(cypher) Run any Cypher query against the graph — returns list of tuples cs.vector_only_search(query, topk=10) Semantic search over all function embeddings — returns [{id, score}] cs.summary() Print a human-readable overview of the indexed codebase Structural Analysis Method What it does cs.impact(func_name, change_desc, max_hops=3) Find callers up to N hops, ranked by semantic relevance to the change cs.hotspots(topk=10) Rank functions by structural risk (fan-in × fan-out) cs.dead_code() Find functions with zero callers (excluding entry points) cs.circular_deps() Detect circular import chains at file level cs.module_coupling(topk=10) Find cross-module coupling pairs with call counts cs.bridge_functions(topk=30) Find functions called from the most distinct modules cs.layer_discovery(topk=30) Auto-discover infrastructure / mid / consumer layers cs.stability_analysis(topk=50) Correlate fan-in with modification frequency cs.class_hierarchy(class_name=None) Return inheritance tree for a class (or all classes) Class Dependency Relationships (UML-Style) CodeScope extracts three UML relationship types from class fields and type annotations during indexing: Relationship UML symbol Meaning How detected COMPOSES *-- filled diamond Strong ownership — field always holds an instance Non-optional field assigned a constructed object AGGREGATES o-- open diamond Optional/weak reference — may be None Optional[X] , X | None , or assigned None INHERITS <|-- hollow arrow Subclass extends parent class A(B) # Get all composition relationships (A strongly owns B) list (cs.conn.execute( 'MATCH (c1:Class)-[:COMPOSES]->(c2:Class) RETURN c1.name, c2.name' )) # Get all aggregation relationships (A optionally holds B) list (cs.conn.execute( 'MATCH (c1:Class)-[:AGGREGATES]->(c2:Class) RETURN c1.name, c2.name' )) # How many objects does a class directly own? list (cs.conn.execute( 'MATCH (c:Class {name: "Llama"})-[:COMPOSES]->(t:Class) RETURN t.name' )) # Full dependency graph for a class (composition + aggregation + inheritance) list (cs.conn.execute( 'MATCH (c:Class {name: "GPUModelRunner"})-[r:COMPOSES|AGGREGATES]->(t:Class) ' 'RETURN type(r), t.name' )) Generating a Mermaid class diagram: inherits = list (cs.conn.execute( 'MATCH (c1:Class)-[:INHERITS]->(c2:Class) RETURN c1.name, c2.name' )) composes = list (cs.conn.execute( 'MATCH (c1:Class)-[:COMPOSES]->(c2:Class) RETURN c1.name, c2.name' )) aggregates = list (cs.conn.execute( 'MATCH (c1:Class)-[:AGGREGATES]->(c2:Class) RETURN c1.name, c2.name' )) print ( 'classDiagram' ) for src, tgt in inherits: print ( f' {tgt} <|-- {src} ' ) # parent <|-- child for src, tgt in composes: print ( f' {src} *-- {tgt} ' ) # owner *-- owned for src, tgt in aggregates: print ( f' {src} o-- {tgt} ' ) # holder o-- optional Scale reference: Project Classes INHERITS COMPOSES AGGREGATES Index time llama-cpp-python 128 18 8 4 ~2s vllm 4,002 2,185 3,217 149 ~50s Semantic Search Method What it does cs.similar(function, scope, topk=10) Find functions similar to a given function within a module scope cs.cross_locate(query, topk=10) Find semantically related functions, then reveal call-chain connections. Returns CrossLocateResult (see below) cs.semantic_cross_pollination(query, topk=15) Find similar functions across distant subsystems cross_locate return value — a CrossLocateResult dataclass (not iterable directly): result = cs.cross_locate( "memory allocation error handling" , topk= 10 ) # result.seeds: list[dict] — semantically matched functions for seed in result.seeds: print ( f" [ {seed[ 'score' ]: .3 f} ] {seed[ 'name' ]} ( {seed[ 'file_path' ]} )" ) # result.connections: list[dict] — call-chain links between seeds for conn in result.connections: print ( f" {conn[ 'from' ]} -> {conn[ 'to' ]} (distance= {conn[ 'distance' ]} , via= {conn[ 'via' ]} )" ) # result.clusters: list[list[str]] — connected groups of seed function IDs for cluster in result.clusters: print ( f" Cluster: {cluster} " ) Evolution (requires --commits during init) Method What it does cs.change_attribution(func_name, file_path=None, limit=20) Which commits modified a function? (requires backfill) cs.co_change(func_name, file_path=None, min_commits=2, topk=10) Functions that are always modified together cs.intent_search(query, topk=10) Find commits matching a natural-language intent cs.commit_modularity(topk=20) Score commits by how many modules they touch cs.hot_cold_map(topk=30) Module modification density Report Generation from codegraph.analyzer import generate_report report = generate_report(cs) # full architecture analysis as markdown Or via CLI: codegraph analyze --output reports/analysis.md The report covers: overview stats, subsystem distribution, top modules, architectural layers (with Mermaid diagrams), bridge functions, fan-in/fan-out hotspots, cross-module coupling, evolution hotspots, and dead code density. Java Support CodeScope includes a full Java adapter that handles enterprise-scale repositories like Apache Hadoop (~8K files, ~97K functions indexed in ~3.5 minutes). What Gets Indexed Element Graph Node/Edge Notes Classes Class node Includes generics, annotations Interfaces Class node extends → INHERITS edge Enums Class node Enum methods extracted Methods Function node Full generic signatures, JavaDoc Constructors Function node (name= <init> ) Including super() calls Method calls CALLS edge Receiver context preserved ( obj.method() ) new expressions CALLS edge to ClassName.<init> Constructor invocations Imports IMPORTS edge (file→file) Single, wildcard, static Inner classes Class node (name= Outer.Inner ) Prefixed with outer class Inheritance INHERITS edge extends + implements Indexing a Java Project codegraph init --repo /path/to/java-project --lang java --commits 500 Or with auto-detection (auto-detects .java files): codegraph init --repo /path/to/java-project --lang auto Java-Specific Exclusions