aimux

module
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 8, 2026 License: MIT

README

aimux logo
aimux
Multiplex your AI agents. Trace, launch, export. Never leave the terminal.

Release License

aimux demo

You're running 5 agents across 3 projects. Claude is refactoring auth. Codex is writing tests. A third session is idle, or stuck on a permission prompt? You don't know, because each lives in its own terminal.

aimux is your control plane. One terminal. Every agent. Full visibility.

  • See everything: all agents, their status, model, cost, and project in one view
  • Trace what happened: every prompt, response, and tool call, turn by turn
  • Launch from here: spawn Claude, Codex, or Gemini without leaving the terminal
  • Annotate, label, and export: mark turns GOOD/BAD/WASTE, export to MLflow for eval datasets
  • Bring your own agent: pluggable provider interface, add a new agent in one Go file

Install

# 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

Then run:

aimux            # launch the TUI
aimux --version  # check installed version

Requires tmux for split-pane session embedding.

Features

Discovery

Auto-finds running Claude, Codex, and Gemini processes. Shows status, model, tokens, cost, git branch, and permission mode. Refreshes every 2s. Multiple sessions in the same project directory appear as separate entries with #1, #2 suffixes. Sort by name, cost, age, model, or PID with s. Subagents spawned via the Agent tool are detected and tracked with provider-aware identity across all three providers.

Split View

Press Enter on any agent to open trace + session side by side. Live trace on the left, interactive session on the right. Claude uses direct PTY embedding, Codex and Gemini use tmux mirror.

Conversation Trace

Full turn-by-turn view of prompts, responses, and tool calls:

 17:32 USER  fix the authentication bug in login.go
 17:32 ASST  I'll look at the login.go file...
 17:32 TOOL  Read /src/auth/login.go
 17:32 TOOL  Edit /src/auth/login.go   [BAD] "deleted wrong file"

Annotations

Label turns as GOOD, BAD, or WASTE while watching agents work. Add free-text notes. Annotations persist to disk and export with traces.

Trace view with GOOD/BAD annotations and notes

Export to MLflow

Press e in the trace pane to export:

  • j JSONL to ~/.aimux/exports/
  • o OTLP to MLflow, Jaeger, or any OTEL backend

Annotations become MLflow feedback assessments for building eval datasets.

Exported aimux trace in MLflow showing turn-by-turn inputs and outputs

Agent Launcher

Press :new to spawn agents. The launcher walks you through each step:

Pick provider, directory (recent or browse), model, permission mode, runtime (tmux/iTerm), and toggle OTEL tracing. Launches into tmux with telemetry enabled.

Session History

Press S from the agent list to browse past sessions across all projects. Resume any session in split view, annotate outcomes, tag failure modes, and generate LLM-powered titles.

  • Browse: navigate past sessions sorted by recency with prompt preview
  • Resume: press Enter to reopen a session in split view (trace + live Claude)
  • Annotate: mark sessions as achieved/partial/failed/abandoned (a key)
  • Tag: add failure mode tags with autocomplete (f key)
  • Filter: fuzzy search by prompt, project, annotation, or tags (/)
  • Delete: remove sessions permanently (d key, with confirmation)
  • LLM Titles: auto-generate descriptive titles from session content

CLI access:

aimux sessions --list                    # plain table
aimux sessions --export                  # JSONL for eval pipelines
aimux sessions --generate-titles         # generate titles with Gemini Flash
aimux sessions --regenerate-titles       # regenerate all titles
aimux resume <session-id>               # resume directly

Cost Dashboard

Press c from the agent list for aggregated token usage and estimated USD spend per project:

Cost dashboard showing per-project token usage and cost breakdown

OTEL Receiver

Built-in OTLP/HTTP receiver on port 4318 collects live telemetry from spawned agents. Debug anytime: curl http://localhost:4318/debug

Teams

Press T from the agent list to view Claude Code team configurations and members.

Teams view showing Claude Code team configurations and members

Key Bindings

Key Where Action
j/k Everywhere Navigate up/down
Enter Agent list Split view (trace + session)
t Agent list Standalone trace view
c Agent list Cost dashboard
S Agent list Session history browser
T Agent list Teams overview
Tab Split view Switch focus between panes
e Trace pane Export menu (j:JSONL, o:OTEL)
a Trace pane Annotate turn (GOOD/BAD/WASTE)
N Trace pane Add note to annotated turn
Ctrl+f Split view Toggle fullscreen on focused pane
Tab Agent list Expand/collapse process tree (for grouped sessions)
s Agent list Cycle sort: Name/Cost/Age/Model/PID
x Agent list Kill agent
:new Anywhere Launch new agent
Esc Split/trace Exit to agent list
? Anywhere Help

Configuration

~/.aimux/config.yaml, all settings optional:

providers:
  claude:
    enabled: true
  codex:
    enabled: true
  gemini:
    enabled: false

shell: /bin/zsh

# OTEL receiver: collects live telemetry from spawned agents
otel:
  enabled: true
  port: 4318

# OTLP export: where to send traces (e → o in trace pane)
export:
  endpoint: "localhost:5001"
  insecure: true
  mlflow:
    experiment_id: "1"        # required by MLflow

# Session history: LLM-powered title generation
# Requires GEMINI_API_KEY (for flash) or ANTHROPIC_API_KEY (for haiku/sonnet/opus)
sessions:
  auto_title: true
  title_model: "flash"        # flash, haiku, sonnet, opus
MLflow setup
# Start MLflow
mlflow server --host 127.0.0.1 --port 5001

# Create an experiment
curl -X POST http://localhost:5001/api/2.0/mlflow/experiments/create \
  -H "Content-Type: application/json" \
  -d '{"name": "agent-evals"}'
# Returns {"experiment_id": "1"} — put in config above

In aimux: Tab to trace pane, a to annotate, e then o to export.

Provider System

Provider Discovery Trace Session OTEL
Claude Process scan + JSONL Full conversations Direct PTY embed Logs via http/protobuf
Codex Process scan + JSONL Full conversations Tmux mirror Traces + logs
Gemini Process scan + JSON Full conversations (per-session chat files) Tmux mirror Traces + logs
Adding a new provider

Implement the Provider interface (10 methods), register in app.go, add pricing:

type Provider interface {
    Name() string
    Discover() ([]agent.Agent, error)
    ResumeCommand(a agent.Agent) *exec.Cmd
    CanEmbed() bool
    FindSessionFile(a agent.Agent) string
    RecentDirs(max int) []RecentDir
    SpawnCommand(dir, model, mode string) *exec.Cmd
    SpawnArgs() SpawnArgs
    ParseTrace(filePath string) ([]trace.Turn, error)
    OTELEnv(endpoint string) string
}

See Adding a Provider for the full walkthrough.

Architecture

No daemon, no hooks, no modifications to your AI tools. Reads from the filesystem:

Source Location Data
Config ~/.aimux/config.yaml Provider settings, export config
Process table ps aux Running agents
Session logs ~/.claude/projects/*/, ~/.codex/sessions/, ~/.gemini/tmp/*/chats/ Conversations, tool calls
OTEL receiver localhost:4318 Live telemetry from agents
Teams ~/.claude/teams/*/config.json Team membership

Releasing

Releases are fully automated via CI. To cut a new release:

git tag v0.5.0
git push origin v0.5.0

This triggers the Release workflow which:

  1. Runs the full test suite (build, vet, test)
  2. Cross-compiles binaries for darwin/linux (amd64/arm64) via GoReleaser
  3. Creates a GitHub release with changelog and binaries
  4. Updates the Homebrew tap formula

Users then upgrade with brew upgrade zanetworker/aimux/aimux.

Do not run goreleaser locally — let CI handle it to avoid duplicate asset conflicts.

Built With

Bubble Tea | Lip Gloss | charmbracelet/x/vt | creack/pty | OpenTelemetry

License

MIT

Directories

Path Synopsis
cmd
aimux command
internal
history
Package history discovers and manages past AI agent sessions.
Package history discovers and manages past AI agent sessions.
trace
Package trace defines shared types for conversation trace parsing.
Package trace defines shared types for conversation trace parsing.
tui

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL