Codebase Exploration

Delegates to the Explore agent for fast, read-only investigation of the codebase.

Standalone Codex

Claude frontmatter does not enforce a fork or tool restriction in standalone Codex. Keep this workflow read-only yourself, or use spawn_agent with an explore agent and a read-only prompt. Gather current state by explicitly running pwd, basename "$PWD", ls package.json Cargo.toml go.mod pyproject.toml, and git rev-parse --show-toplevel; the !command lines below are Claude interpolation only.

Codex does not receive TLDR from this package. In broad mode use rg --files, rg -n exact searches, direct import searches, and focused file reads. In upward-zoom mode search the symbol definition and all call sites with rg -n, then trace imports and callers one layer up. Never claim a TLDR MCP ran.

Claude current state

• Directory: !pwd 2>/dev/null
• Project: !basename "$(pwd)" 2>/dev/null
• Stack: !ls package.json Cargo.toml go.mod pyproject.toml 2>/dev/null || echo "unknown"
• Git root: !git rev-parse --show-toplevel 2>/dev/null || echo "not a git repo"

Two modes — pick by what the user asked

Broad investigation mode (default)

Use when the user is asking "how does X work" / "where is X" / "what handles Y" — finding code without a known starting point.

1. Start broad - In Claude use tldr semantic or Glob; in standalone Codex use the native searches above
2. Narrow down - Read specific files to understand implementation
3. Trace connections - In Claude use tldr impact; in standalone Codex trace callers and imports with rg
4. Summarize findings - Return clear, actionable summary

Upward-zoom mode

Use when the user is staring at a known function or module and needs to know how it fits — triggers like "zoom out", "bigger picture", "where does this fit", onboarding unfamiliar code.

1. Follow ../context-doc/DOMAIN-AWARENESS.md — read CONTEXT.md and any relevant ADRs first if they exist.

2. Identify the symbol or file the user is asking about.

3. In Claude, use TLDR for the structural answer:

   tldr context <symbol> --depth 3 --project .
   tldr impact <symbol> --project .
   

4. Synthesize a map: list immediate callers, the modules they live in, and where this area sits in the system. Use CONTEXT.md vocabulary when naming concepts.

5. Stop at one layer up. The user can ask for another zoom-out if they need it.

Upward-zoom output shape:

{Symbol/file in question}
  ↑ called by: {module A}, {module B}
  ↓ depends on: {module C}, {module D}

Where this fits:
{1–2 sentence narrative using CONTEXT.md terms}

Related ADRs:
- ADR-NNNN ({title}) — relevant because…

The point is orientation, not exhaustive coverage.

Output Format (broad mode)

Return a concise summary:

• Location: Key files and their paths
• How it works: Brief explanation of the flow
• Key functions/components: Entry points
• Dependencies: What it relies on
• Suggestions: If the user needs to modify something

Remember

• You are READ-ONLY - do not modify files
• Return summaries, not raw file contents
• Be specific with file paths and line numbers