Installation

This guide provides detailed installation instructions for RepoMaster, including system requirements, dependency management, and troubleshooting common issues.

System requirements

Before installing RepoMaster, ensure your system meets these requirements:

Minimum requirements

Python: 3.11 or higher
Git: Any recent version
Memory: 4GB RAM minimum (8GB recommended)
Disk space: 2GB free space
Operating system: Linux, macOS, or Windows with WSL2
Internet connection: Required for repository cloning and API access

Recommended setup

Python: 3.11+
Virtual environment: conda or venv
Memory: 16GB RAM for complex tasks
Disk space: 10GB+ for repository cache

RepoMaster works best in a Unix-like environment. Windows users should use WSL2 (Windows Subsystem for Linux) for optimal compatibility.

Installation methods

Standard Installation
Development Installation

Clone the repository

First, clone RepoMaster from GitHub:

git clone https://github.com/QuantaAlpha/RepoMaster.git
cd RepoMaster

Create virtual environment (recommended)

Using a virtual environment helps isolate dependencies:

# Create virtual environment
python -m venv venv

# Activate on Linux/macOS
source venv/bin/activate

# Activate on Windows (WSL)
source venv/bin/activate

Install dependencies

Install all required packages from requirements.txt:

pip install -r requirements.txt

This installs the following core dependencies:

AI and Agent Framework

pyautogen~=0.7.6 - Core multi-agent framework
autogen-agentchat~=0.6.1 - Agent chat capabilities
autogen-core~=0.6.1 - Core autogen functionality
openai~=1.68.0 - OpenAI API client

LLM Orchestration

langchain - LLM application framework
langchain-community - Community integrations
tiktoken~=0.7.0 - Token counting

Web Interface

streamlit - Interactive web dashboard
streamlit_extras - Additional UI components
gradio - Alternative UI framework

Data Processing

pandas~=2.2.2 - Data manipulation
beautifulsoup4~=4.12.3 - HTML parsing
requests~=2.32.3 - HTTP requests
aiohttp~=3.8.0 - Async HTTP client

Search and Analysis

serpapi~=0.1.5 - Search engine API
search-engine-parser - Search result parsing
grep_ast - Code analysis
networkx - Graph algorithms

Document Processing

PyMuPDF - PDF processing
pdf2image - PDF to image conversion
pillow - Image processing

Utilities

python-dotenv~=1.0.1 - Environment management
tqdm - Progress bars
plotly - Visualization
joblib - Parallel processing
humanize - Human-readable formatting
genson - JSON schema generation

For contributors and developers:

# Clone repository
git clone https://github.com/QuantaAlpha/RepoMaster.git
cd RepoMaster

# Create development environment
python -m venv venv
source venv/bin/activate  # or conda activate repomaster

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Editable mode (-e flag) allows you to modify the code without reinstalling the package.

Configuration

Environment configuration

RepoMaster uses environment variables for configuration. Follow these steps:

Copy the example configuration

cp configs/env.example configs/.env

Edit the configuration file

Open configs/.env in your preferred text editor:

nano configs/.env  # or vim, code, etc.

Configure API provider

Set your default AI provider:

# Set the default API provider (openai, claude, deepseek, azure_openai)
DEFAULT_API_PROVIDER=openai

Add required API keys

Required services:

# Search Engine APIs (Required for deep search)
SERPER_API_KEY=your_serper_key    # Get at: https://serper.dev/login
JINA_API_KEY=your_jina_key        # Get at: https://jina.ai/

Without SERPER_API_KEY and JINA_API_KEY, the deep search functionality will not work properly.

Primary LLM provider (choose at least one):

OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-5
OPENAI_BASE_URL=https://api.openai.com/v1

Verify installation

Test your configuration:

# Run configuration test
python test_config.py

# Run full test suite
pytest tests/

If the configuration is correct, you should see:

✅ Environment loaded successfully
✅ API configuration validated
✅ All required keys present

Launch RepoMaster

Once installation and configuration are complete, launch RepoMaster:

Web interface

Start the interactive web dashboard:

python launcher.py --mode frontend

Access at: http://localhost:8501 Available options:

python launcher.py --mode frontend \
  --streamlit-port 8502 \
  --streamlit-host 0.0.0.0 \
  --max-upload-size 500 \
  --log-level DEBUG

Frontend configuration options

--streamlit-port: Custom port (default: 8501)
--streamlit-host: Custom host (default: localhost)
--max-upload-size: File upload limit in MB (default: 200, range: 1-2000)
--log-level: Logging level (DEBUG, INFO, WARNING, ERROR)

Command-line interface

Start the unified multi-agent interface:

python launcher.py --mode backend --backend-mode unified

Available options:

python launcher.py --mode backend --backend-mode unified \
  --api-type openai \
  --temperature 0.1 \
  --work-dir /custom/path \
  --timeout 300 \
  --max-tokens 8000

Backend configuration options

--backend-mode: Agent mode (unified, deepsearch, general_assistant, repository_agent)
--api-type: API provider (openai, claude, deepseek, etc.)
--temperature: Model temperature (default: 0.1, range: 0.0-2.0)
--work-dir: Working directory (default: coding)
--timeout: Request timeout in seconds (default: 120)
--max-tokens: Maximum token count (default: 4000)

Direct agent access

Launch individual agents for specialized tasks:

# Advanced web research and data retrieval
python launcher.py --mode backend --backend-mode deepsearch

Troubleshooting

Common issues

ModuleNotFoundError: No module named 'X'

Problem: Missing dependencySolution:

# Reinstall all dependencies
pip install -r requirements.txt --force-reinstall

# Or install specific package
pip install package_name

Configuration file not found

Problem: Missing .env fileSolution:

# Copy the example configuration
cp configs/env.example configs/.env

# Edit with your API keys
nano configs/.env

If you see this error:

⚠️  Configuration file not found!
📝 Please copy the example configuration file:
   cp configs/env.example configs/.env

The launcher will guide you through the setup process.

Missing required API keys

Problem: SERPER_API_KEY or JINA_API_KEY not configuredSolution:

Get API keys:
- SERPER: https://serper.dev/login
- JINA: https://jina.ai/
Add to configs/.env:

SERPER_API_KEY=your_actual_key_here
JINA_API_KEY=your_actual_key_here

Python version incompatibility

Problem: Using Python < 3.11Solution:

# Check Python version
python --version

# Install Python 3.11+ (Ubuntu/Debian)
sudo apt update
sudo apt install python3.11 python3.11-venv

# Create environment with specific version
python3.11 -m venv venv

Port already in use (8501)

Problem: Default Streamlit port is occupiedSolution:

# Use a different port
python launcher.py --mode frontend --streamlit-port 8502

# Or kill the process using the port
lsof -ti:8501 | xargs kill -9

File upload size limit errors

Problem: Files too large for default limit (200MB)Solution:

# Increase upload limit to 500MB
python launcher.py --mode frontend --max-upload-size 500

# Maximum supported: 2000MB (2GB)
python launcher.py --mode frontend --max-upload-size 2000

Getting help

View all available commands and options:

# Show help
python launcher.py --help

# List available modes
python launcher.py --modes

If you encounter issues not covered here:

Running tests

Verify your installation by running the test suite:

# Run configuration tests
python test_config.py

# Run full test suite
pytest tests/

# Run specific benchmark
python -m core.git_task --config configs/gittaskbench.yaml

Run tests after installation to ensure everything is configured correctly.

Next steps

Now that RepoMaster is installed:

Quickstart

Run your first task in minutes

Configuration

Advanced configuration options

Usage examples

Real-world examples and use cases

API reference

Complete API documentation

Getting Started

Core Concepts

Agents

Usage Modes

Configuration

Use Cases

System requirements

Minimum requirements

Recommended setup

Installation methods

Clone the repository

Create virtual environment (recommended)

Install dependencies

Configuration

Environment configuration

Verify installation

Launch RepoMaster

Web interface

Command-line interface

Direct agent access

Troubleshooting

Common issues

Getting help

Running tests

Next steps

Quickstart

Configuration

Usage examples

API reference

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Agents

Usage Modes

Configuration

Use Cases

​System requirements

​Minimum requirements

​Recommended setup

​Installation methods

​Clone the repository

​Create virtual environment (recommended)

​Install dependencies

​Configuration

​Environment configuration

​Verify installation

​Launch RepoMaster

​Web interface

​Command-line interface

​Direct agent access

​Troubleshooting

​Common issues

​Getting help

​Running tests

​Next steps

Quickstart

Configuration

Usage examples

API reference

Build docs developers (and LLMs) love

System requirements

Minimum requirements

Recommended setup

Installation methods

Clone the repository

Create virtual environment (recommended)

Install dependencies

Configuration

Environment configuration

Verify installation

Launch RepoMaster

Web interface

Command-line interface

Direct agent access

Troubleshooting

Common issues

Getting help

Running tests

Next steps