codegraph

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.

OK ships the CodeGraph bundle alongside its own executable, so Resolve finds it next to the binary; an explicit config path and a system-installed `codegraph` on PATH are honored as an override / fallback. 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 EnsureInit(ctx context.Context, bin, root string) error
• func Resolve(override string) (string, bool)
• type Index
  • func (idx *Index) Summarize() string
• type Indexer
  • func NewIndexer() *Indexer
  • func (idx *Indexer) IndexDir(ctx context.Context, root string) (*Index, error)
• type Symbol
• type SymbolKind

Constants

const BundleDirName = "codegraph"

BundleDirName is the directory, beside the ok executable, that the release archive unpacks the CodeGraph bundle into. 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.

Functions

func EnsureInit

func EnsureInit(ctx context.Context, bin, root string) error

EnsureInit initializes 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 Resolve

func Resolve(override string) (string, bool)

Resolve returns the absolute path to the CodeGraph launcher. Search order:

1. override — an explicit codegraph.path from config (~ and ${VAR} expanded);
2. the bundle shipped beside the ok executable (the distribution case);
3. a system-installed `codegraph` on PATH.

ok is false when none resolves, in which case the caller skips the feature silently — a missing bundle just means the codegraph_* tools are unavailable.

Types

type Index

type Index struct {
	Symbols []Symbol `json:"symbols"`
	Files   int      `json:"files"`
	Langs   []string `json:"languages"`
}

func (*Index) Summarize

func (idx *Index) Summarize() string

Summarize returns a concise string for system prompt injection.

type Indexer

type Indexer struct{}

func NewIndexer

func NewIndexer() *Indexer

func (*Indexer) IndexDir

func (idx *Indexer) IndexDir(ctx context.Context, root string) (*Index, error)

type Symbol

type Symbol struct {
	Name     string     `json:"name"`
	Kind     SymbolKind `json:"kind"`
	KindName string     `json:"kind_name"`
	File     string     `json:"file"`
	Line     int        `json:"line"`
	Language string     `json:"language"`
}

type SymbolKind

type SymbolKind int

const (
	SymbolFunction SymbolKind = iota
	SymbolMethod
	SymbolStruct
	SymbolInterface
	SymbolClass
	SymbolImport
	SymbolVariable
	SymbolType
	SymbolEnum
	SymbolTrait
)