SessionLoom

SessionLoom is a local, open-source macOS authentication broker for AI agents. It lets an approved local agent work in the Chrome profile you already use without exporting passwords, copying cookies, disabling MFA, or placing credentials in an agent-readable vault.

Version 0.3 has four local parts:

• a native SwiftUI control center for service allowlists, agent permissions, pause/revoke, setup diagnostics, and audit activity;
• a policy-enforcing MCP server that exposes only scoped browser actions;
• the SessionLoom Browser Bridge, a Manifest V3 Chrome extension paired to this Mac through native messaging and a device-only Keychain record; and
• local Claude Desktop and OpenAI/Codex packages that launch the same broker under independent agent policies.

There is no SessionLoom cloud service, account, telemetry pipeline, analytics SDK, password export, cookie export, or token-read command.

Requirements

• Apple-silicon Mac running macOS 14 or later
• Google Chrome
• Codex, Claude Desktop, or Cursor for direct MCP access; the persistent-session launcher also works without an agent app

Release downloads

Packaged builds, when published, appear on this repository's Releases page — verify them against SessionLoom-SHA256SUMS.txt. Until a notarized Developer ID build ships, build from source with scripts/build-app.sh (current local builds are Apple Development signed; Gatekeeper will warn on unsigned redistribution).

Release artifacts:

• SessionLoom-macOS-arm64.zip — signed Mac app, installer, embedded extension, and connector packages
• SessionLoom-Browser-Extension.zip — unpacked Chrome-extension package
• SessionLoom-Claude.mcpb — private Anthropic MCP Bundle for Claude Desktop
• SessionLoom-OpenAI-plugin.zip — local OpenAI/Codex plugin source
• SessionLoom-source.zip — complete source
• broker and browser-extension CycloneDX SBOMs plus SessionLoom-SHA256SUMS.txt

Install the Mac app

Unzip SessionLoom-macOS-arm64.zip, open Terminal in the resulting folder, and run:

./install.sh

The installer places the app in ~/Applications/SessionLoom.app, links ~/bin/sessionloom, preserves unrelated Codex/Claude/Cursor configuration, installs a user-level Chrome native-messaging manifest, creates a non-displayable device-only pairing value in macOS Keychain, and starts SessionLoom at login. ~/bin/sessionbridge remains only as a compatibility link; new instructions use sessionloom.

Run:

~/bin/sessionloom doctor
~/bin/sessionloom integrations status
~/bin/sessionloom browser-pairing status

Load the browser extension

Chrome requires a one-time permission decision that the installer cannot silently make:

1. Open chrome://extensions in the Chrome profile that holds your signed-in sessions.
2. Enable Developer mode.
3. Choose Load unpacked.
4. Select ~/Applications/SessionLoom.app/Contents/Resources/BrowserExtension.
5. Confirm that SessionLoom Browser Bridge appears with ID gfnhdcgdijakjapfnifgdkjnfloliibn.

The extension requests debugger, tabs, activeTab, tabGroups, nativeMessaging, and <all_urls> because existing-profile CDP control requires them. Those broad browser permissions are constrained by the local broker's service allowlists, exact-origin checks, per-agent capabilities, pause/revoke, and owner-presence policy.

The extension accepts only protocol-v2 requests from sessionloom-policy-broker, only over a loopback ws://127.0.0.1 or ws://[::1] relay with an /extension/<UUID> path, and only after the native host verifies the pairing value. The value is stripped from the extension URL before authorization and is never displayed, copied, logged, or returned by the native host.

Agent integrations

sessionloom integrations install adds direct local MCP configuration for Codex and for Claude Desktop/Cursor when their configuration directories exist. Restart each agent app once after configuration changes.

The release also includes:

• SessionLoom-Claude.mcpb, a local MCPB that launches the trusted installed SessionLoom app as agent claude;
• SessionLoom-OpenAI-plugin.zip, an official-format local Codex workflow plugin. The app installer owns the single local MCP registration so the plugin cannot launch a competing browser broker.

The OpenAI plugin is supported in local Codex clients. A hosted ChatGPT app requires a public HTTPS MCP endpoint; exposing a private Mac browser session that way would violate SessionLoom's local trust boundary. The package therefore includes submission-readiness documentation but does not claim to be an OpenAI- or Anthropic-approved public listing.

First use

1. Open SessionLoom and choose Setup. Confirm the runtime, native host, device pairing, browser extension, and desired agent integration are ready.
2. Choose Services and enable only the services an agent may use. Each service is pinned to an exact HTTPS origin; add another exact origin only when the same service legitimately spans domains.
3. Choose Overview and set each agent's read, navigate, and interact capabilities. Keep owner authentication enabled for sensitive categories.
4. Restart Codex, Claude Desktop, or Cursor. The agent sees fifteen sessionloom_* tools, not unrestricted Playwright tools.
5. Verify with sessionloom_status, sessionloom_services, and a non-consequential service probe.

SessionLoom begins with Codex, Claude, and Cursor policies for configured services. Financial, publishing, destructive, security, and communication actions require Touch ID or the Mac login password by default. Approval is cached only for the same agent, service, and category and only for the locally configured duration.

Persistent-authentication SOP

For browser/admin work, agents must start with sessionloom_status and sessionloom_services, then use sessionloom_open and scoped tools. The CLI fallback is sessionloom doctor --json, sessionloom list --json, and sessionloom open <service> in the assigned persistent profile. Agents must not silently use a guest, private, temporary, or fresh profile when a configured SessionLoom service is available.

For native apps and API-first workflows, use an already authenticated official connector/OAuth session. SessionLoom is a browser broker, not an API token vault. Reused authentication changes only the login path; it never authorizes the underlying financial, publishing, destructive, security, or communication action.

See AUTH-SOP.md for the complete reusable rule.

Scoped tools

The local MCP server can list approved services, open approved origins, inspect an accessibility snapshot, find page text, take a screenshot, click, type, fill forms, select options, press keys, hover, wait for bounded page text, handle dialogs, and run a heuristic session-health check labeled authenticated-likely, expired-likely, or unknown.

It intentionally does not expose arbitrary JavaScript, raw CDP, arbitrary network requests, cookies, browser storage, password APIs, token reads, unrestricted URLs, shell execution, or Playwright unsafe-code tools. Every tool includes a title and read-only, destructive, idempotent, and open-world annotations for host review UX.

Pause, revoke, and reset

~/bin/sessionloom pause
~/bin/sessionloom resume
~/bin/sessionloom browser-pairing reset

Pause and policy changes are re-read before every browser action. You can disable one agent, remove a capability, disable a service, or remove a service from an agent allowlist. Resetting pairing deletes only the SessionLoom browser-pairing record; the next bootstrap or MCP start creates a new local value.

Local data

services.json stores service names, exact origins, enabled state, browser choice, and profile directory. policy.json stores agent allowlists and approval rules. audit.jsonl stores metadata such as time, agent, action, service, category, and result. Typed text, form values, passwords, cookies, tokens, screenshots, page content, and browser snapshots are not written to the audit log.

The browser-pairing value is a SessionLoom-specific local secret, not a website credential. It is stored as a device-only Keychain item and used only to authenticate the browser extension to the local broker. Configuration and audit files use mode 0600; parent directories use 0700.

Provider limits

SessionLoom does not guarantee that a provider will keep a session alive. A website may expire a cookie, revoke OAuth, require CAPTCHA, request a passkey, or force MFA/account recovery. SessionLoom does not bypass those controls. Use ~/bin/sessionloom open <service> for the assigned profile and hand control back for genuine user-presence gates.

Legacy 0.1 cleanup

Version 0.3 does not set, read, inject, or execute commands with provider tokens. It can only detect or delete legacy 0.1 Keychain items without retrieving their value:

~/bin/sessionloom token status github
~/bin/sessionloom token delete github

Build from source

The source build requires Swift 6, Node.js 20 or newer, npm, and a valid macOS code-signing identity:

./scripts/build-app.sh
swift test -Xswiftc -warnings-as-errors
npm --prefix AgentBridge test
npm --prefix BrowserExtension test
./scripts/package-release.sh

Public Mac redistribution additionally requires a Developer ID Application certificate and successful Apple notarization. Public Claude or ChatGPT listings require separate publisher, HTTPS policy/support, review-account, test-evidence, and directory approval gates.

Uninstall

Run ./uninstall.sh from the package or ./scripts/uninstall-local.sh from source. Uninstall removes the app, CLI links, login item, Chrome native host, device pairing, and managed Codex/Claude/Cursor entries while preserving unrelated agent configuration, local service/policy/audit files, and any legacy 0.1 provider-token items to avoid accidental destructive data loss.

Read SECURITY.md, THREAT-MODEL.md, and PRIVACY.md before broadening access.