rdv

Remote Dev CLI (rdv)

You are running inside a Remote Dev terminal session. Use the rdv CLI to interact with the system.

All commands output JSON by default. Add --human for human-readable tables. Use rdv --help or rdv <command> --help for full usage details.

---

1. Getting Started

Discover your session context first:

rdv context                    # Show session ID, folder, project path, tmux name
rdv status --human             # System dashboard: sessions, tasks, deploy info

Key environment variables (set automatically in agent sessions):

• RDV_SESSION_ID -- Your session UUID
• RDV_TERMINAL_PORT -- Terminal server port (dev, default 6002)
• RDV_API_PORT -- API server port (default 6001)
• RDV_API_KEY -- Bearer token for API authentication

---

2. Session Management

rdv session list                                          # List all sessions
rdv session create --name "my-session" --folder-id <id>   # Create a new session
rdv session create --working-dir /path --type agent       # Create with type
rdv session exec <session-id> "echo hello"                # Execute command (fire-and-forget)
rdv session suspend <session-id>                          # Suspend a session
rdv session resume <session-id>                           # Resume a suspended session
rdv session close <session-id>                            # Close (delete) a session
rdv session git-status <session-id>                       # Get git status for session

Session Naming

IMPORTANT: Set a descriptive title for your session as one of your first actions so peers can identify your work:

rdv session title fix-auth-token-refresh
rdv session title implement-payment-webhook
rdv session title debug-memory-leak-api

Rules:

• 3-5 words, hyphen-separated (kebab-case)
• Lowercase letters and hyphens only
• Describe the work, not the agent (e.g. "add-user-pagination" not "my-session-3")
• Set this within your first few tool uses

If you don't call rdv session title, the system auto-generates a title from your first message — but prefer setting it explicitly for clarity.

---

3. Agent & Team Orchestration

Agent Sessions

IMPORTANT: Always use worktrees when spawning subagents or working in agent teams. Worktrees provide branch isolation that prevents merge conflicts between parallel agents working on the same codebase.

rdv agent start <folder-id>                        # Start agent in folder (uses folder's provider)
rdv agent start <folder-id> --worktree feature/x   # Start agent with worktree isolation
rdv agent list                                     # List active agent sessions
rdv agent stop <session-id>                        # Stop (suspend) an agent session

Team Orchestration

Launch and manage coordinated multi-agent sessions:

# Launch multiple agent sessions
rdv teams launch --folder-id <id> --count 3 --provider claude --name-prefix "worker"

# List sessions grouped by parent
rdv teams list --parent-id <parent-session-id>

# Wait for all child sessions to complete (polls every 2s)
rdv teams wait <parent-session-id> --timeout 300

# Broadcast text to all child sessions
rdv teams broadcast <parent-session-id> "Please wrap up your current task"

---

4. Worktree Management

Create isolated git worktrees for branch work:

rdv worktree create --repo /path/to/repo --branch feature/my-branch
rdv worktree list --repo /path/to/repo
rdv worktree remove --worktree-path /path/to/wt --project-path /path/to/repo [--force]

# Full cleanup: verify merge, remove worktree, delete branches, close session
# Works even when CWD is inside the worktree. Requires RDV_SESSION_ID.
rdv worktree cleanup [--force]

Cleanup Flow

When done with a worktree (commits pushed, PR merged):

1. Verifies branch is merged into main/master (use --force to skip)
2. Removes worktree directory (server-side, CWD-safe)
3. Deletes local and remote branch
4. Closes the tmux session

rdv worktree cleanup           # Safe cleanup (checks merge status)
rdv worktree cleanup --force   # Force cleanup (skip merge check)

---

5. Peer Communication

Messages arrive automatically via push notifications and the PreToolUse hook — no polling needed.

Receiving messages: Peer messages, channel messages, and @mentions are pushed to you in real-time. Direct messages and @mentions are prioritized. You'll see them between tool calls or as MCP push notifications.

Responding (MCP tools — inline, no shell needed):

• send_message — Reply to a peer (session ID from hook output/notification). Omit to_session_id to broadcast.
• send_to_channel — Post to a channel. Supports GFM markdown and threading via reply_to.
• set_summary — Update your work status visible to peers.

Discovery and history (rdv CLI):

rdv peer list                                    # List peer agents in same folder
rdv peer send "I finished the API layer" --to <session-id>   # Direct message
rdv peer send "Starting integration tests"       # Broadcast to all peers
rdv peer messages                                # Check for new messages
rdv peer summary "Working on auth module"        # Set work summary visible to peers
rdv channel list                                 # List channels in project folder
rdv channel messages general                     # Read channel messages
rdv channel send general "Rebased on main"       # Send to channel
rdv channel create auth-refactor                 # Create a new channel

---

6. Browser Automation

Control headless browser sessions:

rdv browser navigate <session-id> https://example.com
rdv browser screenshot <session-id> --output ./screenshot.png
rdv browser snapshot <session-id>                     # Accessibility snapshot
rdv browser click <session-id> 100 200                # Click at (x, y)
rdv browser type <session-id> "hello" --selector "#input"
rdv browser evaluate <session-id> "document.title"
rdv browser back <session-id>
rdv browser forward <session-id>

---

7. Terminal I/O

Send Text & Keystrokes

rdv send text <session-id> "ls -la"              # Send text to session PTY
rdv send key <session-id> Enter                   # Send keystroke (Enter, C-c, Tab, Escape, Up, Down, etc.)
rdv send key <session-id> C-c                     # Send Ctrl+C

Capture Screen

rdv screen <session-id>                           # Capture terminal screen content (JSON)
rdv screen <session-id> --human                   # Print screen content as plain text

tmux Compatibility Layer

Drop-in replacement for common tmux commands, routing through rdv when targeting rdv sessions:

rdv tmux send-keys -t <target> "text" Enter       # Send keys (routes via rdv for rdv-* targets)
rdv tmux capture-pane -t <target> -p               # Capture pane output
rdv tmux <any-other-command>                       # Passes through to real tmux

---

8. Session UI (Status, Progress, Log)

Status Indicators

Set custom status badges on sessions visible in the UI:

rdv set-status <session-id> <key> <value> [--icon bolt.fill] [--color "#4C8DFF"]
rdv clear-status <session-id> <key>

Progress Bar

rdv set-progress <session-id> 0.5 --label "Building..."   # Set progress (0.0 to 1.0)
rdv clear-progress <session-id>                            # Clear progress bar

Session Log

Write structured log entries for a session:

rdv log <session-id> "Deployment complete" --level info --source deploy
rdv log <session-id> "Build failed" --level error

Log levels: debug, info (default), warn, error.

---

9. Notifications

rdv notification list --unread                    # List unread notifications
rdv notification list --limit 10                  # List recent (max 10)
rdv notification read <id1> <id2>                 # Mark specific as read
rdv notification read --all                       # Mark all as read
rdv notification delete <id1> <id2>               # Delete specific
rdv notification delete --all                     # Delete all

---

10. System & Folders

Folders

rdv folder list                                   # List all folders (with IDs)

System Updates

rdv system update                                 # Show update status
rdv system update check                           # Check GitHub for new release
rdv system update apply                           # Download and apply update (restarts service)

---

11. Lifecycle Hooks

Commands designed for Claude Code hook integration (usually called automatically):

# Individual hook handlers
rdv hook pre-tool-use        # Report "running", check peer messages, auto-title, git identity guard
rdv hook post-tool-use       # Sync task/todo data from stdin
rdv hook pre-compact         # Report "compacting" status
rdv hook notification        # Report "waiting" status
rdv hook stop                # Report idle, check tasks, create notification
rdv hook notify <event>      # Send notification (e.g. task_complete, error)
rdv hook session-end         # Report "ended" status
rdv hook validate            # Validate hook connectivity + auto-repair

# Unified handler (alternative to individual commands above)
rdv hook claude <event>      # Events: active, stop, notification, compacting,
                             #         post-tool-use, session-end
                             # Aliases: session-start, idle, notify,
                             #          prompt-submit, task-sync

---

12. Common Workflows

Discover context and start working

rdv context                    # Learn your session info

Start a parallel agent for a subtask

rdv agent start <folder-id> --worktree feature/subtask

Orchestrate a team of agents

rdv teams launch --folder-id <id> --count 3 --provider claude --name-prefix "worker"
rdv teams wait <my-session-id> --timeout 600
rdv teams broadcast <my-session-id> "Time to wrap up"

Create isolated work with worktrees

rdv worktree create --repo . --branch feature/experiment
rdv session create --name "experiment" --working-dir /path/to/worktree

Complete worktree work and clean up

git add . && git commit -m "feat: my changes"
git push origin feature/my-branch
gh pr create --fill && gh pr merge --auto
rdv worktree cleanup              # Remove worktree, branches, close session

Coordinate with peer agents

rdv peer list                                    # See who else is working
rdv peer send "I'm done with the API" --to <id> # Notify a specific peer
rdv peer send "Starting deploy"                  # Broadcast to all

Monitor and interact with other sessions

rdv screen <session-id> --human          # See what another session is doing
rdv send text <session-id> "ls -la"      # Send a command to it
rdv send key <session-id> Enter          # Press Enter

6. Coordinate with peer agents

rdv session title implement-auth-flow     # Name your session first
rdv peer list                             # See what other agents are working on
rdv peer send --broadcast "rebased on main, ready for integration"
rdv peer summary "finishing OAuth implementation, will push to main soon"