Web Dashboard
Launch the web dashboard:
aimux web # default port 9090aimux web --port 8080 # custom portCard Grid
Section titled “Card Grid”The main view shows agent cards grouped by project. Each card displays:
- Provider badge (Claude, Codex) with color coding
- State: needs you, working, idle (or error), the words the TUI and the phone use. A Claude Code session at a permission prompt reads “needs you” when Claude Code’s session registry reports it waiting, and also from
aimux remote hooks install’s markers - Launch mode badge (tmux or direct)
- Title: the title you wrote, else your
/renamename, else one aimux generated, else Claude Code’s own name for the session, else its first message (chosen as in the TUI,aimux sessionsand the phone clients) - Project name and git branch
- Last activity snippet showing the most recent tool call
- CPU% and memory usage with color-coded thresholds
- Model, token counts, and cost
Click a card to toggle the trace panel. Click again to close it.
Toggle between views using the tab bar:
- Live Agents - Live agent cards with filtering and sorting
- Sessions - Historical session table with search
- Plugin tabs - Custom dashboards from plugins (e.g., Skill Dashboard)
List vs Card View
Section titled “List vs Card View”Toggle between card grid and compact list view using the view mode buttons in the filter bar (grid/list icons). Both views show CPU%, memory, token counts, and cost per agent. In list view, focus brings the agent’s own iTerm2 pane to the front, next to kill.
Filtering and Sorting
Section titled “Filtering and Sorting”The filter bar provides:
- Status filters: All, Working, Idle, Needs you, Error
- Provider filters: Claude, Codex
- Location filter: Local, Remote — show only local agents or only remote sandboxes
- Recent filter: Show only agents active in the last 5 minutes
- Text search: Filter by project name or branch
- Content search: Search inside session traces across all agents
- Sort: Last Active, Cost, Tokens
Right Panel
Section titled “Right Panel”Selecting an agent opens the right panel with three tabs:
- Trace: Turn-by-turn conversation with tool calls, inline diffs, and outputs
- Diffs: PR-style diff review with hierarchical file tree, line-numbered diffs, and per-file stats
- Session: Live terminal with “Review Diffs” split view (diffs auto-refresh alongside the session). Resuming a past session uses normal permissions unless you tick Skip permissions, even if the original session ran in bypass mode.
Additional features:
- Annotations: Label turns as good/bad/waste with notes
- Export: JSONL to
~/.aimux/exports/or OTEL to configured endpoint - Fullscreen: Expand the panel to fill the viewport
- Resizable: Drag the panel border or the split divider to resize
Session History
Section titled “Session History”Click the Sessions tab to browse past agent sessions. The sessions table shows:
- Provider and project name
- Title, chosen as on the agent cards; the session filter also matches it
- Age since last activity
- Turn count, token usage, and cost
- Resumable indicator for sessions that can be continued
- Star icon: Click to pin/unpin sessions for quick access
Some sessions are hidden until you ask for them. Sessions started by a program (claude -p, the agent SDK) show when you turn on Automated, in full, as H shows them in the TUI. Subagent sessions show when you turn on Subagents, analyzer sessions (started by aimux’s own analysis or hook prompts, or mentioning “session analyzer”) when you turn on Analyzers, and near-empty sessions (no cost and at most 5 turns) while a search is active. The Sessions tab count and the total under the table follow the switches: they count automated, subagent and analyzer sessions only while their switch is on, and near-empty sessions always (a search shows them). Content search also finds automated sessions; the switches decide whether they show. The server decides which sessions each switch reveals (the hidden list on each /api/history session), with the same rule the TUI and the phone clients use, each with its own switches.
Starring Sessions
Section titled “Starring Sessions”Click the star icon (☆/★) on any session row or agent card to pin it. Starred sessions:
- Sort to the top of the sessions list
- Appear in the dedicated ★ Starred tab (with count)
- Persist across restarts (stored in
.meta.jsonsidecar files) - Show on agent cards in the Agents tab
Title Generation
Section titled “Title Generation”Click Generate Titles in the sessions toolbar to auto-generate LLM titles for untitled sessions. Titles and descriptions you wrote are kept, and the token use is recorded under the label naming. Starring and editing from the dashboard change only the fields it sends, so they no longer reset a description or title you set elsewhere.
Click any row to open its trace in the right panel. The toolbar provides two filter inputs:
- Filter sessions: Search by title, prompt, project, annotation, or tags
- Filter by path: Narrow to sessions in a specific directory (type a directory name like “research” or “aimux”)
Both filters stack: filter by path first, then search within those results. Use the content search for deep matches inside session files. Content search results follow the same rules: Starred, the path filter and the Subagents, Automated and Analyzers switches still apply, and a row matching either the text filter or the content search is shown.
CLI Session Commands
Section titled “CLI Session Commands”You can also browse sessions from the terminal:
aimux sessions --list # table outputaimux sessions --list --json # JSON outputaimux sessions "query" --list # search by keywordaimux sessions --export # JSONL for pipelinesaimux resume <id> # resume a sessionaimux resume <id> --dry-run --json # preview resume commandCross-Session Search
Section titled “Cross-Session Search”Search across all agent traces to find specific files, functions, or topics:
- Web: Use the “Search inside sessions…” input in the filter bar. Results show session ID, file path, and a snippet of the matching content.
- TUI: Press
/to search across all active agent traces.
This is useful for questions like “which agent edited auth.go?” or “who ran the database migration?”.
Content search uses the same ranked index as aimux sessions (~/.aimux/search.db): keyword ranking, plus semantic ranking when OPENAI_API_KEY is set. Each search first picks up session files that changed and embeds them in the background, so it doesn’t wait for them; new messages match by keyword at once and usually join semantic ranking within seconds. Only the query itself is embedded inline (cached after the first time). If more than 20 sessions changed at once, they are not embedded automatically; run aimux sessions index to catch up. If the embedding API is unreachable, the work stays queued and the next search retries it, even if no files changed. One exception: when the index was written by a newer aimux build (several builds can share the file, one per open session), an older build uses it as it is without refreshing and logs a note once, and aimux sessions index refuses to rebuild it; update aimux to bring that build’s search up to date.
Dark/Light Theme
Section titled “Dark/Light Theme”Toggle between dark and light themes using the sun/moon button in the header bar. The preference is saved to localStorage and persists across sessions.
- Dark: Pure black base (
#000000), red accent (#FF3131) - Light: Light grey base (
#F5F5F5), Red Hat Red accent (#EE0000)
Remote Sandboxes
Section titled “Remote Sandboxes”The web dashboard has full support for OpenShell remote sandboxes. Remote agents appear alongside local agents in the card grid.
Launching
Section titled “Launching”Click + Launch, set Runtime: remote, choose a directory, and click Launch Agent. The dashboard navigates directly to the new sandbox’s session terminal and starts Claude automatically.
Card appearance
Section titled “Card appearance”Remote sandbox cards show:
- LOC:
remotebadge in the location column - Name: your project directory (e.g.,
research) — not the raw sandbox ID - Status: working (green) while ready; ERROR / Deleting immediately after Kill
Session terminal
Section titled “Session terminal”The Session tab connects to a live PTY inside the sandbox. Claude starts with --session-id <uuid> on first connect and --resume <uuid> on reconnect, keeping the same conversation thread.
Click Kill on the card — no confirmation dialog. The card switches to Deleting state immediately and disappears once the sandbox is fully removed.
Traces
Section titled “Traces”The Trace tab shows turn-by-turn conversation with assistant replies read from the sandbox’s session file. Replies refresh every 5 seconds.
Stats Bar
Section titled “Stats Bar”The header shows aggregate statistics:
- Session count, working/idle/needs you/error counts; without the hooks, a muted “Permission alerts need
aimux remote hooks install” (a permission prompt still reads needs you when Claude Code’s registry reports the session waiting) - Repository count
- Total tokens in/out
- Total cost across all agents
Local-Only Access
Section titled “Local-Only Access”The dashboard listens on 127.0.0.1 and only answers its own page and local tools:
- Requests must use a loopback host name (
127.0.0.1,localhostor::1), which blocks DNS rebinding. - Requests that change state (
POST,DELETE) are rejected with403when a browser sends them from another site. Pages on other loopback ports (for example the Vite dev server onlocalhost:5173) are allowed. - Terminal WebSockets are stricter: they are accepted only from the dashboard’s exact origin.
- Endpoints that take a
fileparameter (/api/trace,/api/sessions/diffs,/api/sessions/meta, the export endpoints) only read session files under~/.claude/projects,~/.codex/sessionsor~/.aimux/archive.