# repo2txt - Deep Dive

> **TL;DR**: repo2txt is a browser-based tool that converts GitHub repositories (or local directories) into a single text file optimized for LLMs. No server, no setup, no privacy concerns - just paste a repo URL and get LLM-ready text. 1,700+ stars and essential for anyone feeding codebases to AI assistants.

---

## What Is repo2txt?

**repo2txt** is a web application that transforms scattered repository files into a single, consolidated text document that can be easily fed into AI models like Claude, ChatGPT, or Gemini.

### The Problem It Solves

```
THE CHALLENGE:

You want to ask an AI: "Review this codebase and suggest improvements"

But:
├── Your repo has 50+ files
├── Manually copying each file is tedious
├── Context windows have limits
├── You need the AI to understand relationships
└── Privacy matters for proprietary code

REPO2TXT SOLUTION:

GitHub Repo URL → repo2txt → Single formatted text → Paste into AI
```

### Why This Matters

| Without repo2txt | With repo2txt |
|-----------------|---------------|
| Copy files one by one | One-click conversion |
| Lose project structure | Structure preserved |
| Hit context limits randomly | Selective file inclusion |
| Risk sending code to servers | 100% client-side |
| Miss file relationships | Full context provided |

---

## Key Features

### 1. 100% Client-Side (Privacy First)

```
┌─────────────────────────────────────────────────────────────────────┐
│                    HOW REPO2TXT WORKS                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│   Your Browser                                                      │
│   ┌─────────────────────────────────────────────────────────────┐   │
│   │  1. You enter GitHub URL                                    │   │
│   │  2. JavaScript fetches repo via GitHub API                  │   │
│   │  3. Processing happens IN YOUR BROWSER                      │   │
│   │  4. Text file generated locally                             │   │
│   │  5. You copy or download                                    │   │
│   └─────────────────────────────────────────────────────────────┘   │
│                                                                     │
│   ❌ No server processing                                          │
│   ❌ No code uploaded anywhere                                     │
│   ❌ No external storage                                           │
│   ✅ Your code stays on YOUR machine                               │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### 2. Selective File Inclusion

Choose exactly what to include:

```
Repository Structure:
├── src/
│   ├── components/     [✓] Include
│   ├── utils/          [✓] Include
│   └── tests/          [ ] Exclude (saves tokens)
├── docs/               [ ] Exclude
├── node_modules/       [ ] Auto-excluded
└── package.json        [✓] Include
```

### 3. File Extension Filtering

Focus on what matters:

```
Filter by extension:
├── .js, .ts, .tsx     → JavaScript/TypeScript code
├── .py                → Python code
├── .md                → Documentation
├── .json              → Configuration
└── Custom filters     → Whatever you need
```

### 4. Multiple Input Sources

| Source | How It Works |
|--------|--------------|
| **GitHub URL** | Paste any public repo URL |
| **Private Repos** | Works with authentication |
| **Local Directory** | Use `local.html` interface |
| **ZIP Files** | Upload compressed archives |

### 5. Multiple Output Options

| Output | Use Case |
|--------|----------|
| **Copy to Clipboard** | Quick paste into chat |
| **Download Text** | Save for later use |
| **ZIP Export** | Download selected files |

---

## How to Use It

### Option 1: Web Interface (Easiest)

```
1. Visit: https://repo2txt.com/
2. Paste GitHub repo URL
3. Select files/folders to include
4. Apply extension filters (optional)
5. Click "Generate"
6. Copy or download the result
```

### Option 2: Self-Host

```bash
# Clone the repository
git clone https://github.com/abinthomasonline/repo2txt.git

# Open in browser
open index.html        # For GitHub repos
open local.html        # For local directories

# Or use GitHub Pages on your fork
```

### Option 3: Local Directories

```
1. Open local.html in your browser
2. Select a local directory
3. Same filtering and generation options
4. Works completely offline
```

---

## Use Cases

### 1. Code Review with AI

```
WORKFLOW:

1. repo2txt → Convert your feature branch
2. Paste into Claude/ChatGPT
3. Ask: "Review this code for bugs, security issues, and improvements"
4. Get comprehensive feedback with full context
```

### 2. Documentation Generation

```
WORKFLOW:

1. repo2txt → Include source files
2. Ask AI: "Generate documentation for this codebase"
3. AI sees all files, relationships, and patterns
4. Get comprehensive, accurate docs
```

### 3. Codebase Explanation

```
WORKFLOW:

1. New project? repo2txt the whole thing
2. Ask: "Explain the architecture of this project"
3. AI understands the full structure
4. Get accurate explanations, not hallucinations
```

### 4. Refactoring Suggestions

```
WORKFLOW:

1. repo2txt → Include relevant modules
2. Ask: "How would you refactor this for better maintainability?"
3. AI sees actual code, not imagined patterns
4. Get contextual, applicable suggestions
```

### 5. Bug Investigation

```
WORKFLOW:

1. repo2txt → Include relevant files
2. Describe the bug
3. Ask: "What could be causing this issue?"
4. AI can trace through actual code paths
```

---

## Output Format

### What You Get

```
================================================================================
Repository: username/repo-name
================================================================================

================================================================================
File: src/index.js
================================================================================
import React from 'react';
import App from './App';

ReactDOM.render(<App />, document.getElementById('root'));

================================================================================
File: src/App.js
================================================================================
import React from 'react';
import Header from './components/Header';

function App() {
  return (
    <div className="app">
      <Header />
      {/* ... */}
    </div>
  );
}

export default App;

================================================================================
File: src/components/Header.js
================================================================================
// ... and so on for each file
```

### Why This Format Works

| Feature | Benefit for LLMs |
|---------|-----------------|
| **Clear file separators** | AI knows file boundaries |
| **File paths included** | AI understands structure |
| **Sequential ordering** | Logical reading order |
| **Consistent formatting** | Easy to parse |

---

## Comparison with Alternatives

### repo2txt vs. Repomix

| Feature | repo2txt | Repomix |
|---------|----------|---------|
| **Setup** | None (browser) | npm install |
| **Processing** | Client-side | CLI tool |
| **Output formats** | Text | XML, Markdown, JSON |
| **Token counting** | Basic | Built-in |
| **Code compression** | No | Yes (tree-sitter) |
| **Best for** | Quick, simple use | Advanced features |

### repo2txt vs. GitIngest

| Feature | repo2txt | GitIngest |
|---------|----------|-----------|
| **Interface** | Web app | Chrome extension + CLI |
| **URL modification** | No | Replace github.com |
| **Ecosystem** | JavaScript | Python-focused |
| **Best for** | Any workflow | Python/DS workflows |

### repo2txt vs. RepoToText

| Feature | repo2txt | RepoToText |
|---------|----------|------------|
| **Architecture** | Client-side | Server-based |
| **Privacy** | Maximum | Code touches server |
| **Setup** | None | Docker + API key |
| **Best for** | Privacy-conscious | Self-hosted teams |

### The repo2txt Advantage

```
✅ Zero setup
✅ No server (privacy)
✅ Works offline (local.html)
✅ Self-hostable
✅ Open source (MIT)
✅ Simple and focused
```

---

## Technical Details

### Built With

| Component | Purpose |
|-----------|---------|
| **JavaScript (74%)** | Core application logic |
| **HTML (26%)** | User interface |
| **GitHub API** | Fetch repository contents |
| **Browser APIs** | File system, clipboard |

### Files in the Project

```
repo2txt/
├── index.html        # Main interface for GitHub repos
├── local.html        # Interface for local directories
├── script.js         # Core logic
└── style.css         # Styling
```

### How It Fetches Repos

```javascript
// Simplified flow:
1. Parse GitHub URL → owner/repo
2. Fetch repo tree via GitHub API
3. For each file, fetch content
4. Concatenate with formatting
5. Present to user
```

---

## Tips for Effective Use

### 1. Be Selective

```
DON'T: Include entire repo with node_modules
DO: Select only relevant source files

Why: Save tokens, focus AI attention
```

### 2. Use Extension Filters

```
For React review:  .js, .jsx, .tsx, .ts
For Python review: .py
For Config review: .json, .yaml, .toml
```

### 3. Exclude Generated Files

```
Exclude:
├── dist/
├── build/
├── node_modules/
├── __pycache__/
├── .git/
└── *.lock files
```

### 4. Include Context Files

```
Include:
├── README.md         (project overview)
├── package.json      (dependencies)
├── tsconfig.json     (TypeScript config)
└── .env.example      (environment structure)
```

### 5. Estimate Token Usage

```
Rough estimates:
├── 1 KB of code ≈ 250-400 tokens
├── Average file ≈ 200-500 tokens
├── Claude context: 100K-200K tokens
├── ChatGPT-4: 128K tokens

Rule: If your output is < 50KB, you're usually fine
```

---

## How This Helps Us Achieve Our Goals

Looking at our "Software Development in the Age of AI" repository:

### 1. **Essential AI Development Tool**

| Task | How repo2txt Helps |
|------|-------------------|
| Code review with AI | Full codebase context |
| Documentation generation | AI sees everything |
| Debugging assistance | Complete code visibility |
| Refactoring suggestions | Understand relationships |

### 2. **Complements Our Other Deep Dives**

| Deep Dive | Connection |
|-----------|------------|
| **Context Engineering** | repo2txt IS context preparation |
| **Claude Code** | Alternative way to give Claude context |
| **CCPM** | Quick context for parallel agents |
| **LangExtract** | Different approach (extract vs. provide) |

### 3. **Privacy Alignment**

Our repo emphasizes thoughtful AI use. repo2txt's client-side approach means:
- Proprietary code stays private
- No third-party servers
- Full control over what's shared

### 4. **Practical Workflow Tool**

When you need to:
- Get AI feedback on a PR
- Understand an unfamiliar codebase
- Generate documentation
- Debug complex issues

repo2txt makes it possible in seconds.

---

## Recent Updates

| Date | Feature |
|------|---------|
| Dec 2024 | Chrome extension version |
| Dec 2024 | Node.js server option |
| Dec 2024 | Directory structure improvements |
| Ongoing | Community contributions |

---

## Quick Reference

### Basic Usage

```
1. Go to repo2txt.com
2. Paste GitHub URL
3. Select files
4. Generate
5. Copy/Download
```

### Local Usage

```
1. Clone repo
2. Open local.html
3. Select local directory
4. Generate
```

### Self-Hosting

```bash
git clone https://github.com/abinthomasonline/repo2txt
# Enable GitHub Pages or serve locally
```

---

## Key Links

| Resource | URL |
|----------|-----|
| Web Application | https://repo2txt.com/ |
| GitHub Repository | https://github.com/abinthomasonline/repo2txt |
| Local Version | Clone and open `local.html` |

---

## Quick Stats

| Metric | Value |
|--------|-------|
| GitHub Stars | 1,700+ |
| Creator | Abin Thomas |
| Created | September 2024 |
| License | MIT |
| Tech Stack | JavaScript + HTML |
| Server Required | No (100% client-side) |
| Supported Sources | GitHub, Local, ZIP |

---

## Bottom Line

repo2txt solves a simple but critical problem: **getting code into AI assistants effectively**.

**Why it matters**:
- AI assistants reason better with complete context
- Manually copying files is tedious and error-prone
- Privacy matters for real codebases
- Token efficiency requires selectivity

**The key insight**: The quality of AI assistance depends on the quality of context you provide. repo2txt makes providing good context trivial.

For our repository focused on AI-assisted development, repo2txt is a foundational tool. It's the bridge between "your codebase" and "AI that understands your codebase."

**Simple. Private. Essential.**

---

*Document created: January 2026*
*Sources: [GitHub - abinthomasonline/repo2txt](https://github.com/abinthomasonline/repo2txt), [repo2txt.com](https://repo2txt.com/), [WorkOS Blog](https://workos.com/blog/context-is-king-tools-for-feeding-your-code-and-website-to-llms), [Addy Osmani's LLM Workflow](https://addyo.substack.com/p/my-llm-coding-workflow-going-into)*
