aimux

module
v0.14.0 Latest Latest
Warning

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

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

README

aimux

Mission control for AI coding agents: see, steer and evaluate every session.

release CI MIT license

Docs · Install · Quickstart · Changelog


Four agents in one list, then one agent's trace beside its live session, a turn labeled GOOD, and cost per project.

You run five agents in five tmux panes and lose track of which one rewrote auth.go. aimux finds every running and past session, shows each one turn by turn (prompts, tool calls, diffs), and lets you label turns so the good and bad runs become eval data.

Install

brew install zanetworker/aimux/aimux

Requires tmux. No config, SDK or instrumentation: aimux reads the session files Claude Code and Codex already write.

Quickstart

aimux agents
PID   PROVIDER  STATUS   PROJECT       MODEL
7     claude    Active   payments-api  opus
25    claude    Idle     docs          opus
13    claude    Idle     web           opus
19    claude    Waiting  infra         opus

Then open the dashboard:

aimux          # terminal UI
aimux web      # browser UI at localhost:3000

Why aimux

  • See every agent at once. Running and past Claude Code and Codex sessions in one list, with live status, CPU, tokens and cost, and search across all of them ("which agent edited auth.go?").
  • Know what each agent actually did. A turn-by-turn trace of prompts, tool calls and diffs, with a PR-style review panel. Tracing →
  • Turn real runs into evals. Label turns GOOD, BAD or WASTE and export them as MLflow feedback, to any OTLP backend, or as JSONL. MLflow →
  • Run and reach agents anywhere. Launch them locally, in OpenShell sandboxes or on Kubernetes. From your phone, follow your Claude sessions, continue idle ones and answer approvals. Remote sandboxes →

What's inside

Area What you get Docs
Discover Auto-discovery of Claude Code and Codex, live status (working, idle, needs you, error; the same words on the phone), cross-session search, starred sessions, generated titles Web dashboard
Trace and review Turn-by-turn trace, inline diffs, PR-style review panel, live diff pane beside the session terminal Tracing
Cost Per-agent and per-turn cost with model-aware pricing Cost tracking
Evaluate GOOD / BAD / WASTE labels with notes; export to MLflow, Jaeger or any OTLP backend, or JSONL MLflow
Launch Six-axis launcher, saved profiles, quick-launch directories, launches from Google Tasks, continue an idle session with aimux chat Launch modes, Tasks, Chat
Run remotely OpenShell sandboxes with terminal, traces and kill; agents on Kubernetes pods Remote sandboxes, Kubernetes
Reach aimux remote serve: follow and continue Claude sessions from the iPhone app or the phone web client over tailscale, answer approvals, type into sessions open in iTerm2, and open a phone session on the Mac Remote access
Share MCP aimux mcp proxy install: your stdio MCP servers run once in a shared daemon, each at its own endpoint under its original name (permission rules unchanged), started on first call, shared ones stopped when idle and browser ones kept for as long as their Claude Code session runs; aimux mcp serve: session search and resume tools for agents MCP proxy
Interfaces Keyboard TUI with split panes; web dashboard with cards, filters and dark/light themes; desktop and terminal-bell notifications TUI keys, Notifications
Extend Plugin tabs, new providers, --json on every listing command, aimux agent-context for the full CLI contract Plugins, Agent usage, Add a provider

Use the Claude Code or Codex built-in history instead if you run one agent at a time; aimux pays off when several run in parallel.

What it doesn't do: it doesn't plan or orchestrate multi-agent work, and it only supports Claude Code and Codex today (add a provider).


The web dashboard (aimux web): every agent by project, and one agent's trace.

How it works

Usage

Task Command
Search past sessions in all projects aimux sessions "auth.go" --all --list --json --limit 5
Start an agent and wait for it aimux spawn claude --dir ./proj --wait --json
Resume a past session aimux resume <session-id>
Jump to a running agent's iTerm2 pane aimux jump <session-id or pid>
Continue a Claude session that is not open in a terminal aimux chat <session-id> "next step?"
Export a trace aimux export <session-id>
Follow Claude sessions from your phone aimux remote serve (via tailscale serve)
Share MCP servers across sessions aimux mcp proxy install --dry-run, then aimux mcp proxy install
All commands
agent-context  Machine-readable CLI surface for agents
agents         List running AI agents
chat           Send a message to an existing Claude session and stream the reply
collect        Run headless OTEL collector
configs        List named agent configurations
environments   List configured environments
export         Export a session trace
feedback       Send feedback about the CLI
jump           Bring a running agent's terminal pane to the front
kill           Kill a running agent
mcp            MCP server for session search and remote agents
profile        Manage saved configuration profiles
remote         API for your sessions from other devices, through tailscale serve
resume         Resume a past session
sessions       Browse and search past sessions
spawn          Start a new AI agent session
version        Show aimux version
web            Launch web dashboard

Full docs: getting started, configuration.

Contributing

Issues and PRs welcome. Run aimux feedback "..." to report friction straight from the CLI.

License

MIT

Directories

Path Synopsis
Package api holds aimux's published API contracts, embedded so the server can serve them and tests can check the server against them.
Package api holds aimux's published API contracts, embedded so the server can serve them and tests can check the server against them.
clients
web
Package webclient is a browser client for aimux's remote API: a phone web app served at /app/ by `aimux remote serve`.
Package webclient is a browser client for aimux's remote API: a phone web app served at /app/ by `aimux remote serve`.
cmd
aimux command
mcp command
internal
acprun
Package acprun continues an existing agent session through an ACP adapter (claude-agent-acp, codex-acp): it starts the adapter, loads the session, sends prompts, streams updates as numbered events and relays permission requests.
Package acprun continues an existing agent session through an ACP adapter (claude-agent-acp, codex-acp): it starts the adapter, loads the session, sends prompts, streams updates as numbered events and relays permission requests.
catalog
Package catalog is this machine's session catalog: every registered provider's sessions joined with their shown title, visibility, provider and live state.
Package catalog is this machine's session catalog: every registered provider's sessions joined with their shown title, visibility, provider and live state.
clipboard
Package clipboard provides cross-platform text clipboard operations.
Package clipboard provides cross-platform text clipboard operations.
controller
Package controller provides UI-agnostic business logic for aimux.
Package controller provides UI-agnostic business logic for aimux.
folders
Package folders gives every session path one folder identity: the git repository, the linked worktree and the subfolder it runs in.
Package folders gives every session path one folder identity: the git repository, the linked worktree and the subfolder it runs in.
gitinfo
Package gitinfo is the one place aimux asks git about a folder: its top-level and common dir, its origin and its branch.
Package gitinfo is the one place aimux asks git about a folder: its top-level and common dir, its origin and its branch.
gitremote
Package gitremote finds the web address of a folder's git repository, so clients can link commits, issues and files in a reply.
Package gitremote finds the web address of a folder's git repository, so clients can link commits, issues and files in a reply.
harness
Package harness holds the types shared by the core packages and the harness-specific code behind them, so that terminput never imports provider and provider never imports terminput.
Package harness holds the types shared by the core packages and the harness-specific code behind them, so that terminput never imports provider and provider never imports terminput.
harness/claude
Package claude is Claude Code's harness.Composer: it parses the screen Claude Code draws in a terminal (input box, permission prompt, working line, paste marker) and knows its process names.
Package claude is Claude Code's harness.Composer: it parses the screen Claude Code draws in a terminal (input box, permission prompt, working line, paste marker) and knows its process names.
history
Package history discovers and manages past AI agent sessions.
Package history discovers and manages past AI agent sessions.
jsonedit
Package jsonedit edits one top-level key of a JSON config file that another program (Claude Code) also rewrites: atomically, verified by reading back, every other key byte-identical, and backs such files up with rotation.
Package jsonedit edits one top-level key of a JSON config file that another program (Claude Code) also rewrites: atomically, verified by reading back, every other key byte-identical, and backs such files up with rotation.
jsonl
Package jsonl reads agent session files line by line.
Package jsonl reads agent session files line by line.
llm
Package llm is aimux's one model client: the Anthropic Messages API when an API key is set, else `claude -p` in safe mode with the owner's Claude Code login; the short model names config accepts; and a usage line in ~/.aimux/data/usage.jsonl for every call, labelled by the caller ("naming", "insight").
Package llm is aimux's one model client: the Anthropic Messages API when an API key is set, else `claude -p` in safe mode with the owner's Claude Code login; the short model names config accepts; and a usage line in ~/.aimux/data/usage.jsonl for every call, labelled by the caller ("naming", "insight").
mcpproxy
Install (install.go) moves Claude Code's stdio MCP servers behind the proxy and back, one mcpServers entry per server under its own name, so tool names and every permission rule stay as they are.
Install (install.go) moves Claude Code's stdio MCP servers behind the proxy and back, one mcpServers entry per server under its own name, so tool names and every permission rule stay as they are.
mcpserver
Package mcpserver provides the MCP server for remote agent orchestration.
Package mcpserver provides the MCP server for remote agent orchestration.
netguard
Package netguard keeps aimux's local HTTP endpoints reachable only from this machine: no DNS rebinding and no requests from other web sites.
Package netguard keeps aimux's local HTTP endpoints reachable only from this machine: no DNS rebinding and no requests from other web sites.
push
Package push tells a person's devices that an agent is waiting for them, so a permission request reaches the lock screen while no client is open.
Package push tells a person's devices that an agent is waiting for them, so a permission request reaches the lock screen while no client is open.
remoteapi
Package remoteapi is aimux's API for clients on other devices (a phone, another laptop): list sessions, follow them, and continue idle ones.
Package remoteapi is aimux's API for clients on other devices (a phone, another laptop): list sessions, follow them, and continue idle ones.
remoteapi/chatqueue
Package chatqueue holds each session's queue of messages waiting to be sent from the phone, persisted on the Mac, and the rules for how an item moves from waiting to sent.
Package chatqueue holds each session's queue of messages waiting to be sent from the phone, persisted on the Mac, and the rules for how an item moves from waiting to sent.
remoteapi/devicelogin
Package devicelogin keeps the devices paired with the remote API and the pending pairing code.
Package devicelogin keeps the devices paired with the remote API and the pending pairing code.
remoteapp
Package remoteapp composes `aimux remote serve`: it builds the services the remote API needs (provider registry, live sessions, chat manager and router, broker, search, terminal input, chat queue and dispatcher, namer, folders, Mac layout, waiting tracker, push, device login), runs their background jobs and shuts them down in order.
Package remoteapp composes `aimux remote serve`: it builds the services the remote API needs (provider registry, live sessions, chat manager and router, broker, search, terminal input, chat queue and dispatcher, namer, folders, Mac layout, waiting tracker, push, device login), runs their background jobs and shuts them down in order.
runtime
Package runtime defines the interface for agent execution environments.
Package runtime defines the interface for agent execution environments.
search
Package search builds a persistent, ranked index over Claude Code session transcripts: full-text (SQLite FTS5, BM25) plus optional embeddings for semantic ranking.
Package search builds a persistent, ranked index over Claude Code session transcripts: full-text (SQLite FTS5, BM25) plus optional embeddings for semantic ranking.
sessionmcp
Package sessionmcp serves Claude Code session search and resume tools over MCP, on top of the internal/search index.
Package sessionmcp serves Claude Code session search and resume tools over MCP, on top of the internal/search index.
sessions
Package sessions provides interactive session picking via fzf or bubbletea.
Package sessions provides interactive session picking via fzf or bubbletea.
sessionstate
Package sessionstate answers one question for every surface: what is this session doing right now.
Package sessionstate answers one question for every surface: what is this session doing right now.
task
Package task defines the unified Task model and loaders for both Redis (K8s agents) and local filesystem (Claude Code teams).
Package task defines the unified Task model and loaders for both Redis (K8s agents) and local filesystem (Claude Code teams).
terminput
Package terminput types text and keys into Claude Code sessions that are open in a terminal, after checking what the screen shows.
Package terminput types text and keys into Claude Code sessions that are open in a terminal, after checking what the screen shows.
terminput/iterm2
Package iterm2 is the terminput driver for iTerm2.
Package iterm2 is the terminput driver for iTerm2.
trace
Package trace defines shared types for conversation trace parsing.
Package trace defines shared types for conversation trace parsing.
waiting
Package waiting records which Claude Code sessions are waiting for the owner's permission.
Package waiting records which Claude Code sessions are waiting for the owner's permission.
pkg
rediskeys
Package rediskeys defines all Redis key patterns for the k8s-agents system.
Package rediskeys defines all Redis key patterns for the k8s-agents system.
test
e2e/discovery/fakeagent command
Command fakeagent stands in for the claude binary when recording the README demo.
Command fakeagent stands in for the claude binary when recording the README demo.

Jump to

Keyboard shortcuts

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