xgrep-inspect

name	xgrep-inspect
description	Investigates and navigates source code using xgrep's AST-powered code intelligence. Use when exploring unfamiliar code, finding definitions/references, understanding dependencies, or assessing change impact.
allowed-tools	Bash Read Glob Grep

xgrep Code Intelligence

Navigate and understand source code using xgrep's AST-powered code graph and Zoekt-powered text search.

When to Use

• Exploring an unfamiliar codebase ("what does this project do?", "what are the main components?")
• Finding code ("where is X defined?", "who calls Y?", "find all implementations of Z")
• Understanding relationships ("what does this function depend on?", "trace this call chain")
• Assessing change impact ("what breaks if I change this?", "what's the blast radius?")
• Getting a file overview before reading it line by line

When NOT to Use

• Running security scans (use xgrep scan or /xgrep-triage)
• Creating or modifying rules (use /xgrep-rule)
• Simple text searches where grep/ripgrep suffice (single keyword in a known file)

Commands Reference

Orient

Command	Purpose
xgrep inspect overview [dir]	Codebase summary: languages, packages, entry points, key types

Locate

Command	Purpose
xgrep inspect symbol <query> [--kind K]	Search symbols by name (exact, prefix, substring)
xgrep inspect search <query> [--lang L] [--regex]	Fast trigram-indexed text search (Zoekt)

Locating is lexical (a name or a string the code contains), not semantic — there is no search-by-meaning. When you only know what the code does, not its name: run overview first to learn the real vocabulary, then symbol/search those terms (expanding synonyms yourself, e.g. auth → session/credential/login), then references/deps to traverse to the target. This is faster and more precise than guessing patterns with grep.

Navigate

Command	Purpose
xgrep inspect definition --file F --line N	Find symbol definition at position
xgrep inspect hover --file F --line N	Doc comment, type info, params (tooltip)
xgrep inspect ranges <file> --start S --end E	All symbols in a line range (bulk)
xgrep inspect references <name>	Find all callers, callees, references
xgrep inspect implementations <name>	Find interface implementations
xgrep inspect outline <file>	List all symbols in a file

Assess

Command	Purpose
xgrep inspect impact <name>	Blast radius: callers, callees, affected files, risk score
xgrep inspect deps <name> [--depth N]	Call dependencies: upstream callers, downstream callees

Deep Dive (existing graph commands)

Command	Purpose
xgrep graph context <name> --depth N	N-hop neighborhood with inlined source
xgrep graph paths <src> <dst>	Call paths between two functions
xgrep graph callers <name>	Direct callers
xgrep graph callees <name>	Direct callees

Output Formats

All inspect commands support --json for machine-readable output. Without --json, output is human-readable text.

Caching

• Code graph cached to .xgrep/graph.json — incremental rebuild via file mtimes (~0.3s when fresh)
• Search index cached to .xgrep/search/ — full Zoekt trigram index, skipped when fresh (~0.1s)
• Both are built automatically on first use — no setup needed

Supported Languages

xgrep uses tree-sitter for AST parsing. Full symbol extraction (variables, fields, constants, imports, doc comments, visibility) for:

• Go: functions, methods, types, struct fields, variables, constants, imports
• Python: functions, classes, attributes, module variables, constants, imports
• JavaScript/TypeScript: functions, classes, fields, variables, constants, imports

Basic extraction (functions, classes, call edges) for 30+ additional languages.