PRIMARY TOOL - Intelligent shell command handler for remote sessions.

This tool automatically detects and handles:

1. Remote shell commands (ssh, gcloud compute ssh, aws ssm, az ssh, etc.) - Starts a persistent session

2. Regular commands when session is active - Executes in the remote session

3. Session control - Use special exit sequences to close the session

Smart Wait Time: Automatically adjusts wait time based on command type (longer for builds, shorter for ls).

Working Directory Tracking: Tracks cd commands and shows current directory in prompt.

Control sequences (to avoid conflict with normal commands):

• ~. or //end - End session and return to local shell

• //stop or //kill or //ctrl-c - Send Ctrl+C (SIGINT) to interrupt running command

Auto-reconnect: Sessions automatically attempt to reconnect on disconnection.

Sessions auto-cleanup after 1 hour of inactivity. Output is displayed exactly as the terminal shows.

Start a remote shell session with explicit parameters. Use for fine-grained control.

For most cases, prefer the shell tool which auto-detects remote commands.

Get status of all remote sessions with working directory, port forwards, and auto-reconnect status.

Switch the active session when multiple sessions are open.

End remote session(s). Use sessionId='all' to end all sessions.

Get command history for a session with working directories.

Read recent raw output from session buffer.

Send a signal to the session (SIGINT=Ctrl+C, SIGTERM, SIGKILL, SIGHUP).

Search through command history and output. Supports regex.

Find error messages in session history (looks for 'error', 'failed', 'denied', etc.).

Upload a file from local machine to the remote server.

Works with both SSH2 and child process sessions:

• SSH2: Uses SFTP for efficient binary transfer

• Child process: Uses base64 encoding through the shell

Example: Upload a config file to the server.

Download a file from the remote server to local machine.

Works with both SSH2 and child process sessions:

• SSH2: Uses SFTP for efficient binary transfer

• Child process: Uses base64 encoding through the shell

Example: Download logs or config files from a server.

List files in a remote directory with details (like ls -la).

Start a LOCAL port forward (SSH -L style).

Listens on a local port and forwards connections to a port on the remote server.

Example: Access a database running on the remote server:

• localPort: 5433

• remoteHost: localhost

• remotePort: 5432 → Connect to localhost:5433 to access the remote PostgreSQL

Start a REMOTE port forward (SSH -R style).

Listens on a port on the remote server and forwards connections back to your local machine. Requires SSH2 session type.

Example: Expose a local dev server to the remote:

• remotePort: 8080

• localPort: 3000 → Remote server port 8080 forwards to your localhost:3000

List all active port forwards.

Stop a specific port forward by ID.

Stop all port forwards for a session or all sessions.

List command blocks for a session.

Each command execution creates a "block" containing the command and its output. Blocks can be searched, tagged, and referenced by ID.

Get a specific block by ID with full output.

Returns the complete command and output for a block.

Search through command blocks.

Search command history and output across blocks.

Get block output only (for copying).

Returns just the output without the command or metadata.

Add tags to a block for organization.

Tags can be used to filter blocks when searching.

Remove tags from a block.

Toggle or set block collapsed state.

Find error blocks in session history.

Returns blocks that had errors (non-zero exit or error patterns).

Split the current pane horizontally or vertically (tmux-style).

Creates a new pane within the session. Use for running multiple commands in parallel or monitoring.

Switch to a specific pane.

Close a pane (cannot close the last pane).

List all panes for a session.

Execute a command in a specific pane without switching focus.

Broadcast a command to all panes in a session.

Useful for running the same command in multiple contexts simultaneously.

Rename a pane for easier identification.

Switch to the next pane in the session.

Share a terminal session for collaboration.

Creates a shareable URL that others can use to view (or control) your terminal session in real-time.

Stop sharing a session.

List all active session shares.

Update share settings (permissions, expiration).

Start the share server (usually starts automatically).

Stop the share server and disconnect all viewers.

Create a swarm of parallel SSH sessions to multiple machines.

Swarms allow you to connect to multiple servers simultaneously and broadcast commands. Useful for managing clusters, fleets, or performing parallel operations.

Example targets for SSH: [{ "id": "web1", "host": "10.0.0.1", "username": "admin" }, { "id": "web2", "host": "10.0.0.2", "username": "admin" }]

Example targets for GCloud: [{ "id": "vm1", "instance": "my-vm-1", "zone": "us-central1-a" }, { "id": "vm2", "instance": "my-vm-2", "zone": "us-central1-a" }]

List all active swarms with their status.

Get detailed status of a specific swarm including all targets.

Broadcast a command to all sessions in a swarm (parallel execution).

Returns aggregated output from all targets. Use for running the same command across multiple machines.

Send input text to all sessions in a swarm.

Useful for responding to prompts (passwords, confirmations) across all targets.

Send Ctrl+C (SIGINT) to all sessions in a swarm.

End a swarm, closing all its sessions. Use swarmId='all' to end all swarms.

Add a new target to an existing swarm.

Remove a target from a swarm (closes its session).

Send input text to a session (respond to prompts, passwords, confirmations).

Use when a remote command is waiting for user input:

• Password prompts

• Y/N confirmations

• Interactive text input

• Any prompt ending with : or ?

Set hideInput=true for passwords to avoid logging sensitive data.

Check if a session is waiting for user input (password, confirmation, etc.).

Returns details about any detected prompt and how to respond.

Send a Y/N confirmation response to a session.

Send a password to a session. Input is automatically hidden in responses.

Use when prompted for sudo password, SSH passphrase, or other secret input.

Enable real-time streaming for a session with error detection.

When enabled, the system monitors output in real-time for:

• Error patterns (configurable)

• Interactive prompts requiring input

• Command completion

With autoInterrupt=true, it will automatically send Ctrl+C when errors are detected.

Disable real-time streaming for a session.

Get streaming status for a session (enabled, error count, pending prompts).