{
  "markdown": "# CodeGraph\n\n**Cross-language code intelligence for AI agents and developers.**\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)\n\nCodeGraph builds a semantic graph of your codebase — functions, classes, imports, call chains — and exposes it through **42 MCP tools**, a **VS Code extension**, a **JetBrains IDE plugin**, and a **persistent memory layer**. Parses **38 languages** via tree-sitter. AI agents get structured code understanding instead of grepping through files.\n\n## Quick Start\n\n### MCP Server (Claude Code, Cursor, any MCP client)\n\nAdd to `~/.claude.json` (or your MCP client config):\n\n```json\n{\n  \"mcpServers\": {\n    \"codegraph\": {\n      \"command\": \"/path/to/codegraph-server\",\n      \"args\": [\"--mcp\"]\n    }\n  }\n}\n```\n\nThe server indexes the current working directory automatically.\n\n### VS Code Extension\n\nInstall the VSIX:\n\n```bash\ncode --install-extension codegraph-0.20.1.vsix\n```\n\nOne VSIX serves every platform.\nThe analysis engine is not bundled: on first activation the extension offers to download the engine built for your platform, verifies it against the published checksum, and installs it into `~/.codegraph/bin` - the same location the JetBrains plugin uses, so one download serves both.\nThe download is offered rather than performed automatically, because it is a native binary that runs with your permissions.\nDecline it and run **CodeGraph: Download Analysis Engine** from the command palette whenever you are ready.\n\nOnce an engine is present, the extension starts it automatically and registers all tools as Language Model Tools for Copilot.\n\n### JetBrains IDEs\n\nA plugin for IntelliJ IDEA, PyCharm, GoLand, Android Studio and the rest of the\nfamily drives the same engine over LSP: Code Vision, Symbols and Memories tool\nwindows, a graph panel, and one-click MCP registration for the AI Assistant.\nIt resolves or downloads the engine the same way the VS Code extension does,\nsharing `~/.codegraph/bin`.\n\n→ **[jetbrains/README.md](jetbrains/README.md)** for surfaces, engine\nresolution order, and building from source.\n\n### Rules for AI agents\n\nPre-configured rule files that teach AI coding agents (Claude, Cursor,\nWindsurf, Codex, Cline) to use CodeGraph MCP tools before falling back\nto grep / multi-file reads. Maps natural-language intent to the right\n`codegraph_*` tool.\n\n→ **[codegraph-ai/codegraph-rules-for-agents](https://github.com/codegraph-ai/codegraph-rules-for-agents)**\n\nSetup is `cp <agent>/codegraph.md ~/<agent>/` (one line per agent — see\nthe rules repo's README).\n\n### GitHub Action — PR review in CI\n\nDrop a workflow into your repo to get an automatic code-graph analysis\ncomment on every PR — blast radius, test gaps, stale docs, suggested\nreviewers. Runs **graph-only** (no embeddings, no ONNX model), so it's\nfast and needs no API keys — just the built-in `GITHUB_TOKEN`.\n\nCopy [`.github/workflows/codegraph-pr.yml`](.github/workflows/codegraph-pr.yml)\ninto your repo. The core invocation is a single command:\n\n```bash\ncodegraph-server --graph-only \\\n  --run-tool codegraph_pr_context \\\n  --tool-args '{\"baseBranch\":\"main\",\"format\":\"markdown\"}'\n```\n\nThis prints a ready-to-post markdown comment. The `--graph-only` flag\nskips embedding generation (10-50× faster indexing); `--run-tool` runs\none tool and exits without the MCP stdio handshake — ideal for scripting.\n\n---\n\n## Configuration\n\n### MCP Server flags\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--workspace <path>` | current dir | Directories to index (repeatable for multi-project) |\n| `--exclude <dir>` | — | Directories to skip (repeatable) |\n| `--embedding-model <model>` | `bge-small` | `bge-small` (384d, fast), `jina-code-v2` (768d, 6× slower), `granite-97m` (384d, 32K ctx, ~3× slower), or `static` (model2vec, 256d — ~100× faster indexing, no ONNX; needs a local model dir, see below) |\n| `--full-body-embedding` | `true` | Embed full function body (~50 lines) for better semantic search and duplicate detection |\n| `--max-files <n>` | 5000 | Maximum files to index |\n| `--profile <name>` | `all` | Filter the exposed MCP tool surface to a named subset (see below) |\n| `--graph-only` | off | Skip embedding generation — build the graph and serve structural tools only. No ONNX model load, 10-50× faster indexing. Semantic search unavailable. For CI / one-shot graph queries. |\n| `--run-tool <name>` | — | One-shot mode: index, run a single tool, print its result, exit. No MCP handshake. Pair with `--tool-args '<json>'`. |\n\n#### `--embedding-model static` — model2vec fast indexing\n\nStatic (model2vec) embeddings replace the ONNX transformer with a token→vector\nlookup table: indexing is **~100× faster** (this repo's 5,873 symbols embed in\n~1 s vs ~3.4 min with BGE) and there's **no ONNX runtime or 1.5 GB RAM gate**.\nRetrieval stays **hybrid (BM25 + semantic)**, so end-to-end quality is **~90% of BGE**.\nThe model is not bundled with any client — it needs a local model directory\n(`config.json` + `tokenizer.json` + `model.safetensors`) at\n`~/.codegraph/static_models/jina-code-static-256`, or wherever\n`CODEGRAPH_STATIC_MODEL` points:\n\n- Installing `@astudioplus/codegraph-mcp` from npm downloads it into that\n  default location for you (best-effort; set `CODEGRAPH_SKIP_MODEL_FETCH=1` to\n  skip, and the install never fails over it).\n- Otherwise fetch the prebuilt one with `scripts/fetch-static-model.sh`, or\n  distill your own from any sentence-transformer (Apache-2.0 Jina-Code by\n  default) in ~30 s on CPU: `python scripts/distill_static_model.py`.\n- A model in the default location needs no IDE setting: both IDE clients leave\n  `CODEGRAPH_STATIC_MODEL` unset and let the engine resolve it. To use a model\n  kept somewhere else, set `codegraph.staticModelPath` in VS Code, or\n  *Settings → Tools → CodeGraph → Embeddings → Static model directory* in\n  JetBrains; each client then passes that path as `CODEGRAPH_STATIC_MODEL`.\n\n#### `CODEGRAPH_SKIP_MEMORY_CHECK` — force the embedding model past the RAM gate\n\nBefore loading the ONNX model, the server checks available memory and, if under\n~1.5 GB, skips the model to avoid an OOM-kill (running graph-only instead).\nSet `CODEGRAPH_SKIP_MEMORY_CHECK=1` (also accepts `true`/`yes`) to bypass that\ncheck and always load the model.\n\nUse it if embeddings are disabled even though the machine has plenty of free\nRAM.\nA reading of `0 MB available` is treated as a detection failure and the model\nloads anyway (macOS parks reclaimable memory in inactive/speculative pages that\nsome memory readers do not count as free), so this override is mainly for other\ncases where the reported figure is low but wrong.\nIt works in both MCP and one-shot `--run-tool` modes.\n\n#### `--profile` — narrow the MCP tool surface\n\nThe full 42-tool surface is convenient but inflates the agent's prompt-context cost. A profile exposes only the slice you need (also settable via the `CODEGRAPH_TOOL_PROFILE` env var):\n\n| Profile | Tools | Use when |\n|---------|-------|----------|\n| `all` *(default)* | every tool (community + pro) | normal sessions |\n| `core` | 8 — search + symbol info + AI context | chatty agent sessions where you only need lookups |\n| `graph` | 17 — callers/callees/deps/impact/traverse/PR context | refactoring + structural analysis |\n| `memory` | 14 — `codegraph_memory_*` plus the docs tools | note-taking / knowledge-base workflows |\n| `security` | pro security tools only (empty on community) | pro security audits |\n\n### VS Code settings\n\nThe `codegraph.*` settings are documented once, next to the extension that\nreads them:\n\n→ **[vscode/README.md — Configuration](vscode/README.md#configuration)**\n\nFull-body embeddings are enabled by default. Function body text is captured at parse time with zero I/O overhead.\n\nBuilt-in exclusions (always skipped) cover ~47 directories across three categories:\n\n- **Build / cache**: `node_modules`, `target`, `dist`, `build`, `out`, `.git`, `__pycache__`, `vendor`, `.venv`, `venv`, `.tox`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`, `.next`, `.nuxt`, `.svelte-kit`, `.parcel-cache`, `.npm`, `.yarn`, `.pnpm-store`, `.cache`, `.cargo`, `.bundle`, `.gradle`, `DerivedData`, `Pods`, `xcuserdata`, `cmake-build-*`\n- **IDE / IaC state**: `.idea`, `.vscode-test`, `.fleet`, `.terraform`, `.terragrunt-cache`, `.serverless`\n- **Sensitive credential dirs**: `.aws`, `.ssh`, `.gnupg`, `.kube`, `.docker`\n\nPlus glob patterns for binary archives, native libraries, OS metadata, and **secret file extensions** (`*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.crt`, `*.gpg`, `*.kdbx`, SSH key conventions like `id_rsa`, etc.) — defense in depth against accidentally embedding credentials.\n\nIndexing produced zero files, or something else looks wrong? See\n**[docs/troubleshooting.md](docs/troubleshooting.md)**.\n\n---\n\n## Tools\n\n42 community tools, plus 27 more (17 of them security analyzers) in CodeGraph Pro.\n\n### Code Analysis (11)\n\n| Tool | What it does |\n|------|-------------|\n| `get_ai_context` | **Primary context tool.** Intent-aware (explain/modify/debug/test) with token budgeting. Returns source, related symbols, imports, siblings, debug hints. |\n| `get_edit_context` | Everything needed before editing: source + callers + tests + memories + git history |\n| `get_curated_context` | Cross-codebase context for a natural language query (\"how does auth work?\") |\n| `analyze_impact` | Blast radius prediction — what breaks if you modify, delete, or rename |\n| `analyze_complexity` | Cyclomatic complexity with breakdown (branches, loops, nesting, exceptions, early returns) |\n| `find_circular_deps` | Detect circular import/dependency chains across files |\n| `find_hot_paths` | Most-called functions ranked by transitive caller count |\n| `find_dead_imports` | Find unused imports — modules imported but never referenced |\n| `get_module_summary` | High-level summary of a directory: file count, functions, language breakdown, top complex functions |\n| `search_by_pattern` | Regex search across function bodies, signatures, names, and docstrings |\n| `search_by_error` | Find functions that throw, catch, or handle specific error types |\n\n### Code Navigation (13)\n\n| Tool | What it does |\n|------|-------------|\n| `symbol_search` | Find symbols by name or natural language (hybrid BM25 + semantic search) |\n| `get_callers` / `get_callees` | Who calls this? What does it call? (with transitive depth) |\n| `get_detailed_symbol` | Full symbol info: source, callers, callees, complexity |\n| `get_symbol_info` | Quick metadata: signature, visibility, kind |\n| `get_dependency_graph` | File/module import relationships with depth control |\n| `get_call_graph` | Function call chains (callers and callees) |\n| `find_by_imports` | Find files importing a module |\n| `find_by_signature` | Search by param count, return type, modifiers |\n| `find_entry_points` | Main functions, HTTP handlers, CLI commands, event handlers |\n| `find_implementors` | Find all functions registered as ops struct callbacks |\n| `find_related_tests` | Tests that exercise a given function |\n| `traverse_graph` | Custom graph traversal with edge/node type filters |\n\n### Indexing (3)\n\n| Tool | What it does |\n|------|-------------|\n| `reindex_workspace` | Full or incremental workspace reindex |\n| `index_files` | Add/update specific files without full reindex |\n| `index_directory` | Add directory to graph alongside existing data |\n\n### Memory (7)\n\nPersistent AI context across sessions — debugging insights, architectural decisions, known issues.\n\n| Tool | What it does |\n|------|-------------|\n| `memory_store` / `memory_get` / `memory_search` | Store, retrieve, search memories (BM25 + semantic) |\n| `memory_context` | Get memories relevant to a file/function |\n| `memory_list` / `memory_invalidate` / `memory_stats` | Browse, retire, monitor |\n\nPairs well with [Tempera](https://github.com/anvanster/tempera) — an episodic memory system that captures transferable debugging strategies and solutions across projects. CodeGraph's memory tools store project-scoped notes; Tempera captures cross-project BKMs (best-known methods) that improve over time.\n\n### PR / Change Analysis (1)\n\n| Tool | What it does |\n|------|-------------|\n| `pr_context` | **One-call PR review.** Runs git diff against base branch, finds changed functions in the graph, reports: blast radius (callers), test coverage + gaps, affected modules, diff-aware change classification (signature vs body), stale-doc warnings, complexity, commit-message hint, suggested reviewers from git blame. |\n\n### Documentation (7)\n\nPersistent project documentation — index design docs, search them semantically, verify code matches the design, generate architecture docs from the code graph.\n\n| Tool | What it does |\n|------|-------------|\n| `index_markdown` | Index a local `.md` file (ARCHITECTURE.md, API_DESIGN.md, etc.) into the persistent docs store. Heading-tree chunking with leaf-node embeddings. |\n| `search_docs` | Semantic search over indexed docs — returns matching sections with heading-path breadcrumbs |\n| `list_doc_sources` | List all indexed source files |\n| `remove_doc_source` | Remove all indexed chunks from a source file |\n| `verify_design` | Cross-reference doc claims vs code graph. `direction=forward` (doc→code), `reverse` (code→doc), or `both` |\n| `design_gaps` | Find identifiers described in docs that don't exist in code yet — build TODO lists from specs |\n| `generate_architecture_doc` | Auto-generate a structured ARCHITECTURE.md from the live code graph (modules, hot paths, complexity, circular deps) |\n\nAll tool names are prefixed with `codegraph_` (e.g. `codegraph_get_ai_context`). Tools that target a specific symbol accept `uri` + `line` or `nodeId` from `symbol_search` results.\n\n---\n\n### Usage examples\n\n**Index a design doc and search it:**\n```\ncodegraph_index_markdown(path: \"/projects/myapp/docs/ARCHITECTURE.md\")\ncodegraph_search_docs(query: \"how does the auth module handle JWT refresh?\")\n```\n\n**Check if the code matches the design:**\n```\ncodegraph_verify_design(source: \"/projects/myapp/docs/ARCHITECTURE.md\", direction: \"forward\")\n// → \"132/132 identifiers verified, 0 gaps\"\n```\n\n**Find what's described in docs but not yet implemented:**\n```\ncodegraph_design_gaps(source: \"/projects/myapp/docs/API_DESIGN.md\")\n// → \"4 of 12 identifiers not found in code: PaymentService, RefundHandler, ...\"\n```\n\n**Generate architecture docs from the code graph:**\n```\ncodegraph_generate_architecture_doc(scope: \"src/\", topN: 5)\n// → Markdown with modules, complexity hotspots, hot paths, circular deps\n```\n\n**Save a debugging insight for future sessions:**\n```\ncodegraph_memory_store(kind: \"debug_context\", title: \"Nginx body size limit\",\n  content: \"The /upload endpoint fails on payloads > 1MB...\",\n  problem: \"API returns 500 on large uploads\",\n  solution: \"Increase nginx client_max_body_size to 10M\",\n  agentSource: \"claude\")\n```\n\n**Get AI context with graph compression stats + design doc augmentation:**\n```\ncodegraph_get_ai_context(uri: \"file:///projects/myapp/src/auth.rs\", line: 42, intent: \"modify\")\n// → Code context + graphStats: {entitiesInGraph: 13555, entitiesTraversed: 47, entitiesKept: 8}\n// → design_context section from indexed docs mentioning \"auth\"\n```\n\n**Review a PR — blast radius, test gaps, stale docs, reviewers in one call:**\n```\ncodegraph_pr_context(baseBranch: \"main\")\n// → \"PR changes 4 files (+263/-77, 12 functions). 37 direct callers, 8 tests, 3 untested. Risk: medium.\"\n// → test_gaps: [refresh_token, revoke_session] — functions with 0 test callers\n// → stale_docs: [\"auth.rs described in ARCHITECTURE.md > Authentication — doc may need updating\"]\n// → suggested_reviewers: [{author: \"anvanster\", lines_owned: 3200}]\n// → commit_hint: \"feat(mcp): <describe the change>\"\n```\n\n**Narrow the tool surface for chatty sessions:**\n```bash\ncodegraph-server --mcp --profile=core  # Only 8 tools: search + symbol info + AI context\n```\n\n---\n\n### CodeGraph Pro\n\nAdditional tools available in [CodeGraph Pro](https://codegraph.astudioplus.com/pro):\n\n| Tool | What it does |\n|------|-------------|\n| `scan_security` | Security vulnerability scan: 40+ dangerous function patterns, source-to-sink taint tracing, auth coverage for HTTP endpoints (7 languages/frameworks), architectural layer violations, weak crypto, hardcoded secrets |\n| `analyze_coupling` | Module coupling metrics and instability scores |\n| `find_unused_code` | Dead code detection with confidence scoring |\n| `find_duplicates` | Detect duplicate/near-duplicate functions |\n| `find_similar` / `cluster_symbols` / `compare_symbols` | Embedding-based code similarity |\n| `cross_project_search` | Search across all indexed projects |\n| `mine_git_history` / `mine_git_history_for_file` / `search_git_history` | Git history mining and semantic search |\n| `security_control_flow` | Map every execution path through a function — \"can this return without hitting the auth check?\" |\n| `security_trace_data_flow` | Follow a variable from birth to death — \"does user input reach this SQL query?\" |\n| `security_generate_sbom` | CycloneDX SBOM from 8 lockfile formats |\n| `security_audit_deps` | OSV vulnerability check on dependencies |\n| `security_check_unchecked_returns` / `_resource_leaks` / `_misconfig` / `_input_validation` / `_error_exposure` | 5 heuristic analyzers covering ~80% of CWE Top 25 |\n| `security_scan_iac` | Docker / Kubernetes / Terraform misconfiguration scan |\n| `security_check_licenses` | Lockfile license policy enforcement (copyleft detection) |\n| `security_check_secrets_entropy` | Shannon-entropy hardcoded-secret detection |\n| `security_detect_injection` | Focused SQL/XSS/cmd/path/deser/template injection detection (20 patterns) |\n| `security_check_search_path` | Untrusted search-path / DLL-hijacking detection (CWE-426/CWE-427) |\n| `security_check_crypto` | Cryptographic misuse: weak ciphers/hashes/PRNG/keys, static IVs, timing-leak comparisons (CWE-208/326-330/338/916, 35 patterns) |\n| `security_export_sarif` | Aggregate findings as SARIF 2.1.0 (GitHub Code Scanning, GitLab SAST) |\n\n**Cross-cutting features (all `security_check_*` tools):**\n- `include_tests` / `treat_as_production` — first-class skip for tests/samples/vendored\n- `check_compile_gates` — C/C++ findings inside `#ifdef X` are marked DEFENSIVE_GATED_OFF when X isn't defined by CMake/Cargo/Makefile\n- 25-marker suppression honoring (`# nosec`, `// NOLINT`, `// codeql[ignore]`, `# rubocop:disable`, etc.) at line and function level\n- Telemetry blocks per scan: `path_filter` (examined/matched/skipped) + `compile_gate` (gated_off count)\n\n---\n\n## Languages\n\n38 languages parsed via tree-sitter — functions, classes, imports, call graph, complexity metrics, dependency graphs, symbol search, and impact analysis:\n\n| Category | Languages |\n|---|---|\n| **Systems** | C, C++, Rust, Zig, Objective-C |\n| **JVM** | Java, Kotlin, Scala, Groovy, Clojure |\n| **Web/Scripting** | TypeScript/JS, Python, Ruby, PHP, Perl, Lua, Elixir, Elm |\n| **Web/Style** | CSS |\n| **Mobile** | Swift, Dart |\n| **Functional** | Haskell, OCaml, Julia, Erlang, Elm, Clojure |\n| **Enterprise** | C#, COBOL, Fortran, Go |\n| **Blockchain** | Solidity |\n| **Shell/Config** | Bash, Dockerfile, HCL/Terraform, TOML, YAML |\n| **Hardware** | Verilog/SystemVerilog, Tcl |\n| **Data Science** | R, Julia |\n\nHTTP handler detection: Python (FastAPI/Flask/Django), TypeScript (NestJS), Java (Spring/JAX-RS), Go (stdlib/Gin/Echo/Fiber), C# (ASP.NET), Ruby (Rails), PHP (Laravel/Symfony).\n\n> **Community vs full builds:** COBOL, Fortran, Perl, Dart, Zig, and R are\n> compiled only with `--features extra-languages`. The default community binary\n> omits them — they had zero usage in telemetry and their tree-sitter grammars\n> add ~25 MB (COBOL's parse tables alone are 30 MB). The other 32 languages are\n> always available.\n\n---\n\n## Architecture\n\n```\nMCP Client (Claude, Cursor, ...)   VS Code Extension   JetBrains Plugin\n        |                                  |                  |\n    MCP (stdio)                       LSP Protocol       LSP Protocol\n        |                                  |                  |\n        └───────────┐               ┌──────┴──────────────────┘\n                    ▼               ▼\n            ┌─────────────────────────────┐\n            │       codegraph-server      │\n            ├─────────────────────────────┤\n            │  38 tree-sitter parsers     │\n            │  Semantic graph engine      │\n            │  AI query engine (BM25)     │\n            │  Memory layer (RocksDB)     │\n            │  Docs store (RocksDB+HNSW)  │\n            │  Full-body embeddings (BGE) │\n            │  HNSW vector index          │\n            └─────────────────────────────┘\n```\n\nA single Rust binary serves both MCP and LSP protocols.\n\n- **Indexing**: ~60 files/sec. Incremental re-indexing on file changes via FNV-1a content hashing.\n- **Persistence**: Graph and embeddings persist to `~/.codegraph/graph.db` (RocksDB). Instant startup on restart — no re-parsing, no re-embedding.\n- **Queries**: Sub-100ms. Cross-file import and call resolution at index time.\n- **Embeddings**: Full-body (function bodies captured at parse time, zero disk I/O). Vectors stored in RocksDB alongside the graph. Auto-downloads model on first run.\n\n---\n\n## Supported platforms\n\nThe engine is a native binary, downloaded for your platform on first run.\n\n| Platform | Architectures |\n|---|---|\n| macOS | Apple Silicon (arm64) and Intel (x64) |\n| Linux | x64 and arm64 |\n| Windows | x64 (Windows on ARM runs the x64 build under emulation) |\n\n**Linux requires glibc 2.30 or newer *and* a libstdc++ from GCC 11 or newer\n(`GLIBCXX_3.4.29`).** The second requirement is the binding one, and it is not\nimplied by the first — the engine embeds ONNX Runtime, which is built with\nGCC 11.\n\n| Runs | Does not run |\n|---|---|\n| SLES 15 SP4 | Ubuntu 20.04 |\n| Ubuntu 22.04 and newer | Debian 11 |\n| Debian 12 and newer | RHEL / CentOS 8 |\n| RHEL 9 and newer | Amazon Linux 2 |\n| Amazon Linux 2023 | |\n\nBoth Linux architectures have identical requirements. If the engine exits\nimmediately with a message like\n\n```\nversion `GLIBCXX_3.4.29' not found (required by codegraph-server)\n```\n\nthe distribution's C++ runtime is older than the engine needs; installing a\nnewer `libstdc++` (for example RHEL 8's `gcc-toolset-11`) resolves it without\nupgrading the distribution.\n\n---\n\n## Building from Source\n\n```bash\ngit clone https://github.com/codegraph-ai/codegraph\ncd codegraph\ncargo build --release -p codegraph-server    # Rust server\ncd vscode && npm install && npm run esbuild  # VS Code extension\nnpx @vscode/vsce package                     # VSIX\n```\n\nRequires Rust stable, Node.js 18+, VS Code 1.90+.\n\n---\n\n## Support the project\n\nCodeGraph is free, open-source, and maintained by a solo developer.\nIf it saves you time, consider [sponsoring on GitHub](https://github.com/sponsors/anvanster) — it helps keep the project alive and growing.\n\n---\n\n## License\n\nApache-2.0\n",
  "bytes": 22937,
  "sha": "a3aca82de6ca1a21c5e13b956fe7d1499aa6ad1c57cb792e251fbc2c9b0f8a2a",
  "repo_slug": "codegraph-ai/codegraph",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_codegraph_ai_codegraph_125dc8b6/readme"
}