Local Session Switcher

One-click test-user switching for apps on localhost.

Every local project shares one cookie jar. This Chrome MV3 extension keeps named users per project (admin, employee, customer) and swaps cookies plus localStorage / sessionStorage in one click. Tabs reload. No sign-out dance. Nothing leaves your machine.

Homepage: abdallahsaber065.github.io/local-session-switcher

Why it exists

Local apps all live on localhost, so they share cookies and storage. Testing a role-based app means logging out and back in, juggling incognito windows, or pasting tokens into DevTools. Chrome profiles work for two users and fall apart at five roles across three projects.

Local Session Switcher treats the project as the scope, not the URL — because the URL (http://localhost:3000) tells you nothing. You pick the project once; it is remembered.

Features

• Project-scoped user lists — picked manually and persisted, never inferred from the URL.
• One-click session swap — cookies + localStorage/sessionStorage written, stale auth pruned, tabs reloaded. The session goes A → B, never through a logged-out wipe.
• Auth recipes — reuse → refresh → login with CSRF preflights. A failed login aborts before touching the browser.
• Capture or seed — grab a live session, or import a JSON seed (standalone validator included). An agent skill can author the seed from your auth code.
• Test-user awareness — role tags, JWT expiry countdown, active-user detection, toolbar badge with initials.
• Keyboard-first — Alt+Shift+U / Y to cycle users, right-click menu, side panel.
• Extra local hosts — *.test, *.local, *.localhost, *.internal, and LAN/loopback IPs, requested only when you add them. Remote hosts are refused.
• Local-only — no analytics, no servers. Recipe URLs are origin-guarded to the project's own origins.

Works in Chrome, Brave, and other Chromium browsers.

Supported auth presets

Starting points in Settings → Auth — edit URLs and field names to match the project.

Preset	Typical stack
Session cookie	Express / Passport / Rails
NextAuth credentials	Next.js credentials provider (CSRF preflight)
Laravel Sanctum	SPA + sanctum/csrf-cookie
Django session	CSRF form login
JWT + refresh	Access token in localStorage, refresh endpoint

2FA / social / OTP logins stay manual: sign in once, then Capture current tab.

Install

From a GitHub Release (current)

1. Download local-session-switcher-*.zip from the latest Release.
2. Unzip it.
3. Open chrome://extensions → enable Developer mode → Load unpacked → pick the unzipped folder.

Chrome Web Store

Store listing is in progress. This section will get the install link when review completes.

From source

pnpm install && pnpm build

Then load unpacked from .output/chrome-mv3.

Quick start

node test-harness/server.mjs   # fake login page + auth API on http://localhost:3456

1. Open http://localhost:3456 and click Log in as Alice Admin.
2. Popup → Settings: create a project with origin http://localhost:3456, or import skills/session-switcher-seed/assets/example.seed.json (point its origins at :3456 if you use the harness as-is).
3. Popup → Capture current tab → name it Alice, tag admin.
4. On the harness, log in as Carol Customer and capture her too.
5. Click a user in the popup. The tab reloads as that user.

Keyboard: Alt+Shift+U next user, Alt+Shift+Y previous.

Settings — project rail, tabs for Overview / Auth / Users / Data:

Popup — ledger of test users with live session states:

Config / seed JSON

Everything is editable as JSON (Settings → Raw JSON per project, or backup/seed import). Shape:

{
  "schemaVersion": 1,
  "projects": [
    {
      "id": "my-app",
      "name": "My App",
      "origins": ["http://localhost:3000", "http://127.0.0.1:8000"],
      "tags": [{ "name": "admin", "color": "#ef4444" }],
      "clear": {
        "cookies": "all",                                        // or { "names": [] } / { "prefixes": [] }
        "localStorage": { "mode": "all", "exclude": ["theme"] }, // or { "mode": "keys", "keys": [] }
        "sessionStorage": "all"
      },
      "reload": "matching-tabs",                                 // | "active-tab" | "none"
      "users": [
        {
          "id": "u-admin",
          "name": "Admin",
          "tags": ["admin"],
          "cookies": [{ "name": "session", "value": "…", "path": "/", "hostOnly": true }],
          "storage": { "http://localhost:3000": { "localStorage": { "token": "…" }, "sessionStorage": {} } }
        }
      ]
    }
  ]
}

Seed import merges: projects by id/name, users by id/name (seed wins); missing user ids are generated and missing fields get defaults.

This is the beginning of the README. Read the rest at the original. Read the full README ↗