Documentation
¶
Overview ¶
Package codegraph integrates the CodeGraph code-intelligence engine (https://github.com/colbymchenry/codegraph) as a built-in MCP server. CodeGraph indexes a project into a local symbol and call graph (tree-sitter + SQLite, FTS5) and serves it over stdio MCP, giving the agent symbol search, caller / callee, and change-impact tools without the per-language setup an LSP fleet would need.
CodeGraph is fetched on first use into a per-version cache (see Install) rather than shipped in the fairpeer binary, which keeps installs small. Resolve finds the cached launcher; an explicit config path, a system-installed `codegraph` on PATH, and a bundle placed beside the executable are also honored. boot injects the resolved launcher as one more stdio plugin, pinned to the project root via plugin.Spec.Dir (CodeGraph detects the project from its working directory).
Index ¶
- Constants
- func CacheDir() string
- func EnsureInit(ctx context.Context, bin, root string) error
- func IndexableRoot(root string) bool
- func Initialized(root string) bool
- func Install(ctx context.Context, log func(string)) (string, error)
- func InstallWithClient(ctx context.Context, client *http.Client, log func(string)) (string, error)
- func ReadOnlyToolNames() map[string]bool
- func Resolve(override string) (string, bool)
- func SetDownloadBase(url string)
Constants ¶
const BundleDirName = "codegraph"
BundleDirName is the optional directory, beside the fairpeer executable, where an operator can place an unpacked CodeGraph bundle for offline use. Its launcher lives at <BundleDirName>/bin/codegraph, with the bundled node runtime and lib/ beside it; the launcher resolves those relative to itself, so the bundle is relocatable.
const SteerText = `` /* 762-byte string literal not displayed */
SteerText is injected into the system prompt when CodeGraph tools are available, so the model knows to prefer them for symbol-level questions.
const ( // Version is the pinned CodeGraph release fetched on first use. Keep in sync // with CODEGRAPH_VERSION in the Makefile and .github/workflows. Version = "v1.0.0" )
Variables ¶
This section is empty.
Functions ¶
func CacheDir ¶
func CacheDir() string
CacheDir is where the CodeGraph bundle is unpacked on first use: <user cache>/fairpeer/codegraph/<Version>. Versioned so a bump installs cleanly beside the old one. FAIRPEER_CACHE_DIR overrides the base (relocate the cache, or isolate it in tests). Empty when no cache/config dir resolves.
func EnsureInit ¶
EnsureInit initialises CodeGraph for root when it has not been already, by running a bare `codegraph init` (no -i). That only creates the .codegraph/ structure — fast and independent of repo size (~100ms) — because the actual indexing is done by `serve --mcp`'s daemon in the background once connected: the MCP handshake returns in a few hundred ms and symbols fill in shortly after, with CodeGraph flagging partial results as stale meanwhile. So startup never blocks on indexing, even for a huge monorepo.
An existing .codegraph/ is left untouched — serve re-syncs it on connect and the file-watcher keeps it fresh thereafter. The init step is required because serve does NOT auto-create .codegraph/: without it, it runs in a degraded, no-index mode rather than building one.
func IndexableRoot ¶
IndexableRoot reports whether root is a real project directory CodeGraph can safely be pinned to. A filesystem root (a Windows drive root like C:\, a UNC share root, or the unix /) is rejected: serve --mcp walks its working directory, so a root cwd makes it index the whole volume — C:\Windows, C:\Program Files, everything — pinning gigabytes of RAM (#3747). An empty root is rejected too: there is nothing to pin a cwd-aware server to.
func Initialized ¶
Initialized reports whether root already has CodeGraph's project state. Boot uses this to keep warm projects eager while moving first-time project setup to background startup, avoiding a cold MCP handshake on the app's critical path.
func Install ¶
Install downloads and unpacks the CodeGraph bundle into CacheDir on first use, verifying it against the checksum baked into the fairpeer binary, then returns the launcher path. It is idempotent: a present cache is returned untouched. log, if non-nil, receives a couple of progress lines. The extraction is staged in a temp dir and atomically renamed into place, so a cancelled or failed run leaves no partial install behind.
func InstallWithClient ¶
InstallWithClient is Install with an explicit HTTP client, used when fairpeer network proxy settings should apply.
func ReadOnlyToolNames ¶
ReadOnlyToolNames returns the CodeGraph MCP tools fairpeer treats as readers when older CodeGraph runtimes omit MCP annotations.readOnlyHint metadata.
func Resolve ¶
Resolve returns the absolute path to the CodeGraph launcher. Search order:
- override — an explicit codegraph.path from config (~ and ${VAR} expanded);
- the per-version cache populated by Install;
- a system-installed `codegraph` on PATH;
- a bundle placed beside the executable (manual/offline fallback).
ok is false when none resolves — the caller then triggers Install (or skips the feature), so the codegraph_* tools come online once the cache is populated.
func SetDownloadBase ¶
func SetDownloadBase(url string)
SetDownloadBase overrides the download source for the CodeGraph binary. Pass "" to restore the default (GitHub + mainland mirror). The URL should be the base (without the version or asset name); the installer appends those.
Types ¶
This section is empty.
Source Files