opencode-ssh-session

An OpenCode plugin that provides persistent SSH session tools. Connect to a remote host once, then run multiple commands with shell state (working directory, environment variables, etc.) preserved between calls.

Installation

Add the plugin to your OpenCode configuration (opencode.json):

{
  "plugin": ["opencode-ssh-session"]
}

OpenCode will automatically install the package via Bun at startup.

Tools

The plugin registers six tools:

ssh_connect

Open a persistent SSH session to a remote host.

| Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------------------------------------------- | | host | string | yes | SSH host (e.g. user@server, myalias, 192.168.1.10) | | options | string | no | Extra SSH flags (e.g. -p 2222, -i ~/.ssh/mykey) |

ssh

Execute a command on the active SSH session. Shell state persists across calls.

| Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------- | | command | string | yes | Shell command to run on the remote host | | timeout | number | no | Timeout in milliseconds (default: 120000 = 2m) |

ssh_disconnect

Close the active SSH session. Shell state is lost. You can reconnect later with ssh_connect.

No parameters.

ssh_info

Get information about the current SSH session — connected host, duration, and whether a command is running.

No parameters.

ssh_upload

Upload a local file to the remote host through the active SSH session using base64 encoding.

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------- | | localPath | string | yes | Absolute path to the local file | | remotePath | string | yes | Destination path on the remote host |

ssh_download

Download a file from the remote host to the local machine through the active SSH session.

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------- | | remotePath | string | yes | Path to the file on the remote host | | localPath | string | yes | Destination path on the local machine |

Hooks

The plugin automatically registers hooks that improve the SSH experience:

Bash guard (tool.execute.before)

Detects when the AI tries to run ssh, scp, sftp, or rsync through the built-in bash tool and injects a reminder to use the SSH session tools instead.

Session cleanup (event)

Automatically cleans up orphaned SSH processes when an OpenCode session errors out.

Commands & Skills

The plugin ships example commands and a skill in the examples/ directory. Copy them to your OpenCode config to use them.

Commands

Copy to .opencode/commands/ (project) or ~/.config/opencode/commands/ (global):

| Command | File | Description | | -------------- | --------------------------------- | ---------------------------------------- | | /ssh <host> | examples/commands/ssh.md | Quick connect to a host | | /ssh-status | examples/commands/ssh-status.md | Check connection status with diagnostics |

Skill

Copy to .opencode/skills/ (project) or ~/.config/opencode/skills/ (global):

| Skill | Directory | Description | | ---------------- | -------------------------------------- | -------------------------------------------- | | ssh-remote-dev | examples/skills/ssh-remote-dev/ | Remote development best practices for the AI |

The skill teaches the AI patterns for deployments, debugging remote services, file transfers, and common pitfalls to avoid.

How It Works

The plugin spawns a single ssh child process per session and communicates with it via stdin/stdout using unique markers to delimit command output. This avoids reconnection overhead and preserves shell state between commands.

• Commands are non-interactive only (no vim, top, etc.)
• A mutex ensures only one command runs at a time
• File transfers use base64 encoding over the existing connection
• The session is automatically cleaned up on disconnect or error

Requirements

• OpenCode with plugin support (@opencode-ai/plugin >= 1.0.0)
• ssh available on the host machine's PATH

License

MIT