https://github.com/gregolsky/ssh-companion
🤖👁️ 💻 Real-time SSH and shell session observer for Claude Code. Capture at the byte stream, advise without access.
https://github.com/gregolsky/ssh-companion
advisor assistant claude claude-code devops docker mcp mcp-server observability ssh terminal
Last synced: 14 days ago
JSON representation
🤖👁️ 💻 Real-time SSH and shell session observer for Claude Code. Capture at the byte stream, advise without access.
- Host: GitHub
- URL: https://github.com/gregolsky/ssh-companion
- Owner: gregolsky
- Created: 2026-04-17T21:57:26.000Z (25 days ago)
- Default Branch: main
- Last Pushed: 2026-04-17T23:51:39.000Z (25 days ago)
- Last Synced: 2026-04-18T00:36:02.887Z (25 days ago)
- Topics: advisor, assistant, claude, claude-code, devops, docker, mcp, mcp-server, observability, ssh, terminal
- Language: Shell
- Homepage:
- Size: 1.26 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ssh-companion
> "I am always here if you need me, though I confess I find the most enjoyment in simply observing."
> — *Daneel Olivaw, The Caves of Steel* (Isaac Asimov)
An MCP server that lets Claude observe your SSH and local shell sessions in real time and advise on support problems — performance issues, log analysis, error detection — without touching anything.
## 🍭 How it looks
## 🔍 How it works
A Docker container acts as the SSH chokepoint. Every session you open through the container is silently captured via `script` to a log file. Local sessions are captured the same way, directly on the host. The MCP server reads those logs and exposes them to Claude. Works with nested tmux on the remote, any shell, any terminal — capture happens at the raw byte stream level.
```mermaid
flowchart LR
T(["Your terminal"])
subgraph docker ["Docker: ssh-companion"]
W["ssh-wrapper"]
R(["Remote server"])
W <-->|SSH| R
end
L[("~/.ssh-companion-sessions/*.log")]
subgraph srv ["MCP server"]
S["server.py\nstrips ANSI"]
end
CC(["Claude Code"])
T -->|"companion.sh"| W
W -->|"script -f"| L
T -->|"companion-local.sh"| L
L --> S
S -->|stdio| CC
```
## 📋 Prerequisites
- Docker
- tmux (Linux) or Windows Terminal / `wt` (Windows)
- [Claude Code CLI](https://claude.ai/code)
## 🚀 Setup
### 1. Start the container
Pull the pre-built image from GitHub Container Registry and run it:
```bash
docker run -d --name ssh-companion \
-v ~/.ssh:/home/companion/.ssh \
-v ~/.ssh-companion-sessions:/sessions \
--restart unless-stopped \
ghcr.io/gregolsky/ssh-companion:latest
```
**About the key mount:** `ssh` runs *inside* the container as a non-root `companion` user, so it can only read keys that are visible inside the container. The `-v ~/.ssh:/home/companion/.ssh` line above mounts your host SSH directory at the companion user's home — your usual keys (`id_ed25519`, `id_rsa`, etc.) and `known_hosts` are picked up as normal, and new hosts can be written back to `known_hosts`. Add `:ro` to the mount if you want to keep it read-only (note: this breaks first-time host-key acceptance).
**UID caveat:** the prebuilt image pins `companion` to UID/GID 1000, which matches most single-user Linux desktops. If `id -u` on your host isn't 1000, the container won't be able to read your keys or write session logs — build from source instead:
```bash
git clone https://github.com/gregolsky/ssh-companion.git
cd ssh-companion
./build.sh # picks up your host UID/GID automatically
```
If your keys live elsewhere, mount that directory instead (or in addition). Examples:
```bash
# Throwaway key at /tmp/temp-key on the host:
-v /tmp:/tmp
# Project-local keys under ~/work/keys:
-v ~/work/keys:/home/companion/keys:ro # then: ssh -i /home/companion/keys/ user@host
```
Prefer not to mount keys at all? Start your SSH agent on the host, forward it with `-A` (`./companion.sh ssh -A user@host`), and the container uses your agent over the forwarded socket.
**Alternative — build from source:**
```bash
git clone https://github.com/gregolsky/ssh-companion.git
cd ssh-companion
./start-mcp-server.sh
```
### 2. Register the MCP server with Claude Code
#### ✅ Automatic registration
The launch scripts (`companion.sh`, `companion-local.sh`) do this automatically.
#### 🪛 Manual approach
To register manually:
```bash
claude mcp add ssh-companion docker -- exec -i ssh-companion python /app/server.py
```
Or add to `.mcp.json` in your project root for automatic registration when Claude Code opens that directory:
```json
{
"mcpServers": {
"ssh-companion": {
"command": "docker",
"args": ["exec", "-i", "ssh-companion", "python", "/app/server.py"]
}
}
}
```
## 💻 Usage
### SSH session (Linux)
Opens the SSH session on the left and Claude on the right, side by side.
```bash
# Default keys from ~/.ssh (works out of the box if you used the mount
# from the Setup step above):
./companion.sh ssh ubuntu@prod-db-1
# Specific key — the path is resolved inside the container, so the
# directory must be mounted (see "About the key mount" above):
./companion.sh ssh -i /home/companion/.ssh/work_key ubuntu@prod-db-1
# Agent forwarding — no key mount needed:
./companion.sh ssh -A ubuntu@prod-db-1
```
### SSH session (Windows)
```powershell
.\companion.ps1 ssh ubuntu@prod-db-1
.\companion.ps1 ssh -i ~\.ssh\key.pem ubuntu@prod-db-1
```
### Local shell session
Observe a local bash session — no SSH, no Docker for the capture side.
```bash
./companion-local.sh
```
Claude sees it as hostname `local`: `focus_session("local")`.
### Layout options
Both `companion.sh` and `companion-local.sh` accept:
- `--split` (default) — tmux side-by-side pane (prefix remapped to `C-q`)
- `--windows` — two separate terminal windows
`--windows` auto-detects the terminal emulator (gnome-terminal, konsole, alacritty, kitty, wezterm, xfce4-terminal, xterm, or the Debian `x-terminal-emulator` alternative). Override with `COMPANION_TERMINAL_APP`:
```bash
COMPANION_TERMINAL_APP=alacritty ./companion.sh --windows ssh user@host
```
If tmux is missing and no layout is specified, the scripts fall back to `--windows` automatically. On Windows, `companion.ps1` supports `-Split` / `-Windows` switches.
### Manual SSH (if you prefer your own terminal layout)
```bash
# Add this alias to ~/.bashrc or ~/.zshrc
alias ssh='docker exec -it ssh-companion ssh'
# Then use ssh normally — sessions are captured automatically
ssh user@prod-db-1
```
### Ask Claude for help
Once you're in a session, switch to the Claude pane and ask:
```
What's happening on prod-db-1?
```
Claude will call `focus_session("prod-db-1")` and read the last 200 lines of your session.
### Active watch mode (`/loop`)
To have Claude monitor a session and alert you proactively:
```
/loop Watch prod-db-1 every 30 seconds. Call read_session_since with the last
byte_offset each time. Alert me if you see errors, OOM messages, high load,
or anything that looks like it needs attention.
```
**Pre-seed the loop at launch** — instead of typing `/loop …` after Claude opens, pass the prompt via `--instructions-loop`:
```bash
./companion.sh --instructions-loop "Watch prod-db-1 every 30 seconds. \
Call read_session_since with the last byte_offset each time. \
Alert me if you see errors, OOM messages, or high load." \
ssh ubuntu@prod-db-1
```
Works the same with `companion-local.sh`, and with `-InstructionsLoop` on `companion.ps1`. Flags must come before the `ssh` subcommand.
## 🛠️ MCP Tools
| Tool | Description |
|------|-------------|
| `list_sessions()` | List all captured sessions by hostname with last-active time |
| `focus_session(hostname, lines=200)` | Read the latest session log — returns clean text + byte_offset |
| `read_session_since(hostname, byte_offset)` | Efficient poll — only new output since last read |
| `search_session(hostname, pattern)` | Grep all logs for a hostname using a Python regex |
## 🖥️ Multiple servers
Each server gets its own log file(s) under `~/.ssh-companion-sessions/-.log`. Switching between servers just means telling Claude a different hostname — it reads the right log automatically.
```
# You were on prod-db-1, now you're jumping to prod-web-2:
ssh user@prod-web-2
# In Claude:
"I'm now on prod-web-2 — what do you see?"
```
## 🛡️ Threat model
### What ssh-companion defends against
- **Container escape / privilege escalation inside the container.** The container runs as a non-root `companion` user with `--cap-drop=ALL` and `--security-opt=no-new-privileges`. A compromised process can't use Linux capabilities or setuid binaries to elevate.
- **Stale upstream CVEs.** CI runs Trivy on every PR and weekly to flag fixable HIGH/CRITICAL findings in the base image, and Dependabot nudges updates for the Dockerfile base image and GitHub Actions.
- **Tampering with the MCP server or ssh wrapper binaries.** The container is built from source on every release — there's no writable persistence layer that survives a rebuild.
### What's out of scope
- **Host trust.** ssh-companion assumes the host is trusted. `~/.ssh` is bind-mounted into the container (read-write by default so `known_hosts` updates work), so a compromised container still has access to your keys. If that's not acceptable, add `:ro` to the mount and accept the TOFU-verification friction.
- **The SSH target itself.** Whatever the user types in the session hits the remote as-is. The tool observes; it does not filter, rate-limit, or sanitize.
- **Session log confidentiality.** Logs capture the raw session byte stream, including anything typed into interactive prompts (passwords, tokens, sudo inputs). They live at `~/.ssh-companion-sessions/` with host filesystem permissions — anyone with read access to that directory can replay them.
- **MCP access control.** Any process on the host that can `docker exec` into the container can invoke the MCP tools and read every captured session. Claude's tool access is not sandboxed beyond that.
- **Supply chain of `mcp[cli]` and base image.** Trivy scans known CVEs, but zero-days and compromised upstream packages are not detected.
## 🧹 Stopping / cleanup
```bash
# Stop the container
docker stop ssh-companion && docker rm ssh-companion
# Clear session logs (optional)
rm -rf ~/.ssh-companion-sessions
```
## 📝 Notes
- **Read-only**: Claude can only observe. No commands are sent to any session.
- **Nested tmux**: works fine. The capture is at the SSH byte stream level, so what remote tmux renders is captured as-is and ANSI-stripped for Claude.
- **No prefix clash**: `companion.sh` runs tmux on a dedicated socket with the prefix remapped to `C-q`, so `C-b` passes cleanly through to your remote tmux session. Use `C-q` as the local prefix (e.g. `C-q d` to detach, `C-q o` to switch panes).
- **SSH keys**: `ssh` runs inside the container as a non-root `companion` user, so it can only read keys mounted into the container (default: `-v ~/.ssh:/home/companion/.ssh`). Agent forwarding (`-A`) works too — see the Setup section for details, including the UID caveat.