Skip to content
Back to search

MassGen

πŸš€ MassGen is an open-source multi-agent scaling system that runs in your terminal, autonomously orchestrating frontier models and agents to collaborate, reason, and produce high-quality results. | Join us on Discord: discord.massgen.ai

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/massgen--massgen/badge.svg)](/listings/massgen--massgen)

HTML

<a href="/listings/massgen--massgen"><img src="/api/listings/massgen--massgen/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. πŸ“₯ Installation

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

# Install MassGen via pip
pip install massgen

# Or with uv (faster)
pip install uv
uv venv && source .venv/bin/activate
uv pip install massgen

# If you install massgen in uv, make sure you either activate your venv using source .venv/bin/activate
# Or include "uv run" before all commands

**Quickstart Setup** (Fastest way to get running):

# Step 1: Set up API keys, Docker, and skills
uv run massgen --setup

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

npx skills add massgen/skills

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:**

massgen --display rich "Your question"

**Alternative: Full Setup Wizard**

For more control, use the full configuration wizard:

uv run massgen --init

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

**After setup:**

# Interactive mode
uv run massgen

# Single query
uv run massgen "Your question here"

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

git clone https://github.com/Leezekun/MassGen.git
cd MassGen

**Install in editable mode with pip**

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

uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e .

# If you install massgen in uv, make sure you either activate your venv using source .venv/bin/activate
# Or include "uv run" before all commands

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

# Or use the bash script (Unix/Linux/macOS only), need manually config API keys, see sections below
uv run ./scripts/init.sh

# If you would like to install other dependencies later
# Here is a light-weighted setup script which only installs skills (works on all platforms)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 1,637 lines Β· 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.png">
  4. <source media="(prefers-color-scheme: light)" srcset="assets/logo.png">
  5. <img src="assets/logo.png" alt="MassGen Logo" width="360" />
  6. </picture>
  7. </p>
  8. <div align="center">
  9. [![PyPI](https://img.shields.io/pypi/v/massgen?style=flat-square&logo=pypi&logoColor=white&label=PyPI&color=3775A9)](https://pypi.org/project/massgen/)
  10. [![Docs](https://img.shields.io/badge/docs-massgen.ai-blue?style=flat-square&logo=readthedocs&logoColor=white)](https://docs.massgen.ai)
  11. [![GitHub Stars](https://img.shields.io/github/stars/Leezekun/MassGen?style=flat-square&logo=github&color=181717&logoColor=white)](https://github.com/Leezekun/MassGen)
  12. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/)
  13. [![License](https://img.shields.io/badge/license-Apache%202.0-green?style=flat-square)](LICENSE)
  14. </div>
  15. <div align="center">
  16. [![Follow on X](https://img.shields.io/badge/FOLLOW%20ON%20X-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.massgen.ai)
  17. [![Follow on LinkedIn](https://img.shields.io/badge/FOLLOW%20ON%20LINKEDIN-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/company/massgen-ai)
  18. [![Join our Discord](https://img.shields.io/badge/JOIN%20OUR%20DISCORD-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.massgen.ai)
  19. </div>
  20. <h1 align="center">πŸš€ MassGen: Multi-Agent Scaling System for GenAI</h1>
  21. <p align="center">
  22. <i>MassGen is a cutting-edge multi-agent system that leverages the power of collaborative AI to solve complex tasks.</i>
  23. </p>
  24. <p align="center">
  25. <a href="https://www.youtube.com/watch?v=5JofXWf_Ok8">
  26. <img src="docs/source/_static/images/readme.gif" alt="MassGen example" width="800">
  27. </a>
  28. </p>
  29. <p align="center">
  30. <i>Scaling AI with collaborative, continuously improving agents (4x speed)</i>
  31. </p>
  32. MassGen is a cutting-edge multi-agent framework that coordinates AI agents to solve complex tasks through redundancy and iterative refinement. Every agent tackles the full problem, observing, critiquing, and building on each other's work across cycles of refinement and restarts. When agents believe there is a strong enough answer, they vote, and the best collectively validated answer wins. This approach to parallel refinement and collective validation lays the groundwork for principled multi-agent scaling, where the system continuously improves its outputs by leveraging diverse agent perspectives and enforcing quality through consensus.
  33. This project started with the "threads of thought" and "iterative refinement" ideas presented in [The Myth of Reasoning](https://docs.ag2.ai/latest/docs/blog/2025/04/16/Reasoning/), and extends the classic "multi-agent conversation" idea in [AG2](https://github.com/ag2ai/ag2). Here is a [video recording](https://www.youtube.com/watch?v=xM2Uguw1UsQ) of the background context introduction presented at the Berkeley Agentic AI Summit 2025.
  34. <p align="center">
  35. <b>🧩 Use MassGen as a Skill:</b> <code>npx skills add massgen/skills --all</code> β€” then type invoke the skill in Claude Code, Cursor, Copilot, or 40+ other agents. <a href="https://github.com/massgen/skills">Learn more β†’</a>
  36. </p>
  37. <p align="center">
  38. <b>πŸ“š For Contributors:</b> See <a href="https://massgen.github.io/Handbook/">MassGen Contributor Handbook</a> - Centralized policies and resources for development and research teams
  39. </p>
  40. ---
  41. ## πŸ“‹ Table of Contents
  42. <details open>
  43. <summary><h3>✨ Key Features</h3></summary>
  44. - [Cross-Model/Agent Synergy](#-key-features-1)
  45. - [Parallel Processing](#-key-features-1)
  46. - [Intelligence Sharing](#-key-features-1)
  47. - [Consensus Building](#-key-features-1)
  48. - [Live Visualization](#-key-features-1)
  49. </details>
  50. <details open>
  51. <summary><h3>πŸ†• Latest Features</h3></summary>
  52. - [v0.1.96 Features](#-latest-features-v0196)
  53. </details>
  54. <details open>
  55. <summary><h3>πŸ—οΈ System Design</h3></summary>
  56. - [System Architecture](#%EF%B8%8F-system-design-1)
  57. - [Parallel Processing](#%EF%B8%8F-system-design-1)
  58. - [Real-time Collaboration](#%EF%B8%8F-system-design-1)
  59. - [Convergence Detection](#%EF%B8%8F-system-design-1)
  60. - [Adaptive Coordination](#%EF%B8%8F-system-design-1)
  61. </details>
  62. <details open>
  63. <summary><h3>πŸš€ Quick Start</h3></summary>
  64. - [πŸ“₯ Installation](#1--installation)
  65. - [πŸ” API Configuration](#2--api-configuration)
  66. - [🧩 Supported Models and Tools](#3--supported-models-and-tools)
  67. - [Models](#models)
  68. - [Tools](#tools)
  69. - [πŸƒ Run MassGen](#4--run-massgen)
  70. - [CLI Configuration Parameters](#cli-configuration-parameters)
  71. - [1. Single Agent (Easiest Start)](#1-single-agent-easiest-start)
  72. - [2. Multi-Agent Collaboration (Recommended)](#2-multi-agent-collaboration-recommended)
  73. - [3. Model Context Protocol (MCP)](#3-model-context-protocol-mcp)
  74. - [4. File System Operations](#4-file-system-operations--workspace-management)
  75. - [5. Project Integration (NEW in v0.0.21)](#5-project-integration--user-context-paths-new-in-v0021)
  76. - [Backend Configuration Reference](#backend-configuration-reference)
  77. - [Interactive Multi-Turn Mode](#interactive-multi-turn-mode)
  78. - [πŸ“Š View Results](#5--view-results)
  79. - [Real-time Display](#real-time-display)
  80. - [Comprehensive Logging](#comprehensive-logging)
  81. </details>
  82. <details open>
  83. <summary><h3>πŸ€– Automation & LLM Integration</h3></summary>
  84. - [Automation Mode](#-automation--llm-integration)
  85. - [BackgroundShellManager](#using-backgroundshellmanager)
  86. - [Status File Reference](#statusjson-structure)
  87. - [Full Automation Guide](https://docs.massgen.ai/en/latest/user_guide/automation.html)
  88. </details>
  89. <details open>
  90. <summary><h3>πŸ’‘ Case Studies & Examples</h3></summary>
  91. - [Case Studies](#-case-studies)
  92. </details>
  93. <details open>
  94. <summary><h3>πŸ—ΊοΈ Roadmap</h3></summary>
  95. - [Recent Achievements (v0.1.97)](#recent-achievements-v0197)
  96. - [Previous Achievements (v0.0.3 - v0.1.96)](#previous-achievements-v003---v0196)
  97. - [Key Future Enhancements](#key-future-enhancements)
  98. - Bug Fixes & Backend Improvements
  99. - Advanced Agent Collaboration
  100. - Expanded Model, Tool & Agent Integrations
  101. - Improved Performance & Scalability
  102. - Enhanced Developer Experience
  103. - [v0.1.97 Roadmap](#v0197-roadmap)
  104. </details>
  105. <details open>
  106. <summary><h3>πŸ“š Additional Resources</h3></summary>
  107. - [🀝 Contributing](#-contributing)
  108. - [πŸ“„ License](#-license)
  109. - [⭐ Star History](#-star-history)
  110. </details>
  111. ---
  112. ## ✨ Key Features
  113. | Feature | Description |
  114. |---------|-------------|
  115. | **🀝 Cross-Model/Agent Synergy** | Harness strengths from diverse frontier model-powered agents |
  116. | **⚑ Parallel Processing** | Multiple agents tackle problems simultaneously |
  117. | **πŸ‘₯ Intelligence Sharing** | Agents share and learn from each other's work |
  118. | **πŸ”„ Consensus Building** | Natural convergence through collaborative refinement |
  119. | **πŸ–₯️ Live Visualization** | Interactive Textual TUI with timeline, agent cards, and vote tracking (default). Also available: Web UI, Rich display. |
  120. ---
  121. ## πŸ†• Latest Features (v0.1.97)
  122. **πŸŽ‰ Released: June 12, 2026**
  123. **What's New in v0.1.97** (Application-Layer Permission Engine):
  124. - **πŸ›‘οΈ Layered Permission Engine** - Opt-in `permissions:` block routes every tool call through a non-overridable **hardline** floor (`rm -rf /`, fork bombs), declarative **`allow/ask/deny` rules** over a small `action(target)` algebra (deny-wins), and a **blast-radius risk classifier** β€” auto-allowing reads/in-workspace edits and asking only for the dangerous tail (egress, force-push, publish, privilege). The app-layer companion to v0.1.96's OS sandbox.
    • Dismissed after review: Runs `rm -rf` against a root or home-directory path
    • Line 163 on GitHub
  125. - **βœ‹ Approval That Fits the Run** - An `ask` resolves via an automation **policy** (`risk-based` / `deny-all` / `allow-all`) or a **file** request/response handshake for headless/remote approval (Slack bot, `/approve <id>`, …) β€” fail-closed by design.
  126. - **πŸ§‘β€πŸ€β€πŸ§‘ Roles, Audit & Guards** - Per-agent `role` presets (e.g. `read-only`, which also empties the agent's OS-sandbox writable set), an append-only JSONL **audit ledger** of every decision, a runaway-loop **budget**, `always`-grant persistence, and a channel-based **guardrail prompt** that nudges the model to surface blocks rather than circumvent them while keeping `ask` sanctioned. *(Honest scope: the prompt is best-effort alignment; the OS sandbox is the enforcement.)*
  127. **Install v0.1.97:**
  128. ```bash
  129. pip install massgen==0.1.97
  130. ```
  131. β†’ [See full release history and examples](massgen/configs/README.md#release-history--examples)
  132. ---
  133. ## πŸ—οΈ System Design
  134. MassGen operates through an architecture designed for **seamless multi-agent collaboration**:
  135. ```mermaid
  136. graph TB
  137. O[πŸš€ MassGen Orchestrator<br/>πŸ“‹ Task Distribution & Coordination]
  138. subgraph Collaborative Agents
  139. A1[Agent 1<br/>πŸ—οΈ Anthropic/Claude + Tools]
  140. A2[Agent 2<br/>🌟 Google/Gemini + Tools]
  141. A3[Agent 3<br/>πŸ€– OpenAI/GPT + Tools]
  142. A4[Agent 4<br/>⚑ xAI/Grok + Tools]
  143. end
  144. H[πŸ”„ Shared Collaboration Hub<br/>πŸ“‘ Real-time Notification & Consensus]
  145. O --> A1 & A2 & A3 & A4
  146. A1 & A2 & A3 & A4 <--> H
  147. classDef orchestrator fill:#e1f5fe,stroke:#0288d1,stroke-width:3px
  148. classDef agent fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
  149. classDef hub fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
  150. class O orchestrator
  151. class A1,A2,A3,A4 agent
  152. class H hub
  153. ```
  154. The system's workflow is defined by the following key principles:
  155. **Parallel Processing** - Multiple agents tackle the same task simultaneously, each leveraging their unique capabilities (different models, tools, and specialized approaches).
  156. **Real-time Collaboration** - Agents continuously share their working summaries and insights through a notification system, allowing them to learn from each other's approaches and build upon collective knowledge.
  157. **Convergence Detection** - The system intelligently monitors when agents have reached stability in their solutions and achieved consensus through natural collaboration rather than forced agreement.
  158. **Adaptive Coordination** - Agents can restart and refine their work when they receive new insights from others, creating a dynamic and responsive problem-solving environment.
  159. This collaborative approach ensures that the final output leverages collective intelligence from multiple AI systems, leading to more robust and well-rounded results than any single agent could achieve alone.
  160. ---
  161. > πŸ“– **Complete Documentation:** For comprehensive guides, API reference, and detailed examples, visit **[MassGen Official Documentation](https://docs.massgen.ai/)**
  162. >
  163. > πŸ€– **For AI agents:** A curated [`llms.txt`](https://docs.massgen.ai/en/latest/llms.txt) index and full [`llms-full.txt`](https://docs.massgen.ai/en/latest/llms-full.txt) dump are published with the docs ([llmstxt.org spec](https://llmstxt.org)).
  164. ---
  165. ## πŸš€ Quick Start
  166. ### 1. πŸ“₯ Installation
  167. **Method 1: PyPI Installation** (Recommended - Python 3.11+):
  168. ```bash
  169. # Install MassGen via pip
  170. pip install massgen
  171. # Or with uv (faster)
  172. pip install uv
  173. uv venv && source .venv/bin/activate
  174. uv pip install massgen
  175. # If you install massgen in uv, make sure you either activate your venv using source .venv/bin/activate
  176. # Or include "uv run" before all commands
  177. ```
  178. **Quickstart Setup** (Fastest way to get running):
  179. ```bash
  180. # Step 1: Set up API keys, Docker, and skills
  181. uv run massgen --setup
  182. # Step 2: Create a simple config and start
  183. uv run massgen --quickstart
  184. ```
  185. The `--setup` command will:
  186. - Configure your API keys (OpenAI, Anthropic, Google, xAI)
  187. - Offer to set up Docker images for code execution
  188. - Offer to install skills (openskills, Anthropic/OpenAI/Vercel collections, Agent Browser skill, Crawl4AI)
  189. The `--quickstart` command will:
  190. - Ask how many agents you want (1-5, default 3)
  191. - Ask which backend/model for each agent
  192. - For GPT-5x models, ask for `reasoning.effort` (`low|medium|high`; Codex GPT-5 models also include `xhigh`)
  193. - Auto-detect Docker availability and configure execution mode
  194. - 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
  195. - Create a ready-to-use config and launch into interactive TUI mode
  196. **πŸ€– Use MassGen from Your AI Coding Agent:**
  197. 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:
  198. ```bash
  199. npx skills add massgen/skills
  200. ```
  201. 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.
  202. **πŸ–₯️ Textual TUI (Default Display Mode):**
  203. MassGen launches with an interactive Terminal User Interface (TUI) by default, providing:
  204. - πŸ“Š **Real-time timeline** of all agent activities
  205. - 🎯 **Individual agent status cards** for each team member
  206. - πŸ—³οΈ **Vote visualization** and consensus tracking
  207. - πŸ’¬ **Multi-turn conversation** management
  208. - ⌨️ **Keyboard controls** for navigation (↑/↓ to scroll, 'q' to cancel)
  209. **Legacy Rich display:**
  210. ```bash
  211. massgen --display rich "Your question"
  212. ```
  213. **Alternative: Full Setup Wizard**
  214. For more control, use the full configuration wizard:
  215. ```bash
  216. uv run massgen --init
  217. ```
  218. This guides you through use case selection (Research, Code, Q&A, etc.) and advanced configuration options.
  219. **After setup:**
  220. ```bash
  221. # Interactive mode
  222. uv run massgen
  223. # Single query
  224. uv run massgen "Your question here"
  225. # With example configurations
  226. uv run massgen --config @examples/basic/multi/three_agents_default "Your question"
  227. ```
  228. β†’ See [Installation Guide](https://docs.massgen.ai/en/latest/quickstart/installation.html) for complete setup instructions.
  229. **Method 2: Development Installation** (for contributors):
  230. **Clone the repository**
  231. ```bash
  232. git clone https://github.com/Leezekun/MassGen.git
  233. cd MassGen
  234. ```
  235. **Install in editable mode with pip**
  236. **Option 1 (recommended): Installing with uv (faster)**
  237. ```bash
  238. uv venv
  239. source .venv/bin/activate # Windows: .venv\Scripts\activate
  240. uv pip install -e .
  241. # If you install massgen in uv, make sure you either activate your venv using source .venv/bin/activate
  242. # Or include "uv run" before all commands
  243. # Automated setup (works on all platforms) - installs dependencies, skills, Docker images, also sets up API keys
  244. uv run massgen --setup
  245. # Or use the bash script (Unix/Linux/macOS only), need manually config API keys, see sections below
  246. uv run ./scripts/init.sh
  247. # If you would like to install other dependencies later
  248. # Here is a light-weighted setup script which only installs skills (works on all platforms)
  249. uv run massgen --setup-skills
  250. # Or use the bash script (Unix/Linux/macOS only)
  251. uv run ./scripts/init_skills.sh
  252. ```
  253. **Option 2: Using traditional Python env**
  254. ```bash
  255. pip install -e .
  256. # Optional: External framework integration
  257. pip install -e ".[external]"
  258. # Automated setup (works on all platforms) - installs dependencies, skills, Docker images, also sets up API keys
  259. massgen --setup
  260. # Or use the bash script (Unix/Linux/macOS only), need manually config API keys, see sections below
  261. ./scripts/init.sh
  262. # If you would like to install other dependencies later
  263. # Here is a light-weighted setup script which only installs skills (works on all platforms)
  264. massgen --setup-skills
  265. # Or use the bash script (Unix/Linux/macOS only)
  266. ./scripts/init_skills.sh
  267. ```
  268. > **Note:** The `--setup` and `--setup-skills` commands work cross-platform (Windows, macOS, Linux). The bash scripts (`init.sh`, `init_skills.sh`) are Unix-only but provide additional dev setup like Docker image builds.
  269. <details>
  270. <summary><b>Alternative Installation Methods</b> (click to expand)</summary>
  271. **Using uv with venv:**
  272. ```bash
  273. git clone https://github.com/Leezekun/MassGen.git
  274. cd MassGen
  275. uv venv
  276. source .venv/bin/activate # Windows: .venv\Scripts\activate
  277. uv pip install -e .
  278. ```
  279. **Using traditional Python venv:**
  280. ```bash
  281. git clone https://github.com/Leezekun/MassGen.git
  282. cd MassGen
  283. python -m venv .venv
  284. source .venv/bin/activate # Windows: .venv\Scripts\activate
  285. pip install -e .
  286. ```
  287. **Global installation with uv tool:**
  288. ```bash
  289. git clone https://github.com/Leezekun/MassGen.git
  290. cd MassGen
  291. uv tool install -e .
  292. # Now run from any directory
  293. uv tool run massgen --config @examples/basic/multi/three_agents_default "Question"
  294. ```
  295. **Backwards compatibility (uv run):**
  296. ```bash
  297. cd /path/to/MassGen
  298. uv run massgen --config @examples/basic/multi/three_agents_default "Question"
  299. uv run python -m massgen.cli --config config.yaml "Question"
  300. ```
  301. </details>
  302. **Optional CLI Tools:**
  303. ```bash
  304. # Claude Code CLI - Advanced coding assistant
  305. npm install -g @anthropic-ai/claude-code
  306. # LM Studio - Local model inference
  307. # MacOS/Linux:
  308. sudo ~/.lmstudio/bin/lms bootstrap
  309. # Windows:
  310. cmd /c %USERPROFILE%\.lmstudio\bin\lms.exe bootstrap
  311. ```
  312. **After setup:**
  313. ```bash
  314. # Interactive mode
  315. uv run massgen
  316. # Single query
  317. uv run massgen "Your question here"
  318. # With example configurations
  319. uv run massgen --config @examples/basic/multi/three_agents_default "Your question"
  320. ```
  321. ### 2. πŸ” API Configuration
  322. **Create a `.env` file in your working directory with your API keys:**
  323. ```bash
  324. # Copy this template to .env and add your API keys
  325. OPENAI_API_KEY=sk-...
  326. ANTHROPIC_API_KEY=sk-ant-...
  327. GOOGLE_API_KEY=...
  328. XAI_API_KEY=...
  329. # Optional: Additional providers
  330. CEREBRAS_API_KEY=...
  331. TOGETHER_API_KEY=...
  332. GROQ_API_KEY=...
  333. OPENROUTER_API_KEY=...
  334. ```
  335. MassGen automatically loads API keys from `.env` in your current directory.
  336. β†’ **Complete setup guide with all providers:** See [API Key Configuration](https://docs.massgen.ai/en/latest/quickstart/installation.html#api-key-configuration) in the docs
  337. **Get API keys:**
  338. - [OpenAI](https://platform.openai.com/api-keys) | [Claude](https://docs.anthropic.com/en/api/overview) | [Gemini](https://ai.google.dev/gemini-api/docs) | [Grok](https://docs.x.ai/docs/overview)
  339. - [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/) | [Cerebras](https://inference-docs.cerebras.ai/introduction) | [OpenRouter](https://openrouter.ai/docs/api/api-reference/api-keys/create-keys) | [More providers...](https://docs.massgen.ai/en/latest/reference/supported_models.html)
  340. ### 3. 🧩 Supported Models and Tools
  341. #### Models
  342. The system currently supports multiple model providers with advanced capabilities:
  343. **API-based Models:**
  344. - **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
  345. - **Note**: We recommend GPT-5.2/5.1/5 over Codex models. Codex models are [optimized for shorter system messages](https://cookbook.openai.com/examples/gpt-5-codex_prompting_guide) and may not work well with MassGen's coordination prompts.
  346. - **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.
  347. - **Azure OpenAI**: Any Azure-deployed models (GPT-4, GPT-4o, GPT-35-turbo, etc.)
  348. - **Claude / Anthropic**: Claude Opus 4.5, Claude Haiku 4.5, Claude Sonnet 4.5, Claude Opus 4.1, Claude Sonnet 4
  349. - Advanced tooling: web search, code execution, Files API, programmatic tool calling, tool search with deferred loading
  350. - **Claude Code**: Native Claude Code SDK with server-side session persistence and built-in dev tools
  351. - **Gemini**: Gemini 3 Pro, Gemini 2.5 Flash, Gemini 2.5 Pro with code execution and grounding
  352. - **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
  353. - **Grok / xAI**: Grok-4.1, Grok-4, Grok-3, Grok-3-mini with Grok Live Search
  354. - **Cerebras AI**: Ultra-fast inference for supported models
  355. - **Together AI**, **Fireworks AI**, **Groq**: Fast inference for LLaMA, Mistral, Qwen, and other open models
  356. - **OpenRouter**: Multi-model aggregator with dynamic model listing (400+ models)
  357. - **Kimi / Moonshot**: Chinese AI models via OpenAI-compatible API
  358. - **Nebius AI Studio**: Cloud inference platform
  359. - **POE**: Quora AI platform with dynamic model discovery
  360. - **Qwen / Alibaba**: DashScope API for Qwen models
  361. - **Z AI / Zhipu**: GLM-4.5 and related models
  362. **Local Model Support:**
  363. - **vLLM & SGLang**: Unified inference backend supporting both vLLM and SGLang servers
  364. - vLLM (port 8000) and SGLang (port 30000) with OpenAI-compatible API
  365. - Support for `top_k`, `repetition_penalty`, `chat_template_kwargs` parameters
  366. - SGLang-specific `separate_reasoning` parameter for thinking models
  367. - Mixed server deployments with configuration example: `two_qwen_vllm_sglang.yaml`
  368. - **LM Studio**: Run open-weight models locally with automatic server management
  369. - Automatic LM Studio CLI installation
  370. - Auto-download and loading of models
  371. - Support for LLaMA, Mistral, Qwen and other open-weight models
  372. β†’ For complete model list and configuration details, see [Supported Models](https://docs.massgen.ai/en/latest/reference/supported_models.html)
  373. #### Tools
  374. MassGen agents can leverage various tools to enhance their problem-solving capabilities:
  375. - **Built-in Tools**: Web search, code execution, bash/shell (provider-dependent)
  376. - **Filesystem**: Native file operations or via MCP
  377. - **MCP Integration**: Connect to any MCP server for extended capabilities
  378. - **Custom Tools**: Define your own tools via YAML configuration
  379. - **Multimodal**: Image, audio, video understanding and generation (native or via custom tools)
  380. β†’ For detailed backend capabilities and tool support matrix, see [User Guide - Backends](https://docs.massgen.ai/en/latest/user_guide/backends.html#backend-capabilities)
  381. ---
  382. ### 4. πŸƒ Run MassGen
  383. > **Complete Usage Guide:** For all usage modes, advanced features, and interactive multi-turn sessions, see [Running MassGen](https://docs.massgen.ai/en/latest/quickstart/running-massgen.html)
  384. #### πŸš€ Getting Started
  385. #### CLI Configuration Parameters
  386. | Parameter | Description |
  387. |-------------------|-------------|
  388. | `--config` | Path to YAML configuration file with agent definitions, model parameters, backend parameters and UI settings |
  389. | `--backend` | Backend type for quick setup without a config file (`claude`, `claude_code`, `gemini`, `grok`, `openai`, `azure_openai`, `zai`). Optional for [models with default backends](massgen/utils.py).|
  390. | `--model` | Model name for quick setup (e.g., `gemini-2.5-flash`, `gpt-5-nano`, ...). `--config` and `--model` are mutually exclusive - use one or the other. |
  391. | `--system-message` | System prompt for the agent in quick setup mode. If `--config` is provided, `--system-message` is omitted. |
  392. | `--cwd-context` | Add current working directory as runtime context path: `ro`/`read` for read-only, `rw`/`write` for write access. In TUI, this initializes the same state as `Ctrl+P`. |
  393. | `--plan` | Planning-only mode. Agents create a structured task plan without auto-executing it. |
  394. | `--plan-depth` | Plan granularity for `--plan`: `dynamic`, `shallow`, `medium`, or `deep`. |
  395. | `--plan-and-execute` | Run both phases: create a plan, then execute it automatically. |
  396. | `--execute-plan` | Execute an existing plan by path, plan ID, or `latest`. |
  397. | `--no-display` | Disable real-time streaming UI coordination display (fallback to simple text output).|
  398. | `--no-logs` | Disable real-time logging.|
  399. | `--debug` | Enable debug mode with verbose logging (NEW in v0.0.13). Shows detailed orchestrator activities, agent messages, backend operations, and tool calls. Debug logs are saved to `agent_outputs/log_{time}/massgen_debug.log`. |
  400. | `"<your question>"` | Optional single-question input; if omitted, MassGen enters interactive chat mode. |
  401. #### **0. OpenAI-Compatible HTTP Server (NEW)**
  402. Run MassGen as an **OpenAI-compatible** HTTP API (FastAPI + Uvicorn). This is useful for integrating MassGen with existing tooling that expects `POST /v1/chat/completions`.
  403. ```bash
  404. # Start server (defaults: host 0.0.0.0, port 4000)
  405. massgen serve
  406. # With explicit bind + defaults for model/config
  407. massgen serve --host 0.0.0.0 --port 4000 --config path/to/config.yaml --default-model gpt-5
  408. ```
  409. **Endpoints**
  410. - `GET /health`
  411. - `POST /v1/chat/completions` (supports `stream: true` SSE and OpenAI-style tool calling)
  412. **cURL examples**
  413. ```bash
  414. # Health
  415. curl http://localhost:4000/health
  416. # Non-streaming chat completion
  417. curl http://localhost:4000/v1/chat/completions \
  418. -H "Content-Type: application/json" \
  419. -d '{
  420. "model": "massgen",
  421. "messages": [{"role": "user", "content": "hi"}],
  422. "stream": false
  423. }'
  424. # Streaming (Server-Sent Events)
  425. curl -N http://localhost:4000/v1/chat/completions \
  426. -H "Content-Type: application/json" \
  427. -d '{
  428. "model": "massgen",
  429. "messages": [{"role": "user", "content": "hi"}],
  430. "stream": true
  431. }'
  432. ```
  433. **Notes**
  434. - Client-provided `tools` are supported, but tool names that collide with MassGen workflow tools are rejected.
  435. - Environment variables (optional): `MASSGEN_SERVER_HOST`, `MASSGEN_SERVER_PORT`, `MASSGEN_SERVER_DEFAULT_CONFIG`, `MASSGEN_SERVER_DEFAULT_MODEL`, `MASSGEN_SERVER_DEBUG`.
  436. #### **1. Single Agent (Easiest Start)**
  437. **Quick Start Commands:**
  438. ```bash
  439. # Quick test with any supported model - no configuration needed
  440. uv run python -m massgen.cli --model claude-sonnet-4-5-20250929 "What is machine learning?"
  441. uv run python -m massgen.cli --model gemini-3-pro-preview "Explain quantum computing"
  442. uv run python -m massgen.cli --model gpt-5-nano "Summarize the latest AI developments"
  443. ```
  444. **Configuration:**
  445. Use the `agent` field to define a single agent with its backend and settings:
  446. ```yaml
  447. agent:
  448. id: "<agent_name>"
  449. backend:
  450. type: "azure_openai" | "chatcompletion" | "claude" | "claude_code" | "gemini" | "grok" | "openai" | "zai" | "lmstudio" #Type of backend
  451. model: "<model_name>" # Model name
  452. api_key: "<optional_key>" # API key for backend. Uses env vars by default.
  453. system_message: "..." # System Message for Single Agent
  454. ```
  455. β†’ [See all single agent configs](massgen/configs/basic/single/)
  456. #### **2. Multi-Agent Collaboration (Recommended)**
  457. **Configuration:**
  458. Use the `agents` field to define multiple agents, each with its own backend and config:
  459. **Quick Start Commands:**
  460. ```bash
  461. # Three powerful agents working together - Gemini, GPT-5, and Grok
  462. massgen --config @examples/basic/multi/three_agents_default \
  463. "Analyze the pros and cons of renewable energy"
  464. ```
  465. **This showcases MassGen's core strength:**
  466. - **Gemini 3 Pro** - Fast research with web search
  467. - **GPT-5 Nano** - Advanced reasoning with code execution
  468. - **Grok-4 Fast** - Real-time information and alternative perspectives
  469. ```yaml
  470. agents: # Multiple agents (alternative to 'agent')
  471. - id: "<agent1 name>"
  472. backend:
  473. type: "azure_openai" | "chatcompletion" | "claude" | "claude_code" | "gemini" | "grok" | "openai" | "zai" | "lmstudio" #Type of backend
  474. model: "<model_name>" # Model name
  475. api_key: "<optional_key>" # API key for backend. Uses env vars by default.
  476. system_message: "..." # System Message for Single Agent
  477. - id: "..."
  478. backend:
  479. type: "..."
  480. model: "..."
  481. ...
  482. system_message: "..."
  483. ```
  484. β†’ [Explore more multi-agent setups](massgen/configs/basic/multi/)
  485. #### **3. Model context protocol (MCP)**
  486. The [Model context protocol](https://modelcontextprotocol.io/) (MCP) standardises how applications expose tools and context to language models. From the official documentation:
  487. >MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.
  488. **MCP Configuration Parameters:**
  489. | Parameter | Type | Required | Description |
  490. |-----------|------|----------|-------------|
  491. | `mcp_servers` | dict | **Yes** (for MCP) | Container for MCP server definitions |
  492. | └─ `type` | string | Yes | Transport: `"stdio"` or `"streamable-http"` |
  493. | └─ `command` | string | stdio only | Command to run the MCP server |
  494. | └─ `args` | list | stdio only | Arguments for the command |
  495. | └─ `url` | string | http only | Server endpoint URL |
  496. | └─ `env` | dict | No | Environment variables to pass |
  497. | `allowed_tools` | list | No | Whitelist specific tools (if omitted, all tools available) |
  498. | `exclude_tools` | list | No | Blacklist dangerous/unwanted tools |
  499. **Quick Start Commands ([Check backend MCP support here](#tools)):**
  500. ```bash
  501. # Weather service with GPT-5
  502. massgen --config @examples/tools/mcp/gpt5_nano_mcp_example \
  503. "What's the weather forecast for New York this week?"
  504. # Multi-tool MCP with Gemini - Search + Weather + Filesystem (Requires BRAVE_API_KEY in .env)
  505. massgen --config @examples/tools/mcp/multimcp_gemini \
  506. "Find the best restaurants in Paris and save the recommendations to a file"
  507. ```
  508. **Configuration:**
  509. ```yaml
  510. agents:
  511. # Basic MCP Configuration:
  512. backend:
  513. type: "openai" # Your backend choice
  514. model: "gpt-5-mini" # Your model choice
  515. # Add MCP servers here
  516. mcp_servers:
  517. weather: # Server name (you choose this)
  518. type: "stdio" # Communication type
  519. command: "npx" # Command to run
  520. args: ["-y", "@modelcontextprotocol/server-weather"] # MCP server package
  521. # That's it! The agent can now check weather.
  522. # Multiple MCP Tools Example:
  523. backend:
  524. type: "gemini"
  525. model: "gemini-3.0-pro-preview"
  526. mcp_servers:
  527. # Web search
  528. search:
  529. type: "stdio"
  530. command: "npx"
  531. args: ["-y", "@modelcontextprotocol/server-brave-search"]
  532. env:
  533. BRAVE_API_KEY: "${BRAVE_API_KEY}" # Set in .env file
  534. # HTTP-based MCP server (streamable-http transport)
  535. custodm_api:
  536. type: "streamable-http" # For HTTP/SSE servers
  537. url: "http://localhost:8080/mcp/sse" # Server endpoint
  538. # Tool configuration (MCP tools are auto-discovered)
  539. allowed_tools: # Optional: whitelist specific tools
  540. - "mcp__weather__get_current_weather"
  541. - "mcp__test_server__mcp_echo"
  542. - "mcp__test_server__add_numbers"
  543. exclude_tools: # Optional: blacklist specific tools
  544. - "mcp__test_server__current_time"
  545. ```
  546. β†’ [View more MCP examples](massgen/configs/tools/mcp/)
  547. β†’ For comprehensive MCP integration guide, see [MCP Integration](https://docs.massgen.ai/en/latest/user_guide/mcp_integration.html)
  548. #### **4. File System Operations & Workspace Management**
  549. MassGen provides comprehensive file system support through multiple backends, enabling agents to read, write, and manipulate files in organized workspaces.
  550. **Filesystem Configuration Parameters:**
  551. | Parameter | Type | Required | Description |
  552. |-----------|------|----------|-------------|
  553. | `cwd` | string | **Yes** (for file ops) | Working directory for file operations (agent-specific workspace) |
  554. | `snapshot_storage` | string | Yes | Directory for workspace snapshots |
  555. | `agent_temporary_workspace` | string | Yes | Parent directory for temporary workspaces |
  556. **Quick Start Commands:**
  557. ```bash
  558. # File operations with Claude Code
  559. massgen --config @examples/tools/filesystem/claude_code_single \
  560. "Create a Python web scraper and save results to CSV"
  561. # Multi-agent file collaboration
  562. massgen --config @examples/tools/filesystem/claude_code_context_sharing \
  563. "Generate a comprehensive project report with charts and analysis"
  564. ```
  565. **Configuration:**
  566. ```yaml
  567. # Basic Workspace Setup:
  568. agents:
  569. - id: "file-agent"
  570. backend:
  571. type: "claude_code" # Backend with file support
  572. cwd: "workspace" # Isolated workspace for file operations
  573. # Multi-Agent Workspace Isolation:
  574. agents:
  575. - id: "agent_a"
  576. backend:
  577. type: "claude_code"
  578. cwd: "workspace1" # Agent-specific workspace
  579. - id: "agent_b"
  580. backend:
  581. type: "gemini"
  582. cwd: "workspace2" # Separate workspace
  583. orchestrator:
  584. snapshot_storage: "snapshots" # Shared snapshots directory
  585. agent_temporary_workspace: "temp_workspaces" # Temporary workspace management
  586. ```
  587. **Available File Operations:**
  588. - **Claude Code**: Built-in tools (Read, Write, Edit, MultiEdit, Bash, Grep, Glob, LS, TodoWrite)
  589. - **Other Backends**: Via [MCP Filesystem Server](https://github.com/modelcontextprotocol/servers/blob/main/src%2Ffilesystem%2FREADME.md)
  590. **Workspace Management:**
  591. - **Isolated Workspaces**: Each agent's `cwd` is fully isolated and writable
  592. - **Snapshot Storage**: Share workspace context between Claude Code agents
  593. - **Temporary Workspaces**: Agents can access previous coordination results
  594. β†’ [View more filesystem examples](massgen/configs/tools/filesystem/)
  595. > ⚠️ **IMPORTANT SAFETY WARNING**
  596. >
  597. > MassGen agents can **autonomously read, write, modify, and delete files** within their permitted directories.
  598. >
  599. > **Before running MassGen with filesystem access:**
  600. > - Only grant access to directories you're comfortable with agents modifying
  601. > - Use the permission system to restrict write access where needed
  602. > - Consider testing in an isolated directory or virtual environment first
  603. > - Back up important files before granting write access
  604. > - Review the `context_paths` configuration carefully
  605. >
  606. > The agents will execute file operations without additional confirmation once permissions are granted.
  607. β†’ For comprehensive file operations guide, see [File Operations](https://docs.massgen.ai/en/latest/user_guide/file_operations.html)
  608. #### **5. Project Integration & User Context Paths (NEW in v0.0.21)**
  609. Work directly with your existing projects! User Context Paths allow you to share specific directories with all agents while maintaining granular permission control. This enables secure multi-agent collaboration on your real codebases, documentation, and data.
  610. MassGen automatically organizes all its working files under a `.massgen/` directory in your project root, keeping your project clean and making it easy to exclude MassGen's temporary files from version control.
  611. **Project Integration Parameters:**
  612. | Parameter | Type | Required | Description |
  613. |-----------|------|----------|-------------|
  614. | `context_paths` | list | **Yes** (for project integration) | Shared directories for all agents |
  615. | └─ `path` | string | Yes | Absolute or relative path to your project directory (**must be directory, not file**) |
  616. | └─ `permission` | string | Yes | Access level: `"read"` or `"write"` (write applies only to final agent) |
  617. | └─ `protected_paths` | list | No | Files/directories immune from modification (relative to context path) |
  618. **⚠️ Important Notes:**
  619. - Context paths must point to **directories**, not individual files
  620. - Paths can be **absolute** or **relative** (resolved against current working directory)
  621. - **Write permissions** apply only to the **final agent** during presentation phase
  622. - During coordination, all context paths are **read-only** to protect your files
  623. - MassGen validates all paths during startup and will show clear error messages for missing paths or file paths
  624. **Quick Start Commands:**
  625. ```bash
  626. # Multi-agent collaboration to improve the website in `massgen/configs/resources/v0.0.21-example
  627. 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."
  628. ```
  629. **Configuration:**
  630. ```yaml
  631. # Basic Project Integration:
  632. agents:
  633. - id: "code-reviewer"
  634. backend:
  635. type: "claude_code"
  636. cwd: "workspace" # Agent's isolated work area
  637. orchestrator:
  638. context_paths:
  639. - path: "." # Current directory (relative path)
  640. permission: "write" # Final agent can create/modify files
  641. protected_paths: # Optional: files immune from modification
  642. - ".env"
  643. - "config.json"
  644. - path: "/home/user/my-project/src" # Absolute path example
  645. permission: "read" # Agents can analyze your code
  646. # Advanced: Multi-Agent Project Collaboration
  647. agents:
  648. - id: "analyzer"
  649. backend:
  650. type: "gemini"
  651. cwd: "analysis_workspace"
  652. - id: "implementer"
  653. backend:
  654. type: "claude_code"
  655. cwd: "implementation_workspace"
  656. orchestrator:
  657. context_paths:
  658. - path: "../legacy-app/src" # Relative path to existing codebase
  659. permission: "read" # Read existing codebase
  660. - path: "../legacy-app/tests"
  661. permission: "write" # Final agent can write new tests
  662. protected_paths: # Protect specific test files
  663. - "integration_tests/production_data_test.py"
  664. - path: "/home/user/modernized-app" # Absolute path
  665. permission: "write" # Final agent can create modernized version
  666. ```
  667. **This showcases project integration:**
  668. - **Real Project Access** - Work with your actual codebases, not copies
  669. - **Secure Permissions** - Granular control over what agents can read/modify
  670. - **Multi-Agent Collaboration** - Multiple agents safely work on the same project
  671. - **Context Agents** (during coordination): Always READ-only access to protect your files
  672. - **Final Agent** (final execution): Gets the configured permission (READ or write)
  673. **Use Cases:**
  674. - **Code Review**: Agents analyze your source code and suggest improvements
  675. - **Documentation**: Agents read project docs to understand context and generate updates
  676. - **Data Processing**: Agents access shared datasets and generate analysis reports
  677. - **Project Migration**: Agents examine existing projects and create modernized versions
  678. **Clean Project Organization:**
  679. ```
  680. your-project/
  681. β”œβ”€β”€ .massgen/ # All MassGen state
  682. β”‚ β”œβ”€β”€ sessions/ # Multi-turn conversation history (if using interactively)
  683. β”‚ β”‚ └── session_20240101_143022/
  684. β”‚ β”‚ β”œβ”€β”€ turn_1/ # Results from turn 1
  685. β”‚ β”‚ β”œβ”€β”€ turn_2/ # Results from turn 2
  686. β”‚ β”‚ └── SESSION_SUMMARY.txt # Human-readable summary
  687. β”‚ β”œβ”€β”€ workspaces/ # Agent working directories
  688. β”‚ β”‚ β”œβ”€β”€ agent1/ # Individual agent workspaces
  689. β”‚ β”‚ └── agent2/
  690. β”‚ β”œβ”€β”€ snapshots/ # Workspace snapshots for coordination
  691. β”‚ └── temp_workspaces/ # Previous turn results for context
  692. β”œβ”€β”€ massgen/
  693. └── ...
  694. ```
  695. **Benefits:**
  696. - βœ… **Clean Projects** - All MassGen files contained in one directory
  697. - βœ… **Easy Gitignore** - Just add `.massgen/` to `.gitignore`
  698. - βœ… **Portable** - Move or delete `.massgen/` without affecting your project
  699. - βœ… **Multi-Turn Sessions** - Conversation history preserved across sessions
  700. **Configuration Auto-Organization:**
  701. ```yaml
  702. orchestrator:
  703. # User specifies simple names - MassGen organizes under .massgen/
  704. snapshot_storage: "snapshots" # β†’ .massgen/snapshots/
  705. agent_temporary_workspace: "temp" # β†’ .massgen/temp/
  706. agents:
  707. - backend:
  708. cwd: "workspace1" # β†’ .massgen/workspaces/workspace1/
  709. ```
  710. β†’ For comprehensive project integration guide, see [Project Integration](https://docs.massgen.ai/en/latest/user_guide/project_integration.html)
  711. **Security Considerations:**
  712. - **Agent ID Safety**: Avoid using agent+incremental digits for IDs (e.g., `agent1`, `agent2`). This may cause ID exposure during voting
  713. - **File Access Control**: Restrict file access using MCP server configurations when needed
  714. - **Path Validation**: All context paths are validated to ensure they exist and are directories (not files)
  715. - **Directory-Only Context Paths**: Context paths must point to directories, not individual files
  716. ---
  717. #### Additional Examples by Provider
  718. **Claude (Recursive MCP Execution - v0.0.20+)**
  719. ```bash
  720. # Claude with advanced tool chaining
  721. massgen --config @examples/tools/mcp/claude_mcp_example \
  722. "Research and compare weather in Beijing and Shanghai"
  723. ```
  724. **OpenAI (GPT-5 Series with MCP - v0.0.17+)**
  725. ```bash
  726. # GPT-5 with weather and external tools
  727. massgen --config @examples/tools/mcp/gpt5_nano_mcp_example \
  728. "What's the weather of Tokyo"
  729. ```
  730. **Gemini (Multi-Server MCP - v0.0.15+)**
  731. ```bash
  732. # Gemini with multiple MCP services
  733. massgen --config @examples/tools/mcp/multimcp_gemini \
  734. "Find accommodations in Paris with neighborhood analysis" # (requires BRAVE_API_KEY in .env)
  735. ```
  736. **Claude Code (Development Tools)**
  737. ```bash
  738. # Professional development environment with auto-configured workspace
  739. uv run python -m massgen.cli \
  740. --backend claude_code \
  741. --model sonnet \
  742. "Create a Flask web app with authentication"
  743. # Default workspace directories created automatically:
  744. # - workspace1/ (working directory)
  745. # - snapshots/ (workspace snapshots)
  746. # - temp_workspaces/ (temporary agent workspaces)
  747. ```
  748. **Local Models (LM Studio - v0.0.7+)**
  749. ```bash
  750. # Run open-source models locally
  751. massgen --config @examples/providers/local/lmstudio \
  752. "Explain machine learning concepts"
  753. ```
  754. β†’ [Browse by provider](massgen/configs/providers/) | [Browse by tools](massgen/configs/tools/) | [Browse teams](massgen/configs/teams/)
  755. #### Additional Use Case Examples
  756. **Question Answering & Research:**
  757. ```bash
  758. # Complex research with multiple perspectives
  759. massgen --config @examples/basic/multi/gemini_gpt5_claude \
  760. "What's best to do in Stockholm in October 2025"
  761. # Specific research requirements
  762. massgen --config @examples/basic/multi/gemini_gpt5_claude \
  763. "Give me all the talks on agent frameworks in Berkeley Agentic AI Summit 2025"
  764. ```
  765. **Creative Writing:**
  766. ```bash
  767. # Story generation with multiple creative agents
  768. massgen --config @examples/basic/multi/gemini_gpt5_claude \
  769. "Write a short story about a robot who discovers music"
  770. ```
  771. **Development & Coding:**
  772. ```bash
  773. # Full-stack development with file operations
  774. massgen --config @examples/tools/filesystem/claude_code_single \
  775. "Create a Flask web app with authentication"
  776. ```
  777. **Web Automation:** (still in test)
  778. ```bash
  779. # Browser automation with screenshots and reporting
  780. # Prerequisites: npm install @playwright/mcp@latest (for Playwright MCP server)
  781. massgen --config @examples/tools/code-execution/multi_agent_playwright_automation \
  782. "Browse three issues in https://github.com/Leezekun/MassGen and suggest documentation improvements. Include screenshots and suggestions in a website."
  783. # Data extraction and analysis
  784. massgen --config @examples/tools/code-execution/multi_agent_playwright_automation \
  785. "Navigate to https://news.ycombinator.com, extract the top 10 stories, and create a summary report"
  786. ```
  787. β†’ [**See detailed case studies**](docs/source/examples/case_studies/README.md) with real session logs and outcomes
  788. #### Interactive Mode & Advanced Usage
  789. **Multi-Turn Conversations:**
  790. ```bash
  791. # Start interactive chat (no initial question)
  792. massgen --config @examples/basic/multi/three_agents_default
  793. # Add CWD context quickly (read-only)
  794. massgen --config @examples/basic/multi/three_agents_default --cwd-context ro
  795. # Add CWD context quickly (read+write)
  796. massgen --config @examples/basic/multi/three_agents_default --cwd-context rw
  797. # Debug mode for troubleshooting
  798. massgen --config @examples/basic/multi/three_agents_default \
  799. --debug "Your question"
  800. ```
  801. ## Configuration Files
  802. MassGen configurations are organized by features and use cases. See the [Configuration Guide](massgen/configs/README.md) for detailed organization and examples.
  803. **Quick navigation:**
  804. - **Basic setups**: [Single agent](massgen/configs/basic/single/) | [Multi-agent](massgen/configs/basic/multi/)
  805. - **Tool integrations**: [MCP servers](massgen/configs/tools/mcp/) | [Web search](massgen/configs/tools/web-search/) | [Filesystem](massgen/configs/tools/filesystem/)
  806. - **Provider examples**: [OpenAI](massgen/configs/providers/openai/) | [Claude](massgen/configs/providers/claude/) | [Gemini](massgen/configs/providers/gemini/)
  807. - **Specialized teams**: [Creative](massgen/configs/teams/creative/) | [Research](massgen/configs/teams/research/) | [Development](massgen/configs/teams/development/)
  808. See MCP server setup guides: [Discord MCP](massgen/configs/docs/DISCORD_MCP_SETUP.md) | [Twitter MCP](massgen/configs/docs/TWITTER_MCP_ENESCINAR_SETUP.md)
  809. #### Backend Configuration Reference
  810. For detailed configuration of all supported backends (OpenAI, Claude, Gemini, Grok, etc.), see:
  811. β†’ **[Backend Configuration Guide](massgen/configs/BACKEND_CONFIGURATION.md)**
  812. #### Interactive Multi-Turn Mode
  813. MassGen supports an interactive mode where you can have ongoing conversations with the system:
  814. ```bash
  815. # Start interactive mode with a single agent (no tool enabled by default)
  816. uv run python -m massgen.cli --model gpt-5-mini
  817. # Start interactive mode with configuration file
  818. uv run python -m massgen.cli \
  819. --config massgen/configs/basic/multi/three_agents_default.yaml
  820. ```
  821. **Interactive Mode Features:**
  822. - **Multi-turn conversations**: Multiple agents collaborate to chat with you in an ongoing conversation
  823. - **Real-time coordination tracking**: Live visualization of agent interactions, votes, and decision-making processes
  824. - **Real-time feedback**: Displays real-time agent and system status with enhanced coordination visualization
  825. - **Multi-line input**: Use `"""` or `'''` to enter multi-line messages
  826. - **Slash commands**:
  827. - `/help` or `/h` - Show available commands
  828. - `/status` - Display current system status
  829. - `/config` - Open the configuration file
  830. - `/clear` or `/reset` - Clear conversation history and start fresh
  831. - `/quit`, `/exit`, or `/q` - Exit the session (or press `Ctrl+C`)
  832. **Watch the recorded demo:**
  833. [![MassGen Case Study](https://img.youtube.com/vi/h1R7fxFJ0Zc/0.jpg)](https://www.youtube.com/watch?v=h1R7fxFJ0Zc)
  834. ### 5. πŸ“Š View Results
  835. The system provides multiple ways to view and analyze results:
  836. #### Real-time Display
  837. - **Live Collaboration View**: See agents working in parallel through a multi-region terminal display
  838. - **Status Updates**: Real-time phase transitions, voting progress, and consensus building
  839. - **Streaming Output**: Watch agents' reasoning and responses as they develop
  840. **Watch an example here:**
  841. [![MassGen Case Study](https://img.youtube.com/vi/Dp2oldJJImw/0.jpg)](https://www.youtube.com/watch?v=Dp2oldJJImw)
  842. #### Comprehensive Logging
  843. All sessions are automatically logged with detailed information for debugging and analysis.
  844. **Real-time Interaction:**
  845. - Press `r` during execution to view the coordination table in your terminal
  846. - Watch agents collaborate, vote, and reach consensus in real-time
  847. ##### Logging Storage Structure
  848. ```
  849. .massgen/
  850. └── massgen_logs/
  851. └── log_YYYYMMDD_HHMMSS/ # Timestamped log directory
  852. β”œβ”€β”€ agent_<id>/ # Agent-specific coordination logs
  853. β”‚ └── YYYYMMDD_HHMMSS_NNNNNN/ # Timestamped coordination steps
  854. β”‚ β”œβ”€β”€ answer.txt # Agent's answer at this step
  855. β”‚ β”œβ”€β”€ context.txt # Context available to agent
  856. β”‚ └── workspace/ # Agent workspace (if filesystem tools used)
  857. β”œβ”€β”€ agent_outputs/ # Consolidated output files
  858. β”‚ β”œβ”€β”€ agent_<id>.txt # Complete output from each agent
  859. β”‚ β”œβ”€β”€ final_presentation_agent_<id>.txt # Winning agent's final answer
  860. β”‚ β”œβ”€β”€ final_presentation_agent_<id>_latest.txt # Symlink to latest
  861. β”‚ └── system_status.txt # System status and metadata
  862. β”œβ”€β”€ final/ # Final presentation phase
  863. β”‚ └── agent_<id>/ # Winning agent's final work
  864. β”‚ β”œβ”€β”€ answer.txt # Final answer
  865. β”‚ └── context.txt # Final context
  866. β”œβ”€β”€ coordination_events.json # Structured coordination events
  867. β”œβ”€β”€ coordination_table.txt # Human-readable coordination table
  868. β”œβ”€β”€ vote.json # Final vote tallies and consensus data
  869. β”œβ”€β”€ massgen.log # Complete debug log (or massgen_debug.log in debug mode)
  870. β”œβ”€β”€ snapshot_mappings.json # Workspace snapshot metadata
  871. └── execution_metadata.yaml # Query, config, and execution details
  872. ```
  873. ##### Key Log Files
  874. - **Coordination Table** (`coordination_table.txt`): Complete visualization of multi-agent coordination with event timeline, voting patterns, and consensus building
  875. - **Coordination Events** (`coordination_events.json`): Structured JSON log of all events (started_streaming, new_answer, vote, restart, final_answer)
  876. - **Vote Summary** (`vote.json`): Final vote tallies, winning agent, and consensus information
  877. - **Execution Metadata** (`execution_metadata.yaml`): Original query, timestamp, configuration, and execution context for reproducibility
  878. - **Agent Outputs** (`agent_outputs/`): Complete output history and final presentations from all agents
  879. - **Debug Log** (`massgen.log`): Complete system operations, API calls, tool usage, and error traces (use `--debug` for verbose logging)
  880. β†’ For comprehensive logging guide and debugging techniques, see [Logging & Debugging](https://docs.massgen.ai/en/latest/user_guide/logging.html)
  881. ---
  882. ## πŸ€– Automation & LLM Integration
  883. **β†’ For LLM agents: See [AI_USAGE.md](AI_USAGE.md) for complete command-line usage guide**
  884. MassGen provides **automation mode** designed for LLM agents and programmatic workflows:
  885. ### Quick Start - Automation Mode
  886. ```bash
  887. # Run with minimal output and status tracking
  888. uv run massgen --automation --config your_config.yaml "Your question"
  889. ```
  890. ### Comprehensive Guide
  891. β†’ **Full automation guide with examples:** [Automation Guide](https://docs.massgen.ai/en/latest/user_guide/automation.html)
  892. Topics covered:
  893. - Complete automation patterns with error handling
  894. - Parallel experiment execution
  895. - Performance tips and troubleshooting
  896. ### Python API & LiteLLM
  897. Use MassGen programmatically with the familiar LiteLLM/OpenAI interface:
  898. ```python
  899. from dotenv import load_dotenv
  900. load_dotenv() # Load API keys from .env
  901. import litellm
  902. from massgen import register_with_litellm
  903. register_with_litellm()
  904. # Multi-agent with slash format: "backend/model"
  905. response = litellm.completion(
  906. model="massgen/build",
  907. messages=[{"role": "user", "content": "Compare AI approaches"}],
  908. optional_params={"models": ["openai/gpt-5", "groq/llama-3.3-70b"]}
  909. )
  910. print(response.choices[0].message.content) # Final consensus answer
  911. ```
  912. Or use the direct Python API:
  913. ```python
  914. from dotenv import load_dotenv
  915. load_dotenv()
  916. import asyncio
  917. import massgen
  918. result = asyncio.run(massgen.run(
  919. query="What is machine learning?",
  920. models=["openai/gpt-5", "gemini/gemini-3-pro-preview"]
  921. ))
  922. print(result["final_answer"]) # Consensus answer from winning agent
  923. ```
  924. > **Full API reference:** [Programmatic API Guide](https://docs.massgen.ai/en/latest/user_guide/integration/python_api.html)
  925. ---
  926. ## πŸ’‘ Case Studies
  927. To see how MassGen works in practice, check out these detailed case studies based on real session logs:
  928. **Featured:**
  929. - [**Multi-Turn Persistent Memory**](docs/source/examples/case_studies/multi-turn-persistent-memory.md) - Research-to-implementation workflow demonstrating memory system (v0.1.5) | [πŸ“Ή Watch Demo](https://youtu.be/wWxxFgyw40Y)
  930. **All Case Studies:**
  931. - [**MassGen Case Studies**](docs/source/examples/case_studies/README.md)
  932. - [**Case Studies Documentation**](https://docs.massgen.ai/en/latest/examples/case_studies.html) - Browse case studies online
  933. ---
  934. ## πŸ—ΊοΈ Roadmap
  935. MassGen is currently in its foundational stage, with a focus on parallel, asynchronous multi-agent collaboration and orchestration. Our roadmap is centered on transforming this foundation into a highly robust, intelligent, and user-friendly system, while enabling frontier research and exploration.
  936. ⚠️ **Early Stage Notice:** As MassGen is in active development, please expect upcoming breaking architecture changes as we continue to refine and improve the system.
  937. ### Recent Achievements (v0.1.97)
  938. **πŸŽ‰ Released: June 12, 2026**
  939. #### Application-Layer Permission Engine
  940. - **Permission engine (opt-in `permissions:` block)**: a composite `PreToolUse` pipeline in `massgen/permissions/` β€” a non-overridable **hardline** blocklist (`hardline.py`: `rm -rf /`, fork bombs, raw-disk `dd`), a declarative **`action(target)` rule layer** (`rules.py`: `command`/`read_file`/`write_file`/`read_url`/`mcp`/`*`, deny-wins across scopes), and a **blast-radius `RiskClassifier`** that tiers by what the call does (egress/force-push/publish/privilege β†’ high; reads/in-workspace edits β†’ low). An explicit rule suppresses the risk-ask, so rules + risk live in one hook
  941. - **Approval round-trip**: the `base_with_custom_tool_and_mcp` chokepoint resolves an `ask` via a pluggable `ApprovalProvider` β€” automation **policy** (`risk-based` default / `deny-all` / `allow-all`) and **file** request/response handshake for headless/remote (both live-verified, fail-closed on timeout)
  942. - **Roles, audit & guards**: per-agent `role` presets (`read-only`/`researcher` deny writes+shell, also empties the agent's SRT writable set), an append-only JSONL **`ApprovalLedger`**, a runaway-loop **`ApprovalBudget`**, and `always`-grant persistence to `settings.local.json`
  943. - **Guardrail system prompt** (`PermissionGuardrailSection`, injected only when the engine is active): follow the guardrails, don't circumvent a denial, surface-and-ask β€” while keeping `ask` a sanctioned path. Authority is established by channel (only the system prompt is authoritative). Denied tool calls now render as **first-class failed tool events** (with the command) in the TUI/WebUI timeline
  944. - **Presence-gated & honest**: a config with no `permissions:` block is 100% unchanged; native backends (claude_code/codex) report **INACTIVE** rather than silently inert. All under TDD; live-verified that the prompt is best-effort *alignment* (a model evaded the regex egress classifier via `\c\u\r\l` / `python urllib`), so the OS sandbox remains the load-bearing enforcement
  945. ### Previous Achievements (v0.0.3 - v0.1.96)
  946. βœ… **OS-Level Agent Sandboxing (v0.1.96)**: Added a real OS-level execution sandbox (`command_line_execution_mode: srt`) wrapping agent command/code execution in Anthropic's sandbox-runtime (bubblewrap/Seatbelt), with OS-enforced filesystem + network isolation derived from the same `PathPermissionManager` policy as the app layer (defense in depth), configurable read confinement (`confined`/`strict`/`open`, deny-all network), a hardened key-agnostic permission hook, native-sandbox-backend `srt`β†’`local` degrade, and subagent inheritance.
  947. βœ… **Steering Improvements (v0.1.95)**: Extended mid-stream steering from a UI-only capability into a programmatic, headless one β€” `send_steering_message()` drops guidance into a file inbox (`--inbox-dir`) routed through the same `set_pending_input` chokepoint the TUI/WebUI use β€” and upgraded Codex/Antigravity to interrupt-and-resume the in-flight turn (`codex exec resume` / `agy --continue`) instead of waiting for a round boundary, with `expires_at`-guarded MCP-hook payload IPC and the Antigravity `--model` flag wired through.
  948. βœ… **Parallelism Hardening β€” Engineering Health (v0.1.94)**: Moved the peer-context snapshot copy off the event loop (worker thread via `asyncio.to_thread`) backed by immutable, versioned snapshots (`SnapshotVersionStore`) with atomically-repointed symlinks and refcounted readers, eliminating the read-during-write race; fixed lost peer-answer revisions (R1), lost background-subagent results (R2/R3), leaked trace tasks (R4), and cancel-without-await teardown (R5); surfaced worktree-isolation degradation (D2); and unified the mid-stream injection paths (A1). No per-backend functionality changes.
  949. βœ… **CLI Package Decomposition & Pydantic Config Migration (v0.1.93)**: Split the monolithic 12k-line `cli.py` into an 18-module `massgen/cli/` package, migrated config classes to `pydantic.dataclasses` with `Literal`-typed modes the validator derives from, consolidated provider-exclusion lists, removed ~8.7k lines of dead legacy code from the wheel, and hardened the test-signal/type-checking tooling. Internal-quality release, no runtime behavior changes.
  950. βœ… **Orchestrator Collaborator Refactor & Parallel Search MCP (v0.1.92)**: Reduced `orchestrator.py` from 21,599 to 8,574 lines by extracting 49 lazy collaborators, split Textual display helpers into sibling modules, added characterization coverage, and introduced a Parallel Web Search MCP registry entry plus example config.
  951. βœ… **Config Reliability & Hook Safety (v0.1.91)**: Centralized coordination, timeout, and orchestrator runtime parsing; strict unknown-key validation; checklist runtime control wiring; and safer Gemini/Codex native hook path permission precedence.
  952. βœ… **Discriminative Criteria Refinements & Checklist Calibration (v0.1.90)**: Improved checklist-gated refinement quality with discriminative-power pruning, per-criterion feedback, position-bias counterbalancing, deterministic tie-breaking, a unified checklist gate, shared score parsing utilities, and fast-iteration config updates.
  953. βœ… **Antigravity CLI Full Integration & Hardening (v0.1.89)**: Completed the follow-up Antigravity integration pass with workflow-mode parity, auth checks, workspace project anchoring, standalone `hooks.json`, and prompt affordance gating.
  954. βœ… **Antigravity CLI Backend (v0.1.88)**: Added the first `antigravity_cli` backend wrapping Google's `agy` binary, with workspace-local `.antigravity/` config isolation, MCP config translation, native-hook adapter support, and runnable single-agent / mixed Gemini + Antigravity examples.
  955. βœ… **Framework Comparisons & `llms.txt` (v0.1.87)**: Added CrewAI, LangGraph, and AutoGen/AG2 comparison pages, plus `llms.txt` and generated `llms-full.txt` for AI-agent documentation discovery. Also fixed `bootstrap_subagent` single-shot behavior with `refine=False`.
  956. βœ… **`bootstrap_subagent` Discriminator + Codex MCP Approval Fix (v0.1.86)**: Variant B is now functional β€” the orchestrator runs an in-process LLM critic between rounds, merges critic-proposed criteria into the accumulator, and augments the next round's checklist. Codex MCP tool calls under `codex exec` now write both approval bypasses needed for non-interactive runs.
  957. βœ… **Discriminative Criteria Emergence (`criteria_mode`) (v0.1.85)**: New `orchestrator.coordination.criteria_mode` lets evaluation criteria emerge from observed gaps across rounds. `bootstrap_inline` is fully functional on all backends with checklist tool support, with `proposed_criteria` persisted, deduped, capped, and merged into the next round's effective checklist.
  958. βœ… **TUI Consensus Map (v0.1.84)**: Compact visual map below the agent status ribbon during multi-agent runs that summarizes coordination state β€” agent nodes with latest answer labels, vote arrows, current leader, winner state β€” driven by existing coordination events without backend schema changes.
  959. βœ… **In-Session Standalone Checkpoint MCP Integration (v0.1.83)**: The standalone checkpoint MCP server can now run inside a normal MassGen single-agent session via `coordination.standalone_checkpoint` config block. Enhanced TUI tool card visualization distinguishes primary checkpoint operations from system tasks.
  960. βœ… **TUI Copy Mode & Checkpoint Quality Improvements (v0.1.82)**: `Ctrl+Shift+S` copy mode toggle for native text selection. Checkpoint quality criteria with selective branch depth scoring, optional workspace context for reviewer agents, and single-checkpoint agent recovery guidance.
  961. βœ… **Multi-Region Circuit Breaker Failover (v0.1.81)**: LLM circuit breaker fails over to backup regions when the primary trips OPEN, with automatic recovery when the primary returns to healthy. Completes the circuit breaker series (Phase 1-6).
  962. βœ… **Adaptive Circuit Breaker & Checkpoint Modes (v0.1.80)**: Circuit breaker Phase 5 with self-tuning adaptive thresholds. New standalone checkpoint modes: single checkpoint and draft plan verify.
  963. βœ… **Fast Mode Speed Control & Broader Checkpoint Framing (v0.1.79)**: New fast mode options for fine-grained speed vs. quality control. Checkpoint framing broadened from safety-only to high-stakes and coordinated phases.
  964. βœ… **Circuit Breaker Distributed Store (v0.1.78)**: Pluggable distributed state store for the LLM circuit breaker β€” share state across workers/processes. In-memory (zero-deps) and Redis-backed implementations with atomic state transitions.
  965. βœ… **Answer Now Button (v0.1.77)**: New "Answer Now" button lets agents submit answers more quickly, both within a round, and bypassing additional refinement rounds when quality is sufficient.
  966. βœ… **Exa Search & Circuit Breaker Observability (v0.1.76)**: New Exa AI-powered search tool for MCP. Circuit breaker Phase 3 with observability. Checkpoint agent instructions and Docker dependency fixes.
  967. βœ… **Codex Hooks & Checkpoint WebUI (v0.1.75)**: Hybrid hook system for Codex backend. Checkpoint workflows auto-launch WebUI for visual monitoring. Standalone checkpoint MCP server docs with safety policy integration.
  968. βœ… **Checkpoint Improvements & Tool Call Fixes (v0.1.74)**: Major improvements to standalone checkpoint MCP server. Fix for duplicate tool calls in ChatCompletions and Response API backends.
  969. βœ… **Eval Criteria Evolver & Checkpoint Objectives (v0.1.73)**: New eval criteria evolver subagent that evolves criteria across rounds. Initial draft of checkpoint objective mode for safety planning of irreversible actions.
  970. βœ… **Grok Backend Update & Circuit Breaker Phase 2 (v0.1.72)**: Grok backend update with latest improvements. LLM API circuit breaker extended to ChatCompletions, Response API, and Gemini backends (was Claude-only).
  971. βœ… **Trace Memory & Evaluation Polish (v0.1.71)**: Trace analyzer subagents launch in background after each round to write insights from execution traces into memory. Improved evaluation criteria generation and system prompt tuning.
  972. βœ… **Evaluation Criteria Redesign (v0.1.70)**: Redesigned three-tier evaluation criteria with anti-pattern definitions and aspiration statements. Improved checklist-gated evaluation. Fast iteration mode, WebUI review modal, and background trace analysis.
  973. βœ… **WebUI Automation & Improved Skill (v0.1.69)**: WebUI automation auto-starts without browser interaction. MassGen skill redesign for increased usability and WebUI integration. Quickstart Wizard rework and Workspace Browser expansion.
  974. βœ… **Checkpoint Mode (v0.1.68)**: New checkpoint coordination mode with delegator pattern β€” main agent plans solo then delegates to team via `checkpoint()` tool. LLM API circuit breaker for 429 handling. WebUI checkpoint support. LiteLLM supply chain fix.
  975. βœ… **Modernized WebUI (v0.1.67)**: Complete WebUI redesign with inline final answers, keyboard shortcuts, and Zustand state management. RoundBudgetGuardHook for per-round cost control. Unified parallel pre-collab phases. Regression guard.
  976. βœ… **Step Mode (v0.1.66)**: New `--step` CLI mode for external orchestrators. Powers massgen-refinery plugin step mode. Codex Windows UTF-8 fixes and console text sanitization.
  977. βœ… **MassGen Refinery Plugin (v0.1.65)**: Standalone MCP servers (quality, workflow, media) bring MassGen's checklist-based evaluation to Claude Code through the massgen-refinery plugin. Single-agent refinement working; multi-agent experimental.
  978. βœ… **Gemini CLI Backend (v0.1.64)**: Gemini CLI as a first-class backend with session persistence, MCP tools, and Docker support. WebSocket streaming for OpenAI Response API. Execution trace analyzer subagent. Copilot Docker mode.
  979. βœ… **Ensemble & Contracts (v0.1.63)**: Subagent ensemble pattern with `disable_injection` and `defer_voting_until_all_answered` as defaults. Round evaluator transformation pressure and success contracts. Lighter refinement for subagents. Killed agent handling.
  980. βœ… **MassGen Skill & Viewer (v0.1.62)**: General-purpose multi-agent skill with 4 modes (general, evaluate, plan, spec) for Claude Code and other AI agents. Session viewer for real-time observation. Backend improvements for Claude Code, Codex, and Copilot. Headless and web quickstart modes.
  981. βœ… **Round Evaluator Paradigm (v0.1.61)**: New round evaluator subagent type that automatically spawns evaluator subagents after each new answer to provide detailed feedback as input to the next round. Major orchestrator refactoring with improved evaluation prompts, task plan injection, and subagent fixes.
  982. βœ… **Multimodal Tools, Subagent Enhancements & GPT-5.4 (v0.1.60)**: Rewritten read_media with clearer schema and MediaCallLedgerHook. Subagent enhancements with inherit_spawning_agent_backend, final_answer_strategy, per-agent subagent_agents. GPT-5.4 as default OpenAI flagship. Decomp mode cooperates with checklist workflow. Codex prompt caching fix.
  983. βœ… **Quality Round Improvements (v0.1.59)**: Auto-add improvements to task plan, plan review enhancements. Better eval gen config, checklist fixes, Gemini tool name normalization for MCP. Subagent behavior adjustments, Docker skill write access fixes. Video gen skill adjustments and impact metric restoration.
  984. βœ… **Comprehensive Multimodal Revamp (v0.1.58)**: ElevenLabs TTS/STT, Nano Banana 2 image generation, Grok multimedia generation, media generation skills, and multi-turn image editing. Nvidia NIM backend. Quality rethinking subagent. Smarter checklists with improve/preserve listings. CLI mode flags and logging architecture refactor.
  985. βœ… **Delegated Subagent Protocol & Builder Subagent (v0.1.57)**: File-based delegation protocol for container-to-host subagent spawning. New builder subagent type for large artifact generation with fresh context. Substantiveness tracking for smarter convergence. Claude Code reasoning parameters for updated SDK.
  986. βœ… **Spec Plan Mode & Targeted Messaging (v0.1.56)**: Formal requirements specification with `plan_mode="spec"` and TUI spec mode support. Targeted agent-to-agent messaging via `target_agents` parameter. Critic subagent for quality assessment. Media conversation continuity for follow-up image analysis. Codex OAuth login fix.
  987. βœ… **Specialized Subagent Types & Dynamic Evaluation Criteria (v0.1.55)**: Discovery-based subagent roles (evaluator, explorer, researcher, novelty) via `SUBAGENT.md` frontmatter. GEPA-inspired task-specific evaluation criteria with core/stretch gates. Native backend image routing. Configurable video frame extraction.
  988. βœ… **Subagent Messaging & Copilot SDK Backend (v0.1.54)**: Runtime messaging to steer running background subagents. New GitHub Copilot backend via copilot-sdk with native MCP support. Gemini 3.1 Pro support. Per-agent injection targeting.
  989. βœ… **Background Tool Execution (v0.1.53)**: Non-blocking lifecycle tools for long-running work (start, monitor, wait, cancel, list). Planning task verification requirements. TUI background job indicators and lifecycle controls. Subagent infrastructure groundwork with Evaluator and Explorer types.
  990. βœ… **Final Answer Modal & Coordination Quality Gates (v0.1.52)**: Dedicated final answer modal with tabbed answer and workspace/review interface. Substantive gate prevents low-value iteration rounds. Novelty injection combats premature convergence. Agent identity versioning for answer provenance tracking.
  991. βœ… **Reviewing Coordination & Change Documents (v0.1.51)**: Review modal with multi-file diff visualization. Decision journal system for multi-agent coordination traceability. Changedoc-anchored evaluation checklists with gap reports. Drift conflict policy for safer change application. `--cwd-context` CLI flag.
  992. βœ… **Chunked Plan Execution & Skill Lifecycle Management (v0.1.50)**: Chunked plan execution for safer long-form task completion with progress checkpoints. Skill lifecycle management with consolidation, organizer, and previous-session skill loading. Iterative planning review modal. Responsive TUI mode bar. Worktree improvements with branch accumulation and cross-agent diff visibility.
  993. βœ… **Coordination Quality: Log Analysis TUI, Fairness Gate & Checklist Voting (v0.1.49)**: Log analysis mode built into TUI mode bar for in-app run analysis. Fairness gate prevents fast agents from dominating coordination. Checklist voting tool for structured quality evaluation. Automated testing infrastructure with CI/CD and SVG snapshot baselines.
  994. βœ… **Decomposition Mode & Worktree Isolation (v0.1.48)**: New decomposition coordination mode that decomposes tasks into subtasks assigned to individual agents with a presenter role, git worktree-based isolation for agent file writes with review modal, quickstart wizard Docker setup with animated pull progress, stop tool for agent completion signaling
  995. βœ… **Codex Backend & TUI Theme Refactoring (v0.1.47)**: New Codex backend for OpenAI Codex CLI with local and Docker execution, NativeToolMixin for shared tool handling, TUI theme system refactored to palette-based architecture with dark and light variants, per-agent voting sensitivity configuration
  996. βœ… **Subagent TUI Streaming & Event Architecture Refactor (v0.1.46)**: Interactive preview cards that expand to full timeline views with real-time event streaming, unified event pipeline with single source of truth for display creation, enhanced final presentation with workspace visualization and winning agent highlighting, fixed banner display and tool call ID handling
  997. βœ… **TUI as Default & Config Migration (v0.1.45)**: Textual Terminal UI now launches by default with automatic `rich_terminal` to `textual_terminal` migration, setup wizard generates TUI configs, legacy Rich display accessible via `--display rich` flag
  998. βœ… **Execute Mode for Independent Plan Selection (v0.1.44)**: Mode cycling through Normal β†’ Planning β†’ Execute via `Shift+Tab` or mode bar, plan selector browsing up to 10 recent plans with timestamps, view full plan modal with complete task breakdown, empty submission for plan execution, context path preservation between planning and execution phases, enhanced case studies with interactive setup guides, TUI performance optimizations with viewport-based rendering
  999. βœ… **Tool Call Batching & Interactive Case Studies (v0.1.43)**: Consecutive MCP tool calls grouped into collapsible tree views with "+N more" indicators and click-to-expand. New interactive case studies page with side-by-side SVG comparisons. `PlanOptionsPopover` for browsing plans and selecting depth. Quoted path support for paths with spaces. Final presentation display and TUI polish fixes.
  1000. βœ… **TUI Visual Redesign & Human Input Queue (v0.1.42)**: Modern "Conversational AI" aesthetic with rounded corners, redesigned agent tabs with dot indicators, adaptive tool cards, polished modals. New `HumanInputHook` for injecting messages to agents mid-stream with thread-safe per-agent tracking. AG2 single-agent coordination fix.
  1001. βœ… **Async Subagent Execution (v0.1.41)**: Background subagent execution with `async_=True` for non-blocking parallel work, poll for completion and retrieve results, per-round timeout control with `subagent_round_timeouts` config, extended subagent parameters for timeout and concurrency control
  1002. βœ… **Textual TUI Interactive Mode (v0.1.40)**: Interactive terminal UI with `--display textual` for real-time agent streaming, comprehensive modals for costs/votes/workspace/answers, context path injection with `@path/to/file` syntax, human feedback integration via prompt modals
  1003. βœ… **Plan and Execute Workflow (v0.1.39)**: Complete plan-then-execute workflow with `--plan-and-execute` for autonomous planning and execution, `--execute-plan` to run existing plans without re-planning, task verification workflow with `verified` status and verification groups for batch validation, plan storage system in `.massgen/plans/` with frozen snapshots and execution tracking, Response API function call message sanitization fixes
  1004. βœ… **Task Planning & Two-Tier Workspaces (v0.1.38)**: Task planning mode with `--plan` flag for structured work breakdown (plan-only, no auto-execution), git-backed two-tier workspaces separating scratch exploration from final deliverables, automatic CLAUDE.md/AGENTS.md discovery for project context, batch image analysis with multi-image comparison, circuit breaker for timeout denial loops, Docker health monitoring
  1005. βœ… **Execution Traces & Thinking Mode (v0.1.37)**: Full execution history preserved as `execution_trace.md` for compression recovery and cross-agent coordination, Claude Code and Gemini reasoning content streaming buffer integration, standardized agent labeling across all backends
  1006. βœ… **@path Context Handling & Hook Framework (v0.1.36)**: Inline file picker with `@path` syntax and autocomplete, PreToolUse/PostToolUse hooks for permission validation and content injection, global and per-agent hook registration, built-in `MidStreamInjectionHook` and `HighPriorityTaskReminderHook`, Claude Code hooks compatibility, improved Docker resource management
  1007. βœ… **Log Analysis CLI & Logfire Observability (v0.1.35)**: `massgen logs analyze` command with prompt mode and multi-agent self-analysis, Logfire workflow attributes for round context and vote reasoning, `direct_mcp_servers` config for keeping specific MCPs as protocol tools, improved tool handling for unknown tools and vote-only mode fixes
  1008. βœ… **OpenAI-Compatible Server & Model Discovery (v0.1.34)**: Local HTTP server with `massgen serve` compatible with any OpenAI SDK client, dynamic model discovery for Groq and Together backends via authenticated API calls, WebUI file diffs and answer refresh polling, subagent status tracking and cancellation recovery improvements
  1009. βœ… **Reactive Context Compression & Streaming Buffers (v0.1.33)**: Automatic conversation compression when context length errors occur, streaming buffer system tracking partial responses for recovery, file overwrite protection in `write_file` tool, task plan duplicate prevention, Grok MCP tools visibility fix, Gemini vote-only mode fix, GPT-5 model behavior improvements
  1010. βœ… **Multi-Turn Session Export & Per-Attempt Logging (v0.1.32)**: Turn range selection for session export (`--turns`), workspace export controls (`--no-workspace`, `--workspace-limit`), Logfire moved to optional `[observability]` extra, per-attempt isolated log files with handler reconfiguration, automatic DOCX/PPTX/XLSX to PDF conversion for session sharing
  1011. βœ… **Logfire Observability & Azure Tool Streaming (v0.1.31)**: Optional Logfire integration with automatic LLM instrumentation for OpenAI, Claude, and Gemini backends, Azure OpenAI tool calls yielded as structured chunks, `--logfire` CLI flag and `MASSGEN_LOGFIRE_ENABLED` environment variable
  1012. βœ… **OpenRouter Web Search & Persona Diversity (v0.1.30)**: Native web search via OpenRouter plugins with `enable_web_search`, persona diversity modes (`perspective`/`implementation`) with phase-based adaptation, Azure multi-endpoint auto-detection, environment variable expansion with `${VAR}` syntax
  1013. βœ… **Subagent System & Tool Metrics (v0.1.29)**: Spawn parallel child MassGen processes with isolated workspaces and automatic result aggregation, enhanced tool metrics with per-call averages and min/max/median distribution, CLI per-agent system messages via `massgen --quickstart`
  1014. βœ… **Unified Multimodal Tools & Artifact Previews (v0.1.28)**: Consolidated `read_media` tool for image/audio/video analysis, unified `generate_media` tool for media creation (images, videos, audio), Web UI artifact previewer for PDFs/DOCX/PPTX/images/HTML/SVG/Markdown/Mermaid, OpenRouter tool-capable model filtering, Azure OpenAI fixes
  1015. βœ… **Session Sharing & Log Analysis (v0.1.27)**: Session sharing via GitHub Gist with `massgen export`, log analysis CLI with `massgen logs` command, per-LLM call timing metrics, Gemini 3 Flash model support, enhanced CLI config builder with per-agent web search and system messages
  1016. βœ… **Web UI Setup & Shadow Agent Depth (v0.1.26)**: Docker diagnostics module, Web UI setup wizard with guided first-run experience, shadow agent response depth for test-time compute scaling, GPT-5.1-Codex family models
  1017. βœ… **UI-TARS & Evolving Skills (v0.1.25)**: ByteDance's UI-TARS-1.5-7B for GUI automation, GPT-5.2 model support, evolving skill creator system with session persistence, enhanced Textual terminal with adaptive layouts
  1018. βœ… **Multi-Backend Cost Tracking (v0.1.24)**: Real-time token counting for OpenRouter, xAI/Grok, Gemini, and Claude Code backends with `/inspect c` cost breakdown showing per-agent token usage, aggregated session cost totals with improved display formatting
  1019. βœ… **Turn History Inspection & Web UI Automation (v0.1.23)**: Interactive `/inspect` commands for reviewing turn details with menu navigation, `AutomationView` component for programmatic monitoring, `SessionMountManager` for Docker container persistence across turns, flag-based cancellation with terminal restoration, `run_async_safely()` for nested event loop handling
  1020. βœ… **Shadow Agent Architecture (v0.1.22)**: Lightweight shadow agents respond to broadcasts in parallel without interrupting parent work, inheriting full conversation history and current turn context via `asyncio.gather()` parallelization
  1021. βœ… **Graceful Cancellation & Session Resumption (v0.1.21)**: Ctrl+C saves partial progress during coordination, cancelled sessions resume with `--continue` preserving agent answers and workspaces
  1022. βœ… **Web UI & Auto Docker Setup (v0.1.20)**: Browser-based real-time visualization with React frontend, WebSocket streaming, timeline views, and workspace browsing. Automatic Docker container setup for computer use agents with pre-configured X11 virtual display, xdotool, Firefox, Chromium, and scrot
  1023. βœ… **LiteLLM Integration & Claude Strict Tool Use (v0.1.19)**: MassGen as LiteLLM custom provider with `run()` and `build_config()` programmatic API, Claude strict tool use with structured outputs, Gemini exponential backoff for rate limit resilience
  1024. βœ… **Agent Communication System (v0.1.18)**: Human broadcast Q&A via `ask_others()` tool with three modes, blocking execution with inline response delivery, session-persistent Q&A history
  1025. βœ… **Claude Advanced Tooling (v0.1.18)**: Programmatic tool calling via `enable_programmatic_flow` flag, server-side tool discovery via `enable_tool_search` with regex or bm25 variants
  1026. βœ… **Textual Terminal Display (v0.1.17)**: Interactive terminal UI using the Textual library with dark/light themes, multi-panel layout for agents and orchestrator, real-time streaming with syntax highlighting, content filtering for critical patterns
  1027. βœ… **Terminal Evaluation & Cost Tracking (v0.1.16)**: Automated VHS recording with AI-powered terminal display evaluation, LiteLLM integration for accurate pricing across 500+ models with reasoning/cached tokens support, memory archiving for multi-turn session persistence, four self-evolution skills for MassGen development
  1028. βœ… **Persona Generation & Docker Distribution (v0.1.15)**: Automatic persona generation for agent diversity with multiple strategies (complementary, diverse, specialized, adversarial), GitHub Container Registry integration with ARM support, custom tools in isolated Docker containers for security, MassGen pre-installed in Docker images
  1029. βœ… **Parallel Tool Execution & Gemini 3 Pro (v0.1.14)**: Configurable concurrent tool execution across all backends with asyncio-based scheduling, Gemini 3 Pro integration with function calling, interactive quickstart workflow, MCP registry client for server metadata
  1030. βœ… **Code-Based Tools & MCP Registry (v0.1.13)**: CodeAct paradigm implementation with tool integration via importable Python code reducing token usage by 98%, MCP server registry with auto-discovery and on-demand loading, TOOL.md documentation standard
  1031. βœ… **NLIP Integration & Skills System (v0.1.13)**: Advanced tool routing with Natural Language Interface Protocol across Claude, Gemini, and OpenAI backends, cross-platform automated skills installer for openskills CLI, Anthropic skills, and Crawl4AI
  1032. βœ… **System Prompt Architecture Refactoring (v0.1.12)**: Hierarchical system prompt structure with XML-based formatting for Claude, improved LLM attention management
  1033. βœ… **Semtools & Serena Skills (v0.1.12)**: Semantic search via embedding-based similarity, symbol-level code understanding via LSP integration, local execution mode for non-Docker environments
  1034. βœ… **Multi-Agent Computer Use (v0.1.12)**: Enhanced Gemini computer use with Docker integration, VNC visualization, multi-agent coordination combining Claude (Docker/Linux) and Gemini (Browser)
  1035. βœ… **Skills System (v0.1.11)**: Modular prompting framework with SkillsManager for dynamic skill loading, automatic discovery with always/optional categories, file search skill, Docker-compatible mounting
  1036. βœ… **Memory MCP Tool & Filesystem Integration (v0.1.11)**: MCP server for memory management with markdown-based storage, short-term/long-term memory tiers, automatic workspace persistence, orchestrator integration for cross-agent memory sharing, enhanced Windows support for long system prompts
  1037. βœ… **Rate Limiting System (v0.1.11)**: Multi-dimensional limiting (RPM, TPM, RPD) for Gemini models with configurable thresholds, YAML-based configuration, CLI integration with --enable-rate-limiting flag, asyncio lock fix for event loop reuse
  1038. βœ… **Framework Interoperability Streaming (v0.1.10)**: Real-time intermediate step streaming for LangGraph and SmoLAgent with log/output distinction, enhanced debugging for external framework reasoning steps
  1039. βœ… **Docker Configuration Enhancements (v0.1.10)**: Nested authentication with separate mount and environment variable arrays, custom image support via Dockerfile.custom-example, automatic package installation
  1040. βœ… **Universal Workspace Isolation (v0.1.10)**: Instance ID generation extended to all execution modes ensuring safe parallel execution, enhanced workspace path uniqueness across concurrent sessions
  1041. βœ… **Session Management System (v0.1.9)**: Complete session state tracking and restoration with SessionState dataclass and SessionRegistry for multi-turn persistence across CLI invocations, workspace continuity preserving agent states and coordination history between turns
  1042. βœ… **Computer Use Tools (v0.1.9)**: Native Claude and Gemini computer use API integration for browser and desktop automation with screenshot analysis and action generation, lightweight browser automation for specific tasks without full computer use overhead
  1043. βœ… **Fuzzy Model Matching (v0.1.9)**: Intelligent model name search with approximate inputs (e.g., "sonnet" β†’ "claude-sonnet-4-5-20250929"), model catalog system with curated lists across providers, enhanced config builder with automatic model search
  1044. βœ… **Backend Capabilities Expansion (v0.1.9)**: Comprehensive backend registry with detailed specifications for all providers, audio/video support, hardware acceleration, unified access across diverse model families, enhanced memory update logic focusing on actionable patterns
  1045. βœ… **Automation Mode for LLM Agents (v0.1.8)**: Complete infrastructure for running MassGen inside LLM agents with SilentDisplay class for minimal output (~10 lines vs 250-3,000+), real-time status.json monitoring updated every 2 seconds, meaningful exit codes (0=success, 1=config error, 2=execution error, 3=timeout, 4=interrupted), automatic workspace isolation for parallel execution, meta-coordination capabilities allowing MassGen to run MassGen
  1046. βœ… **DSPy Question Paraphrasing Integration (v0.1.8)**: Intelligent question diversity for multi-agent coordination with semantic-preserving paraphrasing module supporting three strategies (diverse/balanced/conservative), automatic semantic validation to ensure meaning preservation, thread-safe caching system with SHA-256 hashing, support for all backends as paraphrasing engines, orchestrator integration for automatic question variant distribution
  1047. βœ… **Agent Task Planning System (v0.1.7)**: MCP-based planning server with task lifecycle management, dependency tracking with automatic validation and blocking, status transitions between pending/in_progress/completed/blocked states, orchestrator integration for plan-aware multi-agent coordination
  1048. βœ… **Background Shell Execution (v0.1.7)**: Persistent shell sessions for long-running commands with BackgroundShell class supporting async execution, real-time output streaming and monitoring, automatic timeout handling, enhanced code execution server with background capabilities
  1049. βœ… **Preemption Coordination (v0.1.7)**: Agents can interrupt ongoing coordination to submit better answers without full restart, partial progress preservation during preemption, enhanced coordination tracker logging preemption events
  1050. βœ… **Framework Interoperability (v0.1.6)**: AG2 nested chat, LangGraph workflows, AgentScope agents, OpenAI Assistants, and SmoLAgent integrated as custom tools with cross-framework collaboration and streaming support for AG2
  1051. βœ… **Configuration Validator (v0.1.6)**: Comprehensive YAML validation with ConfigValidator class, pre-commit integration, and detailed error messages with actionable suggestions
  1052. βœ… **Unified Tool Execution (v0.1.6)**: ToolExecutionConfig dataclass standardizing tool handling across ResponseBackend, ChatCompletionsBackend, and ClaudeBackend with consistent error reporting
  1053. βœ… **Gemini Backend Simplification (v0.1.6)**: Removed gemini_mcp_manager and gemini_trackers modules, consolidated code reducing codebase by 1,598 lines
  1054. βœ… **Memory System (v0.1.5)**: Long-term semantic memory via mem0 integration with fact extraction and retrieval across sessions, short-term conversational memory for active context, automatic context compression when approaching token limits, cross-agent memory sharing with turn-aware filtering, session management for memory isolation and continuation, Qdrant vector database integration for semantic search
  1055. βœ… **Multimodal Generation Tools (v0.1.4)**: Create images from text via DALL-E API, generate videos from descriptions, text-to-speech with audio transcription support, document generation for PDF/DOCX/XLSX/PPTX formats, image transformation capabilities for existing images
  1056. βœ… **Binary File Protection (v0.1.4)**: Automatic blocking prevents text tools from accessing 40+ binary file types including images, videos, audio, archives, and Office documents, intelligent error messages guide users to appropriate specialized tools for binary content
  1057. βœ… **Crawl4AI Integration (v0.1.4)**: Intelligent web scraping with LLM-powered content extraction and customizable extraction patterns for structured data retrieval from websites
  1058. βœ… **Post-Evaluation Workflow (v0.1.3)**: Winning agents evaluate their own answers before submission with submit and restart capabilities, supports answer confirmation and orchestration restart with feedback across all backends
  1059. βœ… **Multimodal Understanding Tools (v0.1.3)**: Analyze images, transcribe audio, extract video frames, and process documents (PDF/DOCX/XLSX/PPTX) with structured JSON output, works across all backends via OpenAI GPT-4.1 integration
  1060. βœ… **Docker Sudo Mode (v0.1.3)**: Privileged command execution in Docker containers for system-level operations requiring elevated permissions
  1061. βœ… **Intelligent Planning Mode (v0.1.2)**: Automatic question analysis determining operation irreversibility via `_analyze_question_irreversibility()` in orchestrator, selective tool blocking with `set_planning_mode_blocked_tools()` and `is_mcp_tool_blocked()` methods, read-only MCP operations during coordination with write operations blocked, zero-configuration transparent operation, multi-workspace support
  1062. βœ… **Model Updates (v0.1.2)**: Claude 4.5 Haiku model `claude-haiku-4-5-20251001`, reorganized Claude model priorities with `claude-sonnet-4-5-20250929` default, Grok web search fix with `_add_grok_search_params()` method for proper `extra_body` parameter handling
  1063. βœ… **Custom Tools System (v0.1.1)**: User-defined Python function registration using `ToolManager` class in `massgen/tool/_manager.py`, cross-backend support alongside MCP servers, builtin/MCP/custom tool categories with automatic discovery, 40+ examples in `massgen/configs/tools/custom_tools/`, voting sensitivity controls with three-tier quality system (lenient/balanced/strict), answer novelty detection preventing duplicates
  1064. βœ… **Backend Enhancements (v0.1.1)**: Gemini architecture refactoring with extracted MCP management (`gemini_mcp_manager.py`), tracking (`gemini_trackers.py`), and utilities, new capabilities registry in `massgen/backend/capabilities.py` documenting feature support across all backends
  1065. βœ… **PyPI Package Release (v0.1.0)**: Official distribution via `pip install massgen` with simplified installation, global `massgen` command accessible from any directory, comprehensive Sphinx documentation at [docs.massgen.ai](https://docs.massgen.ai/), interactive setup wizard with use case presets and API key management, enhanced CLI with `@examples/` prefix for built-in configurations
  1066. βœ… **Docker Execution Mode (v0.0.32)**: Container-based isolation with secure command execution in isolated Docker containers preventing host filesystem access, persistent state management with packages and dependencies persisting across conversation turns, multi-agent support with dedicated isolated containers for each agent, configurable security with resource limits (CPU, memory), network isolation modes, and read-only volume mounts
  1067. βœ… **MCP Architecture Refactoring (v0.0.32)**: Simplified client with renamed `MultiMCPClient` to `MCPClient` reflecting streamlined architecture, code consolidation by removing deprecated modules and consolidating duplicate MCP protocol handling, improved maintainability with standardized type hints, enhanced error handling, and cleaner code organization
  1068. βœ… **Claude Code Docker Integration (v0.0.32)**: Automatic tool management with Bash tool automatically disabled in Docker mode routing commands through execute_command, MCP auto-permissions with automatic approval for MCP tools while preserving security validation, enhanced guidance with system messages preventing git repository confusion between host and container environments
  1069. βœ… **Universal Command Execution (v0.0.31)**: MCP-based execute_command tool works across Claude, Gemini, OpenAI, and Chat Completions providers, comprehensive security with permission management and command filtering, code execution in planning mode for safer coordination
  1070. βœ… **External Framework Integration (v0.0.31)**: Multi-agent conversations using external framework group chat patterns, smart speaker selection (automatic, round-robin, manual) powered by LLMs, enhanced adapter supporting native group chat coordination
  1071. βœ… **Audio & Video Generation (v0.0.31)**: Audio tools for text-to-speech and transcription, video generation using OpenAI's Sora-2 API, multimodal expansion beyond text and images
  1072. βœ… **Multimodal Support Extension (v0.0.30)**: Audio and video processing for Chat Completions and Claude backends (WAV, MP3, MP4, AVI, MOV, WEBM formats), flexible media input via local paths or URLs, extended base64 encoding for audio/video files, configurable file size limits
  1073. βœ… **Claude Agent SDK Migration (v0.0.30)**: Package migration from `claude-code-sdk` to `claude-agent-sdk>=0.0.22`, improved bash tool permission validation, enhanced system message handling
  1074. βœ… **Qwen API Integration (v0.0.30)**: Added Qwen API provider to Chat Completions ecosystem with `QWEN_API_KEY` support, video understanding configuration examples
  1075. βœ… **MCP Planning Mode (v0.0.29)**: Strategic planning coordination strategy for safer MCP tool usage, multi-backend support (Response API, Chat Completions, Gemini), agents plan without execution during coordination, 5 planning mode configurations
  1076. βœ… **File Operation Safety (v0.0.29)**: Read-before-delete enforcement with `FileOperationTracker` class, `PathPermissionManager` integration with operation tracking methods, enhanced file operation safety mechanisms
  1077. βœ… **External Framework Integration (v0.0.28)**: Adapter system for external agent frameworks with async execution, code execution in multiple environments (Local, Docker, Jupyter, YepCode), ready-to-use configurations for framework integration
  1078. βœ… **Multimodal Support - Image Processing (v0.0.27)**: New `stream_chunk` module for multimodal content, image generation and understanding capabilities, file upload and search for document Q&A, Claude Sonnet 4.5 support, enhanced workspace multimodal tools
  1079. βœ… **File Deletion and Workspace Management (v0.0.26)**: New MCP tools (`delete_file`, `delete_files_batch`, `compare_directories`, `compare_files`) for workspace cleanup and file comparison, consolidated `_workspace_tools_server.py`, enhanced path permission manager
  1080. βœ… **Protected Paths and File-Based Context Paths (v0.0.26)**: Protect specific files within write-permitted directories, grant access to individual files instead of entire directories
  1081. βœ… **Multi-Turn Filesystem Support (v0.0.25)**: Multi-turn conversation support with persistent context across turns, automatic `.massgen` directory structure, workspace snapshots and restoration, enhanced path permission system with smart exclusions, and comprehensive backend improvements
  1082. βœ… **SGLang Backend Integration (v0.0.25)**: Unified vLLM/SGLang backend with auto-detection, support for SGLang-specific parameters like `separate_reasoning`, and dual server support for mixed vLLM and SGLang deployments
  1083. βœ… **vLLM Backend Support (v0.0.24)**: Complete integration with vLLM for high-performance local model serving, POE provider support, GPT-5-Codex model recognition, backend utility modules refactoring, and comprehensive bug fixes including streaming chunk processing
  1084. βœ… **Backend Architecture Refactoring (v0.0.23)**: Major code consolidation with new `base_with_mcp.py` class reducing ~1,932 lines across backends, extracted formatter module for better code organization, and improved maintainability through unified MCP integration
  1085. βœ… **Workspace Copy Tools via MCP (v0.0.22)**: Seamless file copying capabilities between workspaces, configuration organization with hierarchical structure, and enhanced file operations for large-scale collaboration
  1086. βœ… **Grok MCP Integration (v0.0.21)**: Unified backend architecture with full MCP server support, filesystem capabilities through MCP servers, and enhanced configuration files
  1087. βœ… **Claude Backend MCP Support (v0.0.20)**: Extended MCP integration to Claude backend, full MCP protocol and filesystem support, robust error handling, and comprehensive documentation
  1088. βœ… **Comprehensive Coordination Tracking (v0.0.19)**: Complete coordination tracking and visualization system with event-based tracking, interactive coordination table display, and advanced debugging capabilities for multi-agent collaboration patterns
  1089. βœ… **Comprehensive MCP Integration (v0.0.18)**: Extended MCP to all Chat Completions backends (Cerebras AI, Together AI, Fireworks AI, Groq, Nebius AI Studio, OpenRouter), cross-provider function calling compatibility, 9 new MCP configuration examples
  1090. βœ… **OpenAI MCP Integration (v0.0.17)**: Extended MCP (Model Context Protocol) support to OpenAI backend with full tool discovery and execution capabilities for GPT models, unified MCP architecture across multiple backends, and enhanced debugging
  1091. βœ… **Unified Filesystem Support with MCP Integration (v0.0.16)**: Complete `FilesystemManager` class providing unified filesystem access for Gemini and Claude Code backends, with MCP-based operations for file manipulation and cross-agent collaboration
  1092. βœ… **MCP Integration Framework (v0.0.15)**: Complete MCP implementation for Gemini backend with multi-server support, circuit breaker patterns, and comprehensive security framework
  1093. βœ… **Enhanced Logging (v0.0.14)**: Improved logging system for better agents' answer debugging, new final answer directory structure, and detailed architecture documentation
  1094. βœ… **Unified Logging System (v0.0.13)**: Centralized logging infrastructure with debug mode and enhanced terminal display formatting
  1095. βœ… **Windows Platform Support (v0.0.13)**: Windows platform compatibility with improved path handling and process management
  1096. βœ… **Enhanced Claude Code Agent Context Sharing (v0.0.12)**: Claude Code agents now share workspace context by maintaining snapshots and temporary workspace in orchestrator's side
  1097. βœ… **Documentation Improvement (v0.0.12)**: Updated README with current features and improved setup instructions
  1098. βœ… **Custom System Messages (v0.0.11)**: Enhanced system message configuration and preservation with backend-specific system prompt customization
  1099. βœ… **Claude Code Backend Enhancements (v0.0.11)**: Improved integration with better system message handling, JSON response parsing, and coordination action descriptions
  1100. βœ… **Azure OpenAI Support (v0.0.10)**: Integration with Azure OpenAI services including GPT-4.1 and GPT-5-chat models with async streaming
  1101. βœ… **MCP (Model Context Protocol) Support (v0.0.9)**: Integration with MCP for advanced tool capabilities in Claude Code Agent, including Discord and Twitter integration
  1102. βœ… **Timeout Management System (v0.0.8)**: Orchestrator-level timeout with graceful fallback and enhanced error messages
  1103. βœ… **Local Model Support (v0.0.7)**: Complete LM Studio integration for running open-weight models locally with automatic server management
  1104. βœ… **GPT-5 Series Integration (v0.0.6)**: Support for OpenAI's GPT-5, GPT-5-mini, GPT-5-nano with advanced reasoning parameters
  1105. βœ… **Claude Code Integration (v0.0.5)**: Native Claude Code backend with streaming capabilities and tool support
  1106. βœ… **GLM-4.5 Model Support (v0.0.4)**: Integration with ZhipuAI's GLM-4.5 model family
  1107. βœ… **Foundation Architecture (v0.0.3)**: Complete multi-agent orchestration system with async streaming, builtin tools, and multi-backend support
  1108. βœ… **Extended Provider Ecosystem**: Support for 15+ providers including Cerebras AI, Together AI, Fireworks AI, Groq, Nebius AI Studio, and OpenRouter
  1109. ### Key Future Enhancements
  1110. - **Bug Fixes & Backend Improvements:** Fixing image generation path issues and adding Claude multimodal support
  1111. - **Advanced Agent Collaboration:** Exploring improved communication patterns and consensus-building protocols to improve agent synergy
  1112. - **Expanded Model Integration:** Adding support for more frontier models and local inference engines
  1113. - **Improved Performance & Scalability:** Optimizing the streaming and logging mechanisms for better performance and resource management
  1114. - **Enhanced Developer Experience:** Completing tool registration system and web interface for better visualization
  1115. We welcome community contributions to achieve these goals.
  1116. ### v0.1.97 Roadmap
  1117. Version 0.1.97 picks up the image/video edit work deferred from v0.1.86-v0.1.96 and continues multimodal provider-parity work:
  1118. #### Planned Features
  1119. - **Image/Video Edit Capabilities** ([#959](https://github.com/massgen/MassGen/issues/959)): Image and video editing across providers with multi-turn editing workflows via continuation IDs
  1120. ---
  1121. ## 🀝 Contributing
  1122. We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
  1123. ---
  1124. ## 🀝 Acknowledge
  1125. We thank AgentWeb
  1126. <a href="https://www.agentweb.pro/">
  1127. <img width="196" height="51" alt="68dacef628cd7a44dfb97814_agentweb-logo" src="https://github.com/user-attachments/assets/312f1d67-b342-4f62-b8ad-65cc9f54dc65" />
  1128. </a>
  1129. for their kind sponsorship.
  1130. ---
  1131. ## πŸ“„ License
  1132. This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
  1133. ---
  1134. <div align="center">
  1135. **⭐ Star this repo if you find it useful! ⭐**
  1136. Made with ❀️ by the MassGen team
  1137. </div>
  1138. ## ⭐ Star History
  1139. [![Star History Chart](https://api.star-history.com/svg?repos=Leezekun/MassGen&type=Date)](https://www.star-history.com/#Leezekun/MassGen&Date)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.