Merge pull request #48 from optave/docs/ai-agent-guide

docs: add AI Agent Guide and dogfood recommended practices

Author: carlos-alm

.claude/hooks/remind-codegraph.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# remind-codegraph.sh — PreToolUse hook for Edit|Write
+# Reminds the agent to use codegraph before editing a file.
+# Only fires once per file per session (tracks in .claude/codegraph-checked.log).
+
+set -euo pipefail
+
+# Extract file_path from tool input
+INPUT="${TOOL_INPUT:-}"
+FILE_PATH=$(echo "$INPUT" | node -e "
+  let d=''; process.stdin.on('data',c=>d+=c);
+  process.stdin.on('end',()=>{
+    try {
+      const j=JSON.parse(d);
+      const p = j.file_path || j.path || '';
+      // Normalize backslashes
+      console.log(p.replace(/\\\\/g,'/'));
+    } catch { console.log(''); }
+  });
+" 2>/dev/null)
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Normalize to relative path
+REL_PATH="$FILE_PATH"
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+  REL_PATH=$(node -e "
+    const path = require('path');
+    const abs = path.resolve(process.argv[1]);
+    const base = path.resolve(process.argv[2]);
+    console.log(path.relative(base, abs).replace(/\\\\/g,'/'));
+  " "$FILE_PATH" "$CLAUDE_PROJECT_DIR" 2>/dev/null) || REL_PATH="$FILE_PATH"
+fi
+
+# Skip non-source files (docs, config, etc.)
+case "$REL_PATH" in
+  *.md|*.json|*.yml|*.yaml|*.toml|*.txt|*.lock|*.log|*.env*) exit 0 ;;
+esac
+
+# Check if we already reminded for this file
+CHECKED_LOG="${CLAUDE_PROJECT_DIR:-.}/.claude/codegraph-checked.log"
+if [ -f "$CHECKED_LOG" ] && grep -qF "$REL_PATH" "$CHECKED_LOG" 2>/dev/null; then
+  exit 0
+fi
+
+# Record that we've reminded for this file
+mkdir -p "$(dirname "$CHECKED_LOG")"
+echo "$REL_PATH" >> "$CHECKED_LOG"
+
+# Check if graph exists
+if [ ! -f "${CLAUDE_PROJECT_DIR:-.}/.codegraph/graph.db" ]; then
+  exit 0
+fi
+
+# Inject reminder as additionalContext
+cat <<HOOK_OUTPUT
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "additionalContext": "[codegraph reminder] You are about to edit ${REL_PATH}. Did you run codegraph first? Before editing, always: (1) 'node src/cli.js where <name>' to locate the symbol, (2) 'node src/cli.js explain ${REL_PATH}' to understand the file, (3) 'node src/cli.js context <name> -T' for full context, (4) 'node src/cli.js fn-impact <name> -T' to check blast radius. If you already did this, proceed."
+  }
+}
+HOOK_OUTPUT

.claude/settings.json

@@ -35,6 +35,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/remind-codegraph.sh\"",
+            "timeout": 5
+          }
+        ]
       }
     ],
     "PostToolUse": [

.github/workflows/codegraph-impact.yml

@@ -11,10 +11,15 @@ jobs:
         with:
           node-version: '22'
       - run: npm install
+      - uses: actions/cache@v4
+        with:
+          path: .codegraph/
+          key: codegraph-${{ hashFiles('src/**', 'package.json') }}
+          restore-keys: codegraph-
       - run: npx codegraph build
       - name: Run impact analysis
         run: |
-          npx codegraph diff-impact --ref origin/${{ github.base_ref }} --json > impact.json || echo '{"affectedFiles":[],"summary":null}' > impact.json
+          npx codegraph diff-impact --ref origin/${{ github.base_ref }} --json -T > impact.json || echo '{"affectedFiles":[],"summary":null}' > impact.json
       - name: Comment on PR
         uses: actions/github-script@v8
         with:

.github/workflows/shield-license-compliance.yml

@@ -8,9 +8,6 @@ on:
       - "package-lock.json"
   pull_request:
     branches: [main]
-    paths:
-      - "package.json"
-      - "package-lock.json"
   workflow_dispatch:
   schedule:
     - cron: "0 3 * * 1" # Weekly on Monday at 3 AM

.gitignore

@@ -4,5 +4,7 @@ node_modules/
 coverage/
 .env
 grammars/*.wasm
+.claude/session-edits.log
+.claude/codegraph-checked.log
 artifacts/
 pkg/

.husky/commit-msg

@@ -1 +1,20 @@
 npx --no -- commitlint --edit $1
+
+# Append codegraph impact summary if available
+IMPACT=$(codegraph diff-impact --staged --json -T 2>/dev/null || node src/cli.js diff-impact --staged --json -T 2>/dev/null)
+if [ -n "$IMPACT" ]; then
+  SUMMARY=$(echo "$IMPACT" | node -e "
+    let d=''; process.stdin.on('data',c=>d+=c);
+    process.stdin.on('end',()=>{
+      try {
+        const j=JSON.parse(d);
+        if(j.summary && j.summary.functionsChanged > 0)
+          console.log('Impact: '+j.summary.functionsChanged+' functions changed, '+(j.summary.totalAffected||j.summary.callersAffected||0)+' affected');
+      } catch {}
+    });
+  " 2>/dev/null)
+  if [ -n "$SUMMARY" ]; then
+    echo "" >> "$1"
+    echo "$SUMMARY" >> "$1"
+  fi
+fi

.husky/pre-commit

@@ -1 +1,2 @@
 npm run lint
+codegraph build 2>/dev/null || node src/cli.js build . 2>/dev/null || true

.husky/pre-push

@@ -0,0 +1,14 @@
+IMPACT=$(codegraph diff-impact origin/main --json -T 2>/dev/null || node src/cli.js diff-impact origin/main --json -T 2>/dev/null)
+if [ -n "$IMPACT" ]; then
+  AFFECTED=$(echo "$IMPACT" | node -e "
+    let d=''; process.stdin.on('data',c=>d+=c);
+    process.stdin.on('end',()=>{
+      try { console.log(JSON.parse(d).summary?.totalAffected||0); }
+      catch { console.log(0); }
+    });
+  ")
+  if [ "$AFFECTED" -gt 50 ]; then
+    echo "Warning: pushing changes that affect $AFFECTED functions"
+    echo "Run 'codegraph diff-impact origin/main -T' to review"
+  fi
+fi

CLAUDE.md

@@ -2,6 +2,8 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+> **Use codegraph before editing code.** This project has a pre-built dependency graph at `.codegraph/graph.db`. Before modifying any function or file, run `node src/cli.js where <name>` to locate it, `node src/cli.js explain <target>` to understand the structure, `node src/cli.js context <name> -T` to gather full context, and `node src/cli.js fn-impact <name> -T` to check blast radius. After staging changes, run `node src/cli.js diff-impact --staged -T` to verify impact. This saves tokens, prevents blind edits, and catches breakage before it happens. See the [Dogfooding](#dogfooding--codegraph-on-itself) section for the full command reference.
+
 ## Project Overview
 
 Codegraph (`@optave/codegraph`) is a local code dependency graph CLI. It parses codebases with tree-sitter (WASM), builds function-level dependency graphs stored in SQLite, and supports semantic search with local embeddings. No cloud services required.
@@ -97,18 +99,34 @@ The workflow can be overridden with a specific version via the `version-override
 
 ## Dogfooding — codegraph on itself
 
-Codegraph is **our own tool**. Use it to analyze this repository before making changes:
+Codegraph is **our own tool**. Use it to analyze this repository before making changes. If codegraph reports an error, crashes, or produces wrong results when analyzing itself, **fix the bug in the codebase** — don't just work around it.
+
+### Before modifying code, always:
+1. `node src/cli.js where <name>` — find where the symbol lives
+2. `node src/cli.js explain <file-or-function>` — understand the structure
+3. `node src/cli.js context <name> -T` — get full context (source, deps, callers)
+4. `node src/cli.js fn-impact <name> -T` — check blast radius before editing
+
+### After modifying code:
+5. `node src/cli.js diff-impact --staged -T` — verify impact before committing
 
+### Other useful commands
 ```bash
-node src/cli.js build .              # Build/update the graph
+node src/cli.js build .              # Build/update the graph (incremental)
+node src/cli.js map --limit 20       # Module overview & most-connected nodes
+node src/cli.js stats                # Graph health and quality score
+node src/cli.js fn <name> -T         # Function call chain (callers + callees)
+node src/cli.js deps src/<file>.js   # File-level imports and importers
+node src/cli.js diff-impact main     # Impact of current branch vs main
 node src/cli.js cycles               # Check for circular dependencies
-node src/cli.js map --limit 20       # Module overview & coupling hotspots
-node src/cli.js diff-impact main     # See impact of current branch changes
-node src/cli.js fn <name>            # Trace function-level dependency chains
-node src/cli.js deps src/<file>.js   # See what imports/depends on a file
+node src/cli.js search "<query>"     # Semantic search (requires `embed` first)
 ```
 
-If codegraph reports an error, crashes, or produces wrong results when analyzing itself, **fix the bug in the codebase** — don't just work around it. This is the best way to find and resolve real issues.
+### Flags
+- `-T` / `--no-tests` — exclude test files (use by default)
+- `-j` / `--json` — JSON output for programmatic use
+- `-f, --file <path>` — scope to a specific file (partial match)
+- `-k, --kind <kind>` — filter by symbol kind (function, method, class, etc.)
 
 ## Parallel Sessions
 

README.md

@@ -93,7 +93,7 @@ Most code graph tools make you choose: **fast local analysis with no AI, or powe
 | **⚡** | **Always-fresh graph** | Three-tier change detection: journal (O(changed)) → mtime+size (O(n) stats) → hash (O(changed) reads). Sub-second rebuilds even on large codebases. Competitors re-index everything from scratch; Merkle-tree approaches still require O(n) filesystem scanning |
 | **🔓** | **Zero-cost core, LLM-enhanced when you want** | Full graph analysis with no API keys, no accounts, no cost. Optionally bring your own LLM provider for richer embeddings and AI-powered search — your code only goes to the provider you already chose |
 | **🔬** | **Function-level, not just files** | Traces `handleAuth()` → `validateToken()` → `decryptJWT()` and shows 14 callers across 9 files break if `decryptJWT` changes |
-| **🤖** | **Built for AI agents** | 13-tool [MCP server](https://modelcontextprotocol.io/) — AI assistants query your graph directly. Single-repo by default, your code doesn't leak to other projects |
+| **🤖** | **Built for AI agents** | 17-tool [MCP server](https://modelcontextprotocol.io/) — AI assistants query your graph directly. Single-repo by default, your code doesn't leak to other projects |
 | **🌐** | **Multi-language, one CLI** | JS/TS + Python + Go + Rust + Java + C# + PHP + Ruby + HCL in a single graph — no juggling Madge, pyan, and cflow |
 | **💥** | **Git diff impact** | `codegraph diff-impact` shows changed functions, their callers, and full blast radius — ships with a GitHub Actions workflow |
 | **🧠** | **Semantic search** | Local embeddings by default, LLM-powered embeddings when opted in — multi-query with RRF ranking via `"auth; token; JWT"` |
@@ -132,7 +132,7 @@ Here is a cold, analytical breakdown to help you decide which tool fits your wor
 | Aspect | Optave Codegraph | Narsil-MCP |
 | :--- | :--- | :--- |
 | **Philosophy** | Lean, deterministic, AI-optimized | Comprehensive, feature-dense |
-| **AI Tool Count** | 13 focused tools | 90 distinct tools |
+| **AI Tool Count** | 17 focused tools | 90 distinct tools |
 | **Language Support** | 11 languages | 32 languages |
 | **Primary Interface** | CLI-first with MCP integration | MCP-first (CLI is secondary) |
 | **Supply Chain Risk** | Low (minimal dependency tree) | Higher (requires massive dependency graph for embedded ML/scanners) |
@@ -141,7 +141,7 @@ Here is a cold, analytical breakdown to help you decide which tool fits your wor
 #### Choose Codegraph if:
 
 * **You need the fastest possible incremental rebuilds.** Codegraph’s three-tier change detection (journal → mtime+size → hash) achieves true O(changed) when the watcher is running — only touched files are processed. Narsil’s Merkle trees still require O(n) filesystem scanning to recompute hashes on every rebuild, even when nothing changed. On a 3,000-file project, this is the difference between near-instant and noticeable.
-* **You want to optimize AI agent reasoning.** Large Language Models degrade in performance and hallucinate when overwhelmed with choices. Codegraph’s tight 13-tool surface area ensures agents quickly understand their capabilities without wasting context window tokens.
+* **You want to optimize AI agent reasoning.** Large Language Models degrade in performance and hallucinate when overwhelmed with choices. Codegraph’s tight 17-tool surface area ensures agents quickly understand their capabilities without wasting context window tokens.
 * **You are concerned about supply chain attacks.** To support 90 tools, SBOMs, and neural embeddings, a tool must pull in a massive dependency tree. Codegraph keeps its dependencies minimal, dramatically reducing the risk of malicious code sneaking onto your machine.
 * **You want deterministic blast-radius checks.** Features like `diff-impact` are built specifically to tell you exactly how a changed function cascades through your codebase before you merge a PR.
 * **You value a strong standalone CLI.** You want to query your code graph locally without necessarily spinning up an AI agent.
@@ -190,7 +190,7 @@ codegraph deps src/index.ts  # file-level import/export map
 | 📤 | **Export** | DOT (Graphviz), Mermaid, and JSON graph export |
 | 🧠 | **Semantic search** | Embeddings-powered natural language search with multi-query RRF ranking |
 | 👀 | **Watch mode** | Incrementally update the graph as files change |
-| 🤖 | **MCP server** | 13-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
+| 🤖 | **MCP server** | 17-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
 | 🔒 | **Your code, your choice** | Zero-cost core with no API keys. Optionally enhance with your LLM provider — your code only goes where you send it |
 
 ## 📦 Commands
@@ -391,7 +391,7 @@ Metrics are normalized per file for cross-version comparability. Times above are
 
 ### MCP Server
 
-Codegraph includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server with 13 tools, so AI assistants can query your dependency graph directly:
+Codegraph includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server with 17 tools, so AI assistants can query your dependency graph directly:
 
 ```bash
 codegraph mcp                  # Single-repo mode (default) — only local project
@@ -405,20 +405,35 @@ codegraph mcp --repos a,b      # Multi-repo with allowlist
 
 ### CLAUDE.md / Agent Instructions
 
-Add this to your project's `CLAUDE.md` to help AI agents use codegraph:
+Add this to your project's `CLAUDE.md` to help AI agents use codegraph (full template in the [AI Agent Guide](docs/ai-agent-guide.md#claudemd-template)):
 
 ```markdown
 ## Code Navigation
 
 This project uses codegraph. The database is at `.codegraph/graph.db`.
 
-- **Before modifying a function**: `codegraph fn <name> --no-tests`
-- **Before modifying a file**: `codegraph deps <file>`
-- **To assess PR impact**: `codegraph diff-impact --no-tests`
-- **To find entry points**: `codegraph map`
-- **To trace breakage**: `codegraph fn-impact <name> --no-tests`
-
-Rebuild after major structural changes: `codegraph build`
+### Before modifying code, always:
+1. `codegraph where <name>` — find where the symbol lives
+2. `codegraph explain <file-or-function>` — understand the structure
+3. `codegraph context <name> -T` — get full context (source, deps, callers)
+4. `codegraph fn-impact <name> -T` — check blast radius before editing
+
+### After modifying code:
+5. `codegraph diff-impact --staged -T` — verify impact before committing
+
+### Other useful commands
+- `codegraph build .` — rebuild the graph (incremental by default)
+- `codegraph map` — module overview
+- `codegraph fn <name> -T` — function call chain
+- `codegraph deps <file>` — file-level dependencies
+- `codegraph search "<query>"` — semantic search (requires `codegraph embed`)
+- `codegraph cycles` — check for circular dependencies
+
+### Flags
+- `-T` / `--no-tests` — exclude test files (use by default)
+- `-j` / `--json` — JSON output for programmatic use
+- `-f, --file <path>` — scope to a specific file
+- `-k, --kind <kind>` — filter by symbol kind
 
 ### Semantic search
 
@@ -456,6 +471,8 @@ See **[docs/recommended-practices.md](docs/recommended-practices.md)** for integ
 - **Developer workflow** — watch mode, explore-before-you-edit, semantic search
 - **Secure credentials** — `apiKeyCommand` with 1Password, Bitwarden, Vault, macOS Keychain, `pass`
 
+For AI-specific integration, see the **[AI Agent Guide](docs/ai-agent-guide.md)** — a comprehensive reference covering the 6-step agent workflow, complete command-to-MCP mapping, Claude Code hooks, and token-saving patterns.
+
 ## 🔁 CI / GitHub Actions
 
 Codegraph ships with a ready-to-use GitHub Actions workflow that comments impact analysis on every pull request.