aimux

Aimux is a local agent multiplexer for AI coding tools. It keeps Claude, Codex, Aider, and shell sessions running in real tmux windows, scoped to a project checkout or one of that project's git worktrees.

Aimux does not replace those tools' native TUIs. It manages the runtime around them and exposes one control plane through the terminal dashboard, CLI, web app, mobile app, and relay-backed shared chats.

What It Does

• Runs long-lived agent and service sessions in managed tmux windows.
• Groups sessions by project and git worktree.
• Provides dashboard actions for spawning, stopping, forking, resurrecting, and coordinating sessions.
• Keeps shared project state behind a local daemon and one daemon-managed project service per active project.
• Lets web and mobile clients use the same control-plane APIs as the terminal.
• Supports optional relay access for the owner's own devices.
• Supports shared chats as a separate receiver experience; guests do not need their own daemon, CLI, relay, or local project.

Execution stays local. Remote clients relay requests to the owner's running local daemon and project service.

App

Aimux includes a browser app at aimux.app. The app is for remote access to your own running Aimux daemon, shared chat invitations, and the web version of the project control plane.

The iOS and Android apps use the same Expo client and are the upcoming native surfaces for the same workflows.

Install

Homebrew

brew tap TraderSamwise/aimux
brew trust TraderSamwise/aimux
brew install aimux

Current Homebrew versions can refuse third-party formulas from untrusted taps, including the companion aimux-local formula referenced by the tap metadata. Run brew trust TraderSamwise/aimux once after tapping, then install either aimux or aimux-local.

Standalone

curl -fsSL https://raw.githubusercontent.com/TraderSamwise/aimux/master/scripts/install.sh | sh

The installer places a frozen release under ~/.aimux/native/ and links aimux into ~/.local/bin. Reinstalling over an existing install repairs the daemon, project services, tmux runtime contract, and dashboard windows without killing agent panes.

Install a specific release:

curl -fsSL https://raw.githubusercontent.com/TraderSamwise/aimux/master/scripts/install.sh | AIMUX_VERSION=vX.Y.Z sh

npm

npm install -g aimux-cli

Homebrew or the standalone installer is preferred for normal local installs.

Quick Start

# Open the dashboard for the current project
aimux

# Start a tool in a managed agent window
aimux claude
aimux codex
aimux aider

# Repair daemon/service/dashboard/tmux drift
aimux restart

# Inspect installed runtime coherence
aimux doctor versions

Common control-plane commands:

aimux spawn --tool codex --project /path/to/repo
aimux stop <sessionId> --project /path/to/repo
aimux kill <sessionId> --project /path/to/repo
aimux graveyard resurrect <id> --project /path/to/repo
aimux task assign "Audit the reconnect path" --project /path/to/repo
aimux thread list --project /path/to/repo --json

Configuration

Aimux reads defaults, then ~/.aimux/config.json, then .aimux/config.json inside the project. Project config wins over global config.

Tool restart restore is capability-based. A tool supports exact restart restore only when its config has resumeArgs containing {sessionId} and resumeByBackendSessionId is not false. Tools without that capability can still be launched, but Aimux warns at spawn time and labels the session with the restore-blocked reason if it is offline after a restart.

Automatic project scribes are disabled by default. To create one whenever a project service starts, set a default scribe tool:

{
  "scribe": {
    "defaultAgent": "claude"
  }
}

Use object form when the scribe needs tool-specific launch options. extraArgs is the same argument line exposed by the tool picker's o options flow, so model or generation flags stay owned by the underlying tool:

{
  "scribe": {
    "defaultAgent": {
      "tool": "claude",
      "extraArgs": ["--model", "sonnet"],
      "env": { "AIMUX_EXAMPLE": "1" }
    }
  }
}

Set "defaultAgent": null in a project config to disable a global default for that project.

Remote Access And Sharing

The web and native clients are clients of the same local control plane as the terminal dashboard.

Owner remote access is opt-in:

aimux login
aimux remote enable

Remote owner devices are approved from the local CLI and can be required to prove possession of a stored device key before proxying daemon requests. See docs/security.md for the approval, proof, notification, and lockdown model.

Shared chats are orthogonal to a receiver's own projects. A receiver can accept and use a shared chat from aimux.app even if they have no local Aimux install or daemon running. If they do run their own Aimux install, project workflows and shared chats remain separate top-level app areas.

Development

git clone https://github.com/TraderSamwise/aimux.git
cd aimux
yarn install
yarn build

Backend code under src/ runs from dist/ inside the installed bundle. Building this checkout is not enough to update a running aimux install. For backend changes, build and install a local release asset:

AIMUX_RELEASE_VERSION=local-$(git rev-parse --short HEAD) yarn release:asset
ASSET="$(ls -t release/aimux-*.tar.gz | head -n 1)"
scripts/install.sh "$ASSET"
aimux doctor versions

For the Expo web/mobile client:

cd app
yarn dev:web:local
yarn dev:native:local
yarn dev:ios:local
yarn dev:android:local

Local web against the production relay:

cd app
yarn dev:web:relay

Requirements

• macOS or Linux
• Node.js 24+
• tmux
• At least one supported agent tool installed, such as claude, codex, or aider

Documentation

• Architecture
• Development
• Deployment
• Sharing
• Security

Release Channels

Releases publish from git tags to:

• GitHub Releases
• npm: aimux-cli
• Homebrew tap: TraderSamwise/aimux

License

MIT. See LICENSE.