agterm
一款原生 macOS 终端，以命名工作区组织会话，并通过完整的控制 API 和 agtermctl 命令行让脚本与编码 Agent 精确驱动每一个会话。
- Star 数
- ★ 697
- 最近更新
- 今天
- License
- MIT
- 主语言
- Swift
- FA 评分
- 75/100 · 表现良好
30 秒速览
- 运行形态
- 可在哪里用
- 平台专用Codex · Claude Code
- 费用
- 免费，无需付费服务
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 并行运行多个编码 Agent 的开发者：每个 Agent 占一个命名会话并上报状态，一眼看出哪个被阻塞或已完成，无需逐个切换标签页。
- 不适合
- 使用 Intel Mac、Linux 或 Windows 的用户，官方仅支持 Apple Silicon 与 macOS 14+
- 需要开箱即用完整功能、不愿写 keymap.conf 或脚本的用户
- 依赖 zsh 以外登录 shell 且要求会话实时恢复的团队
- 源码审查
- 75/100 · 表现良好
这个 Agent 能做什么，适合哪些场景？
agterm 是一款专为 Apple Silicon Mac 打造的原生 macOS 终端，采用刻意精简的界面设计，核心模型只有一层：窗口包含命名工作区，工作区包含命名会话。它内置 agtermctl 命令行工具，通过本地 Unix socket 驱动几乎所有功能，包括创建会话、注入按键、回读终端文本、在浮层中运行程序、设置状态标记、移动窗口等。它嵌入 Ghostty 的 libghostty 引擎负责真正的终端渲染、VT 解析和 shell I/O，模型、侧边栏、持久化和控制通道则是 agterm 自身的代码。针对同时运行多个编码 Agent 的场景，每个 Agent 在自己的会话中报告 active、blocked 或 completed 状态，侧边栏一眼可见哪个 Agent 需要人工介入。可安装的 Agent Skill 教会 Claude Code 或 Codex 整套控制模型，使 Agent 能自主搭建布局、运行浮层并内联显示图片，而这并非特殊的 Agent 模式，而是与普通脚本相同的控制接口。
agterm 将 shell 会话组织在命名工作区下，支持会话的水平和垂直分屏、临时 scratch 终端，以及在全屏或浮动浮层（overlay）中运行 yazi、git UI 等程序而不干扰底层 shell。agtermctl 通过本地 socket 提供完整控制面：agtermctl workspace new demo 创建工作区，agtermctl session new --workspace "$ws" --cwd "$PWD" 创建会话，session split on --axis horizontal 分屏，session type $'pwd\n' --target "$sid" 向会话注入按键，session text --lines 10 回读终端缓冲区，session status blocked 设置侧边栏状态图标，pick 和 ask 打开原生选择器/对话框，tree -- 输出整个模型的状态。恢复模式有三种：用新 shell 恢复保存的布局、重跑退出时捕获的命令，或通过 zmx 让实际进程保持存活（要求 zsh 为登录 shell）。Agent 状态钩子（Help 菜单安装）支持 Claude Code、Codex、Pi、OpenCode 等 Agent 将自身状态上报到会话行；keymap.conf 中的一行 command 可把任意 shell 命令绑定到快捷键。
- 并行运行多个编码 Agent 的开发者：每个 Agent 占一个命名会话并上报状态，一眼看出哪个被阻塞或已完成，无需逐个切换标签页。
- 用 Claude Code 或 Codex 工作的工程师：安装 Agent Skill 后，Agent 可以自己创建工作区、分屏、运行浮层程序并内联显示图片，无需人工解释 API。
- 需要可脚本化终端的自动化爱好者：用 agtermctl 写脚本搭建布局、驱动非当前会话、回读输出并根据退出状态做出反应。
- 同时处理多个项目的日常用户：用 work/personal 等工作区组织会话，退出后按三种模式之一恢复布局或保持进程存活。
- 喜欢自己定制快捷键的用户：在 keymap.conf 写一行 command，即可把文件管理器或数据库浏览器以浮层形式绑到快捷键上。
如何安装或部署这个 Agent？
agterm 仅支持 Apple Silicon（arm64）、macOS 14 及以上，发行版已签名并经 Apple 公证。Homebrew 安装：brew install --cask umputun/apps/agterm（cask 会同时安装 agtermctl）。或从 GitHub Releases 下载 .dmg，将 agterm.app 拖入 /Applications，再通过 Help ▸ Install Command Line Tool… 安装 agtermctl。Agent Skill 既可从 Help ▸ Install Agent Skill… 安装，也可作为插件安装（两条路只选其一）：claude plugin marketplace add umputun/agterm && claude plugin install agterm@agterm，或 codex plugin marketplace add umputun/agterm && codex plugin add agterm@agterm。Agent 状态钩子从 Help ▸ Install Agent Status Hooks… 安装。
如何使用这个 Agent？
启动 agterm 后，会话按命名工作区组织，可通过名称、最近使用或键盘切换。典型脚本流程：ws=$(agtermctl workspace new demo) 创建工作区；sid=$(agtermctl session new --workspace "$ws" --cwd "$PWD" --no-select) 创建会话；agtermctl session split on --axis horizontal --target "$sid" 分屏；agtermctl session type $'pwd\n' --target "$sid" 注入按键；agtermctl session text --target "$sid" --lines 10 回读输出（注意 session type 仅在按键入队后返回，随后的读取存在竞态）；agtermctl session status blocked --target "$sid" 设置状态图标；agtermctl tree -- 导出全量状态。自定义通过 keymap.conf 中的 command 行绑定快捷键，恢复策略在 Settings ▸ General ▸ Restore sessions 中选择，或用 agtermctl restore mode 直接读写。所有命令的完整参考见 agterm.com/commands。
这个 Agent 有哪些优点和局限？
- 完整的本地 socket 控制 API：脚本和 Agent 可以创建会话、注入输入、回读终端缓冲区、读取状态，这是多数终端不具备的可编程能力。
- 为多 Agent 并行场景专门设计的状态上报：active/blocked/completed 直接显示在侧边栏会话行，配合 Claude Code、Codex、Pi、OpenCode 等钩子即装即用。
- 嵌入成熟的 libghostty 引擎处理渲染和 VT 解析，同时保持精简的功能面，不做深层 Agent 集成，把扩展权交给用户和脚本。
- 三种恢复模式（含基于 zmx 的真进程保活），重启后会话进程可继续存活并重新附着。
- 平台绑定严格：仅支持 Apple Silicon Mac 和 macOS 14+，Linux 和 Windows 需依赖第三方移植或独立仿制项目。
- Live 会话恢复要求 zsh 作为 macOS 登录 shell，且需重启 agterm 才生效；硬断电或强制退出无法捕获命令。
- 会话恢复有明确的能力边界：内联图片、OSC 133 提示符标记、调色板改动和超链接元数据在重新附着后不会保留。
- 扩展依赖自己动手：超出默认功能需要写 keymap.conf 的 command 行或脚本，对不愿定制的用户是额外成本。
这个 Agent 与同类方案有什么区别？
README 明确将 agterm 与分页签终端对比（后者在多 Agent 长会话下容易失控），并列出了生态中的相关项目：melonamin/agterm-linux 是基于 agtermCore 的 Linux/GTK4 移植，jokius/rook 是走向不同方向的 macOS 原生分支，yeroo/agwinterm 是面向 Windows 的独立重写。agterm 的差异化在于：不追求功能堆叠，而是提供完整控制 API 让用户和 Agent 自行扩展。
与相关度最高的同类 agent 并排比较关键指标。
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示依赖按修订号钉死并从上游源码构建（scripts/setup.sh 中的 GHOSTTY_REV/ZMX_REV），CI 逐项钉定并验证 Release 权限集、检查嵌套助手不带应用权限，说明权限最小化有实质机制，故 least_privilege、dependency_security 给分较高；Attribution 一节详细说明 libghostty、macterm 桥接文件与原创代码的边界，source_attribution 给满分。但控制通道是本地 unix socket，README 未说明任何认证、授权或访问控制，任何本机进程都可能创建会话、注入按键并读回终端缓冲区，用户确认仅体现为可选的 ask/pick 提示，故 user_confirmation 扣分；敏感数据处理、socket 对端的权限边界完全未提及。restore-denylist.conf 与恢复排除规则提供了对自动重跑命令的约束与回退，但 denylist 文件本身不在证据内，rollback 只能给中间分。
README、CI 与测试配置相互一致：CI 读取 setup.sh 的钉定修订并缓存，测试、lint、cookbook 检查均在 CI 中执行，self_consistency 尚可；依赖钉定加上可复现构建支持 dependency_availability。README 明确承认 session type 与 session text 之间存在竞态、pick/ask 会阻塞，docs/troubleshooting.md 被引用但其内容不在证据内，无法核实错误信息的质量，failure_messages 只给中间分。
受众与场景描述非常清晰：macOS 上并行运行编码代理的开发者，同时保留日常终端用途；'deliberately minimal' 的边界声明明确说明不做什么，capability_boundaries 可给满分；环境适配明确写死 macOS 14+ arm64。命令参考与文档托管在 agterm.com，不在本仓库证据内，trigger_precision 只能按 README 示例评估，给中间分。
文档结构优秀：README 分层清楚，并指向 docs、命令参考、cookbook、CONTRIBUTING、ARCHITECTURE 与 troubleshooting；安装说明覆盖 Homebrew、DMG、CLI 安装、技能与钩子安装且警告不要双重安装；cookbook 有 CI 强制的目录/索引一致性与固定标题结构，examples_and_fashion、information_architecture、install_notes、known_limitations（恢复的三个排除项、重建屏幕不保留的内容均如实列出）、license（MIT，含 LICENSE 文件）均有据可给高分。但证据内没有 CHANGELOG 或版本文件，versioning_changelog 只能扣到 1；维护责任仅有 Issues/Discussions 指针与独立第三方生态的明确免责声明，naming_stability 缺少长期承诺证据。
输出可用性有据：tree -- 转储全部模型、ask 返回按钮、session text 按行读回、overlay 返回退出码；marginal_value 突出：多代理会话的状态标记与可脚本化布局是普通终端不具备的明确差异化。但 CLI 一次调用一命令、无流式输出，代理循环需反复轮询，成本收益只能给中间分。
README 将事实与动机区分良好，恢复机制的边界条件写得具体而非营销化，fact_inference_separation 可给满分；README 的可验证主张大多指向仓库外（agterm.com、screenshots、denylist 文件），静态证据只能部分追查，claim_traceability 扣分；CI 文件与 README 关于技能文件、权限集、钉定依赖的陈述相互印证，但因缺少实际源码文件，corroboration 只能是部分的。
- 控制 socket 未声明任何认证或访问控制：本机任意进程可能注入按键并读回终端内容，处理敏感信息的会话应避免在共享机器上使用。
- session type 与 session text 存在文档承认的竞态，脚本化代理需自行处理轮询与同步。
- 技能安装有两条途径（插件市场与 Help 菜单），仓库警告双重安装行为未定义，应只选其一。
- Live 恢复依赖 zmx 与 zsh 登录 shell，重建屏幕不保留内联图片、提示标记与超链接元数据。
- 静态评审未见 CHANGELOG 与控制服务端源码，socket 安全与版本策略未经核实。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
v0.38.1 Version 0.38.1
发布说明摘录
Improved - session overlay open and session overlay resize take --width and --height in points, each replacing --size-percent on its own axis, so a local floating program or page keeps its percent width and fits its height to what it shows. A --js page sizes itself through agterm.request('session.overlay.resize', ...). A point-sized axis is capped at 80% of the session, and tree reports the laid-out size as overlayWidth/overlayHeight #798 @umputun --- …在 GitHub 查看 ↗ -
v0.38.0 Version 0.38.0
发布说明摘录
New Features - HTML pages on a remote session. A page opened with session overlay open --html or --url on a session another Mac presents now opens on that Mac, the way a program overlay already does. It used to be refused. A URL page loads on the presenting Mac with that Mac's --persistent storage, and a loopback URL is refused there because it names a server on the origin. A file page and the files its --cwd grants are served from the origin over ssh, and its data-agterm tags and agterm.request calls run on the origin. result --page, --block, close, resize, `reloa …在 GitHub 查看 ↗ -
v0.37.0 Version 0.37.0
发布说明摘录
New Features - File ▸ Open Recent from the CLI. agtermctl recent list prints the Open Recent entries newest first, recent open [ID] [--window W] reopens one by id or prefix, the newest with no id, through the menu's own restore path, and recent clear empties the list. A reopened session keeps its id, split, flag, context and restore pins, which session new could not bring back. It goes to --window or the frontmost window unless another window already holds its session or workspace, and the window is not raised. --json carries closedAt, the workspace id and the session id …在 GitHub 查看 ↗
常见问题
它支持 Intel Mac 或 Linux/Windows 吗？
Agent 状态和 Skill 是不是一种特殊的 Agent 专属模式？
Live 会话恢复有什么前提和限制？
它是免费的吗？采用什么许可？
输出是实时流式的吗？脚本怎么读取会话内容？
agtermctl session text --lines N 按需读取缓冲区；另外 session type 在按键入队后即返回，紧随其后的读取需要考虑与 shell 的竞态。