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

Guide	Description
Korean Guide	한국어 문서 인덱스 (Korean Documentation Index)
CLI Reference	All commands, flags, and config file (.ccg.yaml)
Eval	Parser/search quality evaluation, golden corpus, and metrics
Lint	Detailed ccg lint category reference, interpretation guide, and CI usage
MCP Tools	33 MCP tools, agent skills, AI-Driven Annotation
Annotations	Annotation system — tags, examples, search
Webhook	Webhook sync, branch filtering, HMAC, graceful shutdown
Docker	Docker build, MCP server, Wiki UI, PostgreSQL deployment
Operations	Deployment profiles, database choice, readiness, webhook operations
Postprocess Failure Policy	Status rules, failure causes, and automatic degraded/fail_closed policy for build and postprocess tools
Runtime Layout	ccg, ccg-server, Wiki serving, and shared ccg-core ownership boundaries
Development	Dev guide, integration test, project structure
Namespace Migration	Default namespace change and migration guide
Architecture	Data flow, components, DB schema
CLAUDE.md Guide	Template for projects using CCG

License

MIT