tmux-agent

Headless orchestration CLI / daemon (Effect TS) for supervising multi-session agents, with tmux as the default terminal host adapter.

Quickstart

• Fork 并行（从当前 TMUX_PANE 创建 run）：tmux-agent fork-run --spec -
• 驱动轮询与合并：tmux-agent daemon tick（建议 30s 一次）
• 启动面板：tmux-agent panel
• 排查/跳转（不打开面板）：tmux-agent ui inspect|jump --run <runId> --session <sessionKey> --json
• Headless 查询：tmux-agent run list --json
• 可选 tmux 配置片段：scripts/tmux-agent.tmux.conf
• 可选 Codex tmux 集成：自定义 tmux 绑定到 tmux-agent codex ...

tmux UI 标签（可选）

• 用于嵌入 tmux format（#(cmd)）：tmux-agent unattended badge --preset border --pane <paneId> --server <server>（<server> 推荐 #{b:socket_path}）
• 用于按键绑定（切换开关）：tmux-agent unattended toggle --mode nudge|drive --pane <paneId> --server <server>
• pane-border-format 右上角对齐：在同一条 pane-border-format 里追加 #[align=right]，示例见 scripts/tmux-agent.tmux.conf
• scripts/tmux-agent.tmux.conf 仅负责渲染右上角 badge（不包含鼠标点击切换逻辑）
• 默认未开启时不显示任何标签（badge 输出空字符串）
• scripts/tmux-agent.tmux.conf 用 set -ga pane-border-format 追加 badge；若你有主题会重设 pane-border-format，把 source-file 放到最后

Unattended LLM Gate（可选）

当启发式判定为 uncertain 时，可通过在线大模型做一次 Gate 判定（继续/停下/需要人工）：

• 启用：tmux-agent unattended enable --mode nudge --max-turns 20 --gate-backend llm_api
• 配置（环境变量）：
  • TMUX_AGENT_GATE_LLM_BASE_URL（默认 https://api.openai.com/v1）
  • TMUX_AGENT_GATE_LLM_API_KEY（或 OPENAI_API_KEY）
  • TMUX_AGENT_GATE_LLM_MODEL（默认 gpt-4o-mini）
  • TMUX_AGENT_GATE_LLM_PROMPT（可选；支持 {{turnId}} / {{lastAssistantMessage}}）

作为真实用户跑通 fork→汇总闭环（Codex）

1. 在 tmux pane 中启动 Codex TUI（示例参数按成本优化）：

codex -m gpt-5.1-codex-mini -c model_reasoning_effort=low

2. 在同一个 pane 里 fork 出一个分支并自动提交任务：

tmux-agent fork-run --spec - --json <<'JSON'
{
  "branches": [
    {
      "sessionKey": "branch-1",
      "plannedInput": {
        "initialText": "Return only this block: [TMA_RESULT_V1]{\"schemaVersion\":\"agent-result.v1\",\"status\":\"success\",\"summary\":\"ok\"}[/TMA_RESULT_V1]",
        "autoSubmit": true
      }
    }
  ]
}
JSON

3. 在另一个 pane 里跑 tick 循环（默认 policy：30s 轮询，6 次无进展判 stalled）：

while true; do tmux-agent daemon tick --json >/dev/null; sleep 30; done

完成后主会话会收到 [tmux-agent] fork summary 注入。若失败比例 ≤ 50%，默认会自动回车继续。

示例（1 个分支成功）：

[tmux-agent] fork summary
success: 1/1
- branch-1: ok

Codex tmux 集成（手动配置）

tmux-agent 仅提供子命令；由你自行接入 tmux 配置。

示例（~/.tmux.conf）：

# pane 聚焦时确认 turn-complete 标记
set-hook -ag pane-focus-in 'run -b "tmux-agent codex notify-ack --pane #{pane_id} >/dev/null 2>&1 || true"'

# prompts 浏览弹窗
bind -n M-k display-popup -E -w 80% -h 80% -T "codex-prompts" -d "#{pane_current_path}" -e "ORIGIN_PANE_ID=#{pane_id}" "tmux-agent codex prompts browse"

逐步替换 legacy ~/.config/tmux/extensions/codex：

• 替换 Codex notify handler 配置：
  • 移除 CODEX_NOTIFY_HANDLER=.../codex_notify_dispatch.py
  • 设置 notify = ["tmux-agent", "codex", "notify"]
• 替换 tmux hooks / bindings：
  • codex_notify_ack_turn_complete.sh -> tmux-agent codex notify-ack --pane #{pane_id}
  • codex_notify_on_switch_done.sh -> tmux-agent codex notify-switch-done --client-tty #{client_tty}
  • panel/codex_prompts_browser.sh -> tmux-agent codex prompts browse
  • codex_prompt_picker.sh -> tmux-agent codex prompts pick
  • panel/codex_copy_conversation.sh -> tmux-agent codex copy-conversation
  • panel/codex_reload_active.sh -> tmux-agent codex reload-active
  • panel/codex_worktree_reload_followup.sh -> tmux-agent codex worktree-reload-followup
  • codex_spawn_background_pane.sh -> tmux-agent codex spawn
  • codex_session_id.py -> tmux-agent codex session-info
• 通知点击跳转已内置；仅在需要覆盖时设置：CODEX_NOTIFY_ON_CLICK="..."

Codex notify 加速器（可选）

在 $CODEX_HOME/config.toml 中加入：

notify = ["tmux-agent", "codex", "notify"]

额外 handler（可选）：

export CODEX_NOTIFY_USER_HANDLER="/path/to/your-notify"
export CODEX_NOTIFY_EXTRA_HANDLER_DIRS="/path/to/dir1:/path/to/dir2"
export CODEX_NOTIFY_ENABLE_TMUX_AUTORUN=1

状态与恢复

• 默认目录：~/.tmux-agent（可用 TMUX_AGENT_HOME 覆盖）
• 控制器状态与证据日志都在本地落盘，可在重启后继续接管与恢复
• fork 会话默认运行在“每个 run 一个独立 tmux server”的后台环境中；tmux-agent panel 会显示 attach 提示，便于你随时进入分支会话观察/接管
• 若 panel 选中会话无法跳转/接管：优先用 tmux-agent ui inspect --run <runId> --session <sessionKey> --json 探测 tmux 存活性与 jump 计划
• panel 展示的是 controller state（包含历史/残留项）；state 里显示为 running 也不代表 tmux server 仍可达（常见于旧 itest 产物或 TMUX_TMPDIR 漂移）。这类“不可达残留”可先通过 ui inspect 确认原因。
• 清理残留（两段式）：先 dry-run 再 apply
  • tmux-agent state prune --dry-run --unreachable-only --run <runId> --session <sessionKey> --json
  • tmux-agent state prune --apply --unreachable-only --run <runId> --session <sessionKey> --json

本地集成验收（可选）

• bun run itest
• 真实 Codex e2e：设置 TMUX_AGENT_E2E_CODEX=1

Role

• Primary headless control plane (CLI + daemon) for multi-session orchestration.
• Integrates with @tmux-agent/agent-orchestrator and agent-tmux.

Development

• Effect TS services/layers only; avoid Node globals in core logic.
• Forward-only evolution (breaking changes allowed; contracts must be versioned).
• References: ../../docs/standards/README.md, ../../specs/012-effect-ts-migration/quickstart.md.

Specs / roadmap:

• ../../specs/008-universal-session-orchestration
• ../../specs/012-effect-ts-migration