Amux

amux — background panels for agents

Named tmux panels for long-running processes. Panels are created on first use, tiled within sessions grouped by project root.

Architecture: one global tmux server (separate from your tmux) → sessions (one per project, detected via .git) → panels (named panes, dwm-style tiling).

The run → tail workflow

This is the primary pattern. Start with amux_shell, which streams output for a short timeout (default 5s). If it finishes, you get SUCCESS or FAIL. If it times out, the output tells you exactly how to continue:

⏳ timeout 5s — continue with:
  amux_tail(name: "tests", follow: true, offset: 4820)

Call amux_tail with that offset to resume exactly where amux_shell stopped. No output is lost or duplicated. If amux_tail also times out, it prints another continuation hint — keep chaining until done.

Quick command (finishes in time)

amux_shell(name: "test", command: "npm test")
→ ... test output ...
→ SUCCESS

Long command (timeout → continue)

amux_shell(name: "test", command: "npm test")
→ ... partial output ...
→ ⏳ timeout 5s — continue with:
→   amux_tail(name: "test", follow: true, offset: 4820)

amux_tail(name: "test", follow: true, offset: 4820)
→ ... remaining output ...
→ SUCCESS

Very long command (chain multiple tails)

amux_shell(name: "build", command: "make all", timeout: 30)
→ ⏳ timeout 30s — continue with:
→   amux_tail(name: "build", follow: true, offset: 52000)

amux_tail(name: "build", follow: true, offset: 52000, timeout: 120)
→ ⏳ timeout 120s — continue with:
→   amux_tail(name: "build", follow: true, offset: 128400)

amux_tail(name: "build", follow: true, offset: 128400, timeout: 120)
→ ... final output ...
→ SUCCESS

Tools

amux_shell

Run a command in a panel. Streams output from start. Default timeout 5s, max 300s.

amux_shell(name: "server", command: "npm start")
amux_shell(name: "server", command: "npm start", timeout: 30)

amux_tail

Tail panel output. Default: last 10 lines. Use follow: true to stream live. Use offset to continue from a previous timeout.

amux_tail(name: "server")                                          # last 10 lines
amux_tail(name: "server", lines: 50)                               # last 50 lines
amux_tail(name: "server", follow: true)                            # follow until done (60s)
amux_tail(name: "server", follow: true, offset: 4820)             # continue from offset
amux_tail(name: "server", follow: true, offset: 4820, timeout: 120)  # custom timeout

amux_send_keys

Send keystrokes. Does NOT auto-append Enter.

amux_send_keys(name: "repl", keys: ["puts :hello", "Enter"])
amux_send_keys(name: "server", keys: ["C-c"])

Keys: C-c C-d C-z Enter Tab Esc Space BSpace Up Down Left Right

amux_kill

amux_kill(name: "server")

amux_list

amux_list()

Key Behaviors

• Auto-creation: panels created on first use. No setup.
• Sessions: panels from the same project root share a session (tmux tab).
• Timeout cap: all timeouts max 300s (5 minutes).
• Completion signals: SUCCESS or FAIL EXITCODE:N printed on own line.
• Byte offsets: timeout messages include exact byte offset for seamless continuation.
• Isolated tmux: own socket and config. Never conflicts with personal tmux.