repo-explorer

# Repo Explorer

Launch a separate Claude Code CLI process (`claude -p`) 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, question, and model

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.
- **model** — pick by task type, not by habit:
  - **`haiku`** — mechanical lookup, where the answer is *located* in the code and just needs
    finding: "what endpoints exist", "where is X defined", "list the migrations", structure
    inventory, "does this repo use Y".
  - **`sonnet`** — analytical work, where the answer must be *judged*, not just found: "what can we
    learn/borrow from this repo", applicability assessment, design/architecture review, comparing
    approaches, security analysis, "what's original here", trade-off summaries. Cue words: оцени,
    что полезного, идеи, применимость, review, compare, learn from.
  - A cheap model on an analytical question produces shallow results with flattened nuances that
    cost more to verify than the tokens saved — this rule exists because it happened.
  - An explicit user request ("use haiku", "запусти sonnet", opus) always overrides the heuristic.

### 2. For remote repos — clone to temp directory

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

```bash
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|sonnet per step 1> \
  --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 or analytical (sonnet) runs, increase `--max-turns` to 25
- Model follows the step 1 heuristic (haiku = lookup, sonnet = analysis); an explicit user request
  always wins

### 4. Clean up (remote repos only)

After presenting the result, remove the temp directory:

```bash
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 (lookup → haiku):**
```
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 (analysis → sonnet):**
```bash
REPO_DIR=$(mktemp -d) && git clone --depth 1 https://github.com/expressjs/express "$REPO_DIR"
```
Then:
```
cd "$REPO_DIR" && CLAUDECODE= claude -p "Assess the middleware chain design: what patterns are worth borrowing for our own router, and what are the known trade-offs?" --model sonnet --output-format text --max-turns 25 --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`.