agterm：macOS 终端与 AI Agent 控制台

项目简介

agterm 是一款原生 macOS 终端，界面刻意保持精简，同时提供完整的控制 API。它把 shell 组织成命名 workspace 下的 session，这套层级就是全部模型，不需要先学别的就能用起来。它承载的一切也都是脚本可以操作的对象：随附的 agtermctl 能创建 session、向其输入、读回某个 pane 的文本、在 overlay 中运行程序并取得退出码、设置 session 的状态图标、打开原生选择器、移动窗口，并通过本地 socket 读回这些状态。

它的动机很具体：同时跑多个 coding agent，意味着许多长驻会话各自推进，普通标签页终端很快就会跟丢。每个 agent 在命名 session 里工作并上报自己是进行中、被阻塞还是已完成，你一眼就能看出哪个需要处理。终端渲染、VT 解析和 shell I/O 部分内嵌了 Ghostty 的引擎（libghostty），其余都是 agterm 自己的实现。

主要功能

• Workspaces：session 按「work」「personal」之类的命名 workspace 分组，可按名称、按最近使用或从键盘直达某个 session。
• Control API 与 CLI：agtermctl 通过本地 socket 几乎能操控全部功能，脚本或 agent 可以自己搭建布局、驱动终端，并从它工作的 session 发出通知。
• 分屏、scratch 与 overlay：把 session 拆成左右或上下两个 shell，在它上面打开 scratch 终端，或在不打扰底层 shell 的情况下于全屏 / 浮动 overlay 中运行程序。
• Companions：把日志 tail、watcher、第二个 shell 或 HTML 页面固定在某个 session 下方的侧边栏里，随它移动、折叠和关闭；Duplicate as Companion 可复制分屏布局再起一份。
• Live sessions：退出、更新或重启 agterm 时，主 pane 和分屏 pane 里的进程继续运行（包括正在轮次中的 agent），下次启动重新挂接并恢复文本与 TUI 状态。
• Remote sessions：通过 File ▸ Attach Remote… 或 agtermctl zmx attach --companions，把另一台 Mac 上运行的 session 作为侧边栏一行打开，分屏和 companions 一并带过来。
• Agent skill 与 Agent status：Help ▸ Install Agent Skill… 可安装技能，教会 Claude Code 或 Codex 控制模型和 agtermctl 命令；Help ▸ Install Agent Status Hooks… 为 Claude Code、Codex、Pi、OpenCode 等安装状态钩子，把 agent 状态显示在 session 行上。

更多界面截图见 docs/screenshots：dashboard 集中查看多个 session 的实时输出，浮动 overlay 中运行 yazi 文件管理器，以及不同配色主题的左右分屏。

安装与使用

预编译版本面向 Apple Silicon（arm64）Mac，macOS 14 或更高版本，已用 Developer ID 证书签名并经 Apple 公证，Gatekeeper 可直接打开。

Homebrew：

brew install --cask umputun/apps/agterm

也可以从 releases 页面 下载最新 .dmg，打开后把 agterm.app 拖进 /Applications。

Homebrew cask 会一并安装 agtermctl；用 DMG 安装的话，通过 Help ▸ Install Command Line Tool… 把它加入 PATH。

agtermctl 每次调用执行一条命令，终端输出不会流式推送，需要时用 session text 读取缓冲区：

ws=$(agtermctl workspace new demo)
sid=$(agtermctl session new --workspace "$ws" --cwd "$PWD" --no-select)
agtermctl session type $'pwd\n' --target "$sid"
agtermctl session text --target "$sid" --lines 10
agtermctl tree --json

agent skill 也可以作为插件安装：

claude plugin marketplace add umputun/agterm
claude plugin install agterm@agterm

完整命令见 agterm.com/commands，使用指南见 agterm.com/docs，示例脚本见 cookbook。

注意事项

• Live sessions 需在重启 agterm 后生效，且要求 macOS 登录 shell 为 zsh 或 fish。
• Remote sessions 要求对端 Mac 以 Live sessions 模式运行 agterm，并通过基于密钥的 ssh 连接；对端机器需在 remotes.conf 中命名。
• agent skill 只能在「菜单安装」与「插件安装」中二选一，装两份会导致 agent 选用哪一份不确定。
• session type 在按键入队后即返回，紧接着执行 session text 会与 shell 产生竞争；pick 和 ask 会阻塞直到有人回答。
• 常见问题与日志位置见 docs/troubleshooting.md。

---

本作品整理自 GitHub 开源项目 umputun/agterm，原作者 @umputun，许可证 MIT。中文介绍由 AI 根据项目 README 整理，以原仓库为准。