Agent Deck

Agent Deck

[English](./README.en.md) | **简体中文**

本地 Web 控制台，用于管理多个 AI 编码 Agent CLI（`claude`、`opencode`、`openclaw`、`hermes`、`codex`）和普通 shell 终端。真实 PTY 终端、刷新浏览器会话不丢、Persona 预设一键拉起，并内置文件浏览器与 Git 状态视图。

界面预览

**终端视图** — 左侧边栏包含快捷启动、Persona 预设和实时会话看板；主区域是完整的 PTY 终端，ANSI 颜色与交互式 TUI 均可正常渲染：


**文件浏览器** — 无需离开控制台即可浏览当前会话工作目录的文件树（自动跳过 `node_modules`、`.git`、`dist`、`build`）：


点击文件即可只读预览内容：


**Git 视图** — 列出工作区改动，并标注修改 / 新增 / 删除 / 未跟踪状态：


点击任意文件查看该文件相对 `HEAD` 的完整 diff：


**启动对话框** — 选择 Persona 后，可在启动前覆盖工作目录、模型和标题，也可挑一条历史会话继续：


安装

**环境要求**

• macOS、Linux 或 Windows 10 1809+ / Windows 11
• Node.js ≥ 18
• 至少安装并登录一个受支持的 Agent CLI，且在 PATH 中：claude、opencode、openclaw、hermes 或 codex。控制台会自动检测装了哪些，只显示实际存在的。
• 仅 Linux 需要： node-pty 的 C/C++ 工具链（build-essential + python3）—— node-pty 为 macOS 和 Windows 提供预编译二进制，但不提供 Linux 的，因此 Linux 上需从源码编译。macOS 仅在触发编译时才需要 xcode-select --install。

**一键安装**

npm run setup

安装 `server/` 与 `web/` 依赖、按需修正 node-pty `spawn-helper` 可执行权限（macOS）、构建前端。

**启动**

# 生产模式：单端口同时提供 UI 与 WebSocket
npm start                   # http://127.0.0.1:4173

# 开发模式：Vite HMR + 后端热重载
npm run dev                 # http://127.0.0.1:5173

所有脚本都是纯 Node 实现，在 bash / zsh / cmd.exe / PowerShell 里行为一致。

环境变量：`PORT`（默认 4173）、`HOST`（默认 127.0.0.1）、`SCROLLBACK_BYTES`、`IDLE_AFTER_MS`、`CONTROL_APP_DATA`（personas.json 存放目录）、`REAP_EXITED_AFTER_MS`。

卸载

不写入任何全局位置，所有内容都在本目录内。

用 Ctrl-C 停掉服务，然后删掉整个目录即可。角色数据在 `data/personas.json`（若设置过 `CONTROL_APP_DATA` 则在该目录）。

如果还有残留进程占着端口：

# macOS / Linux
lsof -ti tcp:4173 -sTCP:LISTEN | xargs kill

# Windows
netstat -ano | findstr :4173     # 最后一列是 PID
taskkill /PID  /F

功能

• 多 CLI 实例 — xterm.js +