🎯 pi-queue

Advanced FIFO message queue and steering for pi. 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

pi install npm:@dhruv2mars/pi-queue

Or from source:

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

📖 Table of Contents

• Features
• Quick Start
• Usage
  • Queue Mode
  • Steer Mode
  • Queue Manager
  • Commands
• Keybindings
• How It Works
• Configuration
• Changelog
• Contributing
• 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

# 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 for version history.

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md.

📄 License

MIT © Dhruv2mars