@masyv/relay 0.1.0

package/core/src/handoff/mod.rs

@@ -0,0 +1,156 @@
+//! Handoff package builder — compresses session state into a prompt
+//! that any agent can pick up and continue from.
+
+use crate::SessionSnapshot;
+use anyhow::Result;
+
+/// Build a handoff prompt from a session snapshot.
+/// This is the formatted text that gets sent to the fallback agent.
+pub fn build_handoff(
+    snapshot: &SessionSnapshot,
+    target_agent: &str,
+    max_tokens: usize,
+) -> Result<String> {
+    let mut sections: Vec<String> = Vec::new();
+
+    // ── Header ─────────────────────────────────────────────────
+    let urgency = if let Some(ref deadline) = snapshot.deadline {
+        format!("\n  DEADLINE     : {deadline}")
+    } else {
+        String::new()
+    };
+
+    sections.push(format!(
+        "══ RELAY HANDOFF ══════════════════════════════
+  Original agent : Claude Code
+  Handed off at  : {}
+  Target agent   : {}
+  Project        : {}{}
+══════════════════════════════════════════════",
+        snapshot.timestamp,
+        target_agent,
+        snapshot.project_dir,
+        urgency
+    ));
+
+    // ── Current Task ───────────────────────────────────────────
+    sections.push(format!(
+        "## CURRENT TASK\n\n{}",
+        snapshot.current_task
+    ));
+
+    // ── Todos ──────────────────────────────────────────────────
+    if !snapshot.todos.is_empty() {
+        let mut todo_text = String::from("## PROGRESS\n\n");
+        for t in &snapshot.todos {
+            let icon = match t.status.as_str() {
+                "completed"   => "done",
+                "in_progress" => "IN PROGRESS",
+                _             => "pending",
+            };
+            todo_text.push_str(&format!("  [{}] {}\n", icon, t.content));
+        }
+        sections.push(todo_text);
+    }
+
+    // ── Last Error ─────────────────────────────────────────────
+    if let Some(ref err) = snapshot.last_error {
+        sections.push(format!(
+            "## LAST ERROR\n\n```\n{}\n```",
+            truncate_smart(err, 500)
+        ));
+    }
+
+    // ── Decisions ──────────────────────────────────────────────
+    if !snapshot.decisions.is_empty() {
+        let mut dec = String::from("## KEY DECISIONS\n\n");
+        for d in &snapshot.decisions {
+            dec.push_str(&format!("  - {d}\n"));
+        }
+        sections.push(dec);
+    }
+
+    // ── Git State ──────────────────────────────────────────────
+    if let Some(ref git) = snapshot.git_state {
+        let mut git_text = format!(
+            "## GIT STATE\n\n  Branch: {}\n  Status: {}",
+            git.branch, git.status_summary
+        );
+        if !git.recent_commits.is_empty() {
+            git_text.push_str("\n\n  Recent commits:\n");
+            for c in git.recent_commits.iter().take(5) {
+                git_text.push_str(&format!("    {c}\n"));
+            }
+        }
+        if !git.diff_summary.is_empty() {
+            git_text.push_str(&format!(
+                "\n  Diff summary:\n    {}",
+                truncate_smart(&git.diff_summary, 500)
+            ));
+        }
+        sections.push(git_text);
+    }
+
+    // ── Recent Files ───────────────────────────────────────────
+    if !snapshot.recent_files.is_empty() {
+        let mut files = String::from("## RECENTLY CHANGED FILES\n\n");
+        for f in snapshot.recent_files.iter().take(20) {
+            files.push_str(&format!("  {f}\n"));
+        }
+        sections.push(files);
+    }
+
+    // ── Instructions for agent ─────────────────────────────────
+    let instructions = format!(
+        "## INSTRUCTIONS\n\n\
+        You are continuing work that was started in a Claude Code session.\n\
+        The session was interrupted by a rate limit.\n\
+        Pick up EXACTLY where it left off. Do NOT re-explain context.\n\
+        The user is waiting — be efficient and direct.\n\
+        \n\
+        Working directory: {}\n\
+        {}",
+        snapshot.project_dir,
+        if snapshot.deadline.is_some() {
+            "THERE IS A DEADLINE. Prioritise completing the current task."
+        } else { "" }
+    );
+    sections.push(instructions);
+
+    let mut full = sections.join("\n\n");
+
+    // Truncate if too long (rough token estimate: chars / 3.5)
+    let estimated_tokens = full.len() as f64 / 3.5;
+    if estimated_tokens > max_tokens as f64 {
+        let max_chars = (max_tokens as f64 * 3.5) as usize;
+        full.truncate(max_chars);
+        full.push_str("\n\n[...truncated to fit context limit]");
+    }
+
+    Ok(full)
+}
+
+/// Save handoff to a file for reference/debugging.
+pub fn save_handoff(handoff: &str, project_dir: &std::path::Path) -> Result<std::path::PathBuf> {
+    let relay_dir = project_dir.join(".relay");
+    std::fs::create_dir_all(&relay_dir)?;
+
+    let ts = chrono::Local::now().format("%Y%m%d_%H%M%S");
+    let path = relay_dir.join(format!("handoff_{ts}.md"));
+    std::fs::write(&path, handoff)?;
+
+    Ok(path)
+}
+
+fn truncate_smart(s: &str, max: usize) -> String {
+    if s.len() <= max {
+        return s.to_string();
+    }
+    // Try to cut at a line boundary
+    let cut = &s[..max];
+    if let Some(last_nl) = cut.rfind('\n') {
+        format!("{}\n[...truncated]", &s[..last_nl])
+    } else {
+        format!("{}...", &s[..max])
+    }
+}

package/core/src/lib.rs

@@ -0,0 +1,198 @@
+pub mod agents;
+pub mod capture;
+pub mod detect;
+pub mod handoff;
+
+use serde::{Deserialize, Serialize};
+use std::path::PathBuf;
+
+// ─── Config ──────────────────────────────────────────────────────────────────
+
+/// Relay configuration — loaded from ~/.relay/config.toml
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Config {
+    #[serde(default)]
+    pub general: GeneralConfig,
+    #[serde(default)]
+    pub agents: AgentsConfig,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GeneralConfig {
+    /// Priority order for fallback agents
+    #[serde(default = "default_priority")]
+    pub priority: Vec<String>,
+    /// Max tokens for handoff context
+    #[serde(default = "default_max_context")]
+    pub max_context_tokens: usize,
+    /// Auto-handoff on rate limit detection
+    #[serde(default = "default_true")]
+    pub auto_handoff: bool,
+}
+
+impl Default for GeneralConfig {
+    fn default() -> Self {
+        Self {
+            priority: default_priority(),
+            max_context_tokens: 8000,
+            auto_handoff: true,
+        }
+    }
+}
+
+fn default_priority() -> Vec<String> {
+    vec![
+        "codex".into(),
+        "gemini".into(),
+        "ollama".into(),
+        "openai".into(),
+    ]
+}
+fn default_max_context() -> usize { 8000 }
+fn default_true() -> bool { true }
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct AgentsConfig {
+    #[serde(default)]
+    pub codex: CodexConfig,
+    #[serde(default)]
+    pub gemini: GeminiConfig,
+    #[serde(default)]
+    pub ollama: OllamaConfig,
+    #[serde(default)]
+    pub openai: OpenAIConfig,
+}
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct CodexConfig {
+    /// Path to codex CLI binary (default: search PATH)
+    pub binary: Option<String>,
+    /// Model to use
+    #[serde(default = "codex_default_model")]
+    pub model: String,
+}
+fn codex_default_model() -> String { "o4-mini".into() }
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct GeminiConfig {
+    pub api_key: Option<String>,
+    #[serde(default = "gemini_default_model")]
+    pub model: String,
+}
+fn gemini_default_model() -> String { "gemini-2.5-pro".into() }
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct OllamaConfig {
+    #[serde(default = "ollama_default_url")]
+    pub url: String,
+    #[serde(default = "ollama_default_model")]
+    pub model: String,
+}
+fn ollama_default_url() -> String { "http://localhost:11434".into() }
+fn ollama_default_model() -> String { "llama3".into() }
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct OpenAIConfig {
+    pub api_key: Option<String>,
+    #[serde(default = "openai_default_model")]
+    pub model: String,
+}
+fn openai_default_model() -> String { "gpt-4o".into() }
+
+impl Config {
+    pub fn load() -> anyhow::Result<Self> {
+        let path = config_path();
+        if path.exists() {
+            let text = std::fs::read_to_string(&path)?;
+            Ok(toml::from_str(&text)?)
+        } else {
+            Ok(Self {
+                general: GeneralConfig::default(),
+                agents: AgentsConfig::default(),
+            })
+        }
+    }
+
+    pub fn save_default(path: &std::path::Path) -> anyhow::Result<()> {
+        let cfg = Self {
+            general: GeneralConfig::default(),
+            agents: AgentsConfig::default(),
+        };
+        let text = toml::to_string_pretty(&cfg)?;
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        std::fs::write(path, text)?;
+        Ok(())
+    }
+}
+
+pub fn config_path() -> PathBuf {
+    let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".into());
+    PathBuf::from(home).join(".relay/config.toml")
+}
+
+pub fn data_dir() -> PathBuf {
+    let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".into());
+    PathBuf::from(home).join(".relay")
+}
+
+// ─── Core Types ──────────────────────────────────────────────────────────────
+
+/// The state of a session at time of handoff.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SessionSnapshot {
+    /// What the user was working on (extracted from conversation)
+    pub current_task: String,
+    /// Todo items and their states
+    pub todos: Vec<TodoItem>,
+    /// Key decisions made in the session
+    pub decisions: Vec<String>,
+    /// Recent errors or blockers
+    pub last_error: Option<String>,
+    /// Last tool output (truncated)
+    pub last_output: Option<String>,
+    /// Git state: branch, diff summary, recent commits
+    pub git_state: Option<GitState>,
+    /// Project directory
+    pub project_dir: String,
+    /// Files recently edited
+    pub recent_files: Vec<String>,
+    /// When the snapshot was taken
+    pub timestamp: String,
+    /// Deadline if set
+    pub deadline: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TodoItem {
+    pub content: String,
+    pub status: String, // pending, in_progress, completed
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GitState {
+    pub branch: String,
+    pub status_summary: String,
+    pub recent_commits: Vec<String>,
+    pub diff_summary: String,
+    pub uncommitted_files: Vec<String>,
+}
+
+/// Result of a handoff attempt.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct HandoffResult {
+    pub agent: String,
+    pub success: bool,
+    pub message: String,
+    pub handoff_file: Option<String>,
+}
+
+/// Agent availability status.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AgentStatus {
+    pub name: String,
+    pub available: bool,
+    pub reason: String,
+    pub version: Option<String>,
+}

package/core/src/main.rs

@@ -0,0 +1,331 @@
+use anyhow::Result;
+use clap::{Parser, Subcommand};
+use colored::Colorize;
+use std::path::PathBuf;
+
+use relay::{agents, capture, handoff, Config};
+
+#[derive(Parser)]
+#[command(
+    name = "relay",
+    about = "Relay — When Claude's rate limit hits, another agent picks up where you left off.",
+    long_about = "Captures your Claude Code session state (task, todos, git diff, decisions,\nerrors) and hands it off to Codex, Gemini, Ollama, or GPT-4 — so your\nwork never stops.",
+    version
+)]
+struct Cli {
+    #[command(subcommand)]
+    command: Commands,
+
+    /// Output as JSON
+    #[arg(long, global = true)]
+    json: bool,
+
+    /// Verbose logging
+    #[arg(long, short, global = true)]
+    verbose: bool,
+
+    /// Project directory
+    #[arg(long, global = true)]
+    project: Option<PathBuf>,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Hand off current session to a fallback agent right now
+    Handoff {
+        /// Force a specific agent (codex, gemini, ollama, openai)
+        #[arg(long)]
+        to: Option<String>,
+
+        /// Set deadline urgency (e.g. "7pm", "19:00", "30min")
+        #[arg(long)]
+        deadline: Option<String>,
+
+        /// Don't execute — just print the handoff package
+        #[arg(long)]
+        dry_run: bool,
+    },
+
+    /// Show current session snapshot (what would be handed off)
+    Status,
+
+    /// List configured agents and their availability
+    Agents,
+
+    /// Generate default config file at ~/.relay/config.toml
+    Init,
+
+    /// PostToolUse hook mode (auto-detect rate limits from stdin)
+    Hook {
+        /// Session ID
+        #[arg(long, default_value = "unknown")]
+        session: String,
+    },
+}
+
+fn main() -> Result<()> {
+    let cli = Cli::parse();
+
+    let filter = if cli.verbose { "debug" } else { "warn" };
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::try_from_default_env()
+                .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new(filter)),
+        )
+        .with_target(false)
+        .with_writer(std::io::stderr)
+        .init();
+
+    let project_dir = cli.project
+        .unwrap_or_else(|| std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")));
+    let config = Config::load().unwrap_or_else(|_| Config {
+        general: Default::default(),
+        agents: Default::default(),
+    });
+
+    match cli.command {
+        Commands::Handoff { to, deadline, dry_run } => {
+            eprintln!("{}", "⚡ Relay — capturing session state...".yellow().bold());
+
+            let snapshot = capture::capture_snapshot(
+                &project_dir,
+                deadline.as_deref(),
+            )?;
+
+            let target = to.as_deref().unwrap_or("auto");
+            let handoff_text = handoff::build_handoff(
+                &snapshot,
+                target,
+                config.general.max_context_tokens,
+            )?;
+
+            // Save handoff file for reference
+            let handoff_path = handoff::save_handoff(&handoff_text, &project_dir)?;
+
+            if dry_run || cli.json {
+                if cli.json {
+                    let result = serde_json::json!({
+                        "snapshot": snapshot,
+                        "handoff_text": handoff_text,
+                        "handoff_file": handoff_path.to_string_lossy(),
+                        "target_agent": target,
+                    });
+                    println!("{}", serde_json::to_string_pretty(&result)?);
+                } else {
+                    println!("{handoff_text}");
+                    eprintln!();
+                    eprintln!("{}", format!("📄 Saved to: {}", handoff_path.display()).dimmed());
+                }
+                return Ok(());
+            }
+
+            eprintln!("{}", format!("📄 Handoff saved: {}", handoff_path.display()).dimmed());
+            eprintln!();
+
+            // Execute handoff
+            let result = if let Some(ref agent_name) = to {
+                agents::handoff_to_named(&config, agent_name, &handoff_text, &project_dir.to_string_lossy())
+            } else {
+                agents::handoff_to_first_available(&config, &handoff_text, &project_dir.to_string_lossy())
+            }?;
+
+            if result.success {
+                eprintln!("{}", format!("✅ Handed off to {}", result.agent).green().bold());
+                eprintln!("   {}", result.message);
+            } else {
+                eprintln!("{}", format!("❌ Handoff failed: {}", result.message).red());
+                eprintln!();
+                eprintln!("💡 The handoff context was saved to:");
+                eprintln!("   {}", handoff_path.display());
+                eprintln!("   You can copy-paste it into any AI assistant manually.");
+            }
+        }
+
+        Commands::Status => {
+            let snapshot = capture::capture_snapshot(&project_dir, None)?;
+
+            if cli.json {
+                println!("{}", serde_json::to_string_pretty(&snapshot)?);
+                return Ok(());
+            }
+
+            println!("{}", "═══ Relay Session Snapshot ═══".bold());
+            println!();
+            println!("{}: {}", "Project".bold(), snapshot.project_dir);
+            println!("{}: {}", "Captured".bold(), snapshot.timestamp);
+            println!();
+
+            println!("{}", "── Current Task ──".cyan());
+            println!("  {}", snapshot.current_task);
+            println!();
+
+            if !snapshot.todos.is_empty() {
+                println!("{}", "── Todos ──".cyan());
+                for t in &snapshot.todos {
+                    let icon = match t.status.as_str() {
+                        "completed"   => "✅",
+                        "in_progress" => "🔄",
+                        _             => "⏳",
+                    };
+                    println!("  {icon} [{}] {}", t.status, t.content);
+                }
+                println!();
+            }
+
+            if let Some(ref err) = snapshot.last_error {
+                println!("{}", "── Last Error ──".red());
+                println!("  {err}");
+                println!();
+            }
+
+            if !snapshot.decisions.is_empty() {
+                println!("{}", "── Decisions ──".cyan());
+                for d in &snapshot.decisions {
+                    println!("  • {d}");
+                }
+                println!();
+            }
+
+            if let Some(ref git) = snapshot.git_state {
+                println!("{}", "── Git ──".cyan());
+                println!("  Branch: {}", git.branch);
+                println!("  {}", git.status_summary);
+                if !git.recent_commits.is_empty() {
+                    println!("  Recent:");
+                    for c in git.recent_commits.iter().take(3) {
+                        println!("    {c}");
+                    }
+                }
+                println!();
+            }
+
+            if !snapshot.recent_files.is_empty() {
+                println!("{}", "── Changed Files ──".cyan());
+                for f in snapshot.recent_files.iter().take(10) {
+                    println!("  {f}");
+                }
+                println!();
+            }
+        }
+
+        Commands::Agents => {
+            let statuses = agents::check_all_agents(&config);
+
+            if cli.json {
+                println!("{}", serde_json::to_string_pretty(&statuses)?);
+                return Ok(());
+            }
+
+            println!("{}", "═══ Relay Agents ═══".bold());
+            println!();
+            println!("Priority order: {}", config.general.priority.join(" → "));
+            println!();
+
+            for s in &statuses {
+                let icon = if s.available { "✅" } else { "❌" };
+                let name = if s.available {
+                    s.name.green().bold().to_string()
+                } else {
+                    s.name.dimmed().to_string()
+                };
+                println!(
+                    "  {icon}  {:<10}  {}",
+                    name,
+                    s.reason
+                );
+                if let Some(ref v) = s.version {
+                    println!("              Version: {v}");
+                }
+            }
+            println!();
+
+            let available = statuses.iter().filter(|s| s.available).count();
+            if available == 0 {
+                eprintln!("{}", "⚠️  No agents available. Run 'relay init' to configure.".yellow());
+            } else {
+                println!(
+                    "  {} agent{} ready for handoff.",
+                    available,
+                    if available == 1 { "" } else { "s" }
+                );
+            }
+        }
+
+        Commands::Init => {
+            let path = relay::config_path();
+            if path.exists() {
+                println!("Config already exists at: {}", path.display());
+                println!("Edit it to add API keys and customize agent priority.");
+            } else {
+                Config::save_default(&path)?;
+                println!("{}", "✅ Config created at:".green());
+                println!("   {}", path.display());
+                println!();
+                println!("Edit it to add API keys:");
+                println!("  [agents.gemini]");
+                println!("  api_key = \"your-gemini-key\"");
+                println!();
+                println!("  [agents.openai]");
+                println!("  api_key = \"your-openai-key\"");
+            }
+        }
+
+        Commands::Hook { session: _ } => {
+            use std::io::Read;
+            let mut raw = String::new();
+            std::io::stdin().read_to_string(&mut raw)?;
+
+            // Check for rate limit signals
+            if let Some(detection) = relay::detect::check_hook_output(&raw) {
+                eprintln!(
+                    "{}",
+                    format!(
+                        "🚨 [relay] Rate limit detected in {} output (signal: {})",
+                        detection.tool_name, detection.signal
+                    ).red().bold()
+                );
+
+                if config.general.auto_handoff {
+                    // Auto-handoff
+                    let snapshot = capture::capture_snapshot(&project_dir, None)?;
+                    let handoff_text = handoff::build_handoff(
+                        &snapshot,
+                        "auto",
+                        config.general.max_context_tokens,
+                    )?;
+
+                    let handoff_path = handoff::save_handoff(&handoff_text, &project_dir)?;
+                    eprintln!(
+                        "📄 Handoff saved: {}",
+                        handoff_path.display()
+                    );
+
+                    let result = agents::handoff_to_first_available(
+                        &config,
+                        &handoff_text,
+                        &project_dir.to_string_lossy(),
+                    )?;
+
+                    if result.success {
+                        eprintln!(
+                            "{}",
+                            format!("✅ Auto-handed off to {}", result.agent).green()
+                        );
+                    } else {
+                        eprintln!(
+                            "{}",
+                            format!("⚠️  No agents available. Handoff saved to: {}",
+                                handoff_path.display()
+                            ).yellow()
+                        );
+                    }
+                }
+            }
+
+            // Always pass through the original output
+            print!("{raw}");
+        }
+    }
+
+    Ok(())
+}

package/hooks/rate-limit.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Relay PostToolUse hook — detects rate limits and auto-hands off to fallback agent.
+set -euo pipefail
+
+RELAY="${RELAY_BIN:-relay}"
+if ! command -v "$RELAY" &>/dev/null; then
+  for candidate in "$HOME/.cargo/bin/relay" "/usr/local/bin/relay" \
+    "$(dirname "$0")/../core/target/release/relay"; do
+    [[ -x "$candidate" ]] && { RELAY="$candidate"; break; }
+  done
+fi
+
+INPUT=$(cat)
+
+if command -v "$RELAY" &>/dev/null || [[ -x "$RELAY" ]]; then
+  echo "$INPUT" | "$RELAY" hook --session "${CLAUDE_SESSION_ID:-default}" 2>/dev/null || echo "$INPUT"
+else
+  echo "$INPUT"
+fi