Browser Debug Plugin

What This Project Is

This repository contains a local browser debugging toolkit for reproducible frontend investigations. It combines a Chrome MV3 extension, a local Node.js agent, and JSONL log storage to capture runtime evidence, run browser actions, and query traces by time window.

Operating Modes

Dimension	Core mode	Enhanced mode (fix-app-bugs optional addon)
Goal	Fast local debugging with direct extension + agent workflow.	Strict, machine-verifiable bugfix workflow with guarded instrumentation decisions.
Required tools	Node.js, Chrome with CDP, extension.	Core mode tools + fix-app-bugs skill scripts.
Required bootstrap	No guarded bootstrap required.	Guarded bootstrap required before evidence collection decisions.
Evidence/report strictness	Standard debugging evidence; report format is optional.	Strict evidence mode, cleanup checks, and required final report blocks.
Best for	Manual investigation, local iteration, general diagnostics.	Reproducible bugfix runs with explicit instrumentation gates and auditability.

Core mode is the default and does not require fix-app-bugs. Enhanced mode (fix-app-bugs optional addon) adds guarded bootstrap, strict evidence, and cleanup/report discipline.

Who It Is For

• Developers who need reliable runtime evidence for frontend bug investigations.
• AI agents that must follow deterministic debugging workflows.

Architecture

• extensions/humans-debugger: MV3 extension (background service worker, popup, content script).
• src/agent: local Fastify-based agent with Core API (4678 by default) and Debug API (7331 by default).
• logs/browser-debug: local JSONL event storage and screenshot artifacts.

Mode note: runtime architecture is identical in both modes; Enhanced mode adds external workflow controls on top.

How It Works

1. The extension discovers an available Core API on 127.0.0.1 (ports 4678..4698) and syncs runtime config.
2. A session starts for the active tab through /session/start; the agent attaches to Chrome DevTools Protocol (CDP).
3. The content script captures runtime signals (console, errors, unhandled rejections, fetch/XHR network events).
4. Events are ingested through /events (session + ingest token) or /debug (BUGFIX_TRACE payloads).
5. The agent normalizes payloads, redacts sensitive data, writes JSONL logs, and stores snapshots.
6. Operators query logs via /events/query or npm run agent:query, and run CDP commands via /command or npm run agent:cmd.

Mode note: Enhanced mode gates instrumentation decisions through guarded bootstrap; Core mode can operate directly.

Quick Start (Core mode)

1. Install dependencies:

npm install

2. Start the local agent:

npm run agent:start

3. Start Chrome with CDP enabled:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

4. Open chrome://extensions, enable Developer mode, then load unpacked extension from:

extensions/humans-debugger

Quick Start (Enhanced mode, optional)

1. Complete all Core mode steps first.
2. Ensure CODEX_HOME is set:

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"

3. Run guarded bootstrap for target project:

python3 "$CODEX_HOME/skills/fix-app-bugs/scripts/bootstrap_guarded.py" --project-root <project-root> --json

4. Re-run with the real app URL (required for browser-fetch mode):

python3 "$CODEX_HOME/skills/fix-app-bugs/scripts/bootstrap_guarded.py" --project-root <project-root> --actual-app-url <url> --json

Bootstrap notes:

• Loopback origins localhost and 127.0.0.1 are treated as equivalent for capability checks.
• checks.appUrl.recommendedCommands (object entries) and checks.appUrl.recommendedCommandsText (string entries) prioritize --apply-recommended on mismatch to avoid rerun loops.
• checks.appUrl.primaryRecommendedCommand provides a copy-ready command string for fast remediation.
• Inspect browserInstrumentation.failureCategory to distinguish network-mismatch-only vs endpoint-unavailable.
• Use readyForScenarioRun + readinessReasons as the final go/no-go verdict before scenario pipelines.
• Strict readiness gate blocks scenario launch on app-url-gate:* and, in browser-fetch, on headed-evidence:*.

If guarded bootstrap falls back or Enhanced prerequisites are unavailable, continue in Core mode.

Runtime Configuration

Each target project can provide .codex/browser-debug.json:

{
  "version": 1,
  "projectId": "my-project",
  "appUrl": "http://localhost:5173",
  "agent": {
    "host": "127.0.0.1",
    "corePort": 4678,
    "debugPort": 7331
  },
  "browser": {
    "cdpPort": 9222
  },
  "capture": {
    "allowedDomains": ["localhost", "127.0.0.1"],
    "networkAllowlist": []
  },
  "defaults": {
    "queryWindowMinutes": 30
  }
}

Mode Selection Guidance

• Choose Core mode for local/manual debugging and fast iteration.
• Choose Enhanced mode (fix-app-bugs optional addon) when you need audit-ready evidence, final parity sign-off, CI/release sign-off evidence, or strict 5-block final report output.
• Every run should log Mode selected + reason.

Workflow Auto Routing (Every Skills)

Workflow and reviewer skills can auto-route into Browser Debug + fix-app-bugs based on a shared contract.

Source-of-truth and mirrors:

• Local: $CODEX_HOME/skills/workflows-shared/references/auto-routing-contract.md
• Local capability map: $CODEX_HOME/skills/workflows-shared/references/auto-routing-capability-map.md
• Repo mirrors:
  • docs/contracts/auto-routing-contract.md
  • docs/contracts/auto-routing-capability-map.md

Routing guardrails:

1. EVERY_AUTO_ROUTING_ENABLED=false disables all auto-routing.
2. Session opt-out tokens (no-auto-routing, manual-only, skip-browser-debug) force no-route.
3. Core mode remains default; Enhanced is used only for strict reproducibility.
4. Fallback verdicts force terminal-probe, with no browser-side fetch(debugEndpoint) usage.

Quick Decision Tree

1. Start with Core mode for exploratory debugging and fast command loops.
2. Move to Enhanced mode when you need guarded bootstrap verdicts and strict final reports.
3. If Enhanced returns bootstrap.status = fallback or canInstrumentFromBrowser = false, use terminal-probe immediately.
4. For parity-sensitive work, capture one artifact bundle per checkpoint and keep headed evidence.
5. If parity does not improve after 3 cycles or 90 minutes, stop and switch to rollback/retrospective planning.

Core Commands

These commands are valid in both modes:

• Start agent: npm run agent:start
• Stop active session: npm run agent:stop
• Execute a browser command: npm run agent:cmd -- --session <id> --do <reload|click|type|snapshot|compare-reference|webgl-diagnostics>
• Capture one parity bundle: npm run agent:parity-bundle -- --session <id> --reference /path/ref.png --label baseline
• Query logs: npm run agent:query -- --from <ISO> --to <ISO> [--tag <tag>]
• Aggregate 24h agent feedback: npm run agent:feedback -- --window 24h [--targets browser-debug,fix-app-bugs] (--json now includes structured signals, per-signal promotion, promotionRules, and backlogSlice with promoted signals only).
• Run tests: npm test

Examples:

npm run agent:cmd -- --session <id> --do reload
npm run agent:cmd -- --session <id> --do click --selector "button[data-test=save]"
npm run agent:cmd -- --session <id> --do type --selector "input[name=email]" --text "user@example.com" --clear
npm run agent:cmd -- --session <id> --do snapshot --fullPage
npm run agent:cmd -- --session <id> --do compare-reference --actual /path/app.png --reference /path/ref.png --label baseline --dimension-policy strict --resize-interpolation bilinear
npm run agent:parity-bundle -- --session <id> --reference /path/ref.png --label baseline
npm run agent:cmd -- --session <id> --do webgl-diagnostics
npm run agent:session -- --tab-url http://127.0.0.1:5173/ --match-strategy origin-path

Enhanced fallback helper (terminal-probe scenario pipeline):

python3 "$CODEX_HOME/skills/fix-app-bugs/scripts/terminal_probe_pipeline.py" --project-root <project-root> --session-id <id> --scenarios "$CODEX_HOME/skills/fix-app-bugs/references/terminal-probe-scenarios.example.json" --json

This helper captures scenario snapshots, computes metrics (mean, stddev, nonBlackRatio, MAE), and writes runtime.json, metrics.json, summary.json. It also emits deterministic nextAction guidance and canonical blackScreenVerdict in top-level JSON and in summary.json. Optional reliability flags for auto session flows:

• --tab-url-match-strategy origin-path: match by origin+path first, then retry with exact URL when CDP list resolves a unique candidate.
• --force-new-session: stop active session before session/ensure.
• --open-tab-if-missing: attempt CDP json/new on TARGET_NOT_FOUND and retry ensure (enabled by default in auto mode).
• --no-open-tab-if-missing: disable automatic tab-open recovery.
• --resize-interpolation nearest|bilinear: interpolation mode for resize-reference-to-actual fallback.
• --no-normalize-reference-size: keep strict dimension policy only.

Visual starter helper (strict readiness + optional recovery/evidence):

python3 "$CODEX_HOME/skills/fix-app-bugs/scripts/visual_debug_start.py" --project-root <project-root> --actual-app-url <url> --json

Optional flags:

• --auto-recover-session: one bounded /health -> /session/stop -> /session/ensure recovery attempt on cdp-unavailable:* or session-state:*.
• --tab-url-match-strategy exact|origin-path|origin: matching strategy for recovery ensure + terminal-probe auto session.
• --open-tab-if-missing: keep automatic tab-open recovery enabled for terminal-probe auto-session flows (default).
• --no-open-tab-if-missing: explicitly disable auto tab-open recovery for terminal-probe auto-session flows.
• --headed-evidence: generate headed evidence bundle.
• --reference-image <path>: required with --headed-evidence in browser-fetch.
• --evidence-label <label>: parity bundle label (default visual-debug-start).

visual_debug_start.py --json output also exposes modeSelection.alternateMode, modeSelection.alternateModeRationale, and terminalProbeNextAction when terminal-probe capture returns deterministic follow-up guidance.

Recovery precedence for readiness failures:

1. app-url-gate:*: run config alignment commands first (preview -> apply -> resume).
2. session-state:* or cdp-unavailable:*: use guided session lane (soft recovery -> force-new-session -> open-tab-if-missing).
3. If still blocked, keep terminal-probe mode and inspect readinessReasons before rerun.

HTTP APIs

Default base URLs:

• Core API: http://127.0.0.1:4678
• Debug API: http://127.0.0.1:7331

Endpoint	Method	Purpose
/health	GET	Agent status, active session, readiness (including CDP probe), appUrlDrift, and runReadiness verdict (`runnable
/runtime/config	GET, POST	Read or update active runtime config.
/session/start	POST	Start session and attach to tab via CDP (matchStrategy: `exact
/session/ensure	POST	Ensure/reuse session (matchStrategy: `exact
/session/stop	POST	Stop current session and detach CDP.
/events	POST	Ingest extension runtime events (requires X-Ingest-Token).
/events/query	GET	Query JSONL events by time window and filters.
/command	POST	Execute command (reload, click, type, snapshot, compare-reference, webgl-diagnostics). compare-reference supports dimensionPolicy + resizeInterpolation; webgl-diagnostics returns readPixelsStatus/confidence/confidenceReason.
/debug	OPTIONS, POST	Preflight + BUGFIX_TRACE ingestion with origin allowlist checks.

Mode note: API surface stays the same in both modes; Enhanced mode imposes stricter workflow rules around when and how instrumentation is used.

Privacy and Safety

• The agent binds to loopback (127.0.0.1) by default and is intended for local debugging.
• Domain and origin allowlists gate session start and /debug ingestion.
• Sensitive values are redacted before persistence (email, bearer/JWT-like tokens, cards, secret-like keys).
• Request body capture is rule-based and byte-limited through capture.networkAllowlist.

Troubleshooting

• CDP_UNAVAILABLE: verify Chrome was started with --remote-debugging-port=9222 and that browser.cdpPort matches.
• TARGET_NOT_FOUND: ensure the active tab URL matches the requested tabUrl pattern.
• AMBIGUOUS_TARGET: tighten /session/start or /session/ensure matching (--match-strategy exact) or provide a fully exact tabUrl.
• DOMAIN_NOT_ALLOWED / ORIGIN_NOT_ALLOWED / CORS_POLICY_BLOCKED_PATH: update capture.allowedDomains and refresh runtime config.
• SESSION_ALREADY_RUNNING: stop the active session first (npm run agent:stop or /session/stop).
• browserInstrumentation.failureCategory = network-mismatch-only: apply first checks.appUrl.recommendedCommands entry with --apply-recommended.
• browserInstrumentation.failureCategory = endpoint-unavailable: verify agent health and endpoint reachability before retrying browser-fetch.
• /health.appUrlDrift.status = mismatch: use /health.appUrlDrift.recommendedCommand as a template and replace <project-root> with your target app repository path.
• /health.runReadiness.status = fallback: follow /health.runReadiness.nextAction and continue with terminal-probe starter path.
• /health.runReadiness.status = blocked: execute /health.runReadiness.nextAction.command first, then re-check /health.
• Missing fix-app-bugs tooling is not a blocker for Core mode; run Core workflow directly.

Skill Sync Workflow

Local skill is the source of truth: $CODEX_HOME/skills/fix-app-bugs (fallback: $HOME/.codex/skills/fix-app-bugs).

Keep repository mirror in sync:

1. Sync local -> repo mirror:

npm run skill:sync:from-local

2. Verify sync before commit/push:

npm run skill:sync:check

3. Optional repo -> local sync:

npm run skill:sync:to-local

Auto-routing contract mirror workflow:

1. Sync local -> repo mirror:

npm run routing:sync:from-local

2. Verify sync before commit/push:

npm run routing:sync:check

3. Optional repo -> local sync:

npm run routing:sync:to-local

Quick check:

curl http://127.0.0.1:4678/health

Documentation Map

• Core onboarding and dual-mode entrypoint: README.md
• Enhanced deep runbook: README-debug.md
• Mode-gated AI workflow policy: AGENTS.md