Question Queue (qq)

An outliner for thinking things through: get questions, ideas and to-dos out of your head as they come up, nest them under whatever raised them, and keep working on the thing in front of you.

The storage is a plain markdown file, a nested list:

- Where is the function to do X? <!-- q:a1b2 -->
  foo/bar/core.py:30, next to the parser.

  It's called from two places.
  - [ ] Add a test for it <!-- q:c3d4 -->
  - [x] Check the caller <!-- q:e5f6 -->
- Who's coming? <!-- q:g7h8 -->

• Every list item is an item. Its first line is the subject, which is what the outline shows; the indented lines under it are the rest of it, like a commit message's body. Blank lines and code fences can sit inside.
• [ ] gives an item a box, [x] ticks it. An item with boxes under it is ticked when all of them are; when only some are, the outline shows [-] (the file keeps [ ], since it isn't done).
• Every item gets a short ID comment, added on load if it's missing.
• Every other line in the file is left exactly as it was, and so is every item you haven't changed. Files from the first version (- ? question with > answer lines) open as items whose text starts with ?.

Install

uv tool install question-queue   # puts qq on your PATH

To work on qq itself, clone this repo, then just setup and uv tool install --editable ., so qq runs from your checkout.

Use

qq             # the queue for this folder (see below)
qq notes.md    # a specific file, created if it doesn't exist
qq --here      # start or open the queue in this folder
qq -g          # your global queue, ~/.qq/questions.md

Plain qq looks for a .qq folder in the current folder and its parents, the way git finds .git, and opens .qq/questions.md inside it. If there isn't one, the first screen asks: h starts a queue in this folder, g uses your global one. In a new project, that's qq, then h, and you're asking questions. From your home folder, qq goes straight to the global queue.

Two panes: the outline on the left is for moving around and arranging (keys there are commands and never type), and the editor on the right is the selected item's whole text, where you type. The pane with the bright border has the focus, and the key bar starts with the mode: OUTLINE, EDIT, NEW or MOVE. Below 90 columns the panes stack.

w a s d work as the arrow keys in the outline, and with shift as shift+arrows.

The palette (ctrl+p, like VS Code's quick open with vim's command line in it) works on whatever pane you opened it from:

A replace needs the closing slash, so a search like /src/app.py finds the path as it is. Without flags it replaces the first match on each line; add g for every match and i to ignore case (/old/new/gi). The text is literal, not a pattern. The palette lists what will change before enter, and u undoes it. Plain words with no / find items, wherever you are.

ctrl+d twice quits from anywhere, as in Claude Code: the first press warns, and a second within two seconds quits. (ctrl+q quits straight away.)

Text saves a second after you stop typing, and everything else saves straight away, always by writing a temp file and renaming it. If something else edits the file while qq is open, it reloads; if you have unsaved edits, it asks first.

Layout

• src/questionqueue/core/: the model, parser, serialiser, tree operations and file store. No UI imports, so other front ends can build on it.
• src/questionqueue/tui/: the Textual app.

Run just for the development recipes; just check is the full gate.