Relay 🔄

Seamless AI context handoff across platforms.
Continue exactly where you left off — on Claude, Cursor, Copilot, or Antigravity — without losing a single decision.

The Problem

When you exhaust tokens on one AI coding assistant and switch to another, you lose everything:

| Approach | What goes wrong | |----------|----------------| | Paste raw chat history | New agent gets overwhelmed — hallucinates, loses the original goal | | Start fresh | Repeats the same failed approaches you just spent an hour debugging | | Manual summary | Strips the evidence, constraints, and rationale the next agent actually needs |

The Solution

Relay transfers work state, not conversation history.

It captures what actually matters — the decisions made, the hard constraints, the approaches that failed, and the precise next steps — and hands them off to any AI agent in a structured format it can immediately act on.

# About to hit your token limit?
relay save

# Switched to a new platform?
relay load --prompt --clipboard
# Paste into the new agent — it picks up exactly where you left off

Installation

Option 1: Via npm & GitHub (Recommended)

# Direct install from GitHub
npm install -g github:ajvikram/relay

Option 2: Standalone Binaries (No Node.js runtime required)

Download pre-built standalone executables from GitHub Releases:

• macOS Apple Silicon (M1/M2/M3/M4): relay-darwin-arm64
• macOS Intel (x64): relay-darwin-amd64
• Linux (x64 / ARM64): relay-linux-amd64 / relay-linux-arm64
• Windows (x64): relay-windows-amd64.exe

# One-liner for macOS (Apple Silicon):
curl -fsSL https://github.com/ajvikram/relay/releases/latest/download/relay-darwin-arm64 -o /usr/local/bin/relay && chmod +x /usr/local/bin/relay

Requirements: Git (and Node.js ≥ 18 if installing via npm)

Quick Start

# 1. Initialize Relay in your project
cd my-project
relay init

# 2. Install bootstrap rules (agents auto-read the handoff on session start)
relay install all

# 3. When you hit a token limit — save your context
relay save

# 4. On the new platform — load the context
relay load --prompt --clipboard
# Paste into the new agent — done

Commands

relay init

Initialize Relay in the current git repository. Creates the .relay/ directory and updates .gitignore.

relay init
relay init --dir /path/to/repo

relay save

Save the current session context as a structured handoff document.

relay save                  # Interactive guided mode — prompts for each section
relay save --agent          # Agent-assisted mode — generates a prompt to paste into your current AI
relay save --platform claude  # Override source platform

Interactive mode walks you through:

• Session goal and status
• Decisions made (with rationale and evidence)
• Non-negotiable constraints
• Failed approaches (so the next agent doesn't repeat them)
• Next steps (ordered, with file hints)

Agent-assisted mode (--agent) outputs a prompt you paste into your current AI agent. The agent writes the structured JSON, you paste it back, and Relay saves it. Best used when you're close to the token limit and want the agent to document its own work.

relay load

Load and display the current handoff context.

relay load                   # Display full handoff document
relay load --prompt          # Compact agent-ready prompt (fewer tokens, paste into new session)
relay load --clipboard       # Copy output to clipboard
relay load --json            # Raw JSON (for scripting)
relay load --prompt --clipboard  # Most common: copy compact prompt to clipboard

relay status / relay check

Inspect workspace alignment and detect code drift against the active handoff.

relay status                 # Human-readable drift & alignment report
relay check                  # Alias for relay status
relay status --json          # Raw JSON drift report

Identifies:

• Branch alignment vs. handoff branch
• Commit drift (number of commits made since handoff was recorded)
• Uncommitted modified/added/reverted files
• Immediate pending tasks

relay diff

Compare the active handoff against previous history archives.

relay diff                   # Compare active handoff against previous session
relay diff --from abc1234    # Compare a specific archive against active handoff
relay diff --from a1 --to b2 # Compare two historical handoffs

relay ui / relay dashboard

Launch the local web dashboard to visually explore decisions, constraints, history timeline, and generate custom prompts.

relay ui                     # Launches dashboard and opens browser (http://localhost:4242)
relay dashboard              # Alias for relay ui
relay ui --port 8080         # Use custom port
relay ui --no-open           # Start server without auto-opening browser

Features:

• Active Goal & Status Banner: Instant visibility on token limits and original goal.
• Action Checklist: Filterable next steps by priority (Immediate, Soon, Later).
• Decisions & Constraints Wall: Categorized, searchable card matrix.
• Failed Approaches Graveyard: Clear warnings to prevent agent hallucinations & repeated errors.
• 1-Click Prompt Builder: Customize prompt components and copy with one click.
• Live Git Diff & File Tree: Visual representation of changes made.
• Session History Timeline: Browse chronological archive of past handoffs.

relay branch

Manage branch-scoped handoffs across git branches.

relay branch list            # List all saved branch handoffs
relay branch show <branch>   # View handoff for a specific branch
relay branch apply <branch>  # Apply branch handoff as the active handoff.md

relay hook

Install git hooks to automatically stage commit messages and file diffs into handoff drafts.

relay hook install           # Install post-commit auto-drafting hook
relay hook uninstall         # Remove hook cleanly

relay vscode

Generate VS Code / Cursor IDE tasks for 1-click execution.

relay vscode                 # Configures .vscode/tasks.json with Relay shortcuts

relay repos / relay list

List and manage registered Relay repositories across your machine.

relay repos                  # List all registered repositories and their status
relay list                   # Alias for relay repos
relay repos --json           # Output machine registry as JSON
relay repos --remove <path>  # Remove a repository from the global registry

relay history

Browse past handoffs.

relay history                # List all past handoffs
relay history --limit 5      # Show last 5
relay history --show abc123  # Show a specific handoff by ID

relay install

Install bootstrap rules so AI platforms automatically read .relay/handoff.md. Supports both repository-level and machine-wide global installations.

relay install claude         # Installs to CLAUDE.md in current repo
relay install cursor         # Installs to .cursor/rules/relay.mdc
relay install antigravity    # Installs to AGENTS.md
relay install copilot        # Installs to .github/copilot-instructions.md
relay install all            # Installs to all platforms in current repo

# Global / System-Wide Installation:
relay install all --global   # Installs global rules into ~/.claude, ~/.cursor, etc.
relay install all -g --dry-run  # Preview global installation without touching files

When installed globally, every project on your computer will automatically check for and respect .relay/handoff.md without having to configure rules repository-by-repository!

relay ui / relay dashboard

Launch the local web dashboard to visually explore decisions, constraints, history timeline, and generate custom prompts.

relay ui                     # Launches dashboard and opens browser (http://localhost:4242)
relay dashboard              # Alias for relay ui
relay ui --global            # Launch global multi-repo dashboard with project switcher
relay ui --port 8080         # Use custom port
relay ui --no-open           # Start server without auto-opening browser

relay serve

Start the Relay MCP server for programmatic access from MCP-compatible platforms.

relay serve

Add to your platform's MCP config:

{
  "mcpServers": {
    "relay": {
      "command": "relay",
      "args": ["serve"]
    }
  }
}

Platform Support

| Platform | Auto-reads handoff | MCP tools | Bootstrap file | |----------|--------------------|-----------|----------------| | Claude / Claude Code | ✅ via CLAUDE.md rule | ✅ 5 tools | CLAUDE.md | | Cursor | ✅ via .cursor/rules/ | ✅ 5 tools | .cursor/rules/relay.mdc | | Antigravity | ✅ via AGENTS.md rule | ✅ 5 tools | AGENTS.md | | GitHub Copilot | ✅ via instructions file | ❌ no MCP | .github/copilot-instructions.md |

What Gets Saved

A Relay handoff captures everything the next agent needs:

# 🔄 Relay Handoff

> Generated: 8/28/2026, 2:00:00 PM | Source: claude | Status: in_progress
> ⚠️ Session ended due to token limit

## 🎯 Goal
Implement JWT refresh token rotation in the auth service

## 📁 Repository State
| Field   | Value              |
|---------|--------------------|
| Branch  | `feature/auth`     |
| HEAD    | `abc1234`          |

## 📝 Files Modified This Session
- 🟡 `src/auth/tokens.ts` — Added stub for token rotation
- 🟡 `src/auth/routes.ts` — Added POST /auth/refresh route

## 🏛️ Decisions Made
### Using Redis for refresh token storage
**Why:** O(1) revocation required. DB queries were 40ms+ under load.
**Evidence:** src/auth/benchmarks.ts

## 🚫 Non-Negotiable Constraints
- ❌ No new npm dependencies — bundle size at ceiling
- ❌ Must maintain backward compatibility with v2 API

## ⚠️ Failed Approaches — Do NOT Repeat
### ~~Stateless JWT blocklist~~
**Why it failed:** Requires Redis anyway — doubles overhead with no benefit

## ✅ Next Steps
1. **Complete rotateRefreshToken() in src/auth/tokens.ts**
   - Context: Stub exists at tokens.ts:45, needs Redis atomic swap
   - Start at: `src/auth/tokens.ts`

MCP Tools

When running relay serve, these tools are available to MCP-compatible agents:

| Tool | Description | |------|-------------| | read_handoff | Get current context (prompt / markdown / json format) | | write_handoff | Save context programmatically (agent calls this itself) | | get_git_context | Current branch, modified files, raw diff | | list_history | Past handoffs with timestamps and goals | | get_history_entry | Full content of a specific past handoff |

Resource: relay://handoff/current — the current handoff as a readable MCP resource.

Directory Structure

Relay creates a .relay/ directory in your repository:

.relay/
├── handoff.md       ← Current handoff, human-readable (commit this to git)
├── handoff.json     ← Current handoff, machine-readable (for MCP tools)
├── config.yaml      ← Local config (git-ignored by default)
└── history/         ← Archived past handoffs (git-ignored by default)
    ├── history-index.json
    ├── abc12345.md
    └── def67890.md

Tip: Commit .relay/handoff.md to git so teammates can also pick up context. History files stay local.

Configuration

Edit .relay/config.yaml to customize behaviour:

# Include raw git diff in handoff files (can be large for big changesets)
include_diff: true

# Maximum diff size in bytes before truncation (default: 50KB)
max_diff_size: 51200

# Keep history files in git (default: false — local only)
git_track_history: false

# Track the current handoff.md in git (default: true)
git_track_handoff: true

How the Handoff Protocol Works

┌─────────────────────────────────────────────────────────┐
│                    Platform A (e.g. Claude)              │
│                                                          │
│  Token limit approaching...                              │
│  Developer runs: relay save                              │
│    └─ Captures git state automatically                   │
│    └─ Prompts for decisions / constraints / next steps   │
│    └─ Writes .relay/handoff.md + handoff.json            │
└─────────────────────────────────────────────────────────┘
                          │
                          │  (switch platform)
                          ▼
┌─────────────────────────────────────────────────────────┐
│                    Platform B (e.g. Cursor)              │
│                                                          │
│  Agent reads CLAUDE.md / AGENTS.md / .cursor/rules       │
│    └─ Rule: "Read .relay/handoff.md first"               │
│    └─ Agent reads the handoff and orients itself         │
│    └─ Acknowledges goal, constraints, next steps         │
│  Work continues seamlessly                               │
└─────────────────────────────────────────────────────────┘

Two tiers, both work independently:

| Tier | Mechanism | Works with | Requires | |------|-----------|-----------|----------| | Tier 1 | .relay/handoff.md file | Any platform (any agent can read a file) | Nothing | | Tier 2 | MCP server tools | Claude, Cursor, Antigravity | relay serve running |

Development

# Clone and install
git clone https://github.com/relay-ai/relay
cd relay
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test
npm run test:watch

# Type check only (no emit)
npm run typecheck

Project Structure

src/
├── cli/
│   ├── index.ts              ← CLI entry point (Commander.js)
│   └── commands/
│       ├── init.ts           ← relay init
│       ├── save.ts           ← relay save (interactive + agent-assisted)
│       ├── load.ts           ← relay load
│       ├── history.ts        ← relay history
│       └── install.ts        ← relay install
├── format/
│   ├── schema.ts             ← Zod schema for the handoff document
│   ├── renderer.ts           ← Markdown + agent prompt renderers
│   └── template.ts           ← Interactive prompt choices + agent-save prompt
├── git/
│   └── context.ts            ← Git state capture (branch, HEAD, diff, files)
├── storage/
│   └── index.ts              ← .relay/ directory I/O, history management
├── mcp/
│   └── server.ts             ← MCP server (5 tools + 1 resource)
└── index.ts                  ← Public API exports
tests/
└── schema-renderer.test.ts   ← Unit tests (11 tests, all passing)

Testing

npm test

✓ tests/schema-renderer.test.ts  (11 tests)
  ✓ HandoffSchema — parses a valid handoff
  ✓ HandoffSchema — applies defaults for missing optional arrays
  ✓ HandoffSchema — rejects invalid status
  ✓ HandoffSchema — rejects invalid platform
  ✓ renderMarkdown — generates valid markdown with all sections
  ✓ renderMarkdown — includes token exhausted warning when flag is set
  ✓ renderMarkdown — includes relay metadata comment
  ✓ renderMarkdown — does not include empty sections
  ✓ renderAgentPrompt — generates compact agent prompt
  ✓ renderAgentPrompt — prompt is shorter than markdown output
  ✓ renderAgentPrompt — uses at most one top-level heading

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Make your changes and add tests
4. Run npm run typecheck && npm test — both must pass
5. Submit a pull request

Adding a new platform

1. Add the platform to the Platform enum in src/format/schema.ts
2. Add a bootstrap rule string and installer target in src/cli/commands/install.ts
3. Update the platform support table in this README

Roadmap

• [ ] relay save --quick — minimal prompts for fast saves
• [ ] TUI history browser (relay history with arrow key navigation)
• [ ] VSCode extension — save/load handoff from the command palette
• [ ] Team handoffs — share context via a central server
• [ ] Token budget warning integration — auto-prompt save when approaching limits
• [ ] relay diff — compare two handoffs to see how context evolved

License

MIT — free for personal and commercial use.

Built to solve the real pain of working across AI coding platforms. If it helps you, ⭐ the repo.