Sideshell

AI sidecar terminal — let any MCP client (Claude Code, Cursor, Codex, OpenCode, Pi, …) run commands in a visible, persistent terminal you control.

PyPI version License: MIT

Why?

When AI assistants run shell commands, they execute in a hidden terminal:

• ❌ No visible history
• ❌ Can't intervene (enter password, confirm prompts)
• ❌ Output mixed with AI conversation

sideshell runs commands in a separate visible terminal:

• ✅ Full command history visible
• ✅ Persistent session (survives AI restarts)
• ✅ Intervene anytime (passwords, confirmations)
• ✅ Clean separation from AI conversation

Supported Terminals

Verified on lists the operating systems where the backend is exercised by a live end-to-end test pass. Other combinations may work but are not yet verified — see Notes.

Terminal	Verified on	Notes
iTerm2	macOS	Native Python API
tmux	macOS, Linux	Also expected in WSL (tmux on PATH); not yet verified there
WezTerm	macOS, Linux	Windows expected (wezterm cli); not yet verified
Kitty	macOS, Linux	—
Ghostty	macOS	ghostty_tmux hybrid: native AppleScript splits + per-surface tmux engine (Ghostty 1.3+)
maquake	macOS	Drop-down terminal via Unix socket
VS Code / Cursor	macOS, Linux	Extension + Unix-socket bridge. execute(wait)/output read use VS Code shell integration (on by default for bash/zsh/fish/pwsh). Windows uses a named-pipe bridge — code ready, e2e pending
JetBrains IDEs	macOS, Linux	Plugin + Unix-socket bridge; verified on both terminal engines (Classic + Reworked). Windows named-pipe server pending

Features

• Multi-Backend - Works with iTerm2, tmux, WezTerm, Kitty, Ghostty, maquake, VS Code/Cursor, or JetBrains IDEs
• Sidecar Terminal - AI commands run in a visible terminal pane
• You Stay in Control - See everything, intervene anytime
• Session Persistence - Terminal survives AI session restarts
• TUI Support - Arrow keys, F1-F12, Ctrl+C/D/Z for interactive apps
• Focus Management - Optionally returns focus after operations

Installation

Using uvx (Recommended)

# Install uv first
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run sideshell
uvx sideshell-mcp

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "sideshell": {
      "command": "uvx",
      "args": ["sideshell-mcp"]
    }
  }
}

Using pipx

pipx install sideshell-mcp
sideshell-mcp

Backend Selection

# Auto-detect (default)
uvx sideshell-mcp

# Force specific backend
uvx sideshell-mcp --backend=tmux
uvx sideshell-mcp --backend=iterm2

Available Tools (17)

Tool	Description
execute	Execute commands (supports wait, timeout, targets for broadcast)
read	Read terminal output
control-char	Send special keys: Ctrl+C/D/Z, arrows, F1-F12, Home/End, PageUp/Down
list	List all windows/tabs/sessions
split	Split pane horizontally or vertically
new-window	Create new window
new-tab	Create new tab
new-session	Smart session creation (splits if window exists)
focus	Focus specific session
close-session	Close terminal session
set-appearance	Set tab title, badge, and color
get-terminal-state	Get detailed terminal state
list-color-presets	List available color presets
set-color-preset	Apply color preset
show-alert	Show alert dialog
clear	Clear terminal screen
paste	Paste text to terminal

MCP Resources

Resource	Description
sideshell://sessions	List all terminal sessions
sideshell://capabilities	Backend features and system info
sideshell://sessions/{id}	Session details
sideshell://sessions/{id}/screen	Screen content

Prerequisites

iTerm2 (macOS)

1. Open iTerm2 → Preferences → General → Magic
2. Enable "Enable Python API"
3. Restart iTerm2

tmux

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

WezTerm

Download from wezfurlong.org/wezterm

Kitty

# macOS
brew install --cask kitty

# Linux
curl -L https://sw.kovidgoyal.net/kitty/installer.sh | sh

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│ MCP Client  │────▶│  sideshell   │────▶│  Terminal   │
│   (Claude)  │     │  MCP Server  │     │   Backend   │
└─────────────┘     └──────────────┘     └─────────────┘
                            │
                    ┌───────┴────────────┐
                    │      Backends      │
                    ├────────────────────┤
                    │ • iTerm2           │
                    │ • tmux             │
                    │ • WezTerm          │
                    │ • Kitty            │
                    │ • Ghostty          │
                    │ • maquake          │
                    │ • VS Code / Cursor │
                    │ • JetBrains IDEs   │
                    └────────────────────┘

VS Code/Cursor and JetBrains backends talk to their IDE extension/plugin over a local Unix domain socket (~/.sideshell/<ide>.sock) using newline-delimited JSON-RPC 2.0 with a token handshake.

Development

git clone https://github.com/menemy/sideshell
cd sideshell
uv pip install -e ".[dev]"

# Run tests
python tests/test_iterm2_backend.py   # iTerm2
python tests/test_tmux_backend.py     # tmux
python tests/test_wezterm_backend.py  # WezTerm
python tests/test_kitty_backend.py    # Kitty

# Lint & format
ruff format .
ruff check . --fix

Requirements

• Python 3.11+
• One of: iTerm2, tmux, WezTerm, Kitty, Ghostty, maquake, VS Code/Cursor, or a JetBrains IDE

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request