Sideshell

sideshell

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

[](https://badge.fury.io/py/sideshell-mcp) [](https://opensource.org/licenses/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/.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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: menemy
• Source: menemy/sideshell
• License: MIT
• Homepage: https://sideshell.dev

Install and usage instructions live in the source repository linked above.