---
slug: "dhruv2mars-pi-queue"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/Dhruv2mars/pi-queue@master/README.md"
repo: "https://github.com/Dhruv2mars/pi-queue"
source_file: "README.md"
branch: "master"
---
# 🎯 pi-queue

[![npm version](https://img.shields.io/npm/v/@dhruv2mars/pi-queue.svg?style=flat&colorA=000000&colorB=ff6b6b)](https://www.npmjs.com/package/@dhruv2mars/pi-queue)
[![pi-extension](https://img.shields.io/badge/pi-extension-6366f1?style=flat&colorA=000000)](https://pi.dev)
[![license](https://img.shields.io/badge/license-MIT-4ade80?style=flat&colorA=000000)](LICENSE)

> Advanced **FIFO message queue** and **steering** for [pi](https://pi.dev). Queue up messages while the agent works, then drain them one at a time.

---

## ✨ Why pi-queue?

Ever been deep in a coding session with **pi** and thought of 3 follow-up questions while it's still running? Instead of waiting idle, **queue them up**. pi-queue intercepts your `Enter` key while the agent is working and routes messages into a FIFO queue. When pi finishes its current run, the next queued message auto-sends. No context switching. No lost ideas.

---

## 🚀 Install

```bash
pi install npm:@dhruv2mars/pi-queue
```

Or from source:

```bash
git clone https://github.com/Dhruv2mars/pi-queue.git
pi install ./pi-queue
```

---

## 📖 Table of Contents

- [Features](#-features)
- [Quick Start](#-quick-start)
- [Usage](#-usage)
  - [Queue Mode](#queue-mode-default)
  - [Steer Mode](#steer-mode)
  - [Queue Manager](#queue-manager)
  - [Commands](#commands)
- [Keybindings](#-keybindings)
- [How It Works](#-how-it-works)
- [Configuration](#-configuration)
- [Changelog](#-changelog)
- [Contributing](#-contributing)
- [License](#-license)

---

## 🎨 Features

| Feature | Description |
|---------|-------------|
| **🔄 Queue Mode** | `Enter` while working → queue message for delivery after full run |
| **⚡ Steer Mode** | `Enter` while working → send steering message after current tool batch |
| **📊 Live Widget** | See mode + queue count + queued messages above the editor |
| **🗂️ Queue Manager** | Interactive overlay: edit, remove, reorder queued messages |
| **🎹 Smart Keys** | `Alt+Enter` flips behavior, `Ctrl+Shift+M` toggles mode, `Ctrl+Shift+Q` opens manager |
| **🔄 Auto-Drain** | Queue drains automatically — one message per agent run |
| **💾 Persistent Mode** | Queue/steer mode preference survives session restarts |

---

## 🏁 Quick Start

```bash
# 1. Install
pi install npm:@dhruv2mars/pi-queue

# 2. Start pi
pi

# 3. Ask pi to do something
> build a react component

# 4. While pi is working, queue a follow-up
> add tests for it          ← press Enter, message queued!

# 5. Queue another
> make it responsive        ← press Enter, message queued!

# 6. pi finishes → next queued message auto-sends
# 7. That run finishes → next message auto-sends
```

---

## 🎮 Usage

### Queue Mode (default)

```
┌────────────────────────────────────────┐
│ ▶ QUEUE | 2 queued       ^Q manager    │
│────────────────────────────────────────│
│  1. add tests for it                   │
│  2. make it responsive                 │
│  ● working…                            │
├────────────────────────────────────────┤
│ > type here...                    QUEUE│
└────────────────────────────────────────┘
```

| Action | Key | When | Behavior |
|--------|-----|------|----------|
| Submit | `Enter` | idle | Normal prompt submission |
| **Queue** | `Enter` | working | Add to queue → sent after full run |
| **Steer** | `Alt+Enter` | working | Sent after current tool batch |
| Toggle mode | `Ctrl+Shift+M` | any | Switch queue ↔ steer |
| Open manager | `Ctrl+Shift+Q` | any | Edit / remove / reorder queue |
| Abort + drain | `Escape` | working | Abort run, auto-send next queued |

### Steer Mode

Flip the behavior so `Enter` steers and `Alt+Enter` queues:

| Action | Key | When | Behavior |
|--------|-----|------|----------|
| **Steer** | `Enter` | working | Sent after current tool batch |
| **Queue** | `Alt+Enter` | working | Add to queue → sent after full run |

### Queue Manager

Open with `Ctrl+Shift+Q` or type `/queue`:

```
╭────────────────────────────────────╮
│ Queue Manager                      │
│                                    │
│  ▶ add tests for it                │
│    make it responsive              │
│                                    │
│  ↑↓ navigate  Enter edit  Del ...  │
╰────────────────────────────────────╯
```

| Key | Action |
|-----|--------|
| `↑` / `↓` | Navigate items |
| `Enter` | Edit selected message |
| `Delete` / `Ctrl+D` | Remove selected message |
| `Shift+↑` / `Shift+↓` | Reorder selected message |
| `Escape` | Close manager |

While editing:
- Type to modify text
- `Enter` — Save changes
- `Escape` — Cancel edit

### Commands

| Command | Description |
|---------|-------------|
| `/queue` | Open the queue manager overlay |
| `/queue-mode` | Toggle between queue and steer mode |
| `/queue-clear` | Clear all queued messages |

---

## ⌨️ Keybindings

| Shortcut | Action |
|----------|--------|
| `Enter` (working) | Queue message (queue mode) or steer (steer mode) |
| `Alt+Enter` (working) | Steer (queue mode) or queue (steer mode) |
| `Ctrl+Shift+M` | Toggle queue ↔ steer mode |
| `Ctrl+Shift+Q` | Open queue manager |
| `Escape` (working) | Abort current run, auto-drain queue |

---

## 🧠 How It Works

pi-queue replaces the default editor with a custom `QueueEditor` component that intercepts keypresses while the agent is working.

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  You type   │────▶│  QueueEditor│────▶│  FIFO Queue │
│  "add tests"│     │  intercepts │     │  (in-memory)│
└─────────────┘     │  Enter key  │     └─────────────┘
                    └─────────────┘            │
                                               ▼
                    ┌─────────────┐     ┌─────────────┐
                    │  pi agent   │◀────│  Auto-drain │
                    │  finishes   │     │  next msg   │
                    └─────────────┘     └─────────────┘
```

**Auto-drain flow:**

1. Queue messages while pi is working
2. When pi finishes its current run → first queued message auto-sends via `pi.sendUserMessage()`
3. That run finishes → next queued message auto-sends
4. Repeat until queue is empty

**Smart Escape:** Press `Escape` while working to abort the current run. If the queue has items, draining begins immediately.

---

## ⚙️ Configuration

No configuration required. Mode preference (queue vs steer) is automatically persisted in the session file and survives restarts.

If you want to reset your mode preference, use `/queue-mode` or `Ctrl+Shift+M`.

---

## 📝 Changelog

See [CHANGELOG.md](https://github.com/Dhruv2mars/pi-queue/blob/HEAD/CHANGELOG.md) for version history.

---

## 🤝 Contributing

Contributions welcome! See [CONTRIBUTING.md](https://github.com/Dhruv2mars/pi-queue/blob/HEAD/CONTRIBUTING.md).

---

## 📄 License

MIT © [Dhruv2mars](https://github.com/Dhruv2mars)