amux

name	amux
description	Run background tasks, long-running processes, servers, and anything you'd use tmux for. Named panels persist across commands. Use for dev servers, Electron apps, build watchers, tailing logs, running test suites, or any process that needs to keep running while you do other work.

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.