AI Summary

📌 Обзор CodeGraph — инструмент для ускорения работы AI-агентов с кодом. Вместо постоянных вызовов grep, Read и поиска по файлам, агент получает прединдексированный граф символов, call-graph и структуру проекта. В среднем по 7 репозиториям разных языков инструмент показал 35% снижение стоимости, 59% меньше токенов, 49% быстрее ответ и 70% меньше вызовов инструментов.

📌 Ключевые выводы • 💰 35% дешевле и 70% меньше вызовов инструментов по сравнению с обычным режимом • ⚡ Gains растут с размером репозитория — на больших проектах агент использует 2–3 calls без чтения файлов • 🛠️ Interactive installer автоматически настраивает Claude Code, Cursor, Codex CLI и opencode • 🔍 Граф включает символы, call-graphs, routing-edges и позволяет быстро искать callers/callees • 🏠 100% локальный запуск, MCP-сервер запускается через codegraph serve --mcp • 📊 Методология: 4 прогона на каждом из 7 open-source репозиториев, сравнение с/без CodeGraph с использованием Claude Opus 4.7

CodeGraph CodeGraph builds a semantic knowledge graph of codebases for faster, smarter code exploration. ### If .codegraph/ exists in the project NEVER call codegraph_explore or codegraph_context directly in the main session. These tools return large amounts of source code that fills up main session context. Instead, ALWAYS spawn an Explore agent for any exploration question (e.g., "how does X work?", "explain the Y system", "where is Z implemented?"). When spawning Explore agents, include this instruction in the prompt: > This project has CodeGraph initialized (.codegraph/ exists). Use codegraph_explore as your PRIMARY tool — it returns full source code sections from all relevant files in one call. > > Rules: > 1. Follow the explore call budget in the codegraph_explore tool description — it scales automatically based on project size. > 2. Do NOT re-read files that codegraph_explore already returned source code for. The source sections are complete and authoritative. > 3. Only fall back to grep/glob/read for files listed under "Additional relevant files" if you need more detail, or if codegraph returned no results. The main session may only use these lightweight tools directly (for targeted lookups before making edits, not for exploration): | Tool | Use For | |------|---------| | codegraph_search | Find symbols by name | | codegraph_callers / codegraph_callees | Trace call flow | | codegraph_impact | Check what's affected before editing | | codegraph_node | Get a single symbol's details | ### If .codegraph/ does NOT exist At the start of a session, ask the user if they'd like to initialize CodeGraph: "I notice this project doesn't have CodeGraph initialized. Would you like me to run codegraph init -i to build a code knowledge graph?"

┌─────────────────────────────────────────────────────────────────┐ │ Claude Code │ │ │ │ "Implement user authentication" │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Explore Agent │ ──── │ Explore Agent │ │ │ └────────┬────────┘ └────────┬────────┘ │ │ │ │ │ └───────────┼────────────────────────┼─────────────────────────────┘ │ │ ▼ ▼ ┌───────────────────────────────────────────────────────────────────┐ │ CodeGraph MCP Server │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Search │ │ Callers │ │ Context │ │ │ │ "auth" │ │ "login()" │ │ for task │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ └────────────────┼────────────────┘ │ │ ▼ │ │ ┌───────────────────────┐ │ │ │ SQLite Graph DB │ │ │ │ • 387 symbols │ │ │ │ • 1,204 edges │ │ │ │ • Instant lookups │ │ │ └───────────────────────┘ │ └───────────────────────────────────────────────────────────────────┘ • Extraction — tree-sitter parses source code into ASTs. Language-specific queries extract nodes (functions, classes, methods) and edges (calls, imports, extends, implements). Extraction — tree-sitter parses source code into ASTs. Language-specific queries extract nodes (functions, classes, methods) and edges (calls, imports, extends, implements). • Storage — Everything goes into a local SQLite database (.codegraph/codegraph.db) with FTS5 full-text search. Storage — Everything goes into a local SQLite database (.codegraph/codegraph.db) with FTS5 full-text search. • Resolution — After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns. Resolution — After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns. • Auto-Sync — The MCP server watches your project using native OS file events. Changes are debounced (2-second quiet window), filtered to source files only, and incrementally synced. The graph stays fresh as you code — no configuration needed. Auto-Sync — The MCP server watches your project using native OS file events. Changes are debounced (2-second quiet window), filtered to source files only, and incrementally synced. The graph stays fresh as you code — no configuration needed. codegraph # Run interactive installer codegraph install # Run installer (explicit) codegraph init [path] # Initialize in a project (--index to also index) codegraph uninit [path] # Remove CodeGraph from a project (--force to skip prompt) codegraph index [path] # Full index (--force to re-index, --quiet for less output) codegraph sync [path] # Incremental update codegraph status [path] # Show statistics codegraph query # Search symbols (--kind, --limit, --json) codegraph files [path] # Show file structure (--format, --filter, --max-depth, --json) codegraph context # Build context for AI (--format, --max-nodes) codegraph affected [files...] # Find test files affected by changes (see below) codegraph serve --mcp # Start MCP server Traces import dependencies transitively to find which test files are affected by changed source files. codegraph affected src/utils.ts src/api.ts # Pass files as arguments git diff --name-only | codegraph affected --stdin # Pipe from git diff codegraph affected src/auth.ts --filter "e2e/" # Custom test file pattern #!/usr/bin/env bash AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet) if [ -n "$AFFECTED" ]; then npx vitest run $AFFECTED fi When running as an MCP server, CodeGraph exposes these tools to Claude Code: import CodeGraph from '@colbymchenry/codegraph'; const cg = await CodeGraph.init('/path/to/project'); // Or: const cg = await CodeGraph.open('/path/to/project'); await cg.indexAll({ onProgress: (p) => console.log(${p.phase}: ${p.current}/${p.total}) }); const results = cg.searchNodes('UserService'); const callers = cg.getCallers(results[0].node.id); const context = await cg.buildContext('fix login bug', { maxNodes: 20, includeCode: true, format: 'markdown' }); const impact = cg.getImpactRadius(results[0].node.id, 2); cg.watch(); // auto-sync on file changes cg.unwatch(); // stop watching cg.close(); The .codegraph/config.json file controls indexing: { "version": 1, "languages": ["typescript", "javascript"], "exclude": ["node_modules/", "dist/", "build/**", ".min.js"], "frameworks": [], "maxFileSize": 1048576, "extractDocstrings": true, "trackCallSites": true } "CodeGraph not initialized" — Run codegraph init in your project directory first. Indexing is slow — Check that node_modules and other large directories are excluded. Use --quiet to reduce output overhead. Indexing is slow / MCP database is locked / WASM fallback active — codegraph ships with a WASM SQLite fallback for environments where better-sqlite3 (a native module, declared as optionalDependencies) can't install. The fallback is 5-10x slower than the native backend and uses a journal mode that lets writers block readers, so MCP queries can also hit database is locked while indexing runs. Run codegraph status and look at the Backend: line: • Backend: native — you're on the fast path, nothing to do. Backend: native — you're on the fast path, nothing to do. • Backend: wasm — you're on the slow fallback. Common causes: missing C build tools, prebuilt binary unavailable for your Node version, or your Node version changed after install. Fix: # macOS xcode-select --install # installs the C compiler # Linux (Debian / Ubuntu) sudo apt install build-essential python3 make # Linux (RHEL / Fedora) sudo yum groupinstall "Development Tools" # Then rebuild on any platform: npm rebuild better-sqlite3 # Or force-include as a hard dep: npm install better-sqlite3 --save After the fix, codegraph status should show Backend: native. Backend: wasm — you're on the slow fallback. Common causes: missing C build tools, prebuilt binary unavailable for your Node version, or your Node version changed after install. Fix:

macOS xcode-select --install # installs the C compiler # Linux (Debian / Ubuntu) sudo apt install build-essential python3 make # Linux (RHEL / Fedora) sudo yum groupinstall "Development Tools" # Then rebuild on any platform: npm rebuild better-sqlite3 # Or force-include as a hard dep: npm install better-sqlite3 --save

After the fix, codegraph status should show Backend: native. MCP server not connecting — Ensure the project is initialized/indexed, verify the path in your MCP config, and check that codegraph serve --mcp works from the command line. Missing symbols — The MCP server auto-syncs on save (wait a couple seconds). Run codegraph sync manually if needed. Check that the file's language is supported and isn't excluded by config patterns.

Мои мысли