内容
# 侧边终端
**AI 侧边终端** — 让任何 MCP 客户端（Claude Code, Cursor, Codex, OpenCode, Pi, …）在您可控制的可见、持久终端中运行命令。
[](https://badge.fury.io/py/sideshell-mcp)
[](https://opensource.org/licenses/MIT)
## 为什么？
当 AI 助手运行 shell 命令时，它们会在隐藏的终端中执行：
- ❌ 没有可见的历史记录
- ❌ 无法干预（输入密码，确认提示）
- ❌ 输出与 AI 对话混合
**sideshell** 在一个**单独的可见终端**中运行命令：
- ✅ 完整的命令历史记录可见
- ✅ 持久会话（在 AI 重启后仍然存在）
- ✅ 随时干预（密码，确认）
- ✅ 与 AI 对话的干净分离
## 支持的终端
| 终端 | 平台 | 状态 |
|----------|----------|--------|
| **iTerm2** | macOS | ✅ 完整支持（原生 Python API） |
| **tmux** | macOS, Linux, WSL | ✅ 完整支持 |
| **WezTerm** | macOS, Linux, Windows | ✅ 完整支持 |
| **Kitty** | macOS, Linux | ✅ 完整支持 |
| **Ghostty** | macOS | ✅ 完整支持（`ghostty_tmux` 混合：原生 AppleScript 分割 + 每表面 tmux 引擎，Ghostty 1.3+） |
| **maquake** | macOS | ✅ 完整支持（通过 Unix 套接字下拉终端） |
| **VS Code / Cursor** | macOS, Linux, Windows | ✅ 完整支持（通过扩展，Unix-套接字桥接） |
| **JetBrains IDEs** | macOS, Linux, Windows | ✅ 完整支持（通过插件，Unix-套接字桥接） |
## 功能
- **多后端** - 与 iTerm2、tmux、WezTerm、Kitty、Ghostty、maquake、VS Code/Cursor 或 JetBrains IDEs 配合使用
- **侧边终端** - AI 命令在可见的终端窗格中运行
- **您始终在控制中** - 看到所有内容，随时干预
- **会话持久性** - 终端在 AI 会话重启后仍然存在
- **TUI 支持** - 箭头键，F1-F12，Ctrl+C/D/Z 用于交互式应用程序
- **焦点管理** - 可选地在操作后返回焦点
## 安装
### 使用 uvx（推荐）
```bash
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 运行 sideshell
uvx sideshell-mcp
```
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`)：
```json
{
"mcpServers": {
"sideshell": {
"command": "uvx",
"args": ["sideshell-mcp"]
}
}
}
```
### 使用 pipx
```bash
pipx install sideshell-mcp
sideshell-mcp
```
### 后端选择
```bash
# 自动检测（默认）
uvx sideshell-mcp
# 强制指定后端
uvx sideshell-mcp --backend=tmux
uvx sideshell-mcp --backend=iterm2
```
## 可用工具（17）
| 工具 | 描述 |
|------|-------------|
| `execute` | 执行命令（支持 `wait`、`timeout`、`targets` 进行广播） |
| `read` | 读取终端输出 |
| `control-char` | 发送特殊键：Ctrl+C/D/Z，箭头键，F1-F12，Home/End，PageUp/Down |
| `list` | 列出所有窗口/标签/会话 |
| `split` | 水平或垂直分割窗格 |
| `new-window` | 创建新窗口 |
| `new-tab` | 创建新标签 |
| `new-session` | 智能会话创建（如果窗口存在则分割） |
| `focus` | 聚焦特定会话 |
| `close-session` | 关闭终端会话 |
| `set-appearance` | 设置标签标题、徽章和颜色 |
| `get-terminal-state` | 获取详细的终端状态 |
| `list-color-presets` | 列出可用的颜色预设 |
| `set-color-preset` | 应用颜色预设 |
| `show-alert` | 显示警报对话框 |
| `clear` | 清除终端屏幕 |
| `paste` | 将文本粘贴到终端 |
## MCP 资源
| 资源 | 描述 |
|----------|-------------|
| `sideshell://sessions` | 列出所有终端会话 |
| `sideshell://capabilities` | 后端功能和系统信息 |
| `sideshell://sessions/{id}` | 会话详细信息 |
| `sideshell://sessions/{id}/screen` | 屏幕内容 |
## 先决条件
### iTerm2（macOS）
1. 打开 iTerm2 → 首选项 → 常规 → Magic
2. 启用“启用 Python API”
3. 重启 iTerm2
### tmux
```bash
# macOS
brew install tmux
# Ubuntu/Debian
sudo apt install tmux
```
### WezTerm
从 [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
```
## 架构
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐
│ MCP 客户端 │────▶│ sideshell │────▶│ 终端 │
│ （Claude） │ │ MCP 服务器 │ │ 后端 │
└─────────────┘ └──────────────┘ └─────────────┘
│
┌───────┴────────────┐
│ 后端 │
├────────────────────┤
│ • iTerm2 │
│ • tmux │
│ • WezTerm │
│ • Kitty │
│ • Ghostty │
│ • maquake │
│ • VS Code / Cursor │
│ • JetBrains IDEs │
└────────────────────┘
```
VS Code/Cursor 和 JetBrains 后端通过本地 Unix 域套接字 (`~/.sideshell/<ide>.sock`) 使用换行分隔的 JSON-RPC 2.0 和令牌握手与它们的 IDE 扩展/插件通信。
## 开发
```bash
git clone https://github.com/menemy/sideshell
cd sideshell
uv pip install -e ".[dev]"
# 运行测试
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
# 格式化和检查代码
ruff format .
ruff check . --fix
```
## 要求
- Python 3.11+
- 以下之一：iTerm2、tmux、WezTerm、Kitty、Ghostty、maquake、VS Code/Cursor 或 JetBrains IDE
## 许可证
MIT
## 贡献
1. 分叉仓库
2. 创建功能分支
3. 为新功能添加测试
4. 确保所有测试通过
5. 提交拉取请求
