Documentation
Everything you need to get started with warpsurf.
Important: Warpsurf is an open source research project. Browser automation carries inherent risks. Monitor agents while they work and use capped API keys with spending limits. Use warpsurf at your own risk.
Installation
Chrome Web Store (Recommended)
- Visit the Chrome Web Store
- Click "Add to Chrome"
- Pin the extension for easy access
Manual Installation (Developer Mode)
# Clone the repository
git clone https://github.com/warpsurf/warpsurf.git
cd warpsurf
# Install dependencies
pnpm install
# Build the extension
pnpm build:store
Then in Chrome:
- Navigate to chrome://extensions
- Enable "Developer mode"
- Click "Load unpacked"
- Select the dist folder
Usage
After installation, click the warpsurf icon in your browser toolbar to open the side panel. Add your API keys in Settings and select your preferred model.
Workflows
Warpsurf supports five interaction modes. The smart router automatically selects the best workflow, or you can force a specific mode with slash commands:
- Auto — the smart router triages your query to the best workflow automatically
- Chat /chat — conversational interface for quick questions, with streaming responses and session history
- Search /search — web-grounded answers with sources, powered by provider-native search tools
- Agent /agent — autonomous browsing agent that navigates, clicks, types, and scrolls to complete tasks
- Multi-Agent /magent — orchestrate multiple agents in parallel for complex workflows and research tasks
- Tool — natural language settings control. Change models, temperature, vision mode, timeout, context tabs, and more through conversation
Features
| Feature | Description |
|---|---|
| Smart Router | Queries are automatically triaged to the right workflow — chat, search, or agent |
| Chat | Conversational interface powered by leading LLMs |
| Search | Low-latency web-augmented chat that finds and summarizes information from across the web |
| Agent | Autonomous browsing agent that navigates and interacts with any webpage |
| Multi-Agent | Orchestrate multiple agents in parallel for complex workflows and research tasks |
| Conversational Tools | Change models, temperature, vision, timeout, and context tabs through natural language |
| Voice Input | Speech-to-text via OpenAI Whisper or Google Gemini with optional auto-submit |
| Attachments | Drag-and-drop or paste images, text files, PDFs, and JSON (up to 4MB) |
| Context Menus | Right-click to explain text, summarize pages, or analyze images |
| Take Control | Agents hand back control at critical junctures for your input |
| Pause & Resume | Pause running agents with optional instructions when resuming |
| Live Follow-Up | Send instructions to a running agent without stopping, with queueable messages |
| Emergency Stop | One-click stop for all running workflows |
| Workflow Graph | Visual DAG of multi-agent subtasks with real-time node status |
| Trajectory View | Timeline of agent actions grouped by site with visual markers |
| Agent Manager | Dashboard with search, live tab previews, and task launch |
| Tab Context | Manual or auto tab context with privacy controls |
| Tab Management | Agents operate in their own tab groups with optional cleanup |
| Privacy & Firewall | Runs locally with URL firewall for allow/deny domain control |
| Favorites | Save, import, and reorder prompts for quick access |
| Usage Tracking | Real-time token and cost statistics per session, role, and model |
| Live Pricing | Live pricing data for accurate cost predictions |
| Task Estimation | Preview steps, duration, and cost before starting; switch models in preview |
| History Context | Optionally use browser history with configurable time windows |
| Session Restore | Workflows persist and resume with buffered events on reopen |
| Themes | Dark, light, and auto (system preference) |
Agent Controls
Warpsurf provides several mechanisms for human-in-the-loop control:
- Take Control — agents can request a handover at critical decision points
- Pause & Resume — pause a running agent at any time, optionally provide instructions when resuming
- Live Follow-Up — send additional instructions to a running agent without stopping it
- Emergency Stop — instantly cancel all running workflows with a single click
Input Methods
- Text — type queries directly in the side panel chat input
- Voice — click the microphone button for speech-to-text via OpenAI Whisper or Google Gemini
- Attachments — drag-and-drop files and images, or paste from clipboard (images, text, PDF, JSON up to 4MB)
- Context Menus — right-click to "Explain this", "Summarize this page", or "Explain image"
- Slash Commands — prefix with /chat, /search, /agent, or /magent to force a workflow
Context & History
- Tab Context — manually select open tabs to include as context
- Auto Tab Context — automatically use open tabs with configurable privacy controls
- Browser History — optionally include a summarized window of browsing history
- Session History — full chat history with session management and restore on reopen
- Favorites — save and organize most-used prompts with import/export support
Cost Management
- Usage Tracking — real-time token and cost statistics broken down by role and model
- Task Estimation — preview estimated steps, duration, and cost before starting
- Live Pricing — optionally fetch live pricing data for accurate cost calculations
Model Compatibility
Warpsurf is model-agnostic. Bring your own API keys from any of these providers:
- OpenAI (GPT-4o, o1, o3, etc.)
- Anthropic (Claude)
- Google (Gemini)
- xAI (Grok — native integration)
- OpenRouter (hundreds of models)
- DeepSeek
- Cerebras
- Groq
- Ollama (local models)
- Any OpenAI-compatible API
Each workflow role (chat, search, agent, navigator, planner, validator, multi-agent) can use a different model.
Settings
The Options page provides granular control:
- API Keys — add keys for each provider
- Models — select models for each workflow role
- Tabs — configure tab context behavior
- Web — URL firewall with allow/deny lists
- Voice — STT provider, model, and auto-submit
- Agent — planner/validator, vision, timeout, loop detection
- Pricing — toggle live pricing data
- Warnings — per-chat warnings and privacy notices
Most settings can also be changed conversationally — say "Switch to Claude for all models" or "Turn on vision mode".
Tips
These Chrome extensions can improve agent performance:
- Ad Blocker — removes ads and popups that can disrupt agents
Contributing
Warpsurf is an open source community project. Contributions are welcome!
- Check out the GitHub repository
- Report bugs and security issues
- Submit feature requests