diff --git a/docs/repoprompt.md b/docs/repoprompt.md
new file mode 100644
index 00000000..912e7500
--- /dev/null
+++ b/docs/repoprompt.md
@@ -0,0 +1,321 @@
+# RepoPrompt Pair Programming Guide
+
+RepoPrompt is a powerful MCP (Model Context Protocol) server that enables sophisticated AI pair programming workflows. This guide explains how to use RepoPrompt with Claude Code for complex development tasks.
+
+## Overview
+
+The pair programming mode allows Claude Code to collaborate with other AI models (like OpenAI's O1/O3 or Google's Gemini) by:
+- Claude Code acts as a **context manager** - gathering files, managing tokens, and handling tools
+- Another AI model acts as the **planner/executor** - providing deep reasoning and implementation
+- Both models work together continuously throughout the task
+
+## Key Benefits
+
+1. **Leverages Model Strengths**: Claude excels at tool use and navigation; reasoning models excel at complex problem-solving
+2. **Optimal Context Management**: Reasoning models work best with complete context upfront rather than incremental discovery
+3. **Continuous Collaboration**: Maintains conversation state and file context between messages
+4. **Higher Quality Output**: More considered implementations for complex tasks
+
+## Installation
+
+### Prerequisites
+- Claude Code with MCP support
+- RepoPrompt MCP server installed
+
+### Quick Setup
+```bash
+# Install RepoPrompt if not already installed
+claude mcp add RepoPrompt -- /path/to/repoprompt_cli
+
+# Verify installation
+claude mcp list
+
+# Restart Claude Code to load the server
+# Use Cmd+R or restart from command line
+```
+
+## Basic Workflow
+
+### 1. Select Your Working Files
+
+First, identify and select files relevant to your task:
+
+```
+# List current selection
+manage_selection action="list" include_stats=true
+
+# Add specific files
+manage_selection action="add" paths=["src/main.ts", "src/utils.ts", "tests/main.test.ts"]
+
+# Or replace entire selection
+manage_selection action="replace" paths=["src/auth/login.ts", "src/auth/session.ts"]
+
+# Clear selection to start fresh
+manage_selection action="clear"
+```
+
+**Tips:**
+- Keep total context under 100K tokens (ideally ~60K)
+- Select only directly relevant files
+- Use `get_code_structure` to preview large files efficiently
+
+### 2. Set Your Task Description
+
+Write a clear prompt describing what you want to accomplish:
+
+```
+set_prompt_state prompt="Implement user authentication with JWT tokens, including login, logout, and session management"
+```
+
+### 3. Start the Pair Programming Session
+
+Begin with planning mode to have the AI create a detailed implementation plan:
+
+```
+chat_send mode="plan" message="Let's implement the authentication system as described"
+```
+
+### 4. Execute the Plan
+
+Switch to edit mode to implement the changes:
+
+```
+chat_send mode="edit" message="Now let's implement the authentication module"
+```
+
+## Advanced Features
+
+### File Discovery Workflow
+
+Before starting, use these tools to find relevant files:
+
+```
+# Get project structure
+get_file_tree type="files"
+
+# Search for specific patterns
+search pattern="authentication" mode="both"
+
+# Preview file structure without full content
+get_code_structure paths=["src/auth.ts", "src/server.ts"]
+
+# Read specific files
+read_file path="src/config/auth.config.ts"
+```
+
+### Context Management Strategy
+
+1. **Start Minimal**: Begin with core files only
+2. **Add Dependencies**: Include related files as needed
+3. **Monitor Token Count**: Check with `manage_selection action="list" include_stats=true`
+4. **Update Between Tasks**: Use `replace` when switching focus
+
+### Working with Multiple Models
+
+RepoPrompt supports various AI models. List available presets:
+
+```
+list_models
+```
+
+Choose a specific model for your task:
+
+```
+chat_send mode="plan" model="DeepAnalysis" message="Analyze our authentication architecture"
+```
+
+## Practical Examples
+
+### Example 1: Adding a New Feature
+
+```
+# 1. Clear previous context
+manage_selection action="clear"
+
+# 2. Find relevant files
+search pattern="session manager" mode="both"
+
+# 3. Select core files
+manage_selection action="add" paths=["src/session-manager.ts", "src/types/session.ts", "tests/session.test.ts"]
+
+# 4. Set the task
+set_prompt_state prompt="Add session expiration and automatic cleanup features"
+
+# 5. Plan the implementation
+chat_send mode="plan" message="Design session expiration system with configurable timeouts"
+
+# 6. Execute the plan
+chat_send mode="edit" message="Implement the session expiration features"
+```
+
+### Example 2: Debugging Complex Issues
+
+```
+# 1. Gather error context
+search pattern="error.*websocket" mode="content"
+
+# 2. Select relevant files
+manage_selection action="replace" paths=["src/websocket.ts", "src/error-handler.ts", "logs/recent-errors.log"]
+
+# 3. Describe the issue
+set_prompt_state prompt="WebSocket connections dropping intermittently under high load"
+
+# 4. Analyze with reasoning model
+chat_send mode="plan" message="Investigate and fix WebSocket stability issues"
+```
+
+### Example 3: Refactoring
+
+```
+# 1. Select files to refactor
+manage_selection action="add" paths=["src/old-api.ts", "src/handlers/*.ts"]
+
+# 2. Set refactoring goals
+set_prompt_state prompt="Refactor API to use async/await instead of callbacks, maintain backward compatibility"
+
+# 3. Plan the refactor
+chat_send mode="plan" message="Create refactoring plan preserving all existing functionality"
+
+# 4. Execute incrementally
+chat_send mode="edit" message="Start refactoring the authentication handlers"
+```
+
+## Best Practices
+
+### 1. Context Selection
+- Start with minimal context and add as needed
+- Include test files when modifying code
+- Add configuration files for system-wide changes
+- Remove files that are no longer relevant
+
+### 2. Prompt Writing
+- Be specific about requirements
+- Include constraints (e.g., "maintain backward compatibility")
+- Mention relevant technologies and patterns
+- Specify testing requirements
+
+### 3. Mode Selection
+- Use `plan` mode for:
+  - Complex architectural decisions
+  - Multi-file refactoring
+  - New feature design
+  
+- Use `edit` mode for:
+  - Direct implementation
+  - Bug fixes with clear solutions
+  - Following an established plan
+
+- Use `chat` mode for:
+  - General discussions
+  - Code exploration
+  - Understanding existing code
+
+### 4. Session Management
+- Continue existing chats for related work:
+  ```
+  chat_tools action="list"
+  chat_send chat_id="existing-id" message="Continue the refactoring"
+  ```
+- Start new chats for unrelated tasks
+- Name your chats for easy identification:
+  ```
+  chat_send new_chat=true chat_name="Auth System Refactor" message="Starting auth refactor"
+  ```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Token Limit Exceeded**
+   - Check current usage: `manage_selection action="list" include_stats=true`
+   - Remove unnecessary files: `manage_selection action="remove" paths=["large-file.ts"]`
+   - Use code structure instead of full content for large files
+
+2. **Model Not Responding**
+   - Reasoning models can be slow, especially on complex tasks
+   - Wait for completion before sending follow-up messages
+   - Consider breaking large tasks into smaller chunks
+
+3. **Context Lost Between Messages**
+   - Ensure you're continuing the same chat session
+   - Verify file selection hasn't changed: `manage_selection action="list"`
+   - Check chat history: `chat_tools action="log"`
+
+4. **Edit Mode Not Working**
+   - Ensure you have write permissions for target files
+   - Verify files exist and are selected
+   - Check for syntax errors in previous edits
+
+### Getting Help
+
+- Use `chat_tools action="log"` to review conversation history
+- Check file selection state with `manage_selection action="list"`
+- Verify model availability with `list_models`
+- Ensure RepoPrompt is running: `claude mcp list`
+
+## Advanced Workflows
+
+### Multi-Stage Development
+
+For complex features spanning multiple components:
+
+1. **Stage 1: Architecture Planning**
+   ```
+   manage_selection action="replace" paths=["docs/architecture.md", "src/index.ts"]
+   chat_send mode="plan" message="Design microservice architecture"
+   ```
+
+2. **Stage 2: Core Implementation**
+   ```
+   manage_selection action="replace" paths=["src/core/*.ts", "src/types/*.ts"]
+   chat_send mode="edit" message="Implement core service logic"
+   ```
+
+3. **Stage 3: Integration**
+   ```
+   manage_selection action="add" paths=["src/api/*.ts", "tests/integration/*.ts"]
+   chat_send mode="edit" message="Add API endpoints and integration tests"
+   ```
+
+### Collaborative Review
+
+Use RepoPrompt for code review and improvements:
+
+```
+# Select files for review
+manage_selection action="replace" paths=["src/new-feature/*.ts"]
+
+# Set review criteria
+set_prompt_state prompt="Review for security vulnerabilities, performance issues, and code style"
+
+# Get detailed analysis
+chat_send mode="plan" message="Perform comprehensive code review"
+```
+
+## Tips for Success
+
+1. **Let Models Play to Their Strengths**
+   - Claude: File navigation, tool use, quick edits
+   - O1/O3: Deep reasoning, complex algorithms, architecture
+   - Gemini: Large context analysis, pattern recognition
+
+2. **Maintain Clear Separation**
+   - Planning: High-level design and approach
+   - Execution: Actual code changes
+   - Verification: Testing and validation
+
+3. **Use Appropriate Context**
+   - Include enough context for understanding
+   - But not so much that it overwhelms the model
+   - ~60K tokens is often the sweet spot
+
+4. **Iterate Thoughtfully**
+   - Start with planning before jumping to implementation
+   - Review plans before execution
+   - Test incrementally
+
+## Conclusion
+
+RepoPrompt's pair programming mode enables sophisticated AI collaboration for complex development tasks. By leveraging multiple models' strengths and maintaining careful context management, you can tackle challenging problems more effectively than with a single model alone.
+
+Remember: The key is using Claude Code as an intelligent context manager while letting reasoning models handle complex problem-solving. This division of labor produces higher quality results than either model working alone.
\ No newline at end of file