browser-migrate

Move your browser profile (bookmarks, history, tabs) between browsers. macOS, CLI.

You test a lot of browsers — Chrome, Arc, Dia, Comet, Helium, Firefox, Zen, Safari — and switching means leaving your browsing life behind in the old one. This moves it.

Status: M4 (Chromium + Firefox/Zen + Safari; bookmarks, history, tabs)

Supported for read/export: Chrome, Dia, Brave, Edge, Arc (Chromium); Firefox, Zen (Gecko); Safari (WebKit). Data types: bookmarks + history everywhere; open tabs from Chromium (SNSS), Gecko (mozLz4 sessions) and Safari. Direct bookmark write currently targets Chromium; other engines use the assisted HTML-import path.

Safari reads require Full Disk Access (grant it to your terminal in System Settings → Privacy & Security). Without it, doctor says so instead of failing.

The bundle format is documented in FORMAT.md.

browser-migrate list                          # supported + installed browsers
browser-migrate doctor                         # bookmark / history counts per browser
browser-migrate export <browser> <outDir>      # export a profile to a portable bundle
browser-migrate migrate --from <a> --to <b>    # copy bookmarks a → b   [--dry-run]
browser-migrate import  --in <dir>  --to <b>   # import a bundle → b    [--dry-run]
browser-migrate restore <backupDir>            # undo a write
browser-migrate extensions <browser>           # list installed extensions + store links
browser-migrate extensions <a> --open <b>      # open a's extension store pages in b

Extensions can't be migrated as data (they're installed programs; state is keyed to per-browser IDs, and browsers block silent install). browser-migrate reads the installed list and gives store links — extensions <a> --open <b> opens each store page in the destination browser so you just click Install. Same-engine reuses the store ID; cross-engine is a name match (different store).

Two migration paths:

1. Portable / universal — export writes a bundle (manifest.json, bookmarks.json, history.json, bookmarks.html). The Netscape bookmarks.html imports into any browser via its UI. Zero risk.
2. Direct — migrate/import write bookmarks straight into a Chromium profile. Every write: (a) refuses while the dest browser is running, (b) backs up the profile first (~/.browser-migrate/backups, undo with restore), (c) writes a Bookmarks file with a correct Chrome checksum and strips the stale MAC from Local State so Chrome accepts it. The checksum algorithm is verified against a real Chrome Bookmarks file.

Import enforces the bundle version policy: same major proceeds, newer-major is refused (upgrade the tool), older-major proceeds.

Cross-machine: the export bundle is machine-independent — export on your old Mac, copy the bundle dir over, import (or open bookmarks.html) on the new one. Passwords never travel in a bundle (they'd be plaintext and Keychain is machine-bound).

MCP server (drive it from Claude)

The same operations are exposed as MCP tools so Claude (or any MCP client) can run them directly. Register with Claude Code:

claude mcp add browser-migrate -- bun run /ABSOLUTE/PATH/browser-migrate/src/mcp.ts

Or add to a client's mcpServers config:

{ "browser-migrate": { "command": "bun", "args": ["run", "/ABSOLUTE/PATH/src/mcp.ts"] } }

Tools: list_browsers, doctor, export_profile, migrate, import_bundle, restore. Writing tools (migrate, import_bundle) back up first and refuse while the destination browser is running — the same safety as the CLI. Preview with dryRun: true.

Architecture

Hub-and-spoke. One adapter per browser reads into a neutral intermediate format; export writes out of it. Adding a browser is one adapter file — N+M, not N×M.

source profile ─(adapter.read)─▶ Intermediate ─(export)─▶ bundle + bookmarks.html

• src/core/intermediate.ts — neutral format + epochToUnixMs (the one place the three engine time formats get normalized).
• src/core/adapter.ts — Adapter interface + capabilities matrix.
• src/adapters/chromium.ts — Chrome/Dia/Brave/Edge (shared Chromium layout).
• src/adapters/gecko.ts — Firefox/Zen (places.sqlite, profiles.ini, mozLz4 tabs).
• src/adapters/safari.ts — Safari (plist via plutil, History.db, FDA-aware).

Roadmap

• M2 ✓ — direct migrate/import behind backup+guard, Chromium checksum + Local State MAC strip, --dry-run, restore, bundle version policy.
• M3 ✓ — Firefox/Zen adapters (places.sqlite bookmarks + history, epoch + place: filtering), cross-machine via portable bundle.
• M4 ✓ — Safari read (plist bookmarks + Core-Data history, FDA-aware); tabs in the neutral format; Gecko tabs via a hand-rolled mozLz4 decoder; FORMAT.md.

Deferred, on purpose (with reasons):

• Non-Chromium bookmark write — writing places.sqlite / Safari plists is risky and version-fragile; the assisted bookmarks.html import path covers Firefox/Safari losslessly instead.
• Windows/Linux — Chromium profile paths are resolved per-OS, but only macOS is tested here. Firefox cross-OS layout still TODO (issue #5).

Write path is verified end-to-end on a live Chromium browser (Dia): a written bookmark survives a quit/relaunch and Dia re-signs the file rather than resetting it. Chrome's exact behavior can still vary by version, which is why every write is backed up and undoable with restore.

Passwords ride native CSV export/import (never reimplement browser crypto) and are excluded from bundles by default.

Install

Once a release is tagged (v*), CI builds macOS arm64 + x64 binaries and attaches them to the GitHub release. A Homebrew formula template lives in Formula/ — publish it to a homebrew-tap repo and then:

brew install navotvolkgroundup/tap/browser-migrate

Until then, run from source (below) or grab a release binary directly.

Develop

bun install
bun test
bun run src/cli.ts list
bun run compile     # single binary → ./browser-migrate

CI (.github/workflows/ci.yml) runs bun test on every push/PR. Tagging vX.Y.Z triggers release.yml to build and publish binaries.

MIT.