@masyv/relay 0.4.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"
@@ -42,8 +42,11 @@ blake3 = "1"
 # HTTP client (for Ollama, OpenAI, Gemini APIs)
 ureq = { version = "2", features = ["json"] }
 
-# Terminal
+# Terminal UI
 colored = "2"
+indicatif = "0.17"
+dialoguer = { version = "0.11", features = ["fuzzy-select"] }
+console = "0.15"
 
 [profile.release]
 opt-level = 3

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,11 @@
 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};
 use std::path::PathBuf;