@ohah/agent-devtools 0.1.0

package/bin/agent-devtools.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function getPlatform() {
+  const platform = process.platform;
+  switch (platform) {
+    case "darwin":
+      return "darwin";
+    case "linux":
+      return "linux";
+    case "win32":
+      return "win32";
+    default:
+      throw new Error(`Unsupported platform: ${platform}`);
+  }
+}
+
+function getArch() {
+  const arch = process.arch;
+  switch (arch) {
+    case "arm64":
+      return "arm64";
+    case "x64":
+      return "x64";
+    default:
+      throw new Error(`Unsupported architecture: ${arch}`);
+  }
+}
+
+function getBinaryName(platform, arch) {
+  const ext = platform === "win32" ? ".exe" : "";
+  return `agent-devtools-${platform}-${arch}${ext}`;
+}
+
+const platform = getPlatform();
+const arch = getArch();
+const binaryName = getBinaryName(platform, arch);
+const binaryPath = join(__dirname, binaryName);
+
+if (!existsSync(binaryPath)) {
+  console.error(`Binary not found: ${binaryPath}`);
+  console.error("");
+  console.error("The native binary was not downloaded during installation.");
+  console.error("Try reinstalling:");
+  console.error("  npm install @ohah/agent-devtools");
+  console.error("");
+  console.error("Or build from source:");
+  console.error("  git clone https://github.com/ohah/agent-devtools");
+  console.error("  cd agent-devtools");
+  console.error("  zig build -Doptimize=ReleaseSafe");
+  process.exit(1);
+}
+
+try {
+  execFileSync(binaryPath, process.argv.slice(2), {
+    stdio: "inherit",
+    env: process.env,
+  });
+} catch (error) {
+  if (error.status !== null) {
+    process.exit(error.status);
+  }
+  throw error;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ohah/agent-devtools",
+  "version": "0.1.0",
+  "description": "Browser DevTools CLI for AI agents — web debugging, API reverse engineering, network interception",
+  "type": "module",
+  "files": [
+    "bin",
+    "scripts",
+    "skills",
+    "SKILL.md"
+  ],
+  "bin": {
+    "agent-devtools": "./bin/agent-devtools.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "keywords": [
+    "browser",
+    "automation",
+    "ai",
+    "agent",
+    "devtools",
+    "cdp",
+    "chrome",
+    "testing",
+    "debugging"
+  ],
+  "author": "ohah",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ohah/agent-devtools"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,123 @@
+import { createWriteStream, chmodSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { get as httpsGet } from "node:https";
+import { get as httpGet } from "node:http";
+import { createRequire } from "node:module";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+
+function getPlatform() {
+  switch (process.platform) {
+    case "darwin":
+      return "darwin";
+    case "linux":
+      return "linux";
+    case "win32":
+      return "win32";
+    default:
+      return null;
+  }
+}
+
+function getArch() {
+  switch (process.arch) {
+    case "arm64":
+      return "arm64";
+    case "x64":
+      return "x64";
+    default:
+      return null;
+  }
+}
+
+function getBinaryName(platform, arch) {
+  const ext = platform === "win32" ? ".exe" : "";
+  return `agent-devtools-${platform}-${arch}${ext}`;
+}
+
+function download(url) {
+  return new Promise((resolve, reject) => {
+    const client = url.startsWith("https") ? httpsGet : httpGet;
+    client(url, (response) => {
+      // Follow redirects (GitHub releases redirect to S3)
+      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        download(response.headers.location).then(resolve).catch(reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        reject(new Error(`Download failed with status ${response.statusCode}: ${url}`));
+        return;
+      }
+
+      resolve(response);
+    }).on("error", reject);
+  });
+}
+
+async function main() {
+  const platform = getPlatform();
+  const arch = getArch();
+
+  if (!platform || !arch) {
+    console.warn(`[agent-devtools] Unsupported platform: ${process.platform}-${process.arch}`);
+    console.warn("[agent-devtools] You can build from source: https://github.com/ohah/agent-devtools");
+    process.exit(0);
+  }
+
+  const binaryName = getBinaryName(platform, arch);
+  const binDir = join(__dirname, "..", "bin");
+  const binaryPath = join(binDir, binaryName);
+
+  // Skip if binary already exists (e.g., local development)
+  if (existsSync(binaryPath)) {
+    console.log(`[agent-devtools] Binary already exists: ${binaryName}`);
+    return;
+  }
+
+  const version = pkg.version;
+  const url = `https://github.com/ohah/agent-devtools/releases/download/v${version}/${binaryName}`;
+
+  console.log(`[agent-devtools] Downloading ${binaryName} v${version}...`);
+
+  try {
+    if (!existsSync(binDir)) {
+      mkdirSync(binDir, { recursive: true });
+    }
+
+    const response = await download(url);
+    const file = createWriteStream(binaryPath);
+
+    await new Promise((resolve, reject) => {
+      response.pipe(file);
+      file.on("finish", () => {
+        file.close(resolve);
+      });
+      file.on("error", reject);
+    });
+
+    // Make executable on Unix
+    if (platform !== "win32") {
+      chmodSync(binaryPath, 0o755);
+    }
+
+    console.log(`[agent-devtools] Successfully installed ${binaryName}`);
+  } catch (error) {
+    console.warn(`[agent-devtools] Failed to download binary: ${error.message}`);
+    console.warn("");
+    console.warn("You can build from source instead:");
+    console.warn("  git clone https://github.com/ohah/agent-devtools");
+    console.warn("  cd agent-devtools");
+    console.warn("  zig build -Doptimize=ReleaseSafe");
+    console.warn("");
+    console.warn("Then copy the binary to:");
+    console.warn(`  ${binaryPath}`);
+    // Don't fail the install — the user can still build manually
+    process.exit(0);
+  }
+}
+
+main();

package/skills/agent-devtools/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: agent-devtools
+description: Browser automation and web debugging CLI for AI agents. Use when the user needs to interact with websites, fill forms, click buttons, take screenshots, extract data, test web apps, inspect network traffic, reverse-engineer APIs, intercept requests, or record/diff network flows. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data", "test this web app", "login to a site", "inspect network requests", "find API endpoints", "mock an API", or any task requiring programmatic web interaction.
+allowed-tools: Bash(agent-devtools:*), Bash(./zig-out/bin/agent-devtools:*)
+---
+
+# Browser Automation with agent-devtools
+
+Controls Chrome/Chromium via CDP. Browser persists via background daemon across commands.
+
+## Core Workflow
+
+1. `agent-devtools open <url>` — navigate
+2. `agent-devtools snapshot -i` — get interactive element refs
+3. Use refs (`@e1`, `@e2`) to interact
+4. Re-snapshot after navigation or DOM changes
+
+```bash
+agent-devtools open https://example.com/form
+agent-devtools snapshot -i
+# Output:
+# - textbox "Email" [ref=e1]
+# - textbox "Password" [ref=e2]
+# - button "Submit" [ref=e3]
+
+agent-devtools fill @e1 "user@example.com"
+agent-devtools fill @e2 "password123"
+agent-devtools click @e3
+agent-devtools snapshot -i  # Re-snapshot after submit
+```
+
+**Refs are invalidated on page changes.** Always re-snapshot after clicking links, submitting forms, or loading dynamic content.
+
+## Commands
+
+### Navigation
+```
+open <url>          Navigate (aliases: navigate, goto)
+back / forward      History navigation
+reload              Reload page
+close               Close browser + daemon
+url / title         Get current URL / page title
+```
+
+### Snapshot + Interaction
+```
+snapshot -i         Interactive elements only (recommended)
+snapshot            Full accessibility tree
+click @e1           Click
+dblclick @e1        Double-click
+tap @e1             Touch tap
+fill @e1 "text"     Clear + type
+type @e1 "text"     Type (no clear)
+press Enter         Press key
+hover / focus @e1   Hover or focus
+select @e1 "val"    Select dropdown
+check / uncheck @e1 Checkbox
+scroll down 500     Scroll (up/down/left/right)
+drag @e1 @e2        Drag and drop
+```
+
+### Get Information
+```
+get text/html/value @e1    Element content
+get attr @e1 href          Attribute value
+get url / get title        Page info
+is visible/enabled/checked @e1
+boundingbox @e1            Bounding box {x,y,w,h}
+styles @e1 color           Computed CSS value
+```
+
+### Find Elements (without snapshot)
+```
+find role button           Find by ARIA role
+find text "Submit"         Find by text content
+find label "Email"         Find by label
+```
+
+### Capture & Performance
+```
+screenshot [path]           PNG screenshot
+screenshot --annotate [path] Screenshot with @ref labels overlay
+diff-screenshot <baseline> [current] [--threshold N] [--output path]
+pdf [path]                  Save as PDF
+eval <js>                   Run JavaScript
+video start/stop [path]     Record video (requires FFmpeg)
+trace start/stop [path]     Chrome DevTools trace
+profiler start/stop [path]  CPU profiler
+```
+
+### Network (unique feature)
+```
+network list [pattern]      List requests (filter by URL)
+network get <id>            Full request/response with body
+analyze                     API reverse engineering + schema
+intercept mock "/api" '{}'  Mock response
+intercept fail "/api"       Block request
+intercept delay "/api" 3000 Delay request
+har [file]                  Export HAR 1.2
+```
+
+### Wait
+```
+wait <ms>                   Wait milliseconds
+waitforloadstate [ms]       Wait for page load
+waitfor network <pat> [ms]  Wait for network request
+waitfor console <pat> [ms]  Wait for console message
+waitfor error [ms]          Wait for JS error
+waitdownload [ms]           Wait for download
+```
+
+### Settings
+```
+set viewport 1920 1080     Viewport size
+set media dark             Color scheme
+set timezone Asia/Seoul    Timezone
+set locale ko-KR           Locale
+set device "iPhone 14"     Device emulation
+set useragent "..."        User agent
+set geolocation 37.5 127   Geolocation
+set headers '{"X":"Y"}'    HTTP headers
+set offline on             Offline mode
+set ignore-https-errors    Ignore cert errors
+set permissions grant geo  Grant permission
+```
+
+### Storage & State
+```
+cookies [list/set/get/clear]   Cookies
+storage local [key]            localStorage
+state save/load/list           Save/restore cookies + storage
+credentials <user> <pass>      HTTP basic auth
+```
+
+### Tabs & Console
+```
+tab list / new / close / switch <n>
+console list / clear
+errors [clear]
+dialog accept/dismiss/info
+```
+
+### Recording
+```
+record <name>    Save network state
+diff <name>      Compare current vs recorded
+replay <name>    Navigate + diff
+```
+
+### Auth Vault
+```
+auth save <name> --url <url> --username <user> --password <pass>
+auth login <name>           Auto-login (navigate + fill + submit)
+auth list / show / delete <name>
+```
+
+### Security & Config
+```
+--proxy <url>               Proxy server
+--proxy-bypass <list>       Proxy bypass list
+--extension <path>          Load Chrome extension
+--allowed-domains <list>    Restrict navigation domains
+--content-boundaries        Wrap output with boundary markers
+--auto-connect              Auto-discover running Chrome/Electron
+agent-devtools.json         Config file (project or ~/.agent-devtools/config.json)
+```
+
+## Interactive Mode
+
+`--interactive` for persistent sessions. Events stream automatically.
+
+```bash
+agent-devtools --interactive
+> open https://example.com
+< {"success":true}
+< {"event":"network","url":"https://example.com/","method":"GET","status":200}
+> snapshot -i
+< {"success":true,"data":"- button \"Submit\" [ref=e1]\n"}
+```
+
+## Debug Mode
+
+`--debug` with `--interactive` — action commands automatically include triggered API requests and URL changes. Static resources filtered.
+
+```bash
+agent-devtools --interactive --debug
+> click @e3
+< {"success":true,"debug":{"new_requests":[{"url":"/api/login","method":"POST","status":200}],"url_changed":true}}
+```
+
+## Deep-Dive Documentation
+
+For detailed reference, see `references/`:
+- [commands.md](references/commands.md) — Full command reference
+- [debug-mode.md](references/debug-mode.md) — Debug mode details
+- [patterns.md](references/patterns.md) — Common automation patterns
+
+## Ready-to-Use Templates
+
+Copy and customize these shell scripts from `templates/`:
+- [form-automation.sh](templates/form-automation.sh) — Form fill + submit
+- [authenticated-session.sh](templates/authenticated-session.sh) — Login + state persistence
+- [api-discovery.sh](templates/api-discovery.sh) — API reverse engineering workflow

package/skills/agent-devtools/references/commands.md

@@ -0,0 +1,104 @@
+# Full Command Reference
+
+## Navigation
+| Command | Description |
+|---|---|
+| `open <url>` | Navigate (aliases: navigate, goto) |
+| `back` / `forward` / `reload` | History navigation |
+| `close` | Close browser + daemon |
+| `url` / `title` | Get current URL / title |
+| `content` / `setcontent <html>` | Get/set page HTML |
+| `bringtofront` | Bring window to front |
+
+## Snapshot + Interaction
+| Command | Description |
+|---|---|
+| `snapshot -i` | Interactive elements only (recommended) |
+| `snapshot` | Full accessibility tree |
+| `click` / `dblclick` / `tap @ref` | Click / double-click / touch tap |
+| `fill @ref "text"` | Clear + type |
+| `type @ref "text"` | Type without clearing |
+| `press <key>` | Press key (Enter, Tab, Escape) |
+| `hover` / `focus @ref` | Hover / focus |
+| `check` / `uncheck @ref` | Checkbox |
+| `select @ref "val"` | Dropdown |
+| `clear` / `selectall @ref` | Clear / select all text |
+| `scroll <dir> [px]` | Scroll (up/down/left/right) |
+| `scroll to <x> <y>` | Scroll to coordinates |
+| `scrollintoview @ref` | Scroll element into view |
+| `drag @from @to` | Drag and drop |
+| `upload @ref <file>` | Upload file |
+| `dispatch @ref <event>` | Dispatch DOM event |
+| `highlight @ref` | Highlight with overlay |
+
+## Get Information
+| Command | Description |
+|---|---|
+| `get text/html/value @ref` | Element content |
+| `get attr @ref <name>` | Attribute value |
+| `is visible/enabled/checked @ref` | State check |
+| `boundingbox @ref` | Bounding box |
+| `styles @ref <prop>` | Computed CSS |
+
+## Find Elements
+| Command | Description |
+|---|---|
+| `find role/text/label/placeholder/testid <value>` | Semantic query |
+
+## Capture
+| Command | Description |
+|---|---|
+| `screenshot [path]` | PNG screenshot |
+| `pdf [path]` | PDF export |
+| `eval <js>` | Run JavaScript |
+
+## Network
+| Command | Description |
+|---|---|
+| `network list [pattern]` | List requests |
+| `network get <id>` | Full request/response with body |
+| `network clear` | Clear |
+| `analyze` | API reverse engineering + schema |
+| `intercept mock/fail/delay <pattern>` | Mock/block/delay |
+| `intercept remove/list/clear` | Manage rules |
+| `har [file]` | Export HAR 1.2 |
+
+## Wait
+| Command | Description |
+|---|---|
+| `wait <ms>` | Wait milliseconds |
+| `waitforloadstate [ms]` | Page load |
+| `waitforurl <pat> [ms]` | URL match |
+| `waitforfunction <expr> [ms]` | JS condition |
+| `waitfor network/console/error/dialog [ms]` | Event wait |
+| `waitdownload [ms]` | Download complete |
+
+## Settings
+| Command | Description |
+|---|---|
+| `set viewport/media/offline` | Display settings |
+| `set timezone/locale/geolocation` | Location emulation |
+| `set device/useragent/headers` | Device/network |
+| `set ignore-https-errors` | Cert errors |
+| `set permissions grant <perm>` | Permissions |
+
+## Storage
+| Command | Description |
+|---|---|
+| `cookies list/set/get/clear` | Cookies |
+| `storage local/session [key]` | Web storage |
+| `state save/load/list` | Full state persistence |
+| `credentials <user> <pass>` | HTTP auth |
+
+## Other
+| Command | Description |
+|---|---|
+| `tab list/new/close/switch/count` | Tab management |
+| `console list/clear` | Console messages |
+| `errors [clear]` | Page errors |
+| `dialog accept/dismiss/info` | Dialog handling |
+| `record/diff/replay <name>` | Network recording |
+| `addscript <js>` / `addstyle <css>` | Page injection |
+| `pause` / `resume` | JS debugging |
+| `clipboard get/set` | Clipboard |
+| `status` | Daemon status |

package/skills/agent-devtools/references/debug-mode.md

@@ -0,0 +1,39 @@
+# Debug Mode
+
+## Usage
+```bash
+agent-devtools --interactive --debug
+```
+
+## What it does
+After action commands (click, fill, press, type, select, check, uncheck, tap, hover, drag, dispatch, open), debug mode automatically:
+1. Queries daemon status before the action
+2. Executes the action
+3. Waits 500ms for async effects
+4. Queries status again
+5. If changes detected, fetches details and appends to response
+
+## Response format
+```json
+{
+  "success": true,
+  "debug": {
+    "new_requests": [{"url": "/api/login", "method": "POST", "status": 200}],
+    "new_console": [{"type": "log", "text": "logged in"}],
+    "new_errors": [{"description": "TypeError: ..."}],
+    "url_changed": true
+  }
+}
+```
+
+## Filtering
+- Static resources (JS/CSS/images/fonts) are excluded
+- Tracking pixels (gen_204, client_204) are excluded
+- Only API requests are shown
+
+## When to use
+- **Development**: Use --debug to understand side effects of actions
+- **Testing/CI**: Omit --debug for minimal output and faster execution
+
+## Non-action commands
+snapshot, screenshot, get, is, set, network, console, cookies, eval, wait — these are NOT affected by debug mode.

package/skills/agent-devtools/references/patterns.md

@@ -0,0 +1,82 @@
+# Common Automation Patterns
+
+## Form Submission
+```bash
+agent-devtools open https://example.com/signup
+agent-devtools snapshot -i
+agent-devtools fill @e1 "Jane Doe"
+agent-devtools fill @e2 "jane@example.com"
+agent-devtools select @e3 "California"
+agent-devtools check @e4
+agent-devtools click @e5
+agent-devtools snapshot -i  # Verify result
+```
+
+## Login + State Persistence
+```bash
+agent-devtools open https://app.example.com/login
+agent-devtools snapshot -i
+agent-devtools fill @e1 "user@example.com"
+agent-devtools fill @e2 "password123"
+agent-devtools click @e3
+agent-devtools wait 3000
+agent-devtools state save auth
+
+# Reuse later
+agent-devtools state load auth
+agent-devtools open https://app.example.com/dashboard
+```
+
+## API Discovery
+```bash
+agent-devtools open https://app.example.com
+agent-devtools snapshot -i
+agent-devtools click @e3
+agent-devtools network list /api
+agent-devtools network get <requestId>
+agent-devtools analyze
+```
+
+## Mock API for Testing
+```bash
+agent-devtools intercept mock "/api/users" '[{"id":1,"name":"Test"}]'
+agent-devtools open https://app.example.com/users
+agent-devtools snapshot -i
+agent-devtools intercept clear
+```
+
+## Mobile Device Testing
+```bash
+agent-devtools set device "iPhone 14"
+agent-devtools open https://example.com
+agent-devtools snapshot -i
+agent-devtools tap @e1
+```
+
+## Debug API Calls (--debug mode)
+```bash
+agent-devtools --interactive --debug
+> open https://app.example.com
+> snapshot -i
+> click @e5
+< {"success":true,"debug":{"new_requests":[{"url":"/api/login","method":"POST","status":200}],"url_changed":false}}
+```
+
+## Parallel Sessions
+```bash
+agent-devtools --session=site1 open https://site-a.com
+agent-devtools --session=site2 open https://site-b.com
+agent-devtools --session=site1 snapshot -i
+agent-devtools --session=site2 snapshot -i
+```
+
+## Connect to Existing Chrome
+```bash
+agent-devtools --port=9222 snapshot -i
+```
+
+## E2E Test (CI)
+```bash
+cat tests/login.txt | agent-devtools --interactive
+# exit 0 = pass, exit 1 = fail
+```

package/skills/agent-devtools/templates/api-discovery.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+# Template: API Discovery Workflow
+# Usage: ./api-discovery.sh <app-url>
+set -euo pipefail
+APP_URL="${1:?Usage: $0 <app-url>}"
+
+agent-devtools open "$APP_URL"
+agent-devtools wait 3000
+agent-devtools snapshot -i
+
+# Interact with the app to trigger API calls
+# agent-devtools click @e1
+# agent-devtools wait 2000
+
+# Discover APIs
+echo "=== Network Requests ==="
+agent-devtools network list /api
+
+echo "=== API Analysis ==="
+agent-devtools analyze
+
+echo "=== HAR Export ==="
+agent-devtools har api-capture.har
+
+agent-devtools close