Metadata-Version: 2.4
Name: sideshell-mcp
Version: 1.0.0
Summary: AI sidecar terminal - let Claude/Cursor run commands in a visible, persistent terminal you control
Project-URL: Homepage, https://github.com/menemy/sideshell
Project-URL: Documentation, https://github.com/menemy/sideshell#readme
Project-URL: Repository, https://github.com/menemy/sideshell
Project-URL: Issues, https://github.com/menemy/sideshell/issues
Project-URL: Changelog, https://github.com/menemy/sideshell/blob/main/CHANGELOG.md
Author: sideshell contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,cursor,iterm2,kitty,llm,mcp,model-context-protocol,sidecar,terminal,tmux,wezterm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Shells
Classifier: Topic :: Terminals :: Terminal Emulators/X Terminals
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: mcp>=1.14.0
Provides-Extra: all
Requires-Dist: iterm2>=2.7; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.13.0; extra == 'dev'
Provides-Extra: iterm2
Requires-Dist: iterm2>=2.7; extra == 'iterm2'
Description-Content-Type: text/markdown

# sideshell

**AI sidecar terminal** — let Claude/Cursor 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

| Terminal | Platform | Status |
|----------|----------|--------|
| **iTerm2** | macOS | ✅ Full support (native Python API) |
| **tmux** | macOS, Linux, WSL | ✅ Full support |
| **WezTerm** | macOS, Linux, Windows | ✅ Full support |
| **Kitty** | macOS, Linux | ✅ Full support |
| **Ghostty** | macOS | ✅ Full support (`ghostty_tmux` hybrid: native AppleScript splits + per-surface tmux engine, Ghostty 1.3+) |
| **maquake** | macOS | ✅ Full support (drop-down terminal via Unix socket) |
| **VS Code / Cursor** | macOS, Linux, Windows | ✅ Full support (via extension, Unix-socket bridge) |
| **JetBrains IDEs** | macOS, Linux, Windows | ✅ Full support (via plugin, Unix-socket bridge) |

## 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
