Skip to content

rahulcvwebsitehosting/wayfinder

BranchesTags

Repository files navigation

Wayfinder

The open-source browser agent for local AI automation.

License: AGPL v3 Chromium 148 TypeScript Go Bun Python 3.12+ GitHub

Wayfinder is an open-source, privacy-first browser agent powered by local AI models.
Your data never leaves your machine. Your models run on your hardware. You stay in control.

How local AI works: The browser engine (Chromium) does not run LLMs internally. The agent layer — a Bun/TypeScript server running alongside the browser — connects to local model servers like Ollama or LM Studio via their APIs. The LLM handles planning and reasoning; the agent layer executes browser actions through Chrome DevTools Protocol. This means Wayfinder works with any model server you already run.

How it works

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#6366F1', 'primaryTextColor': '#fff', 'primaryBorderColor': '#4f46e5', 'lineColor': '#6366F1', 'secondaryColor': '#312e81', 'tertiaryColor': '#e0e7ff'}}}%%
flowchart LR
    YOU([You]) --> WAY["Wayfinder
Agent"]
    WAY --> LOCAL["Local LLM
(Ollama / LM Studio)"]
    WAY --> CLOUD["Cloud LLM
(Claude / GPT / Gemini)"]
    LOCAL --> PLAN[Planner]
    CLOUD --> PLAN
    PLAN --> BROWSER[Browser Action]
    BROWSER --> SITES[Websites]
    BROWSER --> RESULT[Result]
    RESULT --> YOU
    
    style YOU fill:#312e81,color:#fff
    style WAY fill:#6366F1,color:#fff
    style LOCAL fill:#4f46e5,color:#fff
    style CLOUD fill:#818cf8,color:#fff
    style PLAN fill:#6366F1,color:#fff
    style BROWSER fill:#6366F1,color:#fff
Loading

Why Wayfinder?

Wayfinder is not a closed AI product — it's an open-source platform that puts you in full control:

Advantage Why it matters
Open Source (AGPL-3.0) Audit every line of code. No black boxes. No hidden telemetry.
Local Models First Run Ollama, LM Studio, or any local LLM. The agent layer connects to your model server — no dependency on cloud APIs.
Privacy-First Your API keys, browsing data, and conversations stay on your machine. Zero data collection.
Self-Hostable Deploy the agent server on your own infrastructure. Full autonomy.
Bring Your Own Key Use any LLM provider — local or cloud. You choose.
No Vendor Lock-In Swap models anytime. No subscriptions, no contracts, no forced upgrades.

Quick Start

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#6366F1', 'primaryTextColor': '#fff', 'primaryBorderColor': '#4f46e5', 'lineColor': '#a5b4fc', 'secondaryColor': '#1e1b4b', 'tertiaryColor': '#f5f3ff'}}}%%
flowchart LR
    A[Download & Install] --> B[Import Chrome Data]
    B --> C[Add Your API Key]
    C --> D[Start Automating]
    
    style A fill:#6366F1,color:#fff
    style B fill:#6366F1,color:#fff
    style C fill:#6366F1,color:#fff
    style D fill:#4f46e5,color:#fff
Loading

1. Download

No pre-built installer yet. This repo contains the full source code. Pre-built binaries will be available on the Releases page once the first build is published.

To build from source, see the Development section below.

2. Import your Chrome data (optional)

First launch walks you through importing bookmarks, passwords, history, and extensions from Chrome. Everything stays local.

3. Connect an AI provider

Wayfinder is bring-your-own-key. Add one or more providers in Settings:

Provider How to connect
Claude (Anthropic) API key from console.anthropic.com
OpenAI (GPT-4o, o3) API key from platform.openai.com
Google Gemini API key from aistudio.google.com
ChatGPT Pro/Plus OAuth login
GitHub Copilot OAuth login
Qwen Code OAuth login
Azure OpenAI Endpoint + API key
AWS Bedrock IAM credentials
OpenRouter API key
Ollama Run locally, connect from settings
LM Studio Run locally, connect from settings

4. Start using AI

Press Cmd+K (macOS) or Ctrl+K (Windows/Linux) to open the command center, or click the Wayfinder icon in the toolbar to open the AI chat side panel.

Features

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#6366F1', 'primaryTextColor': '#fff', 'primaryBorderColor': '#4f46e5', 'lineColor': '#a5b4fc', 'secondaryColor': '#1e1b4b', 'tertiaryColor': '#f5f3ff'}}}%%
mindmap
  root((Wayfinder))
    AI Agent
      Browse & Click
      Fill Forms
      Extract Data
      Natural Language
    MCP Server
      Claude Code
      Gemini CLI
      Cursor
      Any MCP Client
    Visual Workflows
      Graph Builder
      Repeatable
      Scheduled
    Privacy
      Local-first
      No Telemetry
      Your Keys Only
    Browser
      Chromium 148
      Vertical Tabs
      Ad Blocking MV2
      Chrome Extensions
    Integrations
      Gmail, Slack
      GitHub, Linear
      Notion, Figma
      40+ MCP Apps
Loading

🤖 AI Agent Engine

The core of Wayfinder. Ask the agent to do anything in the browser:

"Find all unread emails from GitHub about my PRs and summarize them"
"Go to Amazon, search for mechanical keyboards under $100, and sort by rating"
"Fill out this job application form with my saved profile"
"Monitor this product page for price drops and notify me"

The agent uses 50+ browser automation tools — navigate, click, type, scroll, extract, screenshot, download — all composed automatically.

🔌 MCP Server

Wayfinder exposes a Model Context Protocol (MCP) server so external AI coding agents can control the browser:

  • Claude Code: "Run the test suite in the browser"
  • Gemini CLI: "Take a screenshot of my app and find the CSS bug"
  • Cursor: "Debug this page's console errors"

Install with:

# macOS / Linux
curl -fsSL https://github.com/rahulcvwebsitehosting/wayfinder/releases/latest/download/install.sh | bash

# Windows PowerShell
irm https://github.com/rahulcvwebsitehosting/wayfinder/releases/latest/download/install.ps1 | iex

Then run wayfinder-cli init to link it to your browser.

🔁 Visual Workflows

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#6366F1', 'primaryTextColor': '#fff', 'primaryBorderColor': '#4f46e5', 'lineColor': '#a5b4fc', 'secondaryColor': '#1e1b4b', 'tertiaryColor': '#f5f3ff'}}}%%
flowchart TD
    START([Start]) --> LOGIN[Login to Dashboard]
    LOGIN --> EXPORT[Export Reports]
    EXPORT --> SAVE[Save to Folder]
    SAVE --> EMAIL[Email Summary]
    EMAIL --> END([Done ✓])
    
    style START fill:#6366F1,color:#fff
    style END fill:#4f46e5,color:#fff
Loading

Build drag-and-drop automations that run on a schedule. No coding required.

🧠 Persistent Memory

The agent remembers context across conversations — your preferences, past tasks, and important information persist automatically.

🧩 LLM Hub

Compare responses from multiple AI providers side-by-side on any webpage.

📂 Cowork (Files + Browser)

Combine browser automation with local file operations — research the web, save reports to your folder, edit files, all in one workflow.

⏰ Scheduled Tasks

Run agents on autopilot:

  • "Check for new job postings every morning at 8 AM"
  • "Monitor competitor pricing daily"
  • "Generate a weekly report every Friday"

🛡️ Privacy & Ad Blocking

  • uBlock Origin pre-installed
  • Manifest V2 support (stronger ad blocking than Chrome)
  • No telemetry, no tracking, no data collection
  • Your API keys stay on your machine

📐 Vertical Tabs

Side-panel tab management that keeps you organized even with 100+ tabs open.

🧩 Extension Management & MV2 Support

Wayfinder supports all Chrome extensions out of the box, but unlike Chrome, we actively preserve Manifest V2 — including full uBlock Origin with advanced blocking capabilities that Google's MV3 API restricts.

How to install extensions:

  • Chrome Web Store — Browse and install directly from the Chrome Web Store
  • Sideload CRX files — Load unpacked extensions from disk via chrome://extensions in developer mode
  • Pre-installed bundles — uBlock Origin ships with every build; additional bundled extensions are managed through Wayfinder's built-in extension manager in Settings

Why MV2 matters: Google's Manifest V3 deprecates webRequest blocking, which powers real ad blockers, privacy tools, and security extensions. By maintaining MV2 support, Wayfinder ensures these tools continue working without compromise.

How It Compares

Wayfinder Chrome Brave
Open Source ✅ ❌ ✅
Local Models First ✅ ❌ ❌
Privacy-First ✅ ❌ ✅
Self-Hostable ✅ ❌ ❌
Built-in AI Agent ✅ ❌ ❌
MCP Server ✅ ❌ ❌
Visual Workflows ✅ ❌ ❌
Bring Your Own Keys ✅ ❌ ✅
Ad Blocking (MV2) ✅ ❌ ✅
Chrome Extension Compat ✅ ✅ ✅

Key takeaway: Wayfinder is the only open-source browser agent purpose-built for local AI — you keep your data, you choose your models, you own the stack.

Architecture

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#6366F1', 'primaryTextColor': '#fff', 'primaryBorderColor': '#4f46e5', 'lineColor': '#a5b4fc', 'secondaryColor': '#1e1b4b', 'tertiaryColor': '#f5f3ff'}}}%%
graph TB
    subgraph BROWSER [Browser - Chromium 148]
        CORE[Chromium Core Engine]
        CDP[Chrome DevTools Protocol]
        EXT_SYS[Extension System]
        LLM_CHAT[AI Chat Side Panel]
        LLM_HUB[LLM Hub Panel]
        VERT[Vertical Tabs]
        SETTINGS[Wayfinder Settings]
    end
    
    subgraph AGENT [Agent Platform]
        SERVER[Bun Server]
        MCP_SRV[MCP Protocol]
        AGENT_LOOP[AI Agent Loop]
        WORKFLOW[Workflow Engine]
        MEMORY[Memory Store]
        TOOLS[50+ Browser Tools]
        AUTH[Provider Auth]
    end
    
    subgraph CLI [CLI Tools]
        WAY_CLI[wayfinder-cli - Go]
        DEV_TOOL[dev Toolchain]
    end
    
    CORE <--> CDP
    CDP <--> SERVER
    EXT_SYS <--> AGENT_LOOP
    SERVER <--> MCP_SRV
    SERVER <--> AGENT_LOOP
    AGENT_LOOP <--> TOOLS
    AGENT_LOOP <--> WORKFLOW
    AGENT_LOOP <--> MEMORY
    SERVER <--> AUTH
    WAY_CLI <--> MCP_SRV
    DEV_TOOL <--> SERVER
    
    subgraph EXTERNAL [External]
        AI[AI Providers]
        CODE_AGENTS[Claude Code / Cursor]
        WEB[Websites & APIs]
    end
    
    AUTH <--> AI
    MCP_SRV <--> CODE_AGENTS
    CORE <--> WEB
    
    style BROWSER fill:#4f46e5,color:#fff
    style AGENT fill:#6366F1,color:#fff
    style CLI fill:#818cf8,color:#fff
    style EXTERNAL fill:#1e1b4b,color:#fff
Loading

Repository Structure

wayfinder/
├── packages/wayfinder/                 # Chromium fork + build system
│   ├── chromium_patches/               # Patches applied to Chromium source
│   ├── build/                          # Python build CLI
│   ├── build_go/                       # Go build CLI (production)
│   └── resources/                      # Icons, entitlements, signing configs
│
└── packages/wayfinder-agent/           # Agent platform (TypeScript / Go)
    ├── apps/
    │   ├── server/                     # Bun server - AI agent loop + MCP
    │   ├── agent/                      # WXT browser extension (React)
    │   ├── cli/                        # Go CLI tool
    │   └── eval/                       # Benchmark framework
    │
    └── packages/
        ├── agent-sdk/                  # npm: @wayfinder/agent-sdk
        ├── cdp-protocol/               # CDP type bindings
        └── shared/                     # Shared constants & types
Component Language What it does
packages/wayfinder/ C++, Python, Go Chromium fork — the browser itself with patches, build system, and signing
apps/server/ TypeScript (Bun) MCP server + AI agent loop — connects to the browser via CDP, runs the agent, exposes MCP tools
apps/agent/ TypeScript (React, WXT) Browser extension — new tab page, side panel chat, onboarding, settings UI
apps/cli/ Go CLI tool — control Wayfinder from terminal or AI coding agents
packages/agent-sdk/ TypeScript Node.js SDK for browser automation with natural language
packages/cdp-protocol/ TypeScript Type-safe Chrome DevTools Protocol bindings
packages/shared/ TypeScript Shared constants, provider types, and common code

Development

Prerequisites

Tool Version Purpose
Bun 1.3.6+ JavaScript runtime for the agent platform
Go 1.24+ CLI tooling
Python 3.12+ Chromium build system
Node.js — Used by Bun-compatible tooling

Agent Platform (TypeScript / Go)

# Clone the repo
git clone https://github.com/rahulcvwebsitehosting/wayfinder.git
cd wayfinder

# Navigate to the agent platform
cd packages/wayfinder-agent

# Install dependencies
bun install

# Set up environment
cp .env.example .env
# Edit .env with your settings

# Start the development server
bun run dev:watch

This starts the agent server, MCP server, and browser extension in watch mode.

Browser Development (C++ / Chromium)

Building the browser from source requires the full Chromium toolchain (~100 GB disk, 3-5 hours):

# Install the build CLI
pip install -e packages/wayfinder/

# Provision Chromium source
python scripts/ci/setup_chromium.py \
  --chromium-root /path/to/chromium_root \
  --step checkout

python scripts/ci/setup_chromium.py \
  --chromium-root /path/to/chromium_root \
  --step sync

# Build
wayfinder build \
  --config build/config/release.windows.yaml \
  --chromium-src /path/to/chromium_root/src

Most contributors focus on the agent platform (TypeScript/Go). Browser development is only needed for deep Chromium-level changes.

Chromium Maintenance & Update Strategy

Forking Chromium is a long-term commitment. Here's how Wayfinder manages it:

Patch system: All changes to Chromium live in chromium_patches/ as structured patch files organized by feature layer. Patches are applied deterministically by the build CLI on top of a clean Chromium checkout — no permanent fork branch to maintain.

Rebase strategy:

  • Each Wayfinder release pins a specific Chromium tag (e.g., 148.0.7778.97)
  • When rebasing to a newer Chromium version, patches are reapplied via the build system
  • Patch conflicts are surfaced at apply time, not buried in merge commits
  • The series_patches module handles upstream patches (ungoogled-chromium, etc.) separately from Wayfinder-specific patches, making conflict resolution easier

Update cadence:

  • Security patches: Chromium releases critical security fixes monthly. Each new Chromium tag is evaluated for inclusion.
  • Feature updates: Major Chromium versions are adopted when the upstream improvements align with Wayfinder's roadmap.
  • Extension compatibility: Chromium's extension API changes are monitored to ensure existing patches remain compatible.

Risk acknowledgment: Maintaining a Chromium fork means staying on top of every CVE, API deprecation, and build system change. This is a known cost of providing a truly independent browser. Contributions and community testing are essential to keeping the fork healthy.

Downloading Pre-built Releases

Pre-built installers will be published on the Releases page once available. Each installer will include:

  • The full Wayfinder browser (Chromium 148)
  • The built-in AI agent engine
  • The MCP server
  • uBlock Origin with MV2 support
  • All pre-installed extensions

In the meantime, you can run the agent platform directly without building Chromium (see Development).

FAQ

Can I run Wayfinder entirely offline with local models? Yes. Connect Ollama or LM Studio and you never need an internet connection for AI — just for the websites you browse.

Is Wayfinder truly open source? Yes, AGPL-3.0. Every line of code is public. No proprietary components, no hidden telemetry, no backdoors.

How is this different from Browser Use or OpenAI Operator? Those are cloud-dependent SaaS products. Wayfinder is a self-hostable, open-source browser agent that runs on your own hardware with your own models.

Do I need an API key? Only if you use cloud providers. With local models (Ollama, LM Studio), no API key is needed.

Is my data sent to any server? No. Your API keys, browsing data, and conversations stay on your machine. Network requests are local to your LLM or to the websites you visit.

Can I use Chrome extensions? Yes. Wayfinder is a Chromium fork and supports all Chrome extensions. uBlock Origin is pre-installed with Manifest V2 support.

Can I run Wayfinder headlessly? Yes. Supports headless mode for automated workflows and CI pipelines. Use wayfinder-cli to launch in headless mode.

Contributing

Contributions are welcome! See CONTRIBUTING.md for detailed guidelines.

Quick start for contributors:

# Fork the repo, then:
git clone https://github.com/YOUR_USERNAME/wayfinder.git
cd wayfinder/packages/wayfinder-agent
bun install
bun run dev:watch

Note: The issue tracker and releases are at github.com/rahulcvwebsitehosting/wayfinder.

License

AGPL-3.0 — See LICENSE for details.

Wayfinder is built on Chromium and incorporates patches from ungoogled-chromium.

The open-source browser agent for local AI automation.

Get Started · Download · Contribute · Report Issue

About

Local-first open-source browser agent with MCP server & visual workflows

Topics

open-source automation privacy typescript chromium self-hosted browser-agent local-llm ollama mcp-server

Resources

Readme

License

AGPL-3.0, Unknown licenses found

Licenses found

AGPL-3.0
LICENSE
Unknown
LICENSE.ungoogled_chromium

Contributing

Contributing

Security policy

Security policy
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages