@masyv/relay 0.3.0 → 0.5.0

package/core/Cargo.toml

@@ -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/agents/aider.rs

@@ -0,0 +1,75 @@
+//! Aider agent adapter — launches the aider TUI interactively.
+//! https://github.com/paul-gauthier/aider
+
+use super::Agent;
+use crate::{AgentStatus, HandoffResult};
+use anyhow::Result;
+use std::process::Command;
+
+pub struct AiderAgent {
+    model: String,
+}
+
+impl AiderAgent {
+    pub fn new(model: Option<&str>) -> Self {
+        Self {
+            model: model.unwrap_or("sonnet").to_string(),
+        }
+    }
+
+    fn find_binary() -> Option<String> {
+        let output = Command::new("which").arg("aider").output().ok()?;
+        if output.status.success() {
+            Some(String::from_utf8_lossy(&output.stdout).trim().to_string())
+        } else {
+            None
+        }
+    }
+}
+
+impl Agent for AiderAgent {
+    fn name(&self) -> &str { "aider" }
+
+    fn check_available(&self) -> AgentStatus {
+        match Self::find_binary() {
+            Some(path) => AgentStatus {
+                name: "aider".into(),
+                available: true,
+                reason: format!("Found at {path}"),
+                version: Command::new(&path).arg("--version").output().ok()
+                    .filter(|o| o.status.success())
+                    .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string()),
+            },
+            None => AgentStatus {
+                name: "aider".into(),
+                available: false,
+                reason: "Not found. Install: pip install aider-chat".into(),
+                version: None,
+            },
+        }
+    }
+
+    fn execute(&self, handoff_prompt: &str, project_dir: &str) -> Result<HandoffResult> {
+        let binary = Self::find_binary().unwrap_or("aider".into());
+        let tmp = std::env::temp_dir().join("relay_handoff.md");
+        std::fs::write(&tmp, handoff_prompt)?;
+
+        let status = Command::new(&binary)
+            .current_dir(project_dir)
+            .arg("--model")
+            .arg(&self.model)
+            .arg("--message")
+            .arg(handoff_prompt)
+            .stdin(std::process::Stdio::inherit())
+            .stdout(std::process::Stdio::inherit())
+            .stderr(std::process::Stdio::inherit())
+            .status()?;
+
+        Ok(HandoffResult {
+            agent: "aider".into(),
+            success: status.success(),
+            message: format!("Aider ({}) session ended", self.model),
+            handoff_file: Some(tmp.to_string_lossy().to_string()),
+        })
+    }
+}

package/core/src/agents/claude.rs

@@ -0,0 +1,68 @@
+//! Claude CLI agent — starts a new Claude Code session with full context.
+//! Useful when the rate limit resets or you have a second subscription.
+
+use super::Agent;
+use crate::{AgentStatus, HandoffResult};
+use anyhow::Result;
+use std::process::Command;
+
+pub struct ClaudeAgent;
+
+impl ClaudeAgent {
+    pub fn new() -> Self { Self }
+
+    fn find_binary() -> Option<String> {
+        let output = Command::new("which").arg("claude").output().ok()?;
+        if output.status.success() {
+            Some(String::from_utf8_lossy(&output.stdout).trim().to_string())
+        } else {
+            None
+        }
+    }
+}
+
+impl Agent for ClaudeAgent {
+    fn name(&self) -> &str { "claude" }
+
+    fn check_available(&self) -> AgentStatus {
+        match Self::find_binary() {
+            Some(path) => AgentStatus {
+                name: "claude".into(),
+                available: true,
+                reason: format!("Found at {path}"),
+                version: Command::new(&path).arg("--version").output().ok()
+                    .filter(|o| o.status.success())
+                    .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string()),
+            },
+            None => AgentStatus {
+                name: "claude".into(),
+                available: false,
+                reason: "Not found. Install: npm install -g @anthropic-ai/claude-code".into(),
+                version: None,
+            },
+        }
+    }
+
+    fn execute(&self, handoff_prompt: &str, project_dir: &str) -> Result<HandoffResult> {
+        let binary = Self::find_binary().unwrap_or("claude".into());
+        let tmp = std::env::temp_dir().join("relay_handoff.md");
+        std::fs::write(&tmp, handoff_prompt)?;
+
+        // Launch Claude interactively with the handoff as initial prompt
+        let status = Command::new(&binary)
+            .current_dir(project_dir)
+            .arg("--resume")
+            .arg(handoff_prompt)
+            .stdin(std::process::Stdio::inherit())
+            .stdout(std::process::Stdio::inherit())
+            .stderr(std::process::Stdio::inherit())
+            .status()?;
+
+        Ok(HandoffResult {
+            agent: "claude".into(),
+            success: status.success(),
+            message: "Claude session ended".into(),
+            handoff_file: Some(tmp.to_string_lossy().to_string()),
+        })
+    }
+}

package/core/src/agents/copilot.rs

@@ -0,0 +1,63 @@
+//! GitHub Copilot CLI agent adapter.
+
+use super::Agent;
+use crate::{AgentStatus, HandoffResult};
+use anyhow::Result;
+use std::process::Command;
+
+pub struct CopilotAgent;
+
+impl CopilotAgent {
+    pub fn new() -> Self { Self }
+
+    fn find_binary() -> Option<String> {
+        let output = Command::new("which").arg("copilot").output().ok()?;
+        if output.status.success() {
+            Some(String::from_utf8_lossy(&output.stdout).trim().to_string())
+        } else {
+            None
+        }
+    }
+}
+
+impl Agent for CopilotAgent {
+    fn name(&self) -> &str { "copilot" }
+
+    fn check_available(&self) -> AgentStatus {
+        match Self::find_binary() {
+            Some(path) => AgentStatus {
+                name: "copilot".into(),
+                available: true,
+                reason: format!("Found at {path}"),
+                version: None, // copilot --version hangs, skip it
+            },
+            None => AgentStatus {
+                name: "copilot".into(),
+                available: false,
+                reason: "Not found. Install: gh extension install github/gh-copilot".into(),
+                version: None,
+            },
+        }
+    }
+
+    fn execute(&self, handoff_prompt: &str, project_dir: &str) -> Result<HandoffResult> {
+        let binary = Self::find_binary().unwrap_or("copilot".into());
+        let tmp = std::env::temp_dir().join("relay_handoff.md");
+        std::fs::write(&tmp, handoff_prompt)?;
+
+        let status = Command::new(&binary)
+            .current_dir(project_dir)
+            .arg(handoff_prompt)
+            .stdin(std::process::Stdio::inherit())
+            .stdout(std::process::Stdio::inherit())
+            .stderr(std::process::Stdio::inherit())
+            .status()?;
+
+        Ok(HandoffResult {
+            agent: "copilot".into(),
+            success: status.success(),
+            message: "Copilot session ended".into(),
+            handoff_file: Some(tmp.to_string_lossy().to_string()),
+        })
+    }
+}

package/core/src/agents/mod.rs

@@ -1,7 +1,11 @@
+pub mod aider;
+pub mod claude;
 pub mod codex;
+pub mod copilot;
 pub mod gemini;
 pub mod ollama;
 pub mod openai;
+pub mod opencode;
 
 use crate::{AgentStatus, Config, HandoffResult};
 use anyhow::Result;
@@ -18,10 +22,14 @@ 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))),
+            "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))),
+            "aider"    => agents.push(Box::new(aider::AiderAgent::new(None))),
+            "claude"   => agents.push(Box::new(claude::ClaudeAgent::new())),
+            "copilot"  => agents.push(Box::new(copilot::CopilotAgent::new())),
+            "opencode" => agents.push(Box::new(opencode::OpenCodeAgent::new())),
             _ => {} // unknown agent, skip
         }
     }

package/core/src/agents/ollama.rs

@@ -3,6 +3,7 @@
 use super::Agent;
 use crate::{AgentStatus, HandoffResult, OllamaConfig};
 use anyhow::Result;
+use std::process::Command;
 
 pub struct OllamaAgent {
     url: String,
@@ -22,43 +23,24 @@ impl Agent for OllamaAgent {
     fn name(&self) -> &str { "ollama" }
 
     fn check_available(&self) -> AgentStatus {
-        // Ping Ollama's API
+        // Use curl with a 2s timeout — avoids ureq hanging on refused connections
         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);
+        let output = Command::new("curl")
+            .args(["--silent", "--max-time", "2", &tag_url])
+            .output();
 
-                // 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,
-                    }
+        match output {
+            Ok(o) if o.status.success() => {
+                let body: serde_json::Value = serde_json::from_slice(&o.stdout).unwrap_or_default();
+                let models = body.get("models").and_then(|m| m.as_array()).map(|a| a.len()).unwrap_or(0);
+                AgentStatus {
+                    name: "ollama".into(),
+                    available: true,
+                    reason: format!("Running at {}, {} models available", self.url, models),
+                    version: Some(self.model.clone()),
                 }
             }
-            Err(_) => AgentStatus {
+            _ => AgentStatus {
                 name: "ollama".into(),
                 available: false,
                 reason: format!("Not reachable at {}", self.url),
@@ -69,7 +51,6 @@ impl Agent for OllamaAgent {
 
     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,
@@ -81,11 +62,7 @@ impl Agent for OllamaAgent {
             .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)");
-
+        let text = resp_json.get("response").and_then(|r| r.as_str()).unwrap_or("(no response)");
         println!("{text}");
 
         Ok(HandoffResult {

package/core/src/agents/opencode.rs

@@ -0,0 +1,66 @@
+//! OpenCode agent adapter — Go-based coding agent.
+//! https://github.com/opencode-ai/opencode
+
+use super::Agent;
+use crate::{AgentStatus, HandoffResult};
+use anyhow::Result;
+use std::process::Command;
+
+pub struct OpenCodeAgent;
+
+impl OpenCodeAgent {
+    pub fn new() -> Self { Self }
+
+    fn find_binary() -> Option<String> {
+        let output = Command::new("which").arg("opencode").output().ok()?;
+        if output.status.success() {
+            Some(String::from_utf8_lossy(&output.stdout).trim().to_string())
+        } else {
+            None
+        }
+    }
+}
+
+impl Agent for OpenCodeAgent {
+    fn name(&self) -> &str { "opencode" }
+
+    fn check_available(&self) -> AgentStatus {
+        match Self::find_binary() {
+            Some(path) => AgentStatus {
+                name: "opencode".into(),
+                available: true,
+                reason: format!("Found at {path}"),
+                version: Command::new(&path).arg("--version").output().ok()
+                    .filter(|o| o.status.success())
+                    .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string()),
+            },
+            None => AgentStatus {
+                name: "opencode".into(),
+                available: false,
+                reason: "Not found. Install: go install github.com/opencode-ai/opencode@latest".into(),
+                version: None,
+            },
+        }
+    }
+
+    fn execute(&self, handoff_prompt: &str, project_dir: &str) -> Result<HandoffResult> {
+        let binary = Self::find_binary().unwrap_or("opencode".into());
+        let tmp = std::env::temp_dir().join("relay_handoff.md");
+        std::fs::write(&tmp, handoff_prompt)?;
+
+        let status = Command::new(&binary)
+            .current_dir(project_dir)
+            .arg(handoff_prompt)
+            .stdin(std::process::Stdio::inherit())
+            .stdout(std::process::Stdio::inherit())
+            .stderr(std::process::Stdio::inherit())
+            .status()?;
+
+        Ok(HandoffResult {
+            agent: "opencode".into(),
+            success: status.success(),
+            message: "OpenCode session ended".into(),
+            handoff_file: Some(tmp.to_string_lossy().to_string()),
+        })
+    }
+}

package/core/src/handoff/mod.rs

@@ -117,19 +117,26 @@ pub fn build_handoff(
     }
 
     // ── Instructions for agent ─────────────────────────────────
+    let deadline_note = if snapshot.deadline.is_some() {
+        "\nIMPORTANT: There is a DEADLINE. If the user asks you to continue, prioritise the current task."
+    } else { "" };
+
     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\
+        You have been given the full context from a Claude Code session.\n\
+        The context above shows what was being worked on, what decisions were made,\n\
+        what files were changed, and what the last state was.\n\
+        \n\
+        DO NOT immediately start working on anything.\n\
+        Instead, briefly confirm you have the context by saying something like:\n\
+        \"Context restored from your Claude session. I can see you were working on [brief summary]. What would you like me to do?\"\n\
+        \n\
+        Then WAIT for the user to tell you what to do next.\n\
         \n\
-        Working directory: {}\n\
+        Working directory: {}\
         {}",
         snapshot.project_dir,
-        if snapshot.deadline.is_some() {
-            "THERE IS A DEADLINE. Prioritise completing the current task."
-        } else { "" }
+        deadline_note
     );
     sections.push(instructions);
 

package/core/src/lib.rs

@@ -2,6 +2,7 @@ pub mod agents;
 pub mod capture;
 pub mod detect;
 pub mod handoff;
+pub mod tui;
 
 use serde::{Deserialize, Serialize};
 use std::path::PathBuf;
@@ -43,7 +44,11 @@ impl Default for GeneralConfig {
 fn default_priority() -> Vec<String> {
     vec![
         "codex".into(),
+        "claude".into(),
+        "aider".into(),
         "gemini".into(),
+        "copilot".into(),
+        "opencode".into(),
         "ollama".into(),
         "openai".into(),
     ]

package/core/src/main.rs

@@ -1,22 +1,20 @@
 use anyhow::Result;
 use clap::{Parser, Subcommand};
-use colored::Colorize;
 use std::path::PathBuf;
 
-use relay::{agents, capture, handoff, Config};
+use relay::{agents, capture, handoff, tui, 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
+    /// Output as JSON (no TUI)
     #[arg(long, global = true)]
     json: bool,
 
@@ -31,17 +29,17 @@ struct Cli {
 
 #[derive(Subcommand)]
 enum Commands {
-    /// Hand off current session to a fallback agent right now
+    /// Hand off current session to a fallback agent
     Handoff {
-        /// Force a specific agent (codex, gemini, ollama, openai)
+        /// Target agent (codex, claude, aider, gemini, copilot, opencode, ollama, openai)
         #[arg(long)]
         to: Option<String>,
 
-        /// Set deadline urgency (e.g. "7pm", "19:00", "30min")
+        /// Set deadline urgency (e.g. "7pm", "30min")
         #[arg(long)]
         deadline: Option<String>,
 
-        /// Don't execute — just print the handoff package
+        /// Just print the handoff — don't launch agent
         #[arg(long)]
         dry_run: bool,
 
@@ -54,18 +52,17 @@ enum Commands {
         include: String,
     },
 
-    /// Show current session snapshot (what would be handed off)
+    /// Show current session snapshot
     Status,
 
-    /// List configured agents and their availability
+    /// List configured agents and availability
     Agents,
 
-    /// Generate default config file at ~/.relay/config.toml
+    /// Generate default config at ~/.relay/config.toml
     Init,
 
-    /// PostToolUse hook mode (auto-detect rate limits from stdin)
+    /// PostToolUse hook (auto-detect rate limits)
     Hook {
-        /// Session ID
         #[arg(long, default_value = "unknown")]
         session: String,
     },
@@ -92,286 +89,183 @@ fn main() -> Result<()> {
     });
 
     match cli.command {
+        // ═══════════════════════════════════════════════════════════════
+        // HANDOFF
+        // ═══════════════════════════════════════════════════════════════
         Commands::Handoff { to, deadline, dry_run, turns, include } => {
-            eprintln!("{}", "⚡ Relay — capturing session state...".yellow().bold());
+            if !cli.json {
+                tui::print_banner();
+            }
+
+            // Step 1: Capture
+            let sp = if !cli.json { Some(tui::step(1, 3, "Capturing session state...")) } else { None };
 
-            // Set conversation turn limit before capture
             relay::capture::session::MAX_CONVERSATION_TURNS
                 .store(turns, std::sync::atomic::Ordering::Relaxed);
 
-            let mut snapshot = capture::capture_snapshot(
-                &project_dir,
-                deadline.as_deref(),
-            )?;
+            let mut snapshot = capture::capture_snapshot(&project_dir, deadline.as_deref())?;
 
-            // Filter sections based on --include flag
+            // Apply include filter
             let includes: Vec<&str> = include.split(',').map(|s| s.trim()).collect();
             if !includes.contains(&"all") {
-                if !includes.contains(&"conversation") {
-                    snapshot.conversation.clear();
-                }
-                if !includes.contains(&"git") {
-                    snapshot.git_state = None;
-                    snapshot.recent_files.clear();
-                }
-                if !includes.contains(&"todos") {
-                    snapshot.todos.clear();
-                }
+                if !includes.contains(&"conversation") { snapshot.conversation.clear(); }
+                if !includes.contains(&"git") { snapshot.git_state = None; snapshot.recent_files.clear(); }
+                if !includes.contains(&"todos") { snapshot.todos.clear(); }
             }
 
-            let target = to.as_deref().unwrap_or("auto");
+            if let Some(sp) = sp { sp.finish_with_message("Session captured"); }
+
+            // Step 2: Build handoff
+            let sp = if !cli.json { Some(tui::step(2, 3, "Building handoff package...")) } else { None };
+
+            // Resolve target agent
+            let target_name = if let Some(ref name) = to {
+                name.clone()
+            } else if !cli.json && !dry_run {
+                // Interactive agent selection
+                if let Some(sp) = sp.as_ref() { sp.finish_with_message("Handoff built"); }
+
+                let statuses = agents::check_all_agents(&config);
+                let agent_list: Vec<(String, bool, String)> = statuses
+                    .iter()
+                    .map(|s| (s.name.clone(), s.available, s.reason.clone()))
+                    .collect();
+
+                match tui::select_agent(&agent_list) {
+                    Some(name) => name,
+                    None => {
+                        eprintln!("  No agent selected.");
+                        return Ok(());
+                    }
+                }
+            } else {
+                "auto".into()
+            };
+
             let handoff_text = handoff::build_handoff(
-                &snapshot,
-                target,
-                config.general.max_context_tokens,
+                &snapshot, &target_name, 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());
-                }
+            if let Some(sp) = sp { sp.finish_with_message("Handoff built"); }
+
+            // JSON / dry-run output
+            if cli.json {
+                println!("{}", serde_json::to_string_pretty(&serde_json::json!({
+                    "snapshot": snapshot,
+                    "handoff_text": handoff_text,
+                    "handoff_file": handoff_path.to_string_lossy(),
+                    "target_agent": target_name,
+                }))?);
+                return Ok(());
+            }
+            if dry_run {
+                println!("{handoff_text}");
+                eprintln!();
+                eprintln!("  📄 Saved: {}", handoff_path.display());
                 return Ok(());
             }
 
-            eprintln!("{}", format!("📄 Handoff saved: {}", handoff_path.display()).dimmed());
-            eprintln!();
+            // Step 3: Launch agent
+            let sp = tui::step(3, 3, &format!("Launching {}...", target_name));
 
-            // 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())
+            let result = if to.is_some() {
+                agents::handoff_to_named(&config, &target_name, &handoff_text, &project_dir.to_string_lossy())
             } else {
                 agents::handoff_to_first_available(&config, &handoff_text, &project_dir.to_string_lossy())
             }?;
 
+            sp.finish_with_message(if result.success {
+                format!("{} launched", target_name)
+            } else {
+                "Failed".into()
+            });
+
             if result.success {
-                eprintln!("{}", format!("✅ Handed off to {}", result.agent).green().bold());
-                eprintln!("   {}", result.message);
+                tui::print_handoff_success(&result.agent, &handoff_path.to_string_lossy());
             } 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.");
+                tui::print_handoff_fail(&result.message, &handoff_path.to_string_lossy());
             }
         }
 
+        // ═══════════════════════════════════════════════════════════════
+        // STATUS
+        // ═══════════════════════════════════════════════════════════════
         Commands::Status => {
+            let sp = if !cli.json { Some(tui::spinner("Reading session state...")) } else { None };
             let snapshot = capture::capture_snapshot(&project_dir, None)?;
+            if let Some(sp) = sp { sp.finish_and_clear(); }
 
             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!();
-            }
-
-            if !snapshot.conversation.is_empty() {
-                println!("{}", format!("── Conversation ({} turns) ──", snapshot.conversation.len()).cyan());
-                // Show last 15 turns
-                let start = snapshot.conversation.len().saturating_sub(15);
-                for turn in &snapshot.conversation[start..] {
-                    let prefix = match turn.role.as_str() {
-                        "user"           => "👤 USER".to_string(),
-                        "assistant"      => "🤖 CLAUDE".to_string(),
-                        "assistant_tool" => "🔧 TOOL".to_string(),
-                        "tool_result"    => "📤 RESULT".to_string(),
-                        _                => turn.role.clone(),
-                    };
-                    let content = if turn.content.len() > 120 {
-                        format!("{}...", &turn.content[..117])
-                    } else {
-                        turn.content.clone()
-                    };
-                    println!("  {}: {}", prefix, content);
-                }
-                println!();
+            } else {
+                tui::print_snapshot(&snapshot);
             }
         }
 
+        // ═══════════════════════════════════════════════════════════════
+        // AGENTS
+        // ═══════════════════════════════════════════════════════════════
         Commands::Agents => {
+            let sp = if !cli.json { Some(tui::spinner("Checking agents...")) } else { None };
             let statuses = agents::check_all_agents(&config);
+            if let Some(sp) = sp { sp.finish_and_clear(); }
 
             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" }
-                );
+                tui::print_agents(&config.general.priority, &statuses);
             }
         }
 
+        // ═══════════════════════════════════════════════════════════════
+        // INIT
+        // ═══════════════════════════════════════════════════════════════
         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.");
+                eprintln!("  Config exists: {}", path.display());
+                eprintln!("  Edit to add API keys and customize 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\"");
+                eprintln!("  ✅ Config created: {}", path.display());
+                eprintln!();
+                eprintln!("  Add API keys:");
+                eprintln!("    [agents.gemini]");
+                eprintln!("    api_key = \"your-key\"");
+                eprintln!();
+                eprintln!("    [agents.openai]");
+                eprintln!("    api_key = \"your-key\"");
             }
         }
 
+        // ═══════════════════════════════════════════════════════════════
+        // HOOK
+        // ═══════════════════════════════════════════════════════════════
         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()
+                    "  🚨 Rate limit detected in {} (signal: {})",
+                    detection.tool_name, detection.signal
                 );
-
                 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_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(),
+                        &config, &handoff_text, &project_dir.to_string_lossy(),
                     )?;
-
                     if result.success {
-                        eprintln!(
-                            "{}",
-                            format!("✅ Auto-handed off to {}", result.agent).green()
-                        );
+                        eprintln!("  ✅ Auto-handed off to {}", result.agent);
                     } else {
-                        eprintln!(
-                            "{}",
-                            format!("⚠️  No agents available. Handoff saved to: {}",
-                                handoff_path.display()
-                            ).yellow()
-                        );
+                        eprintln!("  📄 Saved: {}", handoff_path.display());
                     }
                 }
             }
-
-            // Always pass through the original output
             print!("{raw}");
         }
     }

package/core/src/tui.rs

@@ -0,0 +1,324 @@
+//! Beautiful terminal UI for Relay — spinners, boxes, interactive prompts.
+
+use colored::Colorize;
+use console::Term;
+use indicatif::{ProgressBar, ProgressStyle};
+use std::time::Duration;
+
+// ─── Banner ─────────────────────────────────────────────────────────────────
+
+pub fn print_banner() {
+    let banner = r#"
+  ╔═══════════════════════════════════════════════╗
+  ║                                               ║
+  ║   ⚡ R E L A Y                                ║
+  ║   Cross-agent context handoff                 ║
+  ║                                               ║
+  ╚═══════════════════════════════════════════════╝
+"#;
+    eprintln!("{}", banner.cyan());
+}
+
+// ─── Spinners ───────────────────────────────────────────────────────────────
+
+pub fn spinner(msg: &str) -> ProgressBar {
+    let pb = ProgressBar::new_spinner();
+    pb.set_style(
+        ProgressStyle::with_template("  {spinner:.cyan} {msg}")
+            .unwrap()
+            .tick_strings(&["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏", "✓"]),
+    );
+    pb.set_message(msg.to_string());
+    pb.enable_steady_tick(Duration::from_millis(80));
+    pb
+}
+
+pub fn step(num: usize, total: usize, msg: &str) -> ProgressBar {
+    let pb = ProgressBar::new_spinner();
+    pb.set_style(
+        ProgressStyle::with_template(&format!(
+            "  {{spinner:.cyan}} [{}/{}] {{msg}}",
+            num, total
+        ))
+        .unwrap()
+        .tick_strings(&["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏", "✓"]),
+    );
+    pb.set_message(msg.to_string());
+    pb.enable_steady_tick(Duration::from_millis(80));
+    pb
+}
+
+// ─── Boxes ──────────────────────────────────────────────────────────────────
+
+pub fn print_box(title: &str, content: &str) {
+    let term_width = Term::stdout().size().1 as usize;
+    let width = term_width.min(72).max(40);
+    let inner = width - 4;
+
+    // Top border
+    eprintln!("  ╭{}╮", "─".repeat(inner + 2));
+
+    // Title
+    let title_padded = format!(" {} ", title);
+    let pad = inner.saturating_sub(title_padded.len()) + 1;
+    eprintln!("  │{}{}│", title_padded.bold().cyan(), " ".repeat(pad));
+
+    // Separator
+    eprintln!("  ├{}┤", "─".repeat(inner + 2));
+
+    // Content lines
+    for line in content.lines() {
+        let display_line = if line.len() > inner {
+            let mut end = inner.saturating_sub(1);
+            while end > 0 && !line.is_char_boundary(end) { end -= 1; }
+            format!("{}…", &line[..end])
+        } else {
+            line.to_string()
+        };
+        let pad = inner.saturating_sub(display_line.len()) + 1;
+        eprintln!("  │ {}{} │", display_line, " ".repeat(pad.saturating_sub(1)));
+    }
+
+    // Bottom border
+    eprintln!("  ╰{}╯", "─".repeat(inner + 2));
+}
+
+pub fn print_section(icon: &str, title: &str) {
+    eprintln!();
+    eprintln!("  {} {}", icon, title.bold());
+    eprintln!("  {}", "─".repeat(50).dimmed());
+}
+
+// ─── Agent Select ───────────────────────────────────────────────────────────
+
+pub fn select_agent(agents: &[(String, bool, String)]) -> Option<String> {
+    let items: Vec<String> = agents
+        .iter()
+        .map(|(name, available, reason)| {
+            if *available {
+                format!("✅  {} — {}", name, reason)
+            } else {
+                format!("❌  {} — {}", name, reason)
+            }
+        })
+        .collect();
+
+    eprintln!();
+    let selection = dialoguer::FuzzySelect::with_theme(
+        &dialoguer::theme::ColorfulTheme::default(),
+    )
+    .with_prompt("  Select target agent")
+    .items(&items)
+    .default(0)
+    .interact_opt()
+    .ok()
+    .flatten()?;
+
+    let (name, available, _) = &agents[selection];
+    if !*available {
+        eprintln!(
+            "\n  {} {} is not available.",
+            "⚠️ ".yellow(),
+            name.bold()
+        );
+        return None;
+    }
+
+    Some(name.clone())
+}
+
+// ─── Status Display ─────────────────────────────────────────────────────────
+
+pub fn print_snapshot(snapshot: &crate::SessionSnapshot) {
+    eprintln!();
+    let term_width = Term::stdout().size().1 as usize;
+    let width = term_width.min(72).max(40);
+    eprintln!("  {}", "═".repeat(width).cyan());
+    eprintln!(
+        "  {}  {}",
+        "📋".to_string(),
+        "Session Snapshot".bold().cyan()
+    );
+    eprintln!("  {}", "═".repeat(width).cyan());
+
+    // Project + time
+    eprintln!();
+    eprintln!("  {}  {}", "📁", snapshot.project_dir.dimmed());
+    eprintln!("  {}  {}", "🕐", snapshot.timestamp.dimmed());
+
+    // Current task
+    print_section("🎯", "Current Task");
+    eprintln!("  {}", snapshot.current_task);
+
+    // Todos
+    if !snapshot.todos.is_empty() {
+        print_section("📝", "Progress");
+        for t in &snapshot.todos {
+            let (icon, style) = match t.status.as_str() {
+                "completed" => ("✅", t.content.dimmed().to_string()),
+                "in_progress" => ("🔄", t.content.yellow().bold().to_string()),
+                _ => ("⏳", t.content.normal().to_string()),
+            };
+            eprintln!("  {icon}  {style}");
+        }
+    }
+
+    // Last error
+    if let Some(ref err) = snapshot.last_error {
+        print_section("🚨", "Last Error");
+        for line in err.lines().take(5) {
+            eprintln!("  {}", line.red());
+        }
+    }
+
+    // Decisions
+    if !snapshot.decisions.is_empty() {
+        print_section("💡", "Key Decisions");
+        for d in &snapshot.decisions {
+            eprintln!("  • {}", d.dimmed());
+        }
+    }
+
+    // Git
+    if let Some(ref git) = snapshot.git_state {
+        print_section("🔀", "Git State");
+        eprintln!("  Branch: {}", git.branch.green());
+        eprintln!("  {}", git.status_summary);
+        if !git.recent_commits.is_empty() {
+            eprintln!();
+            for c in git.recent_commits.iter().take(3) {
+                eprintln!("  {}", c.dimmed());
+            }
+        }
+    }
+
+    // Changed files
+    if !snapshot.recent_files.is_empty() {
+        print_section("📄", &format!("Changed Files ({})", snapshot.recent_files.len()));
+        for f in snapshot.recent_files.iter().take(10) {
+            eprintln!("  {f}");
+        }
+    }
+
+    // Conversation
+    if !snapshot.conversation.is_empty() {
+        print_section(
+            "💬",
+            &format!("Conversation ({} turns)", snapshot.conversation.len()),
+        );
+        let start = snapshot.conversation.len().saturating_sub(10);
+        for turn in &snapshot.conversation[start..] {
+            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()),
+                "tool_result" => ("📤 OUT ", turn.content.dimmed().to_string()),
+                _ => ("   ", turn.content.normal().to_string()),
+            };
+            let short = if turn.content.len() > 90 {
+                let mut end = 85;
+                while end > 0 && !turn.content.is_char_boundary(end) { end -= 1; }
+                format!("{}…", &turn.content[..end])
+            } else {
+                turn.content.clone()
+            };
+            let styled = match turn.role.as_str() {
+                "user" => short.normal().to_string(),
+                "assistant" => short.cyan().to_string(),
+                "assistant_tool" => short.dimmed().to_string(),
+                "tool_result" => short.dimmed().to_string(),
+                _ => short,
+            };
+            eprintln!("  {} {}", prefix.dimmed(), styled);
+        }
+    }
+
+    eprintln!();
+    eprintln!("  {}", "═".repeat(width).cyan());
+}
+
+// ─── Agents Display ─────────────────────────────────────────────────────────
+
+pub fn print_agents(
+    priority: &[String],
+    statuses: &[crate::AgentStatus],
+) {
+    eprintln!();
+    let term_width = Term::stdout().size().1 as usize;
+    let width = term_width.min(72).max(40);
+    eprintln!("  {}", "═".repeat(width).cyan());
+    eprintln!("  {}  {}", "🤖", "Available Agents".bold().cyan());
+    eprintln!("  {}", "═".repeat(width).cyan());
+    eprintln!();
+    eprintln!(
+        "  Priority: {}",
+        priority
+            .iter()
+            .map(|s| s.as_str())
+            .collect::<Vec<_>>()
+            .join(" → ")
+            .dimmed()
+    );
+    eprintln!();
+
+    for s in statuses {
+        if s.available {
+            eprintln!(
+                "  {}  {:<12} {}",
+                "✅",
+                s.name.green().bold(),
+                s.reason.dimmed()
+            );
+            if let Some(ref v) = s.version {
+                eprintln!("  {}  {:<12} {}", " ", "", format!("v{v}").dimmed());
+            }
+        } else {
+            eprintln!(
+                "  {}  {:<12} {}",
+                "❌",
+                s.name.dimmed(),
+                s.reason.dimmed()
+            );
+        }
+    }
+
+    let available = statuses.iter().filter(|s| s.available).count();
+    eprintln!();
+    if available == 0 {
+        eprintln!(
+            "  {} {}",
+            "⚠️ ",
+            "No agents available. Run 'relay init' to configure.".yellow()
+        );
+    } else {
+        eprintln!(
+            "  {} {} agent{} ready for handoff",
+            "🚀",
+            available.to_string().green().bold(),
+            if available == 1 { "" } else { "s" }
+        );
+    }
+    eprintln!();
+}
+
+// ─── Handoff Result ─────────────────────────────────────────────────────────
+
+pub fn print_handoff_success(agent: &str, file: &str) {
+    eprintln!();
+    eprintln!(
+        "  {} {}",
+        "✅",
+        format!("Handed off to {agent}").green().bold()
+    );
+    eprintln!("  📄 {}", file.dimmed());
+    eprintln!();
+}
+
+pub fn print_handoff_fail(message: &str, file: &str) {
+    eprintln!();
+    eprintln!("  {} {}", "❌", message.red());
+    eprintln!();
+    eprintln!("  💡 Context saved — copy-paste into any AI:");
+    eprintln!("     {}", file.cyan());
+    eprintln!();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masyv/relay",
-  "version": "0.3.0",
+  "version": "0.5.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",