@masyv/relay 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MASYV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# Relay
+
+**When Claude's rate limit hits, another agent picks up exactly where you left off.**
+
+[![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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## The Problem
+
+You're building a feature. It's 6:20 PM. You need to submit by 7 PM. Claude hits its rate limit.
+
+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.
+
+**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.
+
+## How It Works
+
+```
+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.
+```
+
+## Quick Start
+
+```bash
+# Install
+git clone https://github.com/Manavarya09/relay
+cd relay && ./scripts/build.sh && ./scripts/install.sh
+
+# Generate config
+relay init
+
+# Check available agents
+relay agents
+
+# See what would be handed off
+relay status
+
+# Manual handoff (now)
+relay handoff
+
+# Handoff to specific agent with deadline
+relay handoff --to codex --deadline "7:00 PM"
+
+# Dry run — just print the handoff package
+relay handoff --dry-run
+```
+
+## What Relay Captures
+
+```
+═══ Relay Session Snapshot ═══
+
+Project: /Users/dev/myproject
+Captured: 2026-04-05 13:32:02
+
+── Current Task ──
+  Building WebSocket handler in src/server/ws.rs
+
+── Todos ──
+  ✅ [completed] Database schema + REST API
+  🔄 [in_progress] WebSocket handler (60% done)
+  ⏳ [pending] Frontend charts
+  ⏳ [pending] Auth
+
+── Last Error ──
+  error[E0499]: cannot borrow `state` as mutable...
+
+── Decisions ──
+  • Using Socket.io instead of raw WebSockets
+  • Redis pub/sub for cross-server events
+
+── Git ──
+  Branch: feature/websocket
+  3 uncommitted changes
+  Recent: abc1234 Add WebSocket route skeleton
+```
+
+## Agent Priority
+
+Configure in `~/.relay/config.toml`:
+
+```toml
+[general]
+priority = ["codex", "gemini", "ollama", "openai"]
+auto_handoff = true
+max_context_tokens = 8000
+
+[agents.codex]
+model = "o4-mini"
+
+[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
+```
+
+## Auto-Handoff via Hook
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [{ "type": "command", "command": "relay hook" }]
+      }
+    ]
+  }
+}
+```
+
+Relay will detect rate limit signals in tool output and automatically hand off.
+
+## Performance
+
+- **4.6 MB** binary (release, stripped)
+- **< 100ms** to capture full session snapshot
+- **Zero network calls** for capture (git + file reads only)
+
+## License
+
+MIT

package/core/Cargo.toml

@@ -0,0 +1,51 @@
+[package]
+name = "relay"
+version = "0.1.0"
+edition = "2021"
+description = "Relay — When Claude's rate limit hits, another agent picks up exactly where you left off."
+license = "MIT"
+
+[[bin]]
+name = "relay"
+path = "src/main.rs"
+
+[lib]
+name = "relay"
+path = "src/lib.rs"
+
+[dependencies]
+# CLI
+clap = { version = "4", features = ["derive"] }
+
+# Serialization
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+toml = "0.8"
+
+# Error handling
+anyhow = "1"
+thiserror = "2"
+
+# Text processing
+regex = "1"
+
+# Logging
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+
+# Time
+chrono = { version = "0.4", features = ["serde"] }
+
+# Hashing
+blake3 = "1"
+
+# HTTP client (for Ollama, OpenAI, Gemini APIs)
+ureq = { version = "2", features = ["json"] }
+
+# Terminal
+colored = "2"
+
+[profile.release]
+opt-level = 3
+lto = "thin"
+strip = true

package/core/src/agents/codex.rs

@@ -0,0 +1,91 @@
+//! Codex CLI agent adapter.
+//! Launches `codex` (OpenAI Codex CLI) as a subprocess with the handoff prompt.
+
+use super::Agent;
+use crate::{AgentStatus, CodexConfig, HandoffResult};
+use anyhow::Result;
+use std::process::Command;
+
+pub struct CodexAgent {
+    binary: String,
+    model: String,
+}
+
+impl CodexAgent {
+    pub fn new(config: &CodexConfig) -> Self {
+        Self {
+            binary: config.binary.clone().unwrap_or_else(|| "codex".into()),
+            model: config.model.clone(),
+        }
+    }
+
+    fn find_binary(&self) -> Option<String> {
+        // Check if binary exists in PATH
+        let output = Command::new("which")
+            .arg(&self.binary)
+            .output()
+            .ok()?;
+        if output.status.success() {
+            return Some(String::from_utf8_lossy(&output.stdout).trim().to_string());
+        }
+        None
+    }
+}
+
+impl Agent for CodexAgent {
+    fn name(&self) -> &str { "codex" }
+
+    fn check_available(&self) -> AgentStatus {
+        match self.find_binary() {
+            Some(path) => {
+                // Try to get version
+                let version = Command::new(&path)
+                    .arg("--version")
+                    .output()
+                    .ok()
+                    .filter(|o| o.status.success())
+                    .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string());
+
+                AgentStatus {
+                    name: "codex".into(),
+                    available: true,
+                    reason: format!("Found at {path}"),
+                    version,
+                }
+            }
+            None => AgentStatus {
+                name: "codex".into(),
+                available: false,
+                reason: format!("'{}' not found in PATH", self.binary),
+                version: None,
+            },
+        }
+    }
+
+    fn execute(&self, handoff_prompt: &str, project_dir: &str) -> Result<HandoffResult> {
+        let binary = self.find_binary().unwrap_or(self.binary.clone());
+
+        // Write handoff to a temp file
+        let tmp = std::env::temp_dir().join("relay_handoff.md");
+        std::fs::write(&tmp, handoff_prompt)?;
+
+        // Launch codex with the prompt
+        let mut child = Command::new(&binary)
+            .current_dir(project_dir)
+            .arg("--model")
+            .arg(&self.model)
+            .arg("--quiet")
+            .arg(handoff_prompt)
+            .spawn()?;
+
+        // Don't wait — let it run in the foreground
+        let _ = child.wait();
+
+        Ok(HandoffResult {
+            agent: "codex".into(),
+            success: true,
+            message: format!("Codex ({}) launched with handoff context", self.model),
+            handoff_file: Some(tmp.to_string_lossy().to_string()),
+        })
+    }
+}

package/core/src/agents/gemini.rs

@@ -0,0 +1,114 @@
+//! Gemini agent adapter — uses the Gemini API.
+
+use super::Agent;
+use crate::{AgentStatus, GeminiConfig, HandoffResult};
+use anyhow::Result;
+
+pub struct GeminiAgent {
+    api_key: Option<String>,
+    model: String,
+}
+
+impl GeminiAgent {
+    pub fn new(config: &GeminiConfig) -> Self {
+        let api_key = config.api_key.clone()
+            .or_else(|| std::env::var("GEMINI_API_KEY").ok())
+            .or_else(|| std::env::var("GOOGLE_API_KEY").ok());
+        Self {
+            api_key,
+            model: config.model.clone(),
+        }
+    }
+}
+
+impl Agent for GeminiAgent {
+    fn name(&self) -> &str { "gemini" }
+
+    fn check_available(&self) -> AgentStatus {
+        // First check if gemini CLI is available
+        if let Ok(output) = std::process::Command::new("which").arg("gemini").output() {
+            if output.status.success() {
+                return AgentStatus {
+                    name: "gemini".into(),
+                    available: true,
+                    reason: "Gemini CLI found in PATH".into(),
+                    version: None,
+                };
+            }
+        }
+
+        match &self.api_key {
+            Some(_) => AgentStatus {
+                name: "gemini".into(),
+                available: true,
+                reason: format!("API key configured, model: {}", self.model),
+                version: Some(self.model.clone()),
+            },
+            None => AgentStatus {
+                name: "gemini".into(),
+                available: false,
+                reason: "No API key. Set GEMINI_API_KEY env var or add to config.toml".into(),
+                version: None,
+            },
+        }
+    }
+
+    fn execute(&self, handoff_prompt: &str, project_dir: &str) -> Result<HandoffResult> {
+        // Try Gemini CLI first
+        if let Ok(output) = std::process::Command::new("which").arg("gemini").output() {
+            if output.status.success() {
+                let mut child = std::process::Command::new("gemini")
+                    .current_dir(project_dir)
+                    .arg(handoff_prompt)
+                    .spawn()?;
+                let _ = child.wait();
+                return Ok(HandoffResult {
+                    agent: "gemini".into(),
+                    success: true,
+                    message: "Gemini CLI launched with handoff context".into(),
+                    handoff_file: None,
+                });
+            }
+        }
+
+        // Fall back to API
+        let api_key = self.api_key.as_ref()
+            .ok_or_else(|| anyhow::anyhow!("No Gemini API key"))?;
+
+        let url = format!(
+            "https://generativelanguage.googleapis.com/v1beta/models/{}:generateContent?key={}",
+            self.model, api_key
+        );
+
+        let body = serde_json::json!({
+            "contents": [{
+                "parts": [{ "text": handoff_prompt }]
+            }]
+        });
+
+        let resp = ureq::post(&url)
+            .set("Content-Type", "application/json")
+            .send_json(&body)?;
+
+        let resp_json: serde_json::Value = resp.into_json()?;
+
+        let text = resp_json
+            .get("candidates")
+            .and_then(|c| c.get(0))
+            .and_then(|c| c.get("content"))
+            .and_then(|c| c.get("parts"))
+            .and_then(|p| p.get(0))
+            .and_then(|p| p.get("text"))
+            .and_then(|t| t.as_str())
+            .unwrap_or("(no response)");
+
+        println!("{text}");
+
+        Ok(HandoffResult {
+            agent: "gemini".into(),
+            success: true,
+            message: format!("Gemini ({}) responded to handoff", self.model),
+            handoff_file: None,
+        })
+    }
+}

package/core/src/agents/mod.rs

@@ -0,0 +1,86 @@
+pub mod codex;
+pub mod gemini;
+pub mod ollama;
+pub mod openai;
+
+use crate::{AgentStatus, Config, HandoffResult};
+use anyhow::Result;
+
+/// Trait for all fallback agents.
+pub trait Agent {
+    fn name(&self) -> &str;
+    fn check_available(&self) -> AgentStatus;
+    fn execute(&self, handoff_prompt: &str, project_dir: &str) -> Result<HandoffResult>;
+}
+
+/// Get all configured agents in priority order.
+pub fn get_agents(config: &Config) -> Vec<Box<dyn Agent>> {
+    let mut agents: Vec<Box<dyn Agent>> = Vec::new();
+    for name in &config.general.priority {
+        match name.as_str() {
+            "codex"  => agents.push(Box::new(codex::CodexAgent::new(&config.agents.codex))),
+            "gemini" => agents.push(Box::new(gemini::GeminiAgent::new(&config.agents.gemini))),
+            "ollama" => agents.push(Box::new(ollama::OllamaAgent::new(&config.agents.ollama))),
+            "openai" => agents.push(Box::new(openai::OpenAIAgent::new(&config.agents.openai))),
+            _ => {} // unknown agent, skip
+        }
+    }
+    agents
+}
+
+/// Check availability of all agents and return statuses.
+pub fn check_all_agents(config: &Config) -> Vec<AgentStatus> {
+    get_agents(config).iter().map(|a| a.check_available()).collect()
+}
+
+/// Execute handoff on the first available agent.
+pub fn handoff_to_first_available(
+    config: &Config,
+    handoff_prompt: &str,
+    project_dir: &str,
+) -> Result<HandoffResult> {
+    let agents = get_agents(config);
+    for agent in &agents {
+        let status = agent.check_available();
+        if status.available {
+            tracing::info!("Handing off to {}", agent.name());
+            return agent.execute(handoff_prompt, project_dir);
+        }
+    }
+    Ok(HandoffResult {
+        agent: "none".into(),
+        success: false,
+        message: "No agents available. Configure at least one in ~/.relay/config.toml".into(),
+        handoff_file: None,
+    })
+}
+
+/// Execute handoff on a specific named agent.
+pub fn handoff_to_named(
+    config: &Config,
+    agent_name: &str,
+    handoff_prompt: &str,
+    project_dir: &str,
+) -> Result<HandoffResult> {
+    let agents = get_agents(config);
+    for agent in &agents {
+        if agent.name() == agent_name {
+            let status = agent.check_available();
+            if !status.available {
+                return Ok(HandoffResult {
+                    agent: agent_name.into(),
+                    success: false,
+                    message: format!("{} is not available: {}", agent_name, status.reason),
+                    handoff_file: None,
+                });
+            }
+            return agent.execute(handoff_prompt, project_dir);
+        }
+    }
+    Ok(HandoffResult {
+        agent: agent_name.into(),
+        success: false,
+        message: format!("Unknown agent: {agent_name}. Available: codex, gemini, ollama, openai"),
+        handoff_file: None,
+    })
+}

package/core/src/agents/ollama.rs

@@ -0,0 +1,98 @@
+//! Ollama local agent adapter — uses the Ollama REST API.
+
+use super::Agent;
+use crate::{AgentStatus, HandoffResult, OllamaConfig};
+use anyhow::Result;
+
+pub struct OllamaAgent {
+    url: String,
+    model: String,
+}
+
+impl OllamaAgent {
+    pub fn new(config: &OllamaConfig) -> Self {
+        Self {
+            url: config.url.clone(),
+            model: config.model.clone(),
+        }
+    }
+}
+
+impl Agent for OllamaAgent {
+    fn name(&self) -> &str { "ollama" }
+
+    fn check_available(&self) -> AgentStatus {
+        // Ping Ollama's API
+        let tag_url = format!("{}/api/tags", self.url);
+        match ureq::get(&tag_url).call() {
+            Ok(resp) => {
+                let body: serde_json::Value = resp.into_json().unwrap_or_default();
+                let models = body.get("models")
+                    .and_then(|m| m.as_array())
+                    .map(|a| a.len())
+                    .unwrap_or(0);
+
+                // Check if our target model is available
+                let has_model = body.get("models")
+                    .and_then(|m| m.as_array())
+                    .map(|arr| arr.iter().any(|m| {
+                        m.get("name").and_then(|n| n.as_str())
+                            .map(|n| n.starts_with(&self.model))
+                            .unwrap_or(false)
+                    }))
+                    .unwrap_or(false);
+
+                if has_model {
+                    AgentStatus {
+                        name: "ollama".into(),
+                        available: true,
+                        reason: format!("Running at {}, {} models, '{}' available", self.url, models, self.model),
+                        version: Some(self.model.clone()),
+                    }
+                } else {
+                    AgentStatus {
+                        name: "ollama".into(),
+                        available: true,
+                        reason: format!("Running but model '{}' not pulled. {} models available", self.model, models),
+                        version: None,
+                    }
+                }
+            }
+            Err(_) => AgentStatus {
+                name: "ollama".into(),
+                available: false,
+                reason: format!("Not reachable at {}", self.url),
+                version: None,
+            },
+        }
+    }
+
+    fn execute(&self, handoff_prompt: &str, _project_dir: &str) -> Result<HandoffResult> {
+        let url = format!("{}/api/generate", self.url);
+
+        let body = serde_json::json!({
+            "model": self.model,
+            "prompt": handoff_prompt,
+            "stream": false
+        });
+
+        let resp = ureq::post(&url)
+            .set("Content-Type", "application/json")
+            .send_json(&body)?;
+
+        let resp_json: serde_json::Value = resp.into_json()?;
+        let text = resp_json
+            .get("response")
+            .and_then(|r| r.as_str())
+            .unwrap_or("(no response)");
+
+        println!("{text}");
+
+        Ok(HandoffResult {
+            agent: "ollama".into(),
+            success: true,
+            message: format!("Ollama ({}) responded", self.model),
+            handoff_file: None,
+        })
+    }
+}