WezTerm Agent Bridge

把 Claude Code / Codex 这类 CLI agent 的多会话编排能力，迁移到 WezTerm 原生 pane/tab 体系上的兼容层设计仓库。

本项目的核心目标不是重写终端，也不是做一个新的 IDE 插件，而是复用 WezTerm 已有能力：

• pane / tab / window 管理
• wezterm cli 外部控制 API
• Lua 配置与事件系统
• Windows / macOS / Linux / WSL 一致运行模型

然后在其上提供一层 agent 兼容协议，让上层 CLI 误以为自己运行在可用的 iTerm2 环境中，从而复用已有的 it2 session split/run/close/list/focus/read 工作流。

结论

可行，而且适合单独做成 WezTerm 版运行时。

当前 IntelliJ 插件里的可迁移部分是协议层和 shim 思路，不可直接复用的是 IntelliJ ToolWindow / TerminalWidget / Swing splitter 相关实现。WezTerm 版应该重写一个独立 bridge：

flowchart LR
    A[用户在 WezTerm 中运行 miccs / claude / codex] --> B[provider shell wrapper]
    B --> C[真实 Claude Code / Codex CLI]
    C --> D[假 it2 / provider shim]
    D --> E[Agent Bridge daemon 或脚本]
    E --> F[wezterm cli]
    F --> G[WezTerm mux]
    G --> H[Pane / Tab / Window]

    C --> I[SessionStart / Notification hooks]
    I --> E

文档导航

• 项目目标与边界
• 总体架构
• 协议与命令映射
• 跨平台与 Windows/WSL 策略
• 实现计划
• 风险与验证清单
• 决策记录

初始范围

第一阶段只做最小可用体验：在 WezTerm 中直接运行 claude，或运行用户 zshrc 中已经定义好的 miccs 这类封装函数，即可让 Claude Code 的 agent/team 分屏能力落到 WezTerm pane 上。

内部最小协议面：

• it2 session list
• it2 session split [-v] [-s <pane>] [--cwd <path>]
• it2 session run [-s <pane>] <command>
• it2 session close [-f] -s <pane>
• it2 session focus -s <pane>
• it2 session read [-s <pane>] [-n <lines>]

不在第一阶段做：

• GUI 设置页
• 自定义 pane header
• IDE ToolWindow 嵌入
• Marketplace 打包
• 多用户远程协同

推荐形态

第一版建议是一个 WezTerm 内生效的 provider shell wrapper 加本地 daemon 和一组 shim 脚本：

• daemon 负责 session registry、token 校验、调用 wezterm cli、处理 hook 回调
• claude / codex shell wrapper 负责启动或复用 daemon，注入兼容环境，然后执行用户原有 provider 函数或真实 provider CLI
• shim 负责伪装 it2，把 Claude Code 发出的命令转成 daemon API
• WezTerm Lua 配置只做 shell 注入入口和环境注入，不承载复杂业务
• 用户主体验是直接在 WezTerm 中运行 miccs / claude / codex，而不是运行专用启动命令

这样可以同时支持 macOS、Linux、Windows 原生、Windows + WSL。

当前实现状态

已经开始 Milestone 1：

• TypeScript CLI：dist/index.js
• daemon：本地 HTTP API、token 校验、session registry
• WezTerm adapter：封装 list/split-pane/send-text/get-text/activate-pane/kill-pane
• WezTerm socket 自动发现：处理默认 socket symlink 指向旧 GUI 的情况
• it2 shim：生成到 ~/.local/state/wezterm-agent-bridge/shims/it2
• zsh 注入片段：加载在用户 zshrc 后，包住已有 claude shell function

本地验证命令：

npm run build
node dist/index.js doctor
node dist/index.js print-zsh-init

真实端到端验证需要在 WezTerm pane 内执行：

zsh -ic 'type miccs; type claude; echo $WEZTERM_PANE'
miccs --model haiku "/agent-team 用 mimo profile 创建三个队友 都是 haiku 模型 其中一个查询天气 其他两个待命，任意名字，别问我就行"

已验证真实 smoke：该命令能在 WezTerm 中创建 leader pane + 3 个 teammate pane，并在 registry 中记录 wezterm:<pane-id>。

分发与安装

当前推荐先按 npm CLI 包分发。

本机开发安装：

cd /Users/hangox/Desktop/MyProjects/wezterm-agent-bridge
npm install
npm run build
npm link

生成可复制安装包：

npm pack

会生成类似：

wezterm-agent-bridge-0.1.0.tgz

其他机器安装：

npm install -g ./wezterm-agent-bridge-0.1.0.tgz

安装后检查：

wezterm-agent-bridge doctor
wezterm-agent-bridge init zsh

把 wezterm-agent-bridge init zsh 输出的片段放到 ~/.zshrc 靠后位置，确保 miccs / run_claude / claude 等用户函数已经加载完成。之后在 WezTerm 里直接运行 miccs 或 claude 即可。