{"id":50565319,"url":"https://github.com/tae2089/code-context-graph","last_synced_at":"2026-06-04T14:01:09.544Z","repository":{"id":350868296,"uuid":"1208561656","full_name":"tae2089/code-context-graph","owner":"tae2089","description":"Vectorless code retrieval for AI coding agents — search code by business intent (@intent, @domainRule), built for MSA via MCP.","archived":false,"fork":false,"pushed_at":"2026-05-06T13:17:59.000Z","size":12916,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-13T22:09:10.630Z","etag":null,"topics":["agent-skill","ai-coding","claude","claude-code","code-review","go","golang","graphrag","incremental","knowledge-graph","llm","mcp","static-analysis","tree-sitter"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tae2089.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T13:04:21.000Z","updated_at":"2026-05-06T13:18:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tae2089/code-context-graph","commit_stats":null,"previous_names":["tae2089/code-context-graph"],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/tae2089/code-context-graph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tae2089%2Fcode-context-graph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tae2089%2Fcode-context-graph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tae2089%2Fcode-context-graph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tae2089%2Fcode-context-graph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tae2089","download_url":"https://codeload.github.com/tae2089/code-context-graph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tae2089%2Fcode-context-graph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33907694,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","ai-coding","claude","claude-code","code-review","go","golang","graphrag","incremental","knowledge-graph","llm","mcp","static-analysis","tree-sitter"],"created_at":"2026-06-04T14:01:08.098Z","updated_at":"2026-06-04T14:01:09.518Z","avatar_url":"https://github.com/tae2089.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# code-context-graph\n\nLocal code analysis tool that parses codebases via Tree-sitter into a knowledge graph. Supports 12 languages, 33 MCP tools, and custom annotation search.\n\nCCG 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.\n\nThis 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.\n\nInspired by [code-review-graph](https://github.com/tirth8205/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.\n\n## Features\n\n- **12 languages**: Go, Python, TypeScript, Java, Ruby, JavaScript, C, C++, Rust, Kotlin, PHP, Lua/Luau\n- **33 MCP tools**: parse, search, impact analysis, flow tracing, dead code detection, postprocess operations, namespace file management, and more\n- **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\n- **Browser Wiki UI**: `ccg-server` can serve generated docs, tree search, DB-backed retrieval, Context Tray copying, and an Obsidian-style graph viewer\n- **Custom annotations**: `@intent`, `@domainRule`, `@sideEffect`, `@mutates`, `@index` — search code by business context ([details](guide/annotations.md))\n- **Webhook sync**: GitHub / Gitea push events → auto clone + build with per-repo branch filtering and `.ccg.yaml` `include_paths` auto-loading ([details](guide/webhook.md))\n- **Eval**: Golden corpus-based parser accuracy (P/R/F1) and search quality (P@K, MRR, nDCG) evaluation ([details](guide/eval.md))\n- **Multi-DB**: SQLite (local), PostgreSQL\n- **Full-text search**: FTS5 (SQLite), tsvector+GIN (PostgreSQL)\n\n## Installation\n\n### npm / bun (recommended)\n\n```bash\nnpm install -g code-context-graph\n# or\nbun install -g code-context-graph\n```\n\nThe npm package installs both `ccg` and `ccg-server`.\n\n### go install\n\n```bash\ngo install github.com/tae2089/code-context-graph/cmd/ccg@latest\ngo install github.com/tae2089/code-context-graph/cmd/ccg-server@latest\n```\n\n### Build from source\n\n```bash\nCGO_ENABLED=1 go build -tags \"fts5\" -o ccg ./cmd/ccg/\nCGO_ENABLED=1 go build -tags \"fts5\" -o ccg-server ./cmd/ccg-server/\n\n# Or use Makefile (injects version from git tag automatically)\nmake build\n# Local stripped release-style build\nmake release\n```\n\n## Quick Start\n\n```bash\n# Parse your project. For the default local SQLite database (ccg.db), runtime\n# commands create and migrate the database automatically on first use only when\n# the schema is missing.\nccg build .\n# Build complete: 70 files, 749 nodes, 7387 edges\n\n# Search (includes annotations)\nccg search \"authentication\"\n\n# Search by business context\nccg search \"payment\"    # finds functions with @intent/@domainRule about payments\n\n# Build docs and the default vectorless RAG index for agent-oriented exploration\nccg docs --out docs\n\n# Serve the browser Wiki UI from built assets; builds the graph for DB-backed APIs\nmake wiki-run\n\n# Graph statistics\nccg status\n\n# Version info\nccg version\n\n# Namespace isolation (MSA)\nccg build ./backend --namespace backend\nccg search --namespace backend \"auth\"\n\n# Evaluate parser accuracy (12 languages)\nccg eval --suite parser\n\n# Update golden corpus\nccg eval --suite parser --update\n```\n\n`ccg docs` writes generated Markdown plus `.ccg/wiki-index.json` as a browser\nWiki compatibility snapshot. The Wiki prefers the graph database for tree\nnavigation and search, then uses `wiki-index.json` only when DB-backed\nnavigation is unavailable. By default `ccg docs` also refreshes community\nstructure and writes `.ccg/doc-index.json` as a compatibility snapshot for\nmanual RAG-index workflows; runtime `retrieve_docs` uses DB-backed graph and\nannotation evidence. Use `--rag=false` when you only want Markdown and the Wiki\nsnapshot, or `--rag-refresh=false` when you want to rebuild the RAG index from\nexisting community rows without recalculating communities.\n\nFor LLM agents, use DB-backed `retrieve_docs` as the first stop for broad\nnatural-language questions such as \"how does webhook sync work?\" or \"where are\nthe operational risks?\". It is not a Top1 search engine; it is an\nevidence-driven narrowing layer that should return a small set of relevant\nfiles with `matched_fields`, `matched_terms`, and evidence nodes. Use\n`get_doc_content`, `get_node`, `query_graph`, `trace_flow`, and impact tools\nonly after the route is narrowed. Use `ccg search` as a focused\nannotation/keyword candidate search rather than the first tool for broad code\nunderstanding.\n\nIf you use PostgreSQL, a custom SQLite DSN, an existing schema, or a controlled\nupgrade workflow, run `ccg migrate` explicitly before runtime commands. This\nalso applies when upgrading CCG against an existing default `ccg.db` created by\nan older version. See the [CLI Reference](guide/cli-reference.md) for the full\nmigration contract.\n\n## Browser Wiki\n\n`ccg-server` can serve a React-based Wiki UI at `/wiki` when `--wiki-dir` points\nat a built `web/wiki/dist` directory. Docker images include that built UI at\n`/usr/share/ccg/wiki`; standalone binaries keep the assets separate so binary\nsize stays small.\n\nThe Wiki is meant for developers and agents inspecting a generated codebase:\n\n- Tree navigation over folders, packages, files, and annotated symbols\n- Keyword search and DB-backed `retrieve_docs` with matched evidence and small\n  file-level result sets\n- Rich symbol detail cards from CCG annotations even when a symbol has no\n  generated Markdown file\n- Context Tray for collecting files and doc-less symbols into one Markdown\n  bundle that can be copied into another LLM tool\n- Graph tab backed by `/wiki/api/graph`, showing namespace nodes and edges with\n  filters for structure, calls, imports, types, and symbols\n\nLocal development shortcut:\n\n```bash\nmake wiki-run\n```\n\nUse `make wiki-run-indexed` when you also want generated Markdown,\n`wiki-index.json` snapshot, and the compatibility `doc-index.json` before\nstarting the server.\n\nFor self-hosted deployments, run `ccg-server --wiki-dir \u003cdist-dir\u003e` and protect\n`/wiki/api/*` with the same bearer token policy used for `/mcp`. See\n[Docker](guide/docker.md#wiki-ui) and [Runtime Layout](guide/runtime-layout.md)\nfor deployment details.\n\n## Demo\n\nActual output from CCG parsing its own codebase.\n\n### 1. Parse the Codebase\n\n```\n$ ccg build .\nBuild complete: 127 files, 1220 nodes, 12222 edges\n```\n\n### 2. Graph Statistics\n\n```\n$ ccg status\nNodes: 1220\nEdges: 12222\nFiles: 127\n\nNode kinds:\n  class:    124\n  file:     127\n  function: 405\n  test:     543\n  type:      21\n\nEdge kinds:\n  calls:        9245\n  contains:     1097\n  imports_from: 1128\n  inherits:        1\n  tested_by:     751\n\nPostprocess:\n  Status: ok\n  Fail-closed: 0\n  Recent failures: 0\n```\n\n### 3. Code Search\n\n```\n$ ccg search \"impact analysis\"\ninternal/analysis/impact/impact_test.go  file      internal/analysis/impact/impact_test.go:1\ninternal/analysis/impact/impact.go       file      internal/analysis/impact/impact.go:1\nmcp.ImpactAnalyzer                       type      internal/mcp/server.go:36\nimpact.EdgeReader                        type      internal/analysis/impact/impact.go:12\nimpact.Analyzer.ImpactRadius             function  internal/analysis/impact/impact.go:42\ninternal/mcp/handler_analysis.go         file      internal/mcp/handler_analysis.go:1\n\n$ ccg search \"dead code\"\ndeadcode.Options          class     internal/analysis/deadcode/service.go:14\ndeadcode.Service.Find     function  internal/analysis/deadcode/service.go:38\nmcp.handlers.findDeadCode function  internal/mcp/handler_analysis.go:273\n```\n\n### 4. Agent Integration via MCP\n\nAfter configuring `.mcp.json`, you can ask an MCP-capable coding agent directly:\n\n\u003e **\"Explain the webhook sync flow in this project\"**\n\nThe agent calls CCG MCP tools and answers directly from the graph:\n\n```\ntrace_flow(qualified_name: \"webhook.WebhookHandler.ServeHTTP\")\n→ WebhookHandler.ServeHTTP\n  → SyncQueue.Enqueue\n    → safeHandle (retry loop: max 3 attempts, exponential backoff 1s→30s)\n      → clone (git clone, 15min timeout)\n      → build (ccg build, same context)\n```\n\n\u003e **\"Where is the authentication-related code?\"**\n\n```\nsearch(query: \"authentication\")\n→ internal/webhook/handler.go  (HMAC signature validation)\n→ cmd/ccg-server/main.go       (--webhook-secret flag)\n```\n\n## MCP Server\n\nAdd `.mcp.json` to your project:\n\n```json\n{\n  \"mcpServers\": {\n    \"ccg\": {\n      \"command\": \"ccg\",\n      \"args\": [\"serve\", \"--db-driver\", \"sqlite\", \"--db-dsn\", \"ccg.db\"]\n    }\n  }\n}\n```\n\nFor remote HTTP mode:\n\nRun the self-hosted server with `ccg-server` and connect to `/mcp`. The same\nserver can also expose `/wiki` when `--wiki-dir` is configured:\n\n```json\n{\n  \"mcpServers\": {\n    \"ccg\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"http://your-server:8080/mcp\"\n    }\n  }\n}\n```\n\nMCP-capable clients such as Codex or Claude Code can connect and get access to\n33 MCP tools. See [MCP Tools Reference](guide/mcp-tools.md) for the full list.\n\n## Architecture\n\n```\nSource Code → Tree-sitter Parser → Nodes + Edges + Annotations\n                                        ↓\n                              SQLite / PostgreSQL (GORM)\n                                        ↓\n                                   FTS Search\n                                        ↓\n                         ccg serve                ccg-server\n                         stdio MCP        Streamable HTTP + Wiki UI\n                            ↓              ↓          ↓          ↑\n                     Coding Agents   Remote Clients  Browser   GitHub / Gitea Webhook\n                                                       Wiki      push → clone → build → DB\n```\n\nSee [Architecture Details](guide/architecture.md) for component breakdown and DB schema.\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Korean Guide](guide/ko/README.md) | 한국어 문서 인덱스 (Korean Documentation Index) |\n| [CLI Reference](guide/cli-reference.md) | All commands, flags, and config file (`.ccg.yaml`) |\n| [Eval](guide/eval.md) | Parser/search quality evaluation, golden corpus, and metrics |\n| [Lint](guide/lint.md) | Detailed `ccg lint` category reference, interpretation guide, and CI usage |\n| [MCP Tools](guide/mcp-tools.md) | 33 MCP tools, agent skills, AI-Driven Annotation |\n| [Annotations](guide/annotations.md) | Annotation system — tags, examples, search |\n| [Webhook](guide/webhook.md) | Webhook sync, branch filtering, HMAC, graceful shutdown |\n| [Docker](guide/docker.md) | Docker build, MCP server, Wiki UI, PostgreSQL deployment |\n| [Operations](guide/operations.md) | Deployment profiles, database choice, readiness, webhook operations |\n| [Postprocess Failure Policy](guide/postprocess-failure-policy.md) | Status rules, failure causes, and automatic degraded/fail_closed policy for build and postprocess tools |\n| [Runtime Layout](guide/runtime-layout.md) | `ccg`, `ccg-server`, Wiki serving, and shared `ccg-core` ownership boundaries |\n| [Development](guide/development.md) | Dev guide, integration test, project structure |\n| [Namespace Migration](guide/namespace-migration.md) | Default namespace change and migration guide |\n| [Architecture](guide/architecture.md) | Data flow, components, DB schema |\n| [CLAUDE.md Guide](guide/claude-md-guide.md) | Template for projects using CCG |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftae2089%2Fcode-context-graph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftae2089%2Fcode-context-graph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftae2089%2Fcode-context-graph/lists"}