# true-queue

[![npm version](https://img.shields.io/npm/v/pi-true-queue)](https://www.npmjs.com/package/pi-true-queue)
[![npm downloads](https://img.shields.io/npm/dm/pi-true-queue)](https://www.npmjs.com/package/pi-true-queue)
[![license](https://img.shields.io/npm/l/pi-true-queue)](LICENSE)

A task queue for [pi](https://github.com/badlogic/pi-mono). Queued tasks stay hidden from the agent until the current one is done, so it works on one thing at a time instead of rushing toward the last item on your list.

![Demo](demo.gif)

## Install

```
pi install npm:pi-true-queue
```

Or try it without installing:

```
pi -e npm:pi-true-queue
```

## Usage

Prefix a message with `+` to queue it. Works anytime — while the agent is running or when it's idle:

```
+refactor the auth module
+write tests for it
+update the docs
```

Each task is sent as a fresh prompt after the previous one finishes. The agent never sees what's next:

![Queue widget](queue-widget.png)

Messages without `+` are normal pi input — they steer the current task:

```
+migrate the User model to the new schema      ← queued, hidden from the agent
also handle the legacy null emails             ← steer, agent sees it immediately
```

## Directives

Queue items starting with a known slash command are **directives** — executed by the extension between tasks instead of being sent to the LLM. Change model mid-queue, compact context, adjust thinking level:

```
+implement the parser
+/model gpt-5
+write property tests for it
+/compact
+/thinking high
+refactor based on test findings
```

Supported: `/model <name>`, `/compact [instructions]`, `/thinking <level>`. Directives run back-to-back when reached, so `/model` + `/compact` before a task applies both. If a `/model` directive fails (no match, no API key), the queue pauses so remaining tasks don't run with the wrong model. Other slash commands can't be dispatched by extensions, so anything else starting with `/` is queued as a normal task.

You can also ask the agent to queue something — it has an `enqueue_task` tool:

```
you:   when you're done here, queue a cleanup of the old fixtures
agent: Queued at position 1: clean up the old fixtures
```

## Queue editor

Press `ctrl+q` (or type `/queue`) to open the editor, even while the agent is running:

![Queue editor](queue-editor.png)

- `↑↓` navigate, `⇧↑↓` reorder
- `a` add, `e` edit, `d` delete
- `p` pause/resume, `esc` close

## Commands

```
/queue              open editor
/queue add <task>   add a task
/queue clear        clear all
/queue done         mark current done, start next
/queue skip         drop current task
/queue pause        pause auto-dequeue
/queue resume       resume
```

## Why hide the queue?

An LLM that sees five tasks rushes through the first four to get to the last one (goal anchoring, completion bias). Loops and verifiers (`/goal`, `/loop`, Ralph) catch premature completion after the fact; a queue prevents it — the agent can't rush toward a goal it can't see. That makes it a simple way to run long, multi-step work without the model converging early, including work where "done" is your judgment rather than a test suite.

The package ships with a `sequential-isolation` skill that teaches the agent to treat each task as the only one.