​

RepoPrompt Pair Programming Guide

​

Overview

• 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

# 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

# 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"

• 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

set_prompt_state prompt="Implement user authentication with JWT tokens, including login, logout, and session management"

​

3. Start the Pair Programming Session

chat_send mode="plan" message="Let's implement the authentication system as described"

​

4. Execute the Plan

chat_send mode="edit" message="Now let's implement the authentication module"

​

Advanced Features

​

File Discovery Workflow

# 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

list_models

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

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

# 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