mondoohq/secure-stack/understand-code

Understand Code

Map and navigate a codebase before changing it, using xgrep's AST-powered code graph and Zoekt-powered text search — so a change starts from understanding, not guesswork.

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 the secure-pipeline skill, or triage-findings for results)
• Creating or modifying detection rules (use author-detections)
• Simple text searches where grep/ripgrep suffice (single keyword in a known file)

Commands Reference

Orient

Locate

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

Assess

Deep Dive (existing graph commands)

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.

Part of the secure-your-stack toolkit

This is the orientation step. Once you start changing code: secure-coding helps write it safely, and secure-pipeline scans it (SAST/SCA/secrets + IaC) before it ships — with triage-findings and fix-findings for the results. A runtime guard (secure-guard mod) runs those checks automatically as an agent works.