把你的 CLI 接上 conmux

（这一页写给做 agent 框架 / CLI 工具的人。你有一个自己的命令行程序，想让它在 conmux 里跑起来、被看住。）

先说一句实在话

「一键接入任意框架、自动识别、自动适配」这套脚手架，conmux 现在还没有。 别被别的话术带偏——今天 conmux 能给你的是两档，界限很清楚：

1. 任何 CLI 都能起成一个受监管的 pane —— 这是已经能用的地基。你的程序、别人的程序、PowerShell、WSL 里的工具，都一样。
2. 对 Claude Code 会话有一层深观测 —— 这是目前唯一做了专属适配的框架。

至于「你随便丢个 agent 框架进来，conmux 就自动认出它是什么、自动把它的模型 / token / 子任务解析出来」——那是方向，不是现状。想要那一层，得像 Claude 那样为每个框架单独写适配。所以下面分两段讲：先讲对谁都成立的那档，再讲 Claude 专属那档。

第一档：把任意 CLI 起成受监管 pane（人人可用）

conmux 不在乎你的程序「是不是 agent」——它只认进程、字节、pane。要把你的 CLI 接进来，你需要的信息就一条命令这么多：

• program —— 要启动的可执行文件（比如 my-agent.exe、node、python）。
• args —— 启动参数（比如 --serve、run main.py）。
• cwd —— 工作目录（可选；不给就继承当前目录）。

在 GUI 里，这三样合起来就是一条启动项（launch entry）：一个显示名 + 一行命令原文（含参数）+ 可选工作目录。内置就种了两条能直接跑的——Shell（powershell.exe）和 WSL（wsl），你可以照着加自己的、改它、删它。命令原文按「空格分词 + 双引号包含空格段」拆成 program 和 args（不支持管道、重定向、变量展开——那些超出启动项的范围）。

按下去之后发生的事：conmux 把你这条命令当成一个真的 ConPTY 进程直接启动（不是往某个 shell 的 stdin 里灌字符），于是你的 CLI 就成了一块受监管的 pane。从这一刻起，前面几章讲的能力对它全都成立：

• 和别的 pane 分屏并排、一排小圆点之间切换；
• 关掉客户端窗口，你的进程不会死，重新 attach 画面原样接回（detach / attach）；
• 它连同它 fork 出去的子孙进程一起被 Job Object 兜住——要杀就整树杀干净，不留孤儿；
• 所有往它写的输入都过同一条受审计的通道。

这一档不挑框架。 你的 agent CLI 只要能在 Windows 命令行里跑起来，它就能变成 conmux 的一块 pane，享受上面这一整套。这是 conmux 今天能给「任意框架」的、最扎实的那部分。

要更精确的接入契约？ program / args / cwd 怎么进到 spawn、启动项怎么持久化、命令怎么解析——GUI 侧真源在 conmux-app/src/lib/launch-registry.ts 与 sessions.ts。从代码驱动内核（framed 协议、稳定 pane id、事件流）见 从代码驱动 conmux。

第二档：Claude Code 的深观测（目前唯一的专属适配）

除了「起成 pane」，conmux 对 Claude Code 会话还多做了一层——能看出这个会话在跑什么模型、上下文用了多少、派了哪些子任务、什么时候在等你。这一层是给 Claude 专门写的，不是通用能力。

当你用一条裸 claude 命令（就是 claude，你自己没带任何参数）通过 conmux 启动时，conmux 会自动做三件事：

1. 注入 --session-id <uuid> —— 给这个会话钉一个唯一 id，观测端据此精确锚定它的日志文件，不会和同一目录下别的历史会话串台。
2. 顺着 JSONL 读 —— Claude Code 会把会话内容写成 JSONL 日志；conmux 增量读它，从中解析出模型名、token、上下文占比、子 agent 树这些结构化信息。
3. 挂一个 Notification hook —— 通过临时写一份 --settings 文件（只对这个会话生效，且和你自己的全局 hooks 合并、不覆盖），拿到「等你批准权限 / 闲着等你输入」这类结构化的「需要你」信号，补上终端响铃（BEL）抓不到的那些 TUI 权限框场景。

有几条边界要讲在明处：

• 只对裸 claude 生效。 你只要给了任何显式参数（哪怕是自带 --session-id、-c、-p），conmux 就一个字都不动你的命令——不注入、不加 hook。这是刻意的纪律：不越俎代庖改你的启动。
• 依赖 claude CLI 支持 --session-id（2026-07 当时的版本已验证支持）；太老的版本不认这个 flag 会在 pane 里可见地报错退出，不是静默失败。
• 任一步失败都会诚实降级。 写不了 settings 文件 / 拿不到目录，就退回「只注 session-id」甚至只靠 BEL + 退出信号，绝不假装观测正常。
• 观测只读真打印 / 真日志的内容，拿不到就留空（UI 显 —），绝不猜、绝不编造模型或活跃状态。

深观测具体解析出哪些字段、怎么判活跃 / 陈旧、子 agent 树怎么来——见 conmux 观测什么。想接入代码真源在 conmux-app/src/observe/（session-observer 与 parsers/claude.ts）、hook 构造在 src/lib/claude-hooks.ts。

那「通用适配层」呢——差在哪、会往哪走

坦白说清楚这道缺口：

• 今天有的：任意 CLI → 起成受监管 pane（通用）；Claude Code → 深观测（专属）。
• 今天没有的：一个「你丢进来就自动识别框架类型、自动套上对应观测 / 适配」的通用脚手架。观测那一层现在是一个框架一份手写适配——Claude 有，别的框架暂时没有。
• 想让 conmux 认识你的框架，路子就是照 Claude 这条走：为它写一个 parser / 观测适配。这块的可扩展点、以及「机制该管到哪、语义该留给谁」的分界，见 机制 vs 语义：边界在哪。

如果你正在做自己的 agent CLI、想让它在 Windows 上被 conmux 好好看住——第一档现在就能用，欢迎直接接；想推动通用适配层、或想把你的框架加进深观测，特别欢迎开 issue / discussion，或直接发 PR。让「把你的 agent CLI 轻松接上 Windows」这件事真正成立，正是这个项目最想和你一起做的事。