Agent Configuration

Related source file: src/agentmux/configuration/__init__.py

Overview

AgentMux resolves agent configuration from layered config files only.

Resolution order:

1. Built-in defaults shipped in agentmux/configuration/defaults/config.yaml
2. User config in ~/.config/agentmux/config.yaml
3. Project config in .agentmux/config.yaml (or .yml / .json)
4. Optional --config <path> override

Project Initialization

Use agentmux init to scaffold a new project with configuration:

• Interactive mode — Guides you through a quick setup or custom role assignments, GitHub settings, optional MCP setup, and optional prompt stubs
• Non-interactive mode (--defaults) — Creates config with built-in defaults and CLAUDE.md template
• CLI detection — Automatically detects installed providers (claude, codex, gemini, opencode, copilot, qwen)
• Config generation — Creates .agentmux/config.yaml with only necessary overrides (minimal config files)
• CLAUDE.md setup — Creates a template, symlinks an existing file, or skips
• Prompt stubs — Optionally generates role-specific instruction files in .agentmux/prompts/agents/

Interactive init first asks for a default provider, then offers:

• Use default provider for all roles — keeps built-in role defaults and skips per-role provider/model prompts
• Customize roles — prompts for per-role provider and model

After config validation, init checks the effective architect and product-manager providers. If their persistent agentmux MCP entry is missing, init asks once to add it to the provider's native config scope.

Primary project config

The preferred project-level file is .agentmux/config.yaml:

version: 2

defaults:
  session_name: multi-agent-mvp
  provider: claude
  model: sonnet
  max_review_iterations: 3
  completion:
    skip_final_approval: false

github:
  base_branch: main
  draft: true
  branch_prefix: feature/

roles:
  architect:
    model: opus
  reviewer:
    model: sonnet
  coder:
    provider: codex
    model: gpt-5.3-codex

IDE autocompletion

agentmux init automatically adds a yaml-language-server directive at the top of .agentmux/config.yaml. This enables schema validation and autocompletion in editors that support yaml-language-server (VS Code, Cursor, etc.):

# yaml-language-server: $schema=https://raw.githubusercontent.com/markuswondrak/AgentMux/main/src/agentmux/configuration/defaults/config.schema.json
version: 2
...

If you manage the file by hand, add that line yourself. For local development, use the local path variant instead:

# yaml-language-server: $schema=./src/agentmux/configuration/defaults/config.schema.json

Config structure

• version — Required. Must be 2 for new configs. Configs without version or with version: 1 will fail with a helpful migration message.
• defaults.session_name — legacy fallback used only when resuming old sessions that do not yet persist state.json.session_name; new runs derive tmux names from the feature directory (agentmux-<feature_dir_name>)
• defaults.provider — default provider name for roles that do not override it
• defaults.model — default model name (e.g., sonnet, opus, gpt-5.3-codex)
• defaults.max_review_iterations — caps automatic reviewer→coder fix loops
• defaults.completion.skip_final_approval — when true, skips reviewer confirmation in completing and auto-prepares approval (default: false)
• github.base_branch — default PR base branch (default: main)
• github.draft — whether PRs created at completion are draft PRs by default (default: true)
• github.branch_prefix — prefix for completion branches created before opening a PR (default: feature/)
• roles.<role>.provider — optional provider override per role
• roles.<role>.model — model name for that role (direct model selection, no profiles)
• roles.<role>.args — optional full override of the resolved CLI args for that role

Built-in and user-level configs may additionally define:

• providers.<name>.command — CLI binary or wrapper command
• providers.<name>.model_flag — model switch, default --model
• providers.<name>.trust_snippet — auto-accept text for trust prompts
• providers.<name>.role_args.<role> — default CLI args for a role
• providers.<name>.single_coder — when true, the implementing phase sends one combined prompt covering all sub-plans to a single coder pane instead of spawning parallel/serial panes. The coder is expected to use its own internal sub-agents. Default: false.
• providers.<name>.sub_agent_tool — optional string. In single-coder mode, the whole-plan coder prompt’s item 14 tells the model to delegate work in parallel using the slash command /<value> (for example task → /task). When omitted, item 14 describes sequential delegation (finish one plan’s sub-agent before starting the next). Built-in copilot sets sub_agent_tool: task so the prompt matches Copilot CLI’s /task flow alongside the /fleet prefix the runtime sends before the prompt file.

Completion settings boundary

There is one runtime completion-settings owner: workflow_settings.completion.

• Config input maps directly into defaults.completion.skip_final_approval
• Runtime reads workflow_settings.completion.skip_final_approval

Project vs user scope

Project config can define defaults, roles, github, and now also providers (in v2). This allows teams to ship complete project-specific configurations.

User config can define defaults, roles, github, and providers.

Example user config:

version: 2
providers:
  kimi:
    command: kimi
    model_flag: --model-name
    trust_snippet: Trust this folder?
    role_args:
      coder: [--sandbox, workspace-write]

After that, a project can safely select it:

version: 2
roles:
  coder:
    provider: kimi
    model: kimi-2.5

GitHub Copilot CLI provider

copilot (from npm install -g @github/copilot) is a built-in provider. Install the CLI, then select it as the default provider or per role:

version: 2
defaults:
  provider: copilot
  model: claude-sonnet-4.6

Per-role model selection:

version: 2
defaults:
  provider: copilot
  model: claude-sonnet-4.6
roles:
  architect:
    model: claude-opus-4.6
  reviewer_expert:
    model: gpt-5.4

Supported models: claude-sonnet-4.6, claude-opus-4.6, gpt-5.4, gemini-2.5-pro. Models are selected via --model=<model>.

copilot uses --allow-all for all roles to enable non-interactive operation. Additionally, model_args appends --reasoning-effort high for models that support it (claude-sonnet-4.6, claude-opus-4.6). On first run in a directory, Copilot CLI asks "Do you trust the files in this folder?" — Agentmux auto-accepts this via the trust_snippet: "trust the files" configuration.

Qwen CLI provider

qwen is a built-in provider. The bundled defaults use qwen3-max as the provider default model and pass --yolo for every role. When research-enabled roles need MCP setup, AgentMux manages the persistent registration in ~/.qwen/settings.json.

Cursor CLI provider

The built-in cursor provider runs the Cursor CLI binary agent. That CLI only allows --trust together with headless/--print usage; interactive tmux panes therefore do not receive --trust in the default configuration. Trust prompts in the pane are handled via trust_snippet (default "Allow") and trust_key (default a), which drive automatic key acceptance in tmux. Batch research roles (code-researcher, web-researcher) pass the prompt file with -p and include --trust and --force in built-in role_args only for those roles.

Provider default settings

Providers can define default_model and default_role_args that apply to all roles automatically:

version: 2
providers:
  my-provider:
    command: my-cli
    model_flag: --model
    default_model: my-default-model
    default_role_args:
    - --shared-flag
    - shared-value
    role_args:
      coder:
      - --coder-specific

In this example, the coder role receives both [--shared-flag, shared-value, --coder-specific]. The copilot provider uses default_role_args to set [--allow-all] for all roles, and model_args to append [--reasoning-effort, high] for specific models like claude-sonnet-4.6.

Model-specific arguments

Providers can define model_args to append extra CLI flags when a specific model is selected:

version: 2
providers:
  copilot:
    model_args:
      claude-sonnet-4.6:
      - --reasoning-effort
      - high
      claude-opus-4.6:
      - --reasoning-effort
      - high

These args are appended after default_role_args and role_args. To override the built-in reasoning level in a project config, set your own model_args for the model (list replace semantics via deep merge).

Single-coder mode

copilot has single_coder: true set in its built-in provider config. This means the implementing phase sends one combined prompt to a single copilot pane instead of spawning separate panes for each sub-plan. The prompt embeds all plan and tasks content, and instructs copilot to use its own internal sub-agents to implement each plan. Copilot writes the done_N completion marker files as each plan finishes (or all at once at the end).

Built-in copilot also sets sub_agent_tool: task. That value flows into the resolved coder AgentConfig and switches item 14 of the whole-plan prompt to parallel instructions that reference `/task` (in addition to the completion-tool steps in item 13). Providers without sub_agent_tool keep the sequential item 14 (one plan at a time).

When the coder provider is copilot with single_coder: true, the /fleet slash command is automatically sent as keystrokes before the prompt file reference. This tells Copilot CLI to decompose the embedded plan into sub-agent tasks and execute them in parallel, with the main copilot instance acting as orchestrator. The /fleet command is sent interactively (not embedded in the prompt file) because Copilot CLI only recognizes slash commands when entered as direct input. The prefix is applied transparently — no extra config flag is needed.

This design avoids multiple premium-request invocations (one per sub-plan pane) in favour of a single invocation where copilot manages parallelism internally via /fleet.

The single_coder flag can also be set on any custom provider definition in user or project config:

version: 2
providers:
  my-provider:
    command: my-cli
    model_flag: --model
    single_coder: true
    role_args:
      coder: [--allow-all]

Note: The automatic /fleet prefix command is only sent when the coder's provider is copilot. Other providers with single_coder: true receive the combined prompt without the prefix command.

Strict schema

Unsupported legacy forms now fail fast:

• profile key (use model directly)
• launchers: key (renamed to providers:)
• profiles: section (removed entirely)
• top-level role config outside roles
• top-level defaults such as session_name, provider, or max_review_iterations
• defaults.skip_final_approval
• defaults.completion.require_final_approval
• role tier

Migration from v1 to v2

If you have an existing v1 config, you'll see an error like:

Legacy config detected (version: 1). Please migrate to version: 2.
- Rename 'launchers:' to 'providers:'
- Replace 'profile: <name>' with 'model: <model-name>'
- Remove 'profiles:' section

To migrate:

1. Change version: 1 to version: 2
2. Rename launchers: to providers:
3. Replace profile: <profile_name> with model: <model_name> directly
4. Remove the entire profiles: section
5. Remove any custom profiles you defined (models are now specified directly)

Example migration:

# v1 config
version: 1
defaults:
  provider: claude
  profile: standard
roles:
  architect:
    profile: max
  coder:
    provider: codex
    profile: standard

# Becomes v2 config
version: 2
defaults:
  provider: claude
  model: sonnet
roles:
  architect:
    model: opus
  coder:
    provider: codex
    model: gpt-5.3-codex

Resolution

Each role resolves to an AgentConfig with:

• cli
• model_flag
• model
• args
• env (optional runtime environment variables to prepend via env KEY=VALUE ...)
• trust_snippet
• sub_agent_tool (optional; copied from the resolved provider when set)

The tmux runtime launches agents from that fully resolved config. AgentMux still never talks to model APIs directly.

OpenCode provider: model configuration caveat

When using the opencode provider with --agent, opencode ignores the --model flag entirely. The model is determined solely by the agent.<agent-name>.model entry in opencode.json.

AgentMux detects this mismatch at startup: if model: is configured for an opencode role in agentmux config, a warning is printed to stderr and the user is prompted to choose:

• [a] Add the configured model to opencode.json for the matching agent, then continue (AgentMux updates the file automatically)
• [y] Continue without updating opencode.json (the model from opencode.json will be used)
• [n] Abort (default)

To configure which model opencode uses, set it in opencode.json:

{
  "agent": {
    "agentmux-coder": {
      "model": "qwen3"
    }
  }
}

The warning shows the full picture: what was configured in agentmux, what will actually happen, and how to fix it.

Runtime MCP setup for research tools

MCP setup for research uses a two-layer configuration approach that separates persistent project-level config from runtime-generated config.

Persistent config (project-level)

agentmux init and foreground pipeline startup check whether the effective architect / product-manager providers already have an agentmux entry in the provider's native config location:

• Claude: project .claude/settings.json
• Codex: user ~/.codex/config.toml
• Copilot: user ~/.copilot/mcp-config.json
• Gemini: project .gemini/settings.json
• OpenCode: project opencode.json
• Qwen: user ~/.qwen/settings.json

When the entry is missing, the user is prompted to create or refresh it. This persistent config serves as a fallback for manual CLI tool usage outside the pipeline.

Idempotent behavior: The setup process compares existing server entries to the generated entry before writing. If the configuration is unchanged, the file is not modified. This prevents unnecessary writes that could invalidate MCP approval caches. The comparison checks the type, command, and args fields to determine if an update is needed.

Runtime config (generated at startup)

At pipeline startup, a runtime MCP config file is generated at .agentmux/mcp_servers.json inside the project directory. This file contains:

{
  "mcpServers": {
    "agentmux": {
      "type": "stdio",
      "command": "/path/to/python",
      "args": ["-m", "agentmux.integrations.mcp_server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/project"
      }
    }
  }
}

Key characteristics:

• Contains absolute paths specific to the current environment
• Generated fresh on each pipeline run
• Passed to Claude via the --mcp-config <path> command-line flag
• Not meant to be committed to version control (runtime artifact)
• Content is compared before writing to avoid unnecessary updates

Runtime injection

For Claude agents, the pipeline appends ["--mcp-config", ".agentmux/mcp_servers.json"] to the launch arguments. This bypasses project-level settings trust requirements by explicitly providing the MCP server configuration at runtime.

For other providers (Codex, Copilot, Gemini, OpenCode, Qwen), the pipeline only injects PYTHONPATH=<project_dir> into the launched process environment so the research server can import the project checkout.

Claude additionally needs explicit tool allowlisting, so defaults include mcp__agentmux__* in architect/product-manager --allowedTools. Other bundled providers run in approval modes that auto-approve tool calls.