How the Roo Code IPC Server Handles Task Commands: StartNewTask and ResumeTask Explained

The Roo Code IPC server processes task commands by listening on a Unix socket, validating incoming messages against ipcMessageSchema, and routing valid TaskCommand payloads to the API class where a switch statement delegates to startNewTask() or resumeTask() methods.

The Roo Code extension (RooCodeInc/Roo-Code) exposes an inter-process communication (IPC) server that allows external clients like CLIs or VS Code extension hosts to control task execution remotely. Understanding how this IPC server handles commands such as StartNewTask and ResumeTask is essential for developers integrating with Roo Code's automation pipeline.

IPC Server Architecture and Message Reception

The foundation of Roo Code's IPC handling lies in the IpcServer class defined in packages/ipc/src/ipc-server.ts. This server binds to a Unix socket and parses incoming messages using ipcMessageSchema to ensure structural integrity before processing.

When a message arrives from a client, the server checks if the payload's origin equals IpcOrigin.Client and the type equals TaskCommand. Upon validation, the server emits an internal IpcMessageType.TaskCommand event that carries the clientId and the decoded command payload. This event-driven architecture decouples socket-level communication from the extension's business logic.

Command Routing in the API Layer

The API class in src/extension/api.ts instantiates the IpcServer when a socket path is provided during initialization. It registers a handler for IpcMessageType.TaskCommand events that uses a switch statement to differentiate between command names defined in the TaskCommandName enum.

StartNewTask Execution Flow

When the command name matches TaskCommandName.StartNewTask, the API logs the request and invokes API.startNewTask(command.data). This method accepts a configuration object containing RooCodeSettings, task text, optional images array, and a newTab boolean. The implementation creates a new task instance, opens an editor tab if requested, and pushes initialization messages to the webview.

ResumeTask Execution Flow

For TaskCommandName.ResumeTask, the handler calls API.resumeTask(command.data), passing the task ID string. This method focuses the sidebar, ensures webview readiness, retrieves historic task data from storage, and reconstructs the task state in the UI. The implementation wraps the operation in a try-catch block to prevent IPC server crashes when task IDs are invalid or webview initialization fails.

Client-Side Command Transmission

External clients construct payloads validated by taskCommandSchema and transmit them over the Unix socket. The origin field must be set to IpcOrigin.Client and the type to IpcMessageType.TaskCommand for the server to process the message.

Sending a StartNewTask Command

import { IpcMessageType, IpcOrigin, taskCommandSchema } from "@roo-code/types";

// Build the payload (validated by taskCommandSchema)
const startCmd = {
  commandName: "StartNewTask",
  data: {
    configuration: {/* RooCodeSettings */},
    text: "Explain the repository architecture",
    images: [],          // optional
    newTab: false,      // optional
  },
};

process.send?.({
  type: IpcMessageType.TaskCommand,
  origin: IpcOrigin.Client,
  clientId: "cli-123",   // generated by client
  data: startCmd,
});

When the CLI transmits this object over the Unix socket, the server parses it and triggers API.startNewTask with the provided configuration and text.

Sending a ResumeTask Command

const resumeCmd = {
  commandName: "ResumeTask",
  data: "task-7b2c9f1a",   // the taskId to resume
};

process.send?.({
  type: IpcMessageType.TaskCommand,
  origin: IpcOrigin.Client,
  clientId: "cli-123",
  data: resumeCmd,
});

The server invokes API.resumeTask("task-7b2c9f1a") upon receiving this payload, reconstructing the specified task in the interface.

Server-Side Implementation Details

The handler registration in the API constructor demonstrates the routing logic that processes incoming task commands:

ipc.on(IpcMessageType.TaskCommand, async (clientId, command) => {
  switch (command.commandName) {
    case TaskCommandName.StartNewTask:
      this.log(`[API] StartNewTask -> ${command.data.text}`);
      await this.startNewTask(command.data);
      break;

    case TaskCommandName.ResumeTask:
      this.log(`[API] ResumeTask -> ${command.data}`);
      try {
        await this.resumeTask(command.data);
      } catch (error) {
        this.log(`[API] ResumeTask failed for taskId ${command.data}: ${error}`);
      }
      break;

    // … other cases omitted …
  }
});

This implementation ensures that StartNewTask creates fresh task instances while ResumeTask handles reconstruction of existing sessions, with comprehensive error logging to maintain server stability.

Summary

• The IpcServer listens on Unix sockets and validates messages using ipcMessageSchema defined in packages/ipc/src/ipc-server.ts
• Valid TaskCommand messages emit IpcMessageType.TaskCommand events carrying the clientId and decoded payload
• The API class routes commands via a switch statement in src/extension/api.ts to startNewTask() or resumeTask() methods
• StartNewTask creates new task instances with optional editor tab creation and webview initialization
• ResumeTask reconstructs existing task states from historic data stored in the extension
• All errors are caught and logged to ensure IPC server stability and prevent crash propagation

Frequently Asked Questions

What protocol does Roo Code use for IPC communication?

Roo Code uses Unix domain sockets for local IPC communication. The IpcServer class binds to a filesystem socket path provided during initialization, allowing external processes to transmit JSON-encoded messages that adhere to the ipcMessageSchema validation rules defined in packages/types/src/ipc.ts.

How does the IPC server validate incoming task commands?

The server validates all incoming messages against ipcMessageSchema. For task commands specifically, the payload must include an origin of IpcOrigin.Client, a type of IpcMessageType.TaskCommand, and a data object conforming to taskCommandSchema that specifies a valid commandName from the TaskCommandName enum along with command-specific parameters.

Can external CLI tools trigger Roo Code tasks through the IPC server?

Yes. External CLI tools can connect to the Unix socket path and send properly formatted TaskCommand messages. By setting commandName to "StartNewTask" with configuration and text data, or "ResumeTask" with a valid task ID string, CLI processes can remotely control Roo Code's task execution as implemented in src/extension/api.ts.

What happens if ResumeTask fails to find the specified task ID?

The API.resumeTask() method implements error handling that catches exceptions when task IDs cannot be found or when webview initialization fails. According to the implementation in src/extension/api.ts, errors are logged using this.log() with the task ID and error details, allowing the IPC server to continue operating without crashing or terminating the socket connection.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}