Discussion: Alternative approach for remote sessions — SSH ControlMaster + direct tmux (no av required on remote)

[huang-hf]

Background

PR #31 added remote session support by running av on the remote machine via SSH. This is a solid approach that leverages all of av's capabilities on the remote side.

I've been working on an alternative implementation (feat/ssh-remote) that takes a different architectural approach. I'd like to discuss the trade-offs and see if there's interest in either merging ideas or offering both approaches.

Our Approach: SSH ControlMaster + Direct tmux Control

Instead of running av on the remote, we directly control the remote tmux server via SSH — the same way av controls local tmux, but over SSH.

How it works

1. SSH ControlMaster — a persistent background SSH connection is established per host (-o ControlMaster=yes -o ControlPersist=120). Subsequent tmux commands reuse the socket (~10–50ms latency vs ~300ms per new SSH handshake).

2. TmuxExecutor abstraction — a new interface that abstracts tmux command execution:

   • LocalTmuxExecutor — wraps local execFileAsync("tmux", ...)
   • SshTmuxExecutor — routes the same tmux commands through SSH ControlMaster

3. All session operations (create, stop, restart, delete, capture-pane, status polling) go through this abstraction — local and remote sessions share the same code path.

4. Sessions stored locally — remote_host column added to SQLite. No dependency on a running av instance on the remote.

Remote server requirements

• tmux
• The AI tool (claude, opencode, etc.)

That's it — no av installation required on the remote.

UX

• Remote hosts configured via the Settings dialog (c key) — add named SSH aliases (e.g. ai-consulting → maps to ~/.ssh/config)
• When creating a session, a Remote Host selector appears if any hosts are configured
• Remote sessions appear in the unified session list with a [host] tag
• Status polling works the same as local: tmux capture-pane output is parsed for running/waiting/idle/error states
• Attach (Enter) works via ssh -t + tmux attach-session
• Custom tmux.conf is uploaded to remote on first connect so Ctrl+Q detach binding works

Comparison

	PR #31 approach	This approach
Remote requirements	av installed	tmux only
Session storage	Remote SQLite	Local SQLite
Status polling	av list --json	tmux capture-pane via SSH
Multiple hosts	Last-used host only	Named alias list in Settings
Connection	ControlMaster=auto	Explicit lifecycle (connect/check/disconnect)
av features on remote	Full	N/A (direct tmux)

Trade-offs

PR #31 strengths:

• Leverages the full av feature set on the remote (fork, hibernate, etc.)
• Simpler to implement new features (just delegate to av)
• Remote state is self-contained on the remote machine

This approach strengths:

• Zero remote setup friction — works on any machine that can run claude/tmux
• No need to keep av versions in sync across machines
• Unified local session database — one source of truth
• Connection pooling via ControlMaster reduces per-command overhead

Questions for discussion

1. Is the "no remote installation required" property valuable enough to consider supporting both approaches?
2. Would a TmuxExecutor abstraction be a useful foundation even if the higher-level approach differs?
3. Is there interest in merging the named-alias host management from this approach into the existing remote session UX?

Happy to submit a PR if there's interest. The implementation is at: https://github.com/huang-hf/agent-view/tree/feat/ssh-remote