{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Introduction to CodeGraphContext","text":"<p>CodeGraphContext (CGC) is a high-performance, developer-focused Code Intelligence Engine that transforms source repositories into semantic, queryable property graphs. Tree-sitter and optional SCIP indexers extract symbols; CGC resolves calls, imports, and inheritance into a graph you can query from the CLI, MCP tools, or the HTTP API gateway.</p> <p>Current release: 0.5.0</p> <p>Recent improvements in the 0.5.0 line include cross-language call-graph resolution fixes (Perl, Ruby, Lua, Haskell, Rust, TypeScript, C#, Dart, C), structural edge persistence (<code>PARTIAL_OF</code>, <code>IMPLEMENTS</code>, <code>METACLASS</code>, etc.), and average CALLS audit accuracy rising from ~84% to ~98%.</p>"},{"location":"#core-capabilities","title":"Core Capabilities","text":"<ul> <li>Semantic AST Extraction: Utilizes tree-sitter for syntax analysis and SCIP (Sourcegraph Code Intelligence Protocol) for static symbol resolution across multiple directories.</li> <li>Model Context Protocol (MCP) Integration: Built-in MCP server support allows AI models and IDE agents (Cursor, Claude, VS Code, Windsurf) to query the codebase context dynamically.</li> <li>Pluggable Database Architecture: FalkorDB Lite on Unix (Python 3.12+), KuzuDB as the cross-platform fallback, plus LadybugDB, FalkorDB Remote, Nornic, and Neo4j. See configuration defaults.</li> <li>Filesystem Synchronization: Integrated directory watchers monitor file updates and update the graph incrementally.</li> <li>Portable Code Graphs: Supports exporting and importing serialized graph representations as <code>.cgc</code> bundles for offline sharing and registry integration.</li> </ul>"},{"location":"#architectural-layout","title":"Architectural Layout","text":"<p>CGC acts as the translation layer between source code parsing engines, graph datastores, and consumer clients.</p> <pre><code>graph TD\n src[Source Code] --&gt; parse[Tree-sitter &amp; SCIP Ingestion]\n parse --&gt; builder[Graph Builder &amp; Linker]\n builder --&gt; db[Graph Storage: KuzuDB, FalkorDB, Neo4j]\n db --&gt; cli[CGC CLI Client]\n db --&gt; mcp[MCP Server Gateway]\n mcp --&gt; ai[AI Assistant Interfaces]</code></pre>"},{"location":"#documentation-roadmap","title":"Documentation Roadmap","text":"<p>To get started with CodeGraphContext, follow the structured sections below:</p> <ol> <li>Getting Started: Explore prerequisites, installation steps, quickstart tutorials, and MCP setup.</li> <li>Core Concepts: Deep dive into the architecture, graph model schemas, database backends, and parser designs.</li> <li>User Guides: Learn indexing strategies, workspaces contexts, bundles distribution, custom visualizers, and database schema mappings.</li> <li>Reference Manual: CLI commands, HTTP API, MCP tool schemas, and configuration variables.</li> <li>Community Portal: Guidelines for contributing code, extending languages support, and the project roadmap.</li> </ol>"},{"location":"contributing/","title":"Contributing to CodeGraphContext","text":"<p>Thank you for your interest in contributing to CodeGraphContext (CGC). We welcome contributions from the community to improve the performance, language support, and tooling capabilities of the engine.</p>"},{"location":"contributing/#development-principles","title":"Development Principles","text":"<ul> <li>Code Quality: Adhere to PEP 8 standards for Python codebase.</li> <li>Robust Testing: Every bug fix, driver implementation, or parser extension must be accompanied by unit or integration tests.</li> <li>Focused Commits: Keep pull requests focused on a single change set.</li> <li>Maintain Documentation: Update references and guides if code changes alter command arguments or configurations.</li> </ul>"},{"location":"contributing/#setting-up-the-development-workspace","title":"Setting Up the Development Workspace","text":"<ol> <li> <p>Clone the Repository: <pre><code>git clone https://github.com/CodeGraphContext/CodeGraphContext.git\ncd CodeGraphContext\n</code></pre></p> </li> <li> <p>Initialize Virtual Environment: Initialize an isolated python environment and install dependencies: <pre><code>python -m venv .venv\nsource .venv/bin/activate\npip install -e \".[dev]\"\n</code></pre></p> </li> </ol>"},{"location":"contributing/#development-workflows","title":"Development Workflows","text":""},{"location":"contributing/#debug-logging","title":"Debug Logging","text":"<p>Enable verbose debug logs during execution by setting the environment variables: <pre><code>export DEBUG_LOGS=true # developer/troubleshooting logs\nexport ENABLE_APP_LOGS=DEBUG # application log level (default: CRITICAL)\ncgc index\n</code></pre></p> <p><code>LIBRARY_LOG_LEVEL</code> controls the verbosity of third-party libraries (neo4j, asyncio, urllib3) separately, and defaults to <code>WARNING</code>.</p>"},{"location":"contributing/#running-the-test-suite","title":"Running the Test Suite","text":"<p>The testing pipeline utilizes <code>pytest</code>. Ensure all checks pass locally before pushing changes:</p> <pre><code># Run all unit and integration tests\npytest\n\n# Test a specific driver module\npytest tests/unit/core/test_database_kuzu_compat.py\n</code></pre> <p>Note: Integration tests for remote databases like Neo4j require a running local database instance (refer to docker-compose.yml).</p>"},{"location":"contributing/#formatting-linting","title":"Formatting &amp; Linting","text":"<p>We enforce formatting and static checks via <code>ruff</code>. Run linting checks before committing:</p> <pre><code>ruff check .\nruff format .\n</code></pre>"},{"location":"contributing/#pull-request-guidelines","title":"Pull Request Guidelines","text":"<ol> <li>Feature Branches: Branch from <code>main</code> using descriptive naming (e.g., <code>feat/ladybug-concurrency</code> or <code>fix/mcp-json-rpc</code>).</li> <li>Commit Styling: Write clear, descriptive commit logs.</li> <li>Submission: Open a pull request against the <code>main</code> branch. Detail the modification, verify unit test runs, and link to open issue tickets if applicable.</li> </ol>"},{"location":"contributing_languages/","title":"Adding Language Support","text":"<p>This guide outlines the steps required to add parsing support for a new programming language to CodeGraphContext.</p>"},{"location":"contributing_languages/#1-architectural-integration","title":"1. Architectural Integration","text":"<p>CGC uses a modular parsing system based on Tree-sitter:</p> <ol> <li><code>TreeSitterParser</code> (<code>graph_builder.py</code>): The primary generic wrapper that dispatches files to specific language sub-parsers.</li> <li>Language Parser Modules (<code>src/codegraphcontext/tools/languages/</code>): Individual python modules containing:</li> <li>Tree-sitter AST tags queries (<code>&lt;LANG&gt;_QUERIES</code>).</li> <li>A <code>&lt;Lang&gt;TreeSitterParser</code> class inheriting from the parser interface.</li> <li>A <code>pre_scan_&lt;lang&gt;</code> method for rapid initial symbol caching.</li> <li><code>GraphBuilder</code>: Dispatches files to language parsers, resolves imports, and feeds nodes/relationships to the persistence drivers.</li> </ol>"},{"location":"contributing_languages/#2-step-by-step-implementation","title":"2. Step-by-Step Implementation","text":""},{"location":"contributing_languages/#step-a-create-the-language-parser-module","title":"Step A: Create the Language Parser Module","text":"<p>Create a new file under <code>src/codegraphcontext/tools/languages/</code> (e.g., <code>typescript.py</code>).</p> <p>Add standard parser imports: <pre><code>from pathlib import Path\nfrom typing import Dict, Any, List\nfrom codegraphcontext.tools.languages.base import BaseParser\n</code></pre></p>"},{"location":"contributing_languages/#step-b-define-ast-tag-queries","title":"Step B: Define AST Tag Queries","text":"<p>AST tags are parsed using Tree-sitter query expressions. Define queries to target: - <code>functions</code>: Standard functions, methods, arrow assignments. - <code>classes</code>: Class and interface boundaries. - <code>imports</code>: Syntax specifying external file or module dependencies. - <code>calls</code>: Function or method invocations. - <code>variables</code>: Variable declarations and assignments.</p> <p>Tip: Use the CLI <code>tree-sitter parse</code> tool to inspect a sample source file's Concrete Syntax Tree (CST) and locate the correct node name keys.</p>"},{"location":"contributing_languages/#step-c-implement-the-parser-class","title":"Step C: Implement the Parser Class","text":"<p>Inherit from the base parser and implement AST extraction routines:</p> <pre><code>class TypescriptTreeSitterParser(BaseParser):\n def __init__(self, generic_parser):\n super().__init__(generic_parser, \"typescript\")\n self.queries = self.load_queries()\n\n def parse(self, path: Path, is_dependency: bool = False) -&gt; Dict[str, Any]:\n content = path.read_text()\n tree = self.parser.parse(bytes(content, \"utf8\"))\n\n # Populate and return standardized AST data structures\n return {\n \"functions\": self._find_functions(tree, content),\n \"classes\": self._find_classes(tree, content),\n \"calls\": self._find_calls(tree, content),\n \"imports\": self._find_imports(tree, content),\n \"variables\": self._find_variables(tree, content),\n }\n</code></pre>"},{"location":"contributing_languages/#step-d-implement-the-fast-pre-scan","title":"Step D: Implement the Fast Pre-Scan","text":"<p>Define a fast pre-scan routine to map declaration locations before linking call relationships:</p> <pre><code>def pre_scan_typescript(files: List[Path], parser_wrapper) -&gt; Dict[str, Path]:\n # Returns a dictionary mapping class/function symbol names to file paths.\n ...\n</code></pre>"},{"location":"contributing_languages/#step-e-register-the-parser","title":"Step E: Register the Parser","text":"<p>Map the file extension to the new parser class in <code>parser_factory.py</code>:</p> <pre><code># Map extension inside the registry\nSUPPORTED_LANGUAGES = {\n \".ts\": \"typescript\",\n \".tsx\": \"typescript\",\n}\n</code></pre>"},{"location":"contributing_languages/#3-verification-diagnostic-queries","title":"3. Verification &amp; Diagnostic Queries","text":"<p>Once the parser is registered, verify graph extraction using sample source files:</p> <ol> <li>Index a test codebase: <pre><code>cgc index ./tests/fixtures/sample_ts_project/ --force\n</code></pre></li> <li>Execute verification queries using Cypher:</li> <li>Verify files are parsed: <pre><code>cgc query \"MATCH (f:File) RETURN f.path, f.language\"\n</code></pre></li> <li>Verify functions are identified: <pre><code>cgc query \"MATCH (f:File)-[:CONTAINS]-&gt;(fn:Function) RETURN f.path, fn.name\"\n</code></pre></li> <li>Verify caller links: <pre><code>cgc query \"MATCH (caller:Function)-[:CALLS]-&gt;(callee:Function) RETURN caller.name, callee.name\"\n</code></pre></li> </ol>"},{"location":"contributing_languages/#emacs-lisp-smoke-check","title":"Emacs Lisp smoke check","text":"<p>Emacs Lisp support uses the <code>elisp</code> grammar already distributed by <code>tree-sitter-language-pack</code>; no external Emacs process or manual grammar compilation is required for the Tree-sitter path.</p> <p>To smoke-test the checked-in two-file fixture against an isolated Kuzu database:</p> <pre><code>tmpdir=$(mktemp -d)\nexport PYTHONPATH=src\nexport DEFAULT_DATABASE=kuzudb\nexport CGC_RUNTIME_DB_TYPE=kuzudb\nexport CGC_RUNTIME_DB_PATH=\"$tmpdir/kuzu.db\"\n\nuv run python -m codegraphcontext index tests/fixtures/sample_projects/sample_project_elisp --force\n\nuv run python -m codegraphcontext query \"MATCH (f:File) WHERE f.path ENDS WITH '.el' RETURN f.name AS file ORDER BY file\"\nuv run python -m codegraphcontext query \"MATCH (fn:Function) WHERE fn.lang = 'elisp' RETURN fn.name AS function ORDER BY function\"\nuv run python -m codegraphcontext query \"MATCH (v:Variable) WHERE v.lang = 'elisp' RETURN v.name AS variable ORDER BY variable\"\nuv run python -m codegraphcontext query \"MATCH (f:File)-[:IMPORTS]-&gt;(m:Module) RETURN f.name AS file, m.name AS module ORDER BY file, module\"\nuv run python -m codegraphcontext query \"MATCH (caller:Function)-[:CALLS]-&gt;(callee:Function) WHERE caller.lang = 'elisp' RETURN caller.name AS caller_name, callee.name AS callee_name ORDER BY caller_name, callee_name\"\n\nrm -rf \"$tmpdir\"\n</code></pre> <p>Expected results include <code>foo-core.el</code> and <code>foo-ui.el</code>, function nodes such as <code>foo-core-greet</code> and <code>foo-ui-render</code>, variable nodes such as <code>foo-core-count</code> and <code>foo-core-loud</code>, module nodes for <code>cl-lib</code>, <code>foo-core</code>, and <code>foo-ui</code>, and direct call edges including <code>foo-ui-render -&gt; foo-core-greet</code> and <code>foo-core-greet -&gt; foo-core-format</code>.</p>"},{"location":"contributing_languages/#solidity-smoke-check","title":"Solidity smoke check","text":"<p>Solidity support uses the <code>solidity</code> grammar from <code>tree-sitter-language-pack</code> (JoranHonig/tree-sitter-solidity). There is no SCIP indexer in v1 \u2014 Tree-sitter only.</p> <pre><code>tmpdir=$(mktemp -d)\nexport PYTHONPATH=src\nexport DEFAULT_DATABASE=kuzudb\nexport CGC_RUNTIME_DB_TYPE=kuzudb\nexport CGC_RUNTIME_DB_PATH=\"$tmpdir/kuzu.db\"\n\nuv run python -m codegraphcontext index tests/fixtures/sample_projects/sample_project_solidity --force\n\nuv run python -m codegraphcontext query \"MATCH (f:File) WHERE f.path ENDS WITH '.sol' RETURN f.name AS file ORDER BY file\"\nuv run python -m codegraphcontext query \"MATCH (c:Class) WHERE c.lang = 'solidity' RETURN c.name AS class ORDER BY class\"\nuv run python -m codegraphcontext query \"MATCH (fn:Function) WHERE fn.lang = 'solidity' RETURN fn.name AS function ORDER BY function\"\nuv run python -m codegraphcontext query \"MATCH (a)-[:INHERITS]-&gt;(b) RETURN a.name AS child, b.name AS parent ORDER BY child, parent\"\nuv run python -m codegraphcontext query \"MATCH (caller:Function)-[:CALLS]-&gt;(callee) WHERE caller.lang = 'solidity' RETURN caller.name AS caller_name, callee.name AS callee_name ORDER BY caller_name, callee_name\"\n\n# Foundry remapping fixture\nuv run python -m codegraphcontext index tests/fixtures/sample_projects/sample_project_solidity_foundry --force\nuv run python -m codegraphcontext query \"MATCH (f:File)-[i:IMPORTS]-&gt;(m:Module) WHERE f.name = 'App.sol' RETURN m.name, i.full_import_name\"\n\nrm -rf \"$tmpdir\"\n</code></pre> <p>Expected results include files such as <code>Greeter.sol</code> / <code>BaseGreeter.sol</code> / <code>UsingCounter.sol</code>, classes/interfaces such as <code>Greeter</code>, <code>BaseGreeter</code>, <code>IGreeter</code>, <code>MathLib</code>, functions such as <code>greet</code> / <code>bump</code> / <code>add</code>, inheritance <code>Greeter -&gt; BaseGreeter</code>, modifier CALLS (<code>nonEmpty</code>), <code>using for</code> rewrites (<code>MathLib.add</code>), emit CALLS (<code>Greeted</code>), and remapped imports for <code>App.sol</code> resolving <code>forge-std/Helper.sol</code> \u2192 <code>lib/helper/src/Helper.sol</code>.</p>"},{"location":"contributing_languages/#solidity-limitations-v1","title":"Solidity limitations (v1)","text":"Area Behavior SCIP Not supported \u2014 no standard <code>scip-solidity</code> batch indexer Yul / <code>assembly</code> Parse-tolerant; bodies not modeled as a separate graph Remappings Reads <code>foundry.toml</code> <code>remappings = [...]</code> and <code>remappings.txt</code> (longest prefix). Does not run <code>forge</code>. Dependencies only under ignored trees (e.g. <code>node_modules/</code>) stay unresolved unless remapped into an indexed path <code>delegatecall</code> / dynamic targets Best-effort name matching only Events / custom errors Declared as Class-like nodes; <code>emit</code> / <code>revert Error()</code> recorded as CALLS with <code>call_kind</code> <code>emit</code> / <code>revert_error</code> (no separate <code>EMITS</code> edge type) Modifiers Invocations emit CALLS; deep inherited-modifier MRO is best-effort via normal call resolution Noise Filters free built-ins (<code>require</code>, <code>keccak256</code>, \u2026) and receivers <code>vm</code> / <code>msg</code> / <code>abi</code> / \u2026 Name collisions Prefer path-qualified Cypher (<code>WHERE f.path CONTAINS '\u2026'</code>) in monorepos that also contain TypeScript mirrors"},{"location":"contributing_languages/#emacs-lisp-scip-follow-up","title":"Emacs Lisp SCIP follow-up","text":"<p>The initial Emacs Lisp implementation intentionally stays on the Tree-sitter pipeline. There is no standard <code>scip-elisp</code> indexer to register in <code>EXTENSION_TO_SCIP</code>, and the commonly used <code>elisp-refs</code> package is designed as an interactive Emacs reference finder rather than a batch indexer: it searches files recorded in the running Emacs <code>load-history</code>, renders results in a special buffer instead of emitting JSON or SCIP data, and exposes useful Lisp-2 function/variable heuristics only through internal APIs.</p> <p>A future semantic indexer could reuse those heuristics in a dedicated batch wrapper, but it would still need directory discovery, side-effect-safe loading or buffer creation, line/column conversion from character offsets, structured output, and explicit handling for macro expansion and indirect calls. Until that exists, <code>.el</code> files should continue to use Tree-sitter indexing with documented limitations around arbitrary macro semantics and dynamic dispatch.</p>"},{"location":"license/","title":"License","text":"<p>CodeGraphContext is licensed under the MIT License.</p> <pre><code>MIT License\n\nCopyright (c) 2025\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n</code></pre>"},{"location":"roadmap/","title":"CodeGraphContext: 6-Month Evolution &amp; Feature Roadmap","text":"<p>CodeGraphContext (CGC) is a polyglot code intelligence tool that maps static codebases into queryable graph databases, exposing this context to AI assistants and developers. This document provides a complete inventory of CGC's existing features, details its current limitations, and outlines a comprehensive 6-month evolution path split into 50 distinct milestones.</p>"},{"location":"roadmap/#1-inventory-of-current-cgc-capabilities","title":"1. Inventory of Current CGC Capabilities","text":"<p>Below is the inventory of features currently implemented, shipped, and operational within the CodeGraphContext codebase:</p>"},{"location":"roadmap/#11-ingestion-parsing","title":"1.1 Ingestion &amp; Parsing","text":"<ul> <li>Polyglot Tree-Sitter Parsers: Parser classes for 20 target languages:</li> <li>Python (with Jupyter Notebook/<code>.ipynb</code> cells support via <code>nbformat</code>/<code>nbconvert</code>)</li> <li>JavaScript, TypeScript, TSX</li> <li>Go, Rust, C, C++</li> <li>Java, Kotlin, Scala</li> <li>Ruby, C#, PHP, Swift</li> <li>Dart, Perl, Haskell, Elixir, Lua</li> <li>SCIP Parsing Pipeline: Optional protobuf-based precise indexer leveraging external <code>scip-*</code> language tools for deep AST symbol extraction.</li> <li>Dependency Resolvers: Package path resolution logic for 9 languages to link external dependencies into the graph representation.</li> <li>Incremental Watcher: Multi-threaded <code>watchdog</code> system for automatic file modification, creation, and deletion detection with debounced graph writes.</li> <li><code>.cgcignore</code> Filter: Custom pattern matcher adhering to <code>.gitignore</code>-style rules to prevent noise (vendor folders, binaries) from entering the graph database.</li> </ul>"},{"location":"roadmap/#12-graph-persistence-schemas","title":"1.2 Graph Persistence &amp; Schemas","text":"<ul> <li>Database Adapters: Consistent connection wrappers for 5 backend drivers:</li> <li>FalkorDB Lite: Local embedded UNIX DB via Redislite.</li> <li>FalkorDB Remote: Remote FalkorDB client.</li> <li>KuzuDB: Local embedded relational-graph DB (default for Windows).</li> <li>Neo4j: Server-side graph database (AuraDB/Docker compatible).</li> <li>Nornic DB: Neo4j-compatible embedded database driver.</li> <li>Graph Schema: Schema contracts enforcing 17 node labels (e.g., <code>Repository</code>, <code>File</code>, <code>Function</code>, <code>Class</code>, <code>Variable</code>, <code>Interface</code>, <code>Enum</code>, <code>Parameter</code>) and 7 relationship types (<code>CONTAINS</code>, <code>CALLS</code>, <code>IMPORTS</code>, <code>INHERITS</code>, <code>IMPLEMENTS</code>, <code>HAS_PARAMETER</code>, <code>INCLUDES</code>).</li> </ul>"},{"location":"roadmap/#13-query-analysis-codefinder","title":"1.3 Query &amp; Analysis (CodeFinder)","text":"<ul> <li>Fuzzy Search: In-memory Levenshtein distance fallback search for classes and functions across all DB backends.</li> <li>Ast &amp; Structural Queries: Out-of-the-box Cypher queries for:</li> <li>Transitive call chains and callers/callees.</li> <li>Class inheritance and C# interface implementations.</li> <li>Complexity analysis (Cyclomatic complexity calculations).</li> <li>Dead code analysis (unreferenced files and function declarations).</li> <li>Variable scope tracking and usage analysis.</li> <li>Named Contexts: Local configuration profiles allowing switching between global contexts, per-repository contexts, or shared workspace contexts.</li> </ul>"},{"location":"roadmap/#14-interfaces-client-integration","title":"1.4 Interfaces &amp; Client Integration","text":"<ul> <li>MCP Server: JSON-RPC over <code>stdio</code> implementing 20 tools for tools/list and tools/call, allowing cursor/claude to interact with the database.</li> <li>CLI Commands: Over 55 interactive and command-line scripts for configuration, index wizardry, health checks (<code>cgc doctor</code>), and query execution.</li> <li>Viz Server &amp; Website:</li> <li>FastAPI server serving static visual assets locally.</li> <li>React SPA with force-directed graphs (2D, 3D, 3D City visual structures, and Mermaid flowchart SVG exports).</li> <li>In-browser parsing worker utilizing <code>web-tree-sitter</code> WASM files to parse local uploads or cloned GitHub repositories without Python dependencies.</li> <li>Bundles &amp; Registry:</li> <li><code>.cgc</code> archive format for exporting/importing graph snapshots.</li> <li>GitHub-backed registry search and on-demand trigger mechanism via GitHub Actions dispatch.</li> </ul>"},{"location":"roadmap/#15-vs-code-extension","title":"1.5 VS Code Extension","text":"<ul> <li>Early-stage vsix extension (<code>extensions/vscode</code>):</li> <li>Setup wizard commands and activity bar viewer stubs.</li> <li>Config management matching core CLI options.</li> <li>Interactive menus and control panel webview.</li> </ul>"},{"location":"roadmap/#2-current-known-bugs-technical-limitations","title":"2. Current Known Bugs &amp; Technical Limitations","text":"Code Type Limitation / Bug Severity Impact L1 Arch Single-process MCP Server Medium The standard stdio JSON-RPC transport limits the server to one IDE wrapper instance at a time; no concurrent shared connections. L2 Arch Sync-over-Async Handlers Low Handlers run in threads (<code>asyncio.to_thread</code>). True non-blocking asynchronous drivers for Neo4j/Kuzu are not utilized. L3 Arch In-Memory Job Manager Medium Background indexing job states are lost on server restart, leading to broken job polling. L4 Arch Monolithic <code>cli/main.py</code> Medium CLI commands are structured in a single 2386-line file, increasing maintenance overhead and making testing difficult. L5 Arch Monolithic <code>CodeGraphViewer.tsx</code> High Renders layout, handles Cytoscape/Force-graph state, and processes files in a single 1579-line file. L6 DB FalkorDB UNIX Restriction Medium FalkorDB Lite is blocked on Windows due to redislite binaries, causing silent fallbacks. L7 DB KuzuDB Cypher Dialect Discrepancies High Specific Cypher queries (e.g. <code>UNWIND</code>, aggregations) behave differently between Kuzu and Neo4j, resulting in query failures. L8 Parse Syntactic Boundary Medium Tree-sitter has no type solver; dynamic imports or duplicate class names across folders can result in false connections in the call graph. L9 Parse Stubbed Advanced Toolkits High All 16 language <code>*Toolkit</code> classes in <code>query_tool_languages/</code> raise <code>NotImplementedError</code> when advanced queries are invoked. L10 Test Flaky Integration Tests Medium <code>test_cgcignore_patterns.py</code> requires a fully installed workspace and a live DB, leading to CI failures. L11 Test Ruby Mixins and C++ Duplicate Tests Low Stubbed test fixtures like <code>test_mixins.py</code> refer to invalid fixtures, and C++ tests are duplicated."},{"location":"roadmap/#3-the-6-month-evolutionary-roadmap-50-milestones","title":"3. The 6-Month Evolutionary Roadmap (50 Milestones)","text":"<p>Here is the week-by-week and month-by-month execution plan to address the constraints, scale the architecture, and implement the planned integrations (Ollama, cloud LLMs, browser extensions, benchmarking, and VS Code upgrades).</p>"},{"location":"roadmap/#month-1-architectural-refactoring-testing-isolation-benchmarking-milestones-19","title":"Month 1: Architectural Refactoring, Testing Isolation &amp; Benchmarking (Milestones 1\u20139)","text":"<p>Focus: De-monolithing the CLI and frontend, isolating tests, and implementing a real indexing performance bench.</p>"},{"location":"roadmap/#milestone-1-deconstruct-climainpy-monolith","title":"Milestone 1: Deconstruct <code>cli/main.py</code> Monolith","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: Typer CLI, Python Package structures.</li> <li>Deliverable: Split <code>cli/main.py</code> into separate sub-command modules under <code>codegraphcontext/cli/commands/</code> (e.g., <code>index.py</code>, <code>find.py</code>, <code>analyze.py</code>, <code>bundle.py</code>).</li> <li>Behavioral Improvement: Developer maintenance increases; CLI startup overhead drops because only required commands are imported.</li> </ul>"},{"location":"roadmap/#milestone-2-refactor-codegraphviewertsx","title":"Milestone 2: Refactor <code>CodeGraphViewer.tsx</code>","text":"<ul> <li>Difficulty: Hard</li> <li>Knowledge Needed: React, TypeScript, state synchronization.</li> <li>Deliverable: Split the React viewer into subcomponents (<code>GraphCanvas</code>, <code>CodeViewerSidebar</code>, <code>SearchAndFilter</code>, <code>VisualSettingsPanel</code>).</li> <li>Behavioral Improvement: Frontend codebase becomes modular, making it easier to fix rendering bugs and add custom layout managers.</li> </ul>"},{"location":"roadmap/#milestone-3-database-query-interface-protocol-r4","title":"Milestone 3: Database Query Interface Protocol (R4)","text":"<ul> <li>Difficulty: Hard</li> <li>Knowledge Needed: Cypher dialects (Kuzu vs Neo4j vs FalkorDB), Abstract Base Classes.</li> <li>Deliverable: Extract database queries from <code>CodeFinder</code> into a dedicated translation layer (<code>GraphQueryInterface</code>), with subclassed providers for KuzuDB and Neo4j.</li> <li>Behavioral Improvement: Eliminates Cypher dialect differences; KuzuDB queries no longer crash on unsupported Cypher syntax.</li> </ul>"},{"location":"roadmap/#milestone-4-clean-and-isolate-test-suite-l11-l10","title":"Milestone 4: Clean and Isolate Test Suite (L11, L10)","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: pytest, mocks, CI environment configurations.</li> <li>Deliverable: Remove the dead <code>test_mixins.py</code> Ruby fixture; deduplicate C++ tests; isolate <code>test_cgcignore_patterns.py</code> by mocking the database connection.</li> <li>Behavioral Improvement: CI run succeeds on every commit without needing local DB servers or pre-installed environment binaries.</li> </ul>"},{"location":"roadmap/#milestone-5-standardized-error-schema-and-handler-layer-r10","title":"Milestone 5: Standardized Error Schema and Handler Layer (R10)","text":"<ul> <li>Difficulty: Easy</li> <li>Knowledge Needed: MCP protocol, error-handling conventions.</li> <li>Deliverable: Establish structured error codes and messages for the MCP response payloads (e.g., <code>INDEX_NOT_FOUND</code>, <code>DB_CONNECTION_LOST</code>).</li> <li>Behavioral Improvement: AI assistants understand why a tool call failed and can recover gracefully (e.g., prompting the user to run an indexer).</li> </ul>"},{"location":"roadmap/#milestone-6-bundle-schema-versioning-validation-r12-r13","title":"Milestone 6: Bundle Schema Versioning &amp; Validation (R12, R13)","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: ZIP archiving, JSON schema validation, version parsing.</li> <li>Deliverable: Add a version header inside the <code>.cgc</code> bundle <code>metadata.json</code> and create the <code>cgc bundle validate &lt;path&gt;</code> CLI command.</li> <li>Behavioral Improvement: Prevents older versions of CGC from loading newer, incompatible database structures, alerting the user with clear instructions.</li> </ul>"},{"location":"roadmap/#milestone-7-build-real-world-ingestion-benchmarking-suite-r9","title":"Milestone 7: Build Real-World Ingestion Benchmarking Suite (R9)","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: Benchmarking methodologies, performance telemetry.</li> <li>Deliverable: Create <code>scripts/run_benchmarks.py</code> using a standard corpus of target repositories (e.g., a 100k LOC Python/Go codebase). Track parsing throughput (LOC/sec) and database insertion latencies.</li> <li>Behavioral Improvement: Provides quantitative metrics on indexing speed, preventing regressions during parser upgrades.</li> </ul>"},{"location":"roadmap/#milestone-8-establish-query-latency-profiling","title":"Milestone 8: Establish Query Latency Profiling","text":"<ul> <li>Difficulty: Easy</li> <li>Knowledge Needed: Python timing utilities, Cypher EXPLAIN.</li> <li>Deliverable: Include Cypher query execution time metrics in debug logs and <code>cgc</code> CLI output.</li> <li>Behavioral Improvement: Developers can identify slow queries and optimize database constraints/indexes accordingly.</li> </ul>"},{"location":"roadmap/#milestone-9-persistent-job-manager-l3-r6","title":"Milestone 9: Persistent Job Manager (L3, R6)","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: SQLite, async job states.</li> <li>Deliverable: Replace the in-memory dict in <code>JobManager</code> with a lightweight, embedded SQLite table (<code>jobs.db</code>) under <code>.codegraphcontext/</code>.</li> <li>Behavioral Improvement: Long-running index jobs resume or report correct failed/completed states if the IDE or MCP server restarts.</li> </ul>"},{"location":"roadmap/#month-2-core-database-optimization-advanced-language-toolkits-milestones-1018","title":"Month 2: Core Database Optimization &amp; Advanced Language Toolkits (Milestones 10\u201318)","text":"<p>Focus: True asynchronous driver interfaces, query optimizations, and implementing the stubbed programming language query toolkits.</p>"},{"location":"roadmap/#milestone-10-implement-core-python-toolkit-queries-l9","title":"Milestone 10: Implement Core Python <code>*Toolkit</code> Queries (L9)","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: Python Tree-sitter AST, import hooks.</li> <li>Deliverable: Implement <code>PythonToolkit</code> queries for advanced tasks (e.g., identifying decorators, resolving dynamic import boundaries).</li> <li>Behavioral Improvement: The AI assistant can execute target queries tailored specifically to Pythonic patterns instead of generic text searches.</li> </ul>"},{"location":"roadmap/#milestone-11-implement-jsts-and-tsx-toolkit-queries","title":"Milestone 11: Implement JS/TS and TSX <code>*Toolkit</code> Queries","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: JS/TS AST structures.</li> <li>Deliverable: Fill in the JS/TS and TSX toolkit query stubs to handle class overrides, export patterns, and React hook dependencies.</li> <li>Behavioral Improvement: Yields accurate query results for JS/TS codebases.</li> </ul>"},{"location":"roadmap/#milestone-12-implement-go-and-rust-toolkit-queries","title":"Milestone 12: Implement Go and Rust <code>*Toolkit</code> Queries","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: Go and Rust syntax structures (traits, interfaces, structs, impl blocks).</li> <li>Deliverable: Implement toolkit stubs for Go (struct composition) and Rust (trait implementations, lifetimes).</li> <li>Behavioral Improvement: Allows the AI to query traits and interface compositions accurately.</li> </ul>"},{"location":"roadmap/#milestone-13-implement-java-and-c-toolkit-queries","title":"Milestone 13: Implement Java and C# <code>*Toolkit</code> Queries","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: JVM and .NET syntax patterns.</li> <li>Deliverable: Implement toolkit stubs for Java and C# to support generic parameter constraints, annotations, and properties.</li> <li>Behavioral Improvement: Provides accurate class inheritance hierarchies and interface implementations.</li> </ul>"},{"location":"roadmap/#milestone-14-implement-c-and-c-toolkit-queries","title":"Milestone 14: Implement C and C++ <code>*Toolkit</code> Queries","text":"<ul> <li>Difficulty: Hard</li> <li>Knowledge Needed: C/C++ AST, preprocessor patterns.</li> <li>Deliverable: Implement toolkits to track macro expansions and header inclusion graphs.</li> <li>Behavioral Improvement: AI can trace complex C++ macro chains and header-source relationships.</li> </ul>"},{"location":"roadmap/#milestone-15-non-blocking-asynchronous-database-drivers-l2","title":"Milestone 15: Non-Blocking Asynchronous Database Drivers (L2)","text":"<ul> <li>Difficulty: Hard</li> <li>Knowledge Needed: Python <code>asyncio</code>, asynchronous DB drivers (<code>neo4j.AsyncDriver</code>, <code>kuzu</code> async routines).</li> <li>Deliverable: Refactor the database connection layer to use async calls, eliminating thread pools (<code>asyncio.to_thread</code>) for database operations.</li> <li>Behavioral Improvement: Enhances server throughput and reduces thread overhead under heavy concurrent MCP tool calls.</li> </ul>"},{"location":"roadmap/#milestone-16-db-connection-pooling-l11","title":"Milestone 16: DB Connection Pooling (L11)","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: Database connection pooling.</li> <li>Deliverable: Implement connection pooling for Neo4j and KuzuDB adapters.</li> <li>Behavioral Improvement: Eliminates connection handshake overhead for consecutive tool calls, reducing query latency.</li> </ul>"},{"location":"roadmap/#milestone-17-query-result-streaming-l8","title":"Milestone 17: Query Result Streaming (L8)","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: Python generators, streaming JSON serialization.</li> <li>Deliverable: Implement a generator-based streaming query pipeline for large Cypher query results.</li> <li>Behavioral Improvement: Eliminates out-of-memory crashes when querying large graphs.</li> </ul>"},{"location":"roadmap/#milestone-18-kuzudb-dialect-compatibility-layer","title":"Milestone 18: KuzuDB Dialect Compatibility Layer","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: KuzuDB Cypher constraints.</li> <li>Deliverable: Implement a query rewriter that converts standard Neo4j Cypher functions into KuzuDB-compatible Cypher.</li> <li>Behavioral Improvement: Standardizes Cypher features across all backends.</li> </ul>"},{"location":"roadmap/#month-3-deep-ast-parsing-semantic-ingestion-upgrades-milestones-1927","title":"Month 3: Deep AST Parsing &amp; Semantic Ingestion Upgrades (Milestones 19\u201327)","text":"<p>Focus: Enhancing parsers, supporting non-code assets, improving incremental ingestion, and adding type inference patterns.</p>"},{"location":"roadmap/#milestone-19-c-header-parser-disambiguation-l16","title":"Milestone 19: C++ Header Parser Disambiguation (L16)","text":"<ul> <li>Difficulty: Easy</li> <li>Knowledge Needed: Tree-sitter C vs C++ ASTs.</li> <li>Deliverable: Check for pure C markers in <code>.h</code> files to select either the C or C++ parser.</li> <li>Behavioral Improvement: Reduces parse errors for pure C libraries.</li> </ul>"},{"location":"roadmap/#milestone-20-html-and-css-tree-sitter-parsers-l17","title":"Milestone 20: HTML and CSS Tree-Sitter Parsers (L17)","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: HTML/CSS syntax trees.</li> <li>Deliverable: Add parsers for HTML tags and CSS class declarations.</li> <li>Behavioral Improvement: Bridges the gap between frontend templates and backend logic by connecting component classes to styles.</li> </ul>"},{"location":"roadmap/#milestone-21-sql-shell-yaml-parsers-l17","title":"Milestone 21: SQL, Shell &amp; YAML Parsers (L17)","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: SQL dialects, Bash syntax, Tree-sitter.</li> <li>Deliverable: Extract database queries from source code and link them to parsed SQL schemas.</li> <li>Behavioral Improvement: Extends the dependency graph to cover database interactions and configuration files.</li> </ul>"},{"location":"roadmap/#milestone-22-incremental-ingestion-concurrency-tuning","title":"Milestone 22: Incremental Ingestion Concurrency Tuning","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: Multi-processing, file lock queues.</li> <li>Deliverable: Implement worker pools using Python's <code>multiprocessing</code> for parsing, while serializing writes to the database.</li> <li>Behavioral Improvement: Speeds up initial parsing on multi-core machines.</li> </ul>"},{"location":"roadmap/#milestone-23-type-inference-symbol-reference-resolution","title":"Milestone 23: Type Inference &amp; Symbol Reference Resolution","text":"<ul> <li>Difficulty: Hard</li> <li>Knowledge Needed: AST scope analysis, basic type inference.</li> <li>Deliverable: Implement a cross-file reference resolver to link function call parameters to class instantiations.</li> <li>Behavioral Improvement: Improves the accuracy of the call graph by reducing ambiguous function name links.</li> </ul>"},{"location":"roadmap/#milestone-24-incremental-scip-ingestion-l15","title":"Milestone 24: Incremental SCIP Ingestion (L15)","text":"<ul> <li>Difficulty: Hard</li> <li>Knowledge Needed: SCIP protocol specifications, git diffs.</li> <li>Deliverable: Implement incremental SCIP indexing based on git diffs.</li> <li>Behavioral Improvement: Reduces indexing times for large projects when using SCIP.</li> </ul>"},{"location":"roadmap/#milestone-25-automated-scip-installer-script-l14","title":"Milestone 25: Automated SCIP Installer Script (L14)","text":"<ul> <li>Difficulty: Easy</li> <li>Knowledge Needed: Shell scripting, platform binaries.</li> <li>Deliverable: Create <code>cgc index setup-scip</code> to download and install language-specific SCIP binaries.</li> <li>Behavioral Improvement: Reduces setup friction for SCIP indexing.</li> </ul>"},{"location":"roadmap/#milestone-26-ast-cognitive-complexity-calculations","title":"Milestone 26: AST Cognitive Complexity Calculations","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: Static analysis metrics.</li> <li>Deliverable: Implement cognitive complexity parsing alongside cyclomatic complexity.</li> <li>Behavioral Improvement: AI can identify hard-to-maintain code blocks, not just branch-heavy ones.</li> </ul>"},{"location":"roadmap/#milestone-27-workspace-index-size-estimation-utility","title":"Milestone 27: Workspace Index Size Estimation Utility","text":"<ul> <li>Difficulty: Easy</li> <li>Knowledge Needed: CLI user interface design.</li> <li>Deliverable: Create an indexing pre-flight check command showing estimated node count and DB disk usage.</li> <li>Behavioral Improvement: Helps users budget disk space before indexing large codebases.</li> </ul>"},{"location":"roadmap/#month-4-vs-code-extension-upgrades-milestones-2835","title":"Month 4: VS Code Extension Upgrades (Milestones 28\u201335)","text":"<p>Focus: Turning the VS Code extension into a fully featured visual and analytical assistant.</p>"},{"location":"roadmap/#milestone-28-interactive-webview-control-dashboard","title":"Milestone 28: Interactive Webview Control Dashboard","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: VS Code Extension API, React build integration.</li> <li>Deliverable: Embed the local React dashboard within a VS Code webview panel.</li> <li>Behavioral Improvement: Users can view the codebase graph directly inside the IDE.</li> </ul>"},{"location":"roadmap/#milestone-29-codelens-complexity-dependency-markers","title":"Milestone 29: CodeLens Complexity &amp; Dependency Markers","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: VS Code CodeLens API, CGC CLI queries.</li> <li>Deliverable: Overlay cyclomatic complexity and class hierarchies above code declarations.</li> <li>Behavioral Improvement: Developers see code metrics contextually while writing code.</li> </ul>"},{"location":"roadmap/#milestone-30-vs-code-inline-cypher-console","title":"Milestone 30: VS Code Inline Cypher Console","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: VS Code Webview panels, Cypher execution.</li> <li>Deliverable: Implement an inline Cypher query editor with syntax highlighting and table previews.</li> <li>Behavioral Improvement: Power users can query the graph without leaving the IDE.</li> </ul>"},{"location":"roadmap/#milestone-31-automatic-watcher-lifecycle-integration-l18","title":"Milestone 31: Automatic Watcher Lifecycle Integration (L18)","text":"<ul> <li>Difficulty: Easy</li> <li>Knowledge Needed: VS Code Workspace Event listeners.</li> <li>Deliverable: Automatically start the file watcher thread when a workspace with <code>.codegraphcontext/</code> is opened.</li> <li>Behavioral Improvement: Code modifications are indexed in the background without manual CLI intervention.</li> </ul>"},{"location":"roadmap/#milestone-32-diagnostics-provider-for-dead-code","title":"Milestone 32: Diagnostics Provider for Dead Code","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: VS Code DiagnosticCollection API.</li> <li>Deliverable: Expose dead code detections as warnings in the VS Code \"Problems\" tab.</li> <li>Behavioral Improvement: Warns developers about unused parameters and dead functions in real-time.</li> </ul>"},{"location":"roadmap/#milestone-33-context-aware-navigation-go-to-definition","title":"Milestone 33: Context-Aware Navigation (Go to Definition)","text":"<ul> <li>Difficulty: Hard</li> <li>Knowledge Needed: VS Code DefinitionProvider.</li> <li>Deliverable: Implement a definition provider powered by the CGC database graph.</li> <li>Behavioral Improvement: Accelerates navigation in dynamic languages where standard VS Code definitions fail.</li> </ul>"},{"location":"roadmap/#milestone-34-graph-guided-refactoring-previews","title":"Milestone 34: Graph-Guided Refactoring Previews","text":"<ul> <li>Difficulty: Hard</li> <li>Knowledge Needed: VS Code WorkspaceEdit API.</li> <li>Deliverable: Show a refactoring preview panel listing files that will be impacted by renaming a symbol.</li> <li>Behavioral Improvement: Reduces regression risks during large refactors.</li> </ul>"},{"location":"roadmap/#milestone-35-one-click-bundle-export-ui","title":"Milestone 35: One-Click Bundle Export UI","text":"<ul> <li>Difficulty: Easy</li> <li>Knowledge Needed: VS Code extension commands.</li> <li>Deliverable: Add a button to export <code>.cgc</code> bundles directly from the sidebar.</li> <li>Behavioral Improvement: Simplifies sharing indexed codebase contexts with team members.</li> </ul>"},{"location":"roadmap/#month-5-chatgpt-web-external-llm-integration-milestones-3643","title":"Month 5: ChatGPT Web &amp; External LLM Integration (Milestones 36\u201343)","text":"<p>Focus: Supporting remote connections, writing browser extensions, and improving the website.</p>"},{"location":"roadmap/#milestone-36-websocket-sse-mcp-transport-protocol-l1","title":"Milestone 36: WebSocket &amp; SSE MCP Transport Protocol (L1)","text":"<ul> <li>Difficulty: Hard</li> <li>Knowledge Needed: WebSockets, Server-Sent Events, JSON-RPC.</li> <li>Deliverable: Add WebSocket and SSE servers to the MCP server process (<code>cgc mcp start --transport ws</code>).</li> <li>Behavioral Improvement: Multiple clients and IDEs can connect to a single, shared CGC database concurrently.</li> </ul>"},{"location":"roadmap/#milestone-37-web-llm-browser-extension-chrome-firefox","title":"Milestone 37: Web LLM Browser Extension (Chrome &amp; Firefox)","text":"<ul> <li>Difficulty: Hard</li> <li>Knowledge Needed: Web Extensions API, Content Scripts, IPC.</li> <li>Deliverable: Build a browser extension that securely connects ChatGPT, Claude, and Gemini web interfaces to the local CGC MCP daemon.</li> <li>Behavioral Improvement: Web-based LLMs can run code queries against local codebases securely.</li> </ul>"},{"location":"roadmap/#milestone-38-web-extension-workspace-matcher","title":"Milestone 38: Web Extension Workspace Matcher","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: Chrome Tab APIs, Local storage.</li> <li>Deliverable: Detect the GitHub URL or active tab project name and select the matching local database context automatically.</li> <li>Behavioral Improvement: Standardizes LLM responses without manual context switching.</li> </ul>"},{"location":"roadmap/#milestone-39-in-browser-worker-parsing-optimizations","title":"Milestone 39: In-Browser Worker Parsing Optimizations","text":"<ul> <li>Difficulty: Hard</li> <li>Knowledge Needed: Web Workers, WASM memory structures, Tree-sitter WASM.</li> <li>Deliverable: Optimize <code>parser.worker.ts</code> with streaming uploads and file chunking.</li> <li>Behavioral Improvement: Allows the browser explorer to parse large repositories without browser tab freezes.</li> </ul>"},{"location":"roadmap/#milestone-40-multi-engine-web-visualizer-upgrades","title":"Milestone 40: Multi-Engine Web Visualizer Upgrades","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: React-force-graph, WebGL rendering.</li> <li>Deliverable: Update <code>CodeGraphViewer.tsx</code> to support WebGL for rendering large graphs.</li> <li>Behavioral Improvement: Renders repositories exceeding 10,000 files smoothly.</li> </ul>"},{"location":"roadmap/#milestone-41-browser-based-cypher-builder","title":"Milestone 41: Browser-Based Cypher Builder","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: React, visual query builders.</li> <li>Deliverable: Add a drag-and-drop visual Cypher query builder to the website's explore tab.</li> <li>Behavioral Improvement: Simplifies querying the graph for users unfamiliar with Cypher syntax.</li> </ul>"},{"location":"roadmap/#milestone-42-web-based-bundle-comparison-panel","title":"Milestone 42: Web-Based Bundle Comparison Panel","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: React diff libraries.</li> <li>Deliverable: Build a visual dashboard to compare two <code>.cgc</code> bundles and highlight structural changes.</li> <li>Behavioral Improvement: Simplifies tracking structural changes across commits.</li> </ul>"},{"location":"roadmap/#milestone-43-secure-origin-policy-configuration","title":"Milestone 43: Secure Origin Policy Configuration","text":"<ul> <li>Difficulty: Easy</li> <li>Knowledge Needed: Web security, CORS headers.</li> <li>Deliverable: Add strict origin validation filters to CLI configs for external connections.</li> <li>Behavioral Improvement: Protects local database ports from unauthorized web requests.</li> </ul>"},{"location":"roadmap/#month-6-llm-api-local-ollama-integrations-milestones-4450","title":"Month 6: LLM API &amp; Local Ollama Integrations (Milestones 44\u201350)","text":"<p>Focus: Adding AI-guided summarization, local vector embeddings, and creating documentation tutorials.</p>"},{"location":"roadmap/#milestone-44-llm-api-key-configuration-cli","title":"Milestone 44: LLM API Key Configuration CLI","text":"<ul> <li>Difficulty: Easy</li> <li>Knowledge Needed: CLI inputs, config file management.</li> <li>Deliverable: Create the <code>cgc config set-key</code> command to securely store OpenAI, Anthropic, and Gemini API keys.</li> <li>Behavioral Improvement: Provides a unified interface for cloud LLM integrations.</li> </ul>"},{"location":"roadmap/#milestone-45-local-ollama-model-integration","title":"Milestone 45: Local Ollama Model Integration","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: Ollama HTTP API, local LLM configurations.</li> <li>Deliverable: Add an Ollama adapter supporting models like <code>qwen2.5-coder</code> or <code>llama3</code>.</li> <li>Behavioral Improvement: Enables offline code analysis and semantic summarization.</li> </ul>"},{"location":"roadmap/#milestone-46-ai-guided-semantic-summarizer","title":"Milestone 46: AI-Guided Semantic Summarizer","text":"<ul> <li>Difficulty: Hard</li> <li>Knowledge Needed: LLM prompts, batch processing.</li> <li>Deliverable: Build an ingestion pipeline stage that uses LLMs to generate summaries of functions and classes, saving them as properties in the graph.</li> <li>Behavioral Improvement: Allows AI assistants to search the graph using natural language concepts.</li> </ul>"},{"location":"roadmap/#milestone-47-graph-rag-vector-embedding-ingestion","title":"Milestone 47: Graph RAG Vector Embedding Ingestion","text":"<ul> <li>Difficulty: Hard</li> <li>Knowledge Needed: Vector embeddings, Kuzu/Neo4j vector indices.</li> <li>Deliverable: Generate embeddings of code summaries and store them in the graph database.</li> <li>Behavioral Improvement: Combines keyword search with structural graph queries for more accurate results.</li> </ul>"},{"location":"roadmap/#milestone-48-high-level-architecture-blogs","title":"Milestone 48: High-Level Architecture Blogs","text":"<ul> <li>Difficulty: Easy</li> <li>Knowledge Needed: Technical writing, blogging structure.</li> <li>Deliverable: Publish a blog series detailing CGC's design (e.g., Tree-sitter parsers, database adapters, and MCP servers).</li> <li>Behavioral Improvement: Enhances community engagement and adoption.</li> </ul>"},{"location":"roadmap/#milestone-50-interactive-walkthrough-and-demos","title":"Milestone 50: Interactive Walkthrough and Demos","text":"<ul> <li>Difficulty: Easy</li> <li>Knowledge Needed: Video editing, documentation design.</li> <li>Deliverable: Produce video tutorials demonstrating VS Code integrations, browser extensions, and CLI commands.</li> <li>Behavioral Improvement: Lowers the barrier to entry for new users.</li> </ul>"},{"location":"roadmap/#milestone-50-production-ready-release-v100","title":"Milestone 50: Production-Ready Release (v1.0.0)","text":"<ul> <li>Difficulty: Medium</li> <li>Knowledge Needed: PyPI workflows, release lifecycle management.</li> <li>Deliverable: Stabilize the API, verify all tests, and publish v1.0.0 to PyPI.</li> <li>Behavioral Improvement: Delivers a production-ready code intelligence tool.</li> </ul>"},{"location":"roadmap/#4-roadmap-implementation-summary","title":"4. Roadmap Implementation Summary","text":"<p>This roadmap prioritizes foundational stability and codebase cleanup in the first month before introducing advanced semantic and AI integrations.</p> <pre><code> Month 1 Month 2 Month 3 Month 4 Month 5 Month 6\n +----------------+ +----------------+ +----------------+ +----------------+ +----------------+ +----------------+\n | Refactoring | -----&gt; | DB Optimization| -----&gt; | Semantic Parse | -----&gt; | VS Code Engine | -----&gt; | ChatGPT Web | -----&gt; | Ollama &amp; RAG |\n | &amp; Benchmarks | | &amp; Language Stubs| | &amp; Incremental | | &amp; Integrations | | Integrations | | Releases v1.0 |\n +----------------+ +----------------+ +----------------+ +----------------+ +----------------+ +----------------+\n</code></pre>"},{"location":"concepts/architecture/","title":"System Architecture","text":"<p>CodeGraphContext (CGC) is structured as a multi-tier code intelligence pipeline. It acts as the bridge between source code parsers, local/remote graph databases, and client developer tools or AI agents.</p>"},{"location":"concepts/architecture/#high-level-architectural-layout","title":"High-Level Architectural Layout","text":"<p>CGC consists of three primary layers: Ingestion, Persistence, and Interface.</p> <pre><code>graph TD\n subgraph Ingestion Layer\n src[Raw Source Files] --&gt; parsers[Tree-sitter / SCIP Parsers]\n parsers --&gt; builder[Graph Builder &amp; Entity Resolver]\n end\n\n subgraph Persistence Layer\n builder --&gt; db_api[Database Abstraction API]\n db_api --&gt; embedded[Embedded: KuzuDB / LadybugDB / FalkorDB Lite]\n db_api --&gt; server[Server: Neo4j / FalkorDB Remote]\n end\n\n subgraph Interface Layer\n embedded --&gt; cli[CGC CLI Client]\n server --&gt; cli\n embedded --&gt; mcp[MCP Server Gateway]\n server --&gt; mcp\n mcp --&gt; agents[AI Assistant Clients: Cursor, Claude, VS Code]\n end</code></pre>"},{"location":"concepts/architecture/#1-the-ingestion-layer","title":"1. The Ingestion Layer","text":"<p>The Ingestion Layer is responsible for reading raw codebase directories, parsing code tokens, and constructing the structural property graph.</p> <ul> <li>File Discovery &amp; Filtering: Scans the directory tree. Respects standard <code>.gitignore</code> settings and custom <code>.cgcignore</code> configurations.</li> <li>Polyglot Parsers: Utilizes Tree-sitter libraries to generate Concrete Syntax Trees (CSTs) for supported programming languages (Python, Java, JavaScript, TypeScript, Go, C++, etc.).</li> <li>Symbol Linker (SCIP): Optionally processes SCIP index data to resolve cross-file references and imported dependency symbols.</li> <li>Reference Resolution: Resolves target call signatures. If <code>Function A</code> in <code>file_1.py</code> calls <code>Function B</code> in <code>file_2.py</code>, this linker creates a directed <code>CALLS</code> edge between their respective function nodes.</li> <li>Asynchronous Ingestion Workers: Processes large codebases concurrently via multi-threaded background workers managed by a internal job controller queue.</li> </ul>"},{"location":"concepts/architecture/#2-the-persistence-layer","title":"2. The Persistence Layer","text":"<p>The Persistence Layer abstracts database operations so that the engine can interface with multiple graph database systems using a single unified API.</p> <ul> <li>Database Abstraction API: A client layer exposing methods to write batch transactions (<code>write_nodes</code>, <code>write_edges</code>) and query graph relationships via Cypher or native bindings.</li> <li>Embedded Engines:</li> <li>FalkorDB Lite (Default on Unix): Embedded in-memory graph engine when <code>falkordblite</code> is installed (Linux/macOS, Python 3.12+).</li> <li>KuzuDB (Cross-platform fallback): In-process C++ graph engine used automatically on Windows or when FalkorDB Lite is unavailable.</li> <li>LadybugDB: SQL-based embedded graph engine designed for concurrent read/write transactions.</li> <li>Networked Server Engines:</li> <li>FalkorDB Remote: Remote client linking to FalkorDB instances.</li> <li>Neo4j: Enterprise-scale storage supporting distributed clustering and the Neo4j web browser console.</li> </ul>"},{"location":"concepts/architecture/#3-the-interface-layer","title":"3. The Interface Layer","text":"<p>The Interface Layer exposes the query engine to developer workflows and automated pipelines.</p> <ul> <li>CLI (<code>cgc</code>): Compiled Python script offering utilities to index directories, show statistics (<code>cgc stats</code>), execute analysis commands (<code>cgc analyze</code>), export/import context bundles, and verify backend readiness (<code>cgc doctor</code>).</li> <li>FastAPI HTTP Gateway: Exposes a REST API (<code>cgc api start</code>) to query the code graph over standard HTTP and serve the interactive React visualizer.</li> <li>Model Context Protocol (MCP) Server: Exposes 21 standard JSON-RPC tools for tool-calling agents.</li> </ul>"},{"location":"concepts/architecture/#core-data-flows","title":"Core Data Flows","text":""},{"location":"concepts/architecture/#a-repository-ingest-and-index-pipeline","title":"A. Repository Ingest and Index Pipeline","text":"<pre><code>sequenceDiagram\n participant User as Developer / Watcher\n participant CLI as CGC CLI / Watcher\n participant Ingest as Ingestion Pipeline\n participant DB as Graph Database\n\n User-&gt;&gt;CLI: cgc index [path]\n CLI-&gt;&gt;Ingest: Discover and Filter Files (.cgcignore)\n Ingest-&gt;&gt;Ingest: Parse Code Syntax Trees (Tree-sitter)\n Ingest-&gt;&gt;Ingest: Resolve Call Chains &amp; Inheritances\n Ingest-&gt;&gt;DB: Open Transaction\n Ingest-&gt;&gt;DB: Ingest Nodes (Files, Classes, Functions)\n Ingest-&gt;&gt;DB: Ingest Edges (CONTAINS, CALLS, IMPORTS)\n Ingest-&gt;&gt;DB: Commit Transaction\n DB--&gt;&gt;CLI: Return Ingestion Stats\n CLI--&gt;&gt;User: Display Success Summary</code></pre>"},{"location":"concepts/architecture/#b-mcp-query-pipeline","title":"B. MCP Query Pipeline","text":"<pre><code>sequenceDiagram\n participant LLM as AI Assistant (e.g., Claude)\n participant MCP as CGC MCP Server\n participant DB as Graph Database\n\n LLM-&gt;&gt;MCP: Call Tool: analyze_code_relationships(caller_chain)\n MCP-&gt;&gt;MCP: Translate parameters to Cypher Query\n MCP-&gt;&gt;DB: Execute Cypher Statement\n DB--&gt;&gt;MCP: Return Node &amp; Edge Data\n MCP-&gt;&gt;MCP: Format Result Snippets and Code Locations\n MCP--&gt;&gt;LLM: Return Tool Output payload</code></pre>"},{"location":"concepts/backends/","title":"Database Backends","text":"<p>CodeGraphContext (CGC) implements a pluggable database architecture. A common interface abstracts graph creation, updates, and traversals, allowing you to choose the database engine that best fits your scale, operating system, and visualization needs.</p>"},{"location":"concepts/backends/#backend-comparison-matrix","title":"Backend Comparison Matrix","text":"Feature / Metric FalkorDB (Lite, Default) KuzuDB LadybugDB FalkorDB (Remote) Neo4j Type Embedded In-Memory Embedded C++ Embedded SQL Remote Client Remote Client Operating System Linux / macOS Cross-Platform Cross-Platform Cross-Platform Cross-Platform Setup Overhead None None None Low (Docker) Medium (Docker/Aura) Read Latency Extremely Low Very Low Low Low Medium Max Capacity RAM-Bounded Large Medium Unlimited Unlimited Visualization CLI / Custom Web UI CLI / Custom Web UI CLI / Custom Web UI Neo4j Client (via Cypher) Neo4j Browser Console"},{"location":"concepts/backends/#1-kuzudb","title":"1. KuzuDB","text":"<p>KuzuDB is an in-process property graph database management system. It requires zero configuration and stores graph data inside a directory on your filesystem.</p> <ul> <li>OLAP Optimized: Designed for structured graph analysis and multi-hop queries.</li> <li>Cross-Platform: Natively supports Windows, Linux, and macOS on Python 3.10+.</li> <li>Data Directory: Graphs are saved inside the local <code>.codegraphcontext/</code> directory within the workspace.</li> </ul>"},{"location":"concepts/backends/#version-compatibility","title":"Version Compatibility","text":"Package Declared bounds (<code>pyproject.toml</code>) Versions <code>kuzu</code> Not declared <code>0.10.0</code>, <code>0.11.0</code>, <code>0.11.1</code>, <code>0.11.2</code>, <code>0.11.3</code>"},{"location":"concepts/backends/#setup","title":"Setup","text":"<p>Ensure the driver is installed: <pre><code>pip install kuzu\n</code></pre> Select KuzuDB as the default backend: <pre><code>cgc config db kuzudb\n</code></pre></p>"},{"location":"concepts/backends/#2-ladybugdb","title":"2. LadybugDB","text":"<p>LadybugDB is an embedded graph database engine implemented over relational SQL drivers.</p> <ul> <li>Concurreny Safe: Thread-safe operations suitable for concurrent watcher tasks.</li> <li>Relational Backend: Uses SQLite/relational queries underneath to simulate property graph operations.</li> </ul>"},{"location":"concepts/backends/#setup_1","title":"Setup","text":"<p>Select LadybugDB as the default backend: <pre><code>cgc config db ladybugdb\n</code></pre></p>"},{"location":"concepts/backends/#3-falkordb-lite-remote","title":"3. FalkorDB (Lite &amp; Remote)","text":"<p>FalkorDB is a low-latency, high-performance graph database. It supports two execution modes.</p>"},{"location":"concepts/backends/#falkordb-lite","title":"FalkorDB Lite","text":"<p>An embedded, in-memory graph engine that uses local shared memory drivers. - Limitation: Unix-only (Linux and macOS) and requires Python 3.12+. - Speed: Optimal traversal latency due to in-memory index layouts. - Content search: <code>cgc find content</code> uses portable substring matching on <code>source</code> and <code>docstring</code> fields (no Neo4j Lucene index required).</p>"},{"location":"concepts/backends/#falkordb-remote","title":"FalkorDB Remote","text":"<p>Connects to an external Redis-compatible FalkorDB server instance running in a Docker container or network host.</p>"},{"location":"concepts/backends/#version-compatibility_1","title":"Version Compatibility","text":"Package Declared bounds (<code>pyproject.toml</code>) Versions <code>falkordblite</code> <code>&gt;=0.7, &lt;0.10</code> <code>0.7.0</code>, <code>0.8.0</code>, <code>0.9.0</code> <code>falkordb</code> <code>&gt;=1.0, &lt;1.6</code> <code>1.5.0</code> <code>redis</code> <code>&gt;=5, &lt;6</code> <code>5.3.1</code>"},{"location":"concepts/backends/#setup_2","title":"Setup","text":"<p>Install the target drivers: <pre><code># For FalkorDB Lite\npip install falkordblite\n\n# For FalkorDB Remote\npip install falkordb\n</code></pre> Configure FalkorDB: <pre><code># Switch default database\ncgc config db falkordb\n\n# For Remote: configure connections\ncgc config set FALKORDB_HOST 127.0.0.1\ncgc config set FALKORDB_PORT 6379\n</code></pre></p>"},{"location":"concepts/backends/#4-neo4j-enterprise-shared","title":"4. Neo4j (Enterprise &amp; Shared)","text":"<p>Neo4j is the enterprise standard for graph database clustering, management, and analysis.</p> <ul> <li>Neo4j Browser: Connect to <code>http://localhost:7474</code> to visualize and interact with your code graph using Neo4j's query visualizer.</li> <li>Scale: Handles repositories containing millions of lines of code.</li> </ul>"},{"location":"concepts/backends/#version-compatibility_2","title":"Version Compatibility","text":"Package Declared bounds (<code>pyproject.toml</code>) Versions <code>neo4j</code> <code>&gt;=5.15.0</code> <code>6.2.0</code>"},{"location":"concepts/backends/#setup_3","title":"Setup","text":"<p>Start a Neo4j server (e.g., using Docker): <pre><code>docker run -d --name neo4j-cgc -p 7474:7474 -p 7687:7687 -e NEO4J_AUTH=neo4j/password neo4j:latest\n</code></pre> Install the Neo4j client library: <pre><code>pip install neo4j\n</code></pre> Configure CGC to connect to Neo4j: <pre><code>cgc config db neo4j\ncgc config set NEO4J_URI bolt://localhost:7687\ncgc config set NEO4J_USERNAME neo4j\ncgc config set NEO4J_PASSWORD password\n</code></pre></p> <p>Or run the interactive wizard: <code>cgc neo4j setup</code>.</p>"},{"location":"concepts/backends/#5-nornic-db","title":"5. Nornic DB","text":"<p>Nornic is a Neo4j-compatible embedded graph driver. Configure it when you want Bolt/Cypher semantics without a standalone Neo4j server.</p> <pre><code>cgc config db nornic\ncgc config set NORNIC_URI bolt://localhost:7687\ncgc config set NORNIC_USERNAME nornic\ncgc config set NORNIC_PASSWORD &lt;password&gt;\n</code></pre> <p>Connection keys mirror the Neo4j section in Configuration Reference.</p>"},{"location":"concepts/backends/#backend-selection-logic","title":"Backend Selection Logic","text":"<p>When executing commands, CGC automatically resolves the active database connection using the following precedence:</p> <ol> <li>CLI Flag Override: Explicitly set using <code>--database</code> or <code>-db</code> (e.g., <code>cgc index --database neo4j</code>).</li> <li>Environment Variable: Resolves via <code>CGC_RUNTIME_DB_TYPE</code> settings.</li> <li>Global Config File: Reads the value set via <code>cgc config db</code>.</li> <li>Fallback Auto-Detection:</li> <li>If <code>FALKORDB_HOST</code> env is present, connects to FalkorDB Remote.</li> <li>On Unix: Tries to initialize FalkorDB Lite -&gt; KuzuDB -&gt; Neo4j.</li> <li>On Windows: Tries to initialize KuzuDB -&gt; Neo4j.</li> </ol>"},{"location":"concepts/graph-model/","title":"The Code Graph Model","text":"<p>CodeGraphContext models codebase structures as a directed, attributed Property Graph. By mapping files, modules, classes, and functions to distinct nodes, and their interactions to directed edges, the engine provides a semantic representation of your code.</p>"},{"location":"concepts/graph-model/#1-node-types-attributes","title":"1. Node Types &amp; Attributes","text":"<p>Nodes represent physical files or structural syntax declarations. Each node has a set of attribute properties.</p>"},{"location":"concepts/graph-model/#structural-code-nodes","title":"Structural Code Nodes","text":""},{"location":"concepts/graph-model/#repository","title":"<code>Repository</code>","text":"<p>The root node representing the indexed codebase workspace. - <code>path</code>: The absolute file path to the repository directory. - <code>name</code>: The directory name of the repository.</p>"},{"location":"concepts/graph-model/#file","title":"<code>File</code>","text":"<p>Represents a source code file on disk. - <code>path</code>: The path relative to the repository root. - <code>language</code>: The resolved language parser type (e.g., <code>python</code>, <code>typescript</code>, <code>java</code>). - <code>hash</code>: SHA-256 hash of the file contents for tracking changes.</p>"},{"location":"concepts/graph-model/#module","title":"<code>Module</code>","text":"<p>A namespace or package boundary (e.g., a Python module, Java package, Go package). - <code>name</code>: The full qualified import path of the module.</p>"},{"location":"concepts/graph-model/#class","title":"<code>Class</code>","text":"<p>Object-oriented class declarations. - <code>name</code>: The class identifier name. - <code>path</code>: The relative file path containing the class. - <code>start_line</code> / <code>end_line</code>: The line coordinates in the source file.</p>"},{"location":"concepts/graph-model/#function","title":"<code>Function</code>","text":"<p>Methods, functions, or subroutines. - <code>name</code>: The function identifier name. - <code>path</code>: The relative file path containing the definition. - <code>signature</code>: The full function parameters and return type signature (if declared). - <code>docstring</code>: Extracted comments and docstrings. - <code>complexity</code>: Computed cyclomatic complexity score. - <code>start_line</code> / <code>end_line</code>: Source file line coordinates.</p>"},{"location":"concepts/graph-model/#external-integration-framework-nodes","title":"External Integration &amp; Framework Nodes","text":""},{"location":"concepts/graph-model/#springbean-java-spring-framework","title":"<code>SpringBean</code> (Java Spring Framework)","text":"<p>Java classes decorated with Spring stereotype annotations (e.g., <code>@Component</code>, <code>@Service</code>, <code>@Repository</code>, <code>@Controller</code>). - <code>bean_name</code>: The resolved identifier of the bean. - <code>scope</code>: The scope of the bean lifecycle (singleton, prototype). - <code>stereotype</code>: The annotation label type.</p>"},{"location":"concepts/graph-model/#springendpoint-java-spring-rest","title":"<code>SpringEndpoint</code> (Java Spring REST)","text":"<p>HTTP REST controller mappings (e.g., <code>@GetMapping</code>, <code>@PostMapping</code>). - <code>path</code>: The mapped HTTP endpoint URI pattern. - <code>method</code>: The HTTP method (GET, POST, PUT, DELETE). - <code>controller_class</code>: The class containing the handler definition.</p>"},{"location":"concepts/graph-model/#dbtable-datasource-schemas","title":"<code>DbTable</code> (Datasource Schemas)","text":"<p>Database tables imported from SQL schemas. - <code>name</code>: Table identifier name. - <code>schema</code>: The parent database schema/catalog name.</p>"},{"location":"concepts/graph-model/#dbcolumn-datasource-schemas","title":"<code>DbColumn</code> (Datasource Schemas)","text":"<p>Columns inside a database table. - <code>name</code>: Column name. - <code>data_type</code>: SQL data type declaration. - <code>is_primary_key</code> / <code>is_foreign_key</code>: Boolean constraints.</p>"},{"location":"concepts/graph-model/#rediskeypattern-nosql-schemas","title":"<code>RedisKeyPattern</code> (NoSQL Schemas)","text":"<p>Patterns representing keys in Redis cache databases. - <code>pattern</code>: The key naming pattern (e.g., <code>user:{id}:profile</code>). - <code>data_type</code>: Redis data structure (string, hash, list, set).</p>"},{"location":"concepts/graph-model/#2-directed-relationship-edges","title":"2. Directed Relationship Edges","text":"<p>Edges represent structural nesting, import linkages, or execution calls.</p> Edge Type Source Node Target Node Semantics / Description <code>CONTAINS</code> <code>Repository</code> / <code>File</code> / <code>Class</code> <code>File</code> / <code>Class</code> / <code>Function</code> Models physical nesting and scope containment (e.g., File contains Function). <code>IMPORTS</code> <code>File</code> <code>Module</code> / <code>File</code> Models dependency import linkages (e.g., <code>import os</code> or <code>from models import User</code>). <code>CALLS</code> <code>Function</code> <code>Function</code> Models execution paths: the source function invokes the target function. <code>INHERITS</code> <code>Class</code> <code>Class</code> Models object inheritance hierarchy (superclass links). <code>IMPLEMENTS</code> <code>Class</code> <code>Class</code> Models implementation of interfaces or abstract classes. <code>MAPS_TO</code> <code>SpringEndpoint</code> <code>Function</code> Links a REST endpoint URI handler to its target controller method. <code>READS</code> <code>Function</code> <code>DbTable</code> / <code>DbColumn</code> / <code>RedisKeyPattern</code> Identifies that the function queries or fetches data from the datasource node. <code>WRITES</code> <code>Function</code> <code>DbTable</code> / <code>DbColumn</code> / <code>RedisKeyPattern</code> Identifies that the function inserts, updates, or deletes data in the datasource node."},{"location":"concepts/graph-model/#3-polyglot-schema-example","title":"3. Polyglot Schema Example","text":"<p>Below is a conceptual schema illustrating how a Java Spring Controller is parsed, linking REST requests down to database tables:</p> <pre><code>graph TD\n rep[Repository] --&gt;|CONTAINS| file[UserController.java]\n file --&gt;|CONTAINS| cls[UserController Class]\n cls --&gt;|CONTAINS| fn[getUserDetails Method]\n\n endpoint[SpringEndpoint: GET /users/profile] --&gt;|MAPS_TO| fn\n fn --&gt;|CALLS| repo_fn[UserRepository.findById Method]\n repo_fn --&gt;|READS| table[DbTable: users]\n table --&gt;|CONTAINS| col[DbColumn: user_id]</code></pre>"},{"location":"concepts/how-it-works/","title":"How Ingestion Works","text":"<p>This guide explains how CodeGraphContext (CGC) parses source files, maps structural relationships, updates indices incrementally, and serves queries.</p>"},{"location":"concepts/how-it-works/#the-ingest-pipeline-flow","title":"The Ingest Pipeline Flow","text":"<pre><code>graph TD\n A[Start: cgc index / watch] --&gt; B[File Discovery &amp; Hashing]\n B --&gt; C{Has File Hash Changed?}\n C --&gt;|No| D[Skip File Ingestion]\n C --&gt;|Yes| E[Execute Tree-sitter Parser]\n E --&gt; F[Extract AST Entities &amp; Declarations]\n F --&gt; G[Parse Imports &amp; Scope References]\n G --&gt; H[Resolve Symbols &amp; Direct Call Targets]\n H --&gt; I[Open Database Transaction]\n I --&gt; J[Commit Graph Nodes &amp; Edges]\n J --&gt; K[Update local .codegraphcontext/ state]</code></pre>"},{"location":"concepts/how-it-works/#1-syntax-parsing-ast-extraction","title":"1. Syntax Parsing &amp; AST Extraction","text":"<p>CGC scans source code using AST parser engines:</p>"},{"location":"concepts/how-it-works/#tree-sitter-grammar-parsing","title":"Tree-sitter Grammar Parsing","text":"<p>By default, CGC uses Tree-sitter parsers. Tree-sitter generates concrete syntax trees (CSTs) for files: - CGC registers grammar definitions for 22 target programming languages. - Language-specific Tree-sitter query files (e.g., <code>queries/python/tags.scm</code>) scan the AST to isolate definitions: functions, method names, class structures, parameters, variables, and decorators. - It records source coordinates (start line, start column, end line, end column) and docstrings.</p>"},{"location":"concepts/how-it-works/#scip-ingestion-opt-in","title":"SCIP Ingestion (Opt-in)","text":"<p>For large or complex codebases, you can feed a pre-built SCIP (Sourcegraph Code Intelligence Protocol) index file into CGC: - SCIP provides highly accurate cross-module definition-to-reference mappings compiled by compiler front-ends. - CGC merges Tree-sitter structural declarations with SCIP symbol resolution definitions, which improves cross-file reference accuracy.</p>"},{"location":"concepts/how-it-works/#2-cross-file-reference-resolution","title":"2. Cross-File Reference Resolution","text":"<p>Once declarations are parsed into memory, the engine links dependencies and calls:</p> <ul> <li>Containment Linking: Generates <code>CONTAINS</code> relationships mapping a <code>File</code> to its child <code>Class</code> nodes, and <code>Class</code> nodes to their <code>Function</code> methods.</li> <li>Import Resolution: Resolves imports (e.g., <code>from app.models import User</code>) to connect file nodes to module namespaces.</li> <li>Call Targets Linker: When a function contains an invocation name, the resolver searches the symbol index to locate matching target function nodes. If a match is verified, a directed <code>CALLS</code> edge is committed.</li> <li>Inheritance Traversal: Resolves base class relationships, creating directed <code>INHERITS</code> or <code>IMPLEMENTS</code> edges between class nodes.</li> </ul>"},{"location":"concepts/how-it-works/#3-incremental-watching-synchronization","title":"3. Incremental Watching &amp; Synchronization","text":"<p>Re-parsing an entire codebase on every change is slow. CGC handles file writes incrementally:</p> <ul> <li>State File Tracking: CGC stores a database registry tracking every indexed file's path, modification timestamp, and SHA-256 content hash.</li> <li>Filesystem Watcher: The <code>cgc watch</code> command initializes a background watcher using the <code>watchdog</code> library.</li> <li>Incremental Updates:</li> <li>The watchdog detects a file modification event.</li> <li>The indexing scheduler recalculates the modified file's SHA-256 hash.</li> <li>If the hash differs, CGC opens a database write transaction.</li> <li>It removes the file's old node declarations and relationship edges.</li> <li>It parses the new file content, resolves its symbols, and commits the updated nodes and edges.</li> <li>The transaction is committed, ensuring the database remains in sync.</li> </ul>"},{"location":"concepts/how-it-works/#4-serving-queries-via-cypher","title":"4. Serving Queries via Cypher","text":"<p>CGC translates CLI requests and MCP tool invocations into Cypher Queries that run against the active database.</p> <p>For instance, calling <code>cgc analyze callers calculate_total</code> translates into a Cypher query:</p> <pre><code>MATCH (caller:Function)-[:CALLS]-&gt;(callee:Function)\nWHERE callee.name = 'calculate_total'\nRETURN caller.name, caller.path, caller.start_line\n</code></pre> <p>By querying the database engine via Cypher, CGC traverses relationships in milliseconds, bypassing the need to search raw source code files in real-time.</p>"},{"location":"getting-started/installation/","title":"Ingesting &amp; Installing CodeGraphContext","text":"<p>CodeGraphContext (CGC) is packaged as a standard Python utility. The CLI and server components are installed using Python package managers.</p>"},{"location":"getting-started/installation/#1-cli-installation","title":"1. CLI Installation","text":""},{"location":"getting-started/installation/#method-a-execution-via-uvx-recommended","title":"Method A: Execution via <code>uvx</code> (Recommended)","text":"<p>If you use uv, you can run the CGC CLI on demand without installing it globally:</p> <pre><code>uvx codegraphcontext --help\n</code></pre>"},{"location":"getting-started/installation/#method-b-isolated-global-installation-via-pipx","title":"Method B: Isolated Global Installation via <code>pipx</code>","text":"<p>To install the CLI in an isolated Python environment and make it globally available:</p> <pre><code>pipx install codegraphcontext\n</code></pre>"},{"location":"getting-started/installation/#method-c-standard-package-installation-via-pip","title":"Method C: Standard Package Installation via <code>pip</code>","text":"<p>To install CGC in your active Python or virtual environment:</p> <pre><code>pip install codegraphcontext\n</code></pre>"},{"location":"getting-started/installation/#2-database-driver-setup","title":"2. Database Driver Setup","text":"<p>CGC requires Python driver bindings for your selected database backend. On Unix with Python 3.12+, FalkorDB Lite is the default when <code>falkordblite</code> is installed; on Windows (or when FalkorDB Lite is unavailable), CGC falls back to KuzuDB. See Important defaults.</p>"},{"location":"getting-started/installation/#installing-kuzudb-drivers","title":"Installing KuzuDB Drivers","text":"<p>KuzuDB is embedded and runs directly inside the Python process. <pre><code>pip install kuzu\n</code></pre></p>"},{"location":"getting-started/installation/#installing-falkordb-drivers-optional","title":"Installing FalkorDB Drivers (Optional)","text":"<p>If using the FalkorDB backend: - Embedded Lite (Unix and Python 3.12+ only): <pre><code>pip install falkordblite\n</code></pre> - Remote Server Client: <pre><code>pip install falkordb\n</code></pre></p>"},{"location":"getting-started/installation/#installing-neo4j-drivers-optional","title":"Installing Neo4j Drivers (Optional)","text":"<p>If connecting to a standalone Neo4j instance: <pre><code>pip install neo4j\n</code></pre></p>"},{"location":"getting-started/installation/#3-configuring-the-default-backend","title":"3. Configuring the Default Backend","text":"<p>Set your preferred default database backend in the global configuration:</p> <pre><code>cgc config db falkordb # FalkorDB Lite (default on Unix when falkordblite is installed)\ncgc config db kuzudb # KuzuDB (cross-platform fallback)\ncgc config db ladybugdb # LadybugDB\ncgc config db falkordb-remote # Remote FalkorDB server\ncgc config db neo4j # Neo4j\ncgc config db nornic # Nornic (Neo4j-compatible)\n</code></pre> <p>For remote databases (FalkorDB Remote, Neo4j), refer to the database connection properties in the Configuration Reference.</p>"},{"location":"getting-started/installation/#4-validating-the-installation","title":"4. Validating the Installation","text":"<p>Verify that the CLI and its database bindings are correctly loaded using the diagnostics tool:</p> <pre><code># Verify the installed CLI version\ncgc version\n\n# Run the system diagnostics check\ncgc doctor\n</code></pre> <p>The <code>doctor</code> command executes self-tests on the configuration, tests database drivers, and confirms directory permissions.</p>"},{"location":"getting-started/installation/#5-next-steps","title":"5. Next Steps","text":"<p>Once the CLI is verified, continue to index your project workspace.</p> <p>Proceed to Quickstart \u2192</p>"},{"location":"getting-started/mcp-setup/","title":"Model Context Protocol Setup","text":"<p>CodeGraphContext (CGC) implements the Model Context Protocol (MCP). This enables LLM-powered applications and IDE extensions to discover and invoke tools that fetch context directly from your code graph.</p>"},{"location":"getting-started/mcp-setup/#1-automated-setup-recommended","title":"1. Automated Setup (Recommended)","text":"<p>CGC includes an interactive wizard that detects supported IDEs and applications on your system and configures their MCP client settings automatically.</p> <p>Run the wizard from your terminal:</p> <pre><code>cgc mcp setup\n</code></pre> <p>The wizard will locate configuration files for Claude Desktop, Cursor, and other compatible environments, and request permission to add CodeGraphContext as a local tool provider.</p>"},{"location":"getting-started/mcp-setup/#2-manual-client-configuration","title":"2. Manual Client Configuration","text":"<p>If you prefer to configure your workspace manually, refer to the client configurations below.</p>"},{"location":"getting-started/mcp-setup/#claude-desktop","title":"Claude Desktop","text":"<p>To configure Claude Desktop to run the local CGC server, add a configuration entry to the <code>claude_desktop_config.json</code> file.</p>"},{"location":"getting-started/mcp-setup/#configuration-file-locations","title":"Configuration File Locations:","text":"<ul> <li>Linux: <code>~/.config/Claude/claude_desktop_config.json</code></li> <li>macOS: <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></li> <li>Windows: <code>%APPDATA%\\Claude\\claude_desktop_config.json</code></li> </ul>"},{"location":"getting-started/mcp-setup/#configuration-schema","title":"Configuration Schema:","text":"<p>Add the following key under the <code>mcpServers</code> object:</p> <pre><code>{\n \"mcpServers\": {\n \"codegraphcontext\": {\n \"command\": \"cgc\",\n \"args\": [\"mcp\", \"start\"]\n }\n }\n}\n</code></pre> <p>Note: If you are running CGC in an isolated virtual environment or using <code>uvx</code>, adjust the command accordingly (e.g., using <code>uvx codegraphcontext mcp start</code>).</p>"},{"location":"getting-started/mcp-setup/#cursor-ide","title":"Cursor IDE","text":"<p>Cursor supports local MCP servers via direct process execution:</p> <ol> <li>Open Cursor Settings (Preferences / Settings -&gt; Features -&gt; MCP).</li> <li>Click + Add New MCP Server.</li> <li>Fill in the fields:</li> <li>Name: <code>CodeGraphContext</code></li> <li>Type: <code>command</code></li> <li>Command: <code>cgc mcp start</code></li> <li>Click Save.</li> </ol>"},{"location":"getting-started/mcp-setup/#opencode","title":"OpenCode","text":"<p>OpenCode manages MCP in its own UI. Follow the vendor's guide at OpenCode MCP servers to register a stdio server.</p> <p>Use the following configuration details: - Type: <code>stdio</code> - Command: <code>cgc</code> - Arguments: <code>mcp start</code></p> <p>Note: Ensure your database credentials and configurations match what <code>cgc mcp setup</code> generated (usually in <code>~/.codegraphcontext/.env</code>).</p>"},{"location":"getting-started/mcp-setup/#vs-code-via-continue-extension","title":"VS Code (via Continue extension)","text":"<p>If you use VS Code with the Continue.dev plugin:</p> <ol> <li>Open your Continue configuration file (<code>~/.continue/config.json</code>).</li> <li>Add the server details inside the <code>contextProviders</code> or <code>mcp</code> settings array:</li> </ol> <pre><code>{\n \"mcp\": {\n \"codegraphcontext\": {\n \"command\": \"cgc\",\n \"args\": [\"mcp\", \"start\"]\n }\n }\n}\n</code></pre>"},{"location":"getting-started/mcp-setup/#3-verifying-tool-connectivity","title":"3. Verifying Tool Connectivity","text":"<p>After restarting your IDE or Claude Desktop app, verify that the 21 MCP tools are active. You should see commands like:</p> <ul> <li><code>find_code</code> (Keyword search across symbols and file contents)</li> <li><code>analyze_code_relationships</code> (Lookup callers, callees, and inheritance paths)</li> <li><code>execute_cypher_query</code> (Execute direct database Cypher statements)</li> </ul> <p>You can verify it by prompting the assistant:</p> <p>\"Analyze the call path between the <code>process_data</code> and <code>db_commit</code> functions in my current codebase.\"</p>"},{"location":"getting-started/mcp-setup/#4-connection-troubleshooting","title":"4. Connection Troubleshooting","text":"<p>If the tools do not load: 1. Command Resolution: Verify that the <code>cgc</code> command is present in your system's global <code>PATH</code>. If you installed via a virtual environment, use the absolute path to the executable (e.g., <code>/usr/local/bin/cgc</code> or <code>/home/user/.local/bin/cgc</code>). 2. Process Integrity: Test starting the server manually in your shell by running <code>cgc mcp start</code>. It should listen on standard input/output (stdin/stdout) for JSON-RPC messages and not exit immediately. 3. Database Selection: Ensure your default database is configured and has indexed data. Run <code>cgc doctor</code> to verify configuration.</p>"},{"location":"getting-started/prerequisites/","title":"System Prerequisites","text":"<p>CodeGraphContext (CGC) is designed as a client-server architecture. To ensure a successful installation, understand the primary roles and requirements of the environment.</p>"},{"location":"getting-started/prerequisites/#architecture-components","title":"Architecture Components","text":"<ol> <li>The Ingestion Engine: The core Python package responsible for scanning source directories, running Tree-sitter and SCIP syntax parsers, and linking references.</li> <li>The Graph Storage Layer: The database backend containing nodes and edges representing code entities and their interactions.</li> <li>The Interface Clients:<ul> <li>CLI (<code>cgc</code>): Terminal interface used for managing indices, running analytical searches, and system diagnostics.</li> <li>MCP Server: Gateway enabling Model Context Protocol communication for IDEs and AI assistants.</li> </ul> </li> </ol>"},{"location":"getting-started/prerequisites/#hardware-os-requirements","title":"Hardware &amp; OS Requirements","text":"Resource Minimum Requirement Notes Operating System Linux, macOS, or Windows Windows WSL is supported but native installation works via KuzuDB. Python Version Python 3.10 or higher Python 3.10+ is required for the core package and KuzuDB. Memory 4 GB RAM Large repositories benefit from 8 GB+ memory during initial scans."},{"location":"getting-started/prerequisites/#database-backend-selection","title":"Database Backend Selection","text":"<p>CGC supports multiple database engines. You only need to set up the engine that fits your requirements.</p> Database Backend Setup Type Target Platform Use Case FalkorDB Lite (Default) In-process (Embedded) Unix (Linux/macOS), Python 3.12+ Default when <code>falkordblite</code> is installed. In-memory, extremely low latency. KuzuDB In-process (Embedded) Cross-Platform (Linux/macOS/Windows) Automatic fallback on Windows or when FalkorDB Lite is unavailable. Python 3.10+. LadybugDB In-process (Embedded) Cross-Platform Alternative embedded engine; <code>pip install ladybug</code>. FalkorDB Remote Networked Server Cross-Platform Client Connects to a remote FalkorDB/Redis-compatible server. Neo4j Networked Server Cross-Platform Client Enterprise clustering, Neo4j Browser, AuraDB. Nornic DB Embedded / Bolt client Cross-Platform Neo4j-compatible driver without a full Neo4j deployment."},{"location":"getting-started/prerequisites/#development-environment-interfaces","title":"Development Environment Interfaces","text":"<p>To use CodeGraphContext inside your coding workflow, ensure you have an MCP-compliant workspace interface, such as:</p> <ul> <li>Cursor IDE (Native MCP Support)</li> <li>VS Code (with the Continue or similar MCP extension)</li> <li>Claude Desktop (Native local process or SSE support)</li> <li>Windsurf IDE / OpenCode</li> </ul>"},{"location":"getting-started/quickstart/","title":"Quickstart Guide","text":"<p>This guide describes how to index a local repository and run your first code structure analysis queries.</p>"},{"location":"getting-started/quickstart/#1-index-the-repository","title":"1. Index the Repository","text":"<p>Navigate to the root directory of the codebase you want to index. Run the <code>index</code> command to scan the codebase and populate the code graph.</p> <pre><code>cd /path/to/your/repository\ncgc index\n</code></pre> <p>CGC scans your files, respects your <code>.gitignore</code> and <code>.cgcignore</code> configurations, runs Tree-sitter parsers to extract code elements, and links relationships.</p>"},{"location":"getting-started/quickstart/#2-inspect-ingestion-statistics","title":"2. Inspect Ingestion Statistics","text":"<p>Verify the indexed code structure by viewing database statistics:</p> <pre><code>cgc stats\n</code></pre> <p>The command returns metrics showing: - Total number of files parsed - Count of code nodes (functions, classes, modules) - Count of resolved relationships (Containment, Invocations, Imports, Variables)</p>"},{"location":"getting-started/quickstart/#3-query-symbol-relationships","title":"3. Query Symbol Relationships","text":"<p>Query the ingested graph relationships from the terminal. For example, to identify all callers of a function named <code>handle_request</code>:</p> <pre><code>cgc analyze callers handle_request\n</code></pre> <p>To see what other functions <code>handle_request</code> calls:</p> <pre><code>cgc analyze calls handle_request\n</code></pre> <p>To find a call chain/path between two functions (e.g., from <code>main</code> to <code>save_record</code>):</p> <pre><code>cgc analyze chain main save_record\n</code></pre>"},{"location":"getting-started/quickstart/#4-enable-real-time-watchers","title":"4. Enable Real-Time Watchers","text":"<p>To keep your code graph updated as you write code, start a directory watcher in the background. The watcher monitors file writes and incrementally updates the graph database.</p> <pre><code>cgc watch\n</code></pre> <p>To stop a watcher, use <code>cgc unwatch &lt;path&gt;</code>.</p>"},{"location":"getting-started/quickstart/#next-steps","title":"Next Steps","text":"<ul> <li>MCP Server Setup: Connect CodeGraphContext to your AI assistant.</li> <li>Indexing Guide: Learn about ignore files and deep scans.</li> <li>CLI Reference: Full command reference manual.</li> </ul>"},{"location":"guides/bundles/","title":"Portable CGC Bundles &amp; Registries","text":"<p>CodeGraphContext (CGC) supports Portable Graph Bundles (<code>.cgc</code> files)\u2014serialized snapshots of an indexed codebase. Bundles allow teams to distribute pre-parsed code structures so that other developers or CI runners can load them without re-parsing the original source code.</p>"},{"location":"guides/bundles/#what-are-cgc-bundles","title":"\ud83c\udfaf What are .cgc Bundles?","text":"<p><code>.cgc</code> (CodeGraphContext Bundle) files are portable, pre-indexed graph snapshots that can be distributed and loaded instantly without re-indexing. Think of them as \"npm packages for code knowledge graphs.\"</p>"},{"location":"guides/bundles/#key-benefits","title":"Key Benefits","text":"<ul> <li>\u26a1 Instant Loading - Load in seconds instead of minutes/hours of indexing</li> <li>\ud83c\udfaf Pre-analyzed - All code relationships already computed</li> <li>\ud83d\udd0d Query Ready - Start using with AI assistants immediately</li> <li>\ud83d\udce6 Portable - Works across any CodeGraphContext installation</li> <li>\ud83c\udf10 Shareable - Distribute pre-indexed knowledge easily</li> </ul>"},{"location":"guides/bundles/#bundle-structure","title":"\ud83d\udce6 Bundle Structure","text":"<p>A <code>.cgc</code> file is a ZIP archive containing:</p> <pre><code>numpy.cgc\n\u251c\u2500\u2500 metadata.json # Repository and indexing metadata\n\u251c\u2500\u2500 schema.json # Graph schema definition\n\u251c\u2500\u2500 nodes.jsonl # All nodes (one JSON per line)\n\u251c\u2500\u2500 edges.jsonl # All relationships (one JSON per line)\n\u251c\u2500\u2500 stats.json # Graph statistics\n\u2514\u2500\u2500 README.md # Human-readable description\n</code></pre>"},{"location":"guides/bundles/#file-formats","title":"File Formats","text":""},{"location":"guides/bundles/#metadatajson","title":"metadata.json","text":"<pre><code>{\n \"cgc_version\": \"0.5.0\",\n \"exported_at\": \"2026-01-13T22:00:00\",\n \"repo\": \"numpy/numpy\",\n \"commit\": \"a1b2c3d4\",\n \"languages\": [\"python\", \"c\"],\n \"format_version\": \"1.0\"\n}\n</code></pre>"},{"location":"guides/bundles/#nodesjsonl-excerpt","title":"nodes.jsonl (excerpt)","text":"<pre><code>{\"_id\": \"4:abc123\", \"_labels\": [\"Function\"], \"name\": \"array\", \"path\": \"/numpy/core/array.py\", \"line_number\": 42}\n{\"_id\": \"4:def456\", \"_labels\": [\"Class\"], \"name\": \"ndarray\", \"path\": \"/numpy/core/multiarray.py\", \"line_number\": 100}\n</code></pre>"},{"location":"guides/bundles/#edgesjsonl-excerpt","title":"edges.jsonl (excerpt)","text":"<pre><code>{\"from\": \"4:abc123\", \"to\": \"4:def456\", \"type\": \"CALLS\", \"properties\": {}}\n{\"from\": \"4:xyz789\", \"to\": \"4:def456\", \"type\": \"INHERITS\", \"properties\": {}}\n</code></pre>"},{"location":"guides/bundles/#quick-start","title":"\ud83d\ude80 Quick Start","text":""},{"location":"guides/bundles/#creating-bundles","title":"Creating Bundles","text":"<pre><code># Export current indexed repository\ncgc bundle export my-project.cgc --repo /path/to/project\n\n# Export all indexed repositories\ncgc bundle export all-repos.cgc\n\n# Export without statistics (faster)\ncgc bundle export quick.cgc --repo /path/to/project --no-stats\n\n# Shortcut\ncgc export my-project.cgc --repo /path/to/project\n</code></pre>"},{"location":"guides/bundles/#loading-bundles","title":"Loading Bundles","text":"<pre><code># Load a bundle (adds to existing graph)\ncgc bundle import numpy.cgc\n\n# Load and clear existing data (interactive confirmation)\ncgc bundle import numpy.cgc --clear\n\n# Non-interactive / CI: skip confirmation when clearing\ncgc bundle import numpy.cgc --clear --yes\ncgc bundle load numpy --clear -y\n\n# Shortcut\ncgc load numpy.cgc\n</code></pre>"},{"location":"guides/bundles/#using-pre-indexed-bundles","title":"Using Pre-indexed Bundles","text":"<pre><code># Download from GitHub Releases\nwget https://github.com/CodeGraphContext/CodeGraphContext/releases/download/bundles-20260113/numpy-1.26.4-a1b2c3d.cgc\n\n# Load it\ncgc load numpy-1.26.4-a1b2c3d.cgc\n\n# Start querying immediately\ncgc find name linalg\ncgc analyze deps numpy.linalg\n</code></pre>"},{"location":"guides/bundles/#available-pre-indexed-bundles","title":"\ud83d\udcda Available Pre-indexed Bundles","text":"<p>We provide weekly-updated bundles for popular repositories:</p>"},{"location":"guides/bundles/#tier-1-python-core-libraries","title":"Tier 1 - Python Core Libraries","text":"Repository Description Size Download numpy Scientific computing ~50MB Latest pandas Data analysis ~80MB Latest fastapi Modern web framework ~15MB Latest requests HTTP library ~10MB Latest flask Web framework ~12MB Latest"},{"location":"guides/bundles/#coming-soon","title":"Coming Soon","text":"<ul> <li>scikit-learn - Machine learning</li> <li>django - Web framework</li> <li>pytorch - Deep learning (subset)</li> <li>kubernetes - Container orchestration (Go)</li> <li>redis - In-memory database</li> </ul>"},{"location":"guides/bundles/#advanced-usage","title":"\ud83d\udd27 Advanced Usage","text":""},{"location":"guides/bundles/#bundle-versioning","title":"Bundle Versioning","text":"<p>Bundles follow this naming convention: <pre><code>&lt;repo-name&gt;-&lt;version&gt;-&lt;commit&gt;.cgc\n</code></pre></p> <p>Examples: - <code>numpy-1.26.4-a1b2c3d.cgc</code> - <code>pandas-2.1.0-xyz789.cgc</code> - <code>fastapi-0.109.0-abc123.cgc</code></p>"},{"location":"guides/bundles/#combining-bundles","title":"Combining Bundles","text":"<pre><code># Load multiple bundles into the same graph\ncgc load numpy.cgc\ncgc load pandas.cgc\ncgc load scikit-learn.cgc\n\n# Now query across all three\ncgc find name fit --type function\n</code></pre>"},{"location":"guides/bundles/#exporting-specific-repositories","title":"Exporting Specific Repositories","text":"<pre><code># Index multiple repos\ncgc index /path/to/numpy\ncgc index /path/to/pandas\n\n# Export each separately\ncgc export numpy.cgc --repo /path/to/numpy\ncgc export pandas.cgc --repo /path/to/pandas\n\n# Or export everything\ncgc export all-my-projects.cgc\n</code></pre>"},{"location":"guides/bundles/#creating-your-own-bundle-registry","title":"\ud83c\udfd7\ufe0f Creating Your Own Bundle Registry","text":""},{"location":"guides/bundles/#1-index-your-repositories","title":"1. Index Your Repositories","text":"<pre><code># Clone and index\ngit clone https://github.com/your-org/your-repo\ncd your-repo\ncgc index .\n</code></pre>"},{"location":"guides/bundles/#2-export-to-bundle","title":"2. Export to Bundle","text":"<pre><code># Get commit info\nCOMMIT=$(git rev-parse --short HEAD)\nTAG=$(git describe --tags --abbrev=0 2&gt;/dev/null || echo \"main\")\n\n# Export with version info\ncgc export \"your-repo-${TAG}-${COMMIT}.cgc\" --repo .\n</code></pre>"},{"location":"guides/bundles/#3-distribute","title":"3. Distribute","text":""},{"location":"guides/bundles/#option-a-github-releases","title":"Option A: GitHub Releases","text":"<pre><code># Create a release\ngh release create bundles-$(date +%Y%m%d) \\\n your-repo-*.cgc \\\n --title \"Pre-indexed Bundles - $(date +%Y-%m-%d)\" \\\n --notes \"Pre-indexed code graphs for instant loading\"\n</code></pre>"},{"location":"guides/bundles/#option-b-object-storage-s3-r2-gcs","title":"Option B: Object Storage (S3, R2, GCS)","text":"<pre><code># Upload to S3\naws s3 cp your-repo-*.cgc s3://your-bucket/bundles/\n\n# Make public or use signed URLs\naws s3 presign s3://your-bucket/bundles/your-repo-*.cgc\n</code></pre>"},{"location":"guides/bundles/#option-c-hugging-face-datasets","title":"Option C: Hugging Face Datasets","text":"<pre><code># Install huggingface_hub\npip install huggingface_hub\n\n# Upload\nhuggingface-cli upload your-org/cgc-bundles your-repo-*.cgc\n</code></pre>"},{"location":"guides/bundles/#3-the-public-bundle-registry","title":"3. The Public Bundle Registry","text":"<p>CGC hosts a remote repository of pre-indexed graph bundles for popular libraries and frameworks, allowing developers to query third-party code structures.</p>"},{"location":"guides/bundles/#searching-the-registry","title":"Searching the Registry","text":"<p>Search for public graph packages matching a specific keyword (e.g., <code>flask</code>):</p> <pre><code>cgc registry search flask\n</code></pre>"},{"location":"guides/bundles/#loading-registry-bundles","title":"Loading Registry Bundles","text":"<p>To download and load a package from the registry directly into your local database:</p> <pre><code>cgc bundle load flask\n</code></pre> <p>If the package is not found locally, the engine contacts the remote registry API, downloads the matching version, and runs the import process automatically.</p>"},{"location":"guides/bundles/#registry-command-suite","title":"Registry Command Suite","text":"<ul> <li>List All Available Registry Packages: <pre><code>cgc registry list\n</code></pre></li> <li>Request On-Demand Generation: If a specific library is missing, submit a request for the registry build server to generate a bundle from a public GitHub repository URL: <pre><code>cgc registry request https://github.com/pallets/click --wait\n</code></pre></li> </ul>"},{"location":"guides/bundles/#bundle-inspection","title":"\ud83d\udd0d Bundle Inspection","text":""},{"location":"guides/bundles/#view-bundle-contents","title":"View Bundle Contents","text":"<pre><code># Extract and view\nunzip -l numpy.cgc\n\n# View metadata\nunzip -p numpy.cgc metadata.json | jq\n\n# View statistics\nunzip -p numpy.cgc stats.json | jq\n\n# Read README\nunzip -p numpy.cgc README.md\n</code></pre>"},{"location":"guides/bundles/#validate-bundle","title":"Validate Bundle","text":"<pre><code># Check bundle integrity\ncgc bundle validate numpy.cgc # (future feature)\n</code></pre>"},{"location":"guides/bundles/#use-cases","title":"\ud83c\udf93 Use Cases","text":""},{"location":"guides/bundles/#1-ai-assistant-context","title":"1. AI Assistant Context","text":"<pre><code># AI can now query structure instantly\n# \"Show me all functions that use numpy.linalg\"\n</code></pre>"},{"location":"guides/bundles/#2-code-analysis-pipelines","title":"2. Code Analysis Pipelines","text":"<pre><code># CI/CD: Load pre-indexed dependencies\ncgc load fastapi.cgc\ncgc load sqlalchemy.cgc\n\n# Analyze your code against them\ncgc index ./my-api\ncgc analyze deps my_api\n</code></pre>"},{"location":"guides/bundles/#3-educational-resources","title":"3. Educational Resources","text":"<pre><code># Students can explore famous codebases\ncgc load django.cgc\ncgc find name authenticate\ncgc analyze chain authenticate\n</code></pre>"},{"location":"guides/bundles/#4-research-documentation","title":"4. Research &amp; Documentation","text":"<pre><code># Researchers can analyze code evolution\ncgc load numpy-1.25.0.cgc\ncgc load numpy-1.26.0.cgc\n\n# Compare structures (future feature)\ncgc diff numpy-1.25.0.cgc numpy-1.26.0.cgc\n</code></pre>"},{"location":"guides/bundles/#security-considerations","title":"\ud83d\udd10 Security Considerations","text":""},{"location":"guides/bundles/#bundle-verification","title":"Bundle Verification","text":"<p>Always verify bundles from untrusted sources:</p> <pre><code># Check metadata\nunzip -p bundle.cgc metadata.json\n\n# Verify source repository\n# Ensure commit hash matches official repo\n</code></pre>"},{"location":"guides/bundles/#sandboxing","title":"Sandboxing","text":"<p>Bundles only contain graph data, not executable code. However: - Review metadata before loading - Use <code>--clear</code> cautiously (it deletes existing data) - Keep backups of your graph database</p>"},{"location":"guides/bundles/#secrets-in-bundles","title":"Secrets in Bundles","text":"<p>Bundles include node properties from the indexed source code, which may contain string literals and variable values such as API keys, tokens, passwords, and database connection strings that were hardcoded in the source.</p> <p>Before sharing a bundle:</p> <ol> <li>Enable <code>REDACT_SECRETS=true</code> in your CGC config before indexing to automatically redact likely secrets: <pre><code>cgc config set REDACT_SECRETS true\ncgc index /path/to/repo\ncgc bundle export my-project.cgc\n</code></pre></li> <li>Inspect the bundle contents (<code>unzip -p bundle.cgc nodes.jsonl</code>) for any remaining sensitive values.</li> <li>CGC logs a warning at index time when potential secrets are detected, listing the affected nodes and properties.</li> </ol>"},{"location":"guides/bundles/#troubleshooting","title":"\ud83d\udee0\ufe0f Troubleshooting","text":""},{"location":"guides/bundles/#bundle-import-fails","title":"Bundle Import Fails","text":"<pre><code># Check bundle integrity\nunzip -t bundle.cgc\n\n# Verify format version\nunzip -p bundle.cgc metadata.json | jq .cgc_version\n\n# Try with --clear flag\ncgc load bundle.cgc --clear\n</code></pre>"},{"location":"guides/bundles/#large-bundle-performance","title":"Large Bundle Performance","text":"<pre><code># For very large bundles, increase batch size\n# (future configuration option)\nexport CGC_IMPORT_BATCH_SIZE=5000\ncgc load large-bundle.cgc\n</code></pre>"},{"location":"guides/bundles/#version-mismatch","title":"Version Mismatch","text":"<pre><code># Check your CGC version\ncgc --version\n\n# Update if needed\npip install --upgrade codegraphcontext\n\n# Check bundle version\nunzip -p bundle.cgc metadata.json | jq .cgc_version\n</code></pre>"},{"location":"guides/bundles/#api-reference","title":"\ud83d\udcd6 API Reference","text":""},{"location":"guides/bundles/#python-api","title":"Python API","text":"<pre><code>from codegraphcontext.core.cgc_bundle import CGCBundle\nfrom codegraphcontext.core.database import DatabaseManager\n\n# Initialize\ndb_manager = DatabaseManager()\nbundle = CGCBundle(db_manager)\n\n# Export\nsuccess, message = bundle.export_to_bundle(\n output_path=Path(\"my-bundle.cgc\"),\n repo_path=Path(\"/path/to/repo\"),\n include_stats=True\n)\n\n# Import\nsuccess, message = bundle.import_from_bundle(\n bundle_path=Path(\"my-bundle.cgc\"),\n clear_existing=False\n)\n</code></pre>"},{"location":"guides/bundles/#roadmap","title":"\ud83d\uddfa\ufe0f Roadmap","text":""},{"location":"guides/bundles/#v020-bundle-registry","title":"v0.2.0 - Bundle Registry","text":"<ul> <li>[ ] Central bundle registry</li> <li>[ ] <code>cgc registry search</code> command</li> <li>[ ] Automatic download from registry</li> <li>[ ] Bundle versioning and updates</li> </ul>"},{"location":"guides/bundles/#v030-advanced-features","title":"v0.3.0 - Advanced Features","text":"<ul> <li>[ ] Delta bundles (incremental updates)</li> <li>[ ] Bundle compression options</li> <li>[ ] Encrypted bundles</li> <li>[ ] Bundle signing and verification</li> </ul>"},{"location":"guides/bundles/#v040-collaboration","title":"v0.4.0 - Collaboration","text":"<ul> <li>[ ] Bundle merging</li> <li>[ ] Conflict resolution</li> <li>[ ] Multi-repository bundles</li> <li>[ ] Bundle diff and comparison</li> </ul>"},{"location":"guides/bundles/#contributing","title":"\ud83e\udd1d Contributing","text":""},{"location":"guides/bundles/#creating-bundles-for-popular-repos","title":"Creating Bundles for Popular Repos","text":"<p>We welcome contributions of pre-indexed bundles! See CONTRIBUTING.md for guidelines.</p>"},{"location":"guides/bundles/#improving-bundle-format","title":"Improving Bundle Format","text":"<p>The bundle format is versioned and extensible. Propose improvements via GitHub issues.</p>"},{"location":"guides/bundles/#license","title":"\ud83d\udcc4 License","text":"<p>Bundle format specification: MIT License Pre-indexed bundles: Subject to source repository licenses</p>"},{"location":"guides/contexts/","title":"Configuration Contexts &amp; Workspaces","text":"<p>CodeGraphContext (CGC) uses a context resolution system to determine where graph database files are stored and resolved. This allows developers to isolate codebases, use named workspaces, or share a single global database.</p>"},{"location":"guides/contexts/#workspace-directory-structure","title":"Workspace Directory Structure","text":"<p>Below is the standard directory structure under global and local scopes:</p> <pre><code>~/.codegraphcontext/ &lt;-- Global configuration directory\n config.yaml &lt;-- Active context mode and registry\n .env &lt;-- Database credentials and tuning configurations\n global/\n .cgcignore &lt;-- Global ignore patterns\n db/\n falkordb/ &lt;-- Global-mode FalkorDB Lite storage (default on Unix)\n kuzudb/ &lt;-- Global-mode KuzuDB storage directory\n contexts/\n ProjectA/\n db/\n kuzudb/ &lt;-- Named-context KuzuDB storage directory\n .cgcignore &lt;-- Context-specific ignore patterns\n</code></pre>"},{"location":"guides/contexts/#context-resolution-precedence","title":"Context Resolution Precedence","text":"<p>When executing a CLI command (e.g., <code>cgc index</code>) or starting an MCP session, CGC resolves the target database location in this priority order:</p> <ol> <li>Context Override Flag: If <code>--context &lt;name&gt;</code> or <code>-c &lt;name&gt;</code> is provided, CGC routes all writes and queries to the specified named context.</li> <li>Local Repository Scope: If the current directory contains a <code>.codegraphcontext/</code> folder, CGC operates in per-repo mode.</li> <li>Global Config Setting: CGC reads the active mode (<code>global</code>, <code>per-repo</code>, or <code>named</code>) and default context name specified in <code>~/.codegraphcontext/config.yaml</code>.</li> <li>Default Fallback: On Linux/macOS with Python 3.12+, connects to FalkorDB Lite at <code>~/.codegraphcontext/global/db/falkordb/</code>; otherwise KuzuDB at <code>~/.codegraphcontext/global/db/kuzudb/</code>.</li> </ol>"},{"location":"guides/contexts/#context-modes","title":"Context Modes","text":""},{"location":"guides/contexts/#1-global-mode-default","title":"1. Global Mode (Default)","text":"<p>In Global Mode, all indexed repositories populate a single shared database.</p> <pre><code># Verify active mode settings\ncgc context list\n\n# Set mode to global\ncgc context mode global\n</code></pre> <p>When indexing multiple repositories, their nodes are ingested into the same graph structure, which enables cross-project relationship tracing:</p> <pre><code>cd ~/projects/service-api\ncgc index .\n\ncd ~/projects/service-gateway\ncgc index .\n\n# List all ingested repositories\ncgc list\n</code></pre>"},{"location":"guides/contexts/#2-per-repo-mode","title":"2. Per-Repo Mode","text":"<p>In Per-Repo Mode, each repository maintains its own local <code>.codegraphcontext/</code> directory (similar to how Git uses <code>.git/</code>).</p> <pre><code>cgc context mode per-repo\n</code></pre> <p>When indexing inside a project, a local database folder is created within the repository root:</p> <pre><code>cd ~/projects/service-api\ncgc index .\n# Creates: ~/projects/service-api/.codegraphcontext/db/kuzudb/\n</code></pre> <p>Graphs are completely isolated, and commands run within a repository only inspect the local database.</p> <p>When you first index in per-repo mode, CGC auto-creates <code>.codegraphcontext/</code> and seeds a local <code>config.yaml</code> from your global <code>DEFAULT_DATABASE</code>. Project-local <code>.codegraphcontext/.env</code> and <code>.env</code> files are loaded only in this mode (unless you set <code>CGC_LOAD_PROJECT_ENV=1</code>). In global or named mode, global <code>~/.codegraphcontext/.env</code> wins so cloned repos cannot override your credentials.</p>"},{"location":"guides/contexts/#3-named-context-mode","title":"3. Named Context Mode","text":"<p>Named contexts act as logical workspaces. You can assign a specific name (e.g., <code>ClientA</code>, <code>StagingGraph</code>) and associate multiple codebases with it.</p> <pre><code># Switch to named context mode\ncgc context mode named\n\n# Create a named context\ncgc context create ProjectA\n\n# Index codebases into the named context\ncgc index ~/projects/api --context ProjectA\ncgc index ~/projects/web --context ProjectA\n</code></pre> <p>Setting a default context name eliminates the need to pass the <code>--context</code> flag:</p> <pre><code>cgc context default ProjectA\n\n# Future commands use the default named context\ncgc list\ncgc stats\n</code></pre>"},{"location":"guides/contexts/#managing-named-contexts-via-cli","title":"Managing Named Contexts via CLI","text":""},{"location":"guides/contexts/#create-a-named-context","title":"Create a Named Context","text":"<p>Create a context and optionally specify its target database driver and storage path: <pre><code>cgc context create mobile-app --database kuzudb # Or use shorthand aliases: --db, -db, -d\ncgc context create mobile-app --db-path /mnt/fast/cgc\n</code></pre></p>"},{"location":"guides/contexts/#list-contexts","title":"List Contexts","text":"<p>Displays active modes, registered contexts, database backend configurations, and associated repository directories: <pre><code>cgc context list\n</code></pre></p>"},{"location":"guides/contexts/#delete-a-context","title":"Delete a Context","text":"<p>Deletes the named context from the active registry: <pre><code>cgc context delete mobile-app\n</code></pre> Note: Deleting a context removes its registration from <code>config.yaml</code>. The underlying database files on disk are preserved to prevent data loss. You can delete the files manually if needed.</p>"},{"location":"guides/contexts/#ingest-ignore-configurations-cgcignore","title":"Ingest Ignore Configurations (<code>.cgcignore</code>)","text":"<p>CGC filters files using <code>.cgcignore</code> config files. The location of the active ignore file depends on the context mode:</p> Mode Active <code>.cgcignore</code> Path Global <code>~/.codegraphcontext/global/.cgcignore</code> Per-Repo <code>&lt;repo_root&gt;/.codegraphcontext/.cgcignore</code> Named <code>~/.codegraphcontext/contexts/&lt;name&gt;/.cgcignore</code>"},{"location":"guides/contexts/#default-global-cgcignore-template","title":"Default Global <code>.cgcignore</code> Template","text":"<pre><code>node_modules/\nvenv/\n.venv/\ndist/\nbuild/\n__pycache__/\n*.pyc\n.git/\n.idea/\n.vscode/\n</code></pre>"},{"location":"guides/datasource-indexing/","title":"Ingesting Database &amp; Cache Schemas","text":"<p>CodeGraphContext (CGC) goes beyond parsing code syntax\u2014it allows developers to ingest database and cache schemas. By linking code functions to database columns or cache keys, CGC maps dependencies from the API layer down to the storage tables.</p>"},{"location":"guides/datasource-indexing/#1-supported-datasources","title":"1. Supported Datasources","text":"<p>CGC provides ingestion connectors for three primary database models:</p> <ol> <li>Aurora MySQL / Relational Schemas: Ingests tables, columns, primary/foreign keys, and SQL constraints.</li> <li>Apache Cassandra / Column-Family Schemas: Ingests keyspaces, column families (tables), columns, and cluster keys.</li> <li>Redis / NoSQL Cache Stores: Ingests logical key namespace patterns and cache structure types.</li> </ol>"},{"location":"guides/datasource-indexing/#2-ingesting-schemas-via-cli","title":"2. Ingesting Schemas via CLI","text":"<p>Use the <code>cgc datasource</code> command group to configure and ingest datasource metadata.</p>"},{"location":"guides/datasource-indexing/#a-ingesting-mysql-schemas","title":"A. Ingesting MySQL Schemas","text":"<p>Connect to a MySQL database to extract table metadata and column datatypes:</p> <pre><code>cgc datasource mysql --host 127.0.0.1 --port 3306 --user app_user --password secure_pass --database main_db\n</code></pre> <p>This populates the active context with <code>DbTable</code> and <code>DbColumn</code> nodes, linking tables to columns via <code>CONTAINS</code> edges.</p>"},{"location":"guides/datasource-indexing/#b-ingesting-cassandra-schemas","title":"B. Ingesting Cassandra Schemas","text":"<p>Connect to a Cassandra cluster to extract keyspace schemas:</p> <pre><code>cgc datasource cassandra --host 127.0.0.1 --port 9042 --keyspace production_keyspace\n</code></pre> <p>This populates the context with keyspace tables and columns.</p>"},{"location":"guides/datasource-indexing/#c-ingesting-redis-key-patterns","title":"C. Ingesting Redis Key Patterns","text":"<p>Analyze active Redis databases to extract key schemas:</p> <pre><code>cgc datasource redis --host 127.0.0.1 --port 6379 --db 0\n</code></pre> <p>This command runs key scans, resolves namespaces (e.g., <code>user:*:profile</code> or <code>session:*</code>), and populates <code>RedisKeyPattern</code> nodes.</p>"},{"location":"guides/datasource-indexing/#3-resolving-code-to-database-relationships","title":"3. Resolving Code-to-Database Relationships","text":"<p>After ingesting both your codebase (via <code>cgc index</code>) and your database schemas (via <code>cgc datasource</code>), CGC runs static query analysis.</p> <p>It parses SQL query strings and Redis command invocations inside your code functions (e.g., <code>SELECT user_id FROM users</code> or <code>redis.get(f\"user:{user_id}:profile\")</code>) and resolves target nodes.</p>"},{"location":"guides/datasource-indexing/#resulting-edges","title":"Resulting Edges:","text":"<ul> <li><code>READS</code>: Ingested when a function queries database tables, reads columns, or fetches Redis key patterns.</li> <li><code>WRITES</code>: Ingested when a function writes data to tables (INSERT, UPDATE, DELETE) or modifies cache keys.</li> </ul>"},{"location":"guides/datasource-indexing/#4-querying-datasource-relationships","title":"4. Querying Datasource Relationships","text":"<p>Once the unified graph is created, you can query relationships using Cypher:</p>"},{"location":"guides/datasource-indexing/#example-a-trace-functions-modifying-a-table","title":"Example A: Trace Functions Modifying a Table","text":"<pre><code>MATCH (fn:Function)-[:WRITES]-&gt;(table:DbTable {name: 'orders'})\nRETURN fn.name, fn.path\n</code></pre>"},{"location":"guides/datasource-indexing/#example-b-identify-functions-interfacing-with-cache-patterns","title":"Example B: Identify Functions Interfacing with Cache Patterns","text":"<pre><code>MATCH (fn:Function)-[:READS]-&gt;(cache:RedisKeyPattern)\nWHERE cache.pattern CONTAINS 'session'\nRETURN fn.name, cache.pattern\n</code></pre>"},{"location":"guides/indexing/","title":"Indexing Source Code","text":"<p>Indexing extracts syntactic structures and links semantic relationships within a codebase to populate the graph database. CodeGraphContext (CGC) supports multiple scan strategies.</p>"},{"location":"guides/indexing/#1-local-workspace-indexing","title":"1. Local Workspace Indexing","text":"<p>To index the repository directory you are currently working in, navigate to the folder and run:</p> <pre><code>cd /path/to/project\ncgc index\n</code></pre>"},{"location":"guides/indexing/#ingestion-scopes","title":"Ingestion Scopes","text":"<p>By default, the <code>index</code> command scans all supported source files in the current working directory. You can narrow the scope by specifying a target subdirectory or file:</p> <pre><code># Index only the core module folder\ncgc index ./src/core\n\n# Index a single file\ncgc index ./src/main.py\n</code></pre>"},{"location":"guides/indexing/#overwriting-the-index","title":"Overwriting the Index","text":"<p>CGC tracks modification timestamps and file hashes to perform incremental scans. To force a full re-index of all files, bypass the cache with the <code>--force</code> flag:</p> <pre><code>cgc index --force\n</code></pre>"},{"location":"guides/indexing/#2-ingesting-third-party-packages","title":"2. Ingesting Third-Party Packages","text":"<p>To trace references to external dependencies (e.g., standard library classes or package functions), you can manually add installed Python libraries to your active code graph.</p> <p>Use the <code>add-package</code> command:</p> <pre><code># Ingest requests library\ncgc add-package requests python\n</code></pre> <p>The command resolves the package's installation path on your system, parses its definitions, and appends the nodes to your active context.</p>"},{"location":"guides/indexing/#3-scip-and-cgcignore","title":"3. SCIP and <code>.cgcignore</code>","text":"<p>When <code>SCIP_INDEXER=true</code>, external SCIP tools run on eligible source files. SCIP ingestion respects <code>.cgcignore</code> the same way Tree-sitter indexing does\u2014ignored paths are not passed to SCIP indexers.</p> <p>C and C++ SCIP requires a <code>compile_commands.json</code> in the project (or under <code>build/</code> / <code>cmake-build-*/</code>). Without it, CGC logs a warning and falls back to Tree-sitter for those files.</p>"},{"location":"guides/indexing/#4-real-time-directory-watchers","title":"4. Real-Time Directory Watchers","text":"<p>For active development, run a filesystem watcher in the background to capture file writes and incrementally sync the graph.</p> <pre><code># Start watching the active workspace\ncgc watch\n</code></pre> <pre><code>sequenceDiagram\n participant User\n participant Watch as cgc watch\n participant FileSystem\n participant ParsingQueue\n\n User-&gt;&gt;Watch: Start watch command\n Watch-&gt;&gt;FileSystem: Monitor directory\n\n FileSystem--&gt;&gt;Watch: File changed\n Watch-&gt;&gt;ParsingQueue: Queue file for parsing\n\n FileSystem--&gt;&gt;Watch: Another change\n Watch-&gt;&gt;ParsingQueue: Queue updated file</code></pre> <ul> <li>Listing Watchers: View active file monitors with: <pre><code>cgc watching\n</code></pre></li> <li>Stopping Watchers: Terminate directory monitoring using: <pre><code>cgc unwatch /path/to/project\n</code></pre></li> </ul> <p>On startup, each watcher can reconcile the graph with disk: files present on disk but missing from the graph are indexed, and graph entries for deleted files are removed before live monitoring begins.</p> <p>This is off by default \u2014 pass <code>--sync-on-start</code> to enable it. Without it, changes made while the watcher was not running are not picked up for an already-indexed repository.</p>"},{"location":"guides/indexing/#5-ingest-filters-cgcignore","title":"5. Ingest Filters (<code>.cgcignore</code>)","text":"<p>To prevent compiling bloated indices or parsing build artifacts, define ignore rules in a <code>.cgcignore</code> file in the root of your repository or context directory.</p>"},{"location":"guides/indexing/#glob-pattern-rules","title":"Glob Pattern Rules:","text":"<ul> <li>Lines starting with <code>#</code> are treated as comments.</li> <li>Directories should terminate with a trailing slash <code>/</code>.</li> <li>Supports wildcards (<code>*</code>) and recursive matches (<code>**/</code>).</li> </ul>"},{"location":"guides/indexing/#typical-cgcignore-configuration","title":"Typical <code>.cgcignore</code> Configuration:","text":"<pre><code># Exclude build and compiled outputs\nbuild/\ndist/\n*.egg-info/\n__pycache__/\n*.pyc\n\n# Exclude dependency libraries\nnode_modules/\n.venv/\nvenv/\nenv/\n\n# Exclude IDE configurations\n.git/\n.vscode/\n.idea/\n.project\n</code></pre>"},{"location":"guides/onboarding-codebase/","title":"Developer Onboarding &amp; Code Tour","text":"<p>Welcome to the CodeGraphContext (CGC) developer portal. This guide details the structural layout of the repository to help new contributors navigate the codebase, understand the interactions between components, and locate files when debugging or extending features.</p>"},{"location":"guides/onboarding-codebase/#repository-directory-layout","title":"Repository Directory Layout","text":"<p>The root workspace contains the following directories:</p> <pre><code>CodeGraphContext/\n\u251c\u2500\u2500 src/ &lt;-- Core Python application source code\n\u2502 \u2514\u2500\u2500 codegraphcontext/ &lt;-- Primary package namespace\n\u251c\u2500\u2500 website/ &lt;-- React-based force-directed graph visualizer UI\n\u251c\u2500\u2500 docs/ &lt;-- MkDocs documentation source files and themes\n\u251c\u2500\u2500 tests/ &lt;-- Unit, integration, and parser test suites\n\u251c\u2500\u2500 scripts/ &lt;-- Maintainer scripts, build helpers, and language updates\n\u251c\u2500\u2500 k8s/ &lt;-- Kubernetes deployment descriptors and manifests\n\u2514\u2500\u2500 organizer/ &lt;-- Research drafts, roadmaps, and feature experiments\n</code></pre>"},{"location":"guides/onboarding-codebase/#codebase-component-tour","title":"Codebase Component Tour","text":""},{"location":"guides/onboarding-codebase/#1-the-core-engine-srccodegraphcontext","title":"1. The Core Engine (<code>src/codegraphcontext/</code>)","text":"<p>This directory houses the engine execution layers:</p> <ul> <li><code>cli/</code>: Contains the Typer-based command-line definition files. Subcommands like <code>cgc index</code>, <code>cgc watch</code>, and <code>cgc analyze</code> map their arguments here.</li> <li><code>core/</code>: Houses the database abstraction layers. Database files like <code>database_kuzu.py</code>, <code>database_ladybug.py</code>, <code>database_falkor.py</code>, and <code>database_neo4j.py</code> inherit from a unified database driver interface class.</li> <li><code>tools/languages/</code>: Standardizes language parsing classes. Contains Tree-sitter tag query files (e.g., <code>queries/python/tags.scm</code>) and logic to parse classes, functions, and inheritances.</li> <li><code>tools/handlers/</code>: Implements individual handler logics for each Model Context Protocol (MCP) tool. The main server file (<code>server.py</code>) delegates incoming JSON-RPC calls to these specialized handler modules.</li> <li><code>core/watcher.py</code>: Integrates the <code>watchdog</code> monitoring library to schedule incremental index re-scans.</li> <li><code>graph_builder.py</code>: Coordinates multi-threaded ingestion, links call references, and batches insertions to the active database backend.</li> </ul>"},{"location":"guides/onboarding-codebase/#2-the-interactive-visualizer-ui-website","title":"2. The Interactive Visualizer UI (<code>website/</code>)","text":"<p>A self-contained React project that runs the graphical visualization console.</p> <ul> <li><code>src/components/CodeGraphViewer.tsx</code>: Uses <code>react-force-graph</code> to render nodes and relationships in a 2D/3D interface.</li> <li><code>api/</code>: Connection layers to retrieve graph data from the FastAPI backend served by the <code>cgc api start</code> process.</li> </ul>"},{"location":"guides/onboarding-codebase/#3-verification-test-suite-tests","title":"3. Verification Test Suite (<code>tests/</code>)","text":"<p>The test suite ensures reliability across backends and language parsers:</p> <ul> <li><code>unit/</code>: Validates isolated logic blocks, such as specific regex matches, configuration expansions, or parser AST collections.</li> <li><code>integration/</code>: Verifies graph operations against actual database instances (KuzuDB, Neo4j, FalkorDB).</li> <li><code>fixtures/</code>: Minimal test codebases (e.g., mock Python classes or Javascript files) used by integration tests to check parser outputs.</li> </ul>"},{"location":"guides/onboarding-codebase/#4-enterprise-deployments-k8s","title":"4. Enterprise Deployments (<code>k8s/</code>)","text":"<p>Contains Kubernetes descriptors: - <code>deployment.yaml</code> &amp; <code>service.yaml</code>: Manifests to deploy the FastAPI gateway and MCP server in cluster environments. - <code>neo4j-deployment.yaml</code>: Persistent volume claims and stateful sets for Neo4j database containers.</p>"},{"location":"guides/onboarding-codebase/#entry-points-for-extension","title":"Entry Points for Extension","text":""},{"location":"guides/onboarding-codebase/#adding-support-for-a-new-language","title":"Adding Support for a New Language","text":"<ol> <li>Create a language module under <code>src/codegraphcontext/tools/languages/</code> inheriting from the base parser.</li> <li>Define AST query patterns in <code>queries/&lt;language&gt;/tags.scm</code>.</li> <li>Add the parser registration in <code>parser_factory.py</code>.</li> <li>Run language tests via <code>scripts/test_all_parsers.py</code>.</li> </ol>"},{"location":"guides/onboarding-codebase/#implementing-a-new-mcp-tool","title":"Implementing a New MCP Tool","text":"<ol> <li>Register the tool schema definition in <code>src/codegraphcontext/tool_definitions.py</code>.</li> <li>Add a matching tool handler module in <code>src/codegraphcontext/tools/handlers/</code>.</li> <li>Map the tool handler execution path inside <code>src/codegraphcontext/server.py</code>.</li> </ol>"},{"location":"guides/onboarding-codebase/#debugging-database-drivers","title":"Debugging Database Drivers","text":"<ul> <li>Database implementations are isolated in <code>src/codegraphcontext/core/</code>. Modify queries or connection parameters inside the respective driver wrapper file.</li> </ul>"},{"location":"guides/visualization/","title":"Interactive Graph Visualization","text":"<p>Visualizing your code graph helps identify complex call paths, cyclical dependencies, and architectural anomalies. CodeGraphContext includes a built-in React-based interactive force-directed graph visualizer.</p>"},{"location":"guides/visualization/#1-running-the-local-visualizer-server","title":"1. Running the Local Visualizer Server","text":"<p>Start the local visualization server using the <code>visualize</code> command:</p> <pre><code>cgc visualize\n</code></pre> <p>By default, this command: 1. Resolves the active database context. 2. Launches a FastAPI web server on port 8000. 3. Opens your default web browser to <code>http://localhost:8000</code>.</p>"},{"location":"guides/visualization/#custom-port-repo-overrides","title":"Custom Port &amp; Repo Overrides","text":"<p>Specify a custom port or target repository path when starting the server:</p> <pre><code># Run server on port 9000 for a specific repository\ncgc visualize --repo ~/projects/my-api --port 9000\n\n# Use a specific named context database\ncgc visualize --context StagingGraph\n</code></pre>"},{"location":"guides/visualization/#2-using-the-interactive-ui","title":"2. Using the Interactive UI","text":"<p>The browser interface serves a force-directed graph showing your codebase structures:</p> <ul> <li>Node Interactions: Click on any node (file, class, function) to view its code details, extracted signatures, cyclomatic complexity scores, and docstrings in the detail pane.</li> <li>Dynamic Search: Use the search filter to highlight specific symbols.</li> <li>Relationship Filters: Toggle visibility of relationship edges (e.g., hiding <code>IMPORTS</code> to focus exclusively on execution <code>CALLS</code> flow).</li> <li>Navigation Controls: Zoom, pan, and drag nodes to isolate call loops and modules.</li> </ul>"},{"location":"guides/visualization/#3-neo4j-browser-visualizations-neo4j-backend-only","title":"3. Neo4j Browser Visualizations (Neo4j Backend Only)","text":"<p>If you are using Neo4j as your active database backend, you can leverage the native Neo4j Browser Console for complex Cypher queries.</p> <ol> <li>Open your browser and navigate to the Neo4j Console (typically <code>http://localhost:7474</code>).</li> <li>Log in using your configured credentials.</li> <li>Execute a Cypher query to retrieve and render graph structures:</li> </ol> <pre><code>// Visualize all functions called by the \"process_payment\" function\nMATCH (f1:Function {name: 'process_payment'})-[r:CALLS]-&gt;(f2:Function)\nRETURN f1, r, f2\n</code></pre>"},{"location":"reference/api/","title":"HTTP API Reference","text":"<p>CodeGraphContext ships a CGC Gateway HTTP server for ChatGPT Actions, Claude connectors, and custom web frontends. It wraps the same MCP tool surface exposed by <code>cgc mcp start</code>.</p>"},{"location":"reference/api/#starting-the-server","title":"Starting the Server","text":"<pre><code>cgc api start\ncgc api start --host 127.0.0.1 --port 8080\ncgc api start --reload # development only\n</code></pre> <p>The server loads credentials from the same configuration chain as the CLI (<code>~/.codegraphcontext/.env</code>, context resolution, etc.).</p>"},{"location":"reference/api/#endpoints","title":"Endpoints","text":""},{"location":"reference/api/#health-status","title":"Health &amp; Status","text":"Method Path Description <code>GET</code> <code>/health</code> Liveness probe. Returns <code>{\"status\": \"ok\"}</code>. Suitable for load balancers and Kubernetes. <code>GET</code> <code>/</code> Simple HTML landing page with links to OpenAPI docs. <code>GET</code> <code>/api/v1/status</code> Database connectivity and active backend name."},{"location":"reference/api/#mcp-over-sse","title":"MCP-over-SSE","text":"Method Path Description <code>GET</code> <code>/api/v1/mcp/sse</code> Server-Sent Events stream for MCP clients. <code>POST</code> <code>/api/v1/mcp/messages</code> MCP message ingress for SSE transport."},{"location":"reference/api/#rest-tool-bridge","title":"REST Tool Bridge","text":"Method Path Description <code>GET</code> <code>/api/v1/tools</code> Lists registered MCP tools and schemas. <code>POST</code> <code>/api/v1/tools/call</code> Invokes a tool by name with JSON arguments. <code>POST</code> <code>/api/v1/index</code> Triggers repository indexing (background job). <code>POST</code> <code>/api/v1/query</code> Executes a read-only Cypher query. <code>GET</code> <code>/api/v1/repositories</code> Lists indexed repositories in the active context. <p>Interactive OpenAPI documentation is available at <code>/docs</code> while the server is running.</p>"},{"location":"reference/api/#example-health-check","title":"Example: Health Check","text":"<pre><code>curl -s http://localhost:8000/health\n# {\"status\":\"ok\"}\n</code></pre> <pre><code>curl -s http://localhost:8000/api/v1/status\n</code></pre>"},{"location":"reference/api/#relationship-to-mcp","title":"Relationship to MCP","text":"Interface Transport Typical use <code>cgc mcp start</code> stdio Cursor, Claude Desktop, VS Code <code>cgc api start</code> HTTP / SSE Web apps, ChatGPT Actions, remote agents <p>Both paths share the same graph database and tool implementations.</p>"},{"location":"reference/cli/","title":"CLI Command Reference","text":"<p>The <code>cgc</code> command-line interface is the entry point for indexing code, running graph queries, managing contexts, and administering database backends.</p> <p>Run <code>cgc --help</code> or <code>cgc help</code> for the live command tree on your installed version.</p>"},{"location":"reference/cli/#global-options","title":"Global Options","text":"<p>These flags apply to most subcommands:</p> Option Shorthand Description <code>--database</code> <code>--db</code>, <code>-db</code> Override the active backend for this invocation (<code>neo4j</code>, <code>falkordb</code>, <code>falkordb-remote</code>, <code>kuzudb</code>, <code>nornic</code>, <code>ladybugdb</code>). <code>--db-path</code> Override the on-disk storage directory for embedded engines. <code>--context</code> <code>-c</code> Target a named context workspace. <code>--visual</code> <code>--viz</code>, <code>-V</code> Open results in the interactive graph visualization UI. <code>--version</code> <code>-v</code> Print package version and exit. <code>--help</code> <code>-h</code> Show help and exit. <p>Use <code>cgc version</code> (or <code>cgc --version</code>) to print the installed release (currently 0.5.0).</p>"},{"location":"reference/cli/#core-index-lifecycle","title":"Core Index &amp; Lifecycle","text":"<p>The <code>clean</code>, <code>delete</code>, and <code>rm</code> commands are disabled by default because they remove data. Before using them, enable <code>ALLOW_DB_DELETION</code> as described in Destructive Operation Safety.</p> Command Usage Notes <code>index</code> <code>cgc index [PATH] [--force] [--summarize]</code> Shortcut: <code>cgc i</code>. Incremental by default; <code>--force</code> rebuilds from scratch; <code>--summarize</code> displays a summary after indexing. <code>clean</code> <code>cgc clean</code> Purges orphaned nodes and dangling relationships. <code>stats</code> <code>cgc stats</code> Repository and node counts for the active context. <code>delete</code> <code>cgc delete &lt;repo_path&gt;</code> Shortcut: <code>cgc rm</code>. Removes one indexed repository. <code>list</code> <code>cgc list</code> Shortcut: <code>cgc ls</code>. Lists indexed repositories. <code>add-package</code> <code>cgc add-package &lt;name&gt; &lt;language&gt;</code> Indexes an installed third-party package as a dependency graph."},{"location":"reference/cli/#search-find","title":"Search (<code>find</code>)","text":"<pre><code>cgc find &lt;subcommand&gt; [args] [options]\n</code></pre> Subcommand Description <code>find name &lt;symbol&gt;</code> Search by symbol name. Options: <code>--type function\\|class\\|file\\|module</code>, <code>--fuzzy</code> / <code>--no-fuzzy</code>. <code>find pattern &lt;regex&gt;</code> Regex search across indexed source. <code>find type &lt;node_type&gt;</code> List nodes of a given label (e.g. <code>Function</code>, <code>Class</code>). <code>find content &lt;text&gt;</code> Full-text / substring search in source and docstrings. Neo4j uses Lucene; embedded backends use portable substring matching. <code>find decorator &lt;name&gt;</code> Functions with a given decorator. <code>find argument &lt;name-or-type&gt;</code> Functions declaring a parameter with the given name or type. <code>find variable &lt;name&gt;</code> Variable references and assignments."},{"location":"reference/cli/#analysis-analyze","title":"Analysis (<code>analyze</code>)","text":"<pre><code>cgc analyze &lt;subcommand&gt; [args] [options]\n</code></pre> Subcommand Description <code>analyze callers &lt;function&gt;</code> Direct callers of a function. <code>analyze calls &lt;function&gt;</code> Direct callees of a function. <code>analyze chain &lt;source&gt; &lt;target&gt;</code> Shortest call path between two symbols. <code>analyze deps &lt;module&gt;</code> Module import dependencies. <code>analyze tree &lt;class&gt;</code> Class inheritance tree. <code>analyze complexity &lt;function&gt;</code> Cyclomatic complexity for one function. <code>analyze dead-code</code> Unreferenced functions/files (with optional filters). <code>analyze overrides &lt;function&gt;</code> Implementations of a function across classes. <code>analyze variable &lt;name&gt;</code> Variable scope and modification sites. <code>analyze kotlin-call-audit</code> Kotlin-specific call resolution audit."},{"location":"reference/cli/#querying-reports","title":"Querying &amp; Reports","text":""},{"location":"reference/cli/#query","title":"<code>query</code>","text":"<p>Execute a read-only Cypher query.</p> <pre><code>cgc query \"MATCH (f:Function) RETURN f.name LIMIT 10\"\ncgc query \"MATCH (n)-[r]-&gt;(m) RETURN n,r,m LIMIT 50\" --visual\n</code></pre> <p><code>cgc cypher</code> still works as a hidden alias but prints a deprecation warning\u2014prefer <code>cgc query</code>.</p>"},{"location":"reference/cli/#report","title":"<code>report</code>","text":"<p>Generate <code>CGC_REPORT.md</code> with god-node, complexity, and coupling metrics.</p> <pre><code>cgc report [--java]\n</code></pre>"},{"location":"reference/cli/#visualize","title":"<code>visualize</code>","text":"<p>Launch the React force-directed graph UI (shortcut: <code>cgc v</code>).</p> <pre><code>cgc visualize [--repo &lt;path&gt;] [--port 8000]\n</code></pre>"},{"location":"reference/cli/#context-workspaces-context","title":"Context Workspaces (<code>context</code>)","text":"<p>Manage isolation modes and named workspaces. See Configuration Contexts.</p> <pre><code>cgc context list\ncgc context mode &lt;global|per-repo|named&gt;\ncgc context create &lt;name&gt; [--database kuzudb] [--db-path /path]\ncgc context delete &lt;name&gt;\ncgc context default &lt;name&gt;\n</code></pre>"},{"location":"reference/cli/#configuration-config","title":"Configuration (<code>config</code>)","text":"<pre><code>cgc config show\ncgc config set &lt;KEY&gt; &lt;VALUE&gt;\ncgc config db &lt;backend&gt;\ncgc config reset\n</code></pre> <p>Valid backends: <code>kuzudb</code>, <code>ladybugdb</code>, <code>falkordb</code>, <code>falkordb-remote</code>, <code>neo4j</code>, <code>nornic</code>. See Configuration Reference.</p>"},{"location":"reference/cli/#mcp-neo4j-setup","title":"MCP &amp; Neo4j Setup","text":"<pre><code>cgc mcp setup # Interactive IDE wizard (shortcut: cgc m)\ncgc mcp start # Start stdio MCP server\ncgc mcp tools # List registered MCP tools\n\ncgc neo4j setup # Neo4j connection wizard (shortcut: cgc n)\n</code></pre>"},{"location":"reference/cli/#portable-bundles-bundle","title":"Portable Bundles (<code>bundle</code>)","text":"<pre><code>cgc bundle export &lt;output.cgc&gt; [--repo PATH] [--no-stats] [--context NAME]\ncgc bundle import &lt;file.cgc&gt; [--clear] [--yes|-y] [--context NAME]\ncgc bundle load &lt;name&gt; [--clear] [--yes|-y]\n\n# Shortcuts\ncgc export my-project.cgc --repo /path/to/project\ncgc load numpy\n</code></pre> <p>Use <code>--yes</code> / <code>-y</code> with <code>--clear</code> to skip the destructive-import confirmation (required in CI/non-interactive shells).</p>"},{"location":"reference/cli/#registry","title":"<code>registry</code>","text":"<p>Browse and download pre-indexed bundles.</p> <pre><code>cgc registry list [--verbose] [--unique]\ncgc registry search &lt;query&gt;\ncgc registry download &lt;name&gt; [--output DIR] [--load]\ncgc registry request &lt;github_url&gt;\n</code></pre>"},{"location":"reference/cli/#real-time-watchers","title":"Real-Time Watchers","text":"<pre><code>cgc watch [PATH] # Shortcut: cgc w\ncgc unwatch &lt;PATH&gt;\ncgc watching\n</code></pre> <p>With <code>--sync-on-start</code>, watchers reconcile the graph with the filesystem (add missing files, remove deleted paths) before monitoring changes. This is off by default.</p>"},{"location":"reference/cli/#git-hooks-hook","title":"Git Hooks (<code>hook</code>)","text":"<p>Keep the graph in sync on commit:</p> <pre><code>cgc hook install [PATH] [--force]\ncgc hook uninstall [PATH]\ncgc hook status [PATH]\n</code></pre>"},{"location":"reference/cli/#http-api-gateway-api","title":"HTTP API Gateway (<code>api</code>)","text":"<pre><code>cgc api start [--host 0.0.0.0] [--port 8000] [--reload]\n</code></pre> <p>Exposes REST endpoints under <code>/api/v1</code> and a liveness probe at <code>GET /health</code>. See HTTP API Reference.</p>"},{"location":"reference/cli/#external-datasources-datasource","title":"External Datasources (<code>datasource</code>)","text":"<pre><code>cgc datasource mysql\ncgc datasource cassandra\ncgc datasource redis\n</code></pre>"},{"location":"reference/cli/#scip-setup","title":"SCIP Setup","text":"<pre><code>cgc setup-scip\n</code></pre> <p>Installs or verifies external SCIP indexers when <code>SCIP_INDEXER=true</code>. C/C++ require <code>compile_commands.json</code>; see the README SCIP section.</p>"},{"location":"reference/cli/#system-diagnostics","title":"System Diagnostics","text":"<pre><code>cgc doctor\n</code></pre> <p>Checks configuration, database connectivity, Tree-sitter parsers, dependencies, and file permissions.</p>"},{"location":"reference/cli/#command-shortcuts","title":"Command Shortcuts","text":"Shortcut Full command <code>cgc i</code> <code>cgc index</code> <code>cgc ls</code> <code>cgc list</code> <code>cgc rm</code> <code>cgc delete</code> <code>cgc v</code> <code>cgc visualize</code> <code>cgc w</code> <code>cgc watch</code> <code>cgc m</code> <code>cgc mcp</code> <code>cgc n</code> <code>cgc neo4j</code> <code>cgc export</code> <code>cgc bundle export</code> <code>cgc load</code> <code>cgc bundle load</code>"},{"location":"reference/config/","title":"Configuration Reference","text":"<p>CodeGraphContext (CGC) is configured using environment variables, local configuration files, and the CLI.</p>"},{"location":"reference/config/#important-defaults-read-this-first","title":"Important defaults (read this first)","text":"<p>These three points are the most common sources of confusion in older docs and issue reports:</p>"},{"location":"reference/config/#default-database-backend","title":"Default database backend","text":"Platform What CGC uses by default Unix (Linux/macOS), Python 3.12+ FalkorDB Lite when <code>falkordblite</code> is installed (<code>DEFAULT_DATABASE=falkordb</code>) Windows, or FalkorDB Lite unavailable KuzuDB as the automatic fallback Any platform Override anytime with <code>cgc config db &lt;backend&gt;</code> <p>KuzuDB is not the universal default\u2014it is the cross-platform fallback when FalkorDB Lite cannot run.</p>"},{"location":"reference/config/#neo4j-username-key","title":"Neo4j username key","text":"<p>Use <code>NEO4J_USERNAME</code>, not <code>NEO4J_USER</code>. The latter is not a valid <code>cgc config set</code> key.</p> <pre><code>cgc config set NEO4J_USERNAME neo4j\n</code></pre>"},{"location":"reference/config/#project-local-env-files","title":"Project-local <code>.env</code> files","text":"<p>Repository <code>.codegraphcontext/.env</code> and <code>.env</code> files are loaded only in per-repo context mode (or when <code>CGC_LOAD_PROJECT_ENV=1</code>). In global or named mode, <code>~/.codegraphcontext/.env</code> wins so cloned repos cannot override your credentials. Set <code>CGC_IGNORE_PROJECT_ENV=1</code> to force-skip project env.</p> <p>See Project-Local Environment Files below for the full precedence table.</p>"},{"location":"reference/config/#the-cgc-config-cli-utility","title":"The <code>cgc config</code> CLI Utility","text":"<p>Use the <code>config</code> command group to inspect and modify settings from your terminal.</p>"},{"location":"reference/config/#1-inspect-effective-settings","title":"1. Inspect Effective Settings","text":"<p>Prints the merged configuration values (resolving defaults, global <code>.env</code>, and local workspaces):</p> <pre><code>cgc config show\n</code></pre>"},{"location":"reference/config/#2-set-configuration-values","title":"2. Set Configuration Values","text":"<p>Persists key-value settings to the global environment configuration file:</p> <pre><code># Set default database engine\ncgc config set DEFAULT_DATABASE falkordb\n\n# Change file size threshold (in MB)\ncgc config set MAX_FILE_SIZE_MB 25\n</code></pre> <p><code>DEFAULT_DATABASE</code> is the supported configuration key for selecting the database backend. <code>DEFAULT_BACKEND</code> is not a valid <code>cgc config</code> key.</p>"},{"location":"reference/config/#3-database-selection-shortcut","title":"3. Database Selection Shortcut","text":"<p>Quickly updates the <code>DEFAULT_DATABASE</code> key:</p> <pre><code>cgc config db falkordb\n</code></pre> <p>Valid database backend identifiers: <code>kuzudb</code>, <code>ladybugdb</code>, <code>falkordb</code> (Lite/embedded), <code>falkordb-remote</code>, <code>neo4j</code>, and <code>nornic</code>.</p>"},{"location":"reference/config/#4-reset-to-defaults","title":"4. Reset to Defaults","text":"<p>Restores all keys to factory configurations:</p> <pre><code>cgc config reset\n</code></pre>"},{"location":"reference/config/#configuration-variable-reference","title":"Configuration Variable Reference","text":""},{"location":"reference/config/#destructive-operation-safety","title":"Destructive Operation Safety","text":"Config Key Default Description <code>ALLOW_DB_DELETION</code> <code>false</code> Enables destructive database operations, including <code>cgc clean</code> and <code>cgc delete</code> (<code>cgc rm</code>). <p><code>cgc clean</code> and <code>cgc delete</code> exit with an error while this setting is <code>false</code>. Enable it explicitly before running either command:</p> <pre><code>cgc config set ALLOW_DB_DELETION true\n</code></pre> <p>After the operation, restore the safety guard:</p> <pre><code>cgc config set ALLOW_DB_DELETION false\n</code></pre>"},{"location":"reference/config/#core-engine-settings","title":"Core Engine Settings","text":"Config Key Default Description <code>DEFAULT_DATABASE</code> <code>falkordb</code> Active database engine. Options: <code>kuzudb</code>, <code>ladybugdb</code>, <code>falkordb</code>, <code>falkordb-remote</code>, <code>neo4j</code>. <code>ENABLE_AUTO_WATCH</code> <code>false</code> When <code>true</code>, indexing a project automatically initializes a directory watcher. <code>PARALLEL_WORKERS</code> <code>4</code> Max thread pool size for parsing code files concurrently. <code>CACHE_ENABLED</code> <code>true</code> Caches file hashes to support fast incremental scans."},{"location":"reference/config/#indexing-scope-configurations","title":"Indexing Scope Configurations","text":"Config Key Default Description <code>MAX_FILE_SIZE_MB</code> <code>10</code> Skips source files exceeding this size limit (in Megabytes). <code>IGNORE_TEST_FILES</code> <code>false</code> When <code>true</code>, skips files containing test keywords or directories like <code>tests/</code>. <code>IGNORE_HIDDEN_FILES</code> <code>true</code> When <code>true</code>, skips dotfiles and hidden folders (e.g., <code>.github/</code>). <code>INDEX_VARIABLES</code> <code>true</code> Extracts variable assignments into the graph. Set to <code>false</code> for smaller graph database sizes. <code>INDEX_SOURCE</code> <code>true</code> Stores raw source snippets in node attributes. Set to <code>false</code> for a lighter graph. <code>SKIP_EXTERNAL_RESOLUTION</code> <code>false</code> Skips looking up external Java dependencies."},{"location":"reference/config/#optional-scip-indexer-configurations","title":"Optional SCIP Indexer Configurations","text":"Config Key Default Description <code>SCIP_INDEXER</code> <code>false</code> When <code>true</code>, enables SCIP-based symbol resolution. <code>SCIP_LANGUAGES</code> <code>python,typescript,javascript,go,rust,java,dart,cpp,c,csharp</code> List of target languages to process via SCIP. <code>SCIP_LOCAL_INDEXER_TIMEOUT_SECONDS</code> <code>300</code> Timeout for the local SCIP indexer subprocess. Raise it for large repositories whose indexer runs longer than 5 minutes. Values <code>&lt;= 0</code> or non-numeric fall back to <code>300</code>."},{"location":"reference/config/#database-connection-configurations","title":"Database Connection Configurations","text":""},{"location":"reference/config/#neo4j-connection-properties","title":"Neo4j Connection Properties","text":"<p>Required when <code>DEFAULT_DATABASE</code> is set to <code>neo4j</code>.</p> Config Key Default Description <code>NEO4J_URI</code> <code>bolt://localhost:7687</code> Server connection URI. <code>NEO4J_USERNAME</code> <code>neo4j</code> Database user name. <code>NEO4J_PASSWORD</code> None Database connection password. <code>NEO4J_DATABASE</code> <code>neo4j</code> Logical database partition name."},{"location":"reference/config/#nornic-connection-properties","title":"Nornic Connection Properties","text":"<p>Required when <code>DEFAULT_DATABASE</code> is set to <code>nornic</code>.</p> Config Key Default Description <code>NORNIC_URI</code> <code>bolt://localhost:7687</code> Server connection URI (supports <code>nornic://</code> and <code>bolt://</code> schemes). <code>NORNIC_USERNAME</code> <code>nornic</code> Database user name. <code>NORNIC_PASSWORD</code> None Database connection password. <code>NORNIC_DATABASE</code> None Logical database partition name."},{"location":"reference/config/#falkordb-remote-connection-properties","title":"FalkorDB Remote Connection Properties","text":"<p>Required when <code>DEFAULT_DATABASE</code> is set to <code>falkordb-remote</code>.</p> Config Key Default Description <code>FALKORDB_HOST</code> <code>127.0.0.1</code> Remote host address. <code>FALKORDB_PORT</code> <code>6379</code> TCP Port. <code>FALKORDB_PASSWORD</code> None Authentication password. <code>FALKORDB_SSL</code> <code>false</code> Enables SSL/TLS connection socket. <code>FALKORDB_GRAPH_NAME</code> <code>codegraph</code> Target graph namespace."},{"location":"reference/config/#embedded-database-directories-kuzudb-ladybugdb-falkordb-lite","title":"Embedded Database Directories (KuzuDB / LadybugDB / FalkorDB Lite)","text":"<p>Local embedded database instances are stored on disk. Use the settings below to redirect them:</p> Config Key Default Description <code>KUZUDB_PATH</code> <code>~/.codegraphcontext/global/db/kuzudb/</code> Root storage directory for KuzuDB files. <code>LADYBUGDB_PATH</code> <code>~/.codegraphcontext/global/db/ladybugdb/</code> Root storage directory for LadybugDB files. <code>FALKORDB_PATH</code> <code>~/.codegraphcontext/global/db/falkordb/</code> Storage path for FalkorDB Lite database. <code>CGC_EMBEDDED_BUFFER_POOL_MB</code> <code>4096</code> Max buffer pool size in MiB for LadybugDB/Kuzu. Set <code>0</code> to use the library default (~80% of system RAM)."},{"location":"reference/config/#project-local-environment-files","title":"Project-Local Environment Files","text":"<p>Repository-level env files are not loaded in every mode:</p> File When it applies <code>~/.codegraphcontext/.env</code> Always (global defaults) <code>&lt;repo&gt;/.codegraphcontext/.env</code> Per-repo mode only (or when <code>CGC_LOAD_PROJECT_ENV=1</code>) <code>&lt;repo&gt;/.env</code> Per-repo mode only (searched up to 5 parent directories) <p>In global or named context mode, a checked-in <code>.codegraphcontext/.env</code> inside a clone does not override your user config\u2014this prevents accidental hijacking when indexing third-party repos.</p> <p>Override flags:</p> <ul> <li><code>CGC_IGNORE_PROJECT_ENV=1</code> \u2014 never load project-local env.</li> <li><code>CGC_LOAD_PROJECT_ENV=1</code> \u2014 always load project-local env (even outside per-repo mode).</li> </ul>"},{"location":"reference/config/#settings-precedence-levels","title":"Settings Precedence Levels","text":"<p>CGC resolves configuration keys in the following hierarchical priority (highest level overrides lower levels):</p> <ol> <li>CLI flag parameters \u2014 e.g. <code>cgc index --db neo4j</code>.</li> <li>Runtime environment variables \u2014 shell/CI exports and <code>CGC_RUNTIME_DB_TYPE</code>.</li> <li>Project-local env \u2014 <code>.codegraphcontext/.env</code> / <code>.env</code> (per-repo mode only; see above).</li> <li>User global settings \u2014 <code>~/.codegraphcontext/.env</code> (including values from <code>cgc config set</code>).</li> <li>System defaults \u2014 hardcoded fallbacks in the package.</li> </ol>"},{"location":"reference/mcp/","title":"MCP Tool Reference","text":"<p>When running the CodeGraphContext (CGC) MCP server, it registers a suite of 25 JSON-RPC tools that AI assistants can use to analyze and query the code graph.</p>"},{"location":"reference/mcp/#code-ingestion-system-control","title":"Code Ingestion &amp; System Control","text":""},{"location":"reference/mcp/#add_code_to_graph","title":"<code>add_code_to_graph</code>","text":"<p>Indexes a local directory or file into the active database context. - Parameters: - <code>path</code> (string, required): Absolute filesystem path. - <code>is_dependency</code> (boolean, optional): Marks the code as an external library.</p>"},{"location":"reference/mcp/#add_package_to_graph","title":"<code>add_package_to_graph</code>","text":"<p>Discovers, downloads (if needed), and indexes a third-party package. - Parameters: - <code>package_name</code> (string, required): Name of the package (e.g., <code>requests</code>, <code>express</code>). - <code>language</code> (string, required): Language syntax parser (<code>python</code>, <code>javascript</code>, <code>typescript</code>, <code>java</code>, <code>c</code>, <code>go</code>, <code>ruby</code>, <code>php</code>, <code>cpp</code>). - <code>is_dependency</code> (boolean, optional): Marks the package as an external library (default: true).</p>"},{"location":"reference/mcp/#watch_directory","title":"<code>watch_directory</code>","text":"<p>Launches a directory watcher for incremental updates. - Parameters: - <code>path</code> (string, required): Directory path to watch.</p>"},{"location":"reference/mcp/#unwatch_directory","title":"<code>unwatch_directory</code>","text":"<p>Stops file monitoring on a folder path. - Parameters: - <code>path</code> (string, required): Directory path.</p>"},{"location":"reference/mcp/#list_watched_paths","title":"<code>list_watched_paths</code>","text":"<p>Lists all directories currently monitored by watchers.</p>"},{"location":"reference/mcp/#delete_repository","title":"<code>delete_repository</code>","text":"<p>Removes a repository's code structures from the graph. - Parameters: - <code>repo_path</code> (string, required): Repository path.</p>"},{"location":"reference/mcp/#list_indexed_repositories","title":"<code>list_indexed_repositories</code>","text":"<p>Returns a list of all repositories stored in the active database.</p>"},{"location":"reference/mcp/#get_repository_stats","title":"<code>get_repository_stats</code>","text":"<p>Retrieves ingestion metrics (counts of files, functions, classes, modules). - Parameters: - <code>repo_path</code> (string, optional): Restricts stats to a specific repository.</p>"},{"location":"reference/mcp/#background-job-controller","title":"Background Job Controller","text":"<p>Some operations (like indexing large codebases) execute as background tasks. Use these tools to monitor task states:</p>"},{"location":"reference/mcp/#list_jobs","title":"<code>list_jobs</code>","text":"<p>Lists all background jobs and their execution states.</p>"},{"location":"reference/mcp/#check_job_status","title":"<code>check_job_status</code>","text":"<p>Queries progress and logs for a specific job. - Parameters: - <code>job_id</code> (string, required): Target job ID.</p>"},{"location":"reference/mcp/#code-search-relationship-analysis","title":"Code Search &amp; Relationship Analysis","text":""},{"location":"reference/mcp/#find_code","title":"<code>find_code</code>","text":"<p>Searches symbol definitions, file names, or source code for keyword matches. - Parameters: - <code>query</code> (string, required): Target keyword or pattern. - <code>fuzzy_search</code> (boolean, optional): Enables fuzzy matching. - <code>edit_distance</code> (number, optional): Levenshtein distance limit (0-2). - <code>repo_path</code> (string, optional): Restricts search scope.</p>"},{"location":"reference/mcp/#analyze_code_relationships","title":"<code>analyze_code_relationships</code>","text":"<p>The primary tool for traversing structural relationships in the graph. - Parameters: - <code>query_type</code> (string, required): The traversal type. Must be one of: - <code>find_callers</code>: Find immediate caller functions. - <code>find_callees</code>: Find immediate functions called by target. - <code>find_all_callers</code>: Deep search up the invocation chain. - <code>find_all_callees</code>: Deep search down the execution path. - <code>find_importers</code>: Find files importing the target symbol/module. - <code>who_modifies</code>: Trace variables or structures written to. - <code>class_hierarchy</code>: Resolves superclass and subclass trees. - <code>overrides</code>: Finds functions overriding parent methods. - <code>dead_code</code>: Scans context for unused subroutines. - <code>call_chain</code>: Traces invocation chains between source and destination. - <code>module_deps</code>: Identifies dependencies between modules. - <code>variable_scope</code>: Tracks variable bindings. - <code>find_complexity</code>: Returns cyclomatic complexity score. - <code>find_functions_by_argument</code>: Searches for functions declaring the target parameter name or type. - <code>find_functions_by_decorator</code>: Searches for functions decorated with target. - <code>target</code> (string, required): The identifier to analyze. For <code>find_functions_by_argument</code>, this may be a parameter name or type. - <code>context</code> (string, optional): Specific file path to resolve target namespace conflicts. - <code>repo_path</code> (string, optional): Restricts search scope.</p>"},{"location":"reference/mcp/#calculate_cyclomatic_complexity","title":"<code>calculate_cyclomatic_complexity</code>","text":"<p>Computes the complexity score of a function. - Parameters: - <code>function_name</code> (string, required): Function identifier. - <code>path</code> (string, optional): File path containing definition. - <code>repo_path</code> (string, optional): Restricts search scope.</p>"},{"location":"reference/mcp/#find_most_complex_functions","title":"<code>find_most_complex_functions</code>","text":"<p>Returns methods with the highest cyclomatic complexity scores. - Parameters: - <code>limit</code> (integer, optional): Maximum rows to return (default: 10). - <code>repo_path</code> (string, optional): Restricts search scope.</p>"},{"location":"reference/mcp/#find_dead_code","title":"<code>find_dead_code</code>","text":"<p>Scans for unreferenced code declarations. - Parameters: - <code>exclude_decorated_with</code> (array of strings, optional): Excludes functions carrying specified decorator annotations (e.g., <code>@app.route</code>, or <code>Composable</code> for Kotlin). Matching is by substring, so <code>Preview</code> matches <code>@Preview(showBackground = true)</code>. - <code>repo_path</code> (string, optional): Restricts search scope. - For Android codebases, <code>ANDROID_DECORATOR_PRESET</code> (<code>codegraphcontext.tools.code_finder.ANDROID_DECORATOR_PRESET</code>) is a preset tuple of Compose/JUnit/Hilt/Room/tooling annotation names to pass as <code>exclude_decorated_with</code>. Same substring matching applies.</p>"},{"location":"reference/mcp/#workspace-context-management","title":"Workspace Context Management","text":""},{"location":"reference/mcp/#discover_codegraph_contexts","title":"<code>discover_codegraph_contexts</code>","text":"<p>Scans subdirectories for existing <code>.codegraphcontext/</code> directories. - Parameters: - <code>path</code> (string, optional): Scan root directory. - <code>max_depth</code> (integer, optional): Folder depth limit (default: 1).</p>"},{"location":"reference/mcp/#switch_context","title":"<code>switch_context</code>","text":"<p>Reconnects the MCP session to a different graph database. - Parameters: - <code>context_path</code> (string, required): Path to the target repository root containing <code>.codegraphcontext/</code>. - <code>save</code> (boolean, optional): Persists configuration mapping (default: true).</p>"},{"location":"reference/mcp/#advanced-querying-reporting","title":"Advanced Querying &amp; Reporting","text":""},{"location":"reference/mcp/#execute_cypher_query","title":"<code>execute_cypher_query</code>","text":"<p>Executes raw Cypher queries directly against the graph database. - Parameters: - <code>cypher_query</code> (string, required): Cypher statement.</p>"},{"location":"reference/mcp/#visualize_graph_query","title":"<code>visualize_graph_query</code>","text":"<p>Generates a Neo4j visualization link. - Parameters: - <code>cypher_query</code> (string, required): Cypher statement to render.</p>"},{"location":"reference/mcp/#generate_report","title":"<code>generate_report</code>","text":"<p>Compiles a markdown quality report (<code>CGC_REPORT.md</code>). - Parameters: - <code>output_path</code> (string, optional): Output report path. - <code>include_java</code> (boolean, optional): Appends Spring endpoints and bean tables. - <code>god_node_limit</code> (integer, optional): Limit for high fan-in symbol rows. - <code>complexity_limit</code> (integer, optional): Limit for complex method rows. - <code>cross_module_limit</code> (integer, optional): Limit for module coupling rows.</p>"},{"location":"reference/mcp/#portability-registries","title":"Portability &amp; Registries","text":""},{"location":"reference/mcp/#load_bundle","title":"<code>load_bundle</code>","text":"<p>Imports a portable <code>.cgc</code> file, downloading it from the registry if needed. - Parameters: - <code>bundle_name</code> (string, required): Package name (e.g., <code>requests</code>) or file name. - <code>clear_existing</code> (boolean, optional): Purges active context before loading.</p>"},{"location":"reference/mcp/#search_registry_bundles","title":"<code>search_registry_bundles</code>","text":"<p>Searches the public CGC bundle server database. - Parameters: - <code>query</code> (string, optional): Name or description keywords. - <code>unique_only</code> (boolean, optional): Returns only the latest version of packages.</p>"},{"location":"reference/mcp/#frameworks-datasource-extensions","title":"Frameworks &amp; Datasource Extensions","text":""},{"location":"reference/mcp/#find_java_spring_endpoints","title":"<code>find_java_spring_endpoints</code>","text":"<p>Searches Spring controller REST mappings. - Parameters: - <code>http_method</code> (string, optional): Method filter (<code>GET</code>, <code>POST</code>, etc.). - <code>path_pattern</code> (string, optional): URL path substring. - <code>repo_path</code> (string, optional): Restricts search scope.</p>"},{"location":"reference/mcp/#find_java_spring_beans","title":"<code>find_java_spring_beans</code>","text":"<p>Returns registered Spring stereotype beans. - Parameters: - <code>stereotype</code> (string, optional): Stereotype filter (<code>SERVICE</code>, <code>REPOSITORY</code>, etc.). - <code>repo_path</code> (string, optional): Restricts search scope.</p>"},{"location":"reference/mcp/#find_datasource_nodes","title":"<code>find_datasource_nodes</code>","text":"<p>Returns ingested MySQL, Cassandra, or Redis schema nodes. - Parameters: - <code>kind</code> (string, optional): Datasource kind (<code>mysql</code>, <code>cassandra</code>, <code>redis</code>). - <code>name</code> (string, optional): Substring filter for names. - <code>include_columns</code> (boolean, optional): Appends table columns/key patterns (default: false).</p>"},{"location":"reference/troubleshooting/","title":"Troubleshooting Manual","text":"<p>This guide detail procedures for identifying, diagnosing, and resolving issues when setting up or executing CodeGraphContext.</p>"},{"location":"reference/troubleshooting/#1-engine-installation-compilation-issues","title":"1. Engine Installation &amp; Compilation Issues","text":""},{"location":"reference/troubleshooting/#kuzudb-installation-errors-c-compiler-required","title":"KuzuDB Installation Errors (C++ Compiler Required)","text":"<p>KuzuDB relies on a compiled C++ engine core. If <code>pip install kuzu</code> fails: - Reason: The pre-compiled wheel is not available for your system architecture/Python version, forcing a compile from source without build tools. - Resolution: - Linux: Install build essentials: <code>sudo apt-get install build-essential python3-dev</code> - macOS: Install developer CLI tools: <code>xcode-select --install</code> - Windows: Install Visual C++ Build Tools via Visual Studio Installer.</p>"},{"location":"reference/troubleshooting/#falkordb-lite-unix-dependencies","title":"FalkorDB Lite Unix Dependencies","text":"<p>FalkorDB Lite only runs on Linux/macOS and requires Python 3.12+. - Reason: Underlying shared libraries are not compiled for Windows or older Python interpreter versions. - Resolution: Switch the active database context backend to <code>kuzudb</code> which is fully cross-platform.</p>"},{"location":"reference/troubleshooting/#2-database-connection-failures","title":"2. Database Connection Failures","text":""},{"location":"reference/troubleshooting/#no-database-backend-available","title":"\"No database backend available\"","text":"<ul> <li>Reason: CGC is looking for KuzuDB, FalkorDB, or Neo4j, but the respective Python client packages are missing from the current virtual environment.</li> <li>Resolution: Verify package installations: <pre><code>pip install kuzu neo4j falkordb\n</code></pre></li> </ul>"},{"location":"reference/troubleshooting/#neo4j-connection-refused-auth-failures","title":"Neo4j Connection Refused / Auth Failures","text":"<ul> <li>Reason: Connection parameters in configuration do not match your running Neo4j Instance.</li> <li>Resolution: Run <code>cgc config show</code> to check host bindings and credentials. Verify that the Neo4j instance is up and accepting TCP connections (e.g., using <code>telnet localhost 7687</code> or via Docker logs).</li> </ul>"},{"location":"reference/troubleshooting/#3-mcp-server-daemon-failures","title":"3. MCP Server &amp; Daemon Failures","text":""},{"location":"reference/troubleshooting/#ide-assistant-fails-to-load-tools","title":"IDE Assistant Fails to Load Tools","text":"<p>If Claude Desktop or Cursor does not show CGC tools: - Step 1: Process Check: Test the server execution by running the launch command directly in your shell: <pre><code>cgc mcp start\n</code></pre> The server should wait for input on stdin/stdout. If it immediately crashes or exits, inspect the stack trace. - Step 2: Absolute Executable Paths: IDEs often run in isolated shell contexts that do not inherit your user shell's <code>PATH</code>. Replace the <code>cgc</code> command with the absolute path in your IDE configuration files: - Find the absolute path using: <code>which cgc</code> (Linux/macOS) or <code>where cgc</code> (Windows). - Update <code>command</code> in JSON (e.g., <code>/home/username/.local/bin/cgc</code>). - Step 3: Logs Inspection: Review the server log files. MCP server logs are written to: <code>~/.codegraphcontext/logs/mcp.log</code></p>"},{"location":"reference/troubleshooting/#4-indexing-filesystem-watcher-failures","title":"4. Indexing &amp; Filesystem Watcher Failures","text":""},{"location":"reference/troubleshooting/#indexing-is-slow-or-out-of-memory","title":"Indexing is Slow or Out of Memory","text":"<ul> <li>Reason: CGC is attempting to index massive build folders, dependencies, or compiled files (e.g., <code>.git/</code>, <code>node_modules/</code>, <code>venv/</code>).</li> <li>Resolution: Ensure a <code>.cgcignore</code> file is present in the repository root containing appropriate ignore rules (refer to the Indexing Guide).</li> </ul>"},{"location":"reference/troubleshooting/#directory-watcher-fails-to-update","title":"Directory Watcher Fails to Update","text":"<ul> <li>Reason: The watchdog monitor has run out of system file handles (common on Linux with large repositories).</li> <li>Resolution: Increase the max user watches value: <pre><code>echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf &amp;&amp; sudo sysctl -p\n</code></pre></li> </ul>"},{"location":"reference/troubleshooting/#5-http-api-gateway","title":"5. HTTP API Gateway","text":""},{"location":"reference/troubleshooting/#gateway-does-not-respond","title":"Gateway does not respond","text":"<ul> <li>Check: Confirm the process is running: <code>cgc api start --port 8000</code>.</li> <li>Health probe: <code>curl http://localhost:8000/health</code> should return <code>{\"status\":\"ok\"}</code>.</li> <li>Database errors on <code>/api/v1/status</code>: Run <code>cgc doctor</code>\u2014the gateway uses the same database configuration as the CLI.</li> </ul>"},{"location":"reference/troubleshooting/#6-system-health-check-doctor","title":"6. System Health Check (<code>doctor</code>)","text":"<p>To execute a comprehensive diagnostic test of the active environment, run:</p> <pre><code>cgc doctor\n</code></pre> <p>The diagnostics engine performs the following tests: 1. Python Version: Confirms interpreter meets version requirements. 2. Configuration Integrity: Checks for syntax errors in <code>config.yaml</code>. 3. Database Driver Availability: Checks imports for Kuzu, FalkorDB, and Neo4j. 4. Active Connection Health: Attempts connection transactions to the configured database. 5. Permissions Audit: Verifies write capability to target log and database storage directories.</p>"}]}