Skip to content

Getting Started

Terminal window
# Homebrew (macOS/Linux)
brew install zanetworker/aimux/aimux
# From source
git clone https://github.com/zanetworker/aimux.git
cd aimux
make install # builds and copies to /usr/local/bin
  • tmux - required for split-pane session embedding and agent launch
  • Go 1.24+ - only if building from source
  • Running AI coding agents: Claude Code or Codex CLI
Terminal window
aimux

aimux auto-discovers running Claude and Codex processes. The agent table refreshes every 2 seconds.

Terminal window
aimux web # web dashboard on port 9090
aimux web --port 8080 # custom port
aimux --web # both TUI and web simultaneously

Open http://localhost:9090 in your browser.

CommandDescription
aimuxLaunch TUI dashboard
aimux webLaunch web dashboard (default port 3000)
aimux --webLaunch both TUI and web
aimux agents --jsonList running agents (structured output)
aimux sessions --listList session history
aimux sessions "query" --listSearch sessions by keyword
aimux spawn claude --dir ./projStart a new agent session
aimux resume <id>Resume a previous session
aimux jump <id>Bring a running session’s iTerm2 pane to the front (session ID, unique prefix or PID)
aimux setupCheck every concern and run only the missing setup steps (tool registry, clients, sandbox, Chrome host); on a terminal, offer to review changed tools
aimux doctorRead-only checks with one fix per problem; exit 1 on any failure, warnings exit 0 (Troubleshooting)
aimux agent-contextMachine-readable CLI schema for agents
aimux profile save <name>Save a named configuration bundle (v1; aimux profile migrate converts it to a profile)
aimux feedback "text"Report CLI friction
aimux version --jsonPrint version info

All data commands support --json for structured output. See Agent Usage for the full reference.

Terminal window
aimux setup --extension-id <id> # the id is in chrome://extensions once the Wingman extension is loaded
aimux doctor # read-only: what is still wrong, and the fix for each

aimux setup checks the sandbox, tools, router, browser, OpenShell gateway and tool gateway worker and runs only what is missing (it reports a missing worker with aimux mcp proxy gateway install but does not install it): it asks before each step on a terminal, and --yes runs them without asking. It ends with one line per concern (✓, ! or ✗) and a Next: line for each problem. Run it again any time; with nothing missing it changes nothing. It never approves a tool unless you answer yes to that tool’s diff on a terminal. The Wingman guide has the details and Troubleshooting lists every aimux doctor check.

  1. Start some agents - Run Claude Code or Codex in other terminals
  2. Open aimux - They appear automatically in the dashboard
  3. Select an agent - Press Enter (TUI) or click a card (web) to see its trace
  4. Annotate - Mark turns as good/bad/waste to build eval datasets
  5. Export - Send traces to MLflow via OTEL, or save as JSONL