Skip to main content
Each AI provider has unique capabilities and limitations. Maestro adapts its UI based on what each provider supports.

​
Custom Configuration

All providers support custom command-line arguments and environment variables. Configure these in Settings → Providers for each agent type.
Provider configuration showing custom arguments and environment variables

​
Custom Arguments

Additional CLI arguments are appended to every call to the agent. Common use cases:
  • 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

Environment variables are passed to the agent process. Use these for:
  • API keys and authentication tokens
  • Configuration overrides (e.g., CLAUDE_CONFIG_DIR or CODEX_HOME for multiple accounts)
  • Provider-specific settings
The MAESTRO_SESSION_RESUMED variable is automatically set to 1 when resuming sessions - you don’t need to configure this manually.

​
Claude Code

Notes:
  • 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: Max plan vs. API

Claude Code agents can bill against either your Anthropic API credit or your Claude Max plan quota. Pick the source per-agent under Settings → Providers → Claude Code (or in the New Agent / Edit Agent dialog), and Maestro can show a matching pill on each captured turn. The pill is off by default. Turn it on under Settings → Display → Provider Mode Pill to show it under chat responses and on History entries. When a window does run dry, Agent Resilience takes the turn over: it reads the reset moment out of Claude’s own banner (resets 11:40am (America/Chicago)) and resends your prompt then, instead of leaving you to notice and retype it. The TUI Wrapper and Dynamic modes are powered by maestro-p, a small standalone helper that drives Claude Code’s interactive TUI (the mode that draws on your Max plan quota rather than per-token API credit). It ships bundled with the desktop app, so local agents work out of the box.
For SSH remote agents, maestro-p must be installed on the remote host’s PATH, since the TUI runs there rather than on your machine. If it is missing, Maestro disables the Max plan options and falls back to API. Install it from the maestro-p install page, then click Re-check in the agent’s Claude Token Source panel.

​
Codex (OpenAI)

Notes:
  • 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.

​
OpenCode

Notes:
  • 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

Notes:
  • 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

Notes:
  • 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

Notes:
  • 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.

​
Pi

Notes:
  • 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

Notes:
  • 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

Notes:
  • 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.