cld-pi 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 smithersai (claude-p)
+Copyright (c) 2026 cld-pi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,180 @@
-# Temporary Holding Version
+# cld-pi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** · [简体中文](./README.zh-CN.md)
+
+An interactive shell around [Claude Code](https://code.claude.com), forked from
+[smithersai/claude-p](https://github.com/smithersai/claude-p).
+
+- `npx cld-pi` with **no arguments** opens Claude Code (fullscreen TUI) inside a
+  thin wrapper that adds prefix completion, overlays and JS plugins on top.
+- `npx cld-pi "prompt"` keeps the original behaviour: a drop-in for `claude -p`.
+
+The wrapper never rewrites Claude Code's output. It forwards every byte,
+mirrors the screen in a [ghostty-vt](https://github.com/ghostty-org/ghostty)
+grid, and paints its own layer on top.
+
+## Run
+
+```sh
+npx cld-pi                               # interactive
+npx cld-pi -r [id]                       # interactive, resume a session (-c: continue)
+npx cld-pi "explain this repo"           # same output as `claude -p`
+npx cld-pi .json "summarize" < diff.txt  # .text / .json / .stream-json = --output-format
+npx cld-pi -r <id> "and now?"            # -p mode in an existing session
+npx cld-pi -a codex                      # wrap another TUI (set pi.arg.prompt / busy / … for its screen)
+```
+
+Requires `claude` on `$PATH`, Node ≥ 18, macOS or Linux.
+
+`npm i -g cld-pi` installs the same thing as the `claude-p` command (and
+`cld-pi`). On first run it prints a one-liner that binds **Ctrl+P** in your
+shell to `claude-p`. Nothing is written to your rc files for you.
+
+Interactive mode forces `/tui fullscreen` and registers `Notification`,
+`Stop` and `SessionStart` hooks through `--settings`; Stop / Notification
+pop a desktop notification (`notify-send`) when the terminal isn't focused, and the
+default `herdry` plugin spins the tab title (`✻ message`) in Yakuake / Konsole / Guake
+(window title elsewhere) until you focus it. It keeps its files in
+`~/claude/-p/`:
+
+| File | What |
+|---|---|
+| `scr` | Plain-text dump of the current screen, refreshed every frame — only while the file exists (`touch` it to turn it on; removed on exit) |
+| `host.log` | Log of the node sidecar — same opt-in: written only if it exists, removed on exit |
+| `inspect` | DevTools URL of the sidecar |
+| `*.js` | Your plugins: `export default pi => { … }` (ES module) |
+
+The `◆ plugins n/m` badge in the top-right corner lists every plugin; click it
+to turn one off — its listeners, `pi.sed`s and timers go away with it. A plugin can
+put its own text there with `pi.notify(msg, 'snack')` (bottom-right: `'snackRD'`);
+the default `pace` plugin shows how long the last ● took and what the last 3 minutes
+cost in the bottom-right corner. Both corners open the plugin list.
+
+## Keys
+
+| Key | In the input box |
+|---|---|
+| `./…` + Tab | fzf over files in CC's current dir → inserts `@path ` (cycles; ctrl-d: the file's folder) |
+| `/~/…` + Tab | same, under `~` |
+| `//…` + Tab | fzf over your Chrome tabs → screenshots the pick, inserts `@/tmp/….png ` |
+| `//gh/…` + Tab | URLs on that site (`gh` → github.com) from your tabs and Chrome history |
+| Ctrl+C | clears the caret's line and the lines below, caret stays on a fresh line; empty box → Claude Code's own Ctrl+C |
+| Ctrl+Enter | paste the clipboard and submit (needs a kitty-protocol or modifyOtherKeys terminal) |
+| Ctrl+P | settings panel: session name + cost, model / effort / mode, file / web permissions (the web toggle also revokes the sites `//` added to `~/.F12-mcp.json`), hide Bash output, CtrlO / CtrlR / Undo / Copy |
+| quitting with Ctrl+C | moves that conversation out of `~/.claude/projects/` to `~/claude/last` (replacing the previous one) and prints `To restore #> mv ~/claude/last …`; an empty session prints nothing (quit with `/exit` to keep it) |
+| mouse wheel | goes to Claude Code untouched; overlays step aside until it stops (`pi.arg.whlSpeed = n`: n notches = one PgUp / PgDn instead) |
+| double click | pages (PgUp / PgDn) the way the wheel last went |
+| click a row ending in `.png` / `.webp` | opens that file in `imv` (`xdg-open` where `imv` is missing); clicks on the input box and the status line still go to CC |
+| Enter on a single line `/~/name` | creates `~/claude/name`; in Yakuake / Guake it opens a new tab and runs `cd … && npx cld-pi` there, elsewhere it copies the command to paste in a new terminal |
+
+## Commands
+
+Typed as a single line in the input box; Claude Code never sees them.
+Every registered name also gets a tiny stub in a throwaway
+`--plugin-dir` (inside claude-p's temp dir, never the project), so it shows
+up in Claude Code's `/` autocomplete as `cldp-pi:<name> (<name>)`.
+
+| Command | |
+|---|---|
+| `/ad <dir>` | `/add-dir` it (confirms the dialog), then `!tree -L 2 <dir>` |
+| `/w` | cloudcli web UI on `:3001` (started in the background if nothing serves it); shows localhost / LAN / tailscale URLs, with buttons to copy the LAN or tailscale URL or show the tailscale one as a QR code (`npx qrcode-terminal`) |
+| `/m` | `~/.local/bin/magpie panel` |
+
+## Chrome
+
+`//` needs remote debugging on in your Chrome: open
+`chrome://inspect/#remote-debugging` and allow it (Chrome 144+; Chrome asks you
+to *Allow* cld-pi once per session). Every site you pick with `//` or `//gh/` is
+added to `allowedUrlPattern` in `~/.F12-mcp.json`, the config of the
+chrome-devtools MCP that lets Claude drive the same browser. The first `//`
+offers its install command:
+
+```sh
+claude mcp add chrome-devtools --scope user -- npx -y chrome-devtools-mcp@latest \
+  --autoConnect --config ~/.F12-mcp.json --watchConfig
+```
+
+Picking a tab types `@/tmp/…png` plus `@/tmp/…f12.md`: the tab's URL, what
+F12 shows (console messages, uncaught exceptions, network errors) and how to
+reach the same tab through the MCP. Plugins, and the F12 inspector, can also
+read a tab live:
+
+```js
+await pi.ext.f12.devtools('https://github.com/', { reload: false, ms: 500 })
+```
+
+`reload: true` reloads the page first, so the console replay starts from the
+fresh page. `target` is a URL, a URL prefix, or a CDP targetId.
+
+`CLAUDE_P_CDP=9222` (a port or a `ws://` URL) connects to another browser instead.
+
+## Plugins
+
+A plugin is an ES module in `~/claude/-p/` exporting a function of `pi`:
+
+```js
+// ~/claude/-p/hello.js
+export default pi => {
+  pi.command('hi', ([name = 'there']) => pi.dialog({ body: `hello ${name}`, timeout: 2000 }))
+  pi.complete('#', tok => ['#bug', '#feat', '#docs'].filter(t => t.startsWith(tok)))
+  pi.on({ CtrlG: () => (pi.BUFFER = 'git status', false) })   // false: skip the default
+  setInterval(() => {}, 60_000)                                 // cleared when turned off
+}
+```
+
+## Debugging plugins (F12)
+
+The node sidecar runs with the inspector on by default, listening on
+`127.0.0.1:9229` (a random port if taken; see `~/claude/-p/inspect`). Open
+`chrome://inspect` → *inspect*, and the global `pi` is there:
+
+```js
+pi`/help`            // type a line into Claude Code + Enter
+pi.BUFFER = 'draft'  // replace the input box text, no Enter (write-only)
+pi.BUFFER=await pi.menu('abc'.split(''))
+
+pi.arg.fzf = "--pointer '▶' --height=60%"   // fzf options for Tab completion
+pi.arg.whlSpeed = 5                          // wheel notches per PgUp / PgDn (0: pass through)
+pi.arg.prompt = '>'   // also border, bash, busy, running: how the TUI's screen reads (CC's by default)
+pi.notify('3 tests left', 'snack')           // text in the top-right badge ('' takes it down)
+pi.notify('busy', 'snackRD', { bg: 236 })    // bottom-right; bg: 0-255, '#rrggbb', 'none'
+await pi.dialog({ title: 'Hi', body: 'gum-style', OK: () => {}, Stat: () => pi`/status` })
+pi.dialog({ body: 'saved', timeout: 3000, or: 'OK', OK: () => {} })   // non-modal, top-right, counts down "(3s)"; ←/→ / click stops the countdown
+pi.sed(ln => ln.includes('secret') ? '' : null)   // blank / rewrite screen rows
+pi.click(row => …)   // a plain click on grid row `row` above the input box (img.js: .png / .webp rows → imv)
+await pi.on.stop      // wait for the next Stop hook
+```
+
+`CLAUDE_P_INSPECT=9223` picks another port. (0=OFF).
+
+> [Refer this](./goal-v1.ts) for more · [goal-v1.ipynb](./goal-v1.ipynb): a `%%js` Jupyter magic that runs these against your session (CDP :9229), with examples
+
+## Roadmap
+
+| Phase | Scope | Status |
+|---|---|---|
+| P0 | Passthrough, ghostty-vt grid, `scr`, hooks, node sidecar | ✅ done |
+| P1 | Input box detection, `./` `/~/` completion, Ctrl+C, path → `cd` | ✅ done |
+| P2 | Overlays (menu / dialog / paint), Ctrl+Enter, `notify-send` | ✅ done |
+| P3 | Plugin API, `/m` `/w` `/ad` | ✅ done |
+| P4 | Ctrl+P settings panel | ✅ done |
+| P5 | Chrome tabs: `//` screenshot, `//gh/` URLs, WebMCP | ✅ done |
+| P6 | Conversation outline WebUI | |
+
+Full design: [goal-v1.md](./goal-v1.md) · plugin API draft: [goal-v1.ts](./goal-v1.ts).
+
+## Build from source
+
+```sh
+mise install            # Zig 0.15.2, pinned in mise.toml
+zig build test          # Zig unit tests
+node --test js/test/*.test.js
+zig build -Doptimize=ReleaseSafe
+./zig-out/bin/claude-p
+```
+
+On Linux the default target is musl (static binary, same as releases).
+
+## License
+
+[MIT](./LICENSE). Based on claude-p by smithersai, also MIT.

package/README.zh-CN.md

@@ -0,0 +1,166 @@
+# cld-pi
+
+[English](./README.md) · **简体中文**
+
+套在 [Claude Code](https://code.claude.com) 外面的交互式外壳，fork 自
+[smithersai/claude-p](https://github.com/smithersai/claude-p)。
+
+- **不带参数**运行 `npx cld-pi`：打开 Claude Code（fullscreen TUI），外面包一层薄壳，
+  提供前缀补全、叠加层和 JS 插件。
+- `npx cld-pi "prompt"`：保持原有行为，可直接替代 `claude -p`。
+
+外壳从不改写 Claude Code 的输出：每个字节原样转发，同时用
+[ghostty-vt](https://github.com/ghostty-org/ghostty) 网格镜像屏幕，自己的内容画在上层。
+
+## 运行
+
+```sh
+npx cld-pi                               # 交互模式
+npx cld-pi -r [id]                       # 交互模式，恢复会话（-c：继续上次）
+npx cld-pi "解释一下这个仓库"              # 输出与 `claude -p` 一致
+npx cld-pi .json "总结" < diff.txt        # .text / .json / .stream-json 即 --output-format
+npx cld-pi -r <id> "接着呢？"              # 在已有会话里以 -p 模式提问
+npx cld-pi -a codex                      # 套别的 TUI（用 pi.arg.prompt / busy / … 描述它的界面）
+```
+
+需要 `$PATH` 里有 `claude`、Node ≥ 18，支持 macOS 和 Linux。
+
+`npm i -g cld-pi` 会安装同一个程序，命令名仍是 `claude-p`（另有 `cld-pi`）。首次运行时
+会打印一行命令，用来在 shell 里把 **Ctrl+P** 绑定为启动 `claude-p`。它只打印，不会替你改
+rc 文件。
+
+交互模式会强制 `/tui fullscreen`，并通过 `--settings` 注入 `Notification`、`Stop`、
+`SessionStart` 三个 hook；Stop / Notification 在终端没有焦点时弹桌面通知（`notify-send`），默认插件
+`herdry` 还会让 Yakuake / Konsole / Guake 的标签标题转起来（`✻ 消息`，其他终端改窗口标题），直到你切回来。相关文件放在 `~/claude/-p/`：
+
+| 文件 | 说明 |
+|---|---|
+| `scr` | 当前屏幕的纯文本快照，每帧刷新；只在文件存在时写（`touch` 一下开启，退出时删除） |
+| `host.log` | node sidecar 的日志；同样存在才写，退出时删除 |
+| `inspect` | sidecar 的 DevTools 地址 |
+| `*.js` | 你的插件：`export default pi => { … }`（ES module） |
+
+右上角的 `◆ plugins n/m` 角标列出所有插件，点它可以关掉某个插件——它注册的监听、`pi.sed` 和定时器会一起撤掉。插件可以用
+`pi.notify(msg, 'snack')` 把自己的文字放到这个位置（右下角用 `'snackRD'`）；默认插件 `pace`
+在右下角显示上一条 ● 的耗时和近 3 分钟的花费。两个角点进去都是插件列表。
+
+## 按键
+
+| 按键 | 在输入框里 |
+|---|---|
+| `./…` + Tab | 用 fzf 选 CC 当前目录下的文件 → 插入 `@路径 `（可循环滚动；ctrl-d：选该文件所在文件夹） |
+| `/~/…` + Tab | 同上，范围是 `~` |
+| `//…` + Tab | 用 fzf 选 Chrome 标签页 → 截图，插入 `@/tmp/….png ` |
+| `//gh/…` + Tab | 补全该站点（`gh` → github.com）的 URL，来源是标签页和 Chrome 历史 |
+| Ctrl+C | 清掉光标所在行及下面的行，光标停在新的空行；输入框为空时交给 Claude Code 自己处理 |
+| 用 Ctrl+C 退出 | 把这次对话从 `~/.claude/projects/` 移到 `~/claude/last`（覆盖上一次的），并打印 `To restore #> mv ~/claude/last …`；空会话不输出；想保留就用 `/exit` 退出 |
+| 鼠标滚轮 | 原样交给 Claude Code，滚动时叠加层让开，停下再画回来（`pi.arg.whlSpeed = n`：改成 n 格一次 PgUp / PgDn） |
+| 双击 | 顺着上次滚轮的方向翻一页（PgUp / PgDn） |
+| 点击以 `.png` / `.webp` 结尾的一行 | 用 `imv` 打开该文件（没有 `imv` 时用 `xdg-open`）；输入框和状态栏上的点击仍交给 CC |
+| Ctrl+Enter | 粘贴剪贴板并提交（终端需支持 kitty 键盘协议或 modifyOtherKeys） |
+| Ctrl+P | 设置面板：会话名和花费、model / effort / mode、file / web 权限（web 开关还会撤销 `//` 加进 `~/.F12-mcp.json` 的站点）、隐藏 Bash 输出、CtrlO / CtrlR / Undo / Copy |
+| 单行输入 `/~/名字` 后回车 | 创建 `~/claude/名字`；Yakuake / Guake 里直接开新 tab 运行 `cd … && npx cld-pi`，其他终端把命令复制到剪贴板，在新终端粘贴即可打开 |
+
+## 命令
+
+在输入框里单独一行输入；Claude Code 看不到这些行。每个注册的名字还会在 claude-p 每次运行的临时 `--plugin-dir` 里放一个很小的 stub（不会碰项目目录），让它在 Claude Code 的 `/` 自动补齐里以 `cldp-pi:<名字> (<名字>)` 出现。
+
+| 命令 | |
+|---|---|
+| `/ad <目录>` | `/add-dir`（自动确认对话框），然后 `!tree -L 2 <目录>` |
+| `/w` | `:3001` 上的 cloudcli Web UI（没有服务就在后台启动），列出 localhost / 局域网 / tailscale 地址；三个按钮：复制局域网地址、复制 tailscale 地址、显示 tailscale 地址的二维码（`npx qrcode-terminal`） |
+| `/m` | `~/.local/bin/magpie panel` |
+
+## Chrome
+
+`//` 需要 Chrome 打开远程调试：访问 `chrome://inspect/#remote-debugging` 并允许
+（Chrome 144+；每次会话 Chrome 会让你点一次 *Allow*）。用 `//` 或 `//gh/` 选过的站点
+会追加到 `~/.F12-mcp.json` 的 `allowedUrlPattern`，这是 chrome-devtools MCP 的配置，
+Claude 通过它操作同一个浏览器。第一次用 `//` 时会提示安装命令：
+
+```sh
+claude mcp add chrome-devtools --scope user -- npx -y chrome-devtools-mcp@latest \
+  --autoConnect --config ~/.F12-mcp.json --watchConfig
+```
+
+选中标签页会输入 `@/tmp/…png` 和 `@/tmp/…f12.md`：后者是标签页 URL、F12 能看到的东西
+（控制台消息、未捕获异常、网络错误）以及如何通过 MCP 找到同一个标签页。插件和 F12 inspector
+也可以实时读取：
+
+```js
+await pi.ext.f12.devtools('https://github.com/', { reload: false, ms: 500 })
+```
+
+`reload: true` 会先刷新页面，让控制台重放从新页面开始。`target` 可以是 URL、URL 前缀或 CDP targetId。
+
+`CLAUDE_P_CDP=9222`（端口或 `ws://` URL）改连别的浏览器。
+
+## 插件
+
+插件是放在 `~/claude/-p/` 的 ES module，默认导出一个接收 `pi` 的函数：
+
+```js
+// ~/claude/-p/hello.js
+export default pi => {
+  pi.command('hi', ([name = 'there']) => pi.dialog({ body: `hello ${name}`, timeout: 2000 }))
+  pi.complete('#', tok => ['#bug', '#feat', '#docs'].filter(t => t.startsWith(tok)))
+  pi.on({ CtrlG: () => (pi.BUFFER = 'git status', false) })   // 返回 false：不走默认行为
+  setInterval(() => {}, 60_000)                                 // 插件被关掉时自动清除
+}
+```
+
+## 调试插件（F12）
+
+[goal-v1.ipynb](./goal-v1.ipynb)：Jupyter 的 `%%js` magic，通过 CDP :9229 在你的会话里执行代码，附整套接口示例。
+
+node sidecar 默认开启 inspector，监听 `127.0.0.1:9229`（被占用时换随机端口，地址见
+`~/claude/-p/inspect`）。打开 `chrome://inspect` → *inspect*，就能直接使用全局变量 `pi`：
+
+```js
+pi`/help`            // type a line into Claude Code + Enter
+pi.BUFFER = 'draft'  // replace the input box text, no Enter (write-only)
+pi.BUFFER=await pi.menu('abc'.split(''))
+
+pi.arg.fzf = "--pointer '▶' --height=60%"   // fzf options for Tab completion
+pi.arg.whlSpeed = 5                          // 几格滚轮算一次 PgUp / PgDn（0：透传）
+pi.arg.prompt = '>'   // 还有 border、bash、busy、running：怎样识别 TUI 的界面（默认是 CC 的）
+pi.notify('3 tests left', 'snack')           // 显示在右上角角标（'' 撤下）
+pi.notify('busy', 'snackRD', { bg: 236 })    // 右下角；bg：0-255、'#rrggbb'、'none'（透明）
+await pi.dialog({ title: 'Hi', body: 'gum-style', OK: () => {}, Stat: () => pi`/status` })
+pi.dialog({ body: 'saved', timeout: 3000, or: 'OK', OK: () => {} })   // 非模态，右上角，正文实时倒计时 "(3s)"；←/→、点击会停止计时
+pi.sed(ln => ln.includes('secret') ? '' : null)   // blank / rewrite screen rows
+pi.click(row => …)   // 点击输入框上方的第 row 行（img.js：点到 .png / .webp 行就用 imv 打开）
+await pi.on.stop      // wait for the next Stop hook
+```
+
+`CLAUDE_P_INSPECT=<端口>` 指定端口，0关掉共享。
+
+## 路线图
+
+| 阶段 | 内容 | 状态 |
+|---|---|---|
+| P0 | 透传、ghostty-vt 网格、`scr`、hook、node sidecar | ✅ 完成 |
+| P1 | 识别输入框、`./` `/~/` 补全、Ctrl+C、输入路径即 `cd` | ✅ 完成 |
+| P2 | 叠加层（菜单 / dialog / 涂抹）、Ctrl+Enter、`notify-send` | ✅ 完成 |
+| P3 | 插件 API，`/m` `/w` `/ad` | ✅ 完成 |
+| P4 | Ctrl+P 设置面板 | ✅ 完成 |
+| P5 | Chrome 标签页：`//` 截图、`//gh/` 补全 URL、WebMCP | ✅ 完成 |
+| P6 | 会话目录 WebUI | |
+
+完整设计见 [goal-v1.md](./goal-v1.md)，插件 API 草案见 [goal-v1.ts](./goal-v1.ts)。
+
+## 从源码构建
+
+```sh
+mise install            # Zig 0.15.2，版本固定在 mise.toml
+zig build test          # Zig 单元测试
+node --test js/test/*.test.js
+zig build -Doptimize=ReleaseSafe
+./zig-out/bin/claude-p
+```
+
+Linux 上默认目标是 musl（静态链接，与发布版相同）。
+
+## 许可证
+
+[MIT](./LICENSE)。基于 smithersai 的 claude-p（同为 MIT）。

package/bin/claude-p.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Thin shim that execs the platform-specific prebuilt `claude-p` binary
+// downloaded by scripts/install.js into ../prebuilt/.
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function platformDir() {
+  const platform = process.platform;
+  const arch = process.arch;
+  return `${platform}-${arch}`;
+}
+
+function binaryPath() {
+  const dir = path.join(__dirname, "..", "prebuilt", platformDir());
+  const name = process.platform === "win32" ? "claude-p.exe" : "claude-p";
+  return path.join(dir, name);
+}
+
+function main() {
+  const bin = binaryPath();
+  if (!fs.existsSync(bin)) {
+    console.error(
+      `claude-p: prebuilt binary not found at ${bin}\n` +
+        `Re-run \`npm install claude-p\` or build from source with \`zig build\`.`,
+    );
+    process.exit(2);
+  }
+  // Tell the binary where the node sidecar (js/host.js) lives.
+  const env = { ...process.env, CLAUDE_P_JS: path.join(__dirname, "..", "js") };
+  const result = spawnSync(bin, process.argv.slice(2), {
+    stdio: "inherit",
+    env,
+  });
+  if (result.error) {
+    console.error("claude-p:", result.error.message);
+    process.exit(2);
+  }
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+    return;
+  }
+  process.exit(result.status ?? 0);
+}
+
+main();

package/js/cdp.js

@@ -0,0 +1,247 @@
+// Chrome DevTools Protocol, stdlib only (global WebSocket: Node 22+), plus
+// where to find the user's Chrome: its DevToolsActivePort (written once
+// remote debugging is allowed in chrome://inspect/#remote-debugging) and its
+// History database.
+import { copyFileSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+/** Chrome's user data dirs, the usual one first. */
+export function chromeDirs(home, platform = process.platform) {
+  if (platform === 'darwin') {
+    const base = join(home, 'Library', 'Application Support')
+    return [join(base, 'Google', 'Chrome'), join(base, 'Google', 'Chrome Beta'), join(base, 'Chromium')]
+  }
+  const base = join(home, '.config')
+  return [join(base, 'google-chrome'), join(base, 'google-chrome-beta'), join(base, 'chromium')]
+}
+
+/** "9222\n/devtools/browser/<id>" → the browser's WebSocket URL. */
+export function activePortUrl(text) {
+  const [port, path] = String(text).split('\n').map(s => s.trim())
+  if (!/^\d+$/.test(port) || !path?.startsWith('/devtools/browser/')) return null
+  return `ws://127.0.0.1:${port}${path}`
+}
+
+/**
+ * Where to connect: `CLAUDE_P_CDP` (a port, http:// or ws:// URL; agent tests
+ * use 9224) or the first Chrome with a DevToolsActivePort. `dir` is that
+ * Chrome's user data dir (for History), null for CLAUDE_P_CDP.
+ */
+export async function findBrowser({ env = process.env, home = env.HOME, platform } = {}) {
+  const pinned = env.CLAUDE_P_CDP
+  if (pinned) {
+    if (/^wss?:/.test(pinned)) return { url: pinned, dir: null }
+    const base = /^\d+$/.test(pinned) ? `http://127.0.0.1:${pinned}` : pinned.replace(/\/$/, '')
+    try {
+      const res = await fetch(`${base}/json/version`, { signal: AbortSignal.timeout(1500) })
+      return { url: (await res.json()).webSocketDebuggerUrl, dir: null }
+    } catch {
+      return null
+    }
+  }
+  for (const dir of chromeDirs(home, platform)) {
+    let text
+    try {
+      text = readFileSync(join(dir, 'DevToolsActivePort'), 'utf8')
+    } catch {
+      continue
+    }
+    const url = activePortUrl(text)
+    if (url) return { url, dir }
+  }
+  return null
+}
+
+/**
+ * Open a CDP connection. `send(method, params, sessionId, ms)` rejects after
+ * `ms` (default 10 s) with `err.timeout` set. Chrome may hold the handshake
+ * until the user clicks Allow, hence the long `ms` here.
+ */
+export function connect(url, ms = 30_000) {
+  return new Promise((resolve, reject) => {
+    if (typeof WebSocket !== 'function') return reject(new Error('needs Node 22+ (global WebSocket)'))
+    const ws = new WebSocket(url)
+    const calls = new Map()
+    const listeners = new Set()
+    let next = 1
+    const cdp = {
+      closed: false,
+      /** Events: fn(method, params, sessionId); returns the unsubscriber. */
+      on(fn) {
+        listeners.add(fn)
+        return () => listeners.delete(fn)
+      },
+      send(method, params = {}, sessionId, ms = 10_000) {
+        if (cdp.closed) return Promise.reject(new Error('CDP connection closed'))
+        const id = next++
+        const msg = { id, method, params }
+        if (sessionId) msg.sessionId = sessionId
+        return new Promise((ok, fail) => {
+          const timer = setTimeout(() => {
+            calls.delete(id)
+            fail(Object.assign(new Error(`${method} timed out`), { timeout: true }))
+          }, ms)
+          calls.set(id, { ok, fail, timer })
+          ws.send(JSON.stringify(msg))
+        })
+      },
+      close: () => ws.close(),
+    }
+    const giveUp = setTimeout(() => {
+      ws.close()
+      reject(new Error(`no answer from ${url}`))
+    }, ms)
+    ws.addEventListener('open', () => {
+      clearTimeout(giveUp)
+      resolve(cdp)
+    })
+    ws.addEventListener('message', e => {
+      const m = JSON.parse(e.data)
+      if (m.id == null && m.method) {
+        for (const fn of listeners) fn(m.method, m.params, m.sessionId)
+        return
+      }
+      const c = calls.get(m.id)
+      if (!c) return
+      calls.delete(m.id)
+      clearTimeout(c.timer)
+      if (m.error) c.fail(new Error(`${m.error.message} (${m.error.code})`))
+      else c.ok(m.result)
+    })
+    const down = () => {
+      clearTimeout(giveUp)
+      cdp.closed = true
+      for (const c of calls.values()) {
+        clearTimeout(c.timer)
+        c.fail(new Error('CDP connection closed'))
+      }
+      calls.clear()
+      reject(new Error(`cannot connect to ${url}`))
+    }
+    ws.addEventListener('close', down)
+    ws.addEventListener('error', down)
+  })
+}
+
+/** The browser's tabs (Target.getTargets, pages only). */
+export async function tabs(cdp) {
+  const { targetInfos } = await cdp.send('Target.getTargets')
+  return targetInfos.filter(t => t.type === 'page' && !t.url.startsWith('devtools://'))
+}
+
+/**
+ * PNG of a tab. A background tab doesn't paint, so a capture that times out
+ * is retried after bringing the tab to the front.
+ */
+export async function screenshot(cdp, targetId, ms = 4000) {
+  const { sessionId } = await cdp.send('Target.attachToTarget', { targetId, flatten: true })
+  const shot = async () => Buffer.from((await cdp.send('Page.captureScreenshot', { format: 'png' }, sessionId, ms)).data, 'base64')
+  try {
+    return await shot()
+  } catch (e) {
+    if (!e.timeout) throw e
+    await cdp.send('Target.activateTarget', { targetId })
+    return await shot()
+  } finally {
+    cdp.send('Target.detachFromTarget', { sessionId }).catch(() => {})
+  }
+}
+
+/**
+ * Reload a tab and wait for its load event (`ms` at most). Detached again
+ * afterwards, so a following `devtools()` sees the fresh page's console from
+ * the start.
+ */
+export async function reload(cdp, targetId, ms = 5000) {
+  const { sessionId } = await cdp.send('Target.attachToTarget', { targetId, flatten: true })
+  try {
+    await cdp.send('Page.enable', {}, sessionId)
+    const loaded = new Promise(done => {
+      const off = cdp.on((method, p, sid) => {
+        if (sid === sessionId && method === 'Page.loadEventFired') {
+          off()
+          done()
+        }
+      })
+      setTimeout(() => {
+        off()
+        done()
+      }, ms)
+    })
+    await cdp.send('Page.reload', {}, sessionId)
+    await loaded
+  } finally {
+    cdp.send('Target.detachFromTarget', { sessionId }).catch(() => {})
+  }
+}
+
+/** A console argument as DevTools prints it, roughly. */
+const show = o => (o.value !== undefined ? (typeof o.value === 'string' ? o.value : JSON.stringify(o.value)) : o.description ?? o.unserializableValue ?? o.type)
+const where = f => (f?.url ? `${f.url}:${(f.lineNumber ?? 0) + 1}` : '')
+
+/**
+ * What F12 would show for a tab: console messages, uncaught exceptions and
+ * the browser's log (network errors, violations). V8 keeps the messages
+ * logged so far and replays them on Runtime.enable, as does Log.enable, so
+ * attaching late still sees them; `ms` is how long to collect the replay.
+ * Entries: { kind: 'console' | 'exception' | 'log', level, text, at }.
+ */
+export async function devtools(cdp, targetId, ms = 300) {
+  const { sessionId } = await cdp.send('Target.attachToTarget', { targetId, flatten: true })
+  const out = []
+  const off = cdp.on((method, p, sid) => {
+    if (sid !== sessionId) return
+    if (method === 'Runtime.consoleAPICalled')
+      out.push({ kind: 'console', level: p.type, text: (p.args ?? []).map(show).join(' '), at: where(p.stackTrace?.callFrames?.[0]) })
+    else if (method === 'Runtime.exceptionThrown') {
+      const d = p.exceptionDetails ?? {}
+      out.push({ kind: 'exception', level: 'error', text: d.exception?.description ?? d.text ?? 'exception', at: where({ url: d.url, lineNumber: d.lineNumber }) })
+    } else if (method === 'Log.entryAdded') {
+      const e = p.entry ?? {}
+      out.push({ kind: 'log', level: e.level, text: `${e.source}: ${e.text}`, at: e.url ?? '' })
+    }
+  })
+  try {
+    await Promise.all([cdp.send('Runtime.enable', {}, sessionId), cdp.send('Log.enable', {}, sessionId)])
+    await new Promise(r => setTimeout(r, ms))
+    return out
+  } finally {
+    off()
+    cdp.send('Target.detachFromTarget', { sessionId }).catch(() => {})
+  }
+}
+
+/**
+ * Recently visited URLs from a Chrome user data dir (its last used profile),
+ * newest first. Read from a copy: Chrome keeps the database open. [] when
+ * there's none or node:sqlite is missing (Node < 22.5).
+ */
+export async function history(dir, limit = 5000) {
+  if (!dir) return []
+  let sqlite
+  try {
+    sqlite = await import('node:sqlite')
+  } catch {
+    return []
+  }
+  let profile = 'Default'
+  try {
+    profile = JSON.parse(readFileSync(join(dir, 'Local State'), 'utf8')).profile?.last_used || profile
+  } catch {}
+  const tmp = mkdtempSync(join(tmpdir(), 'cld-pi-history-'))
+  try {
+    const copy = join(tmp, 'History')
+    copyFileSync(join(dir, profile, 'History'), copy)
+    const db = new sqlite.DatabaseSync(copy, { readOnly: true })
+    try {
+      return db.prepare('SELECT url, title FROM urls ORDER BY last_visit_time DESC LIMIT ?').all(limit)
+    } finally {
+      db.close()
+    }
+  } catch {
+    return []
+  } finally {
+    rmSync(tmp, { recursive: true, force: true })
+  }
+}