Launch a coding agent

melious launch starts a coding agent you've installed, pointed at the Melious API, in your current terminal.

It's for when you want the agent you already use, without working out where that agent keeps its provider settings or which variable it reads for a key. You'll need to be logged in (melious auth login) and have the agent installed. Manage coding agents covers the install part.

Launch an agent:

melious launch <TOOL> [-- <TOOL_ARGS>]

For example:

melious launch opencode

Supported agents

Claude Code gets its settings through environment variables alone. Your credential goes in as ANTHROPIC_AUTH_TOKEN, and the three tiers map onto Claude Code's model aliases: opus is your main model, sonnet your secondary, haiku your lightweight. Your own Claude Code settings, sessions, and login stay where they are.

Codex gets the Melious provider and your main model as per-invocation overrides on its command line, using the Responses API. Melious writes no file and doesn't touch your Codex config. Codex runs one model at a time, so the other tiers don't apply.

OpenCode gets a generated config file with Melious registered as its provider and the models on your account listed, so you can switch models inside OpenCode. An environment overlay keeps the Melious route in place even if a project's own OpenCode config names a different one. That overlay protects where your key goes; it isn't a sandbox.

Pi gets a generated models.json in a Melious-managed agent directory, so your own ~/.pi/agent is left alone. No Pi extension is needed. Pi starts on your main model and has all three tiers in its model cycle.

Mistral Vibe gets a generated TOML config, found through VIBE_HOME. Vibe reads your key from the environment, so Melious writes no .env file.

The generated files for OpenCode, Pi, and Vibe live under ~/.melious/tool-configs/<TOOL>/, and Melious rewrites them on every launch. Change settings through Melious — see choose models — not in those files. Setting an agent up by hand instead? Each agent's integration page covers it: Claude Code, Codex, OpenCode, Pi, Mistral Vibe.

What happens when you launch

1. Melious checks the agent is installed. If it isn't, you get the install command and a non-zero exit. Nothing else happens. On macOS, for Vibe:

     ✗ Mistral Vibe is not installed.
   
     Install with:
       curl -LsSf https://mistral.ai/vibe/install.sh | bash

2. Melious checks the project is trusted. The first launch in a new project asks whether to trust it. The answer defaults to No. Workspace trust covers the question, what a yes records, and how to answer it ahead of time, and what a no prints. Say yes, and Melious confirms before the agent takes over the terminal:

     ✓ Workspace trust recorded
       ~/code/shop

3. Melious writes the agent's configuration. Each agent gets the setup described above; your own agent config is left alone.

4. The agent starts in your terminal, in your current directory, with your Melious credential in its environment.

5. When the agent exits, you're back at your shell with the agent's own exit status, so melious launch <TOOL> && ./next-step.sh behaves the way you'd expect. If you started the agent from the launcher in bare melious, you return to the launcher instead.

launch doesn't support --json. The agent owns your terminal, so there's no machine-readable result to return.

Default and recommended agents

Run launch without naming an agent and Melious starts your default:

melious launch

The default is the defaults.tool setting. It's claude-code out of the box, and we can change that remotely through Melious's published defaults. Set your own and it always wins:

melious config set defaults.tool <TOOL>

You'll also see a recommended badge on OpenCode in the launcher and in setup. That's our pick, and it's a separate thing from the default. The badge doesn't change what melious launch starts. Only defaults.tool does.

Choose models

Each agent uses up to three model tiers: main, secondary, and lightweight. Melious decides each tier in this order, first match wins:

1. The session flags on this launch: --model, --secondary, --lightweight
2. A per-agent override set with melious tools model <TOOL>
3. The global models.main, models.secondary, and models.lightweight settings

Try a model for one session:

melious launch claude-code --model <MODEL_ID>

Make it stick for one agent only:

melious tools model opencode <MODEL_ID>

Not every agent reads every tier (see supported agents). Setting --secondary for Codex does nothing, and Melious doesn't warn about it. If no secondary model is set, Claude Code falls back to your main model for the sonnet alias.

--preset applies a routing preset (balanced, speed, price, or eco) to every tier for this launch. Routing explains what each one trades. The global settings are covered in Configuration, and per-agent overrides in Manage coding agents.

Pass arguments to the agent

Everything after -- goes to the agent untouched:

melious launch claude-code -- --continue

Melious doesn't read or validate these arguments. If the agent rejects one, that's the agent's error message and exit status you'll see.

The -- is optional when the arguments follow the tool name. Melious treats a flag it doesn't own as the start of the agent's arguments:

melious launch claude-code --dangerously-skip-permissions

--dangerously-skip-permissions removes Claude Code's own permission prompts, so the agent can run tools and change files without asking. Melious prints a warning on stderr before the launch whenever that flag is passed, with or without --:

  ⚠ --dangerously-skip-permissions lets the agent run tools and change files without asking.

The launch still needs workspace trust; the warning comes before the trust check, so you see it even when the launch is refused.

Flags

The launcher in bare melious doesn't take model flags, --trust-once, or passthrough arguments. Use melious launch when you need them.

What Melious sets for telemetry

Melious sets a telemetry-related variable for two agents, and only these:

• Claude Code: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
• Pi: PI_TELEMETRY=0 and PI_SKIP_VERSION_CHECK=1

For Codex, OpenCode, and Vibe, Melious sets nothing. Each agent has its own telemetry policy, and its own documentation is the place to check what it sends and how to turn it off.

Your credential and the agent

The launched agent receives your Melious credential in its environment. It can pass that credential to any process it starts: a shell command, a build script, a plugin.

Melious puts your key only in the variable the selected agent reads, and removes other agents' credential variables from the environment. It can't control what the agent does after it starts. That's why workspace trust exists.