I Got Tired of Splitting My Brain Between Local AI and Remote SSH, So I Built ssh-session-mcp

Zw-awa — Tue, 21 Apr 2026 14:44:43 +0000

I spend a lot of time in environments where the real work does not happen on my laptop.

The code editor is local. The AI assistant is local. But the target machine is often a remote Linux box, a board, a test host, or a GPU server.

That creates a very annoying workflow gap.

My AI assistant can edit files, reason about code, and suggest the exact fix. But the moment the next step involves SSH, I am back to doing manual relay work:

switch to another terminal
connect to the remote host
run the command myself
inspect the output
paste the result back into the AI chat

At that point, the AI is not really participating in the remote workflow. It is just advising from the sidelines.

That is why I built and open sourced ssh-session-mcp.

The Problem Is Not "SSH Is Hard"

SSH itself is mature. The real problem is that most AI coding workflows still treat remote terminals as an external, human-only space.

In practice, that causes several recurring issues.

1. Local AI and remote execution live in different worlds

Your model can understand the repository and modify local files, but it cannot naturally step into the remote terminal where the service actually runs.

So even when the AI knows exactly what should happen next, you still become the manual transport layer.

2. A terminal is stateful, but many integrations treat it like stateless RPC

A remote shell is not just "run command, get output."

It may currently be in:

a normal shell prompt
a password prompt
a pager like less
an editor
a long-running command
a streaming session

If the tool does not understand terminal state, it can easily make the wrong move.

3. Human and AI collaboration on the same remote session is awkward

Real development is not fully manual or fully automated.

Usually it looks more like this:

let the AI inspect the environment
take over manually for one or two commands
hand control back to the AI

Without explicit coordination, that turns into input collisions and confusing terminal history.

4. Multi-host work is easy to get wrong

One local repo can map to several remote targets:

board A
board B
a staging VM
a shared Linux server

In those cases, "the command succeeded" is not enough. You also need confidence that it ran on the correct target.

What I Built

ssh-session-mcp is a persistent SSH PTY session manager for MCP clients.

The short version:

it manages a real SSH PTY session
an AI agent can operate it through MCP tools
the user can observe and type into the same session from a browser terminal
both sides share one actual terminal context

This is the key design choice: not parallel lookalike sessions, but one shared PTY.

That matters because state is the whole point. If the user and the AI are not looking at the same terminal state, they are not really collaborating.

What `ssh-session-mcp` Does Right Now

I have kept the scope intentionally narrow. This project focuses on the SSH transport/runtime layer, not on project-specific business logic.

Current capabilities include:

Shared SSH terminal

The user and the AI share one PTY, so they see the same shell state.

Browser terminal

There is a local browser-based terminal for observation and manual takeover.

Input locking

You can switch between common, user, and claude/codex modes to avoid input conflicts.

Safe vs full mode

Safe mode blocks obviously dangerous commands, interactive programs, and commands that do not naturally terminate.

Intelligent command completion

ssh-run does not rely on a naive fixed timeout. It combines prompt detection, idle timeout, and sentinel markers.

Async command tracking

Long-running commands can automatically transition to async mode and be polled later.

Diagnostics and line-based history

I did not want this to become a black box, so the project includes session diagnostics and line-numbered history recall.

Multi-device profiles

You can manage multiple targets and named connections through configuration instead of constantly rewriting host/user settings.

The Workflow I Wanted

This is the kind of loop I wanted AI tools to support cleanly:

ssh-quick-connect -> ssh-run -> inspect output -> decide -> ssh-run

If the command is long-running:

ssh-run({ command: "apt update" })
-> async commandId

ssh-command-status({ commandId: "..." })

And if I want to intervene manually, I should be able to type into the same terminal without rebuilding the whole session from scratch.

That sounds simple, but it changes the experience a lot. The remote environment stops being a blind spot in the AI workflow.

Why I Did Not Build "Yet Another AI Platform"

I think infrastructure projects get messy when they try to absorb too much.

So I keep ssh-session-mcp focused on:

sessions
viewers
targeting
locks
logging
tool contracts

I am explicitly not trying to bake in:

ROS workflows
board-specific business logic
domain prompts
training pipelines
project orchestration logic

Those things belong outside this repo.

I would rather have a small, reliable runtime layer than a bloated project that mixes transport, policy, and product-specific automation.

Who This Is For

I think this project is most useful if you work in one of these setups:

embedded or board development
remote Linux development
GPU or VM-based development environments
AI-assisted workflows where manual takeover still matters

If all your work happens locally, this may not be very interesting.

But if you keep feeling the gap between "AI can edit my code" and "I still have to manually drive the remote machine," then this is exactly the gap I am trying to close.

Quick Start

Install it:

npm install -g ssh-session-mcp

Or build from source:

git clone https://github.com/Zw-awa/ssh-session-mcp.git
cd ssh-session-mcp
npm install
npm run build

Then configure .env or ssh-session-mcp.config.json, launch the runtime, and register it as an MCP server for your AI client.

Final Thought

I do not think the future of AI-assisted development is "the model does everything."

I think the more realistic future is this:

the model and the developer share better infrastructure.

For remote development, that means SSH can no longer remain a manual side channel outside the workflow.

That is what ssh-session-mcp is trying to fix.

Repo:

https://github.com/Zw-awa/ssh-session-mcp

If you work on remote machines and have strong opinions about shared terminals, safety modes, session targeting, or human/AI handoff, I would genuinely like to hear them.

Forem: Zw-awa