# How to Configure Message Queue and Steering Mode in π‑AI

> Learn to configure message queue and steering mode in π‑AI by adjusting steeringMode and followUpMode settings in JSON or via the SettingsManager API for optimized message handling.

- Repository: [Mario Zechner/pi-mono](https://github.com/badlogic/pi-mono)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Configure message queue and steering mode in π‑AI by setting `steeringMode` and `followUpMode` to either `"all"` or `"one-at-a-time"` in your `~/.pi/settings.json` file or via the `SettingsManager` API.**

The π‑AI engine (powering the **agent** and **coding‑agent** packages in the [badlogic/pi‑mono](https://github.com/badlogic/pi-mono) repository) manages concurrent user input through two internal buffers. Understanding how to configure these queues allows you to control whether the AI processes interruptions immediately or sequences them for later handling.

## Understanding π‑AI Message Queues

π‑AI maintains two distinct message queues while the model is processing a turn:

- **Steering queue** – Holds "steering" messages that interrupt the current turn (for example, when a user types a new command while the assistant is still generating a response).
- **Follow‑up queue** – Holds messages that should be sent *after* the current turn finishes (such as continuations or secondary requests).

Both queues are implemented as simple arrays inside the agent (`steeringQueue` and `followUpQueue` in [`packages/agent/src/agent.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/agent.ts)) and are flushed according to the selected mode.

## Configuring Steering Mode in π‑AI

The `steeringMode` setting determines how the agent delivers messages from the steering queue.

### Steering Mode Options

- **`"one-at-a-time"`** (default) – The agent sends only the first pending steering message and waits for the model to reply before delivering the next one.
- **`"all"`** – The agent flushes the entire steering queue in a single batch the next time the model is invoked.

### Settings File Configuration

Add the following to your `~/.pi/settings.json` file:

```json
{
  "steeringMode": "all"
}

```

The `SettingsManager` class in [`packages/coding-agent/src/core/settings-manager.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/settings-manager.ts) reads this value at runtime:

```ts
// packages/coding-agent/src/core/settings-manager.ts
public getSteeringMode(): "all" | "one-at-a-time" {
    return this.settings.steeringMode || "one-at-a-time";
}

```

### Programmatic Configuration

Change the steering mode dynamically via the agent API:

```ts
import { getAgent } from "@mariozechner/pi-ai";

async function enableBatchSteering() {
  const agent = await getAgent();
  await agent.setSteeringMode("all");
}

```

## Configuring Follow-Up Mode in π‑AI

The `followUpMode` setting controls delivery of the follow‑up queue using the same logic as steering mode.

### Follow-Up Mode Options

- **`"one-at-a-time"`** (default) – Follow‑up messages are delivered sequentially, each waiting for the model's response.
- **`"all"`** – All queued follow‑up messages are sent together after the current turn completes.

### Configuration Examples

In `~/.pi/settings.json`:

```json
{
  "steeringMode": "one-at-a-time",
  "followUpMode": "all"
}

```

Via the `SettingsManager` in [`packages/coding-agent/src/core/settings-manager.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/settings-manager.ts):

```ts
public getFollowUpMode(): "all" | "one-at-a-time" {
    return this.settings.followUpMode || "one-at-a-time";
}

```

## Queue Implementation Details

The internal implementation in [`packages/agent/src/agent.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/agent.ts) uses simple arrays and mode-driven flushing logic:

```ts
// packages/agent/src/agent.ts
private steeringQueue: AgentMessage[] = [];  // L113

public queueSteering(m: AgentMessage) {
    this.steeringQueue.push(m);              // L253
}

private getSteeringMessages(): AgentMessage[] {
    if (this.steeringMode === "one-at-a-time" && this.steeringQueue.length > 0) {
        const first = this.steeringQueue[0];
        this.steeringQueue = this.steeringQueue.slice(1);  // L283‑L285
        return [first];
    }
    const all = this.steeringQueue.slice();  // L291‑L292
    this.steeringQueue = [];
    return all;
}

```

Before each turn, the agent checks `hasPendingMessages()` (which combines steering and follow‑up queues) and injects queued messages back into the conversation flow according to the configured modes.

## Migrating from Legacy queueMode Settings

Earlier versions of π‑AI used a single `queueMode` setting. Starting with v0.12.x, this was split into `steeringMode` and `followUpMode`.

The `SettingsManager` in [`packages/coding-agent/src/core/settings-manager.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/settings-manager.ts) automatically migrates legacy configurations:

```ts
// packages/coding-agent/src/core/settings-manager.ts
if ("queueMode" in settings && !("steeringMode" in settings)) {
    settings.steeringMode = settings.queueMode;  // L189‑L191
    delete settings.queueMode;
}

```

If you have existing `~/.pi/settings.json` files with `queueMode`, they will continue to work without manual intervention.

## Practical Code Examples

### Queuing a Steering Message

From an extension or external tool, you can interrupt the current AI turn by queuing a steering message:

```ts
import { getAgent } from "@mariozechner/pi-ai";

async function interruptAgent(text: string) {
  const agent = await getAgent();
  await agent.queueSteering({ role: "user", content: text });
}

```

The message will be delivered according to the current `steeringMode` setting.

### Inspecting Pending Queues

For debugging purposes, you can inspect the contents of both queues:

```ts
import { getAgent } from "@mariozechner/pi-ai";

async function logQueues() {
  const agent = await getAgent();
  console.log("Steering queue:", await agent.getSteeringQueue());
  console.log("Follow‑up queue:", await agent.getFollowUpQueue());
}

```

## Summary

- π‑AI uses two internal buffers—the **steering queue** for interruptions and the **follow‑up queue** for post‑turn messages—implemented as arrays in [`packages/agent/src/agent.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/agent.ts).
- Configure delivery behavior via `steeringMode` and `followUpMode` in `~/.pi/settings.json`, accepting values `"all"` (batch flush) or `"one-at-a-time"` (sequential delivery).
- The `SettingsManager` class in [`packages/coding-agent/src/core/settings-manager.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/settings-manager.ts) provides getters and automatic migration from the legacy `queueMode` setting.
- Change modes programmatically using `agent.setSteeringMode()` and queue messages via `agent.queueSteering()` according to the API exposed by the agent package.

## Frequently Asked Questions

### What is the difference between steering mode and follow-up mode in π‑AI?

**Steering mode** controls how interruption messages (sent while the AI is processing) are delivered, while **follow-up mode** controls messages queued to run after the current turn completes. Both support `"all"` (batch delivery) and `"one-at-a-time"` (sequential delivery), but they operate on separate queues defined in [`packages/agent/src/agent.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/agent.ts).

### How do I enable batch processing for steering messages?

Set `"steeringMode": "all"` in your `~/.pi/settings.json` file or call `agent.setSteeringMode("all")` programmatically. When set to `"all"`, the agent flushes the entire `steeringQueue` array in a single batch the next time the model is invoked, rather than waiting for individual responses between messages.

### Where are the steering and follow-up queues implemented?

Both queues are implemented as private arrays in the `Agent` class located at [`packages/agent/src/agent.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/agent.ts). The `steeringQueue` is explicitly defined at line 113, while queue manipulation methods like `queueSteering()` (line 253) and `getSteeringMessages()` (lines 283‑292) handle the mode‑driven flushing logic.

### What happened to the old queueMode setting?

The `queueMode` setting was deprecated in π‑AI v0.12.x and replaced by separate `steeringMode` and `followUpMode` settings. The `SettingsManager` class in [`packages/coding-agent/src/core/settings-manager.ts`](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/src/core/settings-manager.ts) automatically migrates legacy configurations by copying `queueMode` to `steeringMode` when the latter is absent, ensuring backward compatibility without manual intervention.