Ravi

Integrate Any Tool with Ravi

The universal pattern

Every Ravi integration follows the same four steps, regardless of the tool:

  1. Provision an Identity — ravi identity create --name "my-agent"
  2. Scope commands — use RAVI_CONFIG_DIR or .ravi/config.json per agent
  3. Use the Identity — receive OTPs, poll email/SMS, store credentials
  4. Clean up — delete ephemeral identities when the task is done

This works with any tool that runs agents in terminals, worktrees, containers, or isolated directories.

Quick setup

# 1. Create an identity for your agent
ravi identity create --name "my-agent"

# 2. Scope all commands to this identity
ravi identity use my-agent

# 3. Store a credential
ravi secrets set GITHUB_TOKEN ghp_abc123

# 4. Retrieve it
ravi secrets get GITHUB_TOKEN

Parallel agents

Never call ravi identity use from concurrent processes — it writes shared state. Instead, isolate each agent:

Option A: RAVI_CONFIG_DIR (recommended)

# Set up isolated config per agent
mkdir -p /tmp/ravi-agent-1
echo '{"identity_uuid":"<uuid>"}' > /tmp/ravi-agent-1/config.json

# All commands scoped to agent-1
RAVI_CONFIG_DIR=/tmp/ravi-agent-1 ravi inbox email --unread

Option B: Per-worktree .ravi/config.json

project/
├── worktrees/
│   ├── agent-1/.ravi/config.json   ← auto-scoped
│   ├── agent-2/.ravi/config.json   ← auto-scoped

Any ravi command run from inside agent-1/ automatically uses agent-1's identity.

REST API (no CLI needed)

Use identity API keys (ravi_id_) for direct HTTP access. The key carries identity scope — no extra headers.

curl https://ravi.id/api/email-messages/ \
  -H "Authorization: Bearer ravi_id_your_key_here"

See API Endpoints for the full reference.

Polling for OTPs

# Poll SMS for a verification code
for i in $(seq 1 15); do
  CODE=$(ravi inbox sms --unread 2>/dev/null | jq -r '.[0].preview // empty')
  [ -n "$CODE" ] && echo "OTP: $CODE" && break
  sleep 2
done

Tested with

Ravi works with any tool that can run shell commands or make HTTP calls. It has been tested with:

Category Tools
Terminal multiplexers amux, cmux, dmux, mux, tmux
Worktree orchestrators Aizen, Claude Squad, Jean, vibe-tree
Agent frameworks Subtask, Aperant, Symphony, HumanLayer, Ariana
Coding agents Claude Code, Supacode, 1Code, T3Code, VibeCode
Task managers vibe-kanban, OpenKanban, Codexmonitor
Other Dorothy, GhostClaw, Lemon, Lettabot, BabyAGI3, Hermes

The integration pattern is the same for all of them. If your tool can call ravi or make HTTP requests, it works with Ravi.

Next steps