sideshell

AI sidecar terminal — let Claude/Cursor run commands in a visible, persistent terminal you control.

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

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)

MCP Resources

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