claude-surf
starsforks
How to install claude-surf?
vibesurf-ai/claude-surf
$git clone https://github.com/vibesurf-ai/claude-surfA Claude Code plugin for control real browsers, execute AI skills, run workflows, and integrate with external apps.
README.md
| 1 | # Claude-Surf: A Claude Code plugin for controlling browser and real-time previewing |
| 2 | [](https://discord.gg/86SPfhRVbk) |
| 3 | [](https://opensource.org/licenses/MIT) |
| 4 | [](https://x.com/warmshao) |
| 5 | |
| 6 | |
| 7 | [English](README.md) | [简体中文](README_zh.md) |
| 8 | |
| 9 | ## Overview |
| 10 | |
| 11 | Claude-Surf is a Claude Code plugin that bridges Claude with [VibeSurf](https://github.com/vibesurf-ai/VibeSurf), enabling powerful browser automation and web interaction capabilities. |
| 12 | |
| 13 | ### What You Can Do |
| 14 | |
| 15 | - **Browser Control** - Navigate websites, interact with elements |
| 16 | - **VibeSurf Skills** - Search, crawl, extract data, summarize content, fetch url content |
| 17 | - **Workflows** - Execute pre-built automation workflows |
| 18 | - **App Integrations** - Gmail, GitHub, Slack, Supabase and 100+ apps via Composio/MCP |
| 19 | - **Browser-Use Agent** - Parallel multi-task automation using AI sub-agents |
| 20 | - **Website API** - Platform APIs for XiaoHongShu, YouTube, Douyin, Weibo, Zhihu, etc. |
| 21 | |
| 22 | ## Prerequisites |
| 23 | |
| 24 | ### 1. Claude Code |
| 25 | Install [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI. |
| 26 | |
| 27 | ### 2. VibeSurf |
| 28 | |
| 29 | Choose one of the following installation methods: |
| 30 | |
| 31 | #### Local Installation (Control Local Browser) |
| 32 | Use this method to control your local browser: |
| 33 | |
| 34 | ```bash |
| 35 | # Install VibeSurf |
| 36 | uv tool install vibesurf |
| 37 | |
| 38 | # Start VibeSurf server |
| 39 | vibesurf |
| 40 | ``` |
| 41 | |
| 42 | #### Docker Installation (Control Sandbox Browser) |
| 43 | Use this method to control a sandboxed browser in a container: |
| 44 | |
| 45 | ```bash |
| 46 | # Pull the image |
| 47 | docker pull ghcr.io/vibesurf-ai/vibesurf:latest |
| 48 | |
| 49 | # Run the container |
| 50 | docker run --name vibesurf -d --restart unless-stopped \ |
| 51 | -p 9335:9335 \ |
| 52 | -p 6080:6080 \ |
| 53 | -p 5901:5901 \ |
| 54 | -v ./data:/data \ |
| 55 | -e IN_DOCKER=true \ |
| 56 | -e VIBESURF_BACKEND_PORT=9335 \ |
| 57 | -e VIBESURF_WORKSPACE=/data/vibesurf_workspace \ |
| 58 | -e RESOLUTION=1440x900x24 \ |
| 59 | -e VNC_PASSWORD=vibesurf \ |
| 60 | --shm-size=4g \ |
| 61 | --cap-add=SYS_ADMIN \ |
| 62 | ghcr.io/vibesurf-ai/vibesurf:latest |
| 63 | ``` |
| 64 | |
| 65 | VibeSurf must be running for Claude-Surf to work. |
| 66 | |
| 67 | **Configuration**: By default, Claude-Surf connects to `http://127.0.0.1:9335`. You can customize this by setting the `VIBESURF_ENDPOINT` environment variable before starting Claude Code: |
| 68 | |
| 69 | ```bash |
| 70 | # Linux/macOS |
| 71 | export VIBESURF_ENDPOINT=http://192.168.1.100:9335 |
| 72 | |
| 73 | # Windows PowerShell |
| 74 | $env:VIBESURF_ENDPOINT="http://192.168.1.100:9335" |
| 75 | |
| 76 | # Windows CMD |
| 77 | set VIBESURF_ENDPOINT=http://192.168.1.100:9335 |
| 78 | ``` |
| 79 | |
| 80 | ## Installation |
| 81 | |
| 82 | ### From GitHub Marketplace (Recommended) |
| 83 | |
| 84 | ```bash |
| 85 | # Add the marketplace |
| 86 | /plugin marketplace add vibesurf-ai/claude-surf |
| 87 | |
| 88 | # Install the plugin |
| 89 | /plugin install surf |
| 90 | ``` |
| 91 | |
| 92 | ### Local Installation |
| 93 | |
| 94 | ```bash |
| 95 | # Clone repository |
| 96 | git clone https://github.com/vibesurf-ai/claude-surf |
| 97 | cd claude-surf |
| 98 | |
| 99 | # Add to marketplace and install |
| 100 | /plugin marketplace add ./ |
| 101 | /plugin install surf |
| 102 | ``` |
| 103 | |
| 104 | **Restart Claude Code** to load the plugin. |
| 105 | |
| 106 | ## Quick Start |
| 107 | |
| 108 | After installation, try a simple example: |
| 109 | |
| 110 | ``` |
| 111 | surf search AI news today |
| 112 | ``` |
| 113 | |
| 114 | This will use VibeSurf to search for today's AI news and return summarized results. |
| 115 | |
| 116 | ## VSCode Integration with Real-Time Browser Preview |
| 117 | |
| 118 | When using the Docker installation, you can control and preview the browser directly in VSCode alongside Claude Code: |
| 119 | |
| 120 | ### Open the Internal Browser |
| 121 | |
| 122 | 1. Open the Command Palette: |
| 123 | - Windows/Linux: `Ctrl + Shift + P` |
| 124 | - macOS: `Cmd + Shift + P` |
| 125 | 2. Type and select: `Simple Browser: Show` |
| 126 | 3. Enter the URL: `http://127.0.0.1:6080/` |
| 127 | 4. Press Enter |
| 128 | |
| 129 | ### Adjust VNC Screen Size |
| 130 | |
| 131 | 1. Click the **Settings** icon (gear button) on the left sidebar of the VNC viewer |
| 132 | 2. Under **Scaling Mode**, select **Local Scaling** |
| 133 | 3. This will allow the VNC screen to automatically resize to fit the window |
| 134 | |
| 135 | Now you can see Claude Code controlling the browser in real-time within VSCode! |
| 136 | |
| 137 | ### Demo Video |
| 138 | |
| 139 | <video src="https://github.com/user-attachments/assets/e46099cf-0e10-4088-8f10-b9d175f44f77" controls="controls">Your browser does not support playing this video!</video> |
| 140 | |
| 141 | |
| 142 | ## Contributing |
| 143 | |
| 144 | Contributions welcome! This is a markdown-first plugin - edit skills directly and test. |
| 145 | |
| 146 | ## License |
| 147 | |
| 148 | MIT License - see [LICENSE](LICENSE) for details |
| 149 | |
| 150 | ## Acknowledgments |
| 151 | |
| 152 | - [VibeSurf](https://github.com/vibesurf-ai/VibeSurf) - Browser automation framework |
People who liked this also viewed
6 picksType
- claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.WorkflowsJul 2026
- TrellisThe best agent harness.WorkflowsJul 2026
- reflyThe first open-source agent skills builder. Define skills by vibe workflow, run on Claude Code, Cursor, Codex & more. Build Clawdbot 🦞· APIs for Lovable · Bots for Slack & Lark/Feishu · Skills are infrastructure, not prompts.WorkflowsMar 2026
- pyspurA visual playground for agentic workflows: Iterate over your agents 10x fasterWorkflowsJun 2026
- claude-code🚀 Open source Claude Code CLI source code. Advanced AI Agent for developers. Includes TypeScript codebase for LLM tool-calling, agentic workflows, and terminal UI. Remember this is just the skeleton not the brain itself. Found by Chaofan Shou. WorkflowsApr 2026
- claude-codeClaude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.WorkflowsApr 2026
