rpi-codegraph

A Rust rpi plugin that exposes the upstream CodeGraph index through focused native tools. Every call (including codegraph_status) first runs codegraph init <project> if .codegraph/ is absent, then runs codegraph sync <project>. These steps can scan the workspace and write the project index. It then starts codegraph serve --mcp --path <project> and proxies a query to the local index; successful response text is bounded.

Requirements

Install the upstream CLI (available on PATH) and select an accessible project directory. A previously initialized project is not required:

npm install -g @colbymchenry/codegraph

The plugin automatically initializes and synchronizes the index on each call. Do not use these tools when writing index files is not permitted; use direct read, grep or find instead.

On Windows the plugin discovers codegraph through PowerShell, so npm and Scoop installations do not need a hardcoded path.

Tools

The plugin registers:

• codegraph_search — symbol search, locations only
• codegraph_node — one symbol or one indexed source file
• codegraph_callers / codegraph_callees — call relationships
• codegraph_impact — bounded dependency impact
• codegraph_explore — relevant source grouped by file
• codegraph_files — indexed file tree with filters
• codegraph_status — index health and pending state after init/sync; not a read-only view of pre-sync state

Parameters and result boundaries

Every tool accepts an optional absolute projectPath pointing to an accessible directory; omitted or blank uses the process current working directory. The schema accepts extra host metadata such as __rpi. Optional fields remain optional; the plugin forwards parameters without injecting schema defaults or clamping numeric values. Actual resolution, normalization, caps and support for optional selectors depend on the installed upstream CodeGraph version.

For node file mode, omit symbol and provide a file path or basename. Source is line-numbered; offset is a 1-based starting line (omitted: beginning), limit requests a maximum line count (the locally inspected upstream defaults to 2,000 lines, with a separate character budget; 2,000 is not a hard line cap). symbolsOnly=true requests an outline/dependents rather than source. In symbol mode includeCode=true requests source; containers may return member outlines, and line selects a definition, not a source read offset. Older upstream versions may not support file mode or definition selectors: use direct reads rather than assuming those parameters were honored.

Successful response text is truncated at a Unicode-safe boundary to at most 25,000 characters plus a truncation marker, possibly ending at an earlier newline. This bounds returned context, not total index work or process memory. The subsequent MCP session (handshake and query together) has a 20-second response deadline. CLI discovery, automatic init/sync and process startup are outside that deadline; init/sync are blocking operations without that timeout or cancellation checks. Do not describe the whole call as having a 20-second limit. The MCP child is killed/waited after the session operation.

Indexed file listings are not complete filesystem inventories. Relationships are best-effort static results, not exhaustive runtime paths, a compiler check or proof of impact completeness. Sync cannot prevent concurrent edits or unsupported-language gaps. If results are stale, empty, ambiguous, truncated, or the CLI/index is unavailable, narrow queries or verify using read, grep and find; do not repeatedly retry an unavailable index. For truncated node file source, resume with an explicit later offset and smaller limit.

Metadata regression tests

Unit tests inspect the actual tool_specs() used by registration, parse every schema as JSON, and check object/property shape, required versus optional fields, host metadata compatibility, default hints, enums and concise shared CLI/index-write/truncation/fallback guidance. Detailed timeout boundaries stay in this README rather than being repeated in every tool description. They do not invoke CodeGraph or change index behavior.