# 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](https://badge.fury.io/py/sideshell-mcp.svg)](https://badge.fury.io/py/sideshell-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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)

```bash
# 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`):
```json
{
  "mcpServers": {
    "sideshell": {
      "command": "uvx",
      "args": ["sideshell-mcp"]
    }
  }
}
```

### Using pipx

```bash
pipx install sideshell-mcp
sideshell-mcp
```

### Backend Selection

```bash
# 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
```bash
# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux
```

### WezTerm
Download from [wezfurlong.org/wezterm](https://wezfurlong.org/wezterm/)

### Kitty
```bash
# 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

```bash
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