vibesurf

VibeSurf - Browser Automation

Control real browsers through VibeSurf. This skill delegates to detailed reference guides.

? VIBESURF STATUS

Check if VibeSurf is running:

curl $VIBESURF_ENDPOINT/health

• ✅ HTTP 200 → Proceed with vibesurf skills
• ❌ Connection refused → Ask user to run vibesurf (NEVER run it yourself)

Default endpoint: http://127.0.0.1:9335

How to Call VibeSurf API

VibeSurf exposes three core HTTP endpoints:

1. List Available Actions

GET $VIBESURF_ENDPOINT/api/tool/search?keyword={optional_keyword}

Returns all available VibeSurf actions.

2. Get Action Parameters

GET $VIBESURF_ENDPOINT/api/tool/{action_name}/params

Returns JSON schema for the action's parameters.

3. Execute Action

POST $VIBESURF_ENDPOINT/api/tool/execute
Content-Type: application/json

{
  "action_name": "action_name_here",
  "parameters": {
    // action-specific parameters
  }
}

Workflow:

1. Search for action → Get action name
2. Get params schema → See required/optional parameters
3. Execute → Call with parameters

⚠️ Parameter Error Handling

ALWAYS call GET /api/tool/{action_name}/params before executing ANY action if you are unsure about parameters.

---

Which Reference to Read

Task Type	Read Reference	Action Name
AI web search	references/search.md	skill_search
Fetch URL content as markdown	references/fetch.md	skill_fetch
Extract lists/tables	references/js_code.md	skill_code
Extract page content	references/crawl.md	skill_crawl
Summarize page	references/summary.md	skill_summary
Stock/financial data	references/finance.md	skill_finance
Trending news	references/trend.md	skill_trend
Screenshot	references/screenshot.md	skill_screenshot
Precise browser control	references/browser.md	browser.* actions
Task-oriented automation (sub-agent)	references/browser-use.md	execute_browser_use_agent
Social Media Platform APIs	references/website-api.md	call_website_api
Pre-built workflows	references/workflows.md	execute_workflow
Gmail/GitHub/Slack	references/integrations.md	execute_extra_tool
LLM profile settings	references/config-llm.md	/api/config/llm-profiles/*
MCP server config	references/config-mcp.md	/api/config/mcp-profiles/*
VibeSurf key/workflows	references/config-vibesurf.md	/api/vibesurf/*
Composio key/toolkits	references/config-composio.md	/api/composio/*
Schedule workflows	references/config-schedule.md	/api/schedule/*

---

Configuration References

Config Task	Reference	When to Use
Add/switch LLM	references/config-llm.md	Manage AI model profiles (OpenAI, Anthropic, etc.)
Add MCP server	references/config-mcp.md	Configure MCP integrations for extended tools
VibeSurf API key	references/config-vibesurf.md	Set up API key, import/export workflows
Enable Gmail/GitHub/etc	references/config-composio.md	Configure Composio toolkits and OAuth
Schedule workflows	references/config-schedule.md	Set up cron-based workflow automation

Note: After configuring Composio or MCP tools, use them through the references/integrations.md (see tool naming: cpo.{toolkit}.{action} or mcp.{server}.{action}).

---

Decision Flow

Browser/Web Task
│
├─ Need to search for information/bug/issue? → Read [references/search.md](references/search.md) [PREFERRED]
│  Examples: "Search for solutions to [bug name]", "Find latest info about [topic]"
│
├─ Need to fetch URL content directly? → Read [references/fetch.md](references/fetch.md)
│  Examples: "Fetch content from [URL]", "Get documentation at [URL]", "Read this webpage"
│
├─ Need to open website? → Read [references/browser.md](references/browser.md)
│  Examples: "Open documentation site", "Go to [URL]", "Check this page"
│
├─ Need to extract data?
│  ├─ Lists/tables/repeated items? → Read [references/js_code.md](references/js_code.md)
│  └─ Main content? → Read [references/crawl.md](references/crawl.md)
│
├─ Need summary? → Read [references/summary.md](references/summary.md)
│
├─ Stock/finance data? → Read [references/finance.md](references/finance.md)
│
├─ Trending news? → Read [references/trend.md](references/trend.md)
│
├─ Screenshot? → Read [references/screenshot.md](references/screenshot.md)
│
├─ Need precise control or step-by-step operations? → Read [references/browser.md](references/browser.md)
│  Examples: "Click the button", "Type in the field", "Scroll down"
│
├─ Complex task-oriented automation? → Read [references/browser-use.md](references/browser-use.md)
│  Examples: "Fill out this form", "Extract data from multiple pages"
│
├─ Platform API (XiaoHongShu/Youtube/etc)? → Read [references/website-api.md](references/website-api.md)
│
├─ External app (Gmail/Google Calendar/GitHub)? → Read [references/integrations.md](references/integrations.md)
│
├─ Pre-built workflow? → Read [references/workflows.md](references/workflows.md)
│
└─ Need to configure LLM/MCP/VibeSurf/Composio/Schedule? → Read config-* references
   - LLM profiles → [references/config-llm.md](references/config-llm.md)
   - MCP servers → [references/config-mcp.md](references/config-mcp.md)
   - VibeSurf key/workflows → [references/config-vibesurf.md](references/config-vibesurf.md)
   - Composio key/toolkits → [references/config-composio.md](references/config-composio.md)
   - Schedule workflows → [references/config-schedule.md](references/config-schedule.md)

---

Quick Reference

Goal	Read Reference	Action
Search web	references/search.md	skill_search
Fetch URL content	references/fetch.md	skill_fetch
Extract prices/products	references/js_code.md	skill_code
Get main content	references/crawl.md	skill_crawl
Summarize page	references/summary.md	skill_summary
Stock data	references/finance.md	skill_finance
Hot topics	references/trend.md	skill_trend
Take screenshot	references/screenshot.md	skill_screenshot
Click/navigate/type	references/browser.md	browser.click, browser.navigate, etc.
Task-oriented automation	references/browser-use.md	execute_browser_use_agent
Social Media Platform APIs	references/website-api.md	call_website_api
Send email	references/integrations.md	execute_extra_tool
Run workflow	references/workflows.md	execute_workflow
Configure LLM profiles	references/config-llm.md	/api/config/llm-profiles/*
Configure MCP servers	references/config-mcp.md	/api/config/mcp-profiles/*
Configure VibeSurf key	references/config-vibesurf.md	/api/vibesurf/verify-key
Enable Composio toolkits	references/config-composio.md	/api/composio/toolkits
Schedule workflows	references/config-schedule.md	/api/schedule/*

---

Common Patterns

Request	Read Reference	Action
"Search for X"	references/search.md	skill_search
"Fetch content from [URL]"	references/fetch.md	skill_fetch
"Extract all prices"	references/js_code.md	skill_code
"Summarize this page"	references/summary.md	skill_summary
"Stock info for AAPL"	references/finance.md	skill_finance
"What's trending"	references/trend.md	skill_trend
"Take a screenshot"	references/screenshot.md	skill_screenshot
"Navigate and click"	references/browser.md	browser.navigate, browser.click
"Fill out this form"	references/browser-use.md or references/browser.md	execute_browser_use_agent or manual browser
"Get XiaoHongShu posts"	references/website-api.md	call_website_api
"Send Gmail"	references/integrations.md	execute_extra_tool
"Run video download"	references/workflows.md	execute_workflow
"Configure LLM"	references/config-llm.md	/api/config/llm-profiles
"Add MCP server"	references/config-mcp.md	/api/config/mcp-profiles
"Set VibeSurf API key"	references/config-vibesurf.md	/api/vibesurf/verify-key
"Enable Gmail/GitHub"	references/config-composio.md	/api/composio/toolkits
"Schedule workflow"	references/config-schedule.md	/api/schedule/*

---

Error Handling

Error	Solution
VibeSurf not running	Check status: curl $VIBESURF_ENDPOINT/health<br>If not running: Inform user to run vibesurf<br>NEVER run the command yourself
Don't know which reference	Read decision tables above
Action not found	Call GET /api/tool/search to list all actions
Wrong parameters	Call GET /api/tool/{action_name}/params to see schema
browser-use fails or gets stuck	Fallback to references/browser.md: use get_browser_state → browser.{action} → repeat loop
LLM/Crawl/Summary errors	Cause: No LLM profile configured<br>Solution: Read references/config-llm.md to add an LLM profile first
Integration tools empty/not found	Cause: Composio/MCP not configured<br>Solution: Read references/config-composio.md or references/config-mcp.md to enable toolkits first

---

Getting Browser State

? Check Current Browser State

When user asks about current page content or browser status (e.g., "What's on the current page?", "What tabs are open?", "What's the browser showing?"), read references/browser.md and use the get_browser_state action.

This is essential when you don't have context about what the user is currently viewing in their browser.

---

browser vs browser-use

Both can accomplish the same browser tasks - they're complementary:

Approach	Best For	How It Works
browser-use (references/browser-use.md)	Complex, long tasks	Task-oriented sub-agent: describe goal + desired output, agent figures out steps
browser (references/browser.md)	Precise control	Step-by-step manual control: explicit actions with full visibility
Hybrid	Best reliability	Try browser-use first, fallback to browser if it fails

Fallback pattern when browser-use fails:

browser-use fails or gets stuck
→ Read references/browser.md
→ get_browser_state (inspect page)
→ browser.{action} (perform action)
→ get_browser_state (verify & plan next)
→ repeat until complete

---

Resources

• GitHub: https://github.com/vibesurf-ai/VibeSurf
• Reference Docs: See references/ folder for detailed guides