Remote stitching

Remote stitching relieves tmux users from having to self-manage tmux-in-tmux instances.

Previously, to maintain SSH connectivity through a jump host as a tmux user, you’d have to:

1. Open an SSH connection to the jump host from inside a local tmux pane
2. On the jump host, start another instance of tmux
3. Open a second SSH connection to the actual target
4. Fumble with sending the prefix key twice to communicate ‘detach’ to the remote tmux

With remote stitching:

1. Configure a remote server once in Options
2. From any pane, select ☰ then Convert to remote and choose the server
3. Anything you do on the remote host will be persisted for you ¹

Effectively, remote stitching converts a single local tmux pane into a window onto a shell running on an SSH host. The pane keeps its place in your local layout, the surrounding window stays local, and Honeymux continues to track clipboard passthrough and agent activity through the remote connection — so one window can mix local and remote panes without leaving the local tmux session.

Configuring remote servers

Remote targets live in the remote array of ~/.config/honeymux/config.json. Each entry is a RemoteServerConfig object with:

• name (required) — user-facing label shown in the pane border menu, for example "dev-box".
• host (required) — SSH hostname or an alias from ~/.ssh/config.
• port (optional) — SSH port. Defaults to 22.
• identityFile (optional) — path to an SSH identity key file.
• agentForwarding (optional) — forward the local SSH agent to the remote. Defaults to false.

See remote in the Configuration reference for the authoritative field list. Edit the array by hand or from the Remote tab in Options.

Caution

Agent forwarding is opt-in — set agentForwarding: true only for hosts you trust. Honeymux does not auto-accept unknown SSH host keys; add the host to your known_hosts the usual way before stitching panes to it.

Converting a pane to remote

Open the pane border menu from the ≡ button on any pane border, then pick Convert to remote ▸ and choose a server from the submenu.

A server whose SSH connection is still coming up is listed as <name> (please wait) and is disabled until it is ready. When no configured server has connected yet, the parent menu item reads Convert to remote (please wait) with no submenu arrow.

Behind the scenes Honeymux spawns a shell on a mirror pane over the SSH connection and respawns the local pane with a proxy process that forwards output from the remote shell. The local pane ID does not change, so pane tabs, zoom, and layout are preserved.

Reverting to local

On a remote pane, the border menu’s first entry becomes Revert to local. Selecting it respawns the pane with a local shell and clears the @hmx-remote-* tmux options that marked the pane as remote.

XXX TODO: I think this feature is broken; revisit

When SSH fails

If a server’s SSH connection drops or fails to come up, Honeymux records the error and surfaces it through the Notifications review frame. Opening the entry shows the SshErrorDialog — the server name, the sanitized error text, and how long ago it happened — with an OK button to dismiss.

Dismissing the dialog clears it for that review pass; the underlying warning also clears automatically once the server reconnects.

Agent monitoring over remote

Coding agents started inside a remote pane are tracked the same way as local ones. In the Agents dialog and the Agents view of the Sidebar, remote sessions are grouped under their server’s name instead of localhost, so you can tell at a glance which host a given agent is running on. See Agent Integrations for per-provider install details.

Footnotes

1. This is accomplished in part by mirroring the local tmux layout to each remote server. ↩