Open a new SSH session in a tmux window. Returns the session_id.

The host can be an SSH config alias or a hostname/IP. The session_id will be in the format 'user@host-'. The initial snapshot is included in the response to verify connection success.

Send a command to an active session and return the screen snapshot.

This tool automatically polls waiting for the command to complete. The response includes [INFO: ...] hints about detected prompts or interactive input requests.

For long-running commands (builds, downloads, etc.), use get_snapshot() to check progress periodically. Do NOT close the session while processes are running - they will be terminated.

Args: session_id: The ID of the session (format: user@host-). command: The command to send. lines: Number of lines to capture from the end of the screen and tmux scrollback (default 40). timeout: Max seconds to poll for command completion (default 2.0). Increase for slower commands like package installs.

Send raw keystrokes to a session without appending Enter.

Use this for:

• Interrupting commands: keys="C-c" (Ctrl+C)

• Sending EOF: keys="C-d" (Ctrl+D)

• Interactive input: keys="yes" (without submitting)

• Special keys: keys="Enter", keys="Tab", keys="BSpace"

Tmux key notation: C-x (Ctrl), M-x (Alt), S-x (Shift). Multiple keys: "C-c Enter" After sending keys, use get_snapshot() to see the result.

Args: session_id: The ID of the session (format: user@host-). keys: Keys to send using tmux notation.

Get the current screen state of a session.

Use this to check on long-running commands without sending new input. The response includes [INFO: ...] hints about detected prompts or interactive states.

Args: session_id: The ID of the session (format: user@host-). lines: Number of lines to capture from the end of the screen and tmux scrollback (default 40).

List all SSH sessions, including dead ones (SSH connection closed but pane not yet cleaned up).

Dead sessions still have their terminal output available via get_snapshot(). Use close_session() to clean them up.

Close an active SSH session and return its final screen state.

WARNING: Closing a session will terminate any running processes in that session. For long-running tasks (builds, downloads, etc.), leave the session open until the task completes. You can monitor progress using get_snapshot() without closing.

Kill all sessions where the SSH connection has closed.

Args: max_age_seconds: Optional. Only kill sessions that have been dead for at least this many seconds. If omitted, all dead sessions are killed immediately.

Read a file from the remote host using the established session.

Prefer this over running 'cat' via send_command/get_snapshot when you want file contents. send_command() and get_snapshot() only return the last N lines of visible terminal output.

read_remote_file() attempts a direct SSH file read first so agents can get the full file instead of just the pane tail. If that is not possible, it falls back to reading via the existing PTY. fallback_lines controls how much tmux history to inspect during that PTY fallback (default 200). Best for text files such as configs, logs, and source code.

Write content to a file on the remote host using the established session.

Use this tool to write file contents instead of using echo, redirection, or heredocs with send_command. This method handles large files, binary data, and special characters correctly.