Provider Notes

​

Custom Configuration

​

Custom Arguments

• Claude Code: --model claude-sonnet-4-20250514 to specify a particular model
• Codex: -m o3 to use a specific OpenAI model
• OpenCode: --model anthropic/claude-sonnet-4-20250514 to configure the model

​

Environment Variables

• API keys and authentication tokens
• Configuration overrides (e.g., CLAUDE_CONFIG_DIR or CODEX_HOME for multiple accounts)
• Provider-specific settings

​

Switching Providers with Memory and Session Carry

maestro-cli update-agent <agent-id> --provider codex --dry-run --json
maestro-cli update-agent <agent-id> --provider codex --migration-plan <plan-id> --accept-translation-limitations --json
maestro-cli update-agent <agent-id> --migration status --migration-plan <plan-id> --json

​

Starting Translation from Cue

subscriptions:
  - name: plan-provider-translation
    pipeline_name: Provider Translation
    agent_id: CONTROLLER_AGENT_ID
    event: agent.completed
    source_session_ids: [SOURCE_AGENT_ID]
    enabled: true
    action: command
    command:
      mode: shell
      shell: >-
        maestro-cli update-agent SOURCE_AGENT_ID
        --provider codex --dry-run --json

​

Claude Code

• Claude Code’s TUI supports injecting user messages mid-turn (between tool calls in its agentic loop), but this is not available in batch mode (--print). Maestro uses batch mode, so new messages are queued and sent after the current turn completes via --resume. This is a limitation of the CLI’s batch interface, not Maestro.
• Maestro sets CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 by default for every Claude Code spawn (desktop UI, CLI batch, --live, SSH). This disables Claude Code’s Bash run_in_background + Monitor feature, which is incompatible with Maestro for two reasons: (1) short-lived CLI batch sessions exit before background tasks finish, silently losing results; and (2) the polling wrapper Claude Code generates around each background task can deadlock on a self-matching pgrep -f predicate when the watched command regex appears verbatim in the wrapper’s own argv, leaving long-running desktop tabs stuck on a zsh until loop that can never satisfy its exit condition. Maestro’s multi-tab terminals cover the same use cases (watch a dev server, tail a log) more reliably. To re-enable, export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=0 from your shell, or set it per-agent under Settings → Providers → Claude Code → Environment Variables.
• Ask-back questions require Standard permission mode. In Standard mode Maestro injects a permission relay into Claude Code (API mode) that surfaces tool approvals and AskUserQuestion ask-backs as in-app prompts you answer inline. Full Access passes --dangerously-skip-permissions and skips the relay, so an AskUserQuestion call there has nowhere to go: the question never appears and the turn stalls until you stop the agent. A follow-up message won’t recover it either: it only queues behind the stalled turn, which never completes to dispatch it. Read-Only mode also runs without the relay. SSH remote agents can’t use Standard mode at all: a Standard-mode Claude Code spawn over SSH fails loudly (the relay socket is local-only and can’t mediate a remote spawn) rather than downgrading, so SSH agents always run in Full Access or Read-Only, which is why ask-backs never surface there. This is the expected trade-off of bypassing permissions, not a defect; switch the tab to Standard mode when you want ask-back questions to work.

​

Token Source

• Signed in with a Claude plan (Pro, Max, Team): both modes draw from that plan’s 5-hour and weekly limits. Anthropic confirms this for claude -p in Monthly API credits for Max and Team plans.
• An API key, gateway, or cloud provider (ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, Bedrock, Vertex) in the agent’s environment: both modes bill that credential instead. A Max or Team plan’s monthly API credits are spent this way, through a key from the linked Claude Console organization.

​

Codex (OpenAI)

• Codex’s resume subcommand doesn’t accept the -i/--image flag. Images can only be attached when starting a new session. Maestro hides the attach image button when resuming Codex sessions.
• Your custom Codex commands appear in Maestro’s / autocomplete. Maestro reads them straight off disk from <CODEX_HOME>/skills/<name>/SKILL.md and .codex/skills/ (plus <CODEX_HOME>/prompts/*.md on older Codex builds), so no extra setup is needed. CODEX_HOME is honoured, and a project-local command shadows a global one with the same name. A skill marked user-invocable: false is skipped, matching Codex’s own picker.
• Because Maestro drives Codex through codex exec, the CLI never expands the slash itself. Maestro substitutes the command’s file contents before sending, so the agent receives the fully expanded prompt.
• Codex’s built-in slash commands (/compact, /diff, /model, etc.) are still unavailable: they are implemented inside the interactive TUI and have no on-disk prompt to expand.
• Codex commands on an SSH remote agent are not discovered yet, since the skills live on the remote host.

​

App Server Transport (Experimental)

• Agent settings: set Codex Transport to codex app-server in the New Agent or Edit Agent dialog.
• CLI: maestro-cli update-agent <agent-id> --codex-transport app-server (use exec to switch back).

• SSH remote agents
• Prompts with attached images
• Auto Run, Maestro Cue, and maestro-cli batch runs

​

Nonfatal notices

• Dark
• Light

​

OpenCode

• OpenCode uses the run subcommand which auto-approves all permissions (similar to Codex’s YOLO mode). Maestro enables this via the OPENCODE_CONFIG_CONTENT environment variable.

​

Factory Droid

• Maestro drives Factory Droid through its droid exec batch subcommand with -o stream-json output. Read-only agents run in the default mode with no auto-approval flags.

​

Copilot-CLI

• Copilot-CLI is multi-model via models.dev. Maestro maps image uploads to temporary-file @image mentions in the prompt, which also works on resumed sessions.

​

Hermes

• Hermes is Nous Research’s coding agent. Set a documented model override (for example anthropic/claude-sonnet-4-20250514) under Settings → Providers → Hermes, or leave it blank for the CLI default.
• On Windows, Maestro passes batch prompts through stdin with hermes chat -Q --yolo --query-file -. The explicit query source keeps Auto Run and tab naming out of the interactive TUI without exposing long prompts to the Windows command-line limit. Hermes must support chat --query-file; update Hermes if your installation does not list it in hermes chat --help.

​

Pi

• Pi is a customizable agent harness. Maestro uses its JSON output mode and enforces read-only agents by restricting the tool set to read-only tools.

​

Qwen3 Coder

• Qwen3 Coder is Alibaba’s Qwen Code agent, a Gemini CLI fork. It is multi-provider, so any model id works (for example qwen3-coder-plus or an OpenAI-compatible id); leave the model blank for the account default.

​

Oh My Pi

• Oh My Pi is a multi-model coding agent, invoked via the omp CLI.
• OpenCode Agent (in an agent’s settings) picks the primary OpenCode agent for that Maestro agent, running it as opencode run --agent <name>. Use it to keep an agent pinned to a specific persona, model, and instruction set: point one Maestro agent at build, another at a plugin-provided agent, then group chat across them. Plugin agents (for example the ones oh-my-opencode registers) work even though opencode agent list doesn’t print them, since OpenCode resolves the name at run time. The value is stored in that agent’s Custom Arguments, so it is per-agent rather than shared across every OpenCode agent. Plan mode still forces --agent plan and ignores the selection for that turn.