Automated setup (works on all platforms) - installs dependencies, skills, Docker images, also sets up API keys

uv run massgen --setup

If you would like to install other dependencies later

Automated setup (works on all platforms) - installs dependencies, skills, Docker images, also sets up API keys

massgen --setup

If you would like to install other dependencies later

Multi-tool MCP with Gemini - Search + Weather + Filesystem (Requires BRAVE_API_KEY in .env)

massgen --config @examples/tools/mcp/multimcp_gemini \ "Find the best restaurants in Paris and save the recommendations to a file"

**Configuration:**

# Add MCP servers here mcp_servers: weather: # Server name (you choose this) type: "stdio" # Communication type command: "npx" # Command to run args: ["-y", "@modelcontextprotocol/server-weather"] # MCP server package

# That's it! The agent can now check weather.

# Multiple MCP Tools Example: backend: type: "gemini" model: "gemini-3.0-pro-preview" mcp_servers: # Web search search: type: "stdio" command: "npx" args: ["-y", "@modelcontextprotocol/server-brave-search"] env: BRAVE_API_KEY: "${BRAVE_API_KEY}" # Set in .env file

# HTTP-based MCP server (streamable-http transport) custodm_api: type: "streamable-http" # For HTTP/SSE servers url: "http://localhost:8080/mcp/sse" # Server endpoint

# Tool configuration (MCP tools are auto-discovered) allowed_tools: # Optional: whitelist specific tools - "mcpweatherget_current_weather" - "mcp__test_server__mcp_echo" - "mcp__test_server__add_numbers"

exclude_tools: # Optional: blacklist specific tools - "mcp__test_server__current_time"

→ [View more MCP examples](massgen/configs/tools/mcp/)

→ For comprehensive MCP integration guide, see [MCP Integration](https://docs.massgen.ai/en/latest/user_guide/mcp_integration.html)

#### **4. File System Operations & Workspace Management**

MassGen provides comprehensive file system support through multiple backends, enabling agents to read, write, and manipulate files in organized workspaces.


**Filesystem Configuration Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cwd` | string | **Yes** (for file ops) | Working directory for file operations (agent-specific workspace) |
| `snapshot_storage` | string | Yes | Directory for workspace snapshots |
| `agent_temporary_workspace` | string | Yes | Parent directory for temporary workspaces |


**Quick Start Commands:**

Specific research requirements

massgen --config @examples/basic/multi/gemini_gpt5_claude \ "Give me all the talks on agent frameworks in Berkeley Agentic AI Summit 2025"

**Creative Writing:**

Prerequisites: npm install @playwright/mcp@latest (for Playwright MCP server)

massgen --config @examples/tools/code-execution/multi_agent_playwright_automation \ "Browse three issues in https://github.com/Leezekun/MassGen and suggest documentation improvements. Include screenshots and suggestions in a website."

1. 📥 Installation

Method 1: PyPI Installation (Recommended - Python 3.11+):

```bash

Install MassGen via pip

pip install massgen

If you install massgen in uv, make sure you either activate your venv using source .venv/bin/activate

Step 1: Set up API keys, Docker, and skills

uv run massgen --setup

If you install massgen in uv, make sure you either activate your venv using source .venv/bin/activate

Here is a light-weighted setup script which only installs skills (works on all platforms)

uv run massgen --setup-skills

Here is a light-weighted setup script which only installs skills (works on all platforms)

massgen --setup-skills

Basic Workspace Setup:

agents: - id: "file-agent" backend: type: "claude_code" # Backend with file support cwd: "workspace" # Isolated workspace for file operations

🚀 Quick Start

With example configurations

uv run massgen --config @examples/basic/multi/three_agents_default "Your question"

→ See [Installation Guide](https://docs.massgen.ai/en/latest/quickstart/installation.html) for complete setup instructions.

**Method 2: Development Installation** (for contributors):

**Clone the repository**

**Install in editable mode with pip**

**Option 1 (recommended): Installing with uv (faster)**

With example configurations

uv run massgen --config @examples/basic/multi/three_agents_default "Your question" ```

Multi-agent collaboration to improve the website in `massgen/configs/resources/v0.0.21-example

massgen --config @examples/tools/filesystem/gpt5mini_cc_fs_context_path "Enhance the website with: 1) A dark/light theme toggle with smooth transitions, 2) An interactive feature that helps users engage with the blog content (your choice - could be search, filtering by topic, reading time estimates, social sharing, reactions, etc.), and 3) Visual polish with CSS animations or transitions that make the site feel more modern and responsive. Use vanilla JavaScript and be creative with the implementation details."

**Configuration:**

Quick Start - Automation Mode

```bash

Comprehensive Guide

→ Full automation guide with examples: Automation Guide

Topics covered: - Complete automation patterns with error handling - Parallel experiment execution - Performance tips and troubleshooting

Browser automation with screenshots and reporting

Step 2: Create a simple config and start

uv run massgen --quickstart

The `--setup` command will:
- Configure your API keys (OpenAI, Anthropic, Google, xAI)
- Offer to set up Docker images for code execution
- Offer to install skills (openskills, Anthropic/OpenAI/Vercel collections, Agent Browser skill, Crawl4AI)

The `--quickstart` command will:
- Ask how many agents you want (1-5, default 3)
- Ask which backend/model for each agent
- For GPT-5x models, ask for `reasoning.effort` (`low|medium|high`; Codex GPT-5 models also include `xhigh`)
- Auto-detect Docker availability and configure execution mode
- If Docker mode is selected, show a Skills step where you can choose package(s) (`openskills`-based Anthropic/OpenAI/Vercel/Agent Browser plus Crawl4AI) and install them in-place with live status
- Create a ready-to-use config and launch into interactive TUI mode

**🤖 Use MassGen from Your AI Coding Agent:**

Install the [MassGen skill](https://github.com/massgen/skills) to invoke MassGen directly from Claude Code, OpenAI Codex, GitHub Copilot, Cursor, and [40+ other agents](https://skills.sh) that support the [Agent Skills](https://agentskills.io/home) standard:

Then use `/massgen` (Claude Code) or `$massgen` (Codex) to run multi-agent evaluation, planning, spec writing, or any general task. See the [skills docs](https://docs.massgen.ai/en/latest/user_guide/skills.html) for per-agent install options.

**🖥️ Textual TUI (Default Display Mode):**

MassGen launches with an interactive Terminal User Interface (TUI) by default, providing:
- 📊 **Real-time timeline** of all agent activities
- 🎯 **Individual agent status cards** for each team member
- 🗳️ **Vote visualization** and consensus tracking
- 💬 **Multi-turn conversation** management
- ⌨️ **Keyboard controls** for navigation (↑/↓ to scroll, 'q' to cancel)

**Legacy Rich display:**

**Alternative: Full Setup Wizard**

For more control, use the full configuration wizard:

This guides you through use case selection (Research, Code, Q&A, etc.) and advanced configuration options.

**After setup:**

Or use the bash script (Unix/Linux/macOS only), need manually config API keys, see sections below

uv run ./scripts/init.sh

Optional: External framework integration

pip install -e ".[external]"

Or use the bash script (Unix/Linux/macOS only), need manually config API keys, see sections below

./scripts/init.sh

2. 🔐 API Configuration

Create a .env file in your working directory with your API keys:

```bash

Copy this template to .env and add your API keys

OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... GOOGLE_API_KEY=... XAI_API_KEY=...

Optional: Additional providers

CEREBRAS_API_KEY=... TOGETHER_API_KEY=... GROQ_API_KEY=... OPENROUTER_API_KEY=... ```

MassGen automatically loads API keys from .env in your current directory.

→ Complete setup guide with all providers: See API Key Configuration in the docs

Get API keys: - OpenAI | Claude | Gemini | Grok - Azure OpenAI | Cerebras | OpenRouter | More providers...

With explicit bind + defaults for model/config

massgen serve --host 0.0.0.0 --port 4000 --config path/to/config.yaml --default-model gpt-5

**Endpoints**

- `GET /health`
- `POST /v1/chat/completions` (supports `stream: true` SSE and OpenAI-style tool calling)

**cURL examples**

Quick test with any supported model - no configuration needed

uv run python -m massgen.cli --model claude-sonnet-4-5-20250929 "What is machine learning?" uv run python -m massgen.cli --model gemini-3-pro-preview "Explain quantum computing" uv run python -m massgen.cli --model gpt-5-nano "Summarize the latest AI developments"

**Configuration:**

Use the `agent` field to define a single agent with its backend and settings:

→ [See all single agent configs](massgen/configs/basic/single/)


#### **2. Multi-Agent Collaboration (Recommended)**

**Configuration:**

Use the `agents` field to define multiple agents, each with its own backend and config:

**Quick Start Commands:**

Professional development environment with auto-configured workspace

uv run python -m massgen.cli \ --backend claude_code \ --model sonnet \ "Create a Flask web app with authentication"

Configuration Files

MassGen configurations are organized by features and use cases. See the Configuration Guide for detailed organization and examples.

Quick navigation: - Basic setups: Single agent | Multi-agent - Tool integrations: MCP servers | Web search | Filesystem - Provider examples: OpenAI | Claude | Gemini - Specialized teams: Creative | Research | Development

See MCP server setup guides: Discord MCP | Twitter MCP

Backend Configuration Reference

For detailed configuration of all supported backends (OpenAI, Claude, Gemini, Grok, etc.), see:

→ Backend Configuration Guide

Interactive Multi-Turn Mode

MassGen supports an interactive mode where you can have ongoing conversations with the system:

```bash

Start interactive mode with configuration file

uv run python -m massgen.cli \ --config massgen/configs/basic/multi/three_agents_default.yaml ```

Interactive Mode Features: - Multi-turn conversations: Multiple agents collaborate to chat with you in an ongoing conversation - Real-time coordination tracking: Live visualization of agent interactions, votes, and decision-making processes - Real-time feedback: Displays real-time agent and system status with enhanced coordination visualization - Multi-line input: Use """ or ''' to enter multi-line messages - Slash commands: - /help or /h - Show available commands - /status - Display current system status - /config - Open the configuration file - /clear or /reset - Clear conversation history and start fresh - /quit, /exit, or /q - Exit the session (or press Ctrl+C)

Watch the recorded demo:

Claude Code CLI - Advanced coding assistant

npm install -g @anthropic-ai/claude-code

Python API & LiteLLM

Use MassGen programmatically with the familiar LiteLLM/OpenAI interface:

```python from dotenv import load_dotenv load_dotenv() # Load API keys from .env

import litellm from massgen import register_with_litellm

register_with_litellm()

3. 🧩 Supported Models and Tools

Models

The system currently supports multiple model providers with advanced capabilities:

API-based Models: - OpenAI: GPT-5.2 (recommended default), GPT-5.1, GPT-5 series (GPT-5, GPT-5-mini, GPT-5-nano), GPT-5.1-Codex series, GPT-4.1 series, GPT-4o, o4-mini with reasoning, web search, code interpreter, and computer-use support - Note: We recommend GPT-5.2/5.1/5 over Codex models. Codex models are optimized for shorter system messages and may not work well with MassGen's coordination prompts. - Reasoning: GPT-5.1 and GPT-5.2 default to reasoning: none. MassGen automatically sets reasoning.effort: medium when no reasoning config is provided, matching GPT-5's default behavior. - Azure OpenAI: Any Azure-deployed models (GPT-4, GPT-4o, GPT-35-turbo, etc.) - Claude / Anthropic: Claude Opus 4.5, Claude Haiku 4.5, Claude Sonnet 4.5, Claude Opus 4.1, Claude Sonnet 4 - Advanced tooling: web search, code execution, Files API, programmatic tool calling, tool search with deferred loading - Claude Code: Native Claude Code SDK with server-side session persistence and built-in dev tools - Gemini: Gemini 3 Pro, Gemini 2.5 Flash, Gemini 2.5 Pro with code execution and grounding - Antigravity CLI: Google's agy CLI as a MassGen backend, with hardened workspace isolation, workflow-tool fallback, native hooks, and Gemini-tier server-side model selection - Grok / xAI: Grok-4.1, Grok-4, Grok-3, Grok-3-mini with Grok Live Search - Cerebras AI: Ultra-fast inference for supported models - Together AI, Fireworks AI, Groq: Fast inference for LLaMA, Mistral, Qwen, and other open models - OpenRouter: Multi-model aggregator with dynamic model listing (400+ models) - Kimi / Moonshot: Chinese AI models via OpenAI-compatible API - Nebius AI Studio: Cloud inference platform - POE: Quora AI platform with dynamic model discovery - Qwen / Alibaba: DashScope API for Qwen models - Z AI / Zhipu: GLM-4.5 and related models

Local Model Support: - vLLM & SGLang: Unified inference backend supporting both vLLM and SGLang servers - vLLM (port 8000) and SGLang (port 30000) with OpenAI-compatible API - Support for top_k, repetition_penalty, chat_template_kwargs parameters - SGLang-specific separate_reasoning parameter for thinking models - Mixed server deployments with configuration example: two_qwen_vllm_sglang.yaml

• LM Studio: Run open-weight models locally with automatic server management
• Automatic LM Studio CLI installation
• Auto-download and loading of models
• Support for LLaMA, Mistral, Qwen and other open-weight models

→ For complete model list and configuration details, see Supported Models

Tools

MassGen agents can leverage various tools to enhance their problem-solving capabilities:

• Built-in Tools: Web search, code execution, bash/shell (provider-dependent)
• Filesystem: Native file operations or via MCP
• MCP Integration: Connect to any MCP server for extended capabilities
• Custom Tools: Define your own tools via YAML configuration
• Multimodal: Image, audio, video understanding and generation (native or via custom tools)

→ For detailed backend capabilities and tool support matrix, see User Guide - Backends

---

Basic Project Integration:

agents: - id: "code-reviewer" backend: type: "claude_code" cwd: "workspace" # Agent's isolated work area

orchestrator: context_paths: - path: "." # Current directory (relative path) permission: "write" # Final agent can create/modify files protected_paths: # Optional: files immune from modification - ".env" - "config.json" - path: "/home/user/my-project/src" # Absolute path example permission: "read" # Agents can analyze your code

🤖 Automation & LLM Integration

→ For LLM agents: See AI_USAGE.md for complete command-line usage guide

MassGen provides automation mode designed for LLM agents and programmatic workflows:

Start interactive chat (no initial question)

massgen --config @examples/basic/multi/three_agents_default

Debug mode for troubleshooting

massgen --config @examples/basic/multi/three_agents_default \ --debug "Your question" ```