aimux

aimux is an AI-agent-friendly tmux wrapper.

Use aimux when you need a long-lived shell session — a REPL, a build/server you want to interact with across multiple commands, or anything running on a remote SSH host. Use bash directly for one-shot commands. aimux gives you session primitives, file-transfer helpers, and remote-host helpers; this skill explains how to combine them.

Install

pip install aimux # or `uv pip install aimux` if using uv venv

Usage

aimux is tool that enables tmux-like capability cross ssh.

(.venv) /home/.../...$ aimux -h

Usage: aimux [OPTIONS] COMMAND [ARGS]...

aimux — AI-agent-friendly tmux wrapper.

─ Options
--help  -h        Show this message and exit.

─ Commands 
ls                          List all aimux sessions.
new                         Create a new session.
attach                      Attach to a session. ⚠️  Human use only — agents should use send-keys + capture.
send-keys                   Send keys to a session. Behaves exactly like 'tmux send-keys': supports -F/-H/-K/-l/-M/-R/-X/-N <count>. Pass 'Enter' as a key to submit a line.     
send-files                  Upload multiple local files or directories to an SSH host using sftp.
get-files                   Download multiple remote files or directories from an SSH host using sftp.
sync-dir                    Differentially synchronize a local directory with a bridge remote directory.
read                        Read a remote file and print a metadata header followed by numbered content.
apply-patch                 Apply a patch to create, edit, or delete files (absolute paths only).
capture                     Capture pane output (last N lines).
kill                        Destroy a single session. Does not accept wildcards or batch.
wait-last-command-complete  Block until the pane's foreground process is back at a shell. Local sessions only.
remote                      Remote-host management (reads/appends ~/.ssh/config).

Example

adding and naming a remote host in aimux.

First, usually you will get a ssh address, for example,

HostName localhost
Port 8824
User root

To begin, you will need to check whether this address is already inside aimux's storage:

$ aimux remote ls
HOST              USER  HOSTNAME    PORT  STATUS         RTT   
github.com        git   github.com  22    auth-required  2261ms
local-8824        root  localhost   8824  reachable      709ms

If not in storage, you will have to add that server using:

aimux remote add --host localhost --port 8824 --user root --name local-8824 --timeout 2s
aimux remote test local-8824 --timeout 2s

Creating a session and run command in it.

aimux new --remote local-8824 --name testsession
aimux send-keys "local-8824/testsession" -- 'ls -la' Enter
aimux capture "local-8824/testsession" --lines 200

Creating a bridge session.

Bridge remotes are reverse-connected clients. Start a broker on the server, connect a client back to it, then create sessions through the same --remote API. Bridge remotes require an explicit profile:

# server
aimux bridge deploy --port=8765

# client
aimux reverse connect http://SERVER:8765 --identifier=winbox --token=<token>

# server
aimux remote ls
aimux new --remote=winbox --profile=cmd --name=cmd-1
aimux send-keys winbox/cmd-1 -- "echo hello" Enter
aimux capture winbox/cmd-1 --lines=50

Windows bridge profiles include cmd, powershell, pwsh, and mingw64 when available. macOS exposes mac-pty and mac-terminal; Linux exposes posix-pty.

Forward a browser-facing HTTP service through the bridge server.

aimux port forward https://SERVER/aimux_bridge \
  --local-port=8080 \
  --remote-host=127.0.0.1 \
  --remote-port=3000 \
  --token=<token>

Open http://127.0.0.1:8080. Ordinary HTTP requests, streaming SSE responses, and WebSocket upgrades are forwarded to http://127.0.0.1:3000 from the bridge server's network namespace. Use --remote-scheme=https for an HTTPS target.

Upload and download files.

File transfer for bridge remotes

aimux send-files and aimux get-files work the same way for bridge remotes as for SSH hosts — the CLI auto-detects the remote type and dispatches accordingly. Bridge transfers use a base64-encoded file.* message family over the existing SSE+POST channel, with no sftp dependency on the client.

aimux send-files winbox 'C:\Users\dev\proj' ./src --gitignore
aimux get-files winbox ./logs 'C:\Users\dev\proj\logs'

Differences vs the SSH path:

Single-file size limit defaults to 16 MiB (configurable via AIMUX_BRIDGE_MAX_FILE_SIZE if you want to override it in code).
Files are written with mode 0o644; existing timestamps/permissions are not preserved.
Symlinks are not followed on the remote side — they show up as symlink entries in directory listings and are skipped during recursive download.
.. segments in remote paths are rejected to prevent traversal.

# aimux send-files REMOTE REMOTE_DIR LOCAL_PATH... [--gitignore]
# aimux get-files REMOTE LOCAL_DIR REMOTE_PATH...
aimux send-files local-8824 /tmp/upload /home/testdir/tests
aimux get-files local-8824 /home/testdir/tests /tmp/upload

Use --gitignore on upload when ignored files should be skipped:

aimux send-files local-8824 /tmp/upload /home/testdir/tests --gitignore

Clean up.

aimux kill "local-8824/testsession"

Metadata

Release files for aimux 0.1.35

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aimux 0.1.35
File	Size	Uploaded
aimux-0.1.35.tar.gz	154.7 kB	Sep 20, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for aimux 0.1.35
File	Interpreter	ABI	Platform	Reset
aimux-0.1.35-py3-none-any.whl 91.8 kB Sep 20, 2026	Python 3	none	any	Details

Total release size: 246.5 kB

Release files / aimux-0.1.35.tar.gz

Download URL	aimux-0.1.35.tar.gz
Size	154.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`9f3812a8906aaa67c45f2340dc0a8e6d01ebc57fd1004eabb992eda887ceb4fb`
BLAKE2b-256 checksum How to use checksums	`1e2a67de0c13a29550e8691b45ae5518a50e71da533f64141476b150a77a661d`
Upload date	Sep 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`

Release files / aimux-0.1.35-py3-none-any.whl

Download URL	aimux-0.1.35-py3-none-any.whl
Size	91.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`40a5ec408a0e9115c055a4676be4877144f4d317672a4980a1fb0e980005020f`
BLAKE2b-256 checksum How to use checksums	`64e398fdccf97c7403f217dd2ead124b4db6a0d20cbbd28ba4d4467bb6c2c562`
Upload date	Sep 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`