Ravi

cmux

Overview

cmux is a native macOS terminal built in Swift on top of libghostty — the same rendering engine as the Ghostty terminal. It is designed for developers running multiple AI coding agents (Claude Code, Codex, OpenCode) in parallel, with a vertical tab sidebar that tracks git branch, PR status, listening ports, and agent notifications per session. When an agent needs attention, its tab lights up and Cmd+Shift+U jumps you straight to it.

cmux also ships a scriptable browser ported from Vercel’s agent-browser, giving agents the ability to click, fill forms, snapshot the accessibility tree, and evaluate JavaScript inside a dev server — all from within the terminal layout.

The moment those agents start doing real work, they hit auth walls: OAuth flows, email verifications, SMS OTPs, credential vaults. That’s where Ravi fits. Ravi gives each cmux workspace a real, isolated identity — a provisioned email address, phone number, and E2E encrypted secrets store — without any manual setup.

The Problem cmux Solves Without Ravi

cmux makes it easy to run eight agents at once. But without a structured identity layer, all eight agents share whatever credentials the developer has manually configured on that machine. There’s no per-workspace isolation, credentials break the moment the project moves to another machine or a CI environment, and when an agent submits an auth form through the browser pane, there’s no automated path to retrieve the OTP that comes back.

What Ravi Adds

1. Credential injection at workspace launch

Instead of scattering .env files across project directories, each cmux workspace can pull credentials from Ravi’s vault at init time. A workspace setup hook that runs ravi passwords get and ravi secrets get feeds the right credentials into the right agent session. Credentials are E2E encrypted on the server and accessible anywhere the Ravi CLI is installed — no OS keyring dependency, no machine lock-in.

2. Per-workspace email identity

Parallel agents often need distinct identities. One workspace might be testing staging webhooks, another handling a production OAuth flow. Ravi’s provisioned email addresses give each cmux workspace a real, isolated inbox. The agent spins up, gets a unique address, registers with the target service, and receives the confirmation without cross-contaminating other agent sessions.

3. 2FA interception during browser automation (strongest fit)

cmux’s browser API lets agents submit forms and interact with auth flows. Those flows frequently end with an SMS or email OTP that lands nowhere useful. Ravi closes that loop: the agent submits the login form using the cmux browser pane, Ravi’s phone number catches the SMS OTP, ravi sms inbox retrieves it, and the agent submits the code — fully autonomous, no human in the loop.

4. Isolated email callbacks per agent

CI runs, deployment webhooks, and error alerts need somewhere to land. With a dedicated Ravi email address per cmux workspace, inbound mail routes to the right agent automatically. No shared inbox, no missed alerts from other sessions.

Setup

1. Install prerequisites

# Install cmux
brew install --cask cmux

# Install Ravi CLI
brew install ravi-hq/tap/ravi
ravi auth login

2. Create a Ravi identity for the workspace

# One identity per project (or per workspace)
ravi identity create "cmux-myproject"

# Check provisioned email + phone
ravi get email --json
# → { "email": "cmux-myproject-a1b2c3@raviapp.com", "phone": "+15551234567" }

3. Inject identity into the workspace environment

Add a workspace init hook in your cmux config (e.g., ~/.config/cmux/config.toml):

[workspace.hooks]
on_create = "eval $(ravi env --identity cmux-myproject --export)"

This writes RAVI_EMAIL, RAVI_PHONE, and RAVI_IDENTITY into the agent’s shell environment at session start. Agents can read these directly — or you can source them in a project .envrc managed by direnv.

4. Retrieve credentials from the Ravi vault

# Store credentials once
ravi secrets set GITHUB_TOKEN ghp_...
ravi passwords create --domain github.com --username mybot --password $(cat /dev/stdin)

# Agents retrieve at runtime (no plaintext config files)
GITHUB_TOKEN=$(ravi secrets get GITHUB_TOKEN --value)

5. Automate 2FA during browser sessions

When a cmux agent submits an auth form through the browser pane and an OTP arrives:

# Poll for the SMS OTP (runs inside the agent's shell)
ravi sms inbox --unread --json | jq -r '.[0].body' | grep -oE '[0-9]{6}'

# Or poll for email OTP
ravi inbox email --unread --json | jq -r '.[0].preview'

The OTP can be fed directly back into the browser via the cmux socket API:

OTP=$(ravi sms inbox --unread --json | jq -r '.[0].body' | grep -oE '[0-9]{6}')
cmux browser type --selector "#otp-input" --text "$OTP"
cmux browser press --key Enter

Example: Workspace Init Flow with Ravi

A fully automated workspace setup:

#!/bin/bash
# cmux workspace init script

# 1. Pull identity for this project
IDENTITY="cmux-$(basename $PWD)"
ravi identity create "$IDENTITY" 2>/dev/null || true

# 2. Export identity info into the session
export RAVI_EMAIL=$(ravi get email --json | jq -r .email)
export RAVI_PHONE=$(ravi get phone --json | jq -r .phone)

# 3. Pull service credentials from vault
export OPENAI_API_KEY=$(ravi secrets get OPENAI_API_KEY --value)
export GITHUB_TOKEN=$(ravi secrets get GITHUB_TOKEN --value)

echo "Workspace ready. Agent identity: $RAVI_EMAIL / $RAVI_PHONE"

A teammate or orchestrating agent can then assign work by emailing cmux-myproject-a1b2c3@raviapp.com directly — no need to know which machine the session is running on.

Why This Matters for Parallel Agent Development

cmux treats isolated, concurrent agent sessions as a first-class primitive. The gap it leaves is that all those sessions still share a single developer’s identity when they hit the real world — the same email, the same phone, the same credential files.

Ravi makes each session a real endpoint: its own email, its own phone number, its own credential scope. The agent fleet becomes a network of addressable identities rather than a collection of processes running under one person’s account. OTPs route correctly, webhooks land where they should, and credentials never leak across workspaces.

cmux provides the session infrastructure. Ravi provides the identity layer those sessions need the moment they touch anything outside localhost.

Next Steps