{"_id":"@abdallahisdev/browser-control","_rev":"2-f379cda3b14e8ef57f08ec7a858f7932","name":"@abdallahisdev/browser-control","dist-tags":{"latest":"0.0.2"},"versions":{"0.0.1":{"name":"@abdallahisdev/browser-control","version":"0.0.1","_id":"@abdallahisdev/browser-control@0.0.1","maintainers":[{"name":"abdallahisdev","email":"a.elfiky.dev@gmail.com"}],"homepage":"https://github.com/AbdallahIsDev/browser-control#readme","bugs":{"url":"https://github.com/AbdallahIsDev/browser-control/issues"},"bin":{"bc":"cli.js"},"dist":{"shasum":"25d25d5367fa5f690f81f98cbf1dba27892398f6","tarball":"https://registry.npmjs.org/@abdallahisdev/browser-control/-/browser-control-0.0.1.tgz","fileCount":464,"integrity":"sha512-UVfM5FA6ipNMRO+DbBOrhobu6+ky+Om1G7PH4JFw6rVaZMsd/LdoJVezoeUrlfhN/qRkypWFzPq211gu1YEs8w==","signatures":[{"sig":"MEUCIH6j3zKmkXp6KYsvc/iNXdpihw4T5w9IJ3BXFBIzES4TAiEA5UvHGxFcE2fkP6UXRDQNRzhE4/+QICQXTqxy734CryU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3447573},"main":"./dist/index.js","build":{"mac":{"target":"dmg","category":"public.app-category.developer-tools"},"win":{"icon":"desktop/icon.ico","target":"zip","signExts":["!.exe"],"signAndEditExecutable":false},"asar":false,"appId":"dev.abdallah.browser-control","files":["dist/**/*","web/dist/**/*","desktop/**/*","!desktop/bin/**/*","!desktop/BrowserControlLauncher/**/*","cli.js","package.json","node_modules/**/*"],"afterPack":"scripts/desktop_after_pack.cjs","npmRebuild":false,"directories":{"output":"dist-desktop"},"productName":"Browser Control","extraMetadata":{"main":"desktop/main.cjs"}},"types":"./dist/index.d.ts","engines":{"node":">=22"},"exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.js"},"./package.json":"./package.json"},"gitHead":"55cb0943d636c11469e2c2b45910a0b66f317d08","scripts":{"cli":"ts-node src/cli.ts","test":"node scripts/run_active_tests.cjs","build":"node scripts/clean_dist.cjs && tsc -p tsconfig.build.json","start":"ts-node src/main.ts","daemon":"ts-node src/daemon.ts","prepack":"npm run build && npm run web:build","test:ci":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/unit/action_result.test.ts tests/unit/config.test.ts tests/unit/policy_engine.test.ts tests/unit/execution_router.test.ts tests/unit/browser_actions.test.ts tests/unit/browser_managed_port.test.ts tests/unit/credential_vault.test.ts tests/unit/network_rules.test.ts tests/unit/telemetry.test.ts tests/unit/terminal_actions.test.ts tests/unit/fs_actions.test.ts tests/unit/broker_server.test.ts tests/unit/operator_doctor_status_setup.test.ts tests/unit/operator_cli.test.ts tests/unit/operator_config.test.ts tests/unit/stagehand_optional.test.ts tests/unit/project_structure.test.ts tests/unit/terminal_render.test.ts tests/unit/operator_dashboard.test.ts tests/unit/workflows.test.ts tests/unit/harness.test.ts tests/unit/packages.test.ts tests/unit/model_router.test.ts tests/unit/recorder.test.ts tests/unit/visual_diff.test.ts tests/unit/proxy_manager.test.ts tests/unit/service_startup.test.ts tests/unit/local_ca.test.ts tests/unit/providers/registry.test.ts tests/unit/providers/custom.test.ts tests/unit/providers/browserless.test.ts tests/unit/providers/browserbase.test.ts tests/unit/providers/health.test.ts tests/unit/knowledge_backends.test.ts tests/unit/proof_of_work.test.ts tests/unit/web_app_server.test.ts tests/unit/web_frontend_format.test.ts tests/unit/desktop_security.test.ts tests/unit/data_home.test.ts tests/unit/trading_supervisor.test.ts tests/unit/benchmarks.test.ts tests/unit/state_storage.test.ts tests/unit/cleanup_safety.test.ts tests/unit/profile_migration.test.ts tests/unit/sqlite_storage.test.ts tests/unit/sqlite_recovery.test.ts tests/integration/mcp_stdio_runtime.test.ts","test:e2e":"node scripts/run_golden_workflows.cjs","test:mcp":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/unit/mcp/server_stdio.test.ts tests/unit/mcp/tool_registry.test.ts","test:web":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/unit/web_app_server.test.ts tests/unit/web_frontend_format.test.ts","typecheck":"tsc --noEmit","web:build":"cd web && npm run build","web:serve":"ts-node src/web/server.ts","audit:high":"npm audit --audit-level=high","daemon:dev":"ts-node src/daemon.ts --dev","docs:check":"node scripts/check_production_status.cjs && node scripts/check_docs.cjs","test:flaky":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 --test-timeout=60000 tests/unit/process_leak_detection.test.ts tests/unit/cli_term_exit.test.ts tests/unit/browser_control.test.ts tests/unit/session_manager.test.ts","test:state":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/unit/state_storage.test.ts tests/unit/sqlite_storage.test.ts tests/unit/sqlite_recovery.test.ts tests/unit/data_home.test.ts tests/unit/cleanup_safety.test.ts tests/unit/profile_migration.test.ts","compat:test":"node --require ts-node/register --require tsconfig-paths/register --test tests/compatibility/package_import_smoke.test.ts tests/compatibility/public_surface.test.ts","desktop:dev":"electron desktop/main.cjs","broker:start":"ts-node src/broker_server.ts","react:doctor":"node scripts/react_doctor.cjs","test:desktop":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/unit/desktop_security.test.ts","test:e2e:mcp":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/e2e/golden/mcp_workflow.test.ts","test:package":"node scripts/ci_package_smoke.cjs","test:trading":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/unit/trading_supervisor.test.ts","compat:update":"node scripts/update_public_surface_snapshots.cjs","desktop:build":"npm run build && npm run web:build && electron-builder build --win --dir","package:smoke":"node scripts/package_smoke_test.cjs","web:typecheck":"cd web && npx tsc --noEmit","prepublishOnly":"npm run build && npm run web:build","test:lifecycle":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 --test-timeout=120000 tests/unit/daemon_launch.test.ts tests/unit/node_pty_windows_patch.test.ts tests/unit/process_leak_detection.test.ts tests/unit/api_term_exit.test.ts tests/unit/cli_term_exit.test.ts tests/unit/cold_start_exit.test.ts","test:mcp-stdio":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 --test-timeout=30000 tests/integration/mcp_stdio_runtime.test.ts","check:data-home":"node scripts/check-data-home-safety.cjs","package:desktop":"npm run build && npm run web:build && electron-builder build --win","test:e2e:golden":"npm run test:e2e","test:browser-smoke":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 --test-timeout=120000 tests/unit/browser_smoke.test.ts","test:browser-features":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/unit/browser_features_regression.test.ts tests/unit/a11y_snapshot.test.ts tests/unit/cli.test.ts tests/unit/cli_debug_observability.test.ts tests/unit/observability/screencast.test.ts tests/unit/browser_connection.test.ts tests/unit/browser_managed_port.test.ts tests/unit/providers/local.test.ts tests/unit/providers/custom.test.ts tests/unit/providers/browserless.test.ts tests/unit/providers/browserbase.test.ts tests/unit/providers/health.test.ts tests/unit/providers/registry.test.ts tests/unit/mcp/tool_registry.test.ts","test:browser-features:live":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 --test-timeout=120000 tests/e2e/browser_features_live_workflow.test.ts"},"_npmUser":{"name":"abdallahisdev","email":"a.elfiky.dev@gmail.com"},"overrides":{"uuid":"^14.0.0","langsmith":"^0.5.25"},"repository":{"url":"git+https://github.com/AbdallahIsDev/browser-control.git","type":"git"},"_npmVersion":"11.12.0","description":"Unified browser, terminal, filesystem, and MCP automation engine for AI agents.","directories":{},"_nodeVersion":"24.13.0","dependencies":{"ws":"^8.20.1","zod":"^3.25.76","dotenv":"^16.6.1","node-gyp":"^12.2.0","node-pty":"^1.1.0","playwright":"^1.54.2","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"pngjs":"^7.0.0","ts-node":"^10.9.2","electron":"^41.5.0","@types/ws":"^8.18.1","typescript":"^5.9.3","@types/node":"^22.19.17","@types/pngjs":"^6.0.5","@biomejs/biome":"2.4.14","tsconfig-paths":"^4.2.0","electron-builder":"^26.8.1","electron-packager":"^17.1.2"},"peerDependencies":{"@browserbasehq/stagehand":">=3.2.1"},"peerDependenciesMeta":{"@browserbasehq/stagehand":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/browser-control_0.0.1_1779451836568_0.6596131788873416","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@abdallahisdev/browser-control","version":"0.0.2","description":"Reusable browser workflow runtime for AI agents.","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.js"},"./package.json":"./package.json"},"bin":{"bc":"cli.js"},"scripts":{"build":"node scripts/clean_dist.cjs && tsc -p tsconfig.build.json","package:smoke":"node scripts/package_smoke_test.cjs","prepack":"npm run build && npm run web:build","prepublishOnly":"npm run build && npm run web:build","test":"node scripts/run_active_tests.cjs","test:ci":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/unit/action_result.test.ts tests/unit/config.test.ts tests/unit/policy_engine.test.ts tests/unit/execution_router.test.ts tests/unit/browser_actions.test.ts tests/unit/browser_managed_port.test.ts tests/unit/credential_vault.test.ts tests/unit/network_rules.test.ts tests/unit/telemetry.test.ts tests/unit/terminal_actions.test.ts tests/unit/fs_actions.test.ts tests/unit/broker_server.test.ts tests/unit/operator_doctor_status_setup.test.ts tests/unit/operator_cli.test.ts tests/unit/operator_config.test.ts tests/unit/stagehand_optional.test.ts tests/unit/project_structure.test.ts tests/unit/terminal_render.test.ts tests/unit/operator_dashboard.test.ts tests/unit/workflows.test.ts tests/unit/harness.test.ts tests/unit/packages.test.ts tests/unit/model_router.test.ts tests/unit/recorder.test.ts tests/unit/visual_diff.test.ts tests/unit/proxy_manager.test.ts tests/unit/service_startup.test.ts tests/unit/local_ca.test.ts tests/unit/providers/registry.test.ts tests/unit/providers/custom.test.ts tests/unit/providers/browserless.test.ts tests/unit/providers/browserbase.test.ts tests/unit/providers/health.test.ts tests/unit/knowledge_backends.test.ts tests/unit/proof_of_work.test.ts tests/unit/web_app_server.test.ts tests/unit/web_frontend_format.test.ts tests/unit/desktop_security.test.ts tests/unit/data_home.test.ts tests/unit/trading_supervisor.test.ts tests/unit/benchmarks.test.ts tests/unit/state_storage.test.ts tests/unit/cleanup_safety.test.ts tests/unit/profile_migration.test.ts tests/unit/sqlite_storage.test.ts tests/unit/sqlite_recovery.test.ts tests/integration/mcp_stdio_runtime.test.ts","test:mcp":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/unit/mcp/server_stdio.test.ts tests/unit/mcp/tool_registry.test.ts","test:mcp-stdio":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 --test-timeout=30000 tests/integration/mcp_stdio_runtime.test.ts","test:flaky":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 --test-timeout=60000 tests/unit/process_leak_detection.test.ts tests/unit/cli_term_exit.test.ts tests/unit/browser_control.test.ts tests/unit/session_manager.test.ts","test:browser-features":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/unit/browser_features_regression.test.ts tests/unit/a11y_snapshot.test.ts tests/unit/cli.test.ts tests/unit/cli_debug_observability.test.ts tests/unit/observability/screencast.test.ts tests/unit/browser_connection.test.ts tests/unit/browser_managed_port.test.ts tests/unit/providers/local.test.ts tests/unit/providers/custom.test.ts tests/unit/providers/browserless.test.ts tests/unit/providers/browserbase.test.ts tests/unit/providers/health.test.ts tests/unit/providers/registry.test.ts tests/unit/mcp/tool_registry.test.ts","test:browser-features:live":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 --test-timeout=120000 tests/e2e/browser_features_live_workflow.test.ts","test:lifecycle":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 --test-timeout=120000 tests/unit/daemon_launch.test.ts tests/unit/node_pty_windows_patch.test.ts tests/unit/process_leak_detection.test.ts tests/unit/api_term_exit.test.ts tests/unit/cli_term_exit.test.ts tests/unit/cold_start_exit.test.ts","test:browser-smoke":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 --test-timeout=120000 tests/unit/browser_smoke.test.ts","test:package":"node scripts/ci_package_smoke.cjs","check:data-home":"node scripts/check-data-home-safety.cjs","docs:check":"node scripts/check_production_status.cjs && node scripts/check_docs.cjs","audit:high":"npm audit --audit-level=high","test:e2e":"node scripts/run_golden_workflows.cjs","test:e2e:golden":"npm run test:e2e","test:e2e:mcp":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/e2e/golden/mcp_workflow.test.ts","broker:start":"ts-node src/broker_server.ts","daemon":"ts-node src/daemon.ts","daemon:dev":"ts-node src/daemon.ts --dev","web:serve":"ts-node src/web/server.ts","web:build":"cd web && npm run build","web:typecheck":"cd web && npx tsc --noEmit","react:doctor":"node scripts/react_doctor.cjs","test:web":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/unit/web_app_server.test.ts tests/unit/web_frontend_format.test.ts","test:state":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/unit/state_storage.test.ts tests/unit/sqlite_storage.test.ts tests/unit/sqlite_recovery.test.ts tests/unit/data_home.test.ts tests/unit/cleanup_safety.test.ts tests/unit/profile_migration.test.ts","test:trading":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/unit/trading_supervisor.test.ts","test:desktop":"node --require ts-node/register --require tsconfig-paths/register --test --test-concurrency=1 tests/unit/desktop_security.test.ts","desktop:dev":"electron desktop/main.cjs","desktop:build":"npm run build && npm run web:build && electron-builder build --win --dir","package:desktop":"npm run build && npm run web:build && electron-builder build --win","typecheck":"tsc --noEmit","start":"ts-node src/main.ts","cli":"ts-node src/cli.ts","compat:test":"node --require ts-node/register --require tsconfig-paths/register --test tests/compatibility/package_import_smoke.test.ts tests/compatibility/public_surface.test.ts","compat:update":"node scripts/update_public_surface_snapshots.cjs"},"build":{"appId":"dev.abdallah.browser-control","productName":"Browser Control","npmRebuild":false,"afterPack":"scripts/desktop_after_pack.cjs","directories":{"output":"dist-desktop"},"files":["dist/**/*","web/dist/**/*","desktop/**/*","!desktop/bin/**/*","!desktop/BrowserControlLauncher/**/*","cli.js","package.json","node_modules/**/*"],"win":{"target":"zip","icon":"desktop/icon.ico","signAndEditExecutable":false,"signExts":["!.exe"]},"mac":{"target":"dmg","category":"public.app-category.developer-tools"},"asar":false,"extraMetadata":{"main":"desktop/main.cjs"}},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","dotenv":"^16.6.1","node-gyp":"^12.2.0","node-pty":"^1.1.0","playwright":"^1.54.2","ws":"^8.20.1","zod":"^3.25.76"},"peerDependencies":{"@browserbasehq/stagehand":">=3.2.1"},"peerDependenciesMeta":{"@browserbasehq/stagehand":{"optional":true}},"repository":{"type":"git","url":"git+https://github.com/AbdallahIsDev/browser-control.git"},"homepage":"https://github.com/AbdallahIsDev/browser-control#readme","bugs":{"url":"https://github.com/AbdallahIsDev/browser-control/issues"},"engines":{"node":">=22"},"devDependencies":{"@biomejs/biome":"2.4.14","@types/node":"^22.19.17","@types/pngjs":"^6.0.5","@types/ws":"^8.18.1","electron":"^41.5.0","electron-builder":"^26.8.1","electron-packager":"^17.1.2","pngjs":"^7.0.0","ts-node":"^10.9.2","tsconfig-paths":"^4.2.0","typescript":"^5.9.3"},"overrides":{"uuid":"^14.0.0","langsmith":"^0.5.25"},"gitHead":"c8d10b080f78ba43287ff5295b36c4e3370fd8a6","_id":"@abdallahisdev/browser-control@0.0.2","_nodeVersion":"24.13.0","_npmVersion":"11.12.0","dist":{"integrity":"sha512-o1CabqUQEYJbfGxrGUgBo8K6wYLh8SWPNgIpI6JVS3o7TxfMFIEGVPFM1AYT2ETun8qNi3IKwsEm1sdTl7DFkg==","shasum":"d1bb60ac0b96953484e1a933600167337b3ab62f","tarball":"https://registry.npmjs.org/@abdallahisdev/browser-control/-/browser-control-0.0.2.tgz","fileCount":427,"unpackedSize":3376785,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDPbSxVIXt0iS1KyARFr3IL2yB2Nv46Df2PXXExFiYZWAiB8zC5a8TGYPVwm78Xa+GWZSX5ToetyjVsYt15iPwJSaw=="}]},"_npmUser":{"name":"abdallahisdev","email":"a.elfiky.dev@gmail.com"},"directories":{},"maintainers":[{"name":"abdallahisdev","email":"a.elfiky.dev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/browser-control_0.0.2_1779488501125_0.640297177797873"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-22T12:10:36.481Z","modified":"2026-05-22T22:21:41.406Z","0.0.1":"2026-05-22T12:10:36.790Z","0.0.2":"2026-05-22T22:21:41.304Z"},"bugs":{"url":"https://github.com/AbdallahIsDev/browser-control/issues"},"homepage":"https://github.com/AbdallahIsDev/browser-control#readme","repository":{"type":"git","url":"git+https://github.com/AbdallahIsDev/browser-control.git"},"description":"Reusable browser workflow runtime for AI agents.","maintainers":[{"name":"abdallahisdev","email":"a.elfiky.dev@gmail.com"}],"readme":"<div align=\"center\">\r\n  <h1>🖥️ Browser Control</h1>\r\n  <p><strong>Browser Control is a reusable browser workflow runtime for AI agents.</strong></p>\r\n  <p>Turn successful browser tasks into Automation Packages that can be replayed, repaired, reviewed, and shared.</p>\r\n\r\n  <a href=\"https://www.npmjs.com/package/@abdallahisdev/browser-control\"><img src=\"https://img.shields.io/npm/v/@abdallahisdev/browser-control?color=blue\" alt=\"npm version\"></a>\r\n  <img width=\"8\" alt=\"\">\r\n  <a href=\"./LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License: MIT\"></a>\r\n  <img width=\"8\" alt=\"\">\r\n  <a href=\"https://nodejs.org\"><img src=\"https://img.shields.io/badge/node-%3E%3D22-brightgreen\" alt=\"Node.js >= 22\"></a>\r\n  <img width=\"8\" alt=\"\">\r\n  <a href=\"https://github.com/AbdallahIsDev/browser-control\"><img src=\"https://img.shields.io/github/stars/AbdallahIsDev/browser-control?style=social\" alt=\"GitHub stars\"></a>\r\n  <img width=\"8\" alt=\"\">\r\n  <a href=\"./docs/support-matrix.md\"><img src=\"https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey\" alt=\"Platforms\"></a>\r\n  <br/><br/>\r\n  <img src=\"https://img.shields.io/badge/status-pre--release%20%7C%20active%20development-yellow\" alt=\"Status: pre-release\">\r\n</div>\r\n\r\n<br/>\r\n\r\n## What It Does\r\n\r\nBrowser Control gives AI agents a **local, policy-governed runtime** for reusable Chromium browser workflows, evidence capture, filesystem reports, and helper scripts.\r\n\r\nIt does not replace Codex/Claude Code. It works with existing agents to turn repeated browser tasks into reusable Automation Packages.\r\n\r\n| Domain | Capabilities |\r\n|--------|-------------|\r\n| **🌐 Browser** | Navigate, snapshot (accessibility tree with stable `@e3` refs), click, fill, hover, type, press keys, scroll, screenshot, tab management, screencast recording. Powered by Chromium/CDP via Playwright. |\r\n| **💻 Terminal** | Persistent PTY sessions (open/exec/read/write/interrupt/close/resume), command execution, output capture. Cross-platform via `node-pty`. |\r\n| **📁 Filesystem** | Structured read/write/list/move/delete/stat — policy-governed, not shell emulation. |\r\n\r\nEvery action is gated by a **policy engine** (`safe` / `balanced` / `trusted` profiles) and returns a structured `ActionResult` with success/failure, risk level, and optional debug evidence.\r\n\r\nPublic integration is CLI-first and MCP-first. The TypeScript API is available for embedding. The web dashboard and Electron desktop app remain experimental/internal operator surfaces until they are stable and redesigned around Automation Packages.\r\n\r\n> **Not a native desktop GUI automation product.** The browser path targets Chromium/CDP and semantic accessibility snapshots. It does not automate native OS windows or non-browser desktop apps.\r\n\r\n<br/>\r\n\r\n## 🎬 Demos\r\n\r\n### MIMO Research Demo — AI-powered web research with MCP tools\r\n\r\n<video src=\"https://github.com/user-attachments/assets/47fc88ce-4b86-4112-a99a-c4bbdcfb19f2\" controls autoplay muted loop width=\"100%\"></video>\r\n\r\n### MCP Server Demo — AI Agent controlling browser + terminal + filesystem via MCP\r\n\r\n<video src=\"https://github.com/user-attachments/assets/bb9cd071-9f50-44de-8012-6d3bfdc7a1a1\" controls autoplay muted loop width=\"100%\"></video>\r\n\r\n<br/>\r\n\r\n## ⚡ Quick Start\r\n\r\n**Prerequisite:** Node.js `>= 22`\r\n\r\n```powershell\r\ngit clone https://github.com/AbdallahIsDev/browser-control.git\r\ncd browser-control\r\nnpm install\r\nnpm run typecheck\r\nnpm run build\r\nnpm link              # Makes `bc` command globally available\r\n```\r\n\r\nExperimental npm package:\r\n\r\n```powershell\r\nnpm install -g @abdallahisdev/browser-control\r\nbc --help\r\n```\r\n\r\nFirst setup:\r\n\r\n```powershell\r\nbc setup --non-interactive --profile balanced\r\nbc doctor\r\nbc status\r\nbc package list\r\n```\r\n\r\n**WSL users:** Run `sh scripts/install_wsl_bc.sh` if `bc` resolves to the Linux calculator instead.\r\n\r\nRuntime data lives under `%USERPROFILE%\\.browser-control` (Windows) or `~/.browser-control` (Unix). Override with `BROWSER_CONTROL_HOME`.\r\n\r\n### First Workflow\r\n\r\n```powershell\r\n# Terminal + Filesystem\r\nbc session create demo --policy balanced\r\nbc term exec \"node --version\" --json\r\nbc fs ls . --json\r\n\r\n# Browser\r\nbc browser launch --port 9222 --profile default\r\nbc browser state --json\r\nbc browser open https://example.com --json\r\nbc browser snapshot --json\r\nbc browser act click \"@e3\" --capture-on-success --json\r\nbc browser task run --steps='[{\"action\":\"open\",\"url\":\"https://example.com\"},{\"action\":\"state\",\"snapshot\":true}]' --json\r\n\r\n# Auth state + profiles\r\nbc browser profile create work --type named\r\nbc browser auth export auth-state.json --live\r\nbc browser auth import auth-state.json --stored\r\n```\r\n\r\n<br/>\r\n\r\n## ⚡ Agent Execution Model\r\n\r\nFor Codex, Hermes-like agents, OpenCode-like agents, Gemini CLI, Claude Code, and any agent that can run shell commands, use CLI-first automation:\r\n\r\n```powershell\r\nbc status --json\r\nbc browser state --json\r\nbc browser open https://example.com --json\r\nbc browser snapshot --json\r\nbc browser act fill searchInput \"Amazon\" --json\r\nbc browser act click \"@e3\" --capture-on-success --json\r\nbc browser task run --steps='[{\"action\":\"open\",\"url\":\"https://example.com\"},{\"action\":\"state\"}]' --json\r\n```\r\n\r\nWhy CLI first:\r\n\r\n- fewer tool calls and fewer LLM-visible requests\r\n- compact structured `ActionResult` output\r\n- same policy/audit path as MCP/API\r\n- better batching through `bc browser task run`\r\n\r\nUse MCP Lite when the client is MCP-native or cannot run CLI. Use full MCP when a task needs the complete tool surface.\r\n\r\n## 🔌 MCP Server — AI Agent Integration\r\n\r\nBrowser Control exposes its full action surface as an MCP stdio server. AI agents (Claude Desktop, Codex, Cursor, etc.) can control your local browser, terminal, filesystem, workflows, packages, and operator services through it.\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"bc\": {\r\n      \"command\": \"bc\",\r\n      \"args\": [\"mcp\", \"serve\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Tool Categories\r\n\r\n| Category | Key Tools |\r\n|----------|----------|\r\n| **Status** | `status`, `bc_status` |\r\n| **Session** | `bc_session_create`, `bc_session_list`, `bc_session_select`, `bc_session_status` |\r\n| **Browser** | Short aliases such as `open`, `snapshot`, `click`, `fill`, `screenshot`, plus `bc_browser_launch`, `attach`, `list`, `hover`, `type`, `press`, `scroll`, `downloads_list`, `drop`, `highlight`, `generate_locator`, `screencast_*`, `provider_*` |\r\n| **Terminal** | `terminal_open`, `terminal_exec`, `bc_terminal_read`, `write`, `interrupt`, `snapshot`, `list`, `resume`, `status` |\r\n| **Filesystem** | `fs_read`, `fs_write`, `fs_list`, `bc_fs_move`, `delete`, `stat` |\r\n| **Network + Vault** | `bc_network_rules_list`, `bc_network_blocked_requests`, `bc_vault_list` |\r\n| **Debug** | `debug_health`, `debug_failure_bundle`, `bc_debug_get_console`, `bc_debug_get_network` |\r\n| **Service** | `bc_service_list`, `bc_service_resolve` |\r\n| **Workflow** | `bc_workflow_run`, `status`, `resume`, `approve`, `cancel`, `events`, `edit_state` |\r\n| **Harness** | `bc_harness_list`, `find_helper`, `validate_helper`, `rollback`, `generate`, `execute` |\r\n| **Packages** | `bc_package_install`, `list`, `info`, `update`, `remove`, `run`, `eval`, `grant`, `review`, `review_history`, `eval_history` |\n\r\nFull tool reference: [docs/mcp.md](docs/mcp.md)\r\n\r\n### MCP Lite\r\n\r\nMCP Lite exposes a smaller high-level toolset for lower token overhead:\r\n\r\n`bc_status`, `bc_session_status`, `bc_browser_open`, `bc_browser_open_many`, `bc_browser_capture`, `bc_browser_capture_many`, `bc_browser_snapshot`, `bc_browser_click`, `bc_browser_fill`, `bc_browser_state`, `bc_browser_act`, `bc_task_run`, `bc_browser_tab_list`, `bc_fs_write_output`\r\n\r\nSet `BROWSER_CONTROL_MCP_MODE=lite` for Lite mode. Full MCP mode keeps the complete tool surface.\r\n\r\n### Security with MCP\r\n\r\nMCP clients are powerful — they can run commands, read/write files, and control browser pages with your logged-in sessions. Use `safe` or `balanced` policy for untrusted agents, scope working directories, and review destructive actions.\r\n\r\n<br/>\r\n\r\n## 🏗️ Architecture\r\n\r\n```\r\nbrowser-control/\r\n├── src/                        # Production TypeScript\r\n│   ├── browser/                # CDP/Playwright browser automation\r\n│   ├── terminal/               # PTY-based native terminal\r\n│   ├── filesystem/             # Policy-governed FS operations\r\n│   ├── policy/                 # Risk-based policy engine\r\n│   ├── mcp/                    # MCP server + tool registry\r\n│   ├── runtime/                # Daemon, broker, health, scheduler\r\n│   ├── observability/          # Debug bundles, console/network capture, recording, visual diff\r\n│   ├── operator/               # Doctor, setup, dashboard\r\n│   ├── providers/              # local-first browser providers; remote providers are opt-in internals\r\n│   ├── services/               # bc:// registry and optional .localhost proxy\r\n│   ├── security/               # credential vault, network rules, redaction\r\n│   ├── state/                  # SQLite-backed durable state\r\n│   ├── workflows/              # Workflow graph runtime\r\n│   ├── harness/                # Self-healing helper registry\r\n│   ├── packages/               # Automation package system\r\n│   └── knowledge/              # Markdown artifact storage\r\n├── web/                        # React 19 + Vite dashboard\r\n├── desktop/                    # Electron wrapper\r\n├── tests/                      # Unit, E2E, compatibility\r\n├── docs/                       # Full documentation\r\n├── examples/                   # Golden workflow examples\r\n└── automation-packages/        # Example packages\r\n```\r\n\r\n**Three execution paths:**\r\n\r\n- **`command`** — terminal, filesystem, process, service, and local system work\r\n- **`a11y`** — browser accessibility snapshots with stable refs (`@e3`)\r\n- **`low_level`** — CDP, DOM, network, and browser fallback\r\n\r\n**Technology stack:** TypeScript, Node.js ≥22, Playwright, node-pty, SQLite, React 19, Vite, Electron 41, Zod, ws, @modelcontextprotocol/sdk.\r\n\r\nSee the full architecture: [docs/architecture/source-layout.md](docs/architecture/source-layout.md) | [docs/architecture/overview.md](docs/architecture/overview.md)\r\n\r\n<br/>\r\n\r\n## 📚 TypeScript API\r\n\r\n```typescript\r\nimport { createBrowserControl } from \"@abdallahisdev/browser-control\";\r\n\r\nconst bc = createBrowserControl({ policyProfile: \"balanced\" });\r\n\r\nconst result = await bc.browser.open({ url: \"https://example.com\" });\r\nconst snapshot = await bc.browser.snapshot();\r\nawait bc.browser.click({ target: \"@e3\" });\r\nawait bc.browser.screenshot({ outputPath: \"./page.png\" });\r\n\r\nconst term = await bc.terminal.exec({ command: \"node --version\" });\r\nawait bc.fs.write({ path: \"./output.txt\", content: \"hello\" });\r\nawait bc.close();\r\n```\r\n\r\nFull API reference: [docs/api.md](docs/api.md)\r\n\r\n<br/>\r\n\r\n## 🖥️ Experimental Operator UI\r\n\r\nBrowser Control includes a token-gated local web dashboard and an Electron wrapper in the repository, but they are **not the main product surface** and are not positioned as stable production UI yet.\r\n\r\nUse CLI/MCP for normal agent integration. Treat dashboard/desktop as experimental internal operator interfaces.\r\n\r\n```powershell\r\nnpm run web:dev           # Experimental dashboard dev mode\r\nnpm run web:build         # Build experimental dashboard assets\r\nbc web open               # Internal loopback operator UI\r\nnpm run desktop:dev       # Experimental Electron wrapper\r\n```\r\n\r\nDashboard direction is package-first: Package Library, Run Automation Package, Create Package from Successful Run, Run History, Evidence Viewer, Repair Failed Package, Permissions/Risk Review, and tool-call/time/token savings. Dashboard/Desktop remain experimental operator surfaces.\n\r\n<br/>\r\n\r\n## 🧰 CLI Highlights\r\n\r\nBrowser Control has a broad CLI surface for both operators and agents. Common areas:\r\n\r\n- `setup`, `doctor`, `status`, `config`\r\n- `open`, `snapshot`, `click`, `fill`, `screenshot`\r\n- `browser launch|attach|list|state|act|task|provider|profile|auth`\r\n- `term open|exec|read|snapshot|interrupt|resume`\r\n- `fs read|write|ls|move|rm|stat`\r\n- `service register|list|resolve|remove`\r\n- `daemon start|stop|status|health|logs`\r\n- `run` and `schedule` for queued tasks and recurring automations\r\n- `debug`, `policy`, `knowledge`, `memory`, `report`, and package/workflow commands\r\n\r\nFull command reference: [docs/cli.md](docs/cli.md)\r\n\r\n<br/>\r\n\r\n## 🗺️ Roadmap\r\n\r\n| Area | Status |\r\n|------|--------|\r\n| ✅ Browser CDP automation | Stable |\r\n| ✅ Accessibility snapshots | Stable |\r\n| ✅ Native terminal (PTY) | Stable |\r\n| ✅ Filesystem operations | Stable |\r\n| ✅ Policy engine (safe/balanced/trusted) | Stable |\r\n| ✅ MCP server | Stable |\r\n| ✅ CLI (`bc` command) | Stable |\r\n| ✅ TypeScript API | Stable |\r\n| ✅ Service registry (`bc://`) | Stable |\r\n| ✅ Debug bundles + observability | Stable |\r\n| 🧪 Web dashboard (React/Vite) | Experimental/internal |\r\n| 🧪 Electron desktop app | Experimental/internal |\r\n| 🔄 Self-healing harness | Active |\r\n| ✅ Workflow graph runtime, events, helpers | Active |\r\n| ✅ Automation packages, trust review, evals | Active |\r\n| 🧪 Remote providers | Experimental/opt-in |\r\n| 🎯 Production hardening | Planned |\r\n| 🎯 Cross-platform package publishing | Planned |\r\n\r\nSee detailed roadmap: [docs/specs/2026-04-20-browser-control-v1-unified-automation-roadmap.md](docs/specs/2026-04-20-browser-control-v1-unified-automation-roadmap.md) | Production upgrade tracker: [docs/production-upgrade/STATUS.md](docs/production-upgrade/STATUS.md)\r\n\r\n<br/>\r\n\r\n## 🔒 Security\r\n\r\nBrowser Control runs with the same authority as your user account. Treat it accordingly.\r\n\r\n- **Three policy profiles:** `safe` (denies high/critical), `balanced` (confirms high/critical, default), `trusted` (audits high, confirms critical)\r\n- **Secrets redaction:** Provider tokens, credential-vault secret refs, CAPTCHA keys, OpenRouter/model keys, and Browserbase URLs are redacted from CLI/API/MCP/UI output\r\n- **MCP security:** Only connect trusted agents. Use `safe`/`balanced` policy, scope working directories, avoid storing tokens in prompts\r\n- **Dedicated browser profiles:** Recommended — use `BROWSER_LAUNCH_PROFILE=isolated` for automation\r\n\r\nFull security documentation: [SECURITY.md](SECURITY.md) | [docs/security.md](docs/security.md)\r\n\r\n<br/>\r\n\r\n## 📖 Documentation\r\n\r\n| Doc | Description |\r\n|-----|-------------|\r\n| [Getting Started](docs/getting-started.md) | Prerequisites, setup, first workflows |\r\n| [CLI Reference](docs/cli.md) | Full `bc` command reference |\r\n| [TypeScript API](docs/api.md) | `createBrowserControl()` API surface |\r\n| [MCP Setup & Tools](docs/mcp.md) | MCP server config + current tool surface |\r\n| [Automation Packages](docs/packages.md) | Package-first workflow model and commands |\r\n| [Architecture Overview](docs/architecture/overview.md) | System architecture, data flow, component map |\r\n| [Source Layout](docs/architecture/source-layout.md) | Directory structure and conventions |\r\n| [Browser Behavior](docs/browser.md) | Modes, profiles, CDP, remote providers |\r\n| [Terminal & Filesystem](docs/terminal.md) | PTY sessions, FS operations |\r\n| [Configuration](docs/configuration.md) | All config keys, env vars, runtime paths |\r\n| [Security Model](docs/security.md) | Trust boundaries, policy, secrets, MCP security |\r\n| [Policy Guide](docs/policy.md) | Policy profiles and risk evaluation |\r\n| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |\r\n| [Support Matrix](docs/support-matrix.md) | Platform and feature support |\r\n| [Compatibility](docs/compatibility.md) | Semver, breaking changes, deprecation |\r\n| [WSL + Windows Chrome](docs/wsl-windows-chrome.md) | WSL-specific browser setup |\r\n| [Examples](docs/examples/) | Copy-pasteable CLI, API, MCP examples |\r\n\r\n<br/>\r\n\r\n## 🤝 Contributing\r\n\r\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards, and [docs/release-checklist.md](docs/release-checklist.md) for the release process.\r\n\r\n<br/>\r\n\r\n## 📄 License\r\n\r\nMIT — see [LICENSE](LICENSE) for details.\r\n\r\n<br/>\r\n\r\n<div align=\"center\">\r\n  <strong>Turn repeated browser tasks into reusable Automation Packages.</strong>\r\n</div>\r\n","readmeFilename":"README.md"}