┌─ PTY-Agent ─────────────────────────────────────────────────────────────────┐
│ $ app.py exec dbg -c "cdb.exe myapp.exe" -t "0:000" --timeout 5             │
│                                                                             │
│ ─────────────────────────────── matched ───────────────────────────────     │
│ Microsoft (R) Windows Debugger Version 10.0.11451.4                         │
│ 0:000>                                                                      │
│ ───────────────────────────────────────────────────────────────────────     │
│ [exec · matched · 0.42s]  dbg  running  pty                                 │
└─────────────────────────────────────────────────────────────────────────────┘

click here to view demo video

Features

• ✨ Shell · CUI · TUI — use terminals like a human: start sessions, send keys, wait for prompts, read screens
• ✨ Cross-platform — Windows / Linux, macOS coming soon
• ✨ Real-time Web monitoring — watch and control every terminal session, collaborate live
• ✨ Sandbox — restrict AI operations to the workspace, prevent accidental damage
• ✨ Plugin system — extend functionality freely
• AI secondary analysis — pipe long logs, large outputs, even rendered terminal screenshots to another AI
• Sub-agents — launch OpenCode / Claude Code / ... across harnesses, managed centrally
• Workflow orchestration — multi-session DAG choreography
• Remote terminal access — SSH-like experience

Why PTY-Agent?

Traditional agents can't run ssh, gdb, cdb, or any program that asks you a question.

Quick overview

Installation

Compilation is required. Download the pre-built Release package, or clone and run build.py.

Architecture

graph LR
    A["AI Agent"] -->|"PTY-Agent &lt;cmd&gt;"| B["CLI<br/>src/cli · src/client"]
    B -->|"TCP · NDJSON<br/>Token+HMAC / TLS+Ed25519"| C["Daemon<br/>src/daemon"]
    C --> D["Session<br/>src/session"]
    D --> E["PTY backend<br/>src/pty"]
    E -->|"ConPTY / openpty"| F["Real program"]
    F --> G["Reader thread → output buffer"]
    G --> H["Terminal model wezterm-term<br/>VT parse → snapshot/diff/SVG"]
    H --> I["Trigger detection<br/>regex · idle · crash · GUI"]
    I -->|"Response JSON"| B
    C --> J["Web · workflow · plugins"]

Configuration

Config files are in config/, overridable via env vars PTY_AGENT_<KEY>, restart required.

CLI ──token──▶ 127.0.0.1:10520    (local dev, strong auth)
CLI ──basic──▶ 0.0.0.0  :10521    (local dev, weak auth)
CLI ──tls────▶ 0.0.0.0  :18767    (remote access)
Browser ──────▶ 127.0.0.1:18766    (Web UI)

Note: disable SINGLE_INSTANCE if running two PTY-Agent instances on one machine.

Docs

License

Except for src\web\static\ and web_rime\, everything else is MIT.

src\web\static\ and web_rime\ use AGPL-3.0 license.

feature

• ✨ 轻松操作Shell · CUI · TUI —— 真正像人一样使用终端：起会话、发按键、等提示符、看屏幕 ✨
• ✨ Windows / Linux 跨平台 —— 将来还会支持 MacOS ✨
• ✨ 实时 Web 监控 —— 实时接管每一个终端会话，也可以一起协作 ✨
• ✨ 沙箱系统 —— 启用后，AI 只在工作区工作，根本上防止删盘
• ✨ 强大的插件系统 -- 需要什么功能，随意扩展
• AI 二次分析，长上下文一步就好 —— 把长日志、大段输出、甚至渲染后的终端图片直接交给另一个 AI，一步返回结论
• 子 Agent：跨 Harness 启动，统一管理 —— OpenCode / Claude Code / ... 支持扩展
• workflow 多会话编排
• 跨机访问终端 —— 支持 ssh 般的体验

为什么需要它

常规 Agent 跑不了 ssh、跑不了 gdb、跑不了 cdb，也跑不了任何会反问你一句的程序

能力速览

安装

该 Skill 需要编译，请下载 Release 的预编译包，或者 clone 之后使用build.py编译

它是怎么工作的

graph LR
    A["AI Agent"] -->|"PTY-Agent &lt;cmd&gt;"| B["CLI<br/>src/cli · src/client"]
    B -->|"TCP · NDJSON<br/>Token+HMAC / TLS+Ed25519"| C["守护进程<br/>src/daemon"]
    C --> D["会话管理<br/>src/session"]
    D --> E["PTY 后端<br/>src/pty"]
    E -->|"ConPTY / openpty"| F["真实程序"]
    F --> G["读者线程 → 输出缓冲"]
    G --> H["终端模型 wezterm-term<br/>VT 解析 → 快照/diff/SVG"]
    H --> I["触发检测<br/>正则·静默·崩溃·GUI"]
    I -->|"响应 JSON"| B
    C --> J["Web · workflow · 插件"]

配置

配置集中在 config/，可用环境变量 PTY_AGENT_<KEY> 覆写，改完需重启进程

CLI ──token──▶ 127.0.0.1:10520    (本地开发强验证)
CLI ──basic──▶ 0.0.0.0  :10521    (本地开发弱验证，没问题开这一个就好)
CLI ──tls────▶ 0.0.0.0  :18767    (提供跨机访问)
浏览器 ───────▶ 127.0.0.1:18766    (Web)

注意：如果一台设备要开启两个 PTY-Agent，请关闭单实例锁SINGLE_INSTANCE

文档

许可证

除了src\web\static\、web_rime\，其他都为 MIT

src\web\static\、web_rime\使用 AGPL-3.0 license

https://github.com/user-attachments/assets/5d8402e8-5fa6-4c7e-91b0-124a2ea953e4