amux

Agent MUltipleXer -- drive AI agent TUIs (Claude Code, Codex) through tmux sessions. Use them programmatically without extra-usage billing.

Why

claude -p (programmatic mode) moves to extra-usage billing on June 15, 2026. amux drives the interactive TUI through real tmux sessions instead -- same programmatic interface, stays within your normal subscription limits.

Codex gets the same treatment: tmux session, prompt injection, completion detection, output extraction.

Install

curl -fsSL https://raw.githubusercontent.com/thevibeworks/amux/main/install.sh | bash

Or manually:

git clone https://github.com/thevibeworks/amux.git
cd amux && bun link

Requires bun >= 1.0 and tmux >= 3.0.

Quick Start

# One-time: install the Claude completion hook
amux hook install

# Send a prompt to Claude Code
amux claude "fix the auth bug in login.py"

# Work in a specific project directory
amux claude "refactor the test suite" -w ~/project

# Run in background, check later
amux claude "audit security of auth module" -d -w ~/project
amux ls                          # check status
amux output claude-2026          # prefix match works

# Pipe prompt from stdin
echo "explain this codebase" | amux claude -w ~/repo

# Pass flags through to the agent CLI
amux claude "continue fixing" -- --continue
amux codex "add error handling" -w ~/api -- --full-auto

# JSON output for scripting
amux claude "list all TODOs" -f json -w ~/repo

How It Works

  prompt --> amux --> tmux session --> agent TUI
                        |
                   [1] new-session     Detached tmux running agent CLI
                   [2] preSend         Agent-specific init (wait for REPL, dismiss prompts)
                   [3] paste-buffer    Inject prompt via tmux buffer (multiline-safe)
                   [4] poll sentinel   Wait for completion signal
                   [5] extract         Parse transcript JSON (Claude) or capture pane (Codex)
                   [6] kill-session    Tear down, return output to stdout

Claude -- A Stop hook writes a sentinel file + JSON payload containing the transcript path. Gated on $AMUX_SENTINEL so normal Claude sessions are unaffected.

Codex -- The shell wrapper touches the sentinel on process exit. Fallback: pane-idle detection after configurable timeout (default 20s). The preSend phase auto-dismisses the trust dialog and waits for MCP server init before injecting the prompt.

Commands

Command	Description
amux claude "prompt"	Run prompt through Claude Code TUI
amux codex "prompt"	Run prompt through Codex CLI TUI
amux ls	List all sessions with status
amux attach <session>	Attach to a running tmux session
amux output <session>	Print session output (prefix match)
amux kill <session>	Kill a session
amux kill --all	Kill all running sessions
amux hook install	Install Claude Stop hook
amux hook check	Verify hook is installed
amux clean	Remove finished session records

Options

Flag	Default	Description
-w, --workdir DIR	cwd	Working directory for the agent
-v, --verbose	off	Tail tmux pane to stderr (debug hangs)
-d, --detach	off	Run in background, return session ID
-t, --timeout SECS	600	Max wait for completion
-f, --format FMT	text	Output format: text or json
--ready-wait SECS	4.0	TUI startup delay before prompt injection
--stdin	off	Read prompt from stdin
-- <args>		Pass-through args to agent CLI

Configuration

Environment Variable	Default	Description
AMUX_HOME	~/.amux	Session data directory
AMUX_CLAUDE_SETTINGS	~/.claude/settings.json	Claude settings file path
AMUX_CODEX_IDLE	20	Codex idle-detection timeout (seconds)

Testing

bun test              # 74 tests, ~400ms
bun x tsc --noEmit    # type check

Tests are fully isolated -- each test gets its own temp directory via AMUX_HOME and AMUX_CLAUDE_SETTINGS env overrides. No tmux required for the test suite.

Project Structure

amux.ts              CLI entry point + run orchestration
lib/
  tmux.ts            tmux wrapper functions (spawn, capture, send)
  agents.ts          Agent adapters (Claude, Codex) + hook management
  session.ts         Session type + filesystem CRUD (~/.amux/sessions/)
tests/
  agents.test.ts     Adapter build commands, output extraction, hooks (40 tests)
  session.test.ts    Session CRUD, find, prefix matching (17 tests)
  cli.test.ts        CLI integration via subprocess (17 tests)
ref/
  claude-i           Reference implementation (vendored)

Credits

Based on the claude-i concept by @isingh, which demonstrated driving Claude's interactive TUI through tmux + Stop hooks as a workaround for claude -p billing changes.

License

MIT -- (c) 2026 thevibeworks