March 9, 2026 🤖 AI-written, human-guided

CrewHub v0.20.0: Agent Handoff — Continue Your Sessions in Terminal, VS Code & Beyond

Status: DRAFT — This post is updated as the feature develops on the feature/agent-handoff branch.

The big idea behind v0.20.0 is simple: stop rebuilding what native tools already do well. CrewHub is great at monitoring and orchestrating agents. Terminals, Claude Desktop, and VS Code are great at interacting with them. Agent Handoff connects the two.

🤔 The Problem with Zen Mode

Zen Mode was CrewHub’s full-screen agent interaction UI: a tmux-inspired layout with chat panels, session switching, keyboard shortcuts, and custom themes (Tokyo Night, anyone?). It worked, but it was fighting a losing battle.

Claude Desktop now has Claude Code built in. Codex has its own terminal UI. iTerm2 and Warp are purpose-built for exactly this kind of interaction. Building a custom chat interface inside a 3D dashboard meant duplicating effort, and the native tools kept getting better faster than we could keep up.

So instead of maintaining a parallel universe, v0.20.0 makes CrewHub the orchestration layer that hands off to whatever tool you already use.

⚡ How It Works

Every session card and detail panel now has a “Continue in…” split button. Click it, and CrewHub:

Resolves your session key to a Claude CLI session ID
Builds the right claude --resume <session-id> command
Opens your terminal with the command ready to run

The dropdown auto-detects what’s installed on your machine:

Target	How it works
iTerm2	Opens a new window via AppleScript (`create window with default profile`)
Warp	Same AppleScript approach, targets Warp instead
Terminal.app	macOS default fallback via `do script`
VS Code Terminal	Opens the folder, toggles the integrated terminal, types the command
Copy Command	Universal clipboard fallback via `pbcopy`, always available

If the primary target fails (accessibility permissions not granted, terminal not responding), CrewHub automatically falls back to copying the command to your clipboard and shows a toast notification so you know what happened.

🔧 What’s Built So Far

Backend: Handoff Service

Two new API endpoints power the feature:

GET /api/handoff/targets — Auto-detects available terminals and tools on the host machine. Checks for iTerm2, Warp, Terminal.app, and the code CLI. Results are cached on the frontend after the first call.

POST /api/handoff/sessions/{session_key} — Executes the handoff. Resolves the session key, builds the CLI command, and either opens a terminal window via AppleScript or copies to clipboard.

The service handles three session key formats:

claude:<uuid>     → claude --resume <uuid>
cc:<agent-id>     → looks up mapped session ID from _agent_sessions, then resumes
agent:main:main   → opens a fresh claude session in the project directory

Under the hood, terminal handoff runs osascript with AppleScript tailored to each app. iTerm2 gets its own script that creates a window with the default profile and writes the command directly. Terminal.app and Warp share a simpler do script approach. VS Code handoff opens the folder, simulates `Ctrl+“ to toggle the integrated terminal, then types the command.

The clipboard fallback uses pbcopy on the server side, with a browser-side navigator.clipboard.writeText fallback in the frontend if that fails.

Frontend: HandoffButton Component

A HandoffButton split button renders on session cards in the main dashboard and the Zen Mode detail panel header:

Primary click triggers the first detected target (usually iTerm2)
Dropdown chevron reveals all available targets
Loading spinner during execution, green checkmark on success
Graceful fallback to clipboard if the primary target errors out
Targets are fetched once on mount via useHandoffTargets hook and cached

The component is compact (size="sm" by default) and stays out of the way until you need it.

Zen Mode Deprecation

Zen Mode is still accessible via ?mode=zen in the URL for a transition period, but the on-ramps are gone:

Removed from the 3D world ActionBar (no more Zen button in the bottom bar)
Removed the auto-launch toggle from Settings → Behavior
Removed the Ctrl+Shift+Z keyboard shortcut
Settings now shows a deprecation notice instead of the old toggle
Added a deprecation banner inside Zen Mode pointing to the new handoff buttons
Added a subtle entrance animation (fade-in + scale) and a minimal ”⬡ zen” indicator badge so the mode feels polished during its sunset period
Fixed text wrapping in the settings deprecation notice
Full removal planned for v0.21.0

🧠 Technical Decisions

Why AppleScript instead of open -a? We need to both launch the terminal and run a specific command in it. AppleScript gives us control over window creation and command execution in a single step. The trade-off is macOS-only support for now.

Why resolve session keys server-side? The backend already tracks session mappings (Claude Code UUIDs, CC agent IDs, OpenClaw sessions). Keeping resolution server-side means the frontend just passes a session key and gets back a ready-to-run command.

Why deprecate gradually? Some users may have workflows built around Zen Mode’s URL parameters. The ?mode=zen escape hatch gives them time to migrate while we collect feedback on the handoff approach.

What happens to session tracking after handoff? When Claude Code resumes a session via --resume, it actually creates a new session ID (the original JSONL is read for context, but new messages go to a new file). CrewHub’s file watcher picks up the new session automatically, so monitoring continues seamlessly.

🔮 Coming Next

The current implementation covers the core handoff flow on macOS. Still on the roadmap:

Codex (OpenAI) support — Detect and hand off to Codex when installed
Claude Desktop integration — Deep link or launch Claude Desktop with session context
Linux/Windows support — Replace AppleScript with platform-appropriate launchers (xdg, PowerShell)
Handoff analytics — Track which targets are used most to inform UX decisions

🎯 Wrapping Up

v0.20.0 is a philosophical shift for CrewHub. Instead of trying to be everything, it focuses on being the best orchestration and monitoring layer, and gets out of the way when you need to interact directly with your agents.

Zen Mode served its purpose. Now it’s time for something better.

Last updated: March 10, 2026 08:45 CET. Core feature merged to develop, plan marked as implemented. Follow the progress or come chat on Discord.

← Back to Blog