v0.0.5

AgentMux v0.0.5

Worker-side terminal state, Web Control mobile polish, and release packaging updates.

Highlights

• Added worker-side terminal control capabilities.
  • Workers advertise render modes for worker-state xterm and live attach xterm.
  • terminal.snapshot can carry ANSI screen data plus optional cells-v1 state.
  • terminal.diff supports conservative row-level state updates after a snapshot boundary.
  • terminal.history.request and terminal.history.page expose worker-side history pages.
  • terminal.state.reset, size sync, size reset, and mouse events are part of the protocol surface.
• Improved Web Control terminal behavior.
  • Web Control requests terminal snapshot, history, state reset, and size-control capabilities.
  • Worker-side state and history can be opened from the terminal toolbar for diagnostics.
  • Worker history no longer opens automatically on initial remote session attach.
  • Remote terminal size can be synced to the browser viewport or reset to the worker default.
  • Mobile terminal chrome keeps the tmux prefix action visible and folds secondary actions into a compact menu.
• Improved mobile Web Control navigation.
  • Overview metrics are more compact on small screens.
  • Worker cards expose primary state first and fold operational actions into an Ops menu.
  • Session/window/pane navigation now has better target summaries, collapsible rows, and local favorites for quick access.
  • When a session has exactly one window and one pane after target inspection, Web Control opens it directly.
• Improved session target and terminal state documentation.
  • Added docs/TERMINAL_STATE_OPTIMIZATION.md.
  • Updated API, usage, architecture, roadmap, and update strategy docs for terminal state and release behavior.
• Expanded release packaging.
  • Release builds include Worker, Control, TUI, and Hub assets for Linux and macOS.
  • Hub assets also include Windows amd64.
  • Release workflows and local Makefile targets now generate role-specific tarballs and checksums.

Terminal State

This release moves AgentMux closer to a worker-owned terminal state model. The
browser can attach with a current screen snapshot instead of relying only on
fresh raw output from a newly attached terminal stream. Worker-side history pages
are kept separate from xterm scrollback so diagnostics and reconnect behavior can
improve without polluting the active terminal buffer.

The production terminal view still uses xterm.js. cells-v1 is currently useful
for diagnostics and validation of worker-side state, not as the primary
long-term renderer.

Web Control Mobile Notes

The mobile surface is now more conservative about always-visible controls:

• tmux prefix stays visible in active terminal panes;
• debug, state, history, sync, reset, split, and close actions move behind a
  compact overflow menu on narrow screens;
• overview cards use a denser layout;
• Worker operational controls are grouped under Ops;
• session/window/pane target rows are easier to expand, collapse, and revisit.

Favorites for sessions and panes are stored in browser local storage in this
release. Server-side user preferences are still a future persistence task.

Compatibility Notes

• Protocol version remains 1.
• Existing Direct Token limits from v0.0.4 still apply.
• Existing Worker and Control credentials continue to work.
• Worker-side terminal state requires a Worker that advertises the new terminal
  capabilities. Older Workers fall back to the live attach behavior.
• Windows release assets are Hub-only. Worker and terminal Control remain
  Linux/macOS-oriented because they rely on Unix terminal semantics.

v0.0.4

AgentMux v0.0.4

Anonymous sharing, Direct Token boundaries, Worker lifecycle controls, and release/deployment polish.

Highlights

• Added anonymous share generation from POST /api/signals.
  • No-token requests mint a tenant-scoped Worker signal plus a Control Direct Token.
  • Registered Control/admin requests mint material for the authenticated tenant.
  • Invalid supplied credentials return 401 instead of silently falling back to anonymous mode.
  • Direct Token credentials cannot generate new signals.
• Added Direct Token share outputs:
  • direct_token
  • direct_token_expires_at
  • control_share_url
  • control_direct_command
• Locked Direct Token mode down to simple shared-session access.
  • Allowed: list shared sessions, connect to an existing session, switch sessions.
  • Blocked: create/stop sessions, generate joins, Worker management, previews, targeted panes, version prompts, Worker updates, and registered-account features.
• Improved Web Control and landing-page generation UX.
  • URLs render as clickable links with copy actions.
  • Signals, Direct Tokens, and commands render as code blocks with copy buttons.
  • Login and signal-generation failures now show readable errors instead of raw response bodies.
• Added Worker duplication safeguards.
  • Workers now keep a stable local instance id.
  • Reusing the same signal from the same Worker instance is rejected.
  • A Worker refuses to join another Hub while a saved Worker credential exists.
  • agentmux worker leave clears the local Worker credential and stops the background Worker by default.
• Added Control-side Worker eviction so stale or accidental joins can be removed from the Hub before re-joining.
• Added Windows Hub-only deployment polish with scripts/run.bat.
• Updated README, API, deployment, usage, architecture, roadmap, and GitHub metadata to match the current implementation.

Anonymous Share Flow

Open a Hub landing page and click Generate:

https://hub.example.com/

Use the generated Worker command on the machine that owns the local sessions:

curl -fsSL https://hub.example.com/install.sh | sh -s -- worker --join 'amx_sig_...' --name "$(hostname)"

Then open the generated Web Control share URL:

https://hub.example.com/control?token=amx_cred_...

Or use the same Direct Token from TUI:

agentmux-tui --hub https://hub.example.com --token 'amx_cred_...'

Direct Token mode is intentionally narrow. It is for anonymous shared access to already-created sessions, not for Hub administration.

Registered Control Mode

Sign in or register in Web Control for the full management surface:

• create and stop sessions
• generate Worker join signals
• manage and evict Workers
• use previews and workspaces
• see version/update prompts
• queue remote Worker updates

Direct Token mode does not expose these registered-account capabilities.

Worker Lifecycle

Use worker leave before moving a Worker instance to another Hub:

agentmux worker leave
agentmux worker join --hub https://hub.example.com --join 'amx_sig_...' --name "$(hostname)"

If a Worker was accidentally joined and is still visible in Control, evict it from Web Control or via:

agentmux control evict --hub https://hub.example.com --worker local

Windows Hub Helper

The Windows helper moved under scripts:

scripts\run.bat

It looks for agentmux-hub.exe, agentmux-hub-windows-amd64.exe, or agentmux.exe in the release/check-out root, starts Hub on 127.0.0.1:8081, and sets --public-url https://agentmux.kinboy.wang.

Compatibility Notes

• Existing registered Control credentials continue to work.
• Existing Worker join commands continue to work, but duplicate signal use from the same local Worker instance is now rejected.
• Direct Token clients should not expect Worker, preview, workspace, create/join, or update APIs to be available.
• Hub-only Windows release assets are supported. Worker and terminal Control are still primarily Linux/macOS paths.

v0.0.3

AgentMux v0.0.3

Control TUI usability, terminal fidelity, and resize smoothness release.

Highlights

• Added Control device login support so agentmux control login and agentmux-tui can obtain and cache Control credentials without manually passing tokens.
• Improved the Control TUI session workflow:
  • smoother session list navigation
  • in-TUI login prompts
  • attach opens in the right-side terminal area by default
  • Ctrl-F toggles full-screen attach
  • Ctrl-] detaches, Ctrl-Q exits, and Ctrl-G writes debug snapshots when debug mode is enabled
• Added detailed TUI observability with --debug, --debug-log, render counters, stream queue state, terminal view size tracking, and manual debug snapshots.
• Added a terminal emulator backed TUI attach path that can render live remote terminal output, preserve stream buffers across detach/re-attach, and avoid the previous "waiting for terminal output" dead state.
• Added UTF-8 input handling for attached sessions, including Chinese input.
• Added mouse support foundations in the TUI:
  • local session selection by mouse
  • local split boundary dragging
  • remote mouse event forwarding when the attached terminal enables mouse mode
  • SGR mouse sequence support for remote tmux interactions such as pane focus and pane border dragging
• Improved tmux pane preview composition so Worker previews can include the visible multi-pane tmux window instead of only the active pane.
• Smoothed attach resize behavior:
  • local split dragging no longer continuously sends remote resize requests
  • remote resize is debounced after mouse release
  • tmux redraw output after resize is settled before the Control TUI repaints
  • Control-side repaint frequency is lowered to reduce flicker and intermediate redraw frames
• Fixed Unicode terminal width handling for box drawing characters such as ─, │, ├, ┤, and ┼, preventing split-pane borders from being truncated in the TUI.
• Added a built-in PTY session backend fallback for Workers when tmux is not available. tmux remains preferred for durable sessions across Worker restarts.
• Improved Web Control workspace behavior:
  • persistent workspace tabs and split layouts
  • drag-and-drop session placement across panes
  • open-in-new-tab and detach controls for active sessions
  • per-worker tmux prefix settings with legacy setting migration
  • recent working-directory suggestions when creating sessions
• Changed session creation to wait for Worker confirmation. The Hub now returns 201 Created only after the Worker accepts the session, and Worker-side validation failures are surfaced as 400 Bad Request.

TUI Control

The dedicated TUI entrypoint remains:

agentmux-tui

First-time Control onboarding can use a generated join signal:

agentmux-tui join --hub https://hub.example.com --join 'amx_sig_...'

Or the browser/device login flow:

agentmux control login --hub https://hub.example.com
agentmux-tui

Inside the TUI:

• Enter or a: attach the selected session in the right-side terminal area
• Ctrl-F: toggle full-screen attach
• Ctrl-]: detach from the active attached session
• Ctrl-Q: quit the TUI
• /fullscreen: attach and enter full-screen from the command prompt
• mouse click: select a session or focus the attached terminal area
• mouse drag: adjust the local session list / terminal split

When the remote terminal enables mouse mode, TUI mouse events are forwarded to the remote terminal. This allows tmux-native mouse behavior such as pane focus and pane resizing from the Control TUI.

Debugging

TUI debug mode can be enabled with:

agentmux-tui --debug --debug-log /tmp/agentmux-tui-debug.log

or:

agentmux control app --hub https://hub.example.com --debug --debug-log /tmp/agentmux-tui-debug.log

Debug snapshots record render counts, stream event counts, pending queue sizes, selected session metadata, active stream state, terminal view sizes, and recent resize state. They intentionally avoid including credentials or terminal output.

Worker Backend

Worker backend selection now supports:

agentmux worker config --backend auto
agentmux worker config --backend tmux
agentmux worker config --backend pty

auto uses tmux when available and falls back to the built-in PTY backend otherwise.

The PTY backend supports detach and re-attach while the Worker process is alive. It is not durable across Worker process restarts, so tmux is still recommended for long-running agent sessions that must survive Worker restarts.

Auth And Credential Refinements

• Control credentials can be exchanged, cached, and refreshed through the same credential cache used by the TUI and CLI.
• Worker credential handling was refined so background services and foreground runs can reuse saved Worker identity more consistently.
• Web auth and signal exchange paths were tightened for Control device login and generated Control URLs.

API And Web Control

• POST /api/sessions now returns {"status":"created"} after the Worker confirms session creation.
• Worker session creation failures such as invalid working directories are returned directly to the Control client instead of being hidden behind an asynchronous queued state.
• Web Control keeps workspace layout state in the browser so reconnecting or switching views does not discard pane placement.
• Web Control terminal panes include tmux prefix controls for tmux-backed sessions.

Fixes

• Fixed TUI attach hangs caused by missing local stream observability and output warmup handling.
• Fixed TUI attach defaulting to full-screen mode; attached sessions now open in the right-side area by default.
• Fixed TUI Chinese input and UTF-8 forwarding in attached sessions.
• Fixed remote tmux mouse forwarding from TUI attach sessions.
• Fixed excessive remote resize churn during local split dragging.
• Fixed repeated intermediate Control TUI repaints during remote tmux resize redraws.
• Fixed box drawing truncation caused by byte-counting Unicode terminal characters.
• Fixed the Web Control TypeScript release build by restoring the terminal settings reader and required icon import in the published tag.

Compatibility Notes

• Existing explicit token workflows remain supported:

agentmux control app --hub https://hub.example.com --token amx_cred_...
agentmux worker run --hub https://hub.example.com --token amx_cred_...

• Existing Web Control flows continue to work.
• TUI mouse forwarding depends on the remote application enabling mouse reporting. tmux users should enable mouse support in tmux when they want pane selection and border dragging from the TUI.
• Windows release assets are still not published because Worker and terminal attach paths currently rely on Unix PTY behavior.

v0.0.2

AgentMux v0.0.2

Worker onboarding and CLI usability release.

Highlights

• Added local credential caching under the user config directory so Worker and Control devices can reuse exchanged credentials after the first join.
• Added agentmux worker join as the primary Worker onboarding command. It exchanges a signal, saves the Worker credential, and starts a background Worker by default.
• Added Worker lifecycle commands:
  • agentmux worker run
  • agentmux worker start
  • agentmux worker stop
  • agentmux worker status
  • agentmux worker logs
• Added user-level background Worker support:
  • Linux: systemd --user
  • macOS: launchd
  • fallback: detached user process with pid and log files
• Added agentmux-tui as a dedicated Control TUI entrypoint. It can join once, then open the TUI directly on later runs.
• Updated /install.sh so generated Worker commands join and start the background Worker, while generated Control commands install and use agentmux-tui.
• Added tmux availability checks before Worker startup with direct installation guidance.
• Fixed WSS dialing for public HTTPS hubs without explicit ports. Worker and Control websocket clients now default wss://... to port 443.

CLI Changes

Worker onboarding now uses:

agentmux worker join --hub https://hub.example.com --join 'amx_sig_...' --name "$(hostname)"

After the first successful join:

agentmux worker status
agentmux worker logs
agentmux worker stop
agentmux worker start

Foreground debugging remains available:

agentmux worker run

Control TUI onboarding now uses:

agentmux-tui join --hub https://hub.example.com --join 'amx_sig_...'

After the first successful join:

agentmux-tui

The generic agentmux command can still infer the latest cached credential role:

• latest worker credential: starts Worker foreground mode
• latest control credential: opens the Control TUI

Credential Cache

Signal exchange results are stored in:

~/.config/agentmux/credentials.json

The cache stores Hub URL, credential, credential ID, tenant ID, role, device ID, device name, expiration, and update time. Entries are filtered by role and expiration, and newer entries replace older entries for the same Hub, role, and device.

Worker Background Service

agentmux worker join starts a user-level background Worker by default.

On Linux, AgentMux writes a systemd --user unit and runs:

systemctl --user enable --now agentmux-worker.service

On macOS, AgentMux writes a LaunchAgent and loads it with launchctl.

If neither backend is available, AgentMux starts a detached user process and stores pid/log state under:

~/.local/state/agentmux/

The fallback process does not provide automatic restart after reboot; use agentmux worker start to start it again.

tmux Requirement

Worker still depends on tmux as the local session backend in this release. AgentMux now checks for tmux before Worker startup and prints install guidance when it is missing.

Install examples:

sudo apt install tmux
sudo dnf install tmux
sudo pacman -S tmux
brew install tmux

Longer term, AgentMux can add a native PTY session backend so tmux becomes optional. In v0.0.2, tmux remains required because it provides durable local session ownership across Control disconnects.

Install Script

Hub-generated install commands now support the new onboarding shape:

curl -fsSL https://hub.example.com/install.sh | sh -s -- worker --join 'amx_sig_...' --name "$(hostname)"
curl -fsSL https://hub.example.com/install.sh | sh -s -- control --join 'amx_sig_...'

The worker path calls agentmux worker join; the control path installs an agentmux-tui symlink and calls agentmux-tui join.

Fixes

• Fixed Worker websocket dialing through HTTPS public URLs such as ngrok or Cloudflare Tunnel. wss://hub.example.com now connects to hub.example.com:443; previous builds could incorrectly dial port 80 and fail with TLS handshake errors.
• Control CLI commands now share the same credential cache path as Control TUI.
• worker status and worker logs handle missing fallback state files gracefully.

Compatibility Notes

• Existing explicit token workflows continue to work:

agentmux worker run --hub http://127.0.0.1:8080 --token dev-token
agentmux control app --hub http://127.0.0.1:8080 --token dev-token

• Existing agentmux worker --join ... remains accepted for compatibility and is treated as a join flow.
• Release assets remain Unix-focused. Windows is still not published because Worker and terminal attach paths currently depend on tmux and Unix PTY behavior.

v0.0.1

AgentMux v0.0.1

Initial public prototype release.

Highlights

• Introduced the AgentMux three-role architecture: Hub, Worker, and Control.
• Added tmux-backed remote session management for long-lived coding agent sessions.
• Added signal-based onboarding with scoped runtime credentials.
• Added Web Control with xterm.js terminal attach, multi-pane layout, split panes, drag-and-drop placement, and IME-safe input handling.
• Added SQLite-backed Hub persistence foundation for users, signals, and credentials.
• Added Cloudflare Tunnel friendly deployment mode with --public-url.
• Added release install script at /install.sh.
• Added product landing page with architecture visuals, bilingual English/Chinese content, GitHub project identity, and zoomable diagrams.
• Added AgentMux brand mark and documentation visual assets.
• Added GitHub Actions CI and cross-platform release builds.
• Added GitHub Container Registry Docker image publishing.

Release Assets

GitHub Actions builds and uploads:

• agentmux-linux-amd64.tar.gz
• agentmux-linux-arm64.tar.gz
• agentmux-darwin-amd64.tar.gz
• agentmux-darwin-arm64.tar.gz
  Each archive includes a matching .sha256 checksum.

Windows release assets are not published in v0.0.1 because the current worker/control terminal path depends on tmux and Unix PTY semantics.

Docker images are published to:

ghcr.io/kinboyw/agentmux:0.0.1
ghcr.io/kinboyw/agentmux:latest

Quick Start

Run Hub:

agentmux hub \
  --addr 0.0.0.0:8080 \
  --data ./agentmux.db \
  --public-url https://your-hub.example.com

Open the landing page, generate a join signal, then run the generated Worker or Control command:

curl -fsSL https://your-hub.example.com/install.sh | sh -s -- worker --join 'amx_sig_...' --name "$(hostname)"
curl -fsSL https://your-hub.example.com/install.sh | sh -s -- control --join 'amx_sig_...'

For local development:

./scripts/dev-tmux.sh

Notes

This is an early prototype release. Core relay flow, Web Control, signal exchange, install script, SQLite-backed identity persistence, Cloudflare-friendly deployment, and release packaging are in place.

Advanced multi-tenant administration, OAuth provider configuration, direct Worker-Control mode, and production hardening are still evolving.