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

> Discover how the Roo Code IPC server manages task commands. Learn how StartNewTask and ResumeTask are processed through Unix sockets, validation, and API routing for efficient task execution.

- Repository: [Roo Code/Roo-Code](https://github.com/RooCodeInc/Roo-Code)
- Tags: internals
- Published: 2026-04-26

---

**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`](https://github.com/RooCodeInc/Roo-Code/blob/main/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`](https://github.com/RooCodeInc/Roo-Code/blob/main/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

```typescript
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

```typescript
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:

```typescript
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`](https://github.com/RooCodeInc/Roo-Code/blob/main/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`](https://github.com/RooCodeInc/Roo-Code/blob/main/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`](https://github.com/RooCodeInc/Roo-Code/blob/main/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`](https://github.com/RooCodeInc/Roo-Code/blob/main/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`](https://github.com/RooCodeInc/Roo-Code/blob/main/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.