Skip to main content
Glama
sessfork-browser
by wasabihu

sessfork

CI License: MIT Python 3.9+ Zero Dependencies

English · 简体中文 · Interactive Visual Guide

Fork live Chrome auth sessions (Cookies + LocalStorage) into headless AI agent browsers — zero window focus theft, zero runtime dependencies.

sessfork Before vs After

When AI coding agents (Google Antigravity, Claude Code, or Cursor) connect directly to your main Chrome instance to reuse logged-in sessions, they hijack your active window, switch tabs, and break your flow.

sessfork decouples your UI viewport from browser auth state in a single command: it takes lock-free snapshots of your live Chromium SQLite Cookies database and LevelDB Local Storage/leveldb store, decrypts cookies in memory via native OS APIs, reconciles MVCC sequence numbers for SPA/JWT localStorage tokens, writes a strict 0600 Playwright storageState file, and wires a silent background Playwright MCP server (sessfork-browser) across your installed AI agents.


10-Second Lazy Quickstart

Install once, then just talk to your AI agent in plain language.

3-Step Lazy Workflow

Auto-detects installed AI tools (Antigravity, Claude Code, Cursor), registers the background sessfork-browser MCP server, and installs the global Agent SKILL.md:

curl -fsSL https://raw.githubusercontent.com/wasabihu/sessfork/main/install.sh | bash

Want to fork your first domains in the very same command? Pass them right after --:

curl -fsSL https://raw.githubusercontent.com/wasabihu/sessfork/main/install.sh | bash -s -- github.com linear.app

(Note: On each cookie fork, macOS asks to read "Chrome Safe Storage" from Keychain — click Allow. For pure LocalStorage JWT sites, pass --no-cookies for zero Keychain prompts. See the FAQ for the opt-in --cache-key.)

Option B · Zero-Install One-Shot (uvx)

Try sessfork immediately without touching global binaries:

uvx --from git+https://github.com/wasabihu/sessfork sessfork github.com

Option C · Global uv tool or Editable Local Checkout

# Install globally via uv
uv tool install git+https://github.com/wasabihu/sessfork.git

# Or clone locally
git clone https://github.com/wasabihu/sessfork.git
cd sessfork
uv tool install -e .

(Tip: Once installed, reload MCP servers once in your AI editor or run /mcp in CLI so sessfork-browser becomes active.)


Related MCP server: Browser MCP

5 Real-World Copy-Paste Examples

Once installed, you don't even have to remember CLI flags. Copy any prompt below straight to your AI agent — or run the 1-line command directly.

1. Triage GitHub PRs & CI Failures Silently

Copy & paste to your AI Agent: "Use sessfork to fork my github.com login session into sessfork-browser, then silently check my unread notifications and review the failing PR checks without switching or touching my active Chrome window."

sessfork github.com

2. Check Linear / Notion / Jira Sprint Tasks

Copy & paste to your AI Agent: "Fork my linear.app and notion.so sessions with sessfork and summarize today's assigned sprint blockers in the background."

sessfork linear.app notion.so

3. Pure SPA / JWT Apps & Localhost (Zero Keychain Prompt)

Modern SPAs (Supabase, Vercel dashboards, local dev apps) store bearer tokens in localStorage instead of HttpOnly cookies. Skip Keychain completely with --no-cookies:

Copy & paste to your AI Agent: "Run sessfork app.supabase.com localhost:3000 --no-cookies and verify the authenticated dashboard API responses in sessfork-browser."

sessfork app.supabase.com localhost:3000 --no-cookies

4. Paste Full URLs Straight from Your Address Bar

Don't bother stripping https:// or paths — sessfork automatically normalizes full URLs to their domain allowlist:

sessfork https://github.com/notifications

5. Fork from Arc, Brave, Edge, or a Specific Work Profile

sessfork supports chrome, canary, brave, edge, and arc, and automatically discovers your most recently active profile (or lets you target one explicitly):

sessfork x.com --browser arc
sessfork console.cloud.google.com --profile "Profile 1"

Architecture & Highlights

sessfork Architecture

  • Zero Runtime Dependencies: Pure Python standard library (>=3.9). Uses macOS CommonCrypto (/usr/lib/libSystem.B.dylib via ctypes) for AES-128-CBC cookie decryption (and openssl CLI on Linux) plus a built-in pure-Python LevelDB SSTable/WAL + Snappy reader.

  • Full Dual-Layer Auth (Cookies + LocalStorage):

    • SQLite Cookies: Handles Chromium Cookie DB meta.version >= 24 (SHA-256(host_key) 32-byte plaintext prefix stripping), live -wal/-shm sidecars, and SameSite / HttpOnly fidelity.

    • LevelDB LocalStorage (origins): Parses Chromium's _<origin>\x00 encoding-prefixed (0x00 UTF-16LE / 0x01 Latin-1) records across .ldb SSTables and .log WALs, honoring kTypeDeletion tombstones (localStorage.removeItem) so logged-out JWTs are never resurrected.

  • One-Command Auto-Wiring: sessfork <domain> and sessfork --setup auto-detect Antigravity, Claude Code, and Cursor (--target auto), resolve absolute npx paths (avoiding macOS GUI $PATH launch failures), and install SKILL.md.


Cheat Sheet

Goal

Command

One-time setup (MCP + Skill for all detected agents)

sessfork --setup

Fork Cookies + LocalStorage for domains

sessfork github.com linear.app

Fork LocalStorage JWT only (zero Keychain prompt)

sessfork app.spa.io --no-cookies

Fork SQLite Cookies only

sessfork github.com --no-local-storage

Choose source browser (chrome, arc, brave, edge, canary)

sessfork x.com --browser arc

Target specific profile folder

sessfork github.com --profile "Profile 1"

Wire Antigravity + Claude Code + Cursor explicitly

sessfork --setup --target all

Inspect cached domains & origins (redacted, safe)

sessfork --status

Re-fork all domains currently saved in state.json

sessfork --refresh

Opt-in: cache the derived key to skip future Keychain prompts (see FAQ)

sessfork github.com --cache-key

Force re-read the key from Keychain (e.g. after Chrome rotated it)

sessfork github.com --refresh-key

Delete any cached derived keys

sessfork --purge-keys

Remove cached state for specific domain (or all)

sessfork --clear linear.app / sessfork --clear


FAQ

Dedicated AI browsers (like ego-lite) ship a separate Chromium desktop app with built-in workspaces and import your Chrome profile so agents can act visually alongside you. sessfork takes a deliberately lighter, least-privilege approach:

  • Keep your existing browser: No second desktop browser to install, maintain, or migrate to — keep using your native Chrome, Arc, Brave, or Edge as usual.

  • Domain-scoped isolation (least privilege): Instead of handing an AI browser your entire profile (banking, primary email, corporate SSO, extensions, and all open tabs), sessfork forks only the exact domains you allowlist (e.g. sessfork github.com linear.app) into a one-way 0600 snapshot.

  • Standard Playwright ecosystem: Outputs standard Playwright storageState JSON, so it plugs straight into official @playwright/mcp as well as your own Playwright scripts and headless automation pipelines.

Choose a dedicated AI browser if you want a visual cursor watching the agent click or routinely deal with heavy headed anti-bot flows; choose sessfork if you want a zero-dependency CLI that keeps your main browser untouched and exposes only selected domains to a silent headless agent.

Chromium encrypts cookie values using a master passphrase stored under "Chrome Safe Storage" in your macOS Keychain. Click Allow so macOS authorizes security to read that entry. If a site uses localStorage tokens (many modern SPAs), pass --no-cookies to bypass Keychain completely.

By default sessfork does not store the derived decryption key anywhere, so macOS stays in charge of every authorization. If you prefer convenience, --cache-key saves the derived key to ~/.sessfork/keys.json (0600). Trade-off: any process running under your user account could then read that file and decrypt your Chrome cookies without a Keychain prompt. Run sessfork --purge-keys to remove it at any time.

  • macOS: fully supported and tested on real Chrome profiles.

  • Linux: experimental — covered by unit tests, but not yet verified against many real-world Chrome/Secret Service setups. Bug reports welcome.

  • Windows: not supported (Chromium on Windows uses DPAPI / app-bound encryption).

Chromium batches localStorage flushes from memory to LevelDB on disk roughly every 5 seconds. Wait ~5 seconds after signing in and re-run sessfork <domain>.

Run sessfork --clear <domain> to purge a single site, or sessfork --clear (or rm -rf ~/.sessfork) to wipe all cached session state.

No — only reload MCP once right after initial installation. Whenever you run sessfork <domain> or sessfork --refresh, sessfork updates an atomic 0600 mirror at ~/.sessfork/playwright-output/.sessfork-state.json inside Playwright MCP's --output-dir sandbox, and your AI agent hot-reloads it straight into the running sessfork-browser via browser_set_storage_state with zero restarts.


Security & Responsible Use

  • Domain Allowlist by Default: Only the domains/origins you explicitly name are extracted.

  • Strict File Permissions: ~/.sessfork/ is 0700 and ~/.sessfork/state.json is atomically created with 0600 permissions before a single byte is written.

  • Redacted Diagnostics: sessfork --status, --json, and SKILL.md never print raw cookie or LocalStorage values to stdout or agent prompt context.

  • No Key Persistence by Default: The derived cookie key lives only in memory for the duration of one command. Persisting it (--cache-key) is an explicit opt-in.

  • Isolated Headless Browser: sessfork-browser runs @playwright/mcp --headless --isolated, so each MCP session starts from the forked state.json instead of a persistent profile. Page snapshots and screenshots go to ~/.sessfork/playwright-output/ (--output-dir), never into a .playwright-mcp/ folder inside your projects.

  • Responsible Use: sessfork operates strictly within your signed-in OS user account and relies on native OS keyring authorization (macOS Keychain / Linux Secret Service) — it never bypasses OS access controls or sandboxes. Use it only on devices and accounts you own or are explicitly authorized to test, and always comply with target websites' Terms of Service.

  • Reporting Vulnerabilities: See SECURITY.md.

Development & Tests

PYTHONPATH=src python3 -m unittest discover -s tests -v

License

MIT

Available Tools

25 tools
browser_clickB
Destructive

Perform click on a web page

Inputs: target (required), button, element, modifiers, +1 more.

browser_closeA
Destructive

Close the browser and all open tabs.

Inputs: no named parameters.

browser_console_messagesC
Read-only

Returns all console messages

Inputs: level (required), all, filename.

browser_dragA
Destructive

Perform drag and drop between two elements

Inputs: endTarget (required), startTarget (required), endElement, startElement.

browser_dropA
Destructive

Drop files or MIME-typed data onto an element, as if dragged from outside the page. At least one of "paths" or "data" must be provided.

Inputs: target (required), data, paths, element.

browser_emulate_mediaA
Destructive

Emulate CSS media features for the page, for example switch between the light and dark color scheme. Omitted parameters are left unchanged; null clears an override.

Inputs: media, contrast, colorScheme, forcedColors, +1 more.

browser_evaluateC
Destructive

Evaluate JavaScript expression on page or element

Inputs: function (required), target, element, filename.

browser_file_uploadB
Destructive

Upload one or multiple files

Inputs: paths.

browser_fill_formB
Destructive

Fill multiple form fields

Inputs: fields (required).

browser_findA
Read-only

Search the accessibility snapshot of the current page for text or a regular expression. Returns matching snapshot nodes with a few lines of surrounding context (like search snippets), each shown under its path from the root of the tree, which is cheaper than capturing the whole snapshot when you only need to locate an element and its ref.

Inputs: text, regex, filename, maxResults.

browser_handle_dialogC
Destructive

Handle a dialog

Inputs: accept (required), promptText.

browser_hoverA
Destructive

Hover over element on page

Inputs: target (required), element.

browser_navigateC
Destructive

Navigate to a URL

Inputs: url (required).

browser_navigate_backA
Destructive

Go back to the previous page in the history

Inputs: no named parameters.

browser_network_requestA
Read-only

Returns full details (headers and body) of a single network request, or a single part if part is set. Use the number from browser_network_requests.

Inputs: index (required), part, filename.

browser_network_requestsA
Read-only

Returns a numbered list of network requests since loading the page. Use browser_network_request with the number to get full details.

Inputs: static (required), all, filter, filename.

browser_press_keyB
Destructive

Press a key on the keyboard

Inputs: key (required).

browser_resizeB
Destructive

Resize the browser window

Inputs: width (required), height (required).

browser_run_code_unsafeA
Destructive

Run a Playwright code snippet. Unsafe: executes arbitrary JavaScript in the Playwright server process and is RCE-equivalent.

Inputs: code, filename.

browser_select_optionB
Destructive

Select an option in a dropdown

Inputs: target (required), values (required), element.

browser_snapshotA
Read-only

Capture accessibility snapshot of the current page, this is better than screenshot

Inputs: boxes, depth, target, filename.

browser_tabsC
Destructive

List, create, close, or select a browser tab.

Inputs: action (required), url, index, isolatedContext.

browser_take_screenshotA
Read-only

Take a screenshot of the current page. Use browser_snapshot for actions by default. With the vision capability enabled, use screenshot coordinates with the coordinate-based mouse tools for elements not exposed in the accessibility snapshot.

Inputs: scale (required), type, target, element, +2 more.

browser_typeB
Destructive

Type text into editable element

Inputs: text (required), target (required), slowly, submit, +1 more.

browser_wait_forA
Read-only

Wait for text to appear or disappear or a specified time to pass. When both text and textGone are provided, waits for the first one to happen

Inputs: text, time, textGone.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 25 tools

    Disambiguation4/5

    Each tool maps to a fairly distinct browser action, and the descriptions actively disambiguate tricky pairs (snapshot vs screenshot, find vs snapshot, network_requests vs network_request). Minor overlap remains between browser_run_code_unsafe and the specialized tools, and between browser_type/browser_fill_form, but the guidance is clear enough to choose correctly.

    Naming Consistency5/5

    Every tool uses the same browser_<snake_case_action> convention with predictable verb or noun phrasing. The singular/plural pair browser_network_requests and browser_network_request is intentional and documented, not an inconsistency.

    Tool Count3/5

    25 tools is at the heavy end for the stated scope; while browser automation is inherently broad, several low-frequency capabilities (drop, emulate_media, resize, run_code_unsafe) push the surface toward the ceiling. It is workable but feels padded rather than tightly scoped.

    Completeness4/5

    Core lifecycle coverage is strong: navigation, interaction, forms, tabs, network, console, screenshots, and dialogs are all present. Gaps are minor but real — no forward navigation counterpart to browser_navigate_back, and no explicit cookie/storage or download handling, though browser_evaluate and browser_run_code_unsafe can work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with a user's real Chrome browser tabs, executing JavaScript, reading cookies, and making fetch requests within authenticated sessions.
      -
    • A
      license
      A
      quality
      A
      maintenance
      Enables AI agents to drive your real, logged-in Chrome browser with existing sessions and cookies, bypassing CAPTCHA and anti-bot measures, with support for multi-session and human-in-the-loop workflows.
      40
      66
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to access authenticated websites by reusing your existing browser profile and cookies, so you never share passwords and sessions persist between runs.
      5
      5
      MIT