cgraphx

Local-first code intelligence for AI coding agents. Based on colbymchenry/codegraph,originally authored by Colby Chenry. See Acknowledgements.

What it is

cgraphx 是一个本地优先的代码智能工具,基于 codegraph 衍生 —— 在原版代码图谱之上增加了中文 skills 工作流、markdown 知识库、数据库查询、Developer Timeline:

• 用 tree-sitter 解析代码库,把 symbols / edges / files 存到 SQLite(FTS5)
• 暴露 knowledge graph 给 AI agent(Claude Code / Cursor / Codex / opencode / ...)
• per-project 数据在 .cgraphx/,不外传
• CLI / MCP server / Library 三种使用方式,同一份二进制

Key Features

• 本地优先 —— 所有数据在 .cgraphx/cgraphx.db,SQLite + WAL,sub-millisecond reads
• 自动同步 —— 文件改动后增量同步(native FSEvents / inotify / RDCW)
• 多语言 —— TypeScript / JavaScript / Python / Go / Rust / Java / C# / PHP / Ruby / C / C++ / Swift / Kotlin / Scala / Dart / Svelte / Vue / Astro / Lua / Luau / R / Liquid / Pascal/Delphi ...
• 多 Agent —— Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro
• 跨平台 —— macOS / Linux / Windows,x64 + arm64
• MCP 单工具入口 —— codegraph_explore 一次调用拿源码 + 调用路径 + 影响半径
• 多子系统 —— code graph + markdown knowledge base + db introspection + developer timeline

Get Started

1. Install the CLI

# npm
npm i -g cgraphx

# 或本地构建
git clone https://github.com/smdnkB/cgraphx.git
cd cgraphx
npm install && npm run build
node dist/bin/codegraph.js --version

2. Wire up your agent(s)

cgraphx install

自动检测并配置:Claude Code / Cursor / Codex CLI / opencode / Hermes / Gemini / Antigravity / Kiro。 仅写入 agent 的 MCP server config,不索引代码。

3. Initialize each project

cd your-project
cgraphx init

cgraphx init 创建 .cgraphx/ 目录并构建完整 graph,一步到位。

4. Auto-sync(默认开启)

文件改动后自动增量同步,无需手动操作。cgraphx status 看新鲜度。

Uninstall

cgraphx uninstall      # 从所有 agent 移除 MCP 配置(保留项目索引)
cgraphx uninit         # 移除当前项目的 .cgraphx/(--force 跳过确认)

CLI Reference

# 安装 / 配置
cgraphx install                # 配置 agent
cgraphx uninstall              # 移除 agent 配置
cgraphx upgrade [version]      # 升级(--check 看是否有新版)

# 项目索引
cgraphx init [path]            # 初始化项目 + 构建 graph
cgraphx uninit [path]          # 移除项目索引
cgraphx index [path]           # 全量重建(--force / --quiet)
cgraphx sync [path]            # 增量同步
cgraphx status [path]          # 索引状态
cgraphx unlock [path]          # 清除 stale lock

# 查询(主 graph)
cgraphx explore <query>        # 自然语言探索,主入口(同 MCP 的 codegraph_explore)
cgraphx node <symbol|file>     # 单符号详情 / 文件内容(带行号)
cgraphx query <search>         # 按名字搜符号(--kind / --limit / --json)
cgraphx callers <symbol>       # 谁调用 X
cgraphx callees <symbol>       # X 调用谁
cgraphx affected [files...]    # 改这些文件受影响的测试(--stdin / --filter)
cgraphx files [path]           # 项目文件结构

# 子系统
cgraphx db <subcmd>            # 数据库 introspection(MySQL/PG,只读,CLI-only)
cgraphx docs <subcmd>          # Markdown 知识库(docs/knowledge/)
cgraphx timeline <subcmd>      # 开发历史(prompt / tool / commit 事件流)

# 其他
cgraphx daemon                 # 管理后台 daemon
cgraphx telemetry [on|off]     # 匿名遥测开关
cgraphx version                # 版本
cgraphx help [command]         # 帮助

详细参数见 cgraphx help <command>。

MCP Tools

CodeGraph 作为 MCP server 时,默认只暴露一个工具:

| Tool | Purpose | |---|---| | codegraph_explore | 主入口。给符号名 / 文件 / 自然语言问题,返回相关符号源码 + 调用路径(含动态派生边)+ 影响半径。一次调用通常够答完整问题 |

其他工具(codegraph_node / codegraph_search / codegraph_callers / codegraph_callees / codegraph_impact / codegraph_files / codegraph_status)功能保留,默认不暴露在 MCP surface —— 它们的输出已经内联在 codegraph_explore 里。需要时:

• 用 CGRAPHX_MCP_TOOLS=explore,node,search,callers 环境变量重新启用
• 或走 CLI 等价命令(cgraphx node / query / callers / ...)

How It Works

┌──────────────────────┐
│   AI agent           │  "How does X reach Y?"
│ (Claude/Cursor/...)  │  → calls codegraph_explore directly
└──────────┬───────────┘
           │
           ▼
┌──────────────────────────────────────────┐
│         CodeGraph MCP Server             │
│  explore: source + flow + blast radius   │
└──────────┬───────────────────────────────┘
           │
           ▼
┌──────────────────────────────────────────┐
│       SQLite Knowledge Graph             │
│  symbols · edges · files · FTS5          │
│  (.cgraphx/cgraphx.db)               │
└──────────────────────────────────────────┘

1. Extraction — tree-sitter 解析为 AST,语言特定 query 提取 nodes / edges
2. Storage — SQLite + WAL + FTS5,per-project 隔离
3. Resolution — 解析 references(imports → source,calls → definitions,framework patterns)
4. Auto-Sync — 原生 OS 文件事件 + debounce(2s)+ 增量同步

Configuration

| 路径 / 文件 | 用途 | |---|---| | .cgraphx/cgraphx.db | 项目主索引(SQLite,symbols/edges/files + markdown_* + timeline_* 同库不同表) | | .cgraphx/db-profiles.json | 数据库 profiles(项目级,优先于用户级) | | ~/.cgraphx/db-profiles.json | 用户级数据库 profiles | | docs/knowledge/*.md | 项目业务知识库(给 cgraphx docs 子系统扫) | | .claude/settings.json | agent MCP 配置(cgraphx install 写入) |

常用环境变量

• CGRAPHX_NO_TIMELINE=1 —— 禁用 timeline hooks
• CGRAPHX_DB_QUERY_DISABLED=1 —— 禁用 db-query 子系统
• CGRAPHX_MCP_TOOLS=explore,node,... —— 自定义 MCP 暴露的工具集
• CGRAPHX_NO_DAEMON=1 —— 禁用共享 daemon(每 session 独立进程,适合 WSL2 /mnt)
• CGRAPHX_DIR=.cgraphx-win —— 区分 Windows / WSL 共享 checkout 的索引

Subsystems

除了主 code graph,cgraphx 还有三个独立子系统:

| 子系统 | 命令 | 用途 | |---|---|---| | Markdown Knowledge Base | cgraphx docs <subcmd> | 索引 docs/knowledge/ 下的业务决策、概念、教训;hybrid search(BM25 + 向量) | | Database Introspection | cgraphx db <subcmd> | 外部 MySQL/PostgreSQL 只读查询(CLI-only,内置安全层) | | Developer Timeline | cgraphx timeline <subcmd> | 开发事件流(user prompt / tool use / git commit),per-project 隔离 |

各子系统有独立的表 / schema 版本 / 安全约束,详见 CLAUDE.md。

Supported Platforms

| Platform | Architectures | |---|---| | macOS | x64, arm64 | | Linux | x64, arm64 | | Windows | x64, arm64 |

Supported Agents

cgraphx install 自动检测并配置:

• Claude Code
• Cursor
• Codex CLI
• opencode
• Hermes Agent
• Gemini CLI
• Antigravity IDE
• Kiro

Supported Languages

| Language | Status | |---|---| | TypeScript / JavaScript | Full | | Python | Full | | Go | Full | | Rust | Full | | Java | Full | | C# | Full | | PHP | Full | | Ruby | Full | | C / C++ | Full | | Swift / Kotlin / Scala / Dart | Full | | Svelte / Vue / Astro | Full(含 framework routes) | | Lua / Luau / R | Full | | Liquid / Pascal / Delphi | Full | | Objective-C | Partial(类、协议、方法、@property、#import、message sends;.mm ObjC++ 可能不完整) |

Troubleshooting

"CodeGraph not initialized" — 在项目目录跑 cgraphx init。

Indexing 慢 — 确认 node_modules / dist 等大目录被默认排除;加 --quiet。

MCP database is locked — 不应出现(本构建用 node:sqlite + WAL,并发读不阻塞写)。若仍出现:cgraphx status 看 Journal 字段,非 wal 说明 WAL 无法启用(网络盘 / WSL2 /mnt),把项目移到本地盘。

MCP server 连不上 — agent 自己启动 server,不需要手动 launch。确认 cgraphx status 正常 + MCP config 路径正确;不行就 cgraphx install 重写配置。

Missing symbols — MCP 自动同步有 ~1s 延迟;不行就 cgraphx sync。确认文件语言被支持、不在 .gitignore 排除目录里。

Windows + WSL 共享 checkout —— 不要让两边用同一个 .cgraphx/。给其中一边设 CGRAPHX_DIR=.cgraphx-win(或类似),两边各用各的索引。

Acknowledgements

cgraphx is based on colbymchenry/codegraph,originally authored by Colby Chenry.

All credit for the original architecture — tree-sitter-based extraction, the MCP single-tool design, the dynamic-dispatch synthesis, and the broader project direction — belongs to the original author and contributors.

This fork exists for internal customization; upstream is the source of truth for the project's roadmap and the canonical place to contribute back.

License

MIT