marcus

Marcus Multi-Agent Experiment Launcher (Codex)

You are helping the user launch a Marcus multi-agent experiment. Marcus uses an MCP server to coordinate independent agent CLI processes, each running in its own tmux pane.

This skill is invoked from within the Codex CLI. When the user runs /marcus from inside Codex, the typical (but not required) intent is to spawn codex agents — pass --harness codex to make that explicit. The skill also accepts --harness claude to spawn Anthropic CLI agents from a Codex driver session if that's what the user wants.

What You Do

1. Parse the user's request to extract: project description, agent count, harness, model
2. Create an experiment directory with config.yaml and project_spec.md
3. Run run_experiment.py which spawns agents in tmux panes
4. Report the tmux session name so the user can attach

Discovering Paths

Find the Marcus repo root via the installed package:

MARCUS_ROOT=$(python3 -c "from pathlib import Path; import marcus_mcp; print(Path(marcus_mcp.__file__).parent.parent.parent)")

From there:

• Run script: ${MARCUS_ROOT}/dev-tools/experiments/runners/run_experiment.py
• Templates: ${MARCUS_ROOT}/dev-tools/experiments/templates/

If the import fails, Marcus isn't installed. Tell the user:

Marcus is not installed. Follow the setup instructions:
  git clone https://github.com/lwgray/marcus.git
  cd marcus && pip install -e .

How to Parse Arguments

The user's input comes in as $ARGUMENTS. Extract:

• Project description: Everything that describes what to build
• Project name: Look for --name "Some Name" or --name some_name. If not provided, derive a short name from the description.
• Agent count: Look for patterns like "N agents", "--agents N", "with N workers". Default: 2
• Complexity: Look for "--complexity prototype|standard|enterprise". Default: "prototype"
• Decomposer: Look for "--decomposer contract_first|feature_based". Default: "contract_first" (as of v0.3.4). This controls Marcus's task decomposition strategy (GH-320):
  • contract_first — default. Generates interface contracts before decomposition. Board is fully populated before any agent starts (no Phase A race). Each agent owns one side of a contract. Best for tightly-coupled projects (games, dashboards, state machines).
  • feature_based — legacy path, splits tasks by functional requirement. Fine for loosely-coupled projects where features don't share files.
• Epictetus mode: Look for --epictetus flag. Default: not set (false). When present, the monitor agent does NOT kill the tmux session after the experiment completes — it stays alive for Epictetus post-experiment interrogation.
• Agent model: Look for --model <value>. Default: not set — Marcus reads ai.model from config_marcus.json and uses that same value for the spawned Agent CLI processes (so by default Planners and Agents share one model). When --model X is provided, X overrides for THIS run only and applies to all spawned panes (project creator + workers + monitor). The same string is passed verbatim to whichever harness is active — accepts claude --model values (e.g. sonnet, opus, haiku, claude-haiku-4-5-20251001) or codex --model values (e.g. gpt-5-codex, o3). No client-side validation against per-harness namespaces — invalid model names surface as CLI errors inside the agent panes. Affects ONLY the spawned Agents — Marcus's Planner model continues to read from config_marcus.json.
• Agent harness: Look for --harness claude|codex. Default: claude (matches run_experiment.py default). When invoked from inside Codex CLI, you typically want --harness codex — but the runner does not auto-detect the caller. codex spawns codex exec --dangerously-bypass-approvals-and-sandbox (the documented form of "YOLO mode" — sets approval: never, sandbox: danger-full-access). All agents in a single experiment use the same harness; mixed-harness teams are out of scope for v1. The runner pre-flights which <cli> and fails fast if the binary is missing.

Examples:

• /marcus Build a snake game with 3 agents -> description="Build a snake game", name="snake_game", agents=3, complexity="prototype", decomposer="contract_first", harness="claude"
• /marcus Build a TODO CLI with 2 agents --harness codex -> description="Build a TODO CLI", name="todo_cli", agents=2, complexity="prototype", decomposer="contract_first", harness="codex"
• /marcus Build a TODO CLI --harness codex --model gpt-5-codex -> description="Build a TODO CLI", name="todo_cli", agents=2, complexity="prototype", decomposer="contract_first", model="gpt-5-codex", harness="codex"
• /marcus Build a snake game with 4 agents --harness codex --model o3 -> description="Build a snake game", name="snake_game", agents=4, complexity="prototype", decomposer="contract_first", model="o3", harness="codex"

Step-by-Step Execution

Step 1: Use the Current Working Directory

Write all files into the current working directory. Do NOT create or mkdir a new directory. run_experiment.py will create the subdirectories it needs (prompts/, logs/, implementation/).

<cwd>/
├── config.yaml       (you create this)
├── project_spec.md   (you create this)
├── prompts/          (created by run_experiment.py)
├── logs/             (created by run_experiment.py)
└── implementation/   (created by run_experiment.py, git repo where agents write code)

Step 2: Generate project_spec.md

Write the user's project description as-is to project_spec.md. Do NOT rewrite, expand, restructure, or add sections to it. Marcus handles task decomposition — the spec is just the raw input from the user.

Step 3: Generate config.yaml

CRITICAL: Always write a fresh config.yaml from the template below. Do NOT read or preserve values from any existing config.yaml in the directory. Overwrite it completely.

Use this exact format — field names are case-sensitive:

project_name: "<--name value if provided, otherwise derived from description>"
project_spec_file: "project_spec.md"

# Harness selection: omit the field (defaults to 'claude') or set explicitly.
# CLI flag --harness on run_experiment.py overrides this value.
harness: "<parsed harness>"  # "claude" (default) or "codex"

project_options:
  complexity: "<parsed complexity>"
  provider: "sqlite"
  mode: "new_project"
  decomposer: "<parsed decomposer>"

agents:
  - id: "agent_unicorn_1"
    name: "Unicorn Developer 1"
    role: "full-stack"
    skills:
      - "python"
      - "javascript"
      - "typescript"
      - "react"
      - "fastapi"
      - "sqlalchemy"
      - "postgresql"
      - "database-design"
      - "rest-api"
      - "jwt"
      - "security"
      - "pytest"
      - "integration-testing"
    subagents: 0
  # Repeat for each agent...

timeouts:
  project_creation: 600
  agent_startup: 60

Complexity heuristic:

• "prototype" — Simple single-page apps, scripts, small tools
• "standard" — Most projects (APIs, full-stack apps, moderate features)
• "enterprise" — Large systems with many components, microservices, complex auth

Decomposer rule: Default is contract_first as of v0.3.4. Only override to feature_based when the user passes --decomposer feature_based explicitly.

Agent count: Generate one agent block per requested agent. Use incrementing IDs: agent_unicorn_1, agent_unicorn_2, etc.

Step 4: Initialize and Run the Experiment

First, discover the Marcus repo root:

MARCUS_ROOT=$(python3 -c "from pathlib import Path; import marcus_mcp; print(Path(marcus_mcp.__file__).parent.parent.parent)")

Then run it directly (using the current working directory as the experiment directory). IMPORTANT: Use a 600000ms (10 minute) timeout on the Bash command. Project creation includes AI design task generation which takes 4-6 minutes. The default 2-minute Bash timeout will kill the process prematurely.

Append --epictetus, --model <value>, and/or --harness <value> to the command based on what the user passed. All flags combine.

# Codex harness, codex's default model:
cd "${MARCUS_ROOT}/dev-tools/experiments" && python runners/run_experiment.py <cwd> --harness codex

# Codex harness with explicit model:
cd "${MARCUS_ROOT}/dev-tools/experiments" && python runners/run_experiment.py <cwd> --harness codex --model gpt-5-codex

# Claude harness from inside Codex (rare but supported):
cd "${MARCUS_ROOT}/dev-tools/experiments" && python runners/run_experiment.py <cwd> --harness claude

This will:

• Create prompts/, logs/, implementation/ directories
• Initialize a git repo in implementation/
• Copy CLAUDE.md to implementation/
• Pre-flight which claude or which codex depending on --harness
• Create a tmux session: marcus_<project_name_lowercase>
• Spawn: 1 project creator + N workers + 1 monitor in tmux panes
• For codex harness, each pane runs codex exec --dangerously-bypass-approvals-and-sandbox with the Marcus MCP server registered via codex mcp add marcus --url http://localhost:4298/mcp/

Step 5: Report to User

After launching, tell the user:

• The tmux session name: marcus_<project_name_lowercase_underscored>
• The harness being used (claude or codex)
• How to attach: tmux attach -t <session_name>
• How to navigate: Click panes (mouse enabled), Ctrl+b arrow keys, Ctrl+b n/p for windows
• How to kill: tmux kill-session -t <session_name>
• The experiment directory location
• Agent count: 1 creator + N workers + 1 monitor = N+2 total panes

Important Notes

• The Marcus MCP server must be running at http://localhost:4298/mcp before launching
• Each agent is a fully independent harness CLI process. For codex: codex exec --dangerously-bypass-approvals-and-sandbox (approval=never, sandbox=danger-full-access). For claude: claude --dangerously-skip-permissions.
• Agents coordinate via MCP tools (register_agent, request_

Content truncated.