@everydaydevopsio/pilot 0.5.2 → 0.6.1

package/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "pilot": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["dist/mcp/index.js"]
+    }
+  }
+}

package/AGENTS.md

@@ -0,0 +1,9 @@
+# Repository agent instructions
+
+## Local Pilot MCP configuration
+
+- Keep `.codex/config.toml` and `.mcp.json` configured to run the compiled local Pilot server with `node dist/mcp/index.js`. Do not replace the local command with the published npm package in this repository.
+- Keep `.codex/config.toml` synchronized with every tool exported by `src/mcp/tools/names.ts`. All listed Pilot tools must remain enabled and use the already-approved approval mode.
+- When adding, renaming, or removing a Pilot MCP tool, update the Codex tool allowlist and verify the Claude `.mcp.json` local-server configuration in the same change.
+- Build Pilot with `pnpm run build` before testing either MCP configuration so `dist/mcp/index.js` reflects the current source.
+- Preserve environment entries needed by the local development session, such as the Linux `DISPLAY` value. Do not assume one display number works on every machine or remote session.

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+## 0.6.0
+
+Agent-oriented browser debugging and interaction release. Adds structured accessibility snapshots, element ref-based interaction, network/console/CSS inspection, file operations, performance tracing, security controls, and existing Chrome connection support.
+
+### New Tools (18)
+
+- **`browser_snapshot`** — Structured accessibility snapshot with element refs (e1, e2, ...)
+- **`browser_find`** — Find elements by role, name, or text
+- **`browser_fill`** — Replace form field value (React/Vue/Svelte compatible)
+- **`browser_hover`** — Hover over element by ref or coordinates
+- **`browser_press_key`** — Press key or combo (Enter, Tab, Control+a, Meta+c)
+- **`browser_select`** — Select option by value, label, or index
+- **`browser_check`** — Toggle checkbox/radio
+- **`browser_scroll`** — Scroll element into view, by direction, or absolute
+- **`browser_network`** — List/get/clear captured network requests with header redaction
+- **`browser_console`** — List/clear console messages with stack traces
+- **`browser_errors`** — List/clear runtime errors and exceptions
+- **`browser_styles`** — Inspect computed styles, CSS rules, and box model
+- **`browser_dialog`** — Handle alert/confirm/prompt dialogs
+- **`browser_upload`** — Upload files with path validation
+- **`browser_downloads`** — Track file downloads (list/wait/clear)
+- **`browser_performance`** — Start/stop tracing; analyze navigation timing, long tasks
+- **`browser_connect`** — Connect to existing Chrome with remote debugging
+- **`browser_tabs`** — Consolidated tab management (list/new/select/close)
+
+### Enhanced Tools
+
+- **`browser_click`** — Now accepts `ref` parameter alongside selector/coordinates
+- **`browser_type`** — Now accepts `ref` parameter alongside selector
+- **`browser_navigate`** — Origin security check before and after navigation (redirect protection)
+
+### Architecture
+
+- Split `src/browser.ts` (799 lines) into cohesive modules under `src/browser/`
+- Element ref system: `ElementRefMap` with generation tracking, `STALE_ELEMENT_REFERENCE` errors
+- Network buffer: ring buffer (~1000 records) with lazy body retrieval and header redaction
+- Runtime exceptions: `Runtime.exceptionThrown` capture with full stack frames
+- CSS inspection: lazy `CSS.enable()` per client via `WeakRef` tracking
+- Dialog queue, download tracker, upload validation with allowed-root security
+- Performance tracing: CDP Tracing + Performance.getMetrics with bounded analysis
+- External Chrome lifecycle: `browser_stop` disconnects without killing external Chrome
+
+### Security
+
+- `PILOT_ALLOWED_ORIGINS` / `PILOT_BLOCKED_ORIGINS` — origin allow/block lists with wildcard support
+- Block wins over allow; scheme-less patterns match host only
+- Post-navigation redirect check — navigate to `about:blank` on violation
+- `PILOT_REDACT_HEADERS` — configurable header redaction (default: Authorization, Cookie, Set-Cookie, X-Api-Key, Proxy-Authorization)
+- `PILOT_UPLOAD_ROOTS` — allowed directories for file uploads
+
+### Backward Compatibility
+
+All 17 original 0.5.x tools remain working unchanged. Legacy tab tools (`browser_list_tabs`, `browser_new_tab`, `browser_close_tab`, `browser_switch_tab`) and error tools (`browser_get_console_logs`, `browser_get_errors`, `browser_clear_errors`) are preserved.
+
+## 0.5.2
+
+- Upgraded Ballast to v5.17.2
+- Fixed headless default behavior
+
+## 0.5.1
+
+- Initial public release

package/CLAUDE.md

@@ -25,7 +25,7 @@ This repository publishes to **npmjs** under the `@everydaydevopsio` scope.
 
 ## Installed agent rules
 
-Created by [Ballast](https://github.com/everydaydevopsio/ballast) v5.9.2. Do not edit this section.
+Created by [Ballast](https://github.com/everydaydevopsio/ballast) v5.17.2. Do not edit this section.
 
 Read and follow these rule files in `.claude/rules/` when they apply:
 
@@ -36,24 +36,24 @@ Read and follow these rule files in `.claude/rules/` when they apply:
 - `.claude/rules/docs.md` — Documentation specialist - GitHub Markdown docs by default, or maintain existing Docusaurus sites with publish-docs automation
 - `.claude/rules/cicd.md` — CI/CD specialist - pipeline design, quality gates, and deployment
 - `.claude/rules/observability.md` — Observability specialist - logging, tracing, metrics, and SLOs
-- `.claude/rules/publishing-api.md` — REST API publishing specialist - Docker CD with Kubernetes health probes and Helm chart update
+- `.claude/rules/publishing-api.md` — REST API publishing specialist - Docker or platform service CD with runtime health checks
 - `.claude/rules/publishing-apps.md` — App publishing specialist - npmjs for Node apps, PyPI for Python apps, GitHub Releases for Go apps
 - `.claude/rules/publishing-apt.md` — APT/deb package publishing specialist - GoReleaser nfpms and GitHub Releases
 - `.claude/rules/publishing-brew.md` — Homebrew tap publishing specialist - GoReleaser brews block and tap repo setup
 - `.claude/rules/publishing-cli.md` — CLI publishing specialist - GoReleaser for Go, npmjs for Node, PyPI for Python
 - `.claude/rules/publishing-libraries.md` — Library publishing specialist - npmjs for TypeScript, PyPI for Python, GitHub tags/releases for Go
 - `.claude/rules/publishing-sdks.md` — SDK publishing specialist - npmjs for TypeScript SDKs, PyPI for Python SDKs, GitHub tags/releases for Go SDKs
-- `.claude/rules/publishing-web.md` — Web app publishing specialist - Docker to GHCR/Docker Hub with Helm chart CD on push to main
+- `.claude/rules/publishing-web.md` — Web app publishing specialist - Docker or platform app CD on push to main
 - `.claude/rules/typescript-linting.md` — TypeScript linting specialist - implements comprehensive linting and code formatting for TypeScript/JavaScript projects
 - `.claude/rules/typescript-logging.md` — Centralized logging specialist - configures Pino with Fluentd for Node/Next.js, and pino-browser to /api/logs
 - `.claude/rules/typescript-testing.md` — Testing specialist - sets up Jest (default) or Vitest for Vite projects, 50% coverage, and test step in build GitHub Action
-- `.claude/rules/git-hooks.md` — Git hook specialist - configure pre-commit, pre-push, and Husky workflows that match the repository layout
-- `.claude/rules/tasks-task-system.md` — Task system integration - use {{taskSystem}} for work items and configure the MCP server
-- `.claude/rules/tasks-todo.md` — Branch-local TODO tracking - manage tasks/TODO.md and triage before PR
+- `.claude/rules/git-hooks.md` — Rules for git-hooks
+- `.claude/rules/tasks-task-system.md` — Task system integration - use the configured work item system and configure MCP when active
+- `.claude/rules/tasks-todo.md` — Branch-local TODO tracking - manage tasks/todo.md and triage before PR
 
 ## Installed skills
 
-Created by [Ballast](https://github.com/everydaydevopsio/ballast) v5.9.2. Do not edit this section.
+Created by [Ballast](https://github.com/everydaydevopsio/ballast) v5.17.2. Do not edit this section.
 
 Read and use these skill files in `.claude/skills/` when they are relevant:
 

package/README.md

@@ -7,9 +7,9 @@
 [![GitHub Release](https://img.shields.io/github/v/release/everydaydevopsio/pilot)](https://github.com/everydaydevopsio/pilot/releases)
 [![npm version](https://img.shields.io/npm/v/@everydaydevopsio/pilot.svg)](https://www.npmjs.com/package/@everydaydevopsio/pilot)
 
-A lightweight Node.js/TypeScript MCP server that gives AI agents DevTools-grade control over a running Chrome instance. Connects to Chrome via the Chrome DevTools Protocol (CDP) and exposes MCP tools for screenshots, navigation, clicks, typing, JavaScript evaluation, and live console/network event monitoring.
+A lightweight Node.js/TypeScript MCP server that gives AI agents DevTools-grade control over a running Chrome instance. Connects to Chrome via the Chrome DevTools Protocol (CDP) and exposes 35 MCP tools for browser automation, inspection, and debugging — including structured accessibility snapshots, element ref-based interaction, network/console/CSS inspection, file operations, performance tracing, and security controls.
 
-Use pilot to open a URL and watch for errors — from any AI agent that speaks MCP.
+Use pilot to open a URL, interact with it using semantic element refs, inspect network traffic, diagnose CSS issues, and watch for errors — all from any AI agent that speaks MCP.
 
 ## Prerequisites
 
@@ -55,6 +55,56 @@ pnpm run build
 pnpm start
 ```
 
+### Linux preflight
+
+Before launching Chrome on Linux, verify the browser environment:
+
+```bash
+pilot check
+```
+
+The command checks that Chrome is executable, the Pilot profile directory is
+writable, an ephemeral CDP port can bind on `127.0.0.1`, outbound HTTPS works,
+and a graphical display is available when `PILOT_HEADLESS=false`.
+
+Visible Chrome requires `DISPLAY` or `WAYLAND_DISPLAY`. On a Linux server or in
+CI, use `PILOT_HEADLESS=true`. To exercise visible-mode behavior without a real
+desktop, run Pilot under Xvfb:
+
+```bash
+xvfb-run -a npx @everydaydevopsio/pilot
+```
+
+#### Remote Linux sessions
+
+When Codex or Claude runs over SSH or in a remote desktop session, the agent's
+MCP process may not inherit the remote display even though applications such as
+`xterm` open successfully. Check the display inside that session with
+`printenv DISPLAY`, forward the value to the Pilot MCP server, and restart the
+agent. With Codex, for example:
+
+```toml
+[mcp_servers.pilot]
+command = "npx"
+args = ["-y", "@everydaydevopsio/pilot"]
+env = { DISPLAY = ":1" }
+```
+
+Replace `:1` with the value from the remote session. Forward `XAUTHORITY` too if
+the X server requires it. For SSH-based display forwarding, start the agent from
+the `ssh -Y` session so it inherits the forwarded display; forwarded display
+values can change between sessions.
+
+Sandboxed environments must allow loopback socket binding for Chrome DevTools.
+An `EPERM` error while binding `127.0.0.1` is a host sandbox or container-policy
+restriction, not a Chrome renderer-sandbox failure. Do not work around it with
+`PILOT_CHROME_NO_SANDBOX=true`; allow loopback binding instead. If the home
+directory is read-only, point profiles at a writable location, for example:
+
+```bash
+export XDG_DATA_HOME=/tmp/pilot-data
+```
+
 ### With Docker
 
 To use the MCP server from a Docker container, pass `-i` so stdin stays open for stdio communication:
@@ -64,6 +114,104 @@ docker build -t pilot .
 claude mcp add pilot -- docker run -i --rm pilot
 ```
 
+## Codex Integration
+
+Codex reads MCP server configuration from `config.toml`. Use
+`~/.codex/config.toml` for a user-level install that follows you across repos,
+or `.codex/config.toml` for a project-level install that applies when Codex is
+started from this trusted repo.
+
+### User-level install
+
+Add pilot to your user Codex config with the Codex CLI:
+
+```bash
+codex mcp add pilot -- npx -y @everydaydevopsio/pilot
+```
+
+Verify the server is configured:
+
+```bash
+codex mcp list
+```
+
+Restart Codex, then run `/mcp` in the Codex TUI to confirm that `pilot` is
+connected.
+
+### Project-level install
+
+To make pilot available for a repo only, add a project-scoped Codex config at
+`.codex/config.toml`. For projects that consume the published package, use the
+portable configuration below:
+
+```toml
+[mcp_servers.pilot]
+command = "npx"
+args = ["-y", "@everydaydevopsio/pilot"]
+```
+
+Project-scoped config is loaded only after you trust the project in Codex. Commit
+`.codex/config.toml` only when it works for all contributors, such as the `npx`
+example above or a repository-relative local build configured by the repository.
+Keep local-build configs with absolute paths in your user config or an
+uncommitted local override.
+
+### Visible Chrome cannot find the Linux display
+
+If desktop applications open normally but `browser_start` reports that
+`DISPLAY` or `WAYLAND_DISPLAY` is missing, the Codex MCP process did not inherit
+the graphical session environment. Check the display used by the desktop
+session:
+
+```bash
+printenv DISPLAY
+```
+
+Forward that value to Pilot in the applicable Codex `config.toml`. For example,
+if the command prints `:1`:
+
+```toml
+[mcp_servers.pilot]
+command = "npx"
+args = ["-y", "@everydaydevopsio/pilot"]
+env = { DISPLAY = ":1" }
+```
+
+Restart Codex after changing the configuration so the Pilot MCP server starts
+with the updated environment. If the graphical session requires an Xauthority
+cookie, forward `XAUTHORITY` in the same `env` map.
+
+### Local build
+
+When developing pilot itself, build the package first and point Codex at the
+compiled server:
+
+This repository commits `.codex/config.toml` with a repository-relative entry
+point. Run the pinned setup before starting Codex from the repository root:
+
+```bash
+make setup
+```
+
+For a local build outside this repository's project config, use an absolute
+path:
+
+```bash
+pnpm run build
+codex mcp add pilot-local -- node /path/to/pilot/dist/mcp/index.js
+```
+
+Or use the equivalent project-scoped config:
+
+```toml
+[mcp_servers.pilot]
+command = "node"
+args = ["/path/to/pilot/dist/mcp/index.js"]
+```
+
+Do not commit project-scoped local-build configs with absolute paths; they are
+machine-specific.
+
 ## Claude Code Integration
 
 Add the MCP server to Claude Code:
@@ -94,49 +242,109 @@ Or add to `.mcp.json` in your project:
 
 **Browser Lifecycle:**
 
-| Tool            | Description   |
-| --------------- | ------------- |
-| `browser_start` | Launch Chrome |
-| `browser_stop`  | Stop Chrome   |
+| Tool              | Description                                         |
+| ----------------- | --------------------------------------------------- |
+| `browser_start`   | Launch Chrome                                       |
+| `browser_stop`    | Stop Chrome (or disconnect from external Chrome)    |
+| `browser_connect` | Connect to an existing Chrome with remote debugging |
+
+**Snapshot & Find:**
+
+| Tool               | Description                                            |
+| ------------------ | ------------------------------------------------------ |
+| `browser_snapshot` | Accessibility snapshot with element refs (e1, e2, ...) |
+| `browser_find`     | Find elements by role, name, or text                   |
+
+**Interaction (ref-based):**
+
+| Tool                | Description                                         |
+| ------------------- | --------------------------------------------------- |
+| `browser_click`     | Click by ref, CSS selector, or coordinates          |
+| `browser_type`      | Type text into ref, selector, or focused element    |
+| `browser_fill`      | Replace field value (React/Vue/Svelte compatible)   |
+| `browser_hover`     | Hover over element by ref or coordinates            |
+| `browser_press_key` | Press key or combo (Enter, Tab, Control+a, etc.)    |
+| `browser_select`    | Select option by value, label, or index             |
+| `browser_check`     | Toggle checkbox/radio                               |
+| `browser_scroll`    | Scroll element into view, by direction, or absolute |
+
+**Inspection:**
+
+| Tool                      | Description                                       |
+| ------------------------- | ------------------------------------------------- |
+| `browser_screenshot`      | Capture viewport or full page screenshot          |
+| `browser_navigate`        | Navigate to URL (with origin security check)      |
+| `browser_evaluate`        | Execute JavaScript and return result              |
+| `browser_wait`            | Wait for selector, network idle, or fixed delay   |
+| `browser_page_info`       | Get current URL, title, and ready state           |
+| `browser_viewport_resize` | Resize the viewport to new dimensions             |
+| `browser_styles`          | Inspect computed styles, CSS rules, and box model |
+
+**Network & Console:**
+
+| Tool              | Description                                   |
+| ----------------- | --------------------------------------------- |
+| `browser_network` | List/get/clear captured network requests      |
+| `browser_console` | List/clear console messages with stack traces |
+| `browser_errors`  | List/clear runtime errors and exceptions      |
+
+**Files & Dialogs:**
 
-**Browser Control:**
+| Tool                | Description                            |
+| ------------------- | -------------------------------------- |
+| `browser_dialog`    | Handle alert/confirm/prompt dialogs    |
+| `browser_upload`    | Upload files to file input elements    |
+| `browser_downloads` | Track file downloads (list/wait/clear) |
 
-| Tool                      | Description                                      |
-| ------------------------- | ------------------------------------------------ |
-| `browser_screenshot`      | Capture viewport or full page screenshot         |
-| `browser_navigate`        | Navigate to URL and wait for load                |
-| `browser_click`           | Click element by CSS selector or coordinates     |
-| `browser_type`            | Type text into focused element or selector       |
-| `browser_evaluate`        | Execute JavaScript and return result             |
-| `browser_wait`            | Wait for selector, network idle, or fixed delay  |
-| `browser_page_info`       | Get current URL, title, and ready state          |
-| `browser_viewport_resize` | Resize the viewport to new dimensions at runtime |
+**Performance:**
 
-**Error Monitoring:**
+| Tool                  | Description                                                              |
+| --------------------- | ------------------------------------------------------------------------ |
+| `browser_performance` | Start/stop tracing; analyze navigation timing, long tasks, slow requests |
+
+**Tab Management:**
+
+| Tool           | Description                               |
+| -------------- | ----------------------------------------- |
+| `browser_tabs` | List/new/select/close tabs (consolidated) |
+
+<details>
+<summary>Legacy tools (backward compatible)</summary>
 
 | Tool                       | Description                                  |
 | -------------------------- | -------------------------------------------- |
+| `browser_list_tabs`        | List all open tabs                           |
+| `browser_new_tab`          | Open a new tab                               |
+| `browser_close_tab`        | Close a tab                                  |
+| `browser_switch_tab`       | Switch to a tab                              |
 | `browser_get_console_logs` | Get buffered console messages with filters   |
 | `browser_get_errors`       | Get console errors (and optionally warnings) |
 | `browser_clear_errors`     | Clear the console message buffer             |
 
+</details>
+
 ## Configuration
 
 All configuration via environment variables.
 
-| Env var                   | Default     | Description                                                                                                                                                                                                                                                          |
-| ------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `PILOT_CDP_PORT`          | `9222`      | CDP port when connecting to an existing Chrome (ignored when `browser_start` launches Chrome)                                                                                                                                                                        |
-| `PILOT_CDP_HOST`          | `127.0.0.1` | CDP host when connecting to an existing Chrome (ignored when `browser_start` launches Chrome)                                                                                                                                                                        |
-| `PILOT_LOG_LEVEL`         | `info`      | Pino log level                                                                                                                                                                                                                                                       |
-| `PILOT_CHROME_PATH`       | (auto)      | Path to Chrome executable                                                                                                                                                                                                                                            |
-| `PILOT_HEADLESS`          | `true`      | Run Chrome headless                                                                                                                                                                                                                                                  |
-| `PILOT_MCP_BUFFER_SIZE`   | `1000`      | Console message buffer size                                                                                                                                                                                                                                          |
-| `PILOT_PROFILE_NAME`      | `profile1`  | Persistent browser profile name. Profiles are stored under `$XDG_DATA_HOME/pilot/<name>` (default `~/.local/share/pilot/<name>`).                                                                                                                                    |
-| `PILOT_RESPONSIVE`        | (preset)    | Responsive viewport mode. When `true`, the page uses real window dimensions and reflows on resize. Desktop presets default to `true`; mobile/tablet presets leave this unset (locked viewport). Set to `false` to lock the viewport with `setDeviceMetricsOverride`. |
-| `PILOT_CHROME_NO_SANDBOX` | (auto)      | Force `--no-sandbox` on/off. Accepts `true`/`1` or `false`/`0`. When unset, the flag is auto-applied only when running as root on Linux. See [Chrome sandbox](#chrome-sandbox) below.                                                                                |
-
-> **Tip — seeing the browser window:** By default Chrome runs headless (no visible window). To watch the browser while the agent works, ask the AI agent: _"set headless to false"_ (or _"run Chrome with a visible window"_). The agent will set `PILOT_HEADLESS=false` before calling `browser_start`, and a Chrome window will appear on your desktop.
+| Env var                   | Default                    | Description                                                                                                                                                                                                                                                          |
+| ------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PILOT_CDP_PORT`          | `9222`                     | CDP port when connecting to an existing Chrome (ignored when `browser_start` launches Chrome)                                                                                                                                                                        |
+| `PILOT_CDP_HOST`          | `127.0.0.1`                | CDP host when connecting to an existing Chrome (ignored when `browser_start` launches Chrome)                                                                                                                                                                        |
+| `PILOT_LOG_LEVEL`         | `info`                     | Pino log level                                                                                                                                                                                                                                                       |
+| `PILOT_CHROME_PATH`       | (auto)                     | Path to Chrome executable                                                                                                                                                                                                                                            |
+| `PILOT_HEADLESS`          | `false`                    | Run Chrome headless. Accepts `true`/`1` or `false`/`0`.                                                                                                                                                                                                              |
+| `PILOT_MCP_BUFFER_SIZE`   | `1000`                     | Console message buffer size                                                                                                                                                                                                                                          |
+| `PILOT_PROFILE_NAME`      | `profile1`                 | Persistent browser profile name. Profiles are stored under `$XDG_DATA_HOME/pilot/<name>` (default `~/.local/share/pilot/<name>`).                                                                                                                                    |
+| `PILOT_RESPONSIVE`        | (preset)                   | Responsive viewport mode. When `true`, the page uses real window dimensions and reflows on resize. Desktop presets default to `true`; mobile/tablet presets leave this unset (locked viewport). Set to `false` to lock the viewport with `setDeviceMetricsOverride`. |
+| `PILOT_CHROME_NO_SANDBOX` | (auto)                     | Force `--no-sandbox` on/off. Accepts `true`/`1` or `false`/`0`. When unset, the flag is auto-applied only when running as root on Linux. See [Chrome sandbox](#chrome-sandbox) below.                                                                                |
+| `PILOT_ALLOWED_ORIGINS`   | (none)                     | Comma-separated origin allow list. Supports wildcards (`*.example.com`). When set, only matching origins can be navigated to.                                                                                                                                        |
+| `PILOT_BLOCKED_ORIGINS`   | (none)                     | Comma-separated origin block list. Block wins over allow. Supports wildcards.                                                                                                                                                                                        |
+| `PILOT_REDACT_HEADERS`    | (defaults)                 | Additional headers to redact in network inspection. Default: Authorization, Cookie, Set-Cookie, X-Api-Key, Proxy-Authorization.                                                                                                                                      |
+| `PILOT_UPLOAD_ROOTS`      | (cwd)                      | Comma-separated allowed directories for file uploads.                                                                                                                                                                                                                |
+| `PILOT_DOWNLOAD_DIR`      | `<tmpdir>/pilot-downloads` | Directory for tracked downloads. Defaults to a `pilot-downloads` subdirectory under the OS temp dir.                                                                                                                                                                 |
+
+> **Tip — running headless:** By default Chrome opens a visible browser window. To run headless (no visible window), set `PILOT_HEADLESS=true` or ask the AI agent: _"set headless to true"_ (or _"run Chrome headless"_). The agent will set `PILOT_HEADLESS=true` before calling `browser_start`.
 
 ### Responsive viewport mode
 
@@ -189,63 +397,68 @@ pnpm run test:e2e:mcp:docker
 
 ```
 src/
-├── browser.ts         # CDP connection + reconnect logic
-├── cli/               # CLI commands
-│   ├── init.ts        # Init command (creates skill)
-│   └── skill-template.ts  # SKILL.md template
-├── commands/          # CDP command implementations
-│   ├── screenshot.ts
-│   ├── navigate.ts
-│   ├── click.ts
-│   ├── type.ts
-│   ├── evaluate.ts
-│   ├── wait.ts
-│   └── page_info.ts
-├── mcp/               # MCP server (sole entry point)
-│   ├── index.ts       # Entry point (stdio)
-│   ├── server.ts      # MCP server setup
-│   ├── console-buffer.ts  # Console message buffer
-│   └── tools/
-│       ├── browser.ts # Browser control tools
-│       └── errors.ts  # Error monitoring tools
-└── util/
-    ├── config.ts      # Configuration loading
-    └── logger.ts      # Pino logger setup
-```
-
-## Claude Code Skill
-
-The `init` command creates a Claude Code skill in your project that automates the browser debugging workflow.
+├── browser.ts              # Backward-compatible re-export barrel
+├── browser/                # Core browser modules
+│   ├── browser-manager.ts  # BrowserManager orchestrator
+│   ├── chrome-launcher.ts  # Chrome process management
+│   ├── connection.ts       # CDP connection + reconnect
+│   ├── events.ts           # CDP event listeners
+│   ├── tabs.ts             # Tab management
+│   ├── types.ts            # Shared types
+│   ├── inspect/            # Snapshot, styles, element refs
+│   ├── interaction/        # Dialogs, uploads, downloads, ref resolver
+│   ├── network/            # Network buffer, monitor, header redaction
+│   ├── performance/        # Tracing + analysis
+│   └── security/           # Origin allow/block lists
+├── cli/                    # CLI commands (init, Linux preflight)
+├── commands/               # Tool command implementations
+├── mcp/                    # MCP server + tool registrations
+└── util/                   # Config, logger
+```
+
+## Pilot Skill for Claude Code and Codex
+
+The `init` command installs a project skill that teaches Claude Code or Codex how
+to run and troubleshoot Pilot.
 
 ### Initialize the Skill
 
 ```bash
 # Using npx (no installation required)
-npx @everydaydevopsio/pilot init
+npx @everydaydevopsio/pilot init --agent claude
+npx @everydaydevopsio/pilot init --agent codex
+
+# Install for both agents
+npx @everydaydevopsio/pilot init --agent both
 
 # If installed globally
-pilot init
+pilot init --agent codex
 
 # Overwrite existing skill
-pilot init --force
+pilot init --agent codex --force
 ```
 
-This creates `.claude/skills/debug-browser/SKILL.md` in your project.
+The Claude target is `.claude/skills/pilot/SKILL.md`; the Codex target is
+`.agents/skills/pilot/SKILL.md`. Omitting `--agent` continues to default to
+Claude for compatibility. Restart the agent after installation if it does not
+detect the skill immediately.
 
 ### Using the Skill
 
-In Claude Code, say **"debug in browser"** or use **/debug-browser**. The skill will:
+Ask Claude or Codex to **"use Pilot to open and debug this page"**, or invoke the
+`pilot` skill explicitly. The skill teaches the agent to:
 
-1. Add the MCP server to your Claude Code session
-2. Call `browser_start` to launch Chrome
-3. Spawn a background sub-agent to watch for console errors
+1. Start Chrome and navigate with the Pilot MCP tools
+2. Use accessibility snapshots and stable element refs for interaction
+3. Inspect console errors, failed requests, styles, and performance data
+4. Diagnose Linux display, profile, Chrome, and loopback preflight failures
 
 ### Error Watching Workflow
 
-1. Ask Claude: "Use pilot to open localhost:3000 and watch for errors"
-2. Claude clears the error buffer and tells you to proceed
+1. Ask the agent: "Use pilot to open localhost:3000 and watch for errors"
+2. The agent clears the error buffer and tells you to proceed
 3. You interact with the app in Chrome
-4. Claude periodically checks for errors and can fix them in your source code
+4. The agent checks for errors and can fix them in your source code
 
 ## License
 

package/dist/browser/browser-manager.d.ts

@@ -0,0 +1,60 @@
+import type { Client } from 'chrome-remote-interface';
+import type { Config } from '../util/config.js';
+import type { ViewportConfig } from '../viewport.js';
+import type { BrowserEventCallback, BrowserState, LaunchOptions, TabInfo } from './types.js';
+export declare class BrowserManager {
+    private readonly config;
+    private client;
+    private targetId;
+    private currentUrl;
+    private retryTimer;
+    private retryMs;
+    private destroyed;
+    private intentionalClose;
+    private eventCallback;
+    private pendingNetworkRequests;
+    private networkIdleTimer;
+    private networkIdleResolvers;
+    private chromeProcess;
+    private launchedCdpPort;
+    private viewportConfig;
+    private launchedUserDataDir;
+    private external;
+    private externalHost;
+    private externalPort;
+    constructor(config: Config);
+    setEventCallback(cb: BrowserEventCallback): void;
+    private emit;
+    getState(): BrowserState;
+    getClient(): Client | null;
+    isConnected(): boolean;
+    isLaunched(): boolean;
+    isExternalChrome(): boolean;
+    getViewportConfig(): ViewportConfig | null;
+    setViewportConfig(config: ViewportConfig): void;
+    static findChromeExecutable(override?: string): string;
+    static findFreePort(): Promise<number>;
+    private getConnectionInfo;
+    private makeEventListenerOpts;
+    launch(opts?: LaunchOptions): Promise<{
+        headless: boolean;
+        viewport: string;
+    }>;
+    connect(): Promise<void>;
+    connectExisting(opts: {
+        host?: string;
+        port?: number;
+    }): Promise<{
+        tabs: TabInfo[];
+    }>;
+    private checkNetworkIdle;
+    waitForNetworkIdle(timeoutMs?: number): Promise<void>;
+    listTabs(): Promise<TabInfo[]>;
+    createTab(url?: string): Promise<TabInfo>;
+    closeTab(targetId: string): Promise<void>;
+    switchTab(targetId: string): Promise<void>;
+    private scheduleReconnect;
+    private cleanupUserDataDir;
+    destroy(): Promise<void>;
+}
+//# sourceMappingURL=browser-manager.d.ts.map

package/dist/browser/browser-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-manager.d.ts","sourceRoot":"","sources":["../../src/browser/browser-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAItD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,KAAK,EACV,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,OAAO,EACR,MAAM,YAAY,CAAC;AAyBpB,qBAAa,cAAc;IAoBb,OAAO,CAAC,QAAQ,CAAC,MAAM;IAnBnC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,aAAa,CAAqC;IAC1D,OAAO,CAAC,sBAAsB,CAAqB;IACnD,OAAO,CAAC,gBAAgB,CAA8C;IACtE,OAAO,CAAC,oBAAoB,CAAyB;IACrD,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,mBAAmB,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,YAAY,CAAuB;gBAEd,MAAM,EAAE,MAAM;IAI3C,gBAAgB,CAAC,EAAE,EAAE,oBAAoB,GAAG,IAAI;IAIhD,OAAO,CAAC,IAAI;IAIZ,QAAQ,IAAI,YAAY;IASxB,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B,WAAW,IAAI,OAAO;IAItB,UAAU,IAAI,OAAO;IAIrB,gBAAgB,IAAI,OAAO;IAI3B,iBAAiB,IAAI,cAAc,GAAG,IAAI;IAI1C,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAI/C,MAAM,CAAC,oBAAoB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;WAIzC,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAI5C,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,qBAAqB;IA6BvB,MAAM,CACV,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAuF7C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAkCxB,eAAe,CAAC,IAAI,EAAE;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAyDhC,OAAO,CAAC,gBAAgB;IAWxB,kBAAkB,CAAC,SAAS,SAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB9C,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAI9B,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BhD,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,kBAAkB;IAOpB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAmD/B"}