rpcc - Remote Procedure Claude Code

Interactive subagent management for Claude Code

rpcc is an MCP server that extends Claude Code with the ability to spawn, monitor, and interact with isolated Claude Code subagents running in separate tmux sessions. This enables true parallel execution, context isolation, and human-in-the-loop intervention for complex tasks.

Problem Statement

Claude Code's builtin subagents are useful to managing context and performing multiple straightforward tasks in parallel. But they are black boxes that take in input and return output with no way of course correcting. This is a simple tool to overcome it by letting you manage subagents interactively within your terminal.

Key Features

• 🔄 Spawn Isolated Subagents: Launch Claude subagents in separate tmux sessions with custom system prompts
• 👁️ Real-Time Monitoring: Interactive TUI dashboard to view all running subagents and their progress
• 🎯 Direct Interaction: Attach to any subagent's tmux session for hands-on debugging and course correction
• ⚡ Parallel Execution: Run multiple subagents simultaneously for independent tasks
• 📝 Session Persistence: Full conversation history and state saved in structured session directories
• 🔌 Seamless Integration: Drop-in replacement for Claude Code's built-in Task tool via MCP protocol

Quick Start

Prerequisites

• Bun runtime installed
• Claude Code CLI installed and authenticated
• tmux installed (for subagent session management)

Installation

# Clone the repository
git clone https://github.com/adagradschool/rpcc.git
cd rpcc

# Install dependencies
bun install

# Link binaries globally
bun link

Configuration

Add rpcc as an MCP server in your Claude Code configuration:

For Claude Code - Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "rpcc": {
      "command": "bunx",
      "args": ["rpcc-mcp-server"],
      "env": {}
    }
  }
}

Restart Claude Code to load the MCP server.

Usage

From Claude Code

Claude Code will automatically use rpcc tools when spawning subagents:

User: "Launch a subagent to refactor the auth module"
Claude: I'll spawn a subagent to handle this task...
[Uses mcp__rpcc__rpcc_task tool]

The main agent can:

• Launch: rpcc_task(type, prompt, description) - Spawn a new subagent
• Poll: rpcc_status(session_id) - Check status without blocking
• Wait: rpcc_wait(session_id) - Block until subagent completes and get results

Interactive Session Manager

Monitor and interact with running subagents using the TUI:

rpcc top

Keyboard Controls:

• ↑/↓ or j/k - Navigate between sessions
• Enter - Attach to selected session's tmux session (full interactive control)
• k - Kill selected session
• c - Clean up completed/failed sessions
• q - Quit

Session Management

# Clean up completed/failed sessions
rpcc clean

Session data is stored in /tmp/rpcc/sessions/<session-id>/ with:

• metadata.json - Agent type, prompt, timestamps
• status.json - Current status and progress
• conversation.jsonl - Full message history
• result.json - Final output (written on completion)
• socket - Unix domain socket for real-time attachment

How It Works

Architecture

1. MCP Server (rpcc-mcp-server) - Provides tools that Claude Code can call
2. Subagent Spawner - Creates session directories and manages subagent lifecycle
3. Subagent Server - Spawns Claude CLI in tmux, monitors output, handles completion
4. CLI Tool (rpcc) - Interactive TUI for viewing and managing sessions

Process Flow

Main Agent (Claude Code)
    ↓ calls mcp__rpcc__rpcc_task
Spawner creates session directory
    ↓ starts SubagentServer
Claude CLI spawned in tmux session
    ↓ monitoring loop every 1s
Parses tmux output for responses
    ← Human attaches via 'rpcc top' → Enter
    → Full tmux interaction
    ← Human detaches (Ctrl-B, D)
Subagent completes task
    ↓ writes result.json
Main Agent receives result

Agent Types

Subagents are configured with system prompts from the agents/ directory:

• general-purpose - Default subagent for background tasks
• statusline-setup - Specialized for Claude Code statusline configuration
• output-style-setup - Specialized for output style configuration

Adding custom agents:

1. Create agents/<type>.txt with your system prompt
2. Add type to AgentType in src/types.ts
3. Update MCP tool enum in src/mcp-server.ts

Data Flow

Main Agent (Terminal 1)
    ↓ launch
Subagent Process (background)
    ← socket connection
Human (Terminal 2: rpcc top)
    → send messages
    ← receive updates
    → detach
Subagent Process (continues)
    ↓ completion
Main Agent (receives result)

Technical Stack

• Runtime: Bun (fast TypeScript runtime with Node.js compatibility)
• IPC: Unix domain sockets (net module)
• Session Storage: JSON files + JSONL append-only logs
• Process Management: Child process spawning (child_process module)
• Claude Integration: Spawn claude CLI as subprocess (supports Pro plan auth, not API-only)
• Main Agent Integration: MCP (Model Context Protocol) server providing task spawning tools

Coordination Model

Main Agent ↔ Subagent

• Poll-based: Main agent reads status.json periodically
• No direct communication channel needed
• Main agent blocks on file watch or polling interval

Human ↔ Subagent

• Socket-based: Real-time bidirectional communication
• Human attachment is transparent to main agent
• Multiple humans can attach (socket supports multiple connections)

Subagent Lifecycle

1. Spawned by main agent via Task tool
2. Runs autonomously, updating status.json
3. Human may attach/detach any number of times
4. Completes and writes result.json
5. Main agent reads result.json
6. Session directory can be archived or cleaned up

Future Enhancements

• Breakpoints: Subagent pauses at specific points for human approval
• Distributed: Run subagents on remote machines
• Custom Subagents: Setup subagents with custom system prompts and context generation prompts (eg. reviewer, designer)