@maxiaochao/pi-toolkit 0.2.6 → 0.4.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2026-09-11 - v0.4.0
+
+- bundle the chrome-cdp skill for attaching to a live Chrome with remote debugging (derived from pasky/chrome-cdp-skill, MIT); pi-worktree: add explicit start subcommand and skip dirty-workspace prompt when reusing an existing worktree
+
+## 2026-09-11 - v0.3.0
+
+- add pi-worktree CLI: one-command worktree + Pi launch with list/info/out/remove/prune and bash completion (postinstall to ~/.local/bin)
+
 ## 2026-09-09 - v0.2.6
 
 - fix cache export: segment-view tooltip and event markers now show global request numbers (aligned with the x-axis) instead of relative 1-based; e2e asserts real tooltip values

package/README.md

@@ -1,6 +1,6 @@
 # pi-toolkit
 
-Personal Pi toolkit with the `/todos`, `/btw`, and `/cache_export` extensions, bundled agent skills including Chrome/Chromium automation, and the Night Owl theme.
+Personal Pi toolkit with the `/todos`, `/btw`, and `/cache_export` extensions, bundled agent skills including Chrome/Chromium automation, the Night Owl theme, and the `pi-worktree` CLI.
 
 ## Install
 
@@ -10,7 +10,7 @@ Install the root package to enable the toolkit extensions globally:
 pi install npm:@maxiaochao/pi-toolkit
 ```
 
-The package also provides the `/btw` side-chat extension, the `web-browser` skill for Chrome/Chromium CDP automation, and the `nightowl` theme. On npm installation, the postinstall hook selects `nightowl` only when no theme has been configured yet; an existing Pi theme setting is preserved.
+The package also provides the `/btw` side-chat extension, the `web-browser` and `chrome-cdp` skills for Chrome/Chromium CDP automation, and the `nightowl` theme. On npm installation, the postinstall hook selects `nightowl` only when no theme has been configured yet; an existing Pi theme setting is preserved.
 
 The package postinstall hook synchronizes the bundled global instructions to:
 
@@ -44,6 +44,21 @@ Use `/cache_export [path]` to write an interactive per-request cache dashboard.
 
 The bundled `nightowl` theme is available to Pi through the package manifest and is selected automatically on npm installation only when no theme is already configured.
 
+## pi-worktree CLI
+
+The package also ships a standalone shell command, `pi-worktree`, that wraps Git worktree creation and Pi launch into one step. On installation (Unix-like systems) the postinstall hook copies it to `~/.local/bin/pi-worktree` and installs bash completion to `~/.local/share/bash-completion/completions/pi-worktree` (no `.bashrc` edits needed).
+
+```bash
+pi-worktree start feat-ui  # create/reuse .worktrees/feat-ui, branch feat-ui, launch pi inside
+pi-worktree list           # list worktrees (main checkout marked "main checkout")
+pi-worktree info feat-ui   # base commit, ahead/behind main, unique commits
+pi-worktree out            # open a shell in the main checkout (for merging)
+pi-worktree remove feat-ui # remove the worktree (refuses unmerged branches)
+pi-worktree prune          # drop stale registrations for manually deleted dirs
+```
+
+Typical loop: `pi-worktree start <name>` to start (Tab completes existing worktree names), commit inside Pi, `pi-worktree out` + `git merge <name>` to land the work, `pi-worktree remove <name>` to clean up. New branches are created from `origin/main` (falling back to `main`, then `HEAD`), and the base commit is recorded in `branch.<name>.base` config so `info` can always tell you where the branch came from. Bash completion covers subcommands and existing worktree names (`pi-worktree feat<Tab>`).
+
 The bundled `web-browser` skill provides reusable scripts for starting Chrome/Chromium with remote debugging, navigating tabs, evaluating JavaScript, emulating devices, taking screenshots, dismissing cookie dialogs, and inspecting browser logs. It auto-detects common Chrome/Chromium installations on macOS and Linux, including Windows Chrome when Pi runs under WSL; set `BROWSER_BIN` when the binary is elsewhere.
 
 The browser skill can be loaded explicitly with `/skill:web-browser`. Its scripts are available relative to the skill directory, for example:
@@ -53,6 +68,17 @@ node skills/web-browser/scripts/start.js --headless
 node skills/web-browser/scripts/nav.js https://example.com
 ```
 
+The bundled `chrome-cdp` skill (derived from [pasky/chrome-cdp-skill](https://github.com/pasky/chrome-cdp-skill), MIT) complements `web-browser`: instead of launching an isolated browser, it attaches to a Chrome session that already runs with remote debugging (port pre-allocated at launch, or the `chrome://inspect/#remote-debugging` toggle). It is a zero-dependency CLI (`scripts/cdp.mjs`, Node 22+) with per-tab daemons so Chrome's "Allow debugging" modal fires once:
+
+```bash
+export CDP_PORT_FILE="/mnt/c/Users/<you>/AppData/Local/Google/Chrome/CDP-Profile/DevToolsActivePort"
+node skills/chrome-cdp/scripts/cdp.mjs list          # list open tabs → target prefix
+node skills/chrome-cdp/scripts/cdp.mjs snap <target> # accessibility tree
+node skills/chrome-cdp/scripts/cdp.mjs eval <target> 'document.title'
+```
+
+Note: Chrome does not always write the `DevToolsActivePort` file (e.g. `--remote-debugging-port` launches on Chrome 152); in that case synthesize one from `GET http://127.0.0.1:<port>/json/version` — first line the port, second line the path of `webSocketDebuggerUrl`. WSL auto-discovery of Windows Chrome profiles is not built in; set `CDP_PORT_FILE` as above.
+
 ## Tiny Subagent
 
 The tiny subagent is a separate npm package. Install it independently when you want the `tiny_subagents` tool:

package/bin/pi-worktree

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+# pi-worktree: create/reuse a git worktree, then launch pi inside it.
+#
+# Usage:
+#   pi-worktree start <name> [pi args...]  # enter worktree <name> and start pi
+#   pi-worktree -l | --list                # list worktrees (main checkout marked "main checkout")
+#   pi-worktree -i <name>                  # show base commit, ahead/behind, unique commits
+#   pi-worktree -o | --out                 # cd back to the main checkout
+#   pi-worktree -r <name>                  # remove worktree <name> (must be clean & merged)
+#   pi-worktree -p | --prune               # drop stale worktree registrations
+set -euo pipefail
+
+# Colors: only when stdout is a TTY and NO_COLOR is unset (no-color.org)
+if [[ -t 1 && -z "${NO_COLOR:-}" ]]; then
+  C_BOLD=$'\e[1m' C_DIM=$'\e[2m' C_RED=$'\e[31m' C_GREEN=$'\e[32m' C_YELLOW=$'\e[33m' C_CYAN=$'\e[36m' C_RESET=$'\e[0m'
+else
+  C_BOLD='' C_DIM='' C_RED='' C_GREEN='' C_YELLOW='' C_CYAN='' C_RESET=''
+fi
+
+ok()      { printf '%spi-worktree:%s %s\n' "$C_GREEN" "$C_RESET" "$*"; }
+warn()    { printf '%s⚠️  %s%s\n' "$C_YELLOW" "$C_RESET" "$*"; }
+die()     { printf '%spi-worktree: %s%s\n' "$C_RED" "$C_RESET" "$*" >&2; exit 1; }
+
+require_repo() {
+  git rev-parse --is-inside-work-tree >/dev/null 2>&1 || die "not inside a git repository"
+}
+
+main_checkout() {
+  git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||'
+}
+
+in_linked_worktree() {
+  local git_dir common_dir
+  git_dir=$(git rev-parse --git-dir 2>/dev/null) || return 1
+  common_dir=$(git rev-parse --git-common-dir 2>/dev/null) || return 1
+  [[ "$(cd "$git_dir" && pwd -P)" != "$(cd "$common_dir" && pwd -P)" ]] \
+    && [[ -z "$(git rev-parse --show-superproject-working-tree 2>/dev/null)" ]]
+}
+
+wt_dir() { echo ".worktrees/$1"; }
+
+# Best available base ref: origin/main > main > HEAD
+pick_base() {
+  if git show-ref --verify --quiet refs/remotes/origin/main; then
+    echo origin/main
+  elif git show-ref --verify --quiet refs/heads/main; then
+    echo main
+  else
+    echo HEAD
+  fi
+}
+
+ensure_gitignore() {
+  if ! git check-ignore -q .worktrees 2>/dev/null; then
+    printf '.worktrees/\n' >> .gitignore
+    ok "added .worktrees/ to .gitignore"
+  fi
+}
+
+cmd_list() {
+  require_repo
+  local main_dir; main_dir=$(main_checkout)
+  # Annotate the primary checkout and stale (prunable) entries.
+  git worktree list --porcelain | awk -v main="$main_dir" \
+    -v D="${C_DIM}" -v Y="${C_YELLOW}" -v C="${C_CYAN}" -v R="${C_RESET}" '
+    /^worktree / { path=substr($0,10); next }
+    /^HEAD /     { sha=substr($0,6); next }
+    /^branch /   { b=substr($0,8); sub("refs/heads/","",b); next }
+    /^detached/  { b="(detached)"; next }
+    /^bare/      { b="(bare)"; next }
+    /^prunable/  { stale=1; next }
+    /^$/ {
+      if (b=="") b="?"
+      mark=(path==main) ? "  " D "(main checkout)" R : ""
+      branch=(path==main) ? b : C b R
+      hint=(stale) ? "  " Y "← stale: dir gone, run: pi-worktree prune" R : ""
+      printf "%s  %s%s%s  %s%s%s\n", path, D, substr(sha,1,7), R, branch, mark, hint
+      path=""; sha=""; b=""; stale=0
+    }
+  '
+}
+
+subcmd_prune() {
+  require_repo
+  git worktree prune -v
+  ok "pruned stale worktree registrations"
+}
+
+cmd_out() {
+  cd "$(main_checkout)" && exec "${SHELL:-/bin/bash}"
+}
+
+cmd_info() {
+  require_repo
+  [[ $# -eq 1 ]] || die "usage: pi-worktree -i <name>"
+  local dir; dir="$(wt_dir "$1")"
+  [[ -d "$dir" ]] || die "worktree not found: $dir"
+  local branch; branch=$(git -C "$dir" branch --show-current)
+  echo "worktree: $dir"
+  if git -C "$dir" diff --quiet 2>/dev/null && git -C "$dir" diff --cached --quiet 2>/dev/null \
+     && [[ -z "$(git -C "$dir" ls-files --others --exclude-standard)" ]]; then
+    echo "status:   clean"
+  else
+    echo "status:   DIRTY"
+    git -C "$dir" status --short | head -10
+  fi
+  echo "branch:   $branch @ $(git -C "$dir" rev-parse --short HEAD)"
+  local base baseRef ahead behind
+  base=$(git config --get "branch.$branch.base" 2>/dev/null || true)
+  baseRef=$(git config --get "branch.$branch.baseRef" 2>/dev/null || true)
+  if [[ -n "$base" ]]; then
+    echo "based on: $baseRef @ $base"
+    ahead=$(git rev-list --count "$base..$branch" 2>/dev/null || echo "?")
+    echo "ahead:    $ahead commits since base"
+  else
+    echo "based on: (not recorded; run: git merge-base main $branch)"
+  fi
+  if git show-ref --verify --quiet refs/heads/main && [[ "$branch" != main ]]; then
+    behind=$(git rev-list --count "$branch..main" 2>/dev/null || echo "?")
+    echo "behind:   $behind commits vs main"$([[ "${behind:-0}" -gt 0 ]] && echo "  ← consider rebase")
+  fi
+  if [[ -n "$base" ]]; then
+    echo "unique commits:"
+    git log --oneline "$base..$branch" | head -5 || true
+  fi
+}
+
+cmd_remove() {
+  require_repo
+  [[ $# -eq 1 ]] || die "usage: pi-worktree -r <name>"
+  local dir; dir="$(wt_dir "$1")"
+  [[ -d "$dir" ]] || die "worktree not found: $dir"
+  # refuse to remove if the branch is not merged into main
+  local branch; branch=$(git -C "$dir" branch --show-current)
+  if [[ -n "$branch" ]] && ! git merge-base --is-ancestor "$branch" main 2>/dev/null; then
+    warn "branch '$branch' does not appear merged into 'main' (or no main branch exists)."
+    read -rp "Remove anyway? [y/N] " ans
+    [[ "$ans" =~ ^[Yy]$ ]] || die "aborted"
+  fi
+  git worktree remove "$dir" && ok "removed: $dir"
+}
+
+cd_wt() {
+  local name="$1"; shift
+  require_repo
+
+  # Already isolated? Just launch pi here (superpowers Step 0).
+  if in_linked_worktree; then
+    ok "already in an isolated worktree ($(pwd)), launching pi here"
+    exec pi "$@"
+  fi
+
+  local dir; dir="$(wt_dir "$name")"
+  ensure_gitignore
+
+  if [[ -d "$dir" ]]; then
+    # Reuse: must be a registered worktree for this repo.
+    # Skip the dirty-workspace prompt — the worktree already exists, nothing new to create.
+    git -C "$dir" rev-parse --git-dir >/dev/null 2>&1 || die "$dir exists but is not a git worktree"
+    ok "reusing existing worktree $dir"
+  else
+    # Dirty workspace: uncommitted changes do NOT follow into the new worktree.
+    if ! git diff --quiet || ! git diff --cached --quiet || [[ -n "$(git ls-files --others --exclude-standard)" ]]; then
+      warn "Uncommitted changes stay in THIS directory; they will NOT appear in the worktree:"
+      git status --short | head -20
+      read -rp "Continue? [y/N] " ans
+      [[ "$ans" =~ ^[Yy]$ ]] || die "aborted"
+    fi
+
+    mkdir -p .worktrees
+    # Reuse branch if it exists, else create it
+    if git show-ref --verify --quiet "refs/heads/$name"; then
+      git worktree add "$dir" "$name"
+      ok "checked out existing branch '$name'"
+      # record a best-effort base for -i display
+      local mb; mb=$(git merge-base main "$name" 2>/dev/null || true)
+      [[ -n "$mb" ]] && git config "branch.$name.base" "$(git rev-parse --short "$mb")" \
+        && git config "branch.$name.baseRef" main
+    else
+      local base; base=$(pick_base)
+      git worktree add "$dir" -b "$name" "$base"
+      git config "branch.$name.base" "$(git rev-parse --short "$base")"
+      git config "branch.$name.baseRef" "$base"
+      ok "created branch '$name' from $base @ $(git rev-parse --short "$base")"
+    fi
+  fi
+
+  cd "$dir"
+  exec pi "$@"
+}
+
+case "${1:-}" in
+  -l|--list|list|ls) shift; cmd_list "$@" ;;
+  -i|--info|info) shift; cmd_info "$@" ;;
+  -o|--out|out) shift; cmd_out "$@" ;;
+  -r|--remove|rm|remove) shift; cmd_remove "$@" ;;
+  -p|--prune|prune) shift; subcmd_prune ;;
+  -h|--help|help) sed -n '2,10p' "$0" | sed 's/^# \{0,1\}//' ;;
+  start) shift
+    [[ $# -ge 1 ]] || die "usage: pi-worktree start <name> [pi args...]"
+    name="$1"; shift; cd_wt "$name" "$@" ;;
+  "")  die "usage: pi-worktree start <name> [pi args...]  (or list / info / out / remove / prune)" ;;
+  *)   die "unknown command: $1  (usage: pi-worktree start <name> [pi args...])" ;;
+esac

package/bin/pi-worktree-completion.bash

@@ -0,0 +1,41 @@
+# bash completion for pi-worktree
+_pi_worktree() {
+  local cur first
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  first="${COMP_WORDS[1]}"
+
+  local SUBS="start list ls info out remove rm prune -l --list -i --info -o --out -r --remove -p --prune -h --help"
+
+  # existing worktree names (only linked worktrees, i.e. under .worktrees/)
+  local wts=""
+  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    local main_dir
+    main_dir=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null | sed 's|/.git$||')
+    wts=$(git worktree list --porcelain 2>/dev/null \
+      | sed -n 's|^worktree ||p' \
+      | while read -r p; do [[ "$p" != "$main_dir" ]] && basename "$p"; done || true)
+  fi
+
+  if (( COMP_CWORD == 1 )); then
+    # first word: subcommands, flags, and existing worktree names (to enter)
+    COMPREPLY=($(compgen -W "$SUBS $wts" -- "$cur"))
+    return
+  fi
+
+  case "$first" in
+    -i|--info|info|-r|--remove|remove|rm|start)
+      # only the second word of info/remove completes worktree names;
+      # later words offer nothing (info/remove take no further args)
+      if (( COMP_CWORD == 2 )); then
+        COMPREPLY=($(compgen -W "$wts" -- "$cur"))
+      else
+        COMPREPLY=()
+      fi
+      ;;
+    *)
+      # after a name: default (file) completion for pi args
+      COMPREPLY=()
+      ;;
+  esac
+}
+complete -F _pi_worktree pi-worktree

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.2.6",
+  "version": "0.4.0",
   "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "keywords": [
@@ -10,6 +10,7 @@
   "files": [
     "extensions",
     "themes",
+    "bin",
     "README.md",
     "CHANGELOG.md",
     "global/AGENTS.md",
@@ -33,6 +34,9 @@
       "./themes"
     ]
   },
+  "bin": {
+    "pi-worktree": "bin/pi-worktree"
+  },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",

package/scripts/install-agents.mjs

@@ -1,10 +1,12 @@
 // postinstall hook: sync the bundled global AGENTS.md and seed the default theme
 // without overriding a theme the user has already selected.
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { homedir } from "node:os";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync, chmodSync } from "node:fs";
+import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
 const agentDir = join(homedir(), ".pi", "agent");
 const bundled = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "global", "AGENTS.md"), "utf8");
 const agentsTarget = join(agentDir, "AGENTS.md");
@@ -41,3 +43,22 @@ if (!existsSync(settingsTarget)) {
     console.warn("[pi-toolkit] could not set default theme:", error instanceof Error ? error.message : String(error));
   }
 }
+
+// Install the pi-worktree CLI + bash completion on Unix-like systems.
+// Copy (not symlink) so the running command does not depend on the repo/node_modules layout.
+if (platform() !== "win32") {
+  try {
+    const binTarget = join(homedir(), ".local", "bin", "pi-worktree");
+    mkdirSync(dirname(binTarget), { recursive: true });
+    copyFileSync(join(packageRoot, "bin", "pi-worktree"), binTarget);
+    chmodSync(binTarget, 0o755);
+    console.log("[pi-toolkit] pi-worktree installed ->", binTarget);
+
+    const compTarget = join(homedir(), ".local", "share", "bash-completion", "completions", "pi-worktree");
+    mkdirSync(dirname(compTarget), { recursive: true });
+    copyFileSync(join(packageRoot, "bin", "pi-worktree-completion.bash"), compTarget);
+    console.log("[pi-toolkit] pi-worktree bash completion installed ->", compTarget);
+  } catch (error) {
+    console.warn("[pi-toolkit] could not install pi-worktree CLI:", error instanceof Error ? error.message : String(error));
+  }
+}

package/skills/chrome-cdp/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pasky
+
+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/skills/chrome-cdp/NOTICE

@@ -0,0 +1,2 @@
+chrome-cdp skill is derived from pasky/chrome-cdp-skill
+(https://github.com/pasky/chrome-cdp-skill), MIT License — see LICENSE.

package/skills/chrome-cdp/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: chrome-cdp
+description: Interact with local Chrome browser session (only on explicit user approval after being asked to inspect, debug, or interact with a page open in Chrome)
+---
+
+# Chrome CDP
+
+Lightweight Chrome DevTools Protocol CLI. Connects directly via WebSocket — no Puppeteer, works with 100+ tabs, instant connection.
+
+## Prerequisites
+
+- Chrome (or Chromium, Brave, Edge, Vivaldi) with remote debugging enabled: open `chrome://inspect/#remote-debugging` and toggle the switch
+- Node.js 22+ (uses built-in WebSocket)
+- If your browser's `DevToolsActivePort` is in a non-standard location, set `CDP_PORT_FILE` to its full path
+
+## Commands
+
+All commands use `scripts/cdp.mjs`. The `<target>` is a **unique** targetId prefix from `list`; copy the full prefix shown in the `list` output (for example `6BE827FA`). The CLI rejects ambiguous prefixes.
+
+### List open pages
+
+```bash
+scripts/cdp.mjs list
+```
+
+### Take a screenshot
+
+```bash
+scripts/cdp.mjs shot <target> [file]    # default: screenshot-<target>.png in runtime dir
+```
+
+Captures the **viewport only**. Scroll first with `eval` if you need content below the fold. Output includes the page's DPR and coordinate conversion hint (see **Coordinates** below).
+
+### Accessibility tree snapshot
+
+```bash
+scripts/cdp.mjs snap <target>
+```
+
+### Evaluate JavaScript
+
+```bash
+scripts/cdp.mjs eval <target> <expr>
+```
+
+> **Watch out:** avoid index-based selection (`querySelectorAll(...)[i]`) across multiple `eval` calls when the DOM can change between them (e.g. after clicking Ignore, card indices shift). Collect all data in one `eval` or use stable selectors.
+
+### Other commands
+
+```bash
+scripts/cdp.mjs html    <target> [selector]   # full page or element HTML
+scripts/cdp.mjs nav     <target> <url>         # navigate and wait for load
+scripts/cdp.mjs net     <target>               # resource timing entries
+scripts/cdp.mjs click   <target> <selector>    # click element by CSS selector
+scripts/cdp.mjs clickxy <target> <x> <y>       # click at CSS pixel coords
+scripts/cdp.mjs type    <target> <text>         # Input.insertText at current focus; works in cross-origin iframes unlike eval
+scripts/cdp.mjs loadall <target> <selector> [ms]  # click "load more" until gone (default 1500ms between clicks)
+scripts/cdp.mjs evalraw <target> <method> [json]  # raw CDP command passthrough
+scripts/cdp.mjs open    [url]                  # open new tab (each triggers Allow prompt)
+scripts/cdp.mjs stop    [target]               # stop daemon(s)
+```
+
+## Coordinates
+
+`shot` saves an image at native resolution: image pixels = CSS pixels × DPR. CDP Input events (`clickxy` etc.) take **CSS pixels**.
+
+```
+CSS px = screenshot image px / DPR
+```
+
+`shot` prints the DPR for the current page. Typical Retina (DPR=2): divide screenshot coords by 2.
+
+## Tips
+
+- Prefer `snap --compact` over `html` for page structure.
+- Use `type` (not eval) to enter text in cross-origin iframes — `click`/`clickxy` to focus first, then `type`.
+- Chrome shows an "Allow debugging" modal once per tab on first access. A background daemon keeps the session alive so subsequent commands need no further approval. Daemons auto-exit after 20 minutes of inactivity.

package/skills/chrome-cdp/scripts/cdp.mjs

@@ -0,0 +1,882 @@
+#!/usr/bin/env node
+// cdp - lightweight Chrome DevTools Protocol CLI
+// Uses raw CDP over WebSocket, no Puppeteer dependency.
+// Requires Node 22+ (built-in WebSocket).
+//
+// Per-tab persistent daemon: page commands go through a daemon that holds
+// the CDP session open. Chrome's "Allow debugging" modal fires once per
+// daemon (= once per tab). Daemons auto-exit after 20min idle.
+
+import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { resolve } from 'path';
+import { spawn } from 'child_process';
+import net from 'net';
+
+const TIMEOUT = 15000;
+const NAVIGATION_TIMEOUT = 30000;
+const IDLE_TIMEOUT = 20 * 60 * 1000;
+const DAEMON_CONNECT_RETRIES = 20;
+const DAEMON_CONNECT_DELAY = 300;
+const MIN_TARGET_PREFIX_LEN = 8;
+const IS_WINDOWS = process.platform === 'win32';
+if (!IS_WINDOWS) process.umask(0o077);
+const RUNTIME_DIR = IS_WINDOWS
+  ? resolve(process.env.LOCALAPPDATA || resolve(homedir(), 'AppData', 'Local'), 'cdp')
+  : process.env.XDG_RUNTIME_DIR
+    ? resolve(process.env.XDG_RUNTIME_DIR, 'cdp')
+    : resolve(homedir(), '.cache', 'cdp');
+try { mkdirSync(RUNTIME_DIR, { recursive: true, mode: 0o700 }); } catch {}
+const PAGES_CACHE = resolve(RUNTIME_DIR, 'pages.json');
+
+function sockPath(targetId) {
+  return IS_WINDOWS
+    ? `\\\\.\\pipe\\cdp-${targetId}`
+    : resolve(RUNTIME_DIR, `cdp-${targetId}.sock`);
+}
+
+function getWsUrl() {
+  const home = homedir();
+  // macOS: ~/Library/Application Support/<name>/DevToolsActivePort
+  const macBrowsers = [
+    'Google/Chrome', 'Google/Chrome Beta', 'Google/Chrome for Testing',
+    'Chromium', 'BraveSoftware/Brave-Browser', 'Microsoft Edge',
+  ];
+  // Linux: ~/.config/<name>/DevToolsActivePort
+  const linuxBrowsers = [
+    'google-chrome', 'google-chrome-beta', 'chromium',
+    'vivaldi', 'vivaldi-snapshot',
+    'BraveSoftware/Brave-Browser', 'microsoft-edge',
+  ];
+  // Linux Flatpak: ~/.var/app/<app-id>/config/<name>/DevToolsActivePort
+  const flatpakBrowsers = [
+    ['org.chromium.Chromium', 'chromium'],
+    ['com.google.Chrome', 'google-chrome'],
+    ['com.brave.Browser', 'BraveSoftware/Brave-Browser'],
+    ['com.microsoft.Edge', 'microsoft-edge'],
+    ['com.vivaldi.Vivaldi', 'vivaldi'],
+  ];
+  const candidates = [
+    process.env.CDP_PORT_FILE,
+    ...macBrowsers.flatMap(b => [
+      resolve(home, 'Library/Application Support', b, 'DevToolsActivePort'),
+      resolve(home, 'Library/Application Support', b, 'Default/DevToolsActivePort'),
+    ]),
+    ...linuxBrowsers.flatMap(b => [
+      resolve(home, '.config', b, 'DevToolsActivePort'),
+      resolve(home, '.config', b, 'Default/DevToolsActivePort'),
+    ]),
+    ...flatpakBrowsers.flatMap(([appId, name]) => [
+      resolve(home, '.var/app', appId, 'config', name, 'DevToolsActivePort'),
+      resolve(home, '.var/app', appId, 'config', name, 'Default/DevToolsActivePort'),
+    ]),
+    // Windows: %LOCALAPPDATA%/<name>/User Data/DevToolsActivePort
+    ...(IS_WINDOWS ? ['Google/Chrome', 'BraveSoftware/Brave-Browser', 'Microsoft/Edge'].flatMap(b => {
+      const base = process.env.LOCALAPPDATA || resolve(home, 'AppData/Local');
+      return [
+        resolve(base, b, 'User Data/DevToolsActivePort'),
+        resolve(base, b, 'User Data/Default/DevToolsActivePort'),
+      ];
+    }) : []),
+  ].filter(Boolean);
+  const portFile = candidates.find(p => existsSync(p));
+  if (!portFile) throw new Error('No DevToolsActivePort found. Enable remote debugging at chrome://inspect/#remote-debugging');
+  const lines = readFileSync(portFile, 'utf8').trim().split('\n');
+  if (lines.length < 2 || !lines[0] || !lines[1]) throw new Error(`Invalid DevToolsActivePort file: ${portFile}`);
+  const host = process.env.CDP_HOST || '127.0.0.1';
+  return `ws://${host}:${lines[0]}${lines[1]}`;
+}
+
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+
+function resolvePrefix(prefix, candidates, noun = 'target', missingHint = '') {
+  const upper = prefix.toUpperCase();
+  const matches = candidates.filter(candidate => candidate.toUpperCase().startsWith(upper));
+  if (matches.length === 0) {
+    const hint = missingHint ? ` ${missingHint}` : '';
+    throw new Error(`No ${noun} matching prefix "${prefix}".${hint}`);
+  }
+  if (matches.length > 1) {
+    throw new Error(`Ambiguous prefix "${prefix}" — matches ${matches.length} ${noun}s. Use more characters.`);
+  }
+  return matches[0];
+}
+
+function getDisplayPrefixLength(targetIds) {
+  if (targetIds.length === 0) return MIN_TARGET_PREFIX_LEN;
+  const maxLen = Math.max(...targetIds.map(id => id.length));
+  for (let len = MIN_TARGET_PREFIX_LEN; len <= maxLen; len++) {
+    const prefixes = new Set(targetIds.map(id => id.slice(0, len).toUpperCase()));
+    if (prefixes.size === targetIds.length) return len;
+  }
+  return maxLen;
+}
+
+// ---------------------------------------------------------------------------
+// CDP WebSocket client
+// ---------------------------------------------------------------------------
+
+class CDP {
+  #ws; #id = 0; #pending = new Map(); #eventHandlers = new Map(); #closeHandlers = [];
+
+  async connect(wsUrl) {
+    return new Promise((res, rej) => {
+      this.#ws = new WebSocket(wsUrl);
+      this.#ws.onopen = () => res();
+      this.#ws.onerror = (e) => rej(new Error('WebSocket error: ' + (e.message || e.type)));
+      this.#ws.onclose = () => this.#closeHandlers.forEach(h => h());
+      this.#ws.onmessage = (ev) => {
+        const msg = JSON.parse(ev.data);
+        if (msg.id && this.#pending.has(msg.id)) {
+          const { resolve, reject } = this.#pending.get(msg.id);
+          this.#pending.delete(msg.id);
+          if (msg.error) reject(new Error(msg.error.message));
+          else resolve(msg.result);
+        } else if (msg.method && this.#eventHandlers.has(msg.method)) {
+          for (const handler of [...this.#eventHandlers.get(msg.method)]) {
+            handler(msg.params || {}, msg);
+          }
+        }
+      };
+    });
+  }
+
+  send(method, params = {}, sessionId) {
+    const id = ++this.#id;
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      const msg = { id, method, params };
+      if (sessionId) msg.sessionId = sessionId;
+      this.#ws.send(JSON.stringify(msg));
+      setTimeout(() => {
+        if (this.#pending.has(id)) {
+          this.#pending.delete(id);
+          reject(new Error(`Timeout: ${method}`));
+        }
+      }, TIMEOUT);
+    });
+  }
+
+  onEvent(method, handler) {
+    if (!this.#eventHandlers.has(method)) this.#eventHandlers.set(method, new Set());
+    const handlers = this.#eventHandlers.get(method);
+    handlers.add(handler);
+    return () => {
+      handlers.delete(handler);
+      if (handlers.size === 0) this.#eventHandlers.delete(method);
+    };
+  }
+
+  waitForEvent(method, timeout = TIMEOUT) {
+    let settled = false;
+    let off;
+    let timer;
+    const promise = new Promise((resolve, reject) => {
+      off = this.onEvent(method, (params) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        off();
+        resolve(params);
+      });
+      timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        off();
+        reject(new Error(`Timeout waiting for event: ${method}`));
+      }, timeout);
+    });
+    return {
+      promise,
+      cancel() {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        off?.();
+      },
+    };
+  }
+
+  onClose(handler) { this.#closeHandlers.push(handler); }
+  close() { this.#ws.close(); }
+}
+
+// ---------------------------------------------------------------------------
+// Command implementations — return strings, take (cdp, sessionId)
+// ---------------------------------------------------------------------------
+
+async function getPages(cdp) {
+  const { targetInfos } = await cdp.send('Target.getTargets');
+  return targetInfos.filter(t => t.type === 'page' && !t.url.startsWith('chrome://'));
+}
+
+function formatPageList(pages) {
+  const prefixLen = getDisplayPrefixLength(pages.map(p => p.targetId));
+  return pages.map(p => {
+    const id = p.targetId.slice(0, prefixLen).padEnd(prefixLen);
+    const title = p.title.substring(0, 54).padEnd(54);
+    return `${id}  ${title}  ${p.url}`;
+  }).join('\n');
+}
+
+function shouldShowAxNode(node, compact = false) {
+  const role = node.role?.value || '';
+  const name = node.name?.value ?? '';
+  const value = node.value?.value;
+  if (compact && role === 'InlineTextBox') return false;
+  return role !== 'none' && role !== 'generic' && !(name === '' && (value === '' || value == null));
+}
+
+function formatAxNode(node, depth) {
+  const role = node.role?.value || '';
+  const name = node.name?.value ?? '';
+  const value = node.value?.value;
+  const indent = '  '.repeat(Math.min(depth, 10));
+  let line = `${indent}[${role}]`;
+  if (name !== '') line += ` ${name}`;
+  if (!(value === '' || value == null)) line += ` = ${JSON.stringify(value)}`;
+  return line;
+}
+
+function orderedAxChildren(node, nodesById, childrenByParent) {
+  const children = [];
+  const seen = new Set();
+  for (const childId of node.childIds || []) {
+    const child = nodesById.get(childId);
+    if (child && !seen.has(child.nodeId)) {
+      seen.add(child.nodeId);
+      children.push(child);
+    }
+  }
+  for (const child of childrenByParent.get(node.nodeId) || []) {
+    if (!seen.has(child.nodeId)) {
+      seen.add(child.nodeId);
+      children.push(child);
+    }
+  }
+  return children;
+}
+
+async function snapshotStr(cdp, sid, compact = false) {
+  const { nodes } = await cdp.send('Accessibility.getFullAXTree', {}, sid);
+  const nodesById = new Map(nodes.map(node => [node.nodeId, node]));
+  const childrenByParent = new Map();
+  for (const node of nodes) {
+    if (!node.parentId) continue;
+    if (!childrenByParent.has(node.parentId)) childrenByParent.set(node.parentId, []);
+    childrenByParent.get(node.parentId).push(node);
+  }
+
+  const lines = [];
+  const visited = new Set();
+  function visit(node, depth) {
+    if (!node || visited.has(node.nodeId)) return;
+    visited.add(node.nodeId);
+    if (shouldShowAxNode(node, compact)) lines.push(formatAxNode(node, depth));
+    for (const child of orderedAxChildren(node, nodesById, childrenByParent)) {
+      visit(child, depth + 1);
+    }
+  }
+
+  const roots = nodes.filter(node => !node.parentId || !nodesById.has(node.parentId));
+  for (const root of roots) visit(root, 0);
+  for (const node of nodes) visit(node, 0);
+
+  return lines.join('\n');
+}
+
+async function evalStr(cdp, sid, expression) {
+  await cdp.send('Runtime.enable', {}, sid);
+  const result = await cdp.send('Runtime.evaluate', {
+    expression, returnByValue: true, awaitPromise: true,
+  }, sid);
+  if (result.exceptionDetails) {
+    throw new Error(result.exceptionDetails.text || result.exceptionDetails.exception?.description);
+  }
+  const val = result.result.value;
+  return typeof val === 'object' ? JSON.stringify(val, null, 2) : String(val ?? '');
+}
+
+async function shotStr(cdp, sid, filePath, targetId) {
+  // Get device scale factor so we can report coordinate mapping
+  let dpr = 1;
+  try {
+    const metrics = await cdp.send('Page.getLayoutMetrics', {}, sid);
+    dpr = metrics.visualViewport?.clientWidth
+      ? metrics.cssVisualViewport?.clientWidth
+        ? Math.round((metrics.visualViewport.clientWidth / metrics.cssVisualViewport.clientWidth) * 100) / 100
+        : 1
+      : 1;
+    // Simpler: deviceScaleFactor is on the root Page metrics
+    const { deviceScaleFactor } = await cdp.send('Emulation.getDeviceMetricsOverride', {}, sid).catch(() => ({}));
+    if (deviceScaleFactor) dpr = deviceScaleFactor;
+  } catch {}
+  // Fallback: try to get DPR from JS
+  if (dpr === 1) {
+    try {
+      const raw = await evalStr(cdp, sid, 'window.devicePixelRatio');
+      const parsed = parseFloat(raw);
+      if (parsed > 0) dpr = parsed;
+    } catch {}
+  }
+
+  const { data } = await cdp.send('Page.captureScreenshot', { format: 'png' }, sid);
+  const out = filePath || resolve(RUNTIME_DIR, `screenshot-${(targetId || 'unknown').slice(0, 8)}.png`);
+  writeFileSync(out, Buffer.from(data, 'base64'));
+
+  const lines = [out];
+  lines.push(`Screenshot saved. Device pixel ratio (DPR): ${dpr}`);
+  lines.push(`Coordinate mapping:`);
+  lines.push(`  Screenshot pixels → CSS pixels (for CDP Input events): divide by ${dpr}`);
+  lines.push(`  e.g. screenshot point (${Math.round(100 * dpr)}, ${Math.round(200 * dpr)}) → CSS (100, 200) → use clickxy <target> 100 200`);
+  if (dpr !== 1) {
+    lines.push(`  On this ${dpr}x display: CSS px = screenshot px / ${dpr} ≈ screenshot px × ${Math.round(100/dpr)/100}`);
+  }
+  return lines.join('\n');
+}
+
+async function htmlStr(cdp, sid, selector) {
+  const expr = selector
+    ? `document.querySelector(${JSON.stringify(selector)})?.outerHTML || 'Element not found'`
+    : `document.documentElement.outerHTML`;
+  return evalStr(cdp, sid, expr);
+}
+
+async function waitForDocumentReady(cdp, sid, timeoutMs = NAVIGATION_TIMEOUT) {
+  const deadline = Date.now() + timeoutMs;
+  let lastState = '';
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const state = await evalStr(cdp, sid, 'document.readyState');
+      lastState = state;
+      if (state === 'complete') return;
+    } catch (e) {
+      lastError = e;
+    }
+    await sleep(200);
+  }
+
+  if (lastState) {
+    throw new Error(`Timed out waiting for navigation to finish (last readyState: ${lastState})`);
+  }
+  if (lastError) {
+    throw new Error(`Timed out waiting for navigation to finish (${lastError.message})`);
+  }
+  throw new Error('Timed out waiting for navigation to finish');
+}
+
+async function navStr(cdp, sid, url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+      throw new Error(`Only http/https URLs allowed, got: ${url}`);
+  } catch (e) {
+    if (e.message.startsWith('Only')) throw e;
+    throw new Error(`Invalid URL: ${url}`);
+  }
+  await cdp.send('Page.enable', {}, sid);
+  const loadEvent = cdp.waitForEvent('Page.loadEventFired', NAVIGATION_TIMEOUT);
+  const result = await cdp.send('Page.navigate', { url }, sid);
+  if (result.errorText) {
+    loadEvent.cancel();
+    throw new Error(result.errorText);
+  }
+  if (result.loaderId) {
+    await loadEvent.promise;
+  } else {
+    loadEvent.cancel();
+  }
+  await waitForDocumentReady(cdp, sid, 5000);
+  return `Navigated to ${url}`;
+}
+
+async function netStr(cdp, sid) {
+  const raw = await evalStr(cdp, sid, `JSON.stringify(performance.getEntriesByType('resource').map(e => ({
+    name: e.name.substring(0, 120), type: e.initiatorType,
+    duration: Math.round(e.duration), size: e.transferSize
+  })))`);
+  return JSON.parse(raw).map(e =>
+    `${String(e.duration).padStart(5)}ms  ${String(e.size || '?').padStart(8)}B  ${e.type.padEnd(8)}  ${e.name}`
+  ).join('\n');
+}
+
+// Click element by CSS selector
+async function clickStr(cdp, sid, selector) {
+  if (!selector) throw new Error('CSS selector required');
+  const expr = `
+    (function() {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) return { ok: false, error: 'Element not found: ' + ${JSON.stringify(selector)} };
+      el.scrollIntoView({ block: 'center' });
+      el.click();
+      return { ok: true, tag: el.tagName, text: el.textContent.trim().substring(0, 80) };
+    })()
+  `;
+  const result = await evalStr(cdp, sid, expr);
+  const r = JSON.parse(result);
+  if (!r.ok) throw new Error(r.error);
+  return `Clicked <${r.tag}> "${r.text}"`;
+}
+
+// Click at CSS pixel coordinates using Input.dispatchMouseEvent
+async function clickXyStr(cdp, sid, x, y) {
+  const cx = parseFloat(x);
+  const cy = parseFloat(y);
+  if (isNaN(cx) || isNaN(cy)) throw new Error('x and y must be numbers (CSS pixels)');
+  const base = { x: cx, y: cy, button: 'left', clickCount: 1, modifiers: 0 };
+  await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mouseMoved' }, sid);
+  await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mousePressed' }, sid);
+  await sleep(50);
+  await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mouseReleased' }, sid);
+  return `Clicked at CSS (${cx}, ${cy})`;
+}
+
+// Type text using Input.insertText (works in cross-origin iframes, unlike eval)
+async function typeStr(cdp, sid, text) {
+  if (text == null || text === '') throw new Error('text required');
+  await cdp.send('Input.insertText', { text }, sid);
+  return `Typed ${text.length} characters`;
+}
+
+// Load-more: repeatedly click a button/selector until it disappears
+async function loadAllStr(cdp, sid, selector, intervalMs = 1500) {
+  if (!selector) throw new Error('CSS selector required');
+  let clicks = 0;
+  const deadline = Date.now() + 5 * 60 * 1000; // 5-minute hard cap
+  while (Date.now() < deadline) {
+    const exists = await evalStr(cdp, sid,
+      `!!document.querySelector(${JSON.stringify(selector)})`
+    );
+    if (exists !== 'true') break;
+    const clickExpr = `
+      (function() {
+        const el = document.querySelector(${JSON.stringify(selector)});
+        if (!el) return false;
+        el.scrollIntoView({ block: 'center' });
+        el.click();
+        return true;
+      })()
+    `;
+    const clicked = await evalStr(cdp, sid, clickExpr);
+    if (clicked !== 'true') break;
+    clicks++;
+    await sleep(intervalMs);
+  }
+  return `Clicked "${selector}" ${clicks} time(s) until it disappeared`;
+}
+
+// Send a raw CDP command and return the result as JSON
+async function evalRawStr(cdp, sid, method, paramsJson) {
+  if (!method) throw new Error('CDP method required (e.g. "DOM.getDocument")');
+  let params = {};
+  if (paramsJson) {
+    try { params = JSON.parse(paramsJson); }
+    catch { throw new Error(`Invalid JSON params: ${paramsJson}`); }
+  }
+  const result = await cdp.send(method, params, sid);
+  return JSON.stringify(result, null, 2);
+}
+
+// ---------------------------------------------------------------------------
+// Per-tab daemon
+// ---------------------------------------------------------------------------
+
+async function runDaemon(targetId) {
+  const sp = sockPath(targetId);
+
+  const cdp = new CDP();
+  try {
+    await cdp.connect(getWsUrl());
+  } catch (e) {
+    process.stderr.write(`Daemon: cannot connect to Chrome: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  let sessionId;
+  try {
+    const res = await cdp.send('Target.attachToTarget', { targetId, flatten: true });
+    sessionId = res.sessionId;
+  } catch (e) {
+    process.stderr.write(`Daemon: attach failed: ${e.message}\n`);
+    cdp.close();
+    process.exit(1);
+  }
+
+  // Shutdown helpers
+  let alive = true;
+  function shutdown() {
+    if (!alive) return;
+    alive = false;
+    server.close();
+    if (!IS_WINDOWS) try { unlinkSync(sp); } catch {}
+    cdp.close();
+    process.exit(0);
+  }
+
+  // Exit if target goes away or Chrome disconnects
+  cdp.onEvent('Target.targetDestroyed', (params) => {
+    if (params.targetId === targetId) shutdown();
+  });
+  cdp.onEvent('Target.detachedFromTarget', (params) => {
+    if (params.sessionId === sessionId) shutdown();
+  });
+  cdp.onClose(() => shutdown());
+  process.on('SIGTERM', shutdown);
+  process.on('SIGINT', shutdown);
+
+  // Idle timer
+  let idleTimer = setTimeout(shutdown, IDLE_TIMEOUT);
+  function resetIdle() {
+    clearTimeout(idleTimer);
+    idleTimer = setTimeout(shutdown, IDLE_TIMEOUT);
+  }
+
+  // Handle a command
+  async function handleCommand({ cmd, args }) {
+    resetIdle();
+    try {
+      let result;
+      switch (cmd) {
+        case 'list': {
+          const pages = await getPages(cdp);
+          result = formatPageList(pages);
+          break;
+        }
+        case 'list_raw': {
+          const pages = await getPages(cdp);
+          result = JSON.stringify(pages);
+          break;
+        }
+        case 'snap': case 'snapshot': result = await snapshotStr(cdp, sessionId, true); break;
+        case 'eval': result = await evalStr(cdp, sessionId, args[0]); break;
+        case 'shot': case 'screenshot': result = await shotStr(cdp, sessionId, args[0], targetId); break;
+        case 'html': result = await htmlStr(cdp, sessionId, args[0]); break;
+        case 'nav': case 'navigate': result = await navStr(cdp, sessionId, args[0]); break;
+        case 'net': case 'network': result = await netStr(cdp, sessionId); break;
+        case 'click': result = await clickStr(cdp, sessionId, args[0]); break;
+        case 'clickxy': result = await clickXyStr(cdp, sessionId, args[0], args[1]); break;
+        case 'type': result = await typeStr(cdp, sessionId, args[0]); break;
+        case 'loadall': result = await loadAllStr(cdp, sessionId, args[0], args[1] ? parseInt(args[1]) : 1500); break;
+        case 'evalraw': result = await evalRawStr(cdp, sessionId, args[0], args[1]); break;
+        case 'stop': return { ok: true, result: '', stopAfter: true };
+        default: return { ok: false, error: `Unknown command: ${cmd}` };
+      }
+      return { ok: true, result: result ?? '' };
+    } catch (e) {
+      return { ok: false, error: e.message };
+    }
+  }
+
+  // Unix socket server — NDJSON protocol
+  // Wire format: each message is one JSON object followed by \n (newline-delimited JSON).
+  // Request:  { "id": <number>, "cmd": "<command>", "args": ["arg1", "arg2", ...] }
+  // Response: { "id": <number>, "ok": <boolean>, "result": "<string>" }
+  //           or { "id": <number>, "ok": false, "error": "<message>" }
+  const server = net.createServer((conn) => {
+    let buf = '';
+    conn.on('data', (chunk) => {
+      buf += chunk.toString();
+      const lines = buf.split('\n');
+      buf = lines.pop(); // keep incomplete last line
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        let req;
+        try {
+          req = JSON.parse(line);
+        } catch {
+          conn.write(JSON.stringify({ ok: false, error: 'Invalid JSON request', id: null }) + '\n');
+          continue;
+        }
+        handleCommand(req).then((res) => {
+          const payload = JSON.stringify({ ...res, id: req.id }) + '\n';
+          if (res.stopAfter) conn.end(payload, shutdown);
+          else conn.write(payload);
+        });
+      }
+    });
+  });
+
+  server.on('error', (e) => {
+    process.stderr.write(`Daemon server listen failed: ${e.message}\n`);
+    process.exit(1);
+  });
+
+  if (!IS_WINDOWS) try { unlinkSync(sp); } catch {}
+  server.listen(sp);
+}
+
+// ---------------------------------------------------------------------------
+// CLI ↔ daemon communication
+// ---------------------------------------------------------------------------
+
+function connectToSocket(sp) {
+  return new Promise((resolve, reject) => {
+    const conn = net.connect(sp);
+    conn.on('connect', () => resolve(conn));
+    conn.on('error', reject);
+  });
+}
+
+async function getOrStartTabDaemon(targetId) {
+  const sp = sockPath(targetId);
+  // Try existing daemon
+  try { return await connectToSocket(sp); } catch {}
+
+  // Clean stale socket
+  if (!IS_WINDOWS) try { unlinkSync(sp); } catch {}
+
+  // Spawn daemon
+  const child = spawn(process.execPath, [process.argv[1], '_daemon', targetId], {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+
+  // Wait for socket (includes time for user to click Allow)
+  for (let i = 0; i < DAEMON_CONNECT_RETRIES; i++) {
+    await sleep(DAEMON_CONNECT_DELAY);
+    try { return await connectToSocket(sp); } catch {}
+  }
+  throw new Error('Daemon failed to start — did you click Allow in Chrome?');
+}
+
+function sendCommand(conn, req) {
+  return new Promise((resolve, reject) => {
+    let buf = '';
+    let settled = false;
+
+    const cleanup = () => {
+      conn.off('data', onData);
+      conn.off('error', onError);
+      conn.off('end', onEnd);
+      conn.off('close', onClose);
+    };
+
+    const onData = (chunk) => {
+      buf += chunk.toString();
+      const idx = buf.indexOf('\n');
+      if (idx === -1) return;
+      settled = true;
+      cleanup();
+      resolve(JSON.parse(buf.slice(0, idx)));
+      conn.end();
+    };
+
+    const onError = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+
+    const onEnd = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(new Error('Connection closed before response'));
+    };
+
+    const onClose = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(new Error('Connection closed before response'));
+    };
+
+    conn.on('data', onData);
+    conn.on('error', onError);
+    conn.on('end', onEnd);
+    conn.on('close', onClose);
+    req.id = 1;
+    conn.write(JSON.stringify(req) + '\n');
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Stop daemons
+// ---------------------------------------------------------------------------
+
+async function stopDaemons(targetPrefix) {
+  if (!existsSync(PAGES_CACHE)) return;
+  const pages = JSON.parse(readFileSync(PAGES_CACHE, 'utf8'));
+  const targets = targetPrefix
+    ? [resolvePrefix(targetPrefix, pages.map(p => p.targetId), 'target')]
+    : pages.map(p => p.targetId);
+
+  for (const targetId of targets) {
+    const sp = sockPath(targetId);
+    try {
+      const conn = await connectToSocket(sp);
+      await sendCommand(conn, { cmd: 'stop' });
+    } catch {
+      if (!IS_WINDOWS) try { unlinkSync(sp); } catch {}
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const USAGE = `cdp - lightweight Chrome DevTools Protocol CLI (no Puppeteer)
+
+Usage: cdp <command> [args]
+
+  list                              List open pages (shows unique target prefixes)
+  snap  <target>                    Accessibility tree snapshot
+  eval  <target> <expr>             Evaluate JS expression
+  shot  <target> [file]             Screenshot (default: screenshot-<target>.png in runtime dir); prints coordinate mapping
+  html  <target> [selector]         Get HTML (full page or CSS selector)
+  nav   <target> <url>              Navigate to URL and wait for load completion
+  net   <target>                    Network performance entries
+  click   <target> <selector>       Click an element by CSS selector
+  clickxy <target> <x> <y>          Click at CSS pixel coordinates (see coordinate note below)
+  type    <target> <text>           Type text at current focus via Input.insertText
+                                    Works in cross-origin iframes unlike eval-based approaches
+  loadall <target> <selector> [ms]  Repeatedly click a "load more" button until it disappears
+                                    Optional interval in ms between clicks (default 1500)
+  evalraw <target> <method> [json]  Send a raw CDP command; returns JSON result
+                                    e.g. evalraw <t> "DOM.getDocument" '{}'
+  open  [url]                       Open a new tab (default: about:blank)
+                                    Note: each new tab triggers a fresh "Allow debugging?" prompt
+  stop  [target]                    Stop daemon(s)
+
+<target> is a unique targetId prefix from "cdp list". If a prefix is ambiguous,
+use more characters.
+
+COORDINATE SYSTEM
+  shot captures the viewport at the device's native resolution.
+  The screenshot image size = CSS pixels × DPR (device pixel ratio).
+  For CDP Input events (clickxy, etc.) you need CSS pixels, not image pixels.
+
+    CSS pixels = screenshot image pixels / DPR
+
+  shot prints the DPR and an example conversion for the current page.
+  Typical Retina (DPR=2): CSS px ≈ screenshot px × 0.5
+  If your viewer rescales the image further, account for that scaling too.
+
+EVAL SAFETY NOTE
+  Avoid index-based DOM selection (querySelectorAll(...)[i]) across multiple
+  eval calls when the list can change between calls (e.g. after clicking
+  "Ignore" buttons on a feed — indices shift). Prefer stable selectors or
+  collect all data in a single eval.
+
+DAEMON IPC (for advanced use / scripting)
+  Each tab runs a persistent daemon at Unix socket in the runtime dir (see below).
+  Protocol: newline-delimited JSON (one JSON object per line, UTF-8).
+    Request:  {"id":<number>, "cmd":"<command>", "args":["arg1","arg2",...]}
+    Response: {"id":<number>, "ok":true,  "result":"<string>"}
+           or {"id":<number>, "ok":false, "error":"<message>"}
+  Commands mirror the CLI: snap, eval, shot, html, nav, net, click, clickxy,
+  type, loadall, evalraw, stop. Use evalraw to send arbitrary CDP methods.
+  The socket disappears after 20 min of inactivity or when the tab closes.
+`;
+
+const NEEDS_TARGET = new Set([
+  'snap','snapshot','eval','shot','screenshot','html','nav','navigate',
+  'net','network','click','clickxy','type','loadall','evalraw',
+]);
+
+async function main() {
+  const [cmd, ...args] = process.argv.slice(2);
+
+  // Daemon mode (internal)
+  if (cmd === '_daemon') { await runDaemon(args[0]); return; }
+
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    console.log(USAGE); process.exit(0);
+  }
+
+  if (cmd === 'list' || cmd === 'ls') {
+    const cdp = new CDP();
+    await cdp.connect(getWsUrl());
+    const pages = await getPages(cdp);
+    cdp.close();
+    writeFileSync(PAGES_CACHE, JSON.stringify(pages), { mode: 0o600 });
+    console.log(formatPageList(pages));
+    setTimeout(() => process.exit(0), 100);
+    return;
+  }
+
+  // Open new tab
+  if (cmd === 'open') {
+    const url = args[0] || 'about:blank';
+    const cdp = new CDP();
+    await cdp.connect(getWsUrl());
+    const { targetId } = await cdp.send('Target.createTarget', { url });
+    // Refresh cache; new tab may not appear in getTargets immediately, so add it manually
+    const pages = await getPages(cdp);
+    if (!pages.some(p => p.targetId === targetId)) {
+      pages.push({ targetId, title: url, url });
+    }
+    cdp.close();
+    writeFileSync(PAGES_CACHE, JSON.stringify(pages), { mode: 0o600 });
+    console.log(`Opened new tab: ${targetId.slice(0, 8)}  ${url}`);
+    console.log('Note: this tab will need "Allow debugging?" approval on first access.');
+    return;
+  }
+
+  // Stop
+  if (cmd === 'stop') {
+    await stopDaemons(args[0]);
+    return;
+  }
+
+  // Page commands — need target prefix
+  if (!NEEDS_TARGET.has(cmd)) {
+    console.error(`Unknown command: ${cmd}\n`);
+    console.log(USAGE);
+    process.exit(1);
+  }
+
+  const targetPrefix = args[0];
+  if (!targetPrefix) {
+    console.error('Error: target ID required. Run "cdp list" first.');
+    process.exit(1);
+  }
+
+  // Resolve prefix → full targetId from pages cache
+  if (!existsSync(PAGES_CACHE)) {
+    console.error('No page list cached. Run "cdp list" first.');
+    process.exit(1);
+  }
+  const pages = JSON.parse(readFileSync(PAGES_CACHE, 'utf8'));
+  const targetId = resolvePrefix(targetPrefix, pages.map(p => p.targetId), 'target', 'Run "cdp list".');
+
+  const conn = await getOrStartTabDaemon(targetId);
+
+  const cmdArgs = args.slice(1);
+
+  if (cmd === 'eval') {
+    const expr = cmdArgs.join(' ');
+    if (!expr) { console.error('Error: expression required'); process.exit(1); }
+    cmdArgs[0] = expr;
+  } else if (cmd === 'type') {
+    // Join all remaining args as text (allows spaces)
+    const text = cmdArgs.join(' ');
+    if (!text) { console.error('Error: text required'); process.exit(1); }
+    cmdArgs[0] = text;
+  } else if (cmd === 'evalraw') {
+    // args: [method, ...jsonParts] — join json parts in case of spaces
+    if (!cmdArgs[0]) { console.error('Error: CDP method required'); process.exit(1); }
+    if (cmdArgs.length > 2) cmdArgs[1] = cmdArgs.slice(1).join(' ');
+  }
+
+  if ((cmd === 'nav' || cmd === 'navigate') && !cmdArgs[0]) {
+    console.error('Error: URL required');
+    process.exit(1);
+  }
+
+  const response = await sendCommand(conn, { cmd, args: cmdArgs });
+
+  if (response.ok) {
+    if (response.result) console.log(response.result);
+  } else {
+    console.error('Error:', response.error);
+    process.exitCode = 1;
+  }
+}
+
+main().catch(e => { console.error(e.message); process.exit(1); });