{"id":51318587,"url":"https://github.com/michaljach/opencode-browser","last_synced_at":"2026-07-01T10:31:22.108Z","repository":{"id":346892947,"uuid":"1127869750","full_name":"michaljach/opencode-browser","owner":"michaljach","description":"Browser automation plugin for OpenCode AI editor - Control Chrome/Edge with AI, automate web testing, scraping \u0026 form filling via MCP integration","archived":false,"fork":false,"pushed_at":"2026-04-29T15:54:37.000Z","size":16108,"stargazers_count":54,"open_issues_count":0,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T11:33:38.391Z","etag":null,"topics":["ai-coding-assistant","ai-plugin","browser-automation","chrome-automation","edge-automation","form-automation","mcp","model-context-protocol","opencode","opencode-plugin","playwright-alternative","selenium-alternative","test-automation","typescript","web-automation","web-scraping","web-testing"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/michaljach.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-04T18:47:20.000Z","updated_at":"2026-06-03T15:23:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/michaljach/opencode-browser","commit_stats":null,"previous_names":["michaljach/opencode-browser"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/michaljach/opencode-browser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaljach%2Fopencode-browser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaljach%2Fopencode-browser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaljach%2Fopencode-browser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaljach%2Fopencode-browser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/michaljach","download_url":"https://codeload.github.com/michaljach/opencode-browser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michaljach%2Fopencode-browser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35003452,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding-assistant","ai-plugin","browser-automation","chrome-automation","edge-automation","form-automation","mcp","model-context-protocol","opencode","opencode-plugin","playwright-alternative","selenium-alternative","test-automation","typescript","web-automation","web-scraping","web-testing"],"created_at":"2026-07-01T10:31:17.896Z","updated_at":"2026-07-01T10:31:22.098Z","avatar_url":"https://github.com/michaljach.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenCode Browser MCP Plugin\n\nAn OpenCode plugin that integrates [Browser MCP](https://browsermcp.io) to enable browser automation capabilities within OpenCode. This plugin allows the AI to control a browser, navigate websites, fill forms, click elements, and perform other browser automation tasks.\n\n## Demo\n\n![Demo](assets/demo.gif)\n\n## Features\n\n- Full browser automation support through Browser MCP\n- **Speed-oriented browser guidance** injected into the model prompt\n- **Tool-specific performance hints** for expensive browser actions\n- **Fast retry behavior** with no artificial reconnect backoff in the plugin\n- Automatic detection of browser-related tasks\n- Context preservation for browser state across session compactions\n- Seamless integration with OpenCode's existing tools\n\n## Prerequisites\n\nBefore using this plugin, you need:\n\n1. **Node.js** installed on your system\n2. **OpenCode** installed and configured\n3. **Browser MCP extension** installed in your browser (Chrome/Edge)\n\n## Installation\n\n### Step 1: Install Browser MCP Extension\n\n1. Visit [https://browsermcp.io/install](https://browsermcp.io/install)\n2. Install the Browser MCP extension for your browser (Chrome or Edge)\n3. Follow the extension setup instructions\n\n### Step 2: Configure OpenCode\n\nFastest path:\n\n```bash\nnpx opencode-browser init\n```\n\nThis creates or updates `./opencode.json` with the required `plugin` and `mcp.browsermcp` entries while preserving any unrelated config you already have.\n\nFor a global setup instead of a project-local one:\n\n```bash\nnpx opencode-browser init --global\n```\n\nCreate or update your `opencode.json` configuration file. You can create this file in one of two locations:\n\n- **Global configuration** (applies to all projects): `~/.config/opencode/opencode.json`\n- **Project-specific configuration** (applies to current project only): `./opencode.json` (in your project root)\n\nLearn more about OpenCode configuration at [https://opencode.ai/docs/config](https://opencode.ai/docs/config)\n\nAdd this configuration to your `opencode.json`:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"plugin\": [\"opencode-browser\"],\n  \"mcp\": {\n    \"browsermcp\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@browsermcp/mcp@0.1.3\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\nThis configuration does two things:\n1. **Installs the plugin** - OpenCode automatically downloads `opencode-browser` from npm\n2. **Configures Browser MCP** - Sets up the MCP server that actually controls the browser\n\nThat's it! No manual file copying required. OpenCode handles everything automatically.\n\nThe generated command pins the Browser MCP package version to avoid the extra `@latest` resolution step on startup and keep launches reproducible.\n\nIf you prefer to preview the generated config without writing it yet:\n\n```bash\nnpx opencode-browser init --print\n```\n\n#### Alternative: Install Locally (for development/testing)\n\nIf you want to modify the plugin or test changes:\n\n**For global installation:**\n```bash\nmkdir -p ~/.config/opencode/plugins\ncp src/index.ts ~/.config/opencode/plugins/browser-mcp.ts\n```\n\n**For project-specific installation:**\n```bash\nmkdir -p .opencode/plugins\ncp src/index.ts .opencode/plugins/browser-mcp.ts\n```\n\nThe plugin will be automatically loaded on OpenCode startup.\n\n## Configuration\n\n### Basic Configuration\n\nThe minimal configuration requires only the MCP server setup:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"browsermcp\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@browsermcp/mcp@0.1.3\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\n### Advanced Configuration\n\nFor more control, you can disable Browser MCP tools globally and enable them per agent:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"browsermcp\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@browsermcp/mcp@0.1.3\"],\n      \"enabled\": true\n    }\n  },\n  \"tools\": {\n    \"browsermcp_*\": false\n  },\n  \"agent\": {\n    \"browser-agent\": {\n      \"tools\": {\n        \"browsermcp_*\": true\n      }\n    }\n  }\n}\n```\n\n### Performance Behavior\n\nThe plugin improves Browser MCP speed by shaping how the model uses browser tools:\n\n- Adds system guidance that prefers direct navigation and fewer browser calls\n- Annotates expensive tools like snapshots, screenshots, and waits with performance hints\n- Preserves fast-resume guidance during session compaction\n- Avoids plugin-side reconnect delays so you can retry immediately when the browser extension is ready\n\n### Environment Variables\n\nIf you need to pass environment variables to the Browser MCP server:\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"browsermcp\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@browsermcp/mcp@0.1.3\"],\n      \"enabled\": true,\n      \"environment\": {\n        \"BROWSER_MCP_DEBUG\": \"true\"\n      }\n    }\n  }\n}\n```\n\n## Usage\n\nOnce installed and configured, you can use browser automation in your OpenCode prompts:\n\n### Basic Browser Navigation\n\n```\nNavigate to https://github.com and search for \"opencode\"\n```\n\n### Form Filling\n\n```\nGo to the contact form at https://example.com/contact and fill in:\n- Name: John Doe\n- Email: john@example.com\n- Message: Hello from OpenCode!\nThen submit the form.\n```\n\n### Web Scraping\n\n```\nVisit https://news.ycombinator.com and get the titles of the top 5 stories\n```\n\n### Complex Automation\n\n```\nGo to https://example.com/login, log in with the test credentials,\nnavigate to the dashboard, and screenshot the main metrics panel\n```\n\n### Prompt Tips\n\nFor best results when using browser automation:\n\n1. **Be specific** about URLs and actions\n2. **Prefer direct URLs** instead of clicking through intermediate pages\n3. **Reuse page state** instead of rechecking the same screen repeatedly\n4. **Ask for verification only when needed** because snapshots and screenshots are slower than targeted extraction\n5. **Specify selectors** when needed (CSS selectors, text content, etc.)\n\nYou can also add browser automation guidelines to your `AGENTS.md` file:\n\n```markdown\n## Browser Automation\n\nWhen performing browser automation tasks:\n- Always confirm the page has loaded before interacting\n- Use descriptive selectors (prefer text content over CSS selectors)\n- Take screenshots when verification is needed\n- Handle errors gracefully (page not found, element not visible, etc.)\n- Close tabs when the task is complete\n```\n\n## Plugin Features\n\n### Speed-Oriented Guidance\n\nThe plugin biases the model toward faster browser workflows:\n\n- Prefers direct `navigate` calls when the destination URL is known\n- Reuses the current tab and page state instead of redoing navigation\n- Minimizes `snapshot`, `screenshot`, and `wait` calls unless they are actually needed\n- Encourages targeted extraction and direct actions over broad inspection\n\n### Lightweight Connection Recovery\n\nThe plugin still detects browser connection issues, but it no longer adds artificial retry sleeps:\n\n- Detects common Browser MCP connection failures from tool output\n- Adds immediate retry guidance to the result instead of pausing inside the plugin\n- Marks the connection as restored after the next successful browser action\n\n### Automatic Browser Tool Detection\n\nThe plugin automatically detects when Browser MCP tools are being used and applies browser-specific guidance.\n\n### Session Context Preservation\n\nDuring session compaction, the plugin preserves browser automation context, ensuring the AI remembers:\n- Browser interactions that occurred\n- Current browser state considerations\n- Fast-resume guidance so it can avoid repeating navigation and inspection\n\n### Tool Definition Hints\n\nThe plugin annotates Browser MCP tool definitions with performance notes, especially for slower tools like snapshots, screenshots, and waits.\n\n## Troubleshooting\n\n### Browser MCP Connection Lost\n\nIf you see connection errors:\n\n1. **Check extension status**: Verify the Browser MCP extension is enabled in Chrome\n2. **Re-enable extension**: If you disabled it, simply re-enable it and retry the browser action immediately\n3. **Check browser is running**: Ensure Chrome/Edge is actually running\n4. **Retry after readiness**: The plugin does not add extra backoff delay, so the next attempt can run right away\n5. **Restart only if needed**: Restart OpenCode only if the browser stays unavailable after retrying\n\nThe plugin will display messages like:\n- `[Browser MCP] The browser connection looks unavailable. Re-enable the Browser MCP extension or browser, then retry.`\n- `[Browser MCP] Connection restored. Continuing without extra retry delay.`\n\n### Browser MCP Not Working\n\n1. **Check extension is installed**: Open your browser and verify the Browser MCP extension is installed and enabled\n2. **Verify MCP server config**: Ensure your `opencode.json` has the correct MCP configuration\n3. **Check Node.js**: Ensure Node.js is installed: `node --version`\n4. **Test MCP connection**: Restart OpenCode after adding the MCP configuration\n\n### Plugin Not Loading\n\n1. **Check file location**: Ensure the plugin file is in the correct directory\n2. **Check file name**: Plugin files should end in `.ts` or `.js`\n3. **Check syntax**: Ensure the TypeScript/JavaScript syntax is valid\n4. **Check logs**: Look for plugin initialization messages in OpenCode output\n\n### Tools Not Available\n\n1. **Check MCP server status**: Ensure the Browser MCP server started successfully\n2. **Check tool configuration**: Verify tools aren't disabled in your config\n3. **Restart OpenCode**: Try restarting OpenCode after configuration changes\n\n### Debug Mode\n\nEnable debug logging by modifying the plugin or checking OpenCode logs:\n\n```bash\n# Check OpenCode logs\nopencode --verbose\n```\n\n## Development\n\n### Building from Source\n\nIf you want to modify the plugin:\n\n1. Clone the repository\n2. Make your changes to `src/index.ts`\n3. Test locally by copying to your OpenCode plugin directory\n4. Submit a PR if you'd like to contribute!\n\n### Plugin Architecture\n\nThe plugin uses OpenCode's plugin system hooks:\n\n- `experimental.chat.system.transform`: Inject speed-oriented browser guidance\n- `tool.definition`: Add performance hints to Browser MCP tools\n- `tool.execute.after`: Post-process browser tool results\n- `experimental.session.compacting`: Preserve browser context\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Submit a pull request\n\n## Resources\n\n- [Browser MCP Documentation](https://docs.browsermcp.io/)\n- [OpenCode Documentation](https://opencode.ai/docs/)\n- [OpenCode Plugin Guide](https://opencode.ai/docs/plugins/)\n- [MCP Servers in OpenCode](https://opencode.ai/docs/mcp-servers/)\n\n## License\n\nMIT License - See LICENSE file for details\n\n## Support\n\nFor issues and questions:\n\n- Browser MCP issues: [Browser MCP GitHub](https://github.com/browsermcp/browser-mcp)\n- OpenCode issues: [OpenCode GitHub](https://github.com/anomalyco/opencode)\n- Plugin issues: Open an issue in this repository\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes in each version.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichaljach%2Fopencode-browser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmichaljach%2Fopencode-browser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichaljach%2Fopencode-browser/lists"}