Guides

Daemon Mode

The daemon is a background process that serves browser sessions over a Unix socket. Multiple agents can connect to one daemon, sharing open browsers, KV store, snapshots, and site knowledge.

Why you need the daemon

By default, each pagerunner mcp process opens the encrypted database directly. Only one process can hold the database lock at a time. If you open pagerunner in a second Claude Code window, you'll hit a DB lock error.

The daemon solves this. Start it once and every pagerunner mcp instance automatically detects it, connects over the Unix socket (~/.pagerunner/daemon.sock), and proxies all tool calls through it.

Starting the daemon

terminal
# Start in foreground
pagerunner daemon
# Start in background
pagerunner daemon &

Install as a background service

For automatic startup at login and crash recovery, install as a launchd service:

terminal
./scripts/install-launchd.sh

The script detects your installed pagerunner binary automatically. Logs are written to ~/.pagerunner/daemon.log.

After installing: Restart Claude Code. The daemon starts via launchd, and the MCP server reconnects in proxy mode. If Claude Code was already running, you may need two restarts — one for launchd to start the daemon, one for the MCP server to discover it.

Stopping the daemon

terminal
pkill -f "pagerunner daemon"

Multi-client architecture

With the daemon running, the architecture looks like this:

architecture
Claude Code #1
  → pagerunner mcp (proxy mode)
    → daemon (Unix socket)
      → Chrome sessions
      → Encrypted DB
Claude Code #2
  → pagerunner mcp (proxy mode)
    → same daemon
Cursor
  → pagerunner mcp (proxy mode)
    → same daemon

All clients share the same open browsers, KV store, snapshots, and site knowledge. An agent in one window can read data another agent wrote.

Status check

terminal
pagerunner status
→ shows daemon status, active sessions, profiles, DB health

Menu bar app

A native macOS menu bar companion app shows all Chrome profiles, active sessions, open tabs, and daemon status without opening a terminal. One-click session management, checkpoint saving, and macOS notifications.

build the menu bar app
pagerunner daemon &
cd apps/menubar
bash scripts/package.sh
open scripts/Pagerunner.app

Notifications

Send macOS notifications from any agent session:

notifications
notify(title="Deploy complete", body="v2.1.0 is live")

The daemon also sends automatic notifications for events like session crashes and checkpoint saves.

When to use daemon mode

  • Multiple Claude Code windows — avoids DB lock errors when running pagerunner in parallel
  • Mixed clients — Claude Code + Cursor + scripts all sharing the same browser state
  • Long-running sessions — daemon keeps Chrome alive even when you close your editor
  • Menu bar visibility — the companion app gives you a quick view of what's running

Back to: ← Documentation overview