Codegraph

# Codegraph

## When to use this skill

Use Codegraph when the user asks structural questions about a repository and plain text search would be too shallow. Codegraph builds dependency graphs, symbol indexes, go-to-definition maps, find-references results, semantic chunks, and PR impact reports across many source languages plus graph-first document and template formats.

Strong triggers for this skill:

- "Understand this repo", "map this codebase", "show me the architecture", or "where should I start?"
- "What depends on this file?", "what imports this?", "what is the dependency path?", or "are there cycles?"
- "Where is this symbol defined?", "where is this used?", or "find references to this function/class/type."
- "What changed in this PR?", "what could this diff break?", or "which tests are likely relevant?"
- "Find hotspots", "inspect the public API surface", or "chunk this file for agent context."

Prefer Codegraph over `rg` when import edges, exported symbols, lexical scope, dependency direction, or PR impact matter. Use `rg` alongside Codegraph for raw text patterns, logs, configuration keys, or strings that are not code symbols.

Do not use Codegraph as the only evidence source for secrets, literal strings, log text, generated artifacts, or runtime behavior. Pair it with text search, tests, or execution evidence for those questions.

## First move for agents

For an unfamiliar repo, start with a health check and a bounded orientation packet. Use `./src` when it exists; otherwise use the product-code directory or `.` for a whole-repo fallback.

```bash
codegraph doctor
codegraph orient --root . --budget small --json
```

Then choose the narrowest follow-up command:

- Architecture summary: `codegraph inspect ./src --limit 20`
- Packet follow-up: `codegraph packet get <handle-from-orient> --json`
- Hot files: `codegraph hotspots ./src --limit 20 --json`
- Search anchors: `codegraph search "auth user" --json`
- Explain an anchor: `codegraph explain <file|symbol|sql-object|search-handle> --json`
- Smaller large-file packet: `codegraph explain <file> --max-symbols 25 --json`
- Dependencies: `codegraph deps <file>`
- Reverse dependencies: `codegraph rdeps <file>`
- Dependency path: `codegraph path <from> <to>`
- Cycles: `codegraph cycles --sort priority --json`
- Go to definition: `codegraph goto <file> <line> <column>`
- Find references: `codegraph refs --file <file> --line <line> --col <column> --pretty`
- PR impact: `codegraph impact --provider git --base main --head HEAD --pretty`
- Worktree impact: `codegraph impact --provider git --base HEAD --head WORKTREE --pretty`
- Review handoff: `codegraph review --base HEAD --head WORKTREE --summary`
- Full review JSON: `codegraph review --base origin/main --head HEAD`
- Architecture drift: `codegraph drift ./src --base origin/main --head HEAD --pretty --graph-edges summary --public-api removals`
- Public API: `codegraph apisurface`
- Duplicate cleanup: `codegraph duplicates --root . ./src --min-confidence medium`
- Chunks: `codegraph chunk <file>`
- Artifact bundle: `codegraph artifact build --root . --out codegraph-out --json`
- MCP server: configure it in the agent/client MCP config; use MCP tools when they are already available.

For `orient`, positional paths are include roots even when there is only one positional. Use `--root /path/to/repo` when targeting a different project root.

## Prefer MCP When Available

Use Codegraph MCP tools when they are already available in the agent runtime. MCP keeps a warm project session and is better for repeated navigation than spawning separate CLI commands.

- Start with MCP `orient` for repo context.
- Use `search` for anchors and `packet_get` for bounded evidence pa