Matrix Co TUI 使用手册

01 · REQUIREMENTS

运行要求

Apple Silicon Mac，macOS 11 或更高版本。
Homebrew。Intel 版本尚未发布。
安装并登录你准备使用的第三方 CLI，例如 Codex、Claude Code、Cursor、Kimi 或 ZCode。
Claude SDK 与实验性 Cursor SDK transport 需要 Node.js 18 或更高版本。其他路径不依赖 Node.js。

Matrix Co 不提供模型账号，也不替代第三方 CLI 的登录。它负责房间、路由、状态、审批和本地持久化。

02 · INSTALL

安装与升级

Homebrew 安装

brew tap moonaries90/matrix-co https://github.com/moonaries90/matrix-co-releases.git
brew install moonaries90/matrix-co/matrix-co

安装完成后检查两个入口：

matrix --help
matrixctl agent --help

升级

brew update
brew upgrade matrix-co

卸载

brew uninstall matrix-co
brew untap moonaries90/matrix-co

卸载程序不会删除 ~/.matrix-co 中的房间状态、会话记录和日志。确认不再需要这些数据后再手动清理。

03 · FIRST RUN

先用 Echo 检查本机链路

Echo 不连接模型，也不需要账号。先用它确认 daemon、TUI、profile 和本地状态可以工作。

matrixctl agent define echo-smoke --kind echo
matrix --invite echo-smoke

进入 TUI 后输入一行文字并按 Enter。
确认右侧成员列表出现 echo-smoke。
输入 /agents 查看在线成员。
输入 /quit 退出。

matrix 会启动本地 matrixd，连接 TUI，并在退出时清理它本次启动的 daemon。已有可用 daemon 时，启动器会复用它。

04 · AGENT PROFILES

配置 Agent

Profile 保存名称、Agent 类型、transport、SOUL、模型和默认权限。工作目录属于每次启动的会话，不写入 Profile。

Codex App Server

matrixctl agent define planner \
  --kind codex \
  --transport app-server \
  --soul architect

Claude Agent SDK

matrixctl agent define reviewer \
  --kind claude \
  --transport claude-sdk \
  --soul reviewer

Cursor ACP

matrixctl agent define cursor-builder \
  --kind cursor \
  --transport acp \
  --soul builder

Kimi ACP

matrixctl agent define kimi-builder \
  --kind kimi \
  --transport acp \
  --soul builder

ZCode Protocol

matrixctl agent define zcode-builder \
  --kind zcode \
  --transport zcode-protocol \
  --soul builder

Cursor SDK transport 仍处于实验阶段，工具执行受限。常规 Cursor 使用请选择 ACP。

查看和删除 Profile

matrixctl agent list
matrixctl agent show planner
matrixctl agent remove planner

05 · ROOMS

进入房间并指定工作目录

cd ~/projects/my-app
matrix --room dev --workspace "$PWD" --invite planner,reviewer

不传 --workspace 时，Matrix Co 使用你执行 matrix 的当前目录。一个 Profile 可以加入多个房间，每个房间会创建独立的运行时 Agent。

进入 TUI 后可以继续邀请或移除成员：

/invite cursor-builder
/kick reviewer
/agents
/status

06 · ROUTING

Host 与 Free 模式

Host

Host 是默认模式。Moderator 接收普通输入并负责组织后续工作。指定 Moderator：

/mode host planner

你仍可使用 /turn 明确启动某个 Agent 的回合。

Free · active

普通输入发送给当前 active executor。/target 设置这个持续生效的目标。

/mode free selector=active
/target cursor-builder

Free · Agent-led

命令中的 wire 名称是 broadcast。普通输入只进入房间，不自动启动 Agent。使用 @agent 或 Agent 的 matrix_delegate 发起后续回合。

/mode free selector=broadcast
@planner 拆分这个需求

Free · round-robin

/mode free selector=round-robin agents=planner,cursor-builder budget=6

budget 只限制没有 mention 的 Free 定向回合。显式 @agent 不消耗该预算。

/target 设置持续目标；/route 只发送一次；/goal target 设置 auto-run 目标。三者用途不同。

07 · COMMANDS

常用 TUI 命令

命令	作用
`/help`	显示命令和键盘帮助。
`/agents`	刷新并显示房间成员。
`/target [agent]`	查看或设置 Free active executor。
`/route <agent> <message>`	在 Free 模式向一个 Agent 发送一次定向消息。
`/turn <agent> <input>`	明确启动一个 Agent 回合。
`/interrupt <agent>`	中断当前回合。
`/tools on\|off`	显示或隐藏工具与 token 事件。
`/context [agent]`	查看房间或 Agent 上下文。
`/clear [agent...]`	清空所选 Agent 会话并写入恢复标记。
`/compact [agent...]`	请求 Provider 原生压缩；只对已接线的 Adapter 生效。
`/resume [profile...]`	打开房间与历史会话选择器。
`/quit`	退出 TUI。

08 · PERMISSIONS

权限模式

模式	行为
`default`	每个 permission request 都进入审批面板。
`accept-edits`	自动允许高置信度文件写入、编辑和 patch；命令、网络、MCP 与未知类型仍询问。
`session-allow`	第一次询问。选择“本会话允许”后，同房间内匹配请求自动通过。
`yolo`	自动允许带 requestId 的类型化权限请求。它不会替你回答问题或 request-user-input。

给 Profile 设置默认模式：

matrixctl agent define cursor-builder \
  --kind cursor \
  --transport acp \
  --soul builder \
  --permission-mode accept-edits

在当前房间设置覆盖：

/permission
/permission accept-edits
/permission cursor-builder default
/permission cursor-builder inherit

优先级为：房间内 Agent 覆盖、房间覆盖、Agent 默认。审批面板打开时，使用 1/2/3 或 a/s/d 选择允许一次、本会话允许或拒绝。

09 · GOALS

目标与 auto-run

/goal 发布 TUI 0.0.1
/goal target planner
/goal auto
/goal resume
/goal complete

/goal <objective> 创建或替换房间目标。/goal target 固定自动执行目标；/goal auto 刷新状态；达到最大步数后使用 /goal resume 重置计数并继续。

当前 Codex app-server、Claude SDK 和 ZCode Profile 可以作为 auto-run 目标。Cursor ACP/SDK、Kimi 和 Echo 可以加入房间，但不能作为目标自动调度。

10 · RESUME

恢复房间与 Provider 会话

/resume
/resume planner
/resume --all

选择器先显示房间，再显示历史会话。Enter 进入房间或查看一段历史；Left/Right 展开和折叠；Esc 关闭。历史文本只回放到人类窗口，不会重新注入 Agent prompt。Provider 原生会话由各 Adapter 使用持久化 session pointer 恢复。

11 · KEYBOARD

键盘操作

`Enter`	发送输入或确认面板选项。
`Shift/Alt+Enter`	在输入框换行。
`Esc`	优先中断活跃回合；无活跃回合时关闭面板。
`Ctrl-C`	清空草稿；短时间内再次按下退出。
`Tab / Shift-Tab`	选择工具、diff 和详情块。
`Ctrl-T`	展开或折叠当前块。
`Left / Right`	输入框为空时折叠、展开或切换审批请求。
`Up / Down`	输入框非空时移动行；否则移动面板选择或滚动。

12 · STATE AND LOGS

数据与日志

`~/.matrix-co/state.sqlite`	房间、Profile、路由状态和 Provider session pointer。
`~/.matrix-co/sessions/`	按日期保存的 append-only JSONL 会话记录。
`~/.matrix-co/logs/matrixd.log`	Daemon 启动与协议错误。
`~/.matrix-co/logs/matrix-tui.log`	TUI 启动、终端和连接错误。
`~/.matrix-co/souls/`	本地 SOUL prompt 文件。

需要隔离测试时，指定另一份状态目录：

MATRIX_CO_HOME=/tmp/matrix-co-test matrix --room scratch --invite echo-smoke

13 · TROUBLESHOOTING

排障顺序

命令不存在

brew list --versions matrix-co
brew --prefix matrix-co
command -v matrix

Agent 无法启动

先确认第三方 CLI 能独立运行，再检查 Profile 的 kind 和 transport。

command -v codex
codex --version
matrixctl agent show planner

Daemon 或 TUI 退出

tail -n 80 ~/.matrix-co/logs/matrixd.log
tail -n 80 ~/.matrix-co/logs/matrix-tui.log

Socket 残留

只有确认没有 Matrix Co 进程正在使用默认 socket 后，才删除残留文件并重试：

rm -f /tmp/matrix-co.sock
matrix --room demo

重新安装

brew reinstall matrix-co
matrix --help

提交问题时请附上 Matrix Co 版本、macOS 版本、所用 Agent/transport，以及两份日志中与失败时间相邻的内容。不要上传 token、账号信息或完整私有会话。

终端版使用手册