tq — Terminal Task Queue

A keyboard-driven, terminal-native task queue that makes you work on one thing at a time.

Pull the top task → focus mode with timer → finish → next. No click, no cloud, no bloated UI. Just your terminal and a queue.

────────────────────────────────────────────────────────
TASK QUEUE v2.0  4 TASKS                 TODAY:0  WEEK:0  14:32
────────────────────────────────────────────────────────

→ PULL NEXT TASK                                  [SPACE]

Design login flow                                 MEDIUM
Implement API endpoints                             HIGH
Write documentation                                  LOW
Refactor auth middleware                          MEDIUM

────────────────────────────────────────────────────────
[A]dd  [↑/↓]  [E]dit  [D]elete  [J/K] Reorder  [SPACE] Pull  [Q]uit

Install

npm install -g task-queue-tui
tq

Or from source:

git clone https://github.com/engine-research-lab/task-queue-tui.git && cd task-queue-tui && npm i && npm link && tq

Or run without installing:

npx task-queue-tui

Requires Node 20+ and a terminal that supports 24-bit color.

Usage

tq                              # grey (default)
tq --theme=amber                # warm retro
tq --theme=slate                # cool blue-grey
tq --types="dev,review,meeting" # custom task types

Press T (Shift+T) to cycle themes. Use --types to define your own task categories (default: thinking,build,design,admin).

Keybindings

Queue view

| Key | Action | |-----|--------| | ↑ ↓ / j k | Navigate tasks | | Space / Enter | Pull next task into focus mode | | a | Open inline add prompt | | e | Edit selected task (energy / type) | | d | Delete selected task | | J (Shift+J) | Move task down in queue | | K (Shift+K) | Move task up in queue | | T (Shift+T) | Cycle theme (amber → grey → slate) | | q | Quit |

Focus mode (working on a task)

| Key | Action | |-----|--------| | f | Finish task (marks completed) | | r | Return task to queue (goes to end) | | Space / Enter | Swap with first queued task | | q / Esc | Return to queue |

Inline add prompt

| Key | Action | |-----|--------| | Type | Enter task name | | ↑ / ↓ | Cycle energy level (MEDIUM → HIGH → LOW) | | ← / → | Cycle task type (based on --types, default: thinking → build → design → admin) | | Enter | Add task | | Esc | Cancel |

Edit overlay

| Key | Action | |-----|--------| | Tab | Toggle between energy / type | | ← / → | Change value | | Enter | Save | | Esc | Cancel |

Themes

| Theme | Primary | Dim | Vibe | |-------|---------|-----|------| | Grey (default) | #cccccc | #888888 | Clean monochrome | | Mono Grey | #cccccc | #888888 | Clean monochrome | | Slate | #94a8b8 | #5a6e7e | Cool blue-grey |

Press T (Shift+T) to cycle through them.

Data

Tasks are stored in ~/.taskqueue/tasks.json as plain JSON. No database, no cloud, no account.

[
  {
    "id": "abc123",
    "name": "Design login flow",
    "energy_level": "medium",
    "task_type": "design",
    "status": "queued",
    "position": 0,
    "created_at": "2026-05-24T03:01:41.771Z"
  }
]

To reset: rm ~/.taskqueue/tasks.json

Project structure

src/
├── index.ts    # Entry point
├── types.ts    # Task type definitions
├── theme.ts    # Color themes (amber, grey, slate)
├── db.ts       # JSON file persistence + CRUD
└── ui.ts       # Blessed TUI screens + keyboard handling

~600 lines total. No React, no VDOM, no build step.

Philosophy

• Queue, not list — FIFO ordering forces focus. Do the top task, then the next.
• Keyboard-native — every action has a key. No mouse, no clicking.
• Terminal-native — no boxes (no jagged resize), no background colors, respects your terminal theme.
• Zero infrastructure — single JSON file, no Supabase, no server, no API keys.

License

MIT