@masyv/relay 0.5.0 → 1.0.0

package/README.md

@@ -1,145 +1,219 @@
 # Relay
 
-**When Claude's rate limit hits, another agent picks up exactly where you left off.**
+**When Claude Code hits its rate limit, another agent picks up exactly where you left off — with full conversation context.**
 
 [![Rust](https://img.shields.io/badge/Rust-1.70+-orange.svg)](https://www.rust-lang.org/)
 [![npm](https://img.shields.io/npm/v/@masyv/relay)](https://www.npmjs.com/package/@masyv/relay)
+[![GitHub Release](https://img.shields.io/github/v/release/Manavarya09/relay)](https://github.com/Manavarya09/relay/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
+![Relay — Claude to Codex handoff](relay-hero.png)
+
+## Features
+
+- **Full conversation capture** — Reads Claude's actual `.jsonl` transcript, not just git
+- **8 agent adapters** — Codex, Claude, Aider, Gemini, Copilot, OpenCode, Ollama, OpenAI
+- **Interactive TUI** — Spinners, progress steps, fuzzy agent picker, color-coded output
+- **`relay resume`** — When Claude comes back, see what the fallback agent did
+- **`relay history`** — Browse all past handoffs with timestamps
+- **`relay diff`** — Show exactly what changed during the handoff
+- **Clipboard mode** — `--clipboard` copies handoff for pasting into any tool
+- **Handoff templates** — `--template minimal|full|raw` for different formats
+- **Rate limit auto-detection** — PostToolUse hook triggers handoff automatically
+- **Context control** — `--turns 10 --include git,todos` to customize
+- **Zero network capture** — Pure local file parsing, < 100ms
+- **4.6 MB binary** — Rust, no runtime, no GC
+
 ## The Problem
 
-You're building a feature. It's 6:20 PM. You need to submit by 7 PM. Claude hits its rate limit.
+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:
 
-Your entire session context — what you were building, your todos, the last error you were debugging, the architectural decisions you made — all gone. You have to re-explain everything to a new tool. By the time you're set up, it's 6:45 PM.
+> **Rate limit reached. Please wait.**
 
-**Relay fixes this.** It captures your full session state and hands it to Codex, Gemini, Ollama, or GPT-4 — automatically, with complete context — so work never stops.
+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.
 
-## How It Works
+## The Solution
+
+```bash
+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:
 
 ```
-Claude Code session running...
-   | (rate limit hit)
-   v
-Relay captures session state:
-  - Current task (from conversation)
-  - Todo list + status (from TodoWrite)
-  - Git branch, diff, recent commits
-  - Last error / last tool output
-  - Key decisions made
-  - Deadline (if set)
-   |
-   v
-Relay dispatches to fallback agent:
-  -> Codex CLI (if installed)
-  -> Gemini (if API key set)
-  -> Ollama (if running locally)
-  -> GPT-4 (if API key set)
-   |
-   v
-Agent picks up EXACTLY where you left off.
+  ════════════════════════════════════════════════════════
+  📋  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
 
 ```bash
 # Install
 git clone https://github.com/Manavarya09/relay
-cd relay && ./scripts/build.sh && ./scripts/install.sh
+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 available agents
+# Check what agents you have
 relay agents
 
-# See what would be handed off
+# See your current session snapshot
 relay status
 
-# Manual handoff (now)
+# Hand off to Codex (interactive — opens TUI)
+relay handoff --to codex
+
+# Interactive agent picker
 relay handoff
 
-# Handoff to specific agent with deadline
+# With deadline urgency
 relay handoff --to codex --deadline "7:00 PM"
 
-# Dry run — just print the handoff package
-relay handoff --dry-run
-```
+# Copy to clipboard instead
+relay handoff --clipboard
 
-## What Relay Captures
+# Minimal handoff (just task + error + git)
+relay handoff --template minimal --to codex
 
+# When Claude comes back — see what happened
+relay resume
+
+# List all past handoffs
+relay history
+
+# What changed since handoff?
+relay diff
 ```
-═══ Relay Session Snapshot ═══
 
-Project: /Users/dev/myproject
-Captured: 2026-04-05 13:32:02
+## Context Control
 
-── Current Task ──
-  Building WebSocket handler in src/server/ws.rs
+```bash
+# Default: last 25 conversation turns + everything
+relay handoff --to codex
 
-── Todos ──
-  ✅ [completed] Database schema + REST API
-  🔄 [in_progress] WebSocket handler (60% done)
-  ⏳ [pending] Frontend charts
-  ⏳ [pending] Auth
+# Light: 10 turns only
+relay handoff --to codex --turns 10
 
-── Last Error ──
-  error[E0499]: cannot borrow `state` as mutable...
+# Only git state + todos (no conversation)
+relay handoff --to codex --include git,todos
 
-── Decisions ──
-  • Using Socket.io instead of raw WebSockets
-  • Redis pub/sub for cross-server events
+# Only conversation
+relay handoff --to codex --include conversation
 
-── Git ──
-  Branch: feature/websocket
-  3 uncommitted changes
-  Recent: abc1234 Add WebSocket route skeleton
+# Dry run — see what gets sent without launching
+relay handoff --dry-run
 ```
 
-## Agent Priority
+## 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
 
-Configure in `~/.relay/config.toml`:
+`~/.relay/config.toml`:
 
 ```toml
 [general]
-priority = ["codex", "gemini", "ollama", "openai"]
-auto_handoff = true
+priority = ["codex", "claude", "aider", "gemini", "copilot", "opencode", "ollama", "openai"]
 max_context_tokens = 8000
+auto_handoff = true
 
 [agents.codex]
-model = "o4-mini"
+model = "gpt-5.4"
 
 [agents.gemini]
 api_key = "your-key"
-model = "gemini-2.5-pro"
-
-[agents.ollama]
-url = "http://localhost:11434"
-model = "llama3"
 
 [agents.openai]
 api_key = "your-key"
-model = "gpt-4o"
-```
 
-Relay tries agents in priority order and uses the first available one.
-
-## CLI
-
-```
-COMMANDS:
-  handoff   Hand off to fallback agent (--to, --deadline, --dry-run)
-  status    Show current session snapshot
-  agents    List agents and availability
-  init      Generate default config
-  hook      PostToolUse hook (auto-detect rate limits)
-
-OPTIONS:
-  --json       Output as JSON
-  --project    Project directory (default: cwd)
-  -v           Verbose logging
+[agents.ollama]
+url = "http://localhost:11434"
+model = "llama3"
 ```
 
-## Auto-Handoff via Hook
+## Auto-Handoff (PostToolUse Hook)
 
 Add to `~/.claude/settings.json`:
 
@@ -147,23 +221,25 @@ Add to `~/.claude/settings.json`:
 {
   "hooks": {
     "PostToolUse": [
-      {
-        "matcher": "*",
-        "hooks": [{ "type": "command", "command": "relay hook" }]
-      }
+      { "matcher": "*", "hooks": [{ "type": "command", "command": "relay hook" }] }
     ]
   }
 }
 ```
 
-Relay will detect rate limit signals in tool output and automatically hand off.
+Relay detects rate limit signals in tool output and automatically hands off.
 
 ## Performance
 
-- **4.6 MB** binary (release, stripped)
-- **< 100ms** to capture full session snapshot
-- **Zero network calls** for capture (git + file reads only)
+- **4.6 MB** binary
+- **< 100ms** session capture
+- **Zero network calls** for capture
+- **Rust** — no runtime, no GC
 
 ## License
 
 MIT
+
+---
+
+Built by [@masyv](https://github.com/Manavarya09)

package/core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "relay"
-version = "0.1.0"
+version = "1.0.0"
 edition = "2021"
 description = "Relay — When Claude's rate limit hits, another agent picks up exactly where you left off."
 license = "MIT"

package/core/src/diff.rs

@@ -0,0 +1,118 @@
+//! `relay diff` — Show what changed since the last handoff.
+
+use anyhow::Result;
+use std::path::Path;
+
+#[derive(Debug, serde::Serialize)]
+pub struct DiffReport {
+    pub handoff_time: String,
+    pub changed_files: Vec<String>,
+    pub new_commits: Vec<String>,
+    pub diff_stat: String,
+    pub files_added: usize,
+    pub files_modified: usize,
+    pub files_deleted: usize,
+}
+
+/// Show what changed since the last handoff.
+pub fn diff_since_handoff(project_dir: &Path) -> Result<DiffReport> {
+    let relay_dir = project_dir.join(".relay");
+    if !relay_dir.exists() {
+        anyhow::bail!("No .relay/ directory found. Run 'relay handoff' first.");
+    }
+
+    // Find latest handoff timestamp
+    let mut latest_time = String::new();
+    let mut latest_modified = std::time::SystemTime::UNIX_EPOCH;
+
+    for entry in std::fs::read_dir(&relay_dir)? {
+        let entry = entry?;
+        let name = entry.file_name().to_string_lossy().to_string();
+        if name.starts_with("handoff_") && name.ends_with(".md") {
+            if let Ok(meta) = entry.metadata() {
+                if let Ok(modified) = meta.modified() {
+                    if modified > latest_modified {
+                        latest_modified = modified;
+                        latest_time = parse_timestamp(&name);
+                    }
+                }
+            }
+        }
+    }
+
+    if latest_time.is_empty() {
+        anyhow::bail!("No handoff files found.");
+    }
+
+    // Git status
+    let status_output = run_git(project_dir, &["status", "--short"]);
+    let changed_files: Vec<String> = status_output
+        .lines()
+        .filter(|l| !l.is_empty())
+        .map(String::from)
+        .collect();
+
+    let mut files_added = 0;
+    let mut files_modified = 0;
+    let mut files_deleted = 0;
+    for f in &changed_files {
+        let prefix = f.trim().chars().next().unwrap_or(' ');
+        match prefix {
+            'A' | '?' => files_added += 1,
+            'M' => files_modified += 1,
+            'D' => files_deleted += 1,
+            _ => files_modified += 1,
+        }
+    }
+
+    // Commits since handoff
+    let new_commits: Vec<String> = run_git(
+        project_dir,
+        &["log", "--oneline", "-10", "--since", &latest_time],
+    )
+    .lines()
+    .filter(|l| !l.is_empty())
+    .map(String::from)
+    .collect();
+
+    // Diff stat
+    let diff_stat = run_git(project_dir, &["diff", "--stat"]);
+
+    Ok(DiffReport {
+        handoff_time: latest_time,
+        changed_files,
+        new_commits,
+        diff_stat: diff_stat.trim().to_string(),
+        files_added,
+        files_modified,
+        files_deleted,
+    })
+}
+
+fn run_git(dir: &Path, args: &[&str]) -> String {
+    std::process::Command::new("git")
+        .current_dir(dir)
+        .args(args)
+        .output()
+        .ok()
+        .filter(|o| o.status.success())
+        .map(|o| String::from_utf8_lossy(&o.stdout).to_string())
+        .unwrap_or_default()
+}
+
+fn parse_timestamp(filename: &str) -> String {
+    let ts = filename
+        .strip_prefix("handoff_")
+        .unwrap_or("")
+        .strip_suffix(".md")
+        .unwrap_or("");
+    if ts.len() >= 15 {
+        format!(
+            "{}-{}-{} {}:{}:{}",
+            &ts[0..4], &ts[4..6], &ts[6..8],
+            &ts[9..11], &ts[11..13], &ts[13..15]
+        )
+    } else {
+        ts.to_string()
+    }
+}

package/core/src/handoff/mod.rs

@@ -1,6 +1,8 @@
 //! Handoff package builder — compresses session state into a prompt
 //! that any agent can pick up and continue from.
 
+pub mod templates;
+
 use crate::SessionSnapshot;
 use anyhow::Result;
 

package/core/src/handoff/templates.rs

@@ -0,0 +1,74 @@
+//! Handoff templates — control what context is included.
+
+use crate::SessionSnapshot;
+
+/// Available handoff templates.
+pub enum Template {
+    Full,     // Everything — conversation, git, todos, errors, decisions
+    Minimal,  // Just task + error + git status
+    Raw,      // Only the conversation turns, no formatting
+}
+
+impl Template {
+    pub fn from_str(s: &str) -> Self {
+        match s.to_lowercase().as_str() {
+            "minimal" | "min" => Self::Minimal,
+            "raw" | "conversation" => Self::Raw,
+            _ => Self::Full,
+        }
+    }
+}
+
+/// Build handoff using the minimal template — task + error + git only.
+pub fn build_minimal(snapshot: &SessionSnapshot, target: &str) -> String {
+    let mut out = format!(
+        "══ RELAY HANDOFF (minimal) ═════════════════\n\
+        Agent: {target} | Project: {}\n\
+        ═══════════════════════════════════════════\n\n",
+        snapshot.project_dir
+    );
+
+    out.push_str(&format!("Task: {}\n\n", snapshot.current_task));
+
+    if let Some(ref err) = snapshot.last_error {
+        out.push_str(&format!("Error: {}\n\n", truncate(err, 300)));
+    }
+
+    if let Some(ref git) = snapshot.git_state {
+        out.push_str(&format!("Branch: {} | {}\n", git.branch, git.status_summary));
+        if !git.recent_commits.is_empty() {
+            out.push_str(&format!("Last commit: {}\n", git.recent_commits[0]));
+        }
+    }
+
+    out.push_str("\nContext restored. What would you like me to do?\n");
+    out
+}
+
+/// Build handoff using raw template — just conversation turns.
+pub fn build_raw(snapshot: &SessionSnapshot) -> String {
+    let mut out = String::new();
+    for turn in &snapshot.conversation {
+        let prefix = match turn.role.as_str() {
+            "user"           => "USER",
+            "assistant"      => "ASSISTANT",
+            "assistant_tool" => "TOOL_CALL",
+            "tool_result"    => "TOOL_OUTPUT",
+            _                => &turn.role,
+        };
+        out.push_str(&format!("[{prefix}] {}\n\n", turn.content));
+    }
+    if out.is_empty() {
+        out.push_str("(no conversation captured)\n");
+    }
+    out
+}
+
+fn truncate(s: &str, max: usize) -> String {
+    if s.len() <= max {
+        return s.to_string();
+    }
+    let mut end = max;
+    while end > 0 && !s.is_char_boundary(end) { end -= 1; }
+    format!("{}...", &s[..end])
+}

package/core/src/history.rs

@@ -0,0 +1,107 @@
+//! `relay history` — List all past handoffs with metadata.
+
+use anyhow::Result;
+use std::path::Path;
+
+#[derive(Debug, serde::Serialize)]
+pub struct HandoffEntry {
+    pub filename: String,
+    pub timestamp: String,
+    pub agent: String,
+    pub task: String,
+}
+
+/// List all handoff files in .relay/ directory.
+pub fn list_handoffs(project_dir: &Path, limit: usize) -> Result<Vec<HandoffEntry>> {
+    let relay_dir = project_dir.join(".relay");
+    if !relay_dir.exists() {
+        return Ok(Vec::new());
+    }
+
+    let mut entries: Vec<(String, std::time::SystemTime)> = Vec::new();
+    for entry in std::fs::read_dir(&relay_dir)? {
+        let entry = entry?;
+        let name = entry.file_name().to_string_lossy().to_string();
+        if name.starts_with("handoff_") && name.ends_with(".md") {
+            if let Ok(meta) = entry.metadata() {
+                if let Ok(modified) = meta.modified() {
+                    entries.push((entry.path().to_string_lossy().to_string(), modified));
+                }
+            }
+        }
+    }
+
+    // Sort newest first
+    entries.sort_by(|a, b| b.1.cmp(&a.1));
+    entries.truncate(limit);
+
+    let mut result = Vec::new();
+    for (path, _) in entries {
+        let content = std::fs::read_to_string(&path).unwrap_or_default();
+        let filename = Path::new(&path)
+            .file_name()
+            .unwrap_or_default()
+            .to_string_lossy()
+            .to_string();
+
+        let timestamp = parse_timestamp(&filename);
+        let agent = extract_field(&content, "Target agent");
+        let task = extract_field(&content, "## CURRENT TASK")
+            .unwrap_or_else(|| extract_first_line_after(&content, "## CURRENT TASK"));
+
+        result.push(HandoffEntry {
+            filename,
+            timestamp,
+            agent: agent.unwrap_or_else(|| "unknown".into()),
+            task: if task.len() > 60 {
+                format!("{}...", &task[..57])
+            } else {
+                task
+            },
+        });
+    }
+
+    Ok(result)
+}
+
+fn parse_timestamp(filename: &str) -> String {
+    let ts = filename
+        .strip_prefix("handoff_")
+        .unwrap_or("")
+        .strip_suffix(".md")
+        .unwrap_or("");
+    if ts.len() >= 15 {
+        format!(
+            "{}-{}-{} {}:{}:{}",
+            &ts[0..4], &ts[4..6], &ts[6..8],
+            &ts[9..11], &ts[11..13], &ts[13..15]
+        )
+    } else {
+        ts.to_string()
+    }
+}
+
+fn extract_field(content: &str, field: &str) -> Option<String> {
+    for line in content.lines() {
+        if line.contains(field) && line.contains(':') {
+            let val = line.split(':').skip(1).collect::<Vec<_>>().join(":").trim().to_string();
+            if !val.is_empty() {
+                return Some(val);
+            }
+        }
+    }
+    None
+}
+
+fn extract_first_line_after(content: &str, header: &str) -> String {
+    if let Some(pos) = content.find(header) {
+        let after = &content[pos + header.len()..];
+        for line in after.lines() {
+            let trimmed = line.trim();
+            if !trimmed.is_empty() && !trimmed.starts_with('#') && !trimmed.starts_with("──") {
+                return trimmed.to_string();
+            }
+        }
+    }
+    "unknown".into()
+}

package/core/src/lib.rs

@@ -1,7 +1,10 @@
 pub mod agents;
 pub mod capture;
 pub mod detect;
+pub mod diff;
 pub mod handoff;
+pub mod history;
+pub mod resume;
 pub mod tui;
 
 use serde::{Deserialize, Serialize};

package/core/src/main.rs

@@ -50,6 +50,14 @@ enum Commands {
         /// What to include: all, conversation, git, todos (comma-separated)
         #[arg(long, default_value = "all")]
         include: String,
+
+        /// Copy handoff to clipboard instead of launching agent
+        #[arg(long)]
+        clipboard: bool,
+
+        /// Handoff template: full (default), minimal, raw
+        #[arg(long, default_value = "full")]
+        template: String,
     },
 
     /// Show current session snapshot
@@ -58,6 +66,19 @@ enum Commands {
     /// List configured agents and availability
     Agents,
 
+    /// Resume after rate limit resets — show what happened during handoff
+    Resume,
+
+    /// List past handoffs
+    History {
+        /// Number of entries to show
+        #[arg(long, default_value = "10")]
+        limit: usize,
+    },
+
+    /// Show what changed since the last handoff
+    Diff,
+
     /// Generate default config at ~/.relay/config.toml
     Init,
 
@@ -92,7 +113,7 @@ fn main() -> Result<()> {
         // ═══════════════════════════════════════════════════════════════
         // HANDOFF
         // ═══════════════════════════════════════════════════════════════
-        Commands::Handoff { to, deadline, dry_run, turns, include } => {
+        Commands::Handoff { to, deadline, dry_run, turns, include, clipboard, template } => {
             if !cli.json {
                 tui::print_banner();
             }
@@ -142,9 +163,18 @@ fn main() -> Result<()> {
                 "auto".into()
             };
 
-            let handoff_text = handoff::build_handoff(
-                &snapshot, &target_name, config.general.max_context_tokens,
-            )?;
+            // Build handoff using selected template
+            let handoff_text = match handoff::templates::Template::from_str(&template) {
+                handoff::templates::Template::Minimal => {
+                    handoff::templates::build_minimal(&snapshot, &target_name)
+                }
+                handoff::templates::Template::Raw => {
+                    handoff::templates::build_raw(&snapshot)
+                }
+                handoff::templates::Template::Full => {
+                    handoff::build_handoff(&snapshot, &target_name, config.general.max_context_tokens)?
+                }
+            };
             let handoff_path = handoff::save_handoff(&handoff_text, &project_dir)?;
 
             if let Some(sp) = sp { sp.finish_with_message("Handoff built"); }
@@ -159,6 +189,29 @@ fn main() -> Result<()> {
                 }))?);
                 return Ok(());
             }
+            // Clipboard mode
+            if clipboard {
+                #[cfg(target_os = "macos")]
+                {
+                    use std::process::{Command, Stdio};
+                    let mut child = Command::new("pbcopy")
+                        .stdin(Stdio::piped())
+                        .spawn()?;
+                    if let Some(mut stdin) = child.stdin.take() {
+                        use std::io::Write;
+                        stdin.write_all(handoff_text.as_bytes())?;
+                    }
+                    child.wait()?;
+                    eprintln!("  📋 Handoff copied to clipboard!");
+                    eprintln!("  📄 Also saved: {}", handoff_path.display());
+                }
+                #[cfg(not(target_os = "macos"))]
+                {
+                    eprintln!("  Clipboard not supported on this platform.");
+                    eprintln!("  📄 Saved to: {}", handoff_path.display());
+                }
+                return Ok(());
+            }
             if dry_run {
                 println!("{handoff_text}");
                 eprintln!();
@@ -218,6 +271,108 @@ fn main() -> Result<()> {
             }
         }
 
+        // ═══════════════════════════════════════════════════════════════
+        // RESUME
+        // ═══════════════════════════════════════════════════════════════
+        Commands::Resume => {
+            let report = relay::resume::build_resume(&project_dir)?;
+
+            if cli.json {
+                println!("{}", serde_json::to_string_pretty(&report)?);
+            } else {
+                tui::print_section("🔄", "Resume — What Happened During Handoff");
+                eprintln!("  Handoff at: {}", report.handoff_time);
+                eprintln!("  Task: {}", report.original_task);
+                eprintln!();
+
+                if !report.new_commits.is_empty() {
+                    tui::print_section("📝", &format!("New Commits ({})", report.new_commits.len()));
+                    for c in &report.new_commits {
+                        eprintln!("  {c}");
+                    }
+                }
+
+                if !report.changes_since.is_empty() {
+                    tui::print_section("📄", &format!("Changed Files ({})", report.changes_since.len()));
+                    for f in &report.changes_since {
+                        eprintln!("  {f}");
+                    }
+                }
+
+                if !report.diff_stat.is_empty() {
+                    tui::print_section("📊", "Diff Summary");
+                    for line in report.diff_stat.lines() {
+                        eprintln!("  {line}");
+                    }
+                }
+
+                eprintln!();
+                eprintln!("  📋 Resume prompt ready. Use --json to get the full prompt.");
+            }
+        }
+
+        // ═══════════════════════════════════════════════════════════════
+        // HISTORY
+        // ═══════════════════════════════════════════════════════════════
+        Commands::History { limit } => {
+            let entries = relay::history::list_handoffs(&project_dir, limit)?;
+
+            if cli.json {
+                println!("{}", serde_json::to_string_pretty(&entries)?);
+                return Ok(());
+            }
+
+            if entries.is_empty() {
+                eprintln!("  No handoffs recorded yet.");
+                return Ok(());
+            }
+
+            tui::print_section("📜", &format!("Handoff History ({} entries)", entries.len()));
+            eprintln!();
+            for e in &entries {
+                eprintln!(
+                    "  {}  → {:<10}  {}",
+                    e.timestamp, e.agent, e.task
+                );
+            }
+            eprintln!();
+        }
+
+        // ═══════════════════════════════════════════════════════════════
+        // DIFF
+        // ═══════════════════════════════════════════════════════════════
+        Commands::Diff => {
+            let report = relay::diff::diff_since_handoff(&project_dir)?;
+
+            if cli.json {
+                println!("{}", serde_json::to_string_pretty(&report)?);
+                return Ok(());
+            }
+
+            tui::print_section("📊", "Changes Since Last Handoff");
+            eprintln!("  Handoff at: {}", report.handoff_time);
+            eprintln!(
+                "  {} added, {} modified, {} deleted",
+                report.files_added, report.files_modified, report.files_deleted
+            );
+
+            if !report.new_commits.is_empty() {
+                eprintln!();
+                eprintln!("  Commits:");
+                for c in &report.new_commits {
+                    eprintln!("    {c}");
+                }
+            }
+
+            if !report.diff_stat.is_empty() {
+                eprintln!();
+                for line in report.diff_stat.lines() {
+                    eprintln!("  {line}");
+                }
+            }
+            eprintln!();
+        }
+
         // ═══════════════════════════════════════════════════════════════
         // INIT
         // ═══════════════════════════════════════════════════════════════

package/core/src/resume.rs

@@ -0,0 +1,202 @@
+//! `relay resume` — When Claude comes back, show what happened during the handoff.
+//! Reads the latest handoff file + git diff since handoff time → generates a
+//! "welcome back" prompt so Claude (or any agent) can pick up with full awareness
+//! of what the fallback agent did.
+
+use anyhow::{Context, Result};
+use std::path::Path;
+
+#[derive(Debug, serde::Serialize)]
+pub struct ResumeReport {
+    pub handoff_file: String,
+    pub handoff_time: String,
+    pub original_task: String,
+    pub changes_since: Vec<String>,
+    pub new_commits: Vec<String>,
+    pub diff_stat: String,
+    pub resume_prompt: String,
+}
+
+/// Build a resume report from the latest handoff.
+pub fn build_resume(project_dir: &Path) -> Result<ResumeReport> {
+    let relay_dir = project_dir.join(".relay");
+    if !relay_dir.exists() {
+        anyhow::bail!("No .relay/ directory found. Run 'relay handoff' first.");
+    }
+
+    // Find latest handoff file
+    let handoff_file = find_latest_handoff(&relay_dir)?;
+    let handoff_content = std::fs::read_to_string(&handoff_file)
+        .context("Failed to read handoff file")?;
+
+    // Extract timestamp from filename: handoff_20260405_141328.md
+    let filename = handoff_file
+        .file_name()
+        .unwrap_or_default()
+        .to_string_lossy();
+    let handoff_time = parse_handoff_timestamp(&filename);
+
+    // Extract original task from handoff content
+    let original_task = extract_section(&handoff_content, "## CURRENT TASK")
+        .unwrap_or_else(|| "Unknown".into());
+
+    // Git changes since handoff
+    let changes_since = git_changed_files(project_dir, &handoff_time);
+    let new_commits = git_commits_since(project_dir, &handoff_time);
+    let diff_stat = git_diff_stat(project_dir, &handoff_time);
+
+    // Build resume prompt
+    let resume_prompt = build_resume_prompt(
+        &original_task,
+        &changes_since,
+        &new_commits,
+        &diff_stat,
+        &handoff_time,
+    );
+
+    Ok(ResumeReport {
+        handoff_file: handoff_file.to_string_lossy().to_string(),
+        handoff_time,
+        original_task,
+        changes_since,
+        new_commits,
+        diff_stat,
+        resume_prompt,
+    })
+}
+
+fn find_latest_handoff(relay_dir: &Path) -> Result<std::path::PathBuf> {
+    let mut latest: Option<(std::path::PathBuf, std::time::SystemTime)> = None;
+    for entry in std::fs::read_dir(relay_dir)? {
+        let entry = entry?;
+        let path = entry.path();
+        let name = path.file_name().unwrap_or_default().to_string_lossy();
+        if name.starts_with("handoff_") && name.ends_with(".md") {
+            if let Ok(meta) = path.metadata() {
+                if let Ok(modified) = meta.modified() {
+                    if latest.as_ref().map_or(true, |(_, t)| modified > *t) {
+                        latest = Some((path, modified));
+                    }
+                }
+            }
+        }
+    }
+    latest
+        .map(|(p, _)| p)
+        .ok_or_else(|| anyhow::anyhow!("No handoff files found in .relay/"))
+}
+
+fn parse_handoff_timestamp(filename: &str) -> String {
+    // handoff_20260405_141328.md → 2026-04-05 14:13:28
+    let ts = filename
+        .strip_prefix("handoff_")
+        .unwrap_or("")
+        .strip_suffix(".md")
+        .unwrap_or("");
+    if ts.len() >= 15 {
+        format!(
+            "{}-{}-{} {}:{}:{}",
+            &ts[0..4], &ts[4..6], &ts[6..8],
+            &ts[9..11], &ts[11..13], &ts[13..15]
+        )
+    } else {
+        "unknown".into()
+    }
+}
+
+fn extract_section(content: &str, header: &str) -> Option<String> {
+    let start = content.find(header)?;
+    let after = &content[start + header.len()..];
+    let end = after.find("\n## ").unwrap_or(after.len());
+    let section = after[..end].trim();
+    if section.is_empty() { None } else { Some(section.to_string()) }
+}
+
+fn git_changed_files(dir: &Path, _since: &str) -> Vec<String> {
+    let output = std::process::Command::new("git")
+        .current_dir(dir)
+        .args(["diff", "--name-only", "HEAD"])
+        .output()
+        .ok();
+    output
+        .filter(|o| o.status.success())
+        .map(|o| {
+            String::from_utf8_lossy(&o.stdout)
+                .lines()
+                .filter(|l| !l.is_empty())
+                .map(String::from)
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn git_commits_since(dir: &Path, since: &str) -> Vec<String> {
+    let output = std::process::Command::new("git")
+        .current_dir(dir)
+        .args(["log", "--oneline", "-10", "--since", since])
+        .output()
+        .ok();
+    output
+        .filter(|o| o.status.success())
+        .map(|o| {
+            String::from_utf8_lossy(&o.stdout)
+                .lines()
+                .filter(|l| !l.is_empty())
+                .map(String::from)
+                .collect()
+        })
+        .unwrap_or_default()
+}
+
+fn git_diff_stat(dir: &Path, _since: &str) -> String {
+    let output = std::process::Command::new("git")
+        .current_dir(dir)
+        .args(["diff", "--stat", "HEAD"])
+        .output()
+        .ok();
+    output
+        .filter(|o| o.status.success())
+        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+        .unwrap_or_default()
+}
+
+fn build_resume_prompt(
+    task: &str,
+    changed: &[String],
+    commits: &[String],
+    diff_stat: &str,
+    handoff_time: &str,
+) -> String {
+    let mut prompt = format!(
+        "══ RELAY RESUME ══════════════════════════════\n\
+        You are resuming a session that was handed off at {handoff_time}.\n\
+        A fallback agent continued the work. Here's what happened:\n\
+        ══════════════════════════════════════════════\n\n\
+        ## ORIGINAL TASK\n\n{task}\n"
+    );
+
+    if !commits.is_empty() {
+        prompt.push_str("\n## COMMITS MADE DURING HANDOFF\n\n");
+        for c in commits {
+            prompt.push_str(&format!("  {c}\n"));
+        }
+    }
+
+    if !changed.is_empty() {
+        prompt.push_str(&format!("\n## FILES CHANGED ({})\n\n", changed.len()));
+        for f in changed.iter().take(20) {
+            prompt.push_str(&format!("  {f}\n"));
+        }
+    }
+
+    if !diff_stat.is_empty() {
+        prompt.push_str(&format!("\n## DIFF SUMMARY\n\n{diff_stat}\n"));
+    }
+
+    prompt.push_str("\n## INSTRUCTIONS\n\n\
+        Review what the fallback agent did above.\n\
+        Continue from the current state. Check if the original task is complete.\n\
+        If not, finish it.\n");
+
+    prompt
+}

package/core/src/tui.rs

@@ -208,7 +208,7 @@ pub fn print_snapshot(snapshot: &crate::SessionSnapshot) {
         );
         let start = snapshot.conversation.len().saturating_sub(10);
         for turn in &snapshot.conversation[start..] {
-            let (prefix, color) = match turn.role.as_str() {
+            let (prefix, _color) = match turn.role.as_str() {
                 "user" => ("👤 YOU ", turn.content.normal().to_string()),
                 "assistant" => ("🤖 AI  ", turn.content.cyan().to_string()),
                 "assistant_tool" => ("🔧 TOOL", turn.content.dimmed().to_string()),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masyv/relay",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "description": "Relay — When Claude's rate limit hits, another agent picks up exactly where you left off. Captures session state and hands off to Codex, Gemini, Ollama, or GPT-4.",
   "scripts": {
     "build": "./scripts/build.sh",