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:

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

amux solvescompletely thiseliminates byquoting addingand escaping issues via native stream-file-streaming injection commands (write-pane -f) 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-b prefix key (matching inner session convention without colliding with outer mtx C-a).
  • 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

Window Naming & Task Lifecycle Methodology

To maintain strict isolation between tasks, prevent command collisions, and keep workspaces clean, windows in atx follow a structured naming convention:

<project_or_domain>-<target>-<task_suffix>

Naming Pattern Examples

  • mc-pokelovers-bluemap: BlueMap setup or rendering for pokelovers
  • mc-pokelovers-datapacks: Managing datapacks and gameplay tweaks
  • mc-pokelovers-console: Direct interactive Minecraft server console
  • rtr-dns-sync: Router DNS record and deSEC synchronization
  • rtr-pf-rules: Firewall rule adjustments and testing
  • bld-amux-stream: Compiling and patching tmux C source code
  • bkp-verify-daily: Backup execution and PAR2 verification

Window Lifecycle Protocol

  1. Window Creation (Task Start): Before running multi-step commands for a task, verify if the dedicated window exists; if not, spawn it:

    ax list-windows -F '#{window_name}' | grep -q '^mc-pokelovers-bluemap$' || \
ax new-window -n "mc-pokelovers-bluemap" "bash --rcfile ~/.agent_profile"

  2. Scoped Execution:Execution via File Injection: Always targetWrite the specificscript taskor window:commands to a file on /dev/shm or /tmp, inject it, and delete the temporary file:

    ax write-pane -t "mc-pokelovers-bluemap" -e -bf "<base64_payload>"/dev/shm/task_payload.sh
rm -f /dev/shm/task_payload.sh

  3. Status Renaming: If a task transitions to a persistent state (e.g. watching logs, running tests), update the title:

    ax rename-window -t "mc-pokelovers-bluemap" "mc-pokelovers-watch"

  4. Task Completion / Cleanup: When the task is complete and verified, tear down the window:

    ax kill-window -t "mc-pokelovers-bluemap"

    Persistent background daemons or long-term monitoring windows remain open with their descriptive suffix.

Built-In Commands

write-pane (alias: writep)

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

tmux write-pane [-en] [-f file] [-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. (Recommended Standard) -e: Automatically appends a newline (\n / Enter) to trigger immediate execution. -b <base64-data>: Decodes a base64 payload in C (b64_pton) and writes raw bytes to the PTY. -n: Do not separate multiple positional arguments with spaces. -t <target-pane>: Specifies the target session, window, or pane (e.g. -t mc-pokelovers-bluemap).

    UsageStandard ExamplesWorkflow: Zero-Escape File Injection

    1.

    The Puregolden Rawrule Heredocfor (Zerorunning Escapingmulti-line via Base64)

    Pipe raw code, multilinecommands, scripts, or SQLnested intoshell base64invocations is: Write the code directly to a file, then inject it with awrite-pane quoted-f.

    heredoc

    This completely eliminates worrying about single quotes, double quotes, subshells, or escaping.

    Step 1: Write the Payload to File

    Write your exact code verbatim to /dev/shm (or <<'EOF'/tmp). No backslashes, no escape sequences::

    PAYLOAD=$(base64# -w0File: <<'EOF'/dev/shm/script.py
python3import -c 'json
import os

for k, v in os.environ.items():
    if "MC" in k or "ROUTER" in k:
        print(f"{k}data = {v}
    "user": os.getenv("USER"),
    "paths": ["/data/minecraft", "/home/luke/git"],
    "quote_test": 'Double "quotes" and single \'quotes\' work without escapes!'
}
print(json.dumps(data, indent=2))
'
    EOF

    Step ) #2: Inject and runExecute

    in agent session task window: 
    ax write-pane -t mc-pokelovers-datapacks -e -bf "$PAYLOAD"/dev/shm/run.sh

    2. Direct File Injection (-f)

    Write or edit any file on disk cleanly, then stream it straight into the target pane with zero terminal quoting:

    ax write-pane -t bld-amux-stream -erm -f /tmp/deploy_database.dev/shm/run.sh

    3. Quick Input with Auto-Enter

    Injecting plain commands directly:

    ax write-pane -t rtr-dns-sync -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.