repomix

# Repomix — Codebase Packer & Analyzer

Pack entire codebases into a single, AI-friendly file for analysis. Repomix intelligently collects repository files, respects `.gitignore`, runs security checks, and generates structured output optimized for LLM consumption.

## When to Use

- "Analyze this repo" / "Explore this codebase"
- "What's the structure of facebook/react?"
- "Find all authentication-related code"
- "How many tokens is this project?"
- "Pack this repo for AI analysis"
- "Show me the main components of vercel/next.js"

## Quick Reference

### Pack a Remote Repository

```bash
npx repomix@latest --remote <owner/repo> --output /tmp/<repo-name>-analysis.xml
```

Always output to a temporary directory (`/tmp` on Unix, `%TEMP%` on Windows) for remote repositories to avoid polluting the user's working directory.

### Pack a Local Directory

```bash
npx repomix@latest [directory] --output /tmp/<name>-analysis.xml
```

### Key Options

| Option | Description |
|--------|-------------|
| `--style <format>` | Output format: `xml` (default, recommended), `markdown`, `plain`, `json` |
| `--compress` | Tree-sitter compression (~70% token reduction) — use for large repos |
| `--include <patterns>` | Include only matching patterns (e.g., `"src/**/*.ts,**/*.md"`) |
| `--ignore <patterns>` | Additional ignore patterns |
| `--output <path>` | Custom output path (default: `repomix-output.xml`) |
| `--remote-branch <name>` | Specific branch, tag, or commit (for remote repos) |

## Workflow

### Step 1: Pack the Repository

Choose the appropriate command based on the target:

```bash
# Remote repository (always output to /tmp)
npx repomix@latest --remote yamadashy/repomix --output /tmp/repomix-analysis.xml

# Large remote repo with compression
npx repomix@latest --remote facebook/react --compress --output /tmp/react-analysis.xml

# Local directory
npx repomix@latest ./src --output /tmp/src-analysis.xml

# Specific file types only
npx repomix@latest --include "**/*.{ts,tsx,js,jsx}" --output /tmp/filtered-analysis.xml
```

### Step 2: Check Command Output

The command displays:
- **Files processed**: Number of files included
- **Total characters**: Size of content
- **Total tokens**: Estimated AI tokens
- **Output file location**: Where the file was saved

Note the output file location for subsequent analysis.

### Step 3: Analyze the Output

**Structure overview:**
1. Search for the file tree section (near the beginning of the output)
2. Check the metrics summary for overall statistics

**Search for patterns** (use the output file path from Step 2):
```bash
# Find exports and main entry points
grep -iE "export.*function|export.*class" <output-file>

# Search with context
grep -iE -A 5 -B 5 "authentication|auth" <output-file>

# Find API endpoints
grep -iE "router|route|endpoint|api" <output-file>

# Find database models
grep -iE "model|schema|database|query" <output-file>
```

**Read specific sections** using offset/limit for large outputs.

### Step 4: Report Findings

- **Metrics**: Files, tokens, size from command output
- **Structure**: Directory layout from file tree analysis
- **Key findings**: Based on pattern search results
- **Next steps**: Suggestions for deeper exploration

## Best Practices

1. **Use `--compress` for large repos** (>100k lines) to reduce token usage by ~70%
2. **Use pattern search first** before reading entire output files
3. **Use a temporary directory for output** (`/tmp` on Unix, `%TEMP%` on Windows) to keep the user's workspace clean
4. **Use `--include` to focus** on specific parts of a codebase
5. **XML is the default and recommended format** — it has clear file boundaries for structured analysis

## Output Formats

| Format | Best For |
|--------|----------|
| XML (default) | Structured analysis, clear file boundaries |
| Markdown | Human-readable documentation |
| Plain | Simple grep-friendly output |
| JSON | Programmatic/machine analysis |

## Error Handling

- **Command fails**: Check error message, verify repository URL/path, check permissions
- **Output too large**: Use `--compress`, narrow scope with `--include`
- **Network issues** (remote): Verify connection, suggest local clone as alternative
- **Pattern not found**: Try alternative patterns, check file tree to verify files exist

## Security

Repomix automatically excludes potentially sensitive files (API keys, credentials, `.env` files) through built-in security checks. Trust its security defaults unless the user explicitly requests otherwise.