Relay

When Claude Code hits its rate limit, another agent picks up exactly where you left off — with full conversation context.

The Problem

It's 6:20 PM. Your submission is at 7 PM. You're deep in a Claude Code session — 45 minutes of context, decisions, half-finished code. Then:

Rate limit reached. Please wait.

Your entire session context is gone. You open Codex or Gemini and spend 20 minutes re-explaining everything. By the time you're set up, it's 6:50.

The Solution

relay handoff --to codex

Relay reads your actual Claude Code session — the full conversation, every tool call, every file edit, every error — compresses it into a handoff package, and opens Codex (or Gemini, Aider, Ollama, etc.) with complete context. The new agent knows exactly what you were doing and waits for your instructions.

What Relay Captures

This is NOT just git state. Relay reads Claude's actual .jsonl session transcript:

  ════════════════════════════════════════════════════════
  📋  Session Snapshot
  ════════════════════════════════════════════════════════

  📁  /Users/dev/myproject
  🕐  2026-04-05 14:46

  🎯 Current Task
  ──────────────────────────────────────────────────
  Fix the mobile/desktop page separation in the footer

  📝 Progress
  ──────────────────────────────────────────────────
  ✅  Database schema + REST API
  ✅  Landing page overhaul
  🔄  Footer link separation (IN PROGRESS)
  ⏳  Auth system

  🚨 Last Error
  ──────────────────────────────────────────────────
  Error: Next.js couldn't find the package from project directory

  💡 Key Decisions
  ──────────────────────────────────────────────────
  • Using Socket.io instead of raw WebSockets
  • Clean reinstall fixed the @next/swc-darwin-arm64 issue

  💬 Conversation (25 turns)
  ──────────────────────────────────────────────────
  🤖 AI   Now update the landing page footer too.
  🔧 TOOL [Edit] pages/index.tsx (replacing 488 chars)
  📤 OUT  File updated successfully.
  🤖 AI   Add /mobile to the Layout bypass list.
  🔧 TOOL [Edit] components/Layout.tsx (replacing 99 chars)
  🔧 TOOL [Bash] npx next build
  📤 OUT  ✓ Build passed — 12 pages compiled

The fallback agent sees everything: what Claude was thinking, what files it edited, what errors it hit, and where it stopped.

8 Supported Agents

  ════════════════════════════════════════════════════════
  🤖  Available Agents
  ════════════════════════════════════════════════════════

  Priority: codex → claude → aider → gemini → copilot → opencode → ollama → openai

  ✅  codex        Found at /opt/homebrew/bin/codex
  ✅  copilot      Found at /opt/homebrew/bin/copilot
  ❌  claude       Install: npm install -g @anthropic-ai/claude-code
  ❌  aider        Install: pip install aider-chat
  ❌  gemini       Set GEMINI_API_KEY env var
  ❌  opencode     Install: go install github.com/opencode-ai/opencode@latest
  ❌  ollama       Not reachable at http://localhost:11434
  ❌  openai       Set OPENAI_API_KEY env var

  🚀 2 agents ready for handoff

Agent	Type	How it launches
Codex	CLI (OpenAI)	Opens interactive TUI with context
Claude	CLI (Anthropic)	New Claude session with context
Aider	CLI (open source)	Opens with --message handoff
Gemini	API / CLI	Gemini CLI or REST API
Copilot	CLI (GitHub)	Opens with context
OpenCode	CLI (Go)	Opens with context
Ollama	Local API	REST call to local model
OpenAI	API	GPT-4o / GPT-5.4 API call

Quick Start

# Install
git clone https://github.com/Manavarya09/relay
cd relay && ./scripts/build.sh

# Symlink to PATH (avoids macOS quarantine)
ln -sf $(pwd)/core/target/release/relay ~/.cargo/bin/relay

# Generate config
relay init

# Check what agents you have
relay agents

# See your current session snapshot
relay status

# Hand off to Codex (interactive — opens TUI)
relay handoff --to codex

# Interactive agent picker
relay handoff

# With deadline urgency
relay handoff --to codex --deadline "7:00 PM"

Context Control

# Default: last 25 conversation turns + everything
relay handoff --to codex

# Light: 10 turns only
relay handoff --to codex --turns 10

# Only git state + todos (no conversation)
relay handoff --to codex --include git,todos

# Only conversation
relay handoff --to codex --include conversation

# Dry run — see what gets sent without launching
relay handoff --dry-run

How It Works

1. Reads ~/.claude/projects/<project>/<session>.jsonl — Claude's actual transcript
2. Extracts user messages, assistant responses, tool calls (Bash, Read, Write, Edit), tool results, errors
3. Reads TodoWrite state from the JSONL (your live todo list)
4. Captures git branch, diff summary, uncommitted files, recent commits
5. Compresses into a handoff prompt optimized for the target agent
6. Launches the agent interactively with inherited stdin/stdout

Config

~/.relay/config.toml:

[general]
priority = ["codex", "claude", "aider", "gemini", "copilot", "opencode", "ollama", "openai"]
max_context_tokens = 8000
auto_handoff = true

[agents.codex]
model = "gpt-5.4"

[agents.gemini]
api_key = "your-key"

[agents.openai]
api_key = "your-key"

[agents.ollama]
url = "http://localhost:11434"
model = "llama3"

Auto-Handoff (PostToolUse Hook)

Add to ~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "*", "hooks": [{ "type": "command", "command": "relay hook" }] }
    ]
  }
}

Relay detects rate limit signals in tool output and automatically hands off.

Performance

• 4.6 MB binary
• < 100ms session capture
• Zero network calls for capture
• Rust — no runtime, no GC

License

MIT

---

Built by @masyv