handmux 0.23.0 → 0.25.0

package/README.md

@@ -27,7 +27,7 @@ handmux is more than a terminal on your phone. It puts the *same* live **tmux**
 
 ## Quick start · about a minute
 
-Your computer needs tmux and Node ≥ 20; the phone just needs a browser. Pick one:
+Your computer needs tmux and Node ≥ 22.16; the phone just needs a browser. Pick one:
 
 **Homebrew — macOS (recommended)** · installs Node + tmux for you:
 
@@ -62,27 +62,50 @@ handmux start --tunnel cloudflare   # instant public URL (cloudflared auto-insta
 - **🧰 More than a terminal — a whole mobile vibe-coding cockpit in your pocket.** Full-screen colored git diffs, one-tap preview of a running site, docs read aloud line by line, files moved both ways — a whole dev kit in hand, no hopping between apps.
 - **🚀 One minute from zero to coding on your phone.** One `handmux start`, one scan, done — no sign-up, no App Store, no app to sideload; just a link. "Add to Home Screen" and it's a full-screen **PWA**, as smooth as a native app.
 - **🧶 Walk away, keep working.** Your phone drives the *one* live tmux pane on your desk (not a new shell, not a screenshot). Close the laptop and keep watching from your thumb — exact same state.
-- **🔔 When it needs you, your phone rings.** Claude Code / Codex push the moment they need a decision; add it to your home screen and they come through as system notifications. An inbox tags each pane working / needs-you / done — many projects at a glance — and you approve permissions and plans with a tap, so you stop babysitting the screen.
+- **🔔 When it needs you, your phone rings.** Claude Code / Codex push the moment they need a decision; add it to your home screen and they come through as system notifications. An inbox tags each pane working / needs-you / done / error — many projects at a glance — while the host keeps terminal-result reads consistent across refreshes and devices. Open a completed item to start at the final completed AI answer in the authoritative latest tail. Claude Hook outcomes queue locally while the Server is offline and replay in session order after it returns. Approve permissions and plans with a tap, so you stop babysitting the screen.
 - **🔒 Your code goes through no middleman.** Free and fully open-source; we run no server in the middle — your data travels straight between your computer and your phone, so it stays secure.
 
 ## Features
 
-- **Claude Code / Codex, deeply** — an inbox status ledger, thumb-approve permissions & plans, and stable host-wide usage bars shared by every connected device.
-- **Chat view** — drive Codex CLI through App Server with streaming Markdown bubbles, tool cards, persistent task goals and live status; long replies hold at their beginning for reading, with an explicit jump back to the latest output. Existing panes can switch in place, and messages sent during a turn form an editable server queue. Claude Code chat is an independently enabled experimental option.
+- **Claude Code / Codex, deeply** — an inbox status ledger, thumb-approve permissions & plans, and stable host-wide subscription usage shared by every connected device; each visible provider can refresh its latest limits from the card action menu, while keeping the previous values visible if that provider cannot be reached. Codex also shows the current account and plan, separate account/model limits, remaining rate-limit resets, and each provided expiry. The same Usage screen can save multiple DeepSeek and Moonshot (Kimi) API accounts encrypted at rest within the Handmux computer's local trust boundary; full API Keys never return to browsers.
+- **Chat view** — drive Codex CLI through App Server with streaming Markdown bubbles, tool cards, native Goal lifecycle cards, and session status; the context-ring details show the absolute Git worktree root path and branch that contain the thread `cwd`. Setting or restarting a Goal creates a fresh active native Goal, immediately shows its user-side card on the right, and starts Codex's built-in continuation. An active or paused Goal stays beneath the live read-only turn task list, Codex terminal feedback stays with its originating turn on the left, and every entry opens the same Bottom Sheet. The current Goal uses one equal-width iOS-style action row; clearing it removes the resident Goal and closes the sheet, while its historical chat card remains. The current terminal Goal can be edited before restarting. Long replies hold at their beginning for reading, with an explicit jump back to the latest output. Existing panes can switch in place. Every sendable Agent uses the same persistent server queue: queued messages can be viewed, edited or deleted and are delivered automatically; Guide now appears only when that Agent supports steering. Failed or unconfirmed sends stay visible under the same request id so the server can reconcile them without duplicate execution. On desktop, <kbd>Shift</kbd>+<kbd>Enter</kbd> focuses the composer or inserts a newline when already focused, <kbd>Enter</kbd> sends, and <kbd>Esc</kbd> releases focus without stopping the Agent. Codex chat is stable; Claude Code and Pi chat are independently enabled experimental options.
 - **Real-time terminal + desktop keyboard** — stream the same tmux pane on phone and desktop with scrollback, weak-network fallback, direct physical-keyboard input, and native copy/paste.
-- **Command & chat modes** — switch between direct terminal input and natural-language agent chat, with a customizable quick bar that stays in sync across devices.
+- **Command & chat modes** — switch between direct terminal input and natural-language agent chat, with direct Alt and Space keys on the mobile command keyboard and a customizable quick bar that stays in sync across devices.
 - **Client reload after updates** — once the server update has finished, use Settings → Reload app to load the new client without quitting and reopening the home-screen app.
 - **Script push** — notify your phone from any script or CI step with `handmux push`; target all devices, a named session, or a specific device.
 - **Workspace recovery** — handmux keeps the metadata needed to restore your latest tmux workspace after a computer or tmux-server restart, without replacing existing sessions.
 - **Git viewer** — changes / commit history / any branch / full-screen colored diff, multi-repo tabs, read-only, never touches your tree.
 - **Web Preview for URLs and static folders** — preview URLs by phone or computer proxy, or open an isolated static folder, with narrow/wide page widths and zoom; computer proxy can also request a mobile or desktop site version. It embeds pages rather than replacing a full browser.
-- **Docs** — tap a path in the terminal to open it; Markdown rendered, font zoom, sentence-by-sentence read-aloud.
+- **Docs** — tap recognized text-file paths in the terminal to open them, regardless of extension; ordinary slash-separated prose stays plain. Markdown rendered, font zoom, sentence-by-sentence read-aloud. Binary files stay download-only.
 - **Mobile select & copy** — long-press to select in the terminal, drag iOS-style handles to fine-tune, copy the selection / a whole line / a whole paragraph.
-- **Files both ways** — multi-select upload from the chat box, download, share in, copy any absolute path.
+- **Files both ways** — multi-select upload from the chat box (including ZIP archives), download, share in, copy any absolute path.
 - **Ideas — catch every one** — a thought the moment it strikes: a per-window idea/to-do list, jot one by voice and drop it straight into the prompt.
 - **Built for flaky networks** — backoff reconnect, connection-lost banner, offline page, polling that pauses in the background; a reflow-safe cursor.
 - **Zero-install PWA** — runs full-screen from your home screen, with English, 简体 / 繁體中文, 日本語, and 한국어.
 
+## Agent integration
+
+Use `handmux <agent> [args...]` to start a supported Agent; every argument after the Agent name is passed through unchanged. Use the separate `handmux agent` namespace to enable or inspect Handmux integration. Codex support is built in, while Pi and Claude Code are explicitly enabled:
+
+```bash
+handmux codex [args...]
+handmux pi [args...]
+
+handmux agent                 # list Agent integration status
+handmux agent enable pi
+handmux agent status pi
+handmux agent disable pi
+
+handmux agent enable claude
+handmux agent status claude
+handmux agent disable claude
+handmux agent status codex    # ready (built-in) when Codex is installed
+```
+
+The legacy `handmux hooks install|uninstall` commands remain compatibility aliases for Claude Code. Pi integration uses a trusted Handmux-owned Extension wrapper for the same native Pi TUI process; enabling it writes only that wrapper under Pi's documented global extension directory and never scans projects or loads third-party extensions. Open a new Pi session, or run `/reload` in Pi, after enabling or disabling it. The wrapper is refreshed automatically across Handmux upgrades, but a file not marked as Handmux-owned is never overwritten or deleted. Pi keeps working normally when the Handmux server is offline; terminal outcomes are queued locally and delivered after it returns.
+
+The capability-driven Agent chat downloads attachments only after a tap. Providers register an opaque, session-bound resource ID; the app never receives a local path, and potentially active content such as HTML or SVG is always downloaded rather than rendered inline.
+
 ## Workspace recovery
 
 handmux continuously maintains two redundant copies of the latest workspace metadata. They are not browsing history: ordinary changes and deletions handmux can confirm simply update the current state. A selectable checkpoint is archived only when the computer or tmux environment changes. If the final tmux session disappears outside handmux, tmux cannot distinguish an intentional deletion from a crash, so handmux retains the last state and can offer recovery immediately, without waiting for a new tmux server or session. Every checkpoint from the latest 24 hours is kept; older history is then trimmed to the newest 10, while the latest valid checkpoint never expires just because of age.
@@ -146,7 +169,7 @@ Once autostart is installed, `handmux start` / `stop` / `restart` coordinate wit
 
 ## Requirements
 
-Your computer needs **Node ≥ 20** and **tmux ≥ 3.0**; the phone just needs a browser. On **Windows**, run it inside **WSL2** (a real Linux kernel + real tmux) — see the [docs](https://handmux.com/docs#windows).
+Your computer needs **Node ≥ 22.16** and **tmux ≥ 3.0**; the phone just needs a browser. On **Windows**, run it inside **WSL2** (a real Linux kernel + real tmux) — see the [docs](https://handmux.com/docs#windows).
 
 ## Feedback & community
 

package/README.zh-CN.md

@@ -27,7 +27,7 @@ handmux 不只是把终端搬上手机。它把你电脑上**正跑着的 tmux
 
 ## 快速上手 · 约一分钟
 
-**电脑上**需要 tmux 和 Node ≥ 20(手机只要个浏览器)。二选一:
+**电脑上**需要 tmux 和 Node ≥ 22.16(手机只要个浏览器)。二选一:
 
 **Homebrew —— macOS 首选** · 顺带帮你装好 Node + tmux:
 
@@ -62,27 +62,50 @@ handmux start --tunnel cloudflare   # 即时公网地址(自动装 cloudflared)
 - **🧰 不只是终端——一整套装进口袋的移动 Vibe Coding 驾驶舱。** git 全屏看彩色 diff、一键预览正跑着的网站、文档逐句朗读、文件随手双向传——一整套开发能力,此刻全套在手,不用在几个 App 间来回切。
 - **🚀 一分钟从零到手机上敲代码。** 一条 `handmux start`、扫个码,完事——不注册、不上应用商店、不装 App,一个链接就进去。"添加到主屏"后即为全屏 **PWA**,和原生 App 一样顺手。
 - **🧶 人走,活不停。** 手机连的是你工位上**那一个**正跑着的 tmux pane(不是新 shell、不是截图)。合上电脑,拇指接着盯,状态一点不差。
-- **🔔 需要你时,手机会响。** Claude Code / Codex 一到要你拍板就推送;添加到主屏后直接走系统通知。收件箱标「进行中 / 需要你 / 已完成」,多项目并行状态一览无余,拇指一点批授权批计划,别再守着屏幕等它。
+- **🔔 需要你时,手机会响。** Claude Code / Codex 一到要你拍板就推送;添加到主屏后直接走系统通知。收件箱标「进行中 / 需要你 / 已完成 / 出错」,多项目并行状态一览无余;终态结果的已读状态由电脑端统一记录,刷新或换设备也不会重复提醒。打开“已完成”会刷新权威最新尾部，并直接从最后一条已完成 AI 回复开头开始阅读。Server 离线时 Claude Hook 结果先在本机排队,恢复后按会话顺序补交。拇指一点批授权批计划,别再守着屏幕等它。
 - **🔒 你的代码,不经过任何中转。** 免费、完全开源;我们没有中转服务器,数据只在你的电脑和手机之间直接走,确保安全。
 
 ## 功能一览
 
-- **Claude Code / Codex 深度**——收件箱状态台账、拇指批授权批计划，以及所有设备共享的本机最新 agent 用量。
-- **对话视图**——通过 App Server 用流式 Markdown 气泡、工具卡、持久任务目标和实时状态操作 Codex CLI；长回答会稳定在开头供阅读，用户可随时回到最新内容；支持现有 pane 原位接入和回复期间可编辑的服务端消息队列。Claude Code 对话是独立开启的实验性功能。
+- **Claude Code / Codex 深度**——收件箱状态台账、拇指批授权批计划，以及所有设备共享的本机最新订阅用量；每个已开启显示的 Provider 都可从卡片操作菜单单独刷新最新额度，厂家暂时不可达时仍保留上一份数值。Codex 还会显示当前账号与套餐、主账号和特定模型的独立额度，以及剩余重置次数与官方提供的各次到期时间。同一个用量页还能在 Handmux 电脑的本机信任边界内静态加密保存多个 DeepSeek 和 Moonshot (Kimi) API 账户，完整 API Key 不会返回浏览器。
+- **对话视图**——通过 App Server 用流式 Markdown 气泡、工具卡、原生 Goal 生命周期卡片和实时状态操作 Codex CLI；上下文圆环详情直接显示 thread `cwd` 所属 Git worktree 的绝对根路径与分支。设置或重新开始会创建全新的 active 原生 Goal，立即在右侧显示用户侧卡片并启动 Codex 自带的自动续跑。进行中或暂停的 Goal 常驻在实时任务列表下方，Codex 终态反馈留在对应回合并靠左，所有入口统一打开同一个 Bottom Sheet；当前 Goal 使用 iOS 风格单行等分操作，清除后会移除常驻目标并关闭详情，已经发生的历史卡片仍保留；当前终态 Goal 可修改内容后重新开始。长回答会稳定在开头供阅读，用户可随时回到最新内容；现有 pane 可原位接入。所有可发送 Agent 共用同一套持久服务端队列：待发消息可查看、编辑、删除并自动发送，只有 Agent 支持 steer 时才显示“立刻引导”。发送失败或送达状态未知的消息会保留在原位置，并用同一个请求标识安全对账，避免重复执行。电脑端可用 <kbd>Shift</kbd>+<kbd>Enter</kbd> 聚焦输入框，聚焦后该组合键换行，<kbd>Enter</kbd> 发送，<kbd>Esc</kbd> 只取消聚焦而不会停止 Agent。Codex 对话为稳定功能；Claude Code 与 Pi 对话均需独立开启，且仍为实验性功能。
 - **实时终端 + 电脑键盘**——在手机和电脑上实时操控同一个 tmux pane，支持历史滚动、弱网回退、物理键盘直输和原生复制粘贴。
-- **命令 / 聊天双模式**——在终端直输与自然语言对话间切换，并用跨设备同步的快捷栏快速操作。
+- **命令 / 聊天双模式**——在终端直输与自然语言对话间切换；手机命令键盘提供直接可用的 Alt 与空格键，并可用跨设备同步的快捷栏快速操作。
 - **更新后重新加载客户端**——服务端更新完成后，在设置里点「重新加载应用」即可载入新版客户端，无需退出主屏应用再重新打开。
 - **脚本推送**——用 `handmux push` 从脚本或 CI 步骤推消息到手机,可指定全部设备、某个会话或某台设备。
 - **工作区恢复**——handmux 静默保存必要元数据，在电脑或 tmux server 重启后恢复最新工作区，绝不替换现有会话。
 - **Git 查看器**——改动 / 提交历史 / 任意分支 / 全屏彩色 diff,多仓库分页,只读不动工作区。
 - **网页预览器**——用手机直连或电脑代理预览网址，也可隔离打开静态目录，支持窄屏 / 宽屏和缩放；电脑代理还可向网站请求手机版或电脑版。它只嵌入网页，不替代完整浏览器。
-- **文档**——终端里点路径即开;Markdown 排版、字号缩放、逐句高亮朗读。
+- **文档**——终端里明确识别出的文本文件路径不分扩展名均可点开，普通斜杠文字保持纯文本；支持 Markdown 排版、字号缩放、逐句高亮朗读，二进制文件仍只下载。
 - **选中 · 拷贝**——终端里长按选中,拖 iOS 式手柄精调,一键拷贝选区 / 整行 / 整段。
-- **文件双向传**——聊天框多选上传、下载、系统分享进来、复制绝对路径。
+- **文件双向传**——聊天框多选上传（含 ZIP 压缩包）、下载、系统分享进来、复制绝对路径。
 - **想法 · 随想随记**——不错过任何点子:每窗口一份想法清单,灵感一冒就记(能语音速记),一点填进输入框。
 - **专治弱网**——退避重连、掉线横幅、离线兜底页、后台暂停轮询;光标不乱跳。
 - **零安装 PWA**——添加到主屏即可全屏运行，支持 English、简体 / 繁體中文、日本語和 한국어。
 
+## Agent 接入
+
+用 `handmux <Agent> [args...]` 启动受支持的 Agent，Agent 名后的参数会原样透传；用独立的 `handmux agent` 命名空间启用或检查 Handmux 接入。Codex 接入已内置，Pi 和 Claude Code 需要显式启用：
+
+```bash
+handmux codex [args...]
+handmux pi [args...]
+
+handmux agent                 # 列出 Agent 接入状态
+handmux agent enable pi
+handmux agent status pi
+handmux agent disable pi
+
+handmux agent enable claude
+handmux agent status claude
+handmux agent disable claude
+handmux agent status codex    # 已安装 Codex 时就绪（接入已内置）
+```
+
+旧的 `handmux hooks install|uninstall` 暂作 Claude Code 兼容别名。Pi 接入使用受信任的 Handmux 自有 Extension wrapper，连接的仍是电脑上同一个原生 Pi TUI 进程；启用时只在 Pi 官方全局 Extension 目录写入这一个 wrapper，不扫描项目，也不加载第三方扩展。启用或禁用后，新开 Pi 会话，或在 Pi 中运行 `/reload`。Handmux 升级后会自动刷新已启用的自有 wrapper；没有 Handmux 所有权标记的文件绝不会被覆盖或删除。Handmux Server 离线时 Pi 仍可正常使用，终态结果会先在本机排队，Server 恢复后再补交。
+
+通用 Agent 对话中的附件只在用户点按后下载。Provider 只注册与会话绑定的 opaque resource ID，手机不会收到本机路径；HTML、SVG 等潜在主动内容始终作为附件下载，不在页面内直接渲染。
+
 ## 工作区恢复
 
 handmux 会持续维护最新工作区元数据的两份容灾副本。它们不是操作历史:日常变动和 handmux 能确认的主动删除只会更新当前状态。只有电脑或 tmux 环境换代时才归档可选择的 checkpoint。若最后一个 tmux 会话在 handmux 外消失，tmux 无法区分主动删除与崩溃；为保留崩溃恢复能力，handmux 会保留最后状态，并立即提供恢复，无需等待新 tmux server 或 session 出现。最近 24 小时内的全部保留;更早历史再裁到最新 10 份,最新有效 checkpoint 不会只因过期而消失。
@@ -146,7 +169,7 @@ handmux push <title> <body> [选项]
 
 ## 环境要求
 
-电脑需 **Node ≥ 20** 与 **tmux ≥ 3.0**;手机只要浏览器。**Windows** 请装进 **WSL2**(真 Linux 内核 + 真 tmux)——见 [文档](https://handmux.com/docs#windows)。
+电脑需 **Node ≥ 22.16** 与 **tmux ≥ 3.0**;手机只要浏览器。**Windows** 请装进 **WSL2**(真 Linux 内核 + 真 tmux)——见 [文档](https://handmux.com/docs#windows)。
 
 ## 反馈与交流