---
title: Getting Started
description: Install aimux and run your first dashboard.
---

## Install

```bash
# 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
```

## Requirements

- **tmux** - required for split-pane session embedding and agent launch
- **Go 1.24+** - only if building from source
- Running AI coding agents: Claude Code, Codex CLI, or Gemini CLI

## Launch the TUI

```bash
aimux
```

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

## Launch the Web Dashboard

```bash
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.

## CLI Commands

| Command | Description |
|---------|-------------|
| `aimux` | Launch TUI dashboard |
| `aimux web` | Launch web dashboard (default port 3000) |
| `aimux --web` | Launch both TUI and web |
| `aimux agents --json` | List running agents (structured output) |
| `aimux sessions --list` | List session history |
| `aimux sessions "query" --list` | Search sessions by keyword |
| `aimux spawn claude --dir ./proj` | Start a new agent session |
| `aimux resume <id>` | Resume a previous session |
| `aimux agent-context` | Machine-readable CLI schema for agents |
| `aimux profile save <name>` | Save a named configuration bundle |
| `aimux feedback "text"` | Report CLI friction |
| `aimux version --json` | Print version info |

All data commands support `--json` for structured output. See [Agent Usage](/guides/agent-usage/) for the full reference.

## Quick Tour

1. **Start some agents** - Run Claude Code, Codex, or Gemini 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
