AgentMux is in early alpha. Many features are incomplete, partially broken, or change between releases without notice. Expect:
- Broken features — pieces of the UI may not function, or may regress from one release to the next.
- Data loss — settings, pane layouts, and agent state may not migrate cleanly across versions. Don't store anything you can't reproduce.
- Breaking changes — config files, identity bundles, memory bundles, and the App API may change shape with no migration path during alpha.
- Platform gaps — Windows is the primary target; macOS and Linux builds lag behind and have additional known issues.
If you hit a problem, please report it as a GitHub issue at https://github.com/agentmuxai/agentmux/issues — it's how alpha gets to beta.
Agent Operating Environment
Watch your agents. Stay in control. A rich monitoring and orchestration environment for AI agents — see every tool call, catch regressions mid-task, and tune your agent system in real time.
Knowledge workers running AI agents across long-horizon tasks are blind while it happens. You can't see which agent found something important. You can't see which one went off-track. You can't redirect mid-task. You find out when it's done, or when something is wrong.
- Agents regress. An agent fixes a bug and then undoes its own work in a later step. By the time you notice, the context is cold and the decision chain is opaque.
- Guardrails are tuned blind. No live signal on which constraints are firing, which are too tight, which agents are working around.
- Multi-agent conflicts are invisible. Two agents reach conflicting conclusions. The synthesis picks one. You never know the conflict happened.
AgentMux is an open-source agent operating environment that surfaces what agents are doing in real time: tool calls, reasoning steps, source citations, output streams, and conflicts between agents. The human role is observer and supervisor, not driver.
Cross-platform (Windows, macOS, Linux). 100% Rust backend (Tokio + Axum). CEF host (bundled Chromium). Apache 2.0.
- Live agent monitoring — Watch every tool call and decision step as it happens. Catch an agent undoing correct work mid-task and redirect it before the damage compounds.
- Multi-agent orchestration — Run parallel agents and see all of them at once. Spot conflicts before synthesis. Redirect any agent without killing the others.
- Guardrail observability — See which constraints are active and firing. Tune your agent system from live signal, not post-mortem guesswork.
- Multi-provider agent support — Claude Code, Codex CLI, Gemini CLI, OpenClaw, Kimi Code CLI, GitHub Copilot CLI, and Pi as first-class providers, alongside Terminal, Editor, Browser, and Sysinfo panes.
- Identity bundles — Named credential sets (GitHub PAT, AWS profile, Anthropic key, etc.) that you assign per agent at launch. Survives renames; swappable without restart.
- Memory bundles — Reusable agent personality + capability stacks (provider, model, instructions, MCP, skills). Manage via the Memory pane inside an Agent pane's settings; launch-modal selection arrives with the spawn-time content-injection layer (PR-F.4).
- Browser pane — Native
CefBrowserViewembedded as a child window of the AgentMux frame — full Chromium fidelity (links, popups, DRM) without iframe limitations. - App API — Local WebSocket RPC with both an intent-based layer (
agent.open,agent.send,pane.open) and a low-level command catalog (block, file, event, conn). External tools and agents can drive the host directly. - Audited dispatch — 4-layer reducer stack (launcher / host / sidecar / frontend slices) with structured event logs at every layer, so "what mutated this state?" has exactly one place to look.
- Drag and drop — Rearrange panes by dragging headers, reorder tabs, drag panes and tabs across windows.
- Per-pane zoom — Independent zoom level per pane, plus global chrome zoom.
- Real PTY support — Authentic terminal emulation via xterm.js and portable-pty.
- Run multiple versions side-by-side — Each instance is fully isolated (separate CEF data, separate backend sidecar, separate ports). Test a new build while the old one is still running.
| Tool | Version | Purpose |
|---|---|---|
| Node.js | 22 LTS | Frontend build |
| Rust | 1.77+ | Backend + CEF host |
| Task | Latest | Build orchestration |
| CMake | 3.20+ | CEF native build (cef-dll-sys) |
| Ninja | 1.10+ | CEF native build (cef-dll-sys) |
Platform-specific:
- Windows: Visual Studio Build Tools (CMake + Ninja ship with VS, but Ninja must be on PATH — see CLAUDE.md)
- macOS: Xcode Command Line Tools,
brew install cmake ninja - Linux: Build essentials,
apt install cmake ninja-build build-essential— see Linux guide
npm install # install frontend dependencies
task dev # CEF host + Vite hot reloadtask package # Portable ZIP for the host platform
task package -- --fresh # …with a throwaway data dir (clean-slate session)
task package:linux # Linux AppImage (writes to ~/Desktop)task package builds a local portable with an ephemeral, traceable label — it does not bump the version and does not touch git. Each build lands in a uniquely-stamped folder (agentmux-<version>+g<sha>[.dirty].<stamp>-x64-portable) so builds never collide on disk, and shares a per-branch data dir so your test session survives rebuilds. The committed version moves only via task release (changesets). See docs/specs/SPEC_LOCAL_BUILD_VERSIONING_2026_05_28.md.
task package:macos and task package:msix are TODO stubs in Taskfile.yml. The full release artifact set is produced by agentmuxai/agentmux-builder — see §Releases below.
The muxlog helper (shipped in every AgentMux terminal) discovers and renders logs across every running instance — the shared dir, each task dev instance (~/.agentmux/dev/<branch>/), and per-build channels — so you never hunt for a file or guess a version. It defaults to the most-recently-active instance and renders the NDJSON logs as compact time level target message.
| What | Command |
|---|---|
| List every instance's logs (newest first) | muxlog ls |
| Tail the active host log (follow) | muxlog host |
| Tail the active sidecar log | muxlog srv |
Frontend [fe] lines only |
muxlog fe |
| Launcher log | muxlog launcher |
| Search the sidecar (agent transcript excluded) | muxlog srv grep <regex> |
| Errors + warnings across host & sidecar | muxlog errors |
| Startup-handshake trace (debug reconnect loops) | muxlog bridge |
| Target a specific instance | muxlog host -i <branch|version> |
| Full usage | muxlog help |
Works identically across task dev, portable, and installed builds. Full reference (targets, filters, recipes, how discovery works): docs/MUXLOG.md. Per-process log layout and the underlying data dirs: docs.agentmux.ai/internals/data-layout and /internals/debugging.
Every widget is pinned by default — the widget bar shows the full set directly, collapsing to icon-only when the title bar is narrow. The canonical list is agentmux-srv/src/config/widgets.json.
| Widget | Icon | View | Description |
|---|---|---|---|
| Agent | sparkles | agent |
AI agent with streaming output and tool execution |
| Browser | globe | browser |
Embedded native CefBrowserView |
| Terminal | square-terminal | term |
Terminal with xterm.js and real PTY |
| Sysinfo | chart-line | sysinfo |
Live system metrics (CPU, memory, network, disk) |
| Editor | file-code | editor |
Code editor with syntax highlighting |
| Swarm | bee | swarm |
Multi-agent orchestration overview |
| Drone | diagram-project | drone |
Visual DAG-of-blocks drone engine |
| Help | circle-question | help |
Built-in documentation and help |
| Warden | shield-halved | warden |
Monitor and control agents across Host / LAN / Internet layers |
| Surface | How to reach it |
|---|---|
| Identity | Tab inside an Agent pane (cog → settings → Identity). Manage the credential bundle assigned to this instance. |
| Memory | Tab inside an Agent pane (cog → settings → Memory). Manage the personality / capability bundle (provider, model, instructions, MCP, skills). Replaces the old Forge concept. |
| Settings | Hamburger menu (≡) in the top tab bar → Settings. Opens settings.json in your default editor. |
| DevTools | Hamburger menu (≡) in the top tab bar → DevTools. Toggles Chromium DevTools (no longer a widget). |
Each agent has two names:
| Field | Purpose | Changeable? |
|---|---|---|
| Display name | Shown in the picker, pane title, notifications | ✅ Yes — rename any time |
| Slug | Drives ~/.agentmux/agents/<slug>/, GH_CONFIG_DIR, AGENTMUX_AGENT_ID |
❌ No — set once at creation |
- Hover an agent card in the Agent picker.
- Click the ✏ pencil icon next to the agent's name.
- Type the new display name and press Enter (or click ✓). Press Esc to cancel.
- The picker card and any open pane titles update immediately.
Nothing on disk moves — working directories, GitHub CLI config dirs, and env vars all key off the immutable slug, so renaming is always safe.
Click the 👤 button on any agent card to assign external accounts (GitHub PAT, AWS profile, Anthropic API key, etc.) to that agent. Accounts are stored per-agent and survive renames. You can swap, add, or unassign accounts at any time without restarting the agent.
AgentMux exposes a local WebSocket RPC surface so external tools and agents can drive the host — open agent panes, send messages, read output, and more. It binds to loopback only and is auth-gated per instance.
// ws://127.0.0.1:{WS_PORT}/ws?authkey={AUTH_KEY}
ws.send(JSON.stringify({
wscommand: "rpc",
message: { command: "agent.list", reqid: "demo-1", data: {} },
}));- Getting started:
docs/api/getting-started.md— connect, discover credentials, make your first call. - Command reference:
docs/specs/app-api-extension.md. - Implementation status:
docs/specs/app-api-status.md.
AgentMux is a four-process desktop app. Each process owns one concern, end-to-end. See Architecture overview for the full topology.
| Process | Crate | Role |
|---|---|---|
| launcher | agentmux-launcher |
Sets DLL search path; spawns the host; tracks Window Reality Reconciliation; durable event log for OS-level facts. |
| host | agentmux-cef |
Embeds Chromium via CEF; owns the OS window, the browser panes, the JS bridge, and IPC fan-out to the renderer. |
| sidecar | agentmux-srv |
App domain: workspaces, tabs, blocks, layouts, agents, identity. Persists to SQLite. Auto-spawned by the host on a dynamic port. |
| renderer | frontend/ |
SolidJS UI running inside CEF. Stateless — projects what the sidecar/host expose, dispatches user actions back through them. |
A fifth crate, agentmux-common, provides shared utilities (path resolution, runtime mode detection) consumed by all the above.
Stack:
- Frontend: SolidJS + TypeScript + Vite (state via SolidJS signals + a 4-layer reducer stack)
- Desktop: CEF 148 via cef-rs — bundles its own Chromium (~160 MB ZIP package, ~150 ms startup, 150–350 MB resident)
- Backend: Rust (Tokio + Axum + SQLite + portable-pty)
- Terminal: xterm.js
| Command | Description |
|---|---|
task dev |
Development mode (CEF host + Vite hot reload) |
task build:host |
Build the CEF host binary |
task bundle |
Bundle CEF runtime DLLs |
task package |
Package a portable build for the host platform |
task build:backend |
Build agentmux-srv |
task build:frontend |
Build frontend only |
task test |
Run tests (vitest) |
task clean |
Clean build artifacts |
Local build outputs from task package on the host platform:
| Platform | Task | Artifact |
|---|---|---|
| Windows | task package |
~/Desktop/agentmux-<version>+g<sha>[.dirty].<stamp>-x64-portable/ and .zip |
| Linux | task package:linux |
~/Desktop/AgentMux_*_amd64.AppImage |
Other platform tasks (task package:macos, task package:msix) are TODO stubs in Taskfile.yml. The full release artifact set (macOS DMG, Windows installer, Windows MSIX, Linux .deb) is produced by agentmuxai/agentmux-builder — see §Releases for the artifact catalog.
Feature PRs add a changeset, not a version bump. RFC #857 Phase 2.
task changeset -- patch "fix(scope): short description"
# Allowed bump types: patch | minor | majorThis creates a uniquely-named .changesets/<id>.md you commit with your code. Parallel-agent PRs never conflict on version files because they each have their own changeset filename.
A separate release PR consumes pending changesets. The bump type is auto-detected from the highest changeset type present (major > minor > patch). To force a specific type, use the explicit task variants:
# Auto-detect bump type (recommended for normal releases):
task release
# Force a specific type regardless of changeset contents:
task release:patch # force patch even if feat changesets are present
task release:minor # force minor even if only fix changesets are present
# Preview what would land without touching anything:
task release -- --dry-run
# After any of the above — all 5 version files are staged automatically:
git commit -m "chore: release v<X.Y.Z>"
git push -u origin <branch>Do not use
task release --as patch—taskparses--asas its own flag and exits with an error. Usetask release:patchinstead.
Release PRs must contain only: changeset deletions, VERSION_HISTORY.md entry, and version bumps in package.json, Cargo.toml, Cargo.lock, package-lock.json. No feature code, cleanup, or analysis docs.
The release flow internally uses @a5af/bump-cli via scripts/bump-wrapper.sh. Config lives in .bump.json. See BUILD.md, .changesets/README.md, and docs/specs/SPEC_MULTI_AGENT_VERSION_COORDINATION_2026_05_15.md for the full workflow.
Releases are built by agentmuxai/agentmux-builder — a private repo that holds CI/CD workflows and signing secrets separate from the public source.
- The builder's workflow checks out this repo at the given ref
- Builds run in parallel on
ubuntu-latest,macos-latest, andwindows-latest - Each job builds the Rust backend binary (agentmux-srv), then builds the CEF host
- macOS builds are code-signed and notarized via Apple Developer credentials
- Windows builds include both an NSIS installer and a portable ZIP
- A final
create-releasejob collects all artifacts and creates a GitHub Release on this repo
# Manual workflow dispatch (pass a tag, branch, or SHA)
gh workflow run tauri-build.yml -R agentmuxai/agentmux-builder -f ref=v0.33.0| Platform | Artifact |
|---|---|
| macOS Apple Silicon | AgentMux_*_aarch64.dmg |
| Windows x64 (installer) | AgentMux_*_x64-setup.exe |
| Windows x64 (portable) | agentmux-*-x64-portable.zip |
| Linux x64 (AppImage) | AgentMux_*_amd64.AppImage |
| Linux x64 (deb) | AgentMux_*_amd64.deb |
# 1. Consume pending changesets, bump version, update VERSION_HISTORY
# All 5 version files are staged automatically — no manual git add.
task release # auto-detect bump type from changesets
task release:patch # or force patch / minor regardless of changeset types
git diff --staged # review: should contain ONLY changeset deletions + version bumps
git commit -m "chore: release v0.X.Y"
git push -u origin <agent>/release-v0.X.Y
# ... open release PR, merge to main after review
# 2. Tag once merged on main
git checkout main && git pull
git tag v0.X.Y && git push origin v0.X.Y
# 3. Trigger the builder (builds all platforms, creates GitHub Release)
gh workflow run tauri-build.yml -R agentmuxai/agentmux-builder -f ref=v0.X.Y
# 4. Wait for build to complete (~15-20 min)
gh run list -R agentmuxai/agentmux-builder --limit 1
# 5. Deploy landing site (fetches new release, updates download links)
cd /workspace/agentmux-landing
deploy run --env prod
# 6. Verify
gh release view v0.X.Y --repo agentmuxai/agentmux # release exists with assets
curl -sf https://agentmux.ai/release.json | jq .version # landing shows new versionFor enterprises interested in adopting or deploying AgentMux at scale, including technical consulting, sponsorship opportunities, or partnership inquiries, please contact us at enterprise@agentmux.ai.
AgentMux is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement.
Performance figures, feature descriptions, and any claims in this README are best-effort observations from our development environment — they are not guarantees. See LICENSE sections 7 (Disclaimer of Warranty) and 8 (Limitation of Liability) for the full terms.
AgentMux is released under the Apache License 2.0.
- NOTICE — required attributions per Apache License 2.0 § 4(d)
- LEGAL.md — corporate entity, trademark, contact
- ACKNOWLEDGEMENTS.md — third-party software and attributions
- SECURITY.md — vulnerability disclosure policy
Originally forked from Wave Terminal, copyright Command Line Inc., licensed under the Apache License 2.0.
Copyright © 2025-2026 AgentMux Corp.