Getting started

Install Relay and capture your first Cursor session

Run relay install, trigger a Cursor task, and confirm hook events land in ~/.relay/captures before you sync to the API.

6 min read Updated Aug 2026

Relay hooks into Cursor and Claude Code without changing how developers work. This guide walks through install, a smoke-test task, and verifying local capture before you upload anything.

Prerequisites

  • macOS, Linux, or Windows with Git Bash or Command Prompt
  • Cursor or Claude Code installed
  • A Relay account on Starter (500 agent sessions per month, no credit card)

Install the CLI

From the monorepo relay/ directory:

cd relay
./install          # macOS / Linux / Git Bash

On Windows Command Prompt:

cd relay
install.cmd

The installer puts relay on PATH and wires capture hooks for Cursor and Claude Code. Default is local mode — transcripts stay in ~/.relay/captures/ until you pass --secret and run relay sync.

relay install --secret <org-key>   # optional: register this machine with the API
relay doctor                       # hooks, watcher, upload readiness

Confirm status

relay status
relay status --json

Local mode shows Mode: local auto-collect, hook paths, and the capture directory. API mode also shows the environment id after relay install --secret.

Trigger a capture

  1. Open Cursor and run any small agent task (refactor a function, explain a file).
  2. Wait for the task to finish.
  3. Inspect the nested auto-collect files:
find ~/.relay/captures -name '*.json' -not -name 'watch-*.json'

New JSON files should appear under an agent subdirectory (cursor/, claude-code/, …) with session metadata and tool-call events.

Optional: wrap a subprocess

For scripts or CI, use API capture mode:

relay run -- echo "capture smoke test"

Stdout/stderr stream normally while Relay records the wrapped run.

Next steps

Ready to try it in your workflow?

Start free — no credit card API reference →

Related guides