🎯 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