code-context-graph

Local code analysis tool that parses codebases via Tree-sitter into a knowledge graph. Supports 12 languages, 33 MCP tools, and custom annotation search.

CCG is built primarily for GPT, Claude, Codex, and other LLM-based coding agents. It acts as local or self-hosted context infrastructure: agents can search code by intent, inspect call graphs, trace impact, retrieve docs, and keep responses bounded instead of reading entire repositories into context.

This is a developer-operated tool, not a general SaaS admin product. The expected users are coding agents and developers who can run CLI commands, configure MCP, read logs, and use the generated graph/docs to guide code changes.

Inspired by code-review-graph — a Python-based code analysis tool. This project reimplements and extends the concept in Go with multi-DB support, custom annotation system, and MCP integration for AI-powered code understanding.

Features

• 12 languages: Go, Python, TypeScript, Java, Ruby, JavaScript, C, C++, Rust, Kotlin, PHP, Lua/Luau
• 33 MCP tools: parse, search, impact analysis, flow tracing, dead code detection, postprocess operations, namespace file management, and more
• Evidence-driven code exploration: DB-backed retrieval returns small file-level candidates with matched fields, evidence nodes, and optional docs before agents drill into exact graph nodes
• Browser Wiki UI: ccg-server can serve generated docs, tree search, DB-backed retrieval, Context Tray copying, and an Obsidian-style graph viewer
• Custom annotations: @intent, @domainRule, @sideEffect, @mutates, @index — search code by business context (details)
• Webhook sync: GitHub / Gitea push events → auto clone + build with per-repo branch filtering and .ccg.yaml include_paths auto-loading (details)
• Eval: Golden corpus-based parser accuracy (P/R/F1) and search quality (P@K, MRR, nDCG) evaluation (details)
• Multi-DB: SQLite (local), PostgreSQL
• Full-text search: FTS5 (SQLite), tsvector+GIN (PostgreSQL)

Installation

npm / bun (recommended)

npm install -g code-context-graph
# or
bun install -g code-context-graph

The npm package installs both ccg and ccg-server.

go install

go install github.com/tae2089/code-context-graph/cmd/ccg@latest
go install github.com/tae2089/code-context-graph/cmd/ccg-server@latest

Build from source

CGO_ENABLED=1 go build -tags "fts5" -o ccg ./cmd/ccg/
CGO_ENABLED=1 go build -tags "fts5" -o ccg-server ./cmd/ccg-server/

# Or use Makefile (injects version from git tag automatically)
make build
# Local stripped release-style build
make release

Quick Start

# Parse your project. For the default local SQLite database (ccg.db), runtime
# commands create and migrate the database automatically on first use only when
# the schema is missing.
ccg build .
# Build complete: 70 files, 749 nodes, 7387 edges

# Search (includes annotations)
ccg search "authentication"

# Search by business context
ccg search "payment"    # finds functions with @intent/@domainRule about payments

# Build docs and the default vectorless RAG index for agent-oriented exploration
ccg docs --out docs

# Serve the browser Wiki UI from built assets; builds the graph for DB-backed APIs
make wiki-run

# Graph statistics
ccg status

# Version info
ccg version

# Namespace isolation (MSA)
ccg build ./backend --namespace backend
ccg search --namespace backend "auth"

# Evaluate parser accuracy (12 languages)
ccg eval --suite parser

# Update golden corpus
ccg eval --suite parser --update

ccg docs writes generated Markdown plus .ccg/wiki-index.json as a browser
Wiki compatibility snapshot. The Wiki prefers the graph database for tree
navigation and search, then uses wiki-index.json only when DB-backed
navigation is unavailable. By default ccg docs also refreshes community
structure and writes .ccg/doc-index.json as a compatibility snapshot for
manual RAG-index workflows; runtime retrieve_docs uses DB-backed graph and
annotation evidence. Use --rag=false when you only want Markdown and the Wiki
snapshot, or --rag-refresh=false when you want to rebuild the RAG index from
existing community rows without recalculating communities.

For LLM agents, use DB-backed retrieve_docs as the first stop for broad
natural-language questions such as "how does webhook sync work?" or "where are
the operational risks?". It is not a Top1 search engine; it is an
evidence-driven narrowing layer that should return a small set of relevant
files with matched_fields, matched_terms, and evidence nodes. Use
get_doc_content, get_node, query_graph, trace_flow, and impact tools
only after the route is narrowed. Use ccg search as a focused
annotation/keyword candidate search rather than the first tool for broad code
understanding.

If you use PostgreSQL, a custom SQLite DSN, an existing schema, or a controlled
upgrade workflow, run ccg migrate explicitly before runtime commands. This
also applies when upgrading CCG against an existing default ccg.db created by
an older version. See the CLI Reference for the full
migration contract.

Browser Wiki

ccg-server can serve a React-based Wiki UI at /wiki when --wiki-dir points
at a built web/wiki/dist directory. Docker images include that built UI at
/usr/share/ccg/wiki; standalone binaries keep the assets separate so binary
size stays small.

The Wiki is meant for developers and agents inspecting a generated codebase:

• Tree navigation over folders, packages, files, and annotated symbols
• Keyword search and DB-backed retrieve_docs with matched evidence and small
  file-level result sets
• Rich symbol detail cards from CCG annotations even when a symbol has no
  generated Markdown file
• Context Tray for collecting files and doc-less symbols into one Markdown
  bundle that can be copied into another LLM tool
• Graph tab backed by /wiki/api/graph, showing namespace nodes and edges with
  filters for structure, calls, imports, types, and symbols

Local development shortcut:

make wiki-run

Use make wiki-run-indexed when you also want generated Markdown,
wiki-index.json snapshot, and the compatibility doc-index.json before
starting the server.

For self-hosted deployments, run ccg-server --wiki-dir <dist-dir> and protect
/wiki/api/* with the same bearer token policy used for /mcp. See
Docker and Runtime Layout
for deployment details.

Demo

Actual output from CCG parsing its own codebase.

1. Parse the Codebase

$ ccg build .
Build complete: 127 files, 1220 nodes, 12222 edges

2. Graph Statistics

$ ccg status
Nodes: 1220
Edges: 12222
Files: 127

Node kinds:
  class:    124
  file:     127
  function: 405
  test:     543
  type:      21

Edge kinds:
  calls:        9245
  contains:     1097
  imports_from: 1128
  inherits:        1
  tested_by:     751

Postprocess:
  Status: ok
  Fail-closed: 0
  Recent failures: 0

3. Code Search

$ ccg search "impact analysis"
internal/analysis/impact/impact_test.go  file      internal/analysis/impact/impact_test.go:1
internal/analysis/impact/impact.go       file      internal/analysis/impact/impact.go:1
mcp.ImpactAnalyzer                       type      internal/mcp/server.go:36
impact.EdgeReader                        type      internal/analysis/impact/impact.go:12
impact.Analyzer.ImpactRadius             function  internal/analysis/impact/impact.go:42
internal/mcp/handler_analysis.go         file      internal/mcp/handler_analysis.go:1

$ ccg search "dead code"
deadcode.Options          class     internal/analysis/deadcode/service.go:14
deadcode.Service.Find     function  internal/analysis/deadcode/service.go:38
mcp.handlers.findDeadCode function  internal/mcp/handler_analysis.go:273

4. Agent Integration via MCP

After configuring .mcp.json, you can ask an MCP-capable coding agent directly:

"Explain the webhook sync flow in this project"

The agent calls CCG MCP tools and answers directly from the graph:

trace_flow(qualified_name: "webhook.WebhookHandler.ServeHTTP")
→ WebhookHandler.ServeHTTP
  → SyncQueue.Enqueue
    → safeHandle (retry loop: max 3 attempts, exponential backoff 1s→30s)
      → clone (git clone, 15min timeout)
      → build (ccg build, same context)

"Where is the authentication-related code?"

search(query: "authentication")
→ internal/webhook/handler.go  (HMAC signature validation)
→ cmd/ccg-server/main.go       (--webhook-secret flag)

MCP Server

Add .mcp.json to your project:

{
  "mcpServers": {
    "ccg": {
      "command": "ccg",
      "args": ["serve", "--db-driver", "sqlite", "--db-dsn", "ccg.db"]
    }
  }
}

For remote HTTP mode:

Run the self-hosted server with ccg-server and connect to /mcp. The same
server can also expose /wiki when --wiki-dir is configured:

{
  "mcpServers": {
    "ccg": {
      "type": "streamable-http",
      "url": "http://your-server:8080/mcp"
    }
  }
}

MCP-capable clients such as Codex or Claude Code can connect and get access to
33 MCP tools. See MCP Tools Reference for the full list.

Architecture

Source Code → Tree-sitter Parser → Nodes + Edges + Annotations
                                        ↓
                              SQLite / PostgreSQL (GORM)
                                        ↓
                                   FTS Search
                                        ↓
                         ccg serve                ccg-server
                         stdio MCP        Streamable HTTP + Wiki UI
                            ↓              ↓          ↓          ↑
                     Coding Agents   Remote Clients  Browser   GitHub / Gitea Webhook
                                                       Wiki      push → clone → build → DB

See Architecture Details for component breakdown and DB schema.

Documentation

License

MIT