mux — Your AI agent, your models, your infrastructure

One engine, four surfaces

Run it however you work

Every surface shares one core — Mux.Core. Start in the terminal, script it in CI, open the dashboard in a browser, or launch the desktop app. Same agent, same tools, same sessions.

mux

Interactive terminal UI

A full-screen REPL with per-job transcripts, a live job sidebar, a multi-line composer, slash commands, an interactive tool-approval modal, and autosaved resumable sessions. Multiple prompts run as concurrent background jobs.

mux print

Headless & scriptable

Single-shot runs for scripting and automation. Stream plain text, one buffered JSON object, or machine-readable JSONL — one event per line. Drop mux into build steps, GitHub Actions, or any shell pipeline.

mux serve

Local web dashboard

A loopback-bound, token-guarded REST + WebSocket API with a self-contained single-page dashboard — chat, configuration, sessions, and usage/pricing analytics. Hosted in the background by a cross-platform system-tray agent.

mux Desktop

Cross-platform desktop app

An Avalonia client that links the engine in-process: streaming chat with Markdown, tables, and syntax-highlighted code; conversations with AI-summarized titles; a command palette; the full configuration surface; and the usage dashboard.

See it work

A real system operator, not a text box

mux turns the model into an agent that reads and writes files, runs commands, searches code, and browses the web — with you in the loop at every step.

Tool-driven from the first turn

The model requests any of mux's built-in tools — edit, read, write, glob, grep, process execution, rendered web retrieval — and the calls are part of the conversation. Watch each one resolve, with timing and a live token/cost readout in the sidebar.

Approval modal — approve once, deny, or auto-approve for the session
Live stats — TTFT, streaming time, context, tokens, and cost per turn
Sandboxing — read-only, workspace-write, or unrestricted, plus tool allow/deny globs

mux interactive terminal UI showing tool calls and a live session sidebar

Switch models without touching code

Endpoints live in JSON — each with its own adapter, base URL, model, auth, and reasoning effort. The picker (Ctrl+E) swaps the active endpoint mid-session, and bulk-imports every model from a running Ollama server in one step.

Any provider — local Ollama, vLLM, LM Studio, or cloud OpenAI / Azure
Per-endpoint reasoning effort, auto-approval, and iteration caps
Secrets by reference — keep keys in env vars, not plaintext config

mux endpoints and models picker listing dozens of local and cloud models

Plans, tasks, and background jobs

For a large request the model lays out a tracked plan and advances it as it goes. The shell draws a live checklist that updates in place, the sidebar shows TASKS n/m, and the plan persists across save and resume. Concurrent jobs run under a single-writer lease so file edits never collide.

Undo / redo — roll a turn's file changes back and forward in any git repo
Session export — render a run to self-contained HTML + Markdown, server-free
Auto-compaction — older history is summarized before it overflows the context budget

mux terminal UI showing a detailed multi-turn agent session with a task plan and stats

Extend & compose

MCP, skills, and subagents — built in

mux isn't a closed box. Plug in tool servers, encode repeatable procedures, and delegate scoped work to isolated agents — all configured in plain files or managed live in-app.

MCP tool servers

/mcp · mcp-servers.json

Define stdio or HTTP Model Context Protocol servers and mux connects live on startup — discovering each server's tools, exposing them to the model, and showing per-server connectivity. Add, edit, or remove servers without a restart.

mcp-servers.json

{
  "name": "filesystem",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@mcp/server-fs"]
}

Skills

/skills · ~/.mux/skills

Versioned Markdown-plus-code capabilities that turn a fuzzy request into a fixed, deterministic procedure — the Markdown carries judgment, the code carries determinism. 46 curated defaults ship on first run; author, import, and manage your own in-app.

SKILL.md

---
name: git-commit
description: Stage & commit changes
mutates: true
commands: [run]
---

Subagents

spawn_subagent · subagents.json

Delegate a scoped sub-task to a named subagent. Each runs in an isolated conversation — its own system prompt, endpoint, and tool allow-list — and returns only its final answer, keeping the primary agent's context clean.

subagents.json

{
  "name": "reviewer",
  "endpoint": "gpt-oss-local",
  "allowTools": ["read_file",
    "grep"]
}

The full toolbox

And a whole lot more

Beyond MCP, skills, and subagents, mux ships a deep set of capabilities for engineers building agents and agentic workflows — not a thin wrapper around a chat endpoint.

Built-in tools

File read / write / edit / multi-edit / delete, directory ops, glob, grep, process execution, and rendered web retrieval — ready on turn one.

MCP tool servers

Define stdio / HTTP servers in mcp-servers.json or manage them with /mcp. mux connects live, discovers their tools, and exposes them to the model.

Skills

Versioned Markdown-plus-code capabilities that turn a fuzzy request into a fixed, deterministic procedure. 46 curated defaults ship on first run; author your own in-app.

Subagents

Delegate a scoped sub-task with spawn_subagent. Each runs in an isolated conversation — its own prompt, endpoint, and tool allow-list — and returns only its final answer.

Background tasks

The model breaks big work into a task DAG and tracks it live — pending → running → done. A task_plan_updated event streams to orchestrators in JSONL mode.

Undo / redo

In a git repo, mux snapshots the working tree before each turn so /undo and /redo roll file changes back and forward — your branch, history, and stash untouched.

Usage analytics

Every model call is recorded to a local SQLite database — tokens, cost, time-to-first-token, latency, throughput. View it via /usage or the dashboard's charts.

Sandbox & approvals

Confinement postures (read-only, workspace-write), tool allow/deny globs, and approval policies — ask, auto, or deny. Or --yolo for full trust.

Plugins & hooks

Out-of-process event hooks (session-start, user-prompt-submit, session-end) and custom /slash commands configured in hooks.json.

Reasoning effort

One control — off to high — mapped per backend: reasoning_effort for OpenAI, a thinking budget for Gemini, think for Ollama. Optionally surface the model's thinking.

Web search & retrieval

web_search discovers results via Tavily or You.com; web_retrieve fetches any URL with a headless browser and returns rendered text, title, and status.

Engine as a library

Mux.Core and Mux.Search publish to NuGet with symbols — build your own experiences on AgentLoop, SessionStore, McpToolManager, and more.

Ridiculous configurability

Tune every knob. Or none of them.

Sensible defaults on first run, and a setting for everything underneath. Config lives in plain JSON under ~/.mux — or a fully isolated directory via MUX_CONFIG_DIR.

01

Endpoints & models

Adapters, base URLs, auth modes, per-endpoint reasoning effort, auto-approval, and iteration caps.

02

Prompts & behavior

Custom system prompts, prompt profiles, compaction strategy, token budgets, temperature, and max turns.

03

Keybindings & theme

Rebind or unbind any command's key chord, toggle borders and sidebar, and pick light / dark / system theming.

04

Pricing & providers

An editable pricing.json drives cost analytics; configure MCP servers, skills, subagents, and web-search providers.

~/.mux/endpoints.json

// swap models without touching a line of code
{
  "name": "gpt-oss-local",
  "adapterType": "ollama",
  "baseUrl": "http://localhost:11434",
  "model": "gpt-oss:120b",
  "reasoningEffort": "high",
  "autoApproveTools": false,
  "showThinking": true,
  "auth": {
    "mode": "bearer",
    "token": "${OLLAMA_TOKEN}"  // from env
  }
}

Automate everything

Headless, deterministic, orchestratable

Drive mux from scripts, CI, or your own orchestrator. Machine-readable JSONL emits one event per line; thin SDKs wrap the same contract in TypeScript and Python.

bash — run a task and stream structured events

# one machine-readable event per line: run_started, tool_call_*, task_plan_updated, run_completed
mux print --output-format jsonl --output-last-message result.txt --yolo \
  "implement the feature described in TASK.md"

# constrain the final response to a JSON Schema, or connect MCP servers for one run
mux print --output-schema schema.json --mcp-config mcp.json --yolo "extract the release notes"

TypeScript — @mux/sdk

import { Mux } from "@mux/sdk";

const mux = new Mux({ yolo: true, sandbox: "workspace-write" });
const result = await mux.run("implement the feature in TASK.md");

console.log(result.text, result.exitCode);

Python — mux-sdk

from mux_sdk import Mux, MuxOptions

mux = Mux(MuxOptions(yolo=True, sandbox="workspace-write"))
result = mux.run("implement the feature in TASK.md")

print(result.text, result.exit_code)