browser-control

Browser Control Addon

Status: DRAFT — scaffolded post-PoC, implementation pending. See .aiwg/intake/browser-control-intake.md for the formal intake form and .aiwg/architecture/adr-remote-browser-control.md for the architectural decision.

Drive a real, user-installed Chromium-derived browser from an AIWG agent. Handles the painful parts: which browser to use, how the Playwright MCP Bridge extension fits in, how the per-install token is captured and stored, how it gets injected into the AIWG MCP registry, and how the agent stays inside an allow-list with audit trail.

Why

The naive setup path (@playwright/mcp + the Web Store extension + token in env var) is real but takes ~10 session restarts and deep knowledge of:

• Which Chromium-derived browsers --extension actually supports (Chrome and Edge only — not Chromium, Brave, Vivaldi, Arc, etc.)
• That tokens are per-install secrets generated by the extension UI
• That env var inheritance through Claude Code → MCP-server-child depends on shell-init semantics
• That .claude/settings.local.json injection is silently overridden by --mcp-config wrappers (e.g., claude-role)

This addon encapsulates that.

Components

Type	Name	Role
Skill	browser-setup	Interactive wizard: detect browsers, install extension, capture token, register MCP, inject, verify
Skill	browser-doctor	Health check across browser, extension, token file, registry, injection, allow-list
Skill	browser-reset	Rotate token, switch browser, clean up
Agent	browser-driver	Persona that respects allow-list + sensitive-domain gates + activity-log discipline
Rule	browser-control-safety	Token security, allow-list enforcement, capability denial
Template	browser-allowlist.yaml.tmpl	Per-workspace allow-list scaffold

Setup (planned UX)

# Deploy the addon
aiwg use browser-control

# Run the wizard (interactive)
aiwg run skill browser-setup

# Health check anytime
aiwg run skill browser-doctor

# Rotate or reconfigure
aiwg run skill browser-reset

After browser-setup completes:

• ~/.config/playwright-mcp/token exists (mode 600)
• ~/.aiwg/mcp-servers.json has playwright registered with --extension and env block
• Active provider config (e.g., .claude/settings.local.json) has playwright in mcpServers
• .aiwg/browser-allowlist.yaml scaffolded (optional)
• Restart provider → agent can drive the configured browser

Security model summary

See rules/browser-control-safety.md for the full set. Headlines:

• Token at mode 600 in user home; never echoed, never committed
• Per-workspace allow-list; off-allow-list navigation requires human authorization
• Sensitive-domain pattern match (banking, identity, payment, admin) requires authorization regardless of allow-list state
• Activity-log entry per MCP tool invocation
• --allow-unrestricted-file-access never enabled
• --caps devtools opt-in only (CVE-2026-8018 precedent)

Dependencies

External:

• @playwright/mcp (npm, pinned by addon version)
• Playwright MCP Bridge installed in target browser

Internal:

• AIWG MCP CLI (aiwg mcp add/inject/profile)
• human-authorization rule (existing)
• activity-log rule (existing)
• token-security rule (existing)

Open core dependency

Token currently sits in plaintext in ~/.aiwg/mcp-servers.json. This is a recognized gap; final addon release blocks on AIWG core supporting ${file:...} substitution in MCP registry env blocks. See ADR "Open follow-ups" §1.

Status notes

• 2026-05-22 — Addon scaffolded from PoC findings. Implementation pending Inception phase outputs.
• PoC log: .aiwg/working/playwright-mcp-poc.md (test plan), .aiwg/activity.log (timeline)

References

• .aiwg/intake/browser-control-intake.md — formal intake
• .aiwg/working/browser-control-feature-plan.md — design + lessons
• .aiwg/architecture/adr-remote-browser-control.md — architectural decision
• microsoft/playwright-mcp