Skip to content

Commit d4540c5

Browse files
claudeclaude
committed
docs(readme): move Mobile-Optimized Web UI right after Quick Start
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 4a83efc commit d4540c5

2 files changed

Lines changed: 104 additions & 104 deletions

File tree

‎README.md‎

Lines changed: 52 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,58 @@ Codeman requires tmux, so Windows users need [WSL](https://learn.microsoft.com/e
157157

158158
---
159159

160+
## Mobile-Optimized Web UI
161+
162+
The most responsive AI coding agent experience on any phone. Full xterm.js terminal with local echo, swipe navigation, and a touch-optimized interface designed for real remote work — not a desktop UI crammed onto a small screen.
163+
164+
<table>
165+
<tr>
166+
<td align="center" width="40%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="Mobile — answering an agent's plan prompt with the keyboard accessory bar and Enter button" width="300"></td>
167+
<td align="center" width="60%"><img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="Mobile toolbar: accessory bar with /init, /clear, clipboard and Esc above the Run, case, stop, Enter, voice and settings controls" width="440"></td>
168+
</tr>
169+
<tr>
170+
<td align="center"><em>Answering prompts by touch</em></td>
171+
<td align="center"><em>Accessory bar + dedicated Enter button</em></td>
172+
</tr>
173+
</table>
174+
175+
<table>
176+
<tr>
177+
<th>Terminal Apps</th>
178+
<th>Codeman Mobile</th>
179+
</tr>
180+
<tr><td>200-300ms input lag over remote</td><td><b>Local echo — instant feedback</b></td></tr>
181+
<tr><td>Tiny text, no context</td><td>Full xterm.js terminal</td></tr>
182+
<tr><td>No session management</td><td>Swipe between sessions</td></tr>
183+
<tr><td>No notifications</td><td>Push alerts for approvals and idle</td></tr>
184+
<tr><td>Manual reconnect</td><td>tmux persistence</td></tr>
185+
<tr><td>No agent visibility</td><td>Background agents in real-time</td></tr>
186+
<tr><td>Copy-paste slash commands</td><td>One-tap <code>/init</code>, <code>/clear</code>, <code>/compact</code></td></tr>
187+
<tr><td>Password typing on phone</td><td><b>QR code scan — instant auth</b></td></tr>
188+
</table>
189+
190+
- **Keyboard accessory bar** — `/init`, `/clear`, `/compact` quick-action buttons above the virtual keyboard; destructive commands require a double-press to confirm, so you never fire one by accident
191+
- **Dedicated Enter button** — replays the keypress through the terminal, so text buffered by local echo is flushed first rather than stranded
192+
- **Swipe navigation & smart keyboard handling** — swipe left/right to switch sessions; toolbar and terminal shift up when the keyboard opens (`visualViewport` API)
193+
- **Built for phones** — safe-area insets for notch and home indicator, 44px touch targets, bottom-sheet case picker, native momentum scrolling
194+
195+
```bash
196+
codeman web --https
197+
# Open on your phone: https://<your-ip>:3000
198+
```
199+
200+
> `localhost` works over plain HTTP. Use `--https` when accessing from another device, or use [Tailscale](https://tailscale.com/) (recommended) — it provides a private network so you can access `http://<tailscale-ip>:3000` from your phone without TLS certificates.
201+
202+
### Secure QR Code Authentication
203+
204+
Typing passwords on a phone keyboard is miserable. Codeman replaces it with **cryptographically secure single-use QR tokens** — scan the code displayed on your desktop and your phone is authenticated instantly.
205+
206+
Each QR encodes a URL containing a 6-character short code that maps to a 256-bit secret (`crypto.randomBytes(32)`) on the server. Tokens auto-rotate every **60 seconds**, are **atomically consumed on first scan** (replays always fail), and use **hash-based `Map.get()` lookup** that leaks nothing through response timing. The short code is an opaque pointer — the real secret never appears in browser history, `Referer` headers, or Cloudflare edge logs.
207+
208+
The security design addresses all 6 critical QR auth flaws identified in ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin) (USENIX Security 2025, which found 47 of the top-100 websites vulnerable): single-use enforcement, short TTL, cryptographic randomness, server-side generation, real-time desktop notification on scan (QRLjacking detection), and IP + User-Agent session binding with manual revocation. Dual-layer rate limiting (per-IP + global) makes brute force infeasible across 62^6 = 56.8 billion possible codes. Full security analysis: [`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
209+
210+
---
211+
160212
## Using Codeman — A Human's Guide
161213

162214
A start-to-finish walkthrough for driving Codeman from the browser. If you just installed, this is where to begin.
@@ -223,58 +275,6 @@ Hit start — Codeman spawns the CLI via a real PTY and streams it to your brows
223275
224276
---
225277

226-
## Mobile-Optimized Web UI
227-
228-
The most responsive AI coding agent experience on any phone. Full xterm.js terminal with local echo, swipe navigation, and a touch-optimized interface designed for real remote work — not a desktop UI crammed onto a small screen.
229-
230-
<table>
231-
<tr>
232-
<td align="center" width="40%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="Mobile — answering an agent's plan prompt with the keyboard accessory bar and Enter button" width="300"></td>
233-
<td align="center" width="60%"><img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="Mobile toolbar: accessory bar with /init, /clear, clipboard and Esc above the Run, case, stop, Enter, voice and settings controls" width="440"></td>
234-
</tr>
235-
<tr>
236-
<td align="center"><em>Answering prompts by touch</em></td>
237-
<td align="center"><em>Accessory bar + dedicated Enter button</em></td>
238-
</tr>
239-
</table>
240-
241-
<table>
242-
<tr>
243-
<th>Terminal Apps</th>
244-
<th>Codeman Mobile</th>
245-
</tr>
246-
<tr><td>200-300ms input lag over remote</td><td><b>Local echo — instant feedback</b></td></tr>
247-
<tr><td>Tiny text, no context</td><td>Full xterm.js terminal</td></tr>
248-
<tr><td>No session management</td><td>Swipe between sessions</td></tr>
249-
<tr><td>No notifications</td><td>Push alerts for approvals and idle</td></tr>
250-
<tr><td>Manual reconnect</td><td>tmux persistence</td></tr>
251-
<tr><td>No agent visibility</td><td>Background agents in real-time</td></tr>
252-
<tr><td>Copy-paste slash commands</td><td>One-tap <code>/init</code>, <code>/clear</code>, <code>/compact</code></td></tr>
253-
<tr><td>Password typing on phone</td><td><b>QR code scan — instant auth</b></td></tr>
254-
</table>
255-
256-
- **Keyboard accessory bar** — `/init`, `/clear`, `/compact` quick-action buttons above the virtual keyboard; destructive commands require a double-press to confirm, so you never fire one by accident
257-
- **Dedicated Enter button** — replays the keypress through the terminal, so text buffered by local echo is flushed first rather than stranded
258-
- **Swipe navigation & smart keyboard handling** — swipe left/right to switch sessions; toolbar and terminal shift up when the keyboard opens (`visualViewport` API)
259-
- **Built for phones** — safe-area insets for notch and home indicator, 44px touch targets, bottom-sheet case picker, native momentum scrolling
260-
261-
```bash
262-
codeman web --https
263-
# Open on your phone: https://<your-ip>:3000
264-
```
265-
266-
> `localhost` works over plain HTTP. Use `--https` when accessing from another device, or use [Tailscale](https://tailscale.com/) (recommended) — it provides a private network so you can access `http://<tailscale-ip>:3000` from your phone without TLS certificates.
267-
268-
### Secure QR Code Authentication
269-
270-
Typing passwords on a phone keyboard is miserable. Codeman replaces it with **cryptographically secure single-use QR tokens** — scan the code displayed on your desktop and your phone is authenticated instantly.
271-
272-
Each QR encodes a URL containing a 6-character short code that maps to a 256-bit secret (`crypto.randomBytes(32)`) on the server. Tokens auto-rotate every **60 seconds**, are **atomically consumed on first scan** (replays always fail), and use **hash-based `Map.get()` lookup** that leaks nothing through response timing. The short code is an opaque pointer — the real secret never appears in browser history, `Referer` headers, or Cloudflare edge logs.
273-
274-
The security design addresses all 6 critical QR auth flaws identified in ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin) (USENIX Security 2025, which found 47 of the top-100 websites vulnerable): single-use enforcement, short TTL, cryptographic randomness, server-side generation, real-time desktop notification on scan (QRLjacking detection), and IP + User-Agent session binding with manual revocation. Dual-layer rate limiting (per-IP + global) makes brute force infeasible across 62^6 = 56.8 billion possible codes. Full security analysis: [`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
275-
276-
---
277-
278278
## Live Agent Visualization
279279

280280
Watch background agents work in real-time. Codeman monitors agent activity and displays each agent in a draggable floating window with animated Matrix-style connection lines back to the parent session.

‎README.zh-CN.md‎

Lines changed: 52 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,58 @@ Codeman 依赖 tmux，因此 Windows 用户需要 [WSL](https://learn.microsoft.
147147

148148
---
149149

150+
## 移动端优化的 Web UI
151+
152+
在任意手机上都能获得最跟手的 AI 编程智能体体验。完整的 xterm.js 终端、本地回显、滑动导航，以及为真正的远程办公而设计的触控优化界面 —— 而不是把桌面 UI 硬塞进小屏幕。
153+
154+
<table>
155+
<tr>
156+
<td align="center" width="40%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="移动端 — 通过键盘配件栏与 Enter 按钮回答智能体的方案提示" width="300"></td>
157+
<td align="center" width="60%"><img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="移动端工具栏：配件栏的 /init、/clear、剪贴板与 Esc，下方是 Run、案例、停止、Enter、语音与设置控件" width="440"></td>
158+
</tr>
159+
<tr>
160+
<td align="center"><em>触控回答提示</em></td>
161+
<td align="center"><em>配件栏 + 独立 Enter 按钮</em></td>
162+
</tr>
163+
</table>
164+
165+
<table>
166+
<tr>
167+
<th>普通终端 App</th>
168+
<th>Codeman 移动端</th>
169+
</tr>
170+
<tr><td>远程输入延迟 200–300 毫秒</td><td><b>本地回显 —— 即时反馈</b></td></tr>
171+
<tr><td>字小、无上下文</td><td>完整 xterm.js 终端</td></tr>
172+
<tr><td>无会话管理</td><td>滑动切换会话</td></tr>
173+
<tr><td>无通知</td><td>审批 / 空闲时推送提醒</td></tr>
174+
<tr><td>需手动重连</td><td>tmux 持久化</td></tr>
175+
<tr><td>看不到智能体</td><td>实时查看后台智能体</td></tr>
176+
<tr><td>斜杠命令靠复制粘贴</td><td>一键 <code>/init</code>、<code>/clear</code>、<code>/compact</code></td></tr>
177+
<tr><td>在手机上手打密码</td><td><b>扫二维码 —— 即时认证</b></td></tr>
178+
</table>
179+
180+
- **键盘配件栏** —— 在虚拟键盘上方提供 `/init`、`/clear`、`/compact` 快捷按钮；破坏性命令需双击确认，绝不误触
181+
- **独立的 Enter 按钮** —— 以按键方式回放，先冲刷本地回显缓冲的文本，不会让内容滞留在屏幕上
182+
- **滑动导航与智能键盘处理** —— 左右滑动切换会话；键盘弹出时工具栏与终端整体上移（`visualViewport` API）
183+
- **为手机而生** —— 刘海与 Home 指示条的安全区适配、44px 触控目标、底部抽屉式 case 选择器、原生惯性滚动
184+
185+
```bash
186+
codeman web --https
187+
# 在手机上打开：https://<你的IP>:3000
188+
```
189+
190+
> `localhost` 走纯 HTTP 即可。从其他设备访问时请使用 `--https`，或使用 [Tailscale](https://tailscale.com/)（推荐）—— 它提供私有网络，让你无需 TLS 证书即可从手机访问 `http://<tailscale-ip>:3000`。
191+
192+
### 安全的二维码认证
193+
194+
在手机键盘上输密码太痛苦了。Codeman 用**密码学安全的一次性二维码令牌**取而代之 —— 扫描桌面上显示的二维码，手机即刻完成认证。
195+
196+
每个二维码编码的是一个包含 6 字符短码的 URL，该短码在服务端映射到一个 256 位密钥（`crypto.randomBytes(32)`）。令牌每 **60 秒**自动轮换，**首次扫描即原子性消费**（重放永远失败），并采用**基于哈希的 `Map.get()` 查找**，不会通过响应时延泄露任何信息。短码只是一个不透明指针 —— 真正的密钥永远不会出现在浏览器历史、`Referer` 头或 Cloudflare 边缘日志中。
197+
198+
该安全设计覆盖了 ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin)（USENIX Security 2025，该研究发现 Top-100 网站中有 47 个存在漏洞）所指出的全部 6 个关键二维码认证缺陷：强制一次性使用、短 TTL、密码学随机性、服务端生成、扫描时桌面实时通知（QRLjacking 检测），以及 IP + User-Agent 会话绑定与手动吊销。双层速率限制（按 IP + 全局）使得在 62^6 = 568 亿种可能短码空间内进行暴力破解变得不可行。完整安全分析见：[`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
199+
200+
---
201+
150202
## 使用 Codeman —— 人类操作指南
151203

152204
从头到尾走一遍如何在浏览器里驾驭 Codeman。如果你刚装好，就从这里开始。
@@ -213,58 +265,6 @@ codeman web -H 0.0.0.0 # 绑定局域网 —— 必须设置 CODEMAN_
213265
214266
---
215267

216-
## 移动端优化的 Web UI
217-
218-
在任意手机上都能获得最跟手的 AI 编程智能体体验。完整的 xterm.js 终端、本地回显、滑动导航，以及为真正的远程办公而设计的触控优化界面 —— 而不是把桌面 UI 硬塞进小屏幕。
219-
220-
<table>
221-
<tr>
222-
<td align="center" width="40%"><img src="docs/screenshots/mobile-session-keyboard-20260727.png" alt="移动端 — 通过键盘配件栏与 Enter 按钮回答智能体的方案提示" width="300"></td>
223-
<td align="center" width="60%"><img src="docs/screenshots/mobile-toolbar-enter-20260727.png" alt="移动端工具栏：配件栏的 /init、/clear、剪贴板与 Esc，下方是 Run、案例、停止、Enter、语音与设置控件" width="440"></td>
224-
</tr>
225-
<tr>
226-
<td align="center"><em>触控回答提示</em></td>
227-
<td align="center"><em>配件栏 + 独立 Enter 按钮</em></td>
228-
</tr>
229-
</table>
230-
231-
<table>
232-
<tr>
233-
<th>普通终端 App</th>
234-
<th>Codeman 移动端</th>
235-
</tr>
236-
<tr><td>远程输入延迟 200–300 毫秒</td><td><b>本地回显 —— 即时反馈</b></td></tr>
237-
<tr><td>字小、无上下文</td><td>完整 xterm.js 终端</td></tr>
238-
<tr><td>无会话管理</td><td>滑动切换会话</td></tr>
239-
<tr><td>无通知</td><td>审批 / 空闲时推送提醒</td></tr>
240-
<tr><td>需手动重连</td><td>tmux 持久化</td></tr>
241-
<tr><td>看不到智能体</td><td>实时查看后台智能体</td></tr>
242-
<tr><td>斜杠命令靠复制粘贴</td><td>一键 <code>/init</code>、<code>/clear</code>、<code>/compact</code></td></tr>
243-
<tr><td>在手机上手打密码</td><td><b>扫二维码 —— 即时认证</b></td></tr>
244-
</table>
245-
246-
- **键盘配件栏** —— 在虚拟键盘上方提供 `/init`、`/clear`、`/compact` 快捷按钮；破坏性命令需双击确认，绝不误触
247-
- **独立的 Enter 按钮** —— 以按键方式回放，先冲刷本地回显缓冲的文本，不会让内容滞留在屏幕上
248-
- **滑动导航与智能键盘处理** —— 左右滑动切换会话；键盘弹出时工具栏与终端整体上移（`visualViewport` API）
249-
- **为手机而生** —— 刘海与 Home 指示条的安全区适配、44px 触控目标、底部抽屉式 case 选择器、原生惯性滚动
250-
251-
```bash
252-
codeman web --https
253-
# 在手机上打开：https://<你的IP>:3000
254-
```
255-
256-
> `localhost` 走纯 HTTP 即可。从其他设备访问时请使用 `--https`，或使用 [Tailscale](https://tailscale.com/)（推荐）—— 它提供私有网络，让你无需 TLS 证书即可从手机访问 `http://<tailscale-ip>:3000`。
257-
258-
### 安全的二维码认证
259-
260-
在手机键盘上输密码太痛苦了。Codeman 用**密码学安全的一次性二维码令牌**取而代之 —— 扫描桌面上显示的二维码，手机即刻完成认证。
261-
262-
每个二维码编码的是一个包含 6 字符短码的 URL，该短码在服务端映射到一个 256 位密钥（`crypto.randomBytes(32)`）。令牌每 **60 秒**自动轮换，**首次扫描即原子性消费**（重放永远失败），并采用**基于哈希的 `Map.get()` 查找**，不会通过响应时延泄露任何信息。短码只是一个不透明指针 —— 真正的密钥永远不会出现在浏览器历史、`Referer` 头或 Cloudflare 边缘日志中。
263-
264-
该安全设计覆盖了 ["Demystifying the (In)Security of QR Code-based Login"](https://www.usenix.org/conference/usenixsecurity25/presentation/zhang-xin)（USENIX Security 2025，该研究发现 Top-100 网站中有 47 个存在漏洞）所指出的全部 6 个关键二维码认证缺陷：强制一次性使用、短 TTL、密码学随机性、服务端生成、扫描时桌面实时通知（QRLjacking 检测），以及 IP + User-Agent 会话绑定与手动吊销。双层速率限制（按 IP + 全局）使得在 62^6 = 568 亿种可能短码空间内进行暴力破解变得不可行。完整安全分析见：[`docs/qr-auth-plan.md`](docs/qr-auth-plan.md)
265-
266-
---
267-
268268
## 实时智能体可视化
269269

270270
实时观看后台智能体工作。Codeman 监控智能体活动，将每个智能体显示在一个可拖拽的浮动窗口中，并用「黑客帝国」风格的动态连接线连回父会话。

0 commit comments

Comments
 (0)