Getting started

Run the MCP server, point your AI client at it, load the extension.

1. Run the MCP server

The simplest path is npx — no install needed. Your AI client will spawn the server for you on demand:

npx -y @peekdev/mcp@latest

This runs the stdio MCP server (it reads and writes the local SQLite at ~/.peek/sessions.db). You generally won't invoke it directly — your AI client (next step) does that.

The @latest tag is required while peek is in alpha: every published version is a prerelease (0.1.0-alpha.*), and a bare npx -y @peekdev/mcp resolves the implicit * range, which doesn't match prereleases (ETARGET: No matching version found). Pinning @latest forces the newest published build.

2. Configure your AI client

Add peek as an MCP server in your client's config. Pick the one you use:

Claude Code — ~/.claude.json

{
  "mcpServers": {
    "peek": {
      "command": "npx",
      "args": ["-y", "@peekdev/mcp@latest"]
    }
  }
}

Cursor — ~/.cursor/mcp.json

{
  "mcpServers": {
    "peek": {
      "command": "npx",
      "args": ["-y", "@peekdev/mcp@latest"]
    }
  }
}

VS Code Copilot — .vscode/mcp.json

{
  "servers": {
    "peek": {
      "command": "npx",
      "args": ["-y", "@peekdev/mcp@latest"]
    }
  }
}

3. Register the native messaging host

The extension talks to peek's local bridge through a Chrome native messaging host (chrome.runtime.connectNative('com.cubenest.peek')). The browser only spawns that host if it's registered, so this step is required — skip it and the extension loads but can't connect.

Install @peekdev/cli and run peek init; it registers the host for the browsers you pick (and configures your AI client's MCP server in the same pass, so you can skip step 2 if you run it):

npm install -g @peekdev/cli
peek init

• macOS — writes a manifest into ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/ (and the Chromium/Edge equivalents).
• Linux — writes a manifest into ~/.config/google-chrome/NativeMessagingHosts/.
• Windows — writes the manifest under %LOCALAPPDATA% and sets the registry key HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts\\com.cubenest.peek (and the Edge equivalent under HKCU\\Software\\Microsoft\\Edge\\NativeMessagingHosts\\).

Registration is consent-prompted — you choose which browsers to register.

4. Install the Chrome extension (alpha)

Install the extension from the Chrome Web Store. To develop against a local build instead, load the extension unpacked:

git clone https://github.com/Cubenest/rrweb-stack.git
cd rrweb-stack
pnpm install
pnpm build
pnpm --filter @peekdev/extension build

1. Open chrome://extensions.
2. Enable Developer mode (top right).
3. Click Load unpacked.
4. Select packages/peek-extension/.output/chrome-mv3/.

5. Enable peek on a site

• Open the side panel from the toolbar.
• Click Enable on this site. peek requests per-origin host permission from your user gesture and starts recording.
• When recording is active, an in-page glow (inside a closed shadow root, excluded from peek's own capture) and a toolbar badge appear. Toggle Show recording border in the side panel to hide the glow; the badge stays visible.
• (Optional) Toggle Deep capture to record response bodies via chrome.debugger. Off by default.
• (Optional) Set the per-origin permission level in the side panel. Default is Level 1 (observe-only).

6. Ask your agent

With the MCP server connected, ask your AI client things like:

• “What did I just do on this page?” (replays the latest rrweb frames)
• “Show me the failed network requests from the last 5 minutes.”
• “What errors are in the console for example.com?”

Next steps

• Privacy policy — what peek records and where it lives.
• @peekdev/mcp README — full MCP tool surface.
• @peekdev/cli README — peek init, sessions, audit log.
• @peekdev/extension README — side-panel UI and per-site activation.
• Manual QA checklist — end-to-end walk of the install path the maintainer used to verify this alpha.

Stuck? Open an issue on GitHub.