# Massgen Run

> Launch a MassGen multi-agent run. Multiple LLM backends (codex, gemini, claude, grok) collaborate on a task via voting and consensus. Runs in Docker containers by default.

- Skill: `massgen/massgen-run` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add massgen/massgen-run`
- Raw SKILL.md: https://api.skillmd.com/api/skills/massgen/massgen-run/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: massgen (https://skillmd.com/u/massgen)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/massgen/massgen-run

---


You are orchestrating a MassGen multi-agent run. Multiple LLM agents will
collaborate on the user's task through answer generation, voting, and consensus.

## Pre-Flight Checks

Before doing anything else, verify the environment:

1. Read `.massgen-quality/environment.json` — check `massgen.available` and
   note `massgen.source` (`"uvx"` or `"local:/path"`) for Step 3 launch method
2. If massgen unavailable: tell the user and provide install instructions:
   ```
   cd /path/to/massgen && uv sync
   ```
3. Read `api_keys` from `.massgen-quality/environment.json` — check which
   providers are authenticated. The hook checks both environment variables AND
   `.env` files (at `$CWD/.env` and `$HOME/.env`). If all keys show missing but the user
   says keys exist, check for a `.env` file and suggest creating one:
   ```
   # .env (at project root or $HOME)
   OPENAI_API_KEY=sk-...
   GOOGLE_API_KEY=AI...
   ANTHROPIC_API_KEY=sk-ant-...
   ```
   MassGen Docker configs already use `env_file: .env` for credential injection,
   so a `.env` file ensures keys are available in containers too.
4. Map requested backends to required keys:
   - `openai`, `codex` → `openai` key
   - `gemini` → `google` key
   - `claude`, `claude_code` → `anthropic` key
   - `grok` → `xai` key
5. Warn if any requested backend lacks its API key — skip that backend
6. If ALL backends lack keys: abort with clear message

### Docker checks (unless `--no-docker`)

Docker is the **default**. Check:

1. Read `docker` from `.massgen-quality/environment.json` — check `docker.available`
2. If Docker unavailable: warn, suggest `--no-docker`, or ask user to start Docker
3. Check `docker.image_available` — if false:
   ```
   docker pull ghcr.io/massgen/mcp-runtime-sudo:latest
   # or build locally:
   cd /path/to/massgen && bash massgen/docker/build.sh --sudo
   ```
4. If user passed `--no-docker`: skip Docker config, use local execution mode

## Step 1: Parse Arguments

Parse from the user's input:
- `query`: the task/question for agents
- `--models`: list of `backend/model` pairs (e.g., `codex/gpt-5.4 gemini/gemini-3.1-pro-preview`)
- `--no-docker`: disable Docker containerization
- `--max-duration N`: override orchestrator timeout (default: 1800s)

If no `--models` specified, use defaults based on available API keys:
- If openai + google available: `openai/gpt-5.4 gemini/gemini-3.1-pro-preview` (default pair)
- If only openai: `openai/gpt-5.4`
- If only google: `gemini/gemini-3.1-pro-preview`
- Include additional backends (claude, grok) as available

Note: coding agent backends (`codex`, `claude_code`) require Docker mode.
Default to `openai` and `gemini` backends which work without Docker.

## Step 2: Generate YAML Config

Write config to `.massgen-quality/sessions/<session_id>/configs/run_<timestamp>.yaml`
(where `<session_id>` is `run_<YYYYMMDD_HHMMSS>`).

For each `backend/model` pair, create an agent entry. See
`references/config-templates.md` for the full template.

**context_paths** (critical): Lives under `orchestrator:`, not `agents:`. Each
entry is a `{path, permission}` dict. Agents can only see files in paths listed
here. If the task involves specific files or a project directory, you MUST
include the absolute path. Use `read` for reference material, `write` if agents
should modify files:
```yaml
orchestrator:
  context_paths:
    - path: "/absolute/path/to/project"
      permission: "read"
```

Key settings:
- `ui.display_type: "simple"` (must be valid; `--automation` overrides to silent)
- `ui.logging_enabled: true`

If Docker mode (not `--no-docker`), add per-agent:
- `enable_code_based_tools: true`
- `exclude_file_operation_mcps: true`
- `enable_mcp_command_line: true`
- `command_line_execution_mode: docker`
- `command_line_docker_image: ghcr.io/massgen/mcp-runtime-sudo:latest`
- `command_line_docker_credentials` with env_file and API keys

If `--no-docker` (or Docker unavailable): use local CLI execution instead:
- `enable_mcp_command_line: true`
- `command_line_execution_mode: local`
- Do NOT include Docker-specific fields (image, network, sudo, credentials)
Agents can run commands and edit files directly on the host via local execution.

## Step 3: Launch MassGen

**MassGen runs take a while** (often 5-30 minutes). Always use `run_in_background: true`
on the Bash tool — the hard 10-minute timeout will kill foreground runs.

Read `plugin_dir` from `.massgen-quality/environment.json`. Use the massgen
wrapper which handles API key sourcing and massgen resolution automatically:

```bash
bash "<plugin_dir>/scripts/run-massgen.sh" --automation \
  --config "<config_path>" \
  "<query>" 2>&1
```

**Parse stderr output** for automation status lines:
- `LOG_DIR: <path>` — the session log directory
- `STATUS: <path>` — path to `status.json` for monitoring

**Launch sequence:**
1. Run the command with `run_in_background: true` on the Bash tool
2. Tell the user the run is in progress and **will take a while**
3. Spawn a `massgen-monitor` background agent with the PID and LOG_DIR
4. The user will be notified on completion

## Step 4: Extract and Present Results

Find `status.json` at `<LOG_DIR>/turn_0/attempt_0/status.json` (or latest turn/attempt).

Read and extract:
- `results.winner` — the winning agent ID
- `results.votes` — vote distribution
- `agents.<id>.answer` — each agent's answer
- `agents.<id>.status` — each agent's final status
- `meta.elapsed_seconds` — duration
- `costs.total_estimated_cost` — cost estimate

Present to the user:
1. **Winning answer** (from the consensus winner)
2. **Vote distribution** (which agents voted for whom)
3. **Per-agent answers** (collapsed/summarized if long)
4. **Duration and cost**

If the user wants to use the answer, offer to write it to a file or apply it.

## Error Handling

- **Exit code 1 (config error)**: Check the YAML config for syntax issues. Read
  the massgen log for details.
- **Exit code 2 (execution error)**: An agent failed. Read `status.json` for
  `agents.<id>.error` details.
- **Exit code 3 (timeout)**: Increase `--max-duration` or reduce agent count.
- **massgen not found**: Provide install instructions.
- **Docker not available**: Suggest `--no-docker` or starting Docker.