Skip to main content

amux - Agent modified tmux

Overview

amux (Agent-Modified tmux) is a custom build of tmux designed to provide clean, robust programmatic control for AI CLI agents and automated scripting.

Standard tmux requires emulating physical keystrokes (send-keys) and screen-scraping the visual terminal grid (capture-pane). This introduces significant failure modes:

    Quoting and Escaping Hell: Nested quotes, shell variables, subshells, and escapes are easily mangled when passed across nested SSH sessions or bash wrappers. Terminal Echo & Input Race Conditions: Rapid key injection can race with shell readline redraws, bracketed paste triggers, or auto-suggestions. ANSI & Layout Pollution: Screen scraping mixes prompt redraws, color escape codes, truncated lines, and terminal dimensions with actual command output.

    amux solves this by adding native stream-injection commands (write-pane) and a dedicated agent session hierarchy (atx / ax).

    Architecture & Session Hierarchy

    The tmux sessions on the host are organized into clean layers managed by /home/luke/bin/tmux_control:

    +-------------------------------------------------------+
|  mtx / mx: Outer Master Session                       |
|  Socket: /tmp/tmux-1000/tmux_luke_mtx                 |
|  Config: ~/.tmux.conf_outer                           |
|                                                       |
|   +-----------------------------------------------+   |
|   |  stx / sx: User Interactive Session           |   |
|   |  Socket: /tmp/tmux-1000/tmux_luke_stx         |   |
|   |  Config: ~/.tmux.conf_inner                   |   |
|   +-----------------------------------------------+   |
|                                                       |
|   +-----------------------------------------------+   |
|   |  atx / ax: Agent Session (amux)               |   |
|   |  Socket: /tmp/tmux-1000/tmux_luke_atx         |   |
|   |  Config: ~/.tmux.conf_agent                   |   |
|   +-----------------------------------------------+   |
+-------------------------------------------------------+
      atx [session]: Attaches to or creates the agent session inside mtx. Styled with a high-visibility orange status bar (#ff8800), [AGENT] badge, and C-a prefix key. ax <command>: Runs commands directly on the agent socket (e.g. ax list-panes, ax write-pane ...). Binary: The custom binary is built from /home/luke/git/tmux and installed at /usr/local/bin/tmux-custom. The system tmux (/usr/bin/tmux) remains unmodified as a fallback.

      Persistent Agent Environment

      When the agent session spawns, it automatically sources ~/.agent_profile:

        Persistent Environment Variables:
          AGENT_SESSION=1 ROUTER=danknasty ROUTER_REPO=/home/luke/git/router_config MC_DIR=/data/minecraft MC_ROUTER_V4=10.0.0.113 MC_ROUTER_V6=fd77:7777:5010::1337:f1ac:d00d:3c MC_BACKEND_PREFIX=fd77:7777:5010::1337:3c:d00d: Persistent Helper Functions:
            rcfg: Git wrapper for router config (git -C $ROUTER_REPO) rssh: Direct SSH to danknasty rdo <cmd>: Direct non-interactive execution on router mipctl: Shortcut for /data/minecraft/ipctl

            Built-In Commands

            write-pane (alias: writep)

            Injects raw binary data, Base64 payloads, or whole files directly into the target pane's PTY input buffer. It completely bypasses terminal keystroke decoding and shell quoting.

            tmux write-pane [-en] [-b base64-data] [-f file] [-t target-pane] [data ...]

            Flags:

              -b <base64-data>: Decodes the base64 string directly inside the C runtime (b64_pton) and writes the raw bytes directly to the PTY event stream. -f <file>: Reads the given file from disk and streams its raw bytes directly into the pane's input buffer. -e: Automatically appends a newline (\n / Enter) to trigger immediate execution. -n: Do not separate multiple positional arguments with spaces. -t <target-pane>: Specifies the target session, window, or pane (e.g. -t main:1.0).

              Usage Examples

              1. Zero-Escape Command Execution (Base64)

              Executing commands with quotes, special characters, or variables without escaping:

              # In shell / Python / script:
PAYLOAD=$(echo -n 'python3 -c "import os; print(\"User:\", os.getenv(\"USER\"))"' | base64 -w0)

# Inject and run in agent session:
ax write-pane -t main -e -b "$PAYLOAD"

              2. Multi-Line Script / File Injection

              Injecting a complex script or SQL / configuration payload directly into a running shell or REPL:

              ax write-pane -t main -e -f /tmp/complex_deploy_script.sh

              3. Quick Input with Auto-Enter

              Injecting plain commands directly:

              ax write-pane -t main -e 'ipctl list'

              Rebuilding & Updating amux

              The source tree is maintained at /home/luke/git/tmux:

              cd /home/luke/git/tmux
make -j$(nproc)
sudo install -m 755 tmux /usr/local/bin/tmux-custom

              Existing sessions can continue running undisturbed; new sessions or restarts of tmux_control (atx, stx, mtx) automatically pick up the updated binary.