repo-explorer

Repo Explorer

Launch a separate Claude Code CLI process (claude -p --model haiku) with read-only tools to explore a repository and answer questions about it. Supports both local repositories and remote URLs.

Workflow

1. Determine repo source and question

From the user's message extract:

• source: one of:
  • local path (~/projects/foo, /opt/services/bar, . or omitted = cwd)
  • remote URL (https://github.com/owner/repo, [email protected]:owner/repo.git)
  • shorthand (owner/repo — treat as https://github.com/owner/repo)
• question: what to find out about the repository.

2. For remote repos — clone to temp directory

If the source is a remote URL or shorthand, clone it first:

REPO_DIR=$(mktemp -d) && git clone --depth 1 <url> "$REPO_DIR" && echo "$REPO_DIR"

• Use --depth 1 for speed (shallow clone, only latest commit)
• If the user asks about a specific branch/tag: git clone --depth 1 --branch <ref> <url> "$REPO_DIR"
• Store $REPO_DIR to clean up later

3. Run the CLI command

Use the Bash tool with timeout: 600000 (10 min) since exploration of large repos can take several minutes.

cd <repo_path> && CLAUDECODE= claude -p "<question>" \
  --model haiku \
  --output-format text \
  --max-turns 15 \
  --allowedTools "Read" "Grep" "Glob" "Bash(find *)" "Bash(ls *)" "Bash(wc *)" "Bash(git log *)" "Bash(git show *)" "Bash(git diff *)" "Bash(git branch *)" "Bash(head *)" "Bash(tail *)" \
  --append-system-prompt "You are a code exploration expert. Thoroughly explore the repository to answer the user's question. Strategy: 1) Glob to discover project structure. 2) Grep to find patterns, definitions, routes, classes. 3) Read to examine key files. Always cite file paths and line numbers. Give a structured answer based on code facts."

IMPORTANT: The CLAUDECODE= prefix (setting the env var to empty) is required to allow launching Claude Code as a subprocess. Without it, the nested session will be blocked.

Rules:

• Always include CLAUDECODE= directly before claude -p (no &&, it's an inline env override)
• Escape double quotes in the question with \"
• Wrap repo paths containing spaces in quotes
• For very large repos, increase --max-turns to 25
• If user explicitly requests sonnet or opus, replace --model haiku

4. Clean up (remote repos only)

After presenting the result, remove the temp directory:

rm -rf "$REPO_DIR"

5. Present the result

Display the CLI output to the user. If empty or error, report the issue and suggest retrying with a more specific question.

Examples

Local repo:

cd ~/projects/my-api && CLAUDECODE= claude -p "What REST endpoints are defined? List each with HTTP method, path, and handler." --model haiku --output-format text --max-turns 15 --allowedTools "Read" "Grep" "Glob" "Bash(find *)" "Bash(ls *)" "Bash(wc *)" "Bash(git log *)" "Bash(git show *)" "Bash(git diff *)" "Bash(git branch *)" "Bash(head *)" "Bash(tail *)" --append-system-prompt "You are a code exploration expert. Thoroughly explore the repository to answer the user's question. Strategy: 1) Glob to discover project structure. 2) Grep to find patterns, definitions, routes, classes. 3) Read to examine key files. Always cite file paths and line numbers. Give a structured answer based on code facts."

Remote repo (GitHub URL):

REPO_DIR=$(mktemp -d) && git clone --depth 1 https://github.com/expressjs/express "$REPO_DIR"

Then:

cd "$REPO_DIR" && CLAUDECODE= claude -p "How is routing implemented? Describe the Router class and middleware chain." --model haiku --output-format text --max-turns 15 --allowedTools "Read" "Grep" "Glob" "Bash(find *)" "Bash(ls *)" "Bash(wc *)" "Bash(git log *)" "Bash(git show *)" "Bash(git diff *)" "Bash(git branch *)" "Bash(head *)" "Bash(tail *)" --append-system-prompt "You are a code exploration expert. Thoroughly explore the repository to answer the user's question. Strategy: 1) Glob to discover project structure. 2) Grep to find patterns, definitions, routes, classes. 3) Read to examine key files. Always cite file paths and line numbers. Give a structured answer based on code facts."

Then: rm -rf "$REPO_DIR"

Shorthand (owner/repo): treat vercel/next.js as https://github.com/vercel/next.js.

Current directory (no path): run claude -p without cd.