Skip to main content

Remi

Monitor, manage, and respond to Claude Code sessions from the CLI, your phone, or a browser.

Overview​

Remi wraps Claude Code and adds remote session management over WebSocket. List sessions across machines, attach from another terminal, browse recent projects, create sessions on remote daemons, and respond to questions from your phone.

# Start Claude with remote monitoring
remi my-project

# Start with auto-approve: fewer prompts, more flow
remi --auto-approve

# List sessions on a remote machine
remi ls --host 100.79.39.98

# Attach to a running session
remi attach

# Browse recent project directories
remi recent

# Create a session on a remote daemon
remi new --host 100.79.39.98 --recent

# Show your connection code for phone/browser access
remi code

Auto-Approve — stop answering routine prompts​

Remi can handle the "Allow this tool?" prompts for you. Turn on remi --auto-approve and routine actions proceed without interrupting your flow; only the ones that actually need your judgment reach your phone.

You stay in charge:

  • Your model, your rules — runs fully locally by default, on the Yooz Engine that remi downloads and supervises itself (Apple Silicon macOS today, Linux in progress), or via any OpenAI-compatible endpoint (OpenRouter, self-hosted, etc.). No calls leave your machine unless you choose a hosted provider.
  • Your allow and deny lists, plus built-in read/VCS/test-command groups on by default — evaluated before any model call.
  • Your instructions — a few sentences of plain-English guidance the model follows, layered on top of a conservative default policy.
  • Human-in-the-loop when it matters — anything uncertain escalates to you as a normal phone notification. Background subagent permissions are decided by whether they ever render on screen, not by the model, so a background agent never spends a GPU call deciding something no one will see.

See the Auto-Approve guide.

Hub Mode — one supervisor, many sessions​

remi start (or remi serve in the foreground) runs a session-less hub: a single always-on process that lists every session running on the machine and spawns new ones on request, without ever starting Claude Code itself. It is the mode behind the macOS menu-bar app and the "new session" flow in the phone/web apps.

See the Hub Mode guide.

Why Remi?​

Works From Anywhere​

Connect directly over your local network, through Tailscale or a VPN, or remotely through a relay code. No port forwarding or firewall configuration needed for relay mode.

Privacy First​

Remi runs entirely on your machine. There is no cloud backend, no account to create, and no data stored outside your device.

Direct connections (local network, Tailscale, VPN, SSH tunnel) never touch a server at all.

Relay connections are the exception, and the detail matters. The relay forwards your traffic through a Cloudflare Worker. That traffic is end-to-end encrypted only when the daemon runs with authentication and a permanent code (remi --auth --permanent-code); in the default rotating-code mode it is not encrypted, and the Worker can see session content. Even when encrypted, the Worker still sees the room code and the timing and volume of traffic: encryption hides content, not metadata. If you want a remote connection with nothing in the middle, use Tailscale or an SSH tunnel rather than a relay code.

Authentication​

Remi supports Ed25519 mutual authentication: server and client each prove their identity with a cryptographic key exchange, with Trust-On-First-Use (TOFU) for verifying the server fingerprint the first time you connect.

It is not on by default. Enable it with remi --auth. Binding to a network address does not enable it on its own.

Architecture​

┌─────────────────────────────────────────────────────────────────┐
│                    REMI CLIENT (Phone/Browser)                   │
│  React + Capacitor (iOS/Android/Web/Desktop)                     │
│  Chat View | Session List | Notifications                        │
└──────────┬───────────────────────────────┬──────────────────────┘
           │ Direct WebSocket              │ Relay (via signaling)
           │ (LAN/Tailscale/VPN)           │ (remote, any network)
┌──────────▼───────────────────────────────▼──────────────────────┐
│                 REMI DAEMON (on dev machine)                     │
│  WebSocket :18765 | Hook Server (auto port) | RelayAdapter       │
│  Persistent code: ~/.remi/connection-code                        │
└──────────┬───────────────────────────────┬──────────────────────┘
           │ PTY (terminal)                │ HTTP hooks
┌──────────▼───────────────────────────────▼──────────────────────┐
│                      CLAUDE CODE CLI                             │
│  Posts hook events (PreToolUse, PostToolUse, Stop, etc.)         │
└─────────────────────────────────────────────────────────────────┘

Remi uses Claude Code's native hooks API for event detection. When Remi starts, it writes hook configuration to .claude/settings.local.json and runs a local HTTP server. Claude Code posts structured events (tool use, permission prompts, session start/stop) to this server, which Remi forwards to connected clients over WebSocket.

Features​

  • Auto-approve - Local (Yooz Engine) or hosted LLM handles routine permission prompts; user-defined rules, built-in read/VCS/test groups, and instructions keep you in control
  • Hub mode - A session-less supervisor (remi start / remi serve) spawns and lists session daemons on demand; back it with a LaunchAgent/systemd service for always-on access
  • Multi-writer sessions - Any attached client, phone, browser, or terminal, can send input to a session at once; no exclusive lock
  • Cross-machine CLI - List, attach, create, and kill sessions on local or remote daemons
  • Recent projects - Browse session history and start new sessions in known directories
  • Real-time monitoring - See Claude's output as it streams, with live-updating transcript messages
  • Quick responses - Tap Yes/No or type a reply from your phone, browser, or another terminal
  • Remote access - Connect from any network using a short relay code (XXXX-YYYY)
  • Authentication - Ed25519 keypairs with mutual authentication, opt-in via remi --auth
  • Multiple transports - Direct WebSocket, relay through signaling server
  • Status line - See Remi status directly in Claude Code's status bar
  • macOS menu-bar app - Native app that surfaces hub state and pending questions without a terminal
  • Service install - Run the hub as a LaunchAgent (macOS) or systemd service (Linux)

Installation​

Homebrew (macOS/Linux)​

brew install yooz-labs/tap/remi

npm​

npm install -g @yooz-labs/remi

From Source​

git clone https://github.com/yooz-labs/remi.git
cd remi
bun install
bun run build
bun link

Next Steps​

  • Quick Start - Get running in 5 minutes
  • Commands - Full command reference
  • Guides - Connection, authentication, and usage guides