From 54ca77229d85939c00f7094d1aae34860a4a4323 Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Tue, 16 Jun 2026 01:33:22 +0900 Subject: [PATCH 1/2] feat(codegraph): add CodeGraph local code-intelligence plugin Add the codegraph plugin wrapping @colbymchenry/codegraph, a local-first MCP server that exposes a pre-indexed knowledge graph (symbols, call graphs, impact) so agents query structure instead of scanning files. - MCP server via npx -y @colbymchenry/codegraph serve --mcp - Skill for intelligent activation (allowed-tools covers all 8 tools) - Conditional SessionStart hook that injects navigation guidance only when the repo is indexed (a .codegraph/ directory exists), so subagents and non-MCP harnesses get the pointers the MCP initialize step misses - Codex + Antigravity manifests generated via multi-format - Marketplace entries (Claude + Codex) --- .agents/plugins/marketplace.json | 12 +++++ .claude-plugin/marketplace.json | 8 +++ plugins/codegraph/.claude-plugin/plugin.json | 20 ++++++++ plugins/codegraph/.codex-plugin/plugin.json | 34 ++++++++++++ plugins/codegraph/.mcp.json | 14 +++++ plugins/codegraph/hooks.json | 17 ++++++ plugins/codegraph/hooks/context.sh | 22 ++++++++ plugins/codegraph/hooks/hooks.json | 17 ++++++ plugins/codegraph/mcp_config.json | 14 +++++ plugins/codegraph/plugin.json | 19 +++++++ plugins/codegraph/skills/codegraph/SKILL.md | 54 ++++++++++++++++++++ 11 files changed, 231 insertions(+) create mode 100644 plugins/codegraph/.claude-plugin/plugin.json create mode 100644 plugins/codegraph/.codex-plugin/plugin.json create mode 100644 plugins/codegraph/.mcp.json create mode 100644 plugins/codegraph/hooks.json create mode 100755 plugins/codegraph/hooks/context.sh create mode 100644 plugins/codegraph/hooks/hooks.json create mode 100644 plugins/codegraph/mcp_config.json create mode 100644 plugins/codegraph/plugin.json create mode 100644 plugins/codegraph/skills/codegraph/SKILL.md diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index fca5d482..3301a14c 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -16,6 +16,18 @@ }, "category": "Database" }, + { + "name": "codegraph", + "source": { + "source": "local", + "path": "./plugins/codegraph" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Development" + }, { "name": "nuxt-ui", "source": { diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e27e5b84..b5ecc491 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -98,6 +98,14 @@ "tags": ["mcp", "database"], "source": "./plugins/neo4j" }, + { + "name": "codegraph", + "description": "Local-first code intelligence for AI agents (MCP) - query a pre-indexed knowledge graph of symbols, call graphs, and code structure instead of scanning files", + "category": "development", + "keywords": ["code-intelligence", "knowledge-graph", "code-navigation", "semantic-search"], + "tags": ["mcp", "code-intelligence"], + "source": "./plugins/codegraph" + }, { "name": "chrome-devtools-mcp", "description": "Control and inspect a live Chrome browser through MCP - automate actions, debug, and analyze performance using Chrome DevTools", diff --git a/plugins/codegraph/.claude-plugin/plugin.json b/plugins/codegraph/.claude-plugin/plugin.json new file mode 100644 index 00000000..65be19ed --- /dev/null +++ b/plugins/codegraph/.claude-plugin/plugin.json @@ -0,0 +1,20 @@ +{ + "name": "codegraph", + "version": "1.0.1", + "description": "Local-first code intelligence for AI agents (MCP) - query a pre-indexed knowledge graph of symbols, call graphs, and code structure instead of scanning files", + "author": { + "name": "Colby McHenry", + "url": "https://github.com/colbymchenry" + }, + "homepage": "https://github.com/colbymchenry/codegraph", + "repository": "https://github.com/colbymchenry/codegraph", + "license": "MIT", + "keywords": ["code-intelligence", "knowledge-graph", "code-navigation", "semantic-search", "local-first"], + "mcpServers": { + "codegraph": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@colbymchenry/codegraph", "serve", "--mcp"] + } + } +} diff --git a/plugins/codegraph/.codex-plugin/plugin.json b/plugins/codegraph/.codex-plugin/plugin.json new file mode 100644 index 00000000..ec995462 --- /dev/null +++ b/plugins/codegraph/.codex-plugin/plugin.json @@ -0,0 +1,34 @@ +{ + "name": "codegraph", + "version": "1.0.1", + "description": "Local-first code intelligence for AI agents (MCP) - query a pre-indexed knowledge graph of symbols, call graphs, and code structure instead of scanning files", + "author": { + "name": "Colby McHenry", + "url": "https://github.com/colbymchenry" + }, + "interface": { + "displayName": "Codegraph", + "shortDescription": "Local-first code intelligence for AI agents (MCP) - query a pre-indexed knowledge graph of symbols, call graphs, and code structure instead of scanning files", + "longDescription": "Local-first code intelligence for AI agents (MCP) - query a pre-indexed knowledge graph of symbols, call graphs, and code structure instead of scanning files", + "developerName": "Colby McHenry", + "category": "Development", + "capabilities": [ + "Tool" + ], + "defaultPrompt": [ + "Use Codegraph for my current task." + ], + "websiteURL": "https://github.com/colbymchenry/codegraph" + }, + "homepage": "https://github.com/colbymchenry/codegraph", + "repository": "https://github.com/colbymchenry/codegraph", + "license": "MIT", + "keywords": [ + "code-intelligence", + "knowledge-graph", + "code-navigation", + "semantic-search", + "local-first" + ], + "mcpServers": "./.mcp.json" +} diff --git a/plugins/codegraph/.mcp.json b/plugins/codegraph/.mcp.json new file mode 100644 index 00000000..f2d6b401 --- /dev/null +++ b/plugins/codegraph/.mcp.json @@ -0,0 +1,14 @@ +{ + "mcpServers": { + "codegraph": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@colbymchenry/codegraph", + "serve", + "--mcp" + ] + } + } +} diff --git a/plugins/codegraph/hooks.json b/plugins/codegraph/hooks.json new file mode 100644 index 00000000..f2dd55ee --- /dev/null +++ b/plugins/codegraph/hooks.json @@ -0,0 +1,17 @@ +{ + "description": "Inject CodeGraph navigation guidance at session start when the repo is indexed (a .codegraph/ directory exists)", + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/context.sh", + "timeout": 10 + } + ] + } + ] + } +} diff --git a/plugins/codegraph/hooks/context.sh b/plugins/codegraph/hooks/context.sh new file mode 100755 index 00000000..0ab446e9 --- /dev/null +++ b/plugins/codegraph/hooks/context.sh @@ -0,0 +1,22 @@ +#!/usr/bin/env bash +# Emit CodeGraph navigation guidance ONLY when the current project is indexed +# (a `.codegraph/` directory exists at the repo root). In an unindexed repo we +# stay silent — indexing is the user's decision, and an unconditional "this +# repo is indexed" claim would send subagents into failing codegraph calls. +# +# The wording mirrors CodeGraph's own marker-fenced instructions block, which +# exists because the MCP server's `initialize` instructions reach only the main +# agent — Task-tool subagents and non-MCP harnesses see this context instead. + +if [ ! -d ".codegraph" ]; then + exit 0 +fi + +cat <<'EOF' +## CodeGraph + +This repository is indexed by CodeGraph (a `.codegraph/` directory exists). Reach for it BEFORE grep/find or reading files when you need to understand or locate code: + +- **MCP tools** (when available): `codegraph_explore` answers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them. `codegraph_node` returns one symbol's source + callers, or reads a whole file with line numbers. If the tools are listed but deferred, load them by name via tool search. +- **Shell** (always works): `codegraph explore ""` and `codegraph node ` print the same output — useful for subagents or harnesses without an MCP client. +EOF diff --git a/plugins/codegraph/hooks/hooks.json b/plugins/codegraph/hooks/hooks.json new file mode 100644 index 00000000..f2dd55ee --- /dev/null +++ b/plugins/codegraph/hooks/hooks.json @@ -0,0 +1,17 @@ +{ + "description": "Inject CodeGraph navigation guidance at session start when the repo is indexed (a .codegraph/ directory exists)", + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/context.sh", + "timeout": 10 + } + ] + } + ] + } +} diff --git a/plugins/codegraph/mcp_config.json b/plugins/codegraph/mcp_config.json new file mode 100644 index 00000000..f2d6b401 --- /dev/null +++ b/plugins/codegraph/mcp_config.json @@ -0,0 +1,14 @@ +{ + "mcpServers": { + "codegraph": { + "type": "stdio", + "command": "npx", + "args": [ + "-y", + "@colbymchenry/codegraph", + "serve", + "--mcp" + ] + } + } +} diff --git a/plugins/codegraph/plugin.json b/plugins/codegraph/plugin.json new file mode 100644 index 00000000..66316f78 --- /dev/null +++ b/plugins/codegraph/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "codegraph", + "version": "1.0.1", + "description": "Local-first code intelligence for AI agents (MCP) - query a pre-indexed knowledge graph of symbols, call graphs, and code structure instead of scanning files", + "author": { + "name": "Colby McHenry", + "url": "https://github.com/colbymchenry" + }, + "homepage": "https://github.com/colbymchenry/codegraph", + "repository": "https://github.com/colbymchenry/codegraph", + "license": "MIT", + "keywords": [ + "code-intelligence", + "knowledge-graph", + "code-navigation", + "semantic-search", + "local-first" + ] +} diff --git a/plugins/codegraph/skills/codegraph/SKILL.md b/plugins/codegraph/skills/codegraph/SKILL.md new file mode 100644 index 00000000..46f77af7 --- /dev/null +++ b/plugins/codegraph/skills/codegraph/SKILL.md @@ -0,0 +1,54 @@ +--- +name: Navigating Codebases with CodeGraph +description: Query a pre-indexed knowledge graph of a codebase (symbols, call graphs, dependencies, impact) instead of scanning files with grep/glob/Read. Use when exploring an unfamiliar codebase, tracing who calls or is called by a function, assessing the blast radius of a change, finding where a symbol is defined or used, or answering architecture questions. Triggers on mentions of code navigation, call graph, callers, callees, impact analysis, symbol search, or understanding code structure. +allowed-tools: mcp__codegraph__codegraph_search, mcp__codegraph__codegraph_explore, mcp__codegraph__codegraph_callers, mcp__codegraph__codegraph_callees, mcp__codegraph__codegraph_impact, mcp__codegraph__codegraph_node, mcp__codegraph__codegraph_status, mcp__codegraph__codegraph_files +--- + +# CodeGraph - Local Code Intelligence + +CodeGraph gives you a pre-indexed knowledge graph of the current project — symbol +relationships, call graphs, and code structure — so you can answer questions +instantly instead of consuming tokens scanning files with grep, glob, and Read. + +## When to Use + +**First check:** CodeGraph applies only in repositories it has indexed — a +`.codegraph/` directory exists at the repo root. If there is no `.codegraph/` +directory, skip CodeGraph entirely; indexing is the user's decision (suggest +`codegraph init` only if they want it). + +In an indexed repo, reach for CodeGraph **before** grep/find or reading files when +you need to understand or locate code: + +- **Explore / answer most code questions** in one call → `codegraph_explore` + (returns the relevant symbols' verbatim source plus the call paths between them) +- **Inspect one symbol** (source + callers) or read a whole file with line numbers + → `codegraph_node` +- **Search** for a symbol, type, or concept by name/intent → `codegraph_search` +- **Trace callers** — who invokes this function/method? → `codegraph_callers` +- **Trace callees** — what does this function call? → `codegraph_callees` +- **Assess impact / blast radius** of changing a symbol → `codegraph_impact` +- **List indexed files** in the project → `codegraph_files` +- **Check index health / freshness** → `codegraph_status` + +## How to Use + +1. For broad questions ("how does X work?", "where is auth handled?"), start with + `codegraph_explore` — it answers most code questions in a single call. +2. To navigate relationships from a known symbol, use `codegraph_node`, then + `codegraph_callers` / `codegraph_callees`. +3. Before refactoring or renaming, run `codegraph_impact` to find everything affected. +4. If the MCP tools are listed but deferred, load them by name via tool search. +5. **Shell fallback (always works):** `codegraph explore ""` + and `codegraph node ` print the same output as the MCP tools — + useful for subagents or harnesses without an MCP client. +6. If a tool response shows a `⚠️` staleness banner naming a file, `Read` that file + directly for live content — it was edited within the sync debounce window. + +## Important Notes + +- **Indexing is per-project**, signalled by the `.codegraph/` directory. No + `.codegraph/` → don't call CodeGraph tools. +- **100% local.** No code leaves the machine; the server bundles its own runtime. +- The index auto-syncs on file changes via a native file watcher, so results stay + current as the codebase evolves. From bf1b5295a20a7987dbe7a1603ead9a59abccca6f Mon Sep 17 00:00:00 2001 From: Minsu Lee Date: Tue, 16 Jun 2026 01:48:55 +0900 Subject: [PATCH 2/2] chore(codegraph): apply AI code review suggestions - context.sh: detect .codegraph/ at the repo root even when the session starts in a subdirectory (git rev-parse, then upward walk, then CWD) so guidance is not silently suppressed in monorepos - shell fallback: use npx -y @colbymchenry/codegraph in context.sh and SKILL.md so the fallback is portable without a global codegraph install --- plugins/codegraph/hooks/context.sh | 21 +++++++++++++++++++-- plugins/codegraph/skills/codegraph/SKILL.md | 7 ++++--- 2 files changed, 23 insertions(+), 5 deletions(-) diff --git a/plugins/codegraph/hooks/context.sh b/plugins/codegraph/hooks/context.sh index 0ab446e9..604b89c2 100755 --- a/plugins/codegraph/hooks/context.sh +++ b/plugins/codegraph/hooks/context.sh @@ -8,7 +8,24 @@ # exists because the MCP server's `initialize` instructions reach only the main # agent — Task-tool subagents and non-MCP harnesses see this context instead. -if [ ! -d ".codegraph" ]; then +# Locate the indexed root. A SessionStart hook usually runs at the repo root, +# but if the session starts in a subdirectory (common in monorepos) a bare CWD +# check would miss a `.codegraph/` at the root. Prefer the git repo root, fall +# back to an upward walk for `.codegraph/`, then the CWD. +root="$(git rev-parse --show-toplevel 2>/dev/null)" +if [ -z "$root" ]; then + dir="$PWD" + while [ "$dir" != "/" ]; do + if [ -d "$dir/.codegraph" ]; then + root="$dir" + break + fi + dir="$(dirname "$dir")" + done +fi +: "${root:=$PWD}" + +if [ ! -d "$root/.codegraph" ]; then exit 0 fi @@ -18,5 +35,5 @@ cat <<'EOF' This repository is indexed by CodeGraph (a `.codegraph/` directory exists). Reach for it BEFORE grep/find or reading files when you need to understand or locate code: - **MCP tools** (when available): `codegraph_explore` answers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them. `codegraph_node` returns one symbol's source + callers, or reads a whole file with line numbers. If the tools are listed but deferred, load them by name via tool search. -- **Shell** (always works): `codegraph explore ""` and `codegraph node ` print the same output — useful for subagents or harnesses without an MCP client. +- **Shell** (no MCP client needed): `npx -y @colbymchenry/codegraph explore ""` and `npx -y @colbymchenry/codegraph node ` print the same output — portable even without a global `codegraph` install (drop the `npx -y @colbymchenry/` prefix if the CLI is on your PATH). EOF diff --git a/plugins/codegraph/skills/codegraph/SKILL.md b/plugins/codegraph/skills/codegraph/SKILL.md index 46f77af7..ba40344b 100644 --- a/plugins/codegraph/skills/codegraph/SKILL.md +++ b/plugins/codegraph/skills/codegraph/SKILL.md @@ -39,9 +39,10 @@ you need to understand or locate code: `codegraph_callers` / `codegraph_callees`. 3. Before refactoring or renaming, run `codegraph_impact` to find everything affected. 4. If the MCP tools are listed but deferred, load them by name via tool search. -5. **Shell fallback (always works):** `codegraph explore ""` - and `codegraph node ` print the same output as the MCP tools — - useful for subagents or harnesses without an MCP client. +5. **Shell fallback (no MCP client needed):** `npx -y @colbymchenry/codegraph explore ""` + and `npx -y @colbymchenry/codegraph node ` print the same output as + the MCP tools — portable even without a global `codegraph` install (drop the + `npx -y @colbymchenry/` prefix if the CLI is on your PATH). 6. If a tool response shows a `⚠️` staleness banner naming a file, `Read` that file directly for live content — it was edited within the sync debounce window.