SnapSurf

SnapSurf is a local-first, canvas-native AI browser. It combines a real Chromium desktop browser, Figma-like live browser frames, PageAgent browser-use control, local Codex or Claude routing, BYOK model profiles, and a localhost MCP bridge.

It is not a web demo and it does not depend on a SnapSurf-hosted AI server.

Live Chromium frames + right-side agent control + local/BYOK models + MCP

Description

SnapSurf is an agentic browser workspace for research, comparison, and repeatable browser work. Instead of putting an AI chat next to a normal tab strip, SnapSurf makes browsing spatial: every page can become a live frame on a canvas, every frame can be selected as an AI target, and every result can become reusable workspace memory.

The browser is designed for people who want AI to use the web with them, not away from them:

Researchers comparing many sources at once.
Operators who need repeated browser tasks to run quickly.
Builders who want MCP-controlled browser automation.
Local-first users who prefer Codex, Claude, or BYOK over a hosted AI browser account.
Power users who like Figma-style spatial workspaces more than linear tab piles.

What It Feels Like

SnapSurf opens as a canvas browser by default. Each window on the canvas is a real WebContentsView page that you can click, type in, scroll, resize, and move. The AI agent works on those same live pages, so human browsing and agent browsing happen in one workspace.

┌──────────────────────────────────────────────────────────────────┐
│ Top Bar: space, sources, MCP, command bar, running agents         │
├──────────────────────────────────────────────┬───────────────────┤
│ Canvas Workspace                              │ Agent Panel       │
│ live browser frames, graph, memory cards      │ chat, status,     │
│ Figma-like labels and resize handles          │ evidence, output  │
├──────────────────────────────────────────────┴───────────────────┤
│ Floating Bottom Canvas Controls: new frame, arrange, zoom, fit    │
└──────────────────────────────────────────────────────────────────┘

The product direction:

Canvas first, no left panel.
Real websites, not screenshots.
Dark gray native-app UI, not navy.
Minimal frame chrome with always-visible frame names.
Agent status that reads like a product, not a developer log.
Fast local model execution through Codex or Claude when available.
BYOK for OpenAI-compatible and Anthropic users.
MCP as an explicit local browser-control bridge.

Use Cases

Multi-Source Research

Open search results, company pages, docs, blogs, and articles as separate live frames. Ask SnapSurf to summarize the selected frames, extract claims, compare evidence, and produce next actions without losing the original pages.

Example:

선택한 창들에서 가격, 기능, 출시 시점만 뽑아서 비교표로 정리해줘

Browser-Use Automation

Use the right agent panel to run direct page actions: inspect, click, type, select, scroll, open URLs, and continue across multiple frames. SnapSurf keeps the page visible while the agent works, so the task does not feel like a hidden background script.

Example:

현재 창에서 가입 버튼을 찾고 입력해야 할 항목을 알려줘

Canvas-Based AI Control

Treat each browser window as an AI target. Select one frame for a narrow command, select several frames for comparison, or run a canvas-level command when the whole workspace matters.

Example:

이 캔버스 전체를 보고 리서치가 부족한 부분과 다음 검색어를 제안해줘

Local MCP Browser Service

Enable MCP to let external clients control the running SnapSurf app through a localhost-only bridge. This turns the browser into a local service that can open pages, inspect state, execute tasks, and return canvas context.

Example:

browser_execute_task: "현재 탭을 요약하고 근거 URL을 함께 반환해줘"

Operating Methodology

SnapSurf is built around a simple workflow:

Open: use the command bar to open URLs, searches, or new browser frames.
Arrange: place pages on the canvas like Figma frames.
Select: choose a frame, multiple frames, memory card, or the full canvas.
Command: ask the agent to summarize, compare, fill, extract, or decide next actions.
Verify: keep the live page visible while the agent works.
Preserve: save useful outputs as canvas memory for the next command.

This is the intended loop:

browse -> arrange -> select scope -> command agent -> verify result -> save memory

Current Status

SnapSurf is an early macOS-focused desktop prototype.

Already implemented:

Electron/Chromium desktop shell.
Canvas Mode as the default first screen.
Live browser frames backed by Electron WebContentsView.
Figma-like frame movement, resizing, labels, zoom, pan, and fit controls.
PageAgent-backed browser-use control.
Right-side Korean-first AI control panel.
Local Codex CLI provider.
Local Claude CLI provider.
OpenAI-compatible BYOK provider.
Anthropic BYOK adapter.
Local MCP bridge plus snapsurf-mcp stdio entrypoint.
Browser state persistence, downloads, permissions, credentials, private browsing, and recovery flows.
Unit, integration, and Electron E2E coverage.

Future work:

Polished packaged releases.
Windows and Linux builds.
Richer multi-agent canvas orchestration.
MCP extension pack management.
Workspace import/export and optional sync.

Quick Start

Requirements:

macOS for the current target.
Node.js 22 or newer.
pnpm 9 or newer.
Optional: Codex CLI for local Codex mode.
Optional: Claude CLI for local Claude mode.

Install:

pnpm install

Run the actual desktop app:

pnpm dev

Build the app:

pnpm build

Preview the built Electron app:

pnpm preview

Run the test suite:

pnpm typecheck
pnpm test
pnpm build
pnpm test:e2e

First App Run

Start SnapSurf with pnpm dev.
The app opens directly into Canvas Mode.
Use the top command bar for URLs, searches, and AI commands.
Use the bottom canvas controls to create a new browser frame, arrange frames, zoom, and fit the canvas.
Click inside a frame to browse normally.
Click the frame label or resize handle to move or resize it like a canvas frame.
Use the right panel to ask the agent to summarize, compare, fill, click, scroll, or plan next actions.

Example commands:

네이버 열어줘
이 창 요약해줘
선택한 창들에서 가격 차이 비교해줘
현재 페이지에서 사용자가 바로 할 수 있는 다음 행동을 정리해줘
하코다테 여행 맛집 후보를 찾아서 비교해줘

Real App Operation

Development mode runs the full Electron app, not a browser-only mock:

Electron main process creates and owns live Chromium views.
Renderer draws the canvas, controls, command bar, and agent panel.
Page preload exposes approved page-control actions over IPC.
AgentService orchestrates PageAgent, local/BYOK providers, and browser tools.
MCP bridge exposes the running app to external MCP clients when enabled.

Useful local commands:

# Start the desktop app
pnpm dev

# Build renderer, main process, and MCP CLI output
pnpm build

# Launch the compiled Electron output
pnpm preview

# Run the full Electron E2E suite
pnpm test:e2e

# Produce a macOS package with electron-builder
pnpm exec electron-builder --mac

Build outputs:

out/       compiled Electron app and MCP CLI
release/   packaged app output when electron-builder is used

Model Configuration

Open SnapSurf settings and choose a provider mode.

SnapSurf does not need a SnapSurf AI server. It can run through local tools or user-owned API keys.

Local Codex

Use this when you want SnapSurf to call a local Codex CLI.

Default:

Command: codex
Model: gpt-5.4-mini

The local CLI adapter converts PageAgent's OpenAI-style tool-call request into a strict local prompt and expects one tool call back.

Local Claude

Use this when you want SnapSurf to call a local Claude CLI.

Default:

Command: claude
Model: sonnet

OpenAI-Compatible BYOK

Use any OpenAI-compatible endpoint.

Required:

baseURL
model
apiKey

Anthropic BYOK

Use an Anthropic API key with the built-in adapter.

Required:

model
apiKey

Secrets are stored through the settings service and encrypted with Electron safeStorage when available.

MCP Usage

SnapSurf includes a local MCP bridge and a snapsurf-mcp stdio entrypoint.

Build first:

pnpm build

Then:

Open SnapSurf.
Enable MCP in settings.
SnapSurf writes a localhost bridge file containing a runtime port and token under Electron userData.
Point an MCP client at the stdio command:

snapsurf-mcp

Current MCP-oriented capabilities:

Get browser status.
Get tabs.
Open URLs.
Get page state.
Execute browser tasks.
Stop browser tasks.
Get canvas state.
Execute canvas tasks.

Security defaults:

MCP is disabled by default.
The bridge is localhost-only.
The bridge token is generated by the app.
Runtime clients can be revoked in settings.
MCP should be treated as browser-control capability, not a passive data API.

Canvas Browser UX

SnapSurf treats browser windows like canvas frames.

Frame behavior:

Each frame is a live Chromium page.
Frame size is logical canvas geometry.
Canvas zoom only changes how close the camera is.
Zooming does not change the frame's logical browser size.
Frame labels stay visible above live pages.
Resize handles stay available from the frame edge.
Bottom controls float above the canvas and do not resize pages.

Canvas actions:

Create a browser frame.
Move and resize frames.
Multi-select frames.
Arrange frames in rows, columns, and grids.
Connect frames into a research graph.
Store agent results as movable memory cards.
Run AI tasks against the selected frame, selected frames, memory card, or full canvas.

Agentic Browser Control

SnapSurf uses:

@page-agent/core
@page-agent/page-controller
@page-agent/llms

SnapSurf does not embed PageAgent's default UI panel. It provides its own right-side control panel with Korean-first task input, status, action history, privacy notes, evidence, result memory, and stop controls.

The agent can:

Inspect page state.
Click elements.
Type into inputs.
Select options.
Scroll pages.
Work across multiple canvas frames.
Open and control tabs.
Summarize, compare, and propose next actions.

Architecture

Electron Main Process
  ├─ TabManager
  │   ├─ Chromium WebContentsView tabs
  │   ├─ Canvas child windows for live browser frames
  │   ├─ Navigation, audio, zoom, downloads, print
  │   └─ Browser state persistence
  ├─ AgentService
  │   ├─ PageAgentCore orchestration
  │   ├─ ElectronPageController
  │   ├─ Canvas tools
  │   └─ Tab tools
  ├─ SettingsService
  │   ├─ Provider settings
  │   ├─ safeStorage-backed secrets
  │   └─ MCP token and bridge file
  ├─ McpBridge
  │   └─ Localhost authenticated JSON-RPC bridge
  └─ Browser services
      ├─ Permissions
      ├─ Credentials
      ├─ Downloads
      ├─ Privacy data
      └─ Context menus

Renderer
  ├─ Browser shell
  ├─ Canvas Mode
  ├─ Agent panel
  ├─ Settings panel
  ├─ Command palette
  └─ Korean-first user-facing state

Page Preload
  ├─ PageAgent-compatible page state
  ├─ Approved DOM actions
  ├─ Element highlight and cursor visuals
  └─ Sandboxed page-control IPC

MCP CLI
  └─ snapsurf-mcp stdio adapter

Repository Layout

src/main/              Electron main process
src/main/agent/        PageAgent orchestration and tools
src/main/tabs/         Browser tab and WebContentsView management
src/main/mcp/          Local MCP bridge
src/main/settings/     Settings, provider resolution, secret storage
src/page-preload/      Sandboxed page automation bridge
src/preload/           Renderer IPC API bridge
src/renderer/          React application
src/shared/            Shared types and pure domain logic
src/mcp/               snapsurf-mcp stdio entrypoint
tests/                 Vitest unit and integration tests
e2e/                   Playwright Electron E2E tests

Testing Strategy

SnapSurf has automated coverage for:

URL normalization.
Tab registry and tab strip behavior.
Provider resolution and health checks.
Secret storage.
MCP schema and bridge validation.
Agent event mapping.
Agent action and privacy logs.
Canvas state and frame layout.
Browser state persistence.
Permissions, downloads, credentials, private browsing.
Electron E2E for canvas, PageAgent control, MCP, popups, failures, cookies, and recovery.

Recommended pre-PR gate:

pnpm typecheck
pnpm test
pnpm build
pnpm test:e2e

Design Principles

Dark gray UI, not navy.
Canvas first, no left panel.
Real websites inside live frames.
Minimal chrome, clear frame labels.
One command bar for URLs, search, and AI tasks.
Agent status should read like a user-facing product.
The bottom control surface floats and must not resize pages.
Page frame labels must remain visible above live browser surfaces.
Canvas zoom changes the view, not the logical browser frame size.

Security Model

SnapSurf intentionally separates trust boundaries:

Web content stays inside Chromium pages.
Page actions go through a preload bridge.
Privileged operations stay in Electron main.
Secrets are not sent to the renderer as plaintext.
Credentials are stored encrypted where Electron safeStorage is available.
MCP uses an app-generated bridge token.
Local model CLIs run as local child processes and should be treated as trusted local tools.

Agent behavior is designed to be direct and fast. The current product direction is no per-action approval prompts. Sensitive actions are still logged and represented in action/privacy surfaces so the user can understand what happened.

Current Limitations

macOS is the first-class target.
Packaging for Windows and Linux is not complete.
The app is pre-1.0 and APIs may change.
Local model quality depends on the installed CLI and model.
MCP extension pack management is planned but not fully implemented.

Roadmap

Near-term:

Improve multi-agent canvas orchestration.
Add richer canvas memory and evidence views.
Continue smoothing WebContentsView/canvas layering.
Add MCP extension pack management.
Expand E2E coverage for long-running canvas tasks.

Later:

Windows and Linux packages.
Better release automation.
More provider adapters.
Import/export for canvas workspaces.
Optional hosted sync without compromising local-first mode.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT. See LICENSE.

Korean Summary

SnapSurf는 로컬 우선 AI 브라우저입니다. 기본 화면은 캔버스이며, 각 브라우저 창은 미리보기가 아니라 실제 Chromium 페이지입니다. 우측 패널에서 한국어로 AI 작업을 내릴 수 있고, 로컬 Codex/Claude 또는 BYOK 모델을 연결할 수 있습니다. MCP를 켜면 외부 클라이언트가 실행 중인 SnapSurf 브라우저와 캔버스를 제어할 수 있습니다.

빠르게 켜려면:

pnpm install
pnpm dev

검증하려면:

pnpm typecheck
pnpm test
pnpm build
pnpm test:e2e

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
docs/assets		docs/assets
e2e		e2e
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
electron.vite.config.ts		electron.vite.config.ts
package.json		package.json
playwright.config.ts		playwright.config.ts
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.cjs		postcss.config.cjs
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
tsconfig.mcp.json		tsconfig.mcp.json
tsconfig.node.json		tsconfig.node.json
tsconfig.web.json		tsconfig.web.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

SnapSurf

Description

What It Feels Like

Use Cases

Multi-Source Research

Browser-Use Automation

Canvas-Based AI Control

Local MCP Browser Service

Operating Methodology

Current Status

Quick Start

First App Run

Real App Operation

Model Configuration

Local Codex

Local Claude

OpenAI-Compatible BYOK

Anthropic BYOK

MCP Usage

Canvas Browser UX

Agentic Browser Control

Architecture

Repository Layout

Testing Strategy

Design Principles

Security Model

Current Limitations

Roadmap

Contributing

Security

License

Korean Summary

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages