feat(codegraph): add CodeGraph local code-intelligence plugin

.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": {

.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",

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"]
+    }
+  }
+}

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"
+}

plugins/codegraph/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "codegraph": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@colbymchenry/codegraph",
+        "serve",
+        "--mcp"
+      ]
+    }
+  }
+}

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
+          }
+        ]
+      }
+    ]
+  }
+}

plugins/codegraph/hooks/context.sh

@@ -0,0 +1,39 @@
+#!/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.
+
+# 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
+
+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** (no MCP client needed): `npx -y @colbymchenry/codegraph explore "<symbol names or question>"` and `npx -y @colbymchenry/codegraph node <symbol-or-file>` 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

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
+          }
+        ]
+      }
+    ]
+  }
+}

plugins/codegraph/mcp_config.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "codegraph": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@colbymchenry/codegraph",
+        "serve",
+        "--mcp"
+      ]
+    }
+  }
+}

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"
+  ]
+}

plugins/codegraph/skills/codegraph/SKILL.md

@@ -0,0 +1,55 @@
+---
+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 (no MCP client needed):** `npx -y @colbymchenry/codegraph explore "<symbols or question>"`
+   and `npx -y @colbymchenry/codegraph node <symbol-or-file>` 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.
+
+## 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.