mlx-agent

Discover, verify, and operate local MLX models on Apple Silicon for your coding agent. mlx-agent ranks candidates for your memory budget, records local role checks, measures served models, and writes reviewed connection configurations.

The Python core uses the standard library. Model execution needs a separately installed runtime; optional backends have their own dependencies.

Current package version: 0.9.0. These docs describe the current checkout; published releases may contain earlier behavior.

Install

Choose your coding-agent host. Install its CLI first, then restart it after adding mlx-agent. See Installation for requirements and provider lifecycle for project scope, updates, removal, and recovery.

Claude Code

claude plugin marketplace add cavi-ai/mlx-agent
claude plugin install mlx-agent@mlx-agent

Run /mlx-scout after restarting.

Codex CLI

codex plugin marketplace add cavi-ai/mlx-agent --ref v0.9.0
codex plugin add mlx-agent@mlx-agent

Invoke $mlx-agent:mlx-scout after restarting. Codex does not support custom slash commands.

Agy

git clone --depth 1 --branch v0.9.0 https://github.com/cavi-ai/mlx-agent.git
agy plugin validate ./mlx-agent/providers/agy
agy plugin install ./mlx-agent/providers/agy

Restart Agy, check /skills, and ask it to use mlx-scout.

OpenCode and portable skills

From a release checkout:

git clone --depth 1 --branch v0.9.0 https://github.com/cavi-ai/mlx-agent.git
cd mlx-agent
python3 scripts/mlx-agent install opencode --scope user --dry-run --json
# Review the plan; copy data.preview.preview_hash.
python3 scripts/mlx-agent install opencode --scope user --confirm --preview-hash <preview-hash> --json
python3 scripts/mlx-agent doctor opencode --scope user --json

Restart OpenCode and use /mlx-scout. For AgentSkills-compatible hosts, use the same preview/confirm sequence with agentskills:

python3 scripts/mlx-agent install agentskills --scope user --dry-run --json
python3 scripts/mlx-agent install agentskills --scope user --confirm --preview-hash <preview-hash> --json

The installer copies a runtime into each installed portable skill. Move unowned older mlx-* skill folders aside before the first managed install.

OpenClaw and Hermes Agent

From the same checkout, use the preview/confirm sequence with openclaw or hermes:

python3 scripts/mlx-agent install openclaw --scope user --dry-run --json
python3 scripts/mlx-agent install openclaw --scope user --confirm --preview-hash <preview-hash> --json

Skills go to $OPENCLAW_STATE_DIR/skills (default ~/.openclaw/skills) or $HERMES_HOME/skills (default ~/.hermes/skills). Start a new session and use /mlx-scout.

Other MCP hosts

The mlx-agent package on PyPI carries the CLI and the MCP server. Add the server to any MCP host's configuration:

{
  "mcpServers": {
    "mlx-agent": {"command": "uvx", "args": ["--from", "mlx-agent", "mlx-agent-mcp"]}
  }
}

Install the CLI with uv tool install mlx-agent or pipx install mlx-agent. Provider installation copies the plugin files, so mlx-agent install runs from a checkout.

First local model

From a checkout, inspect the host and find candidates:

python3 scripts/mlx-agent inspect-host --json
python3 scripts/mlx-agent discover --role coding --limit 3 --json

Review size, license, gating, runtime compatibility, and evidence. Discovery does not download weights. Make the chosen model available with your runtime or an explicitly confirmed Intake download, then start its local server.

Intake can also list existing MLX conversions of a source model on the Hub. Review these candidates before downloading or converting weights.

Follow Your first local model to load weights, verify the shortlist, measure performance, and preview a configuration. Keep the returned receipts for inspection and rollback.

What you can do

Understand the evidence

Models retain a primary role and may also have tool-use membership. For tool-use, metadata is not verification: recommendation requires a schema-valid synthetic runtime tool call. The bounded probe supports Ollama and local OpenAI-compatible LM Studio, mlx_lm, and LiteLLM servers.

Fit estimates and synthetic role probes help choose what to evaluate; they do not establish production quality or reserve memory. See Evidence and sizing.

Configuration transactions and model job starts use reviewed preview hashes. Explicit intake fetch downloads weights, and backend install installs optional dependencies. Direct inference has a different execution contract. Read the security model for confirmation, network, ownership, and recovery boundaries.

Provider support

First-class adapters are included for each provider below. The universal installer supports both user and project scopes.

Documentation and contributing

The documentation index links onboarding, workflows, troubleshooting, references, and examples. Start with CLI, Runtimes, or Troubleshooting.

See Contributing for local checks and Development for adapters and documentation builds. The opt-in release live smoke selects only direct local Ollama, LM Studio, or mlx_lm backends. LiteLLM is excluded from automatic live selection because it can route to remote or paid backends.

Versioned documentation comes from docs/mlx-agent/source. The consumer contract describes release artifacts; editing source pages does not refresh an already published release.

Distributed under the MIT License.