Repository navigation
CLI Reference zh CN
Agent hooks 和装有 tmag-peers skill 的 agents 会自行找到插件的 binary。在 shell 或脚本中使用 tmag 时,将插件的 bin 目录加入 PATH。
$ tmag list
TARGET PANE AGENT STATE FOR ID CWD
work:1.0 %3 claude blocked (permission) 12s 1787a44e ~/src/api
work:2.0 %7 codex idle 4m 01a19fda ~/src/web
work:3.0 %9 codex unknown - - ~/src/web
- - claude working (background) 2m 5c2e90b1 ~/src/api
$ tmag send 01a19fda --wait "Review the diff in HEAD and list risky changes"
01a19fda idle
$ tmag read 01a19fda --last # the reply that ended its turn
$ tmag read 01a19fda --turns 3 # its last turns: prompts and replies
$ tmag send 01a19fda "The parser moved to internal/parse.go."
sent to 01a19fda (%7) seq 43
$ tmag interrupt 01a1 # stop the running turn
$ tmag request 1787 3f9c2a01b6d4 # what an open request asks
$ tmag answer 1787 3f9c2a01b6d4 allow # or: deny --message "not now"
$ tmag read %3 --lines 40 # recent pane output
$ tmag wait 1787 --for idle # block until the session is idle
$ tmag watch # JSON lines: a snapshot, then every change每行对应一个运行 agent 的 pane,其后列出没有 pane 显示的 sessions,例如 Claude Code 后台 session。Target 可以是 session id 或至少 4 个字符的唯一前缀,也可以是 tmux 所称的 pane:当前 tmux server 上 tmux 接受的任何 target-pane(%N、list 打印的 work:1.0、window 名称、{last}),由 tmux 自己解析;或带 socket 名称(与 tmux -L 相同)或路径的 SERVER:%N,list 打印其他 server 的 pane 时即用此形式。对尚未显示 session 的 pane 执行 wait,会一直等到其中的 agent 显示出 session——刚在其中启动的 agent 从第一次 hook 起就会显示;在此之前,其他命令对该 pane 一律以 unbound 拒绝。
无论 session 在哪里运行,其状态都只由 agent hooks 上报:
| 状态 | 含义 |
|---|---|
working |
一个 turn 正在运行。Kind 为 background 表示 main agent 的 turn 已结束,但 subagents 或后台任务仍在运行。 |
blocked |
Session 等待你回应。Kind 为 permission(tool 或网络批准)或 question(也包括 Pi extension 在 turn 期间打开的任何对话框,以及 oh-my-pi 的 ask tool)。Agent 及其 subagents 的所有未决请求都回应后,才会离开 blocked。请求会在以下情况关闭:发起请求的 agent 已没有该 tool 的调用在运行;该 agent 的调用全部结束或 agent 停止;main agent 的 turn 结束。仍在运行的 subagent 发起的请求可超出 main turn 的生命周期。仅通过 Claude 延迟 permission 通知获知的请求(例如 sandboxed command 的网络请求)既不标识具体调用,也不标识发起的 subagent,由下一次 tool 完成来关闭。 |
idle |
等待下一个 prompt。Turn 失败后 kind 为 error。 |
unknown |
尚无状态上报。Agent 尚未上报(启动、信任对话框、插件未安装),或 tmag 无法证明 pane 对应的 session 时,该 pane 显示 unknown。 |
Session 在 agent 上报 SessionEnd 时结束(Pi 和 oh-my-pi 中为退出或切换到另一个 session 时);若承载它的进程未上报就退出,也视为结束。可选的 last_hook_at 是 session 最近一次 hook 联系的时间,出现在 JSON 和 inspect 中,独立于状态的 since:它保存在 record 中,在没有其他变化时最多每十秒更新一次;event 携带的是变更当时的值,仅有联系不会记录 event。联系时间不能证明状态是新的,也不授予控制权限或清理资格。
Session 与显示它的 panes 是分开的。Claude Code、Pi、oh-my-pi session 和通过 --no-daemon 启动的 Codex 运行在终端自己的 agent 进程中;默认 Codex 在共享 daemon 中运行所有 threads,Claude Code 则通过 supervisor 运行后台 sessions。
后两者的 hooks 来自不属于任何终端的进程,其环境也无法指明当前 pane,因此 tmag 从不信任 $TMUX_PANE。Pane 只有在具备以下证据时才关联 session:
| Evidence | 证明方式 |
|---|---|
process |
Session hooks 是 pane 内 agent 进程的后代。适用于 Claude Code、Pi、oh-my-pi 和 --no-daemon 模式的 Codex。 |
title-id |
Codex pane 的 terminal title 显示了 thread id。 |
关联仅在同一个 agent 进程(pid 和启动时间均相同)继续运行于 pane 时有效;对于 Codex,还要求 title 继续显示该 session。Codex pane 显示该 session 的 subagent 时,关联仍保留,view 为 subagent。
Bell、prefix + A 和 pane 边框只作用于已关联 panes;通过 pane 投递的 send 需要这种关联,而用户在工作 session 中的 prompt 或 agent 的 prompt 会走 session 自己的渠道。tmux 展示无法表达不确定性,因此不会把猜测当作事实。Thread names 来自 prompts,可能重复,不能作为证据。
对于共享 daemon 中的 Codex,需启用一次 thread-id title item:在 Codex 中运行 /title,选择 thread-id,Codex 自己会保存配置。此前 sessions 仍会列出状态,但 Codex panes 显示 unknown。手动编辑时,等效配置为:
[tui]
terminal_title = ["activity", "thread-name", "project-name", "thread-id"]运行 claude attach 的 pane 显示后台 session,但 tmag 无法证明关联,因此 pane 显示 unknown,session 则单独列出。
tmag 为所有 agents 提供相同的控制命令:send 发送 prompt、interrupt 中断 turn、answer 回应请求。每种操作都有相应的 gate,tmag 按 agent、runtime、调用者以及 send 请求的回应方式选择投递渠道:
| Session | send |
interrupt |
answer |
|---|---|---|---|
| Claude Code, terminal | idle 时 pane,working 时 inbox | pane | hook |
| Claude Code, background | inbox(用户的 --wait 不受支持) |
— | hook |
Codex, daemon (runtime: service) |
service | service | service |
Codex, --no-daemon
|
仅 idle 时 pane | pane | — |
| Pi, oh-my-pi, terminal | idle 时 pane,working 时 inbox | pane | — |
| Pi, oh-my-pi,为程序而运行 | — | — | — |
对于 send,用户的 prompt 只在 session idle 时通过 pane 输入,session 工作时则走 session 自己的渠道。Agent 的 prompt 无论状态都走 session 自己的渠道;仅当 session idle 且无法证明其 inbox 时,才回退到 pane。该渠道是 Claude Code 的 inbox、Pi 和 oh-my-pi 中 tmag 的 extension,或 Codex daemon 的 control socket。
Session 的 capabilities 列出存在可用投递渠道的操作。没有渠道可用时,以 unsupported 拒绝。这些能力只由 agent 和 runtime 决定,因此即使 agent 的 inbox 尚不可证明,send 也会出现在列表中;实际 send 仍需要可证明的渠道,或在该 session idle 时使用 pane。每次投递的输出和 event 都通过 via 报告所用渠道。
tmag read ID --last 从 agent 的 transcript 中即时读取并打印该 session 最近一个 turn 结束时的回复:Claude Code 最后一条 assistant message 的文本、Codex turn 结束时的 last_agent_message,或 Pi、oh-my-pi session 文件中的最后一条 assistant message。tmag 不保存这些内容。
它只读取 idle session,否则返回 busy;只读取 hooks 上报的那个 turn,并会等待几秒,让 agent 写入 turn 结束记录。Turn 结束但没有回复,或 transcript 未及时更新时,返回 no_reply。
此操作不需要 pane,因此同样适用于 Codex daemon 和 Claude Code 后台 sessions。--json 会附带 session 和 turn。不带 --last 或 --turns 时,read 打印 pane 的近期文本。
tmag read ID --turns N 打印 session 最近的 1 到 20 个 turn,按时间先后排列,不论 session 处于什么状态。每个 turn 先列出它的 prompts(启动它的那条,以及运行期间到达的那些,每条都以引用格式显示),再列出它的回复。Turn 结束后,回复就是 --last 读到的那条;运行期间是 transcript 目前已写下的内容,Codex 只在 turn 结束时写入。Transcript 表明并非本人发送的 prompt 会标出发送者,例如 (peer) 表示另一个 session 的消息,(task) 表示后台任务的通知。每段文本截断到 16 KiB;一个 turn 的 prompts 只保留第一条和最后九条。tmag 不保存这些内容。--json 给出 session 和 turns,每个 turn 包含 id、prompts(text,被标记时还有 from)和 reply。
tmag send <target> [--wait | --reply] [--timeout D] [--json] [text | -]
默认立即投递 prompt:idle session 会用它启动一个 turn,working session 会在
下一个步骤读到它。--reply 以相同方式投递,并要求接收方完成后通过 tmag reply 回复;这需要 tmag 能证明调用者的 session。--wait 要求一个属于它自己
的 turn:session 必须 idle,prompt 会启动一个 turn,命令会等待该 turn 结束或
阻塞于请求;--timeout(默认 30 分钟)限制这次等待。--wait 与 --reply
不能同时使用。
调用者决定由哪个渠道承载 prompt。用户的 prompt 保留用户的身份:session idle
时,它通过显示该 session 的 pane 输入(证据为 process 或 title-id),且
该 pane 的 agent 占有终端前台并显示 main agent;挂起或处于后台的 agent、显示
subagent 的 pane 都会被拒绝。session 工作时,用户的 prompt 改走 session 自己
的渠道,因此不会向忙碌的 pane 输入。Agent 的 prompt 无论状态都走 session 自己
的渠道;仅当 session idle 且无法证明其 inbox 时,才回退到 pane。该渠道是
Claude Code 的 inbox、Pi 和 oh-my-pi 中 tmag 的 extension,或 Codex daemon 的
control socket。以 --no-daemon 运行的 Codex session 除 pane 外没有渠道,因此
只在 idle 时接收 prompt;用户的 --wait 无法到达没有 pane 的 Claude Code
background session。
Session 不能留有尚未确认的 tmag 投递。--wait 的 prompt 在 agent 启动该 turn
前一直占用;异步 prompt 则在 main agent 再次上报前占用。任一标记存在期间,再次
send 会被拒绝为 busy;两者都会在 15 秒后释放。没有渠道的 working session
会被拒绝为 busy,而不会向 pane 输入。Agent 对自身 session 执行 send 会被拒绝
为 self;prompt 写入前 session 结束会返回错误 ended。
通过 pane 投递时使用 bracketed paste,再按 Enter。内容中的控制字符会先被移除,
防止转发文本提前结束 paste 或触发按键。Agent 输入框中的现有草稿会与 prompt
拼接:两种 agent 都没有无副作用清空草稿的按键,因此 tmag 保留草稿。Hooks 也在
相同的 session lock 下更新 session,因此 prompt 启动的 turn 总是在对应 Send
event 之后记录。
send --wait 报告 session 最终到达的状态:turn 结束时为 ID idle;中途停于
请求时为 ID blocked (KIND)。不启动 turn 的输入(例如 slash command)会在 15
秒后释放 session,此时 send --wait 返回 "started": false。Session 结束时,
wait 和 send --wait 以错误码 ended 退出;--wait 在投递后超时会说明
prompt 已投递但后续结果未知,因此应再次运行 tmag wait,而不是重复发送。
Send event 在 prompt 写入前记录。写入后的明确拒绝证明什么都没投递;其他错误则
无法确认 agent 是否接收了 prompt,错误信息会说明这一点。Gate 拒绝以 3 退出;
渠道明确未接收或结果未知则以 1 退出,并由错误信息区分。
tmag reply <target> [--timeout D] [--json] [text | -] 回应要求回复的 prompt,
第一行为 [tmag] Reply from … Do not reply to it.。它通过请求方自己的渠道——
inbox,或 Codex daemon 的 control socket——立即送出,无论请求方状态如何。只有
pane 的请求方会在 idle 时通过其 pane 接收;该请求方忙碌时,reply 仅针对
busy 拒绝重试,直到 --timeout(默认一分钟)。只有 tmag 能证明其 session
身份的 agent 才能发送 reply。超时以 4 退出,并说明是否已投递:拒绝或渠道明确
未接收都证明什么都没投递,可以再次运行;其他错误则结果未知,不得再次发送。输出为
replied to ID (CHANNEL) seq N;通过 pane 投递时括号内为 pane id。
Codex daemon 中的 thread 通过 daemon 的 control socket($CODEX_HOME/app-server-control/app-server-control.sock)接收 prompts 和中断,无论是否有 pane 显示该 thread;终端中看到的 turn 与直接输入时一致。tmag 只为单次命令连接,随后断开。
仅当 socket 对应的进程是运行该 thread hooks 的进程或其祖先进程时,tmag 才会操作。发送前还会询问 daemon:不带 --wait 的 send 接受 idle 或 active 的 thread,--wait 要求 idle,interrupt 要求 thread 正在运行。Daemon 会接收发给运行中 turn 的 prompt 而不是拒绝,因此不带 --wait 的 send 会并入当前 turn;--wait 保留 tmag 的 idle gate,因此其 prompt 会启动自己的 turn。由于 daemon 在响应前就运行 turn hooks,tmag 会先记录 Send 或 Halt event,再向 daemon 发出请求。
第一个连接新 daemon 的客户端可能被记录为之后 threads 的 originator,因此 tmag 只连接已经运行目标 thread 的 daemon。
Session 处于 blocked 时,每个未决请求都列在 requests 中,包含 id、kind(permission、question 或 plan)、相关 tool,以及 subagent 请求对应的 agent。
tmag request 从 agent 持有请求的地方转发请求内容、tool 及输入,仅用于展示,不存储。用 tmag answer TARGET REQUEST allow|deny 作决定;拒绝时,--message 会将说明传给 agent。问题通过 --answers '{"question text":"chosen label"}' 回答。
Claude Code 插件的 PermissionRequest hook 为 tmag answer-hook:它先像普通 hook 一样上报请求,然后等待 tmag answer,与此同时 Claude 自己的对话框仍在屏幕上。终端和 tmag 谁先回应,就采用谁的决定;终端已回应时,hook 退出。
后台 sessions 同样会等待,因此无需终端也能回应。发生任何失败,或等待达到 590 秒时,hook 会静默退出,保留 agent 自己的对话框处理决定。@tmag-answer 为 off 时不等待;所有 agents 的 answer 都会返回 unsupported。
对于 Codex daemon 中的 thread,answer 在与发往 daemon 的 send 相同的身份验证条件下,通过 control socket 接入。Daemon 重放仍在等待的 approvals,每个 approval 标识对应的 tool call。tmag 回应与该 request 的调用相匹配的 approval(Bash、write_stdin 对应 command approval,apply_patch 对应 file change),待 daemon 确认解决后断开。
Codex 的 PermissionRequest hook 不标识具体 call,因此 tmag 将请求关联到 agent 当时正在运行的该 tool 的唯一调用。如果有多个并发调用,则其中任一个都可能在请求批准,只能在 agent 内回应(ambiguous)。其他 tools(例如 MCP tools)的 approvals 也只能在 agent 内回应(unsupported)。
Codex 在 hooks 结束后才显示对话框,因此没有 hook 在那里等待。Codex 的决定不携带 message;以 --no-daemon 运行的 Codex session 只能在 agent 内回应。
Pi 和 oh-my-pi 只能在 agent 内回应:Pi 的对话框属于打开它的 extension,oh-my-pi 的 approvals 和 ask tool 属于它自己的 UI,没有任何渠道能够触及。tmag 仍将它们报告为 requests,因此 tmag inspect 和提醒会显示 session 正在等待什么。
answer 在 session lock 下检查 request 是否仍打开。通过 hook 回应时,hook 接受决定后才记录 Answer,同时关闭 request;event 报告更新后的 session,若它是最后一个请求,session 会继续工作。通过 daemon 时,先记录 Answer 再发送决定,此时 session 仍为 blocked;等 Codex 上报后续行为(tool call 或 agent 继续执行)后才关闭 request。Codex 0.166 接受 decline,尽管其 approvals 未列出该选项。
同时回应同一 request 时,一个会送达,另一个以 changed 拒绝。刚在终端中回应的 request 仍可能接受一个随后被 agent 忽略的决定;实际行为以接下来的 events 为准。Sandboxed command 的网络请求不会触发 hook,只能在 agent 内回应。
tmag interrupt 中断 session 正在运行的 turn,或拒绝其正在等待的请求,从而结束该 turn。通过 pane 时,它按一次 Escape,仅在 main agent 为 working 或 blocked 且其 pane 的 agent 占有终端时执行;idle session 以 idle 拒绝。
这些 agents 在空输入框中连按两次 Escape 都会打开菜单,因此一次中断后,直到 agent 再次上报或经过 90 秒,都会拒绝再次中断。Codex 随后上报 Interrupt,Pi 和 oh-my-pi 上报被中止 turn 的结束,session 变为 idle。处于 blocked 的 Pi 或 oh-my-pi 收到 Escape 时会拒绝其对话框,并由 agent 自行决定 turn 是否继续,随后上报其结果。Claude Code 不上报,连 idle 通知也没有,因此 tmag 记录已投递的结果:Halt event 将 session 标记为 idle,请求标记为已拒绝。