Ravi

amux + Ravi

amux + Ravi

amux is a terminal UI for running multiple AI coding agents in parallel across isolated git worktrees. Each agent gets its own tmux session, its own branch, and its own workspace directory — no shared state, no collisions.

Ravi is the identity layer that gives each of those agents a real email address, phone number, and credentials vault. Together, they let you run fully autonomous agent pipelines that can register for services, pass verification, and operate in the world — without any human in the loop.

The Problem

When you run multiple coding agents in parallel, they all share the same environment: the same API keys, the same email address, the same identity. That creates three failure modes:

  1. Credential conflicts — agents racing to use the same API token hit rate limits or get flagged for unusual activity.
  2. Signup walls — agents that need to register for a service (Stripe, SendGrid, a SaaS API) can’t do it autonomously because they share credentials with your real account.
  3. Verification loops — agents that hit 2FA or email confirmation just stall. There’s no way to intercept the OTP without a human.

Ravi solves all three. Each agent gets its own provisioned identity — isolated, auditable, and headless-automation-ready.

How They Fit Together

amux’s workspace model is the natural integration point. When a new workspace is created, it runs setup commands defined in .amux/workspaces.json — typically things like npm install or copying environment files. That setup hook is where Ravi’s credential injection happens.

The result: every parallel agent starts with fresh, scoped credentials sourced from Ravi’s vault, not from your .env file.

1. Credential Injection at Workspace Setup

amux copies .env.local from the root workspace into each new worktree. You can make that file authoritative by sourcing it from Ravi at setup time:

// .amux/workspaces.json
{
  "setup": [
    "ravi secrets export > .env.local"
  ]
}

Every workspace gets the same set of secrets — API keys, tokens, whatever the agent needs — without anyone hardcoding credentials or managing multiple secret files.

2. Per-Agent Ravi Identities for Service Signups

When a coding agent is tasked with “add Stripe integration and test it end-to-end,” it needs a real Stripe account to actually test against. With Ravi, you can provision a unique identity for each amux workspace — email, phone, credentials vault — so the agent can register, verify, and operate autonomously without touching your real accounts.

# Provision a new Ravi identity for workspace ws-3
ravi identity create "Agent Workspace 3"

# Export that identity's credentials into the workspace
ravi secrets get STRIPE_TEST_KEY --identity ws3 > .env.local

Each agent runs in a fully isolated identity context. No cross-contamination between workspaces.

3. SMS/OTP Interception Mid-Task

Agents frequently hit 2FA walls during testing flows — registering a new account, logging into a service, triggering a security prompt. amux keeps the agent session alive in a persistent tmux pane. Ravi’s phone number can receive the SMS OTP and surface it back to the agent via the headless CLI:

# Agent calls this when it needs to wait for an OTP
ravi sms receive --timeout 60s --extract-otp

The verification loop closes without a human. The task continues.

4. The Headless JSON CLI Composes Cleanly

amux’s --json flag makes it composable with any orchestrator:

amux --json agent send <session> --text "implement feature X" --enter --async
amux --json agent job wait <job_id> --timeout 30s

An OpenClaw skill or any script can drive multiple amux agents programmatically, inject Ravi credentials at the right moment, and poll for completion — all without a GUI.

Complete Setup Guide

Prerequisites

  • tmux ≥ 3.2
  • amux installed (go install github.com/andyrewlee/amux@latest)
  • Ravi CLI installed and authenticated
  • A git repository to work in

Step 1: Initialize amux

cd /your/repo
amux init

This creates .amux/workspaces.json. Edit it to add Ravi credential injection:

{
  "setup": [
    "npm install",
    "ravi secrets export > .env.local"
  ]
}

Step 2: Configure Ravi Secrets

Store the credentials your agents will need in Ravi’s vault:

ravi secrets set OPENAI_API_KEY sk-...
ravi secrets set STRIPE_SECRET_KEY sk_test_...
ravi secrets set SENDGRID_API_KEY SG....

Step 3: Launch Parallel Agents

Open the amux TUI and create workspaces — each workspace will automatically run the Ravi export as part of setup:

amux

Or drive it headlessly:

# Create a workspace and start an agent
amux --json workspace create --name "feature-auth"
amux --json agent send feature-auth --text "Implement OAuth2 login with Google. Use the credentials in .env.local." --enter

Step 4: Monitor and Collect

# Wait for the agent to finish
amux --json agent job wait <job_id>

# Review the diff
git -C .amux/workspaces/feature-auth diff main

The ravi-amux-launcher Pattern

For fully automated pipelines, a launcher script wires everything together:

#!/bin/bash
# ravi-amux-launcher.sh
TASK="$1"
WORKSPACE="task-$(date +%s)"

# 1. Inject Ravi secrets into workspace env
ravi secrets export > .env.local

# 2. Create workspace (setup script runs automatically)
amux --json workspace create --name "$WORKSPACE"

# 3. Send the task
JOB=$(amux --json agent send "$WORKSPACE" --text "$TASK" --enter --async | jq -r '.job_id')

# 4. Wait for completion
amux --json agent job wait "$JOB" --timeout 300s

# 5. Surface the result
git -C ".amux/workspaces/$WORKSPACE" diff main

Call it with any task and the agent runs autonomously — credentials sourced from Ravi, verification handled by Ravi, no human required.

Why Ravi Adds Value

Without RaviWith Ravi
All agents share the same API keysEach agent gets scoped, isolated credentials
Signup walls block autonomous agentsAgents register with real Ravi-provisioned identities
2FA stops the pipelineRavi phone receives OTP, surfaces it headlessly
Credentials hardcoded in .envSecrets managed in Ravi vault, injected at setup
No audit trail per agentEvery identity action is logged against a specific agent identity

amux treats terminal isolation as a first-class concern. Ravi treats identity isolation the same way. They compose naturally.

Resources