Manage coding agents

melious tools is where you install, update, check, and repair the coding agents that melious launch starts, and where you give one agent different models from the rest.

Installing an agent is a separate step from launching it. tools install gets the binary onto your machine; it doesn't configure the agent or start it. Configuration happens on every launch, so there's nothing to set up in between.

See what's installed

melious tools

You get one row per agent: claude-code, codex, opencode, pi, and vibe. Each row shows whether the agent is installed, installed but outside your PATH, or not found, plus its version, its per-agent main model (or global), and how Melious configures it. Your default tool is highlighted, and the footer names it along with your global main model. A Mac with four of the five agents installed, with the list of tips at the end cut short:

  Supported Tools

  TOOL         STATUS       VERSION  MODEL
     INTEGRATION
  ────────────────────────────────────────────────────────────────────────────
  claude-code  ✓ Installed  2.1.303  global
     Env vars (Anthropic API)
     Anthropic's agentic coding tool. Token-heavy on third-party providers —
     expect higher costs.
  codex        ✓ Installed  0.163.0  global
     CLI overrides (Responses API)
     OpenAI's terminal coding agent. Runs one model through the Responses API.
  opencode     ✓ Installed  1.18.15  global
     Config file (JSON)
     Open-source terminal coding agent. Efficient token usage, fast, and fully
     featured.
  pi           ✓ Installed  0.84.1   global
     Config file (models.json)
     Minimal, customizable terminal coding agent. Runs one active model — no
     tier routing.
  vibe         ✗ Not found  -        global
     Config file (VIBE_HOME)
     Mistral's open-source terminal coding agent. Python-based, multi-provider
     support.

  Default: claude-code  Model: glm-5.2
  Tip: melious tools model <tool> <model> → set per-tool model
       melious tools install <tool> → install missing tools or show their setup command
       …

On a wider terminal, the integration moves up into its own column.

Install an agent

melious tools install <TOOL>

Melious runs an install itself in exactly two cases: Pi on macOS and Linux, and Vibe on Windows. For everything else we print the vendor's own command for you to read and run, because we'd rather not pipe someone else's installer into your shell on your behalf:

Agent	macOS and Linux	Windows	Needs
`claude-code`	Prints command	Prints command	None
`codex`	Prints command	Prints command	None
`opencode`	Prints command	Prints `npm` command	Node.js and npm, on Windows
`pi`	Runs `npm`, after asking	Prints `npm` command	Node.js 22.19+ and npm
`vibe`	Prints command	Runs `uv`, after asking	`uv`, on Windows

The two commands Melious runs itself:

# Pi on macOS and Linux
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# Vibe on Windows
uv tool install mistral-vibe

--ignore-scripts is deliberate: it stops a dependency's install script from running as part of a global install. Before either command runs, Melious checks that its prerequisite exists and stops with an error if it doesn't. It shows the command and asks before running it, and without a terminal to ask on, it prints the command and exits non-zero instead.

If the agent is already installed, tools install says so and changes nothing. If it's installed somewhere your shell doesn't look, Melious offers to add that directory to your PATH rather than installing a second copy.

For anything beyond the one-liner — other install methods, system requirements, sign-in — go to the vendor: Claude Code, Codex, OpenCode, Pi, and Mistral Vibe.

Install everything missing

melious tools install --all

--all runs every automatic install for missing agents without asking. Passing it is the yes, given in advance, which is why it's the form to use when provisioning a CI image or a container. Agents that can only be installed by hand are listed with their commands at the end.

The exit status is non-zero if an automatic install failed or a prerequisite was missing. Agents you still have to install yourself don't count as failures.

Update agents

melious tools update <TOOL>
melious tools update

With an agent named, Melious updates that one. Without one, it goes through every installed agent. Where there's an automatic action (Pi on macOS and Linux, Vibe on Windows), tools update runs it straight away, without asking. For the other agents it prints the vendor's command, as tools install does.

Pi updates by reinstalling through the same npm install -g line. Vibe on Windows runs uv tool upgrade mistral-vibe. Updating an agent that isn't installed fails and points you at tools install.

Check, inspect, and diagnose

Three commands for when something doesn't start. None of them changes anything unless you accept a fix.

tools check lists the runtimes the agents need (Node.js, npm, and uv, as your platform requires them) with their versions, then every agent with its version or its install command:

melious tools check

On the same Mac, where only Pi needs a runtime:

  Prerequisites Check

  ✓ node         v24.15.0  (pi)
  ✓ npm          11.12.1  (pi)

  Tools

  ✓ Claude Code      2.1.303 (Claude Code)
  ✓ OpenAI Codex     codex-cli 0.163.0
  ✓ OpenCode         1.18.15
  ✓ Pi               0.84.1
  ✗ Mistral Vibe     curl -LsSf https://mistral.ai/vibe/install.sh | bash

tools info shows everything about one agent: homepage, install status, version, executable, prerequisites, how Melious configures it, and the models it would launch with right now:

melious tools info <TOOL>

For Pi, with the global models:

  Pi
  Minimal, customizable terminal coding agent. Runs one active model — no tier routing.
  Homepage: https://pi.dev

  ✓ Installed
  Version: 0.84.1
  Command: pi
  Prereqs: node ✓, npm ✓
  Method: Config file (models.json)

  Model Configuration
  Main:          glm-5.2 (global)
  Secondary:     minimax-m3
  Lightweight:   deepseek-v4-flash

  Available Commands
  melious tools install pi install/reinstall
  melious tools update pi update
  melious tools diagnose pi run diagnostics

tools diagnose looks for problems in one agent, or in all of them when you leave the name off:

melious tools diagnose <TOOL>

Without a name, on the same Mac:

  ✓ Claude Code — no issues found
  ✓ OpenAI Codex — no issues found
  ✓ OpenCode — no issues found
  ✓ Pi — no issues found

  ⚠ Mistral Vibe — 1 issue(s)
    ✗ Mistral Vibe is not installed
      Fix: curl -LsSf https://mistral.ai/vibe/install.sh | bash

It checks:

whether the agent is installed, with the install command if it isn't
whether it's outside your PATH, and offers to add it
whether its prerequisites are installed
for Pi, whether Node.js is at least 22.19
for Pi on Windows, whether there's a bash for Pi's shell tool (it looks for Git for Windows), and whether a shellPath in Pi's settings points at a file that exists

Each finding comes with a severity (error, warning, or info) and a fix command where there is one. On a terminal, Melious offers to apply the PATH fix for you. tools check and tools diagnose exit 0 even when they find problems, so read their output instead of branching on the status.

Fix your PATH

melious tools fix-path

This finds agents installed in common directories your shell doesn't search, such as ~/.local/bin, ~/.npm-global/bin, and %APPDATA%\npm. It lists those directories and asks before changing anything, so run it in a terminal.

If you say yes, it adds each directory permanently:

zsh: appends an export PATH=… line to ~/.zshrc
fish: writes ~/.config/fish/conf.d/melious.fish
any other shell: appends the line to ~/.bashrc
Windows: adds the directory to your user Path in the registry

A line that's already there isn't added twice. Open a new terminal afterwards, because a shell that's already running won't reread its profile. If you use bash on macOS, check that your login shell actually reads ~/.bashrc; many only read ~/.bash_profile.

melious uninstall doesn't undo these edits. Remove the line, or the registry entry, yourself if you no longer want it.

Give one agent its own models

tools model sets models for one agent only. Other agents keep using the global models.* settings.

The same choices are in the terminal UI: run melious and open Default models. There, ← and → pick all tools or one tool, tab picks the slot, enter sets a model, / searches the list, and x resets the tool to the global models. The screen names Claude Code's slots Opus, Sonnet and Haiku, and marks a slot the tool ignores as "not used by" that tool.

Show what an agent would use now:

melious tools model <TOOL>

Set its main model:

melious tools model <TOOL> <MODEL_ID>

Set the other tiers, together with the main model or on their own:

melious tools model <TOOL> <MODEL_ID> \
  --secondary <MODEL_ID> \
  --lightweight <MODEL_ID>

Remove every override for that agent and go back to the global models:

melious tools model <TOOL> --clear

Overrides are stored under tool_models.<TOOL> in your config file. Each tier you don't set falls back to its global value. Melious doesn't check the ID against the model list, so a typo only shows up when you launch; run melious models first if you're unsure of the name.

For a launch, the order is: --model, --secondary, and --lightweight on melious launch, then the agent's tools model overrides, then the global models.*. Not every agent uses every tier; Codex and Vibe, for example, only use the main model. The launch guide lists which tiers each agent reads.

Version checks and trust

melious tools and its install, update, check, info, diagnose, and fix-path subcommands run each installed agent's own --version to report its version. They run it in your current directory, and they don't ask for workspace trust first. tools model doesn't run any agent. The launcher is stricter: it skips an agent's version check until the workspace is trusted.

Scripting

No tools command has JSON output. Each one refuses --json with exit status 1 and nothing on stdout. Scripting covers what you can rely on in scripts.

On this page