{"id":49491,"library":"task-queue-tq","title":"tq – Terminal Task Queue","description":"A keyboard-driven, terminal-native task queue that enforces single-tasking by pulling the top task, entering focus mode with a timer, and finishing before moving to the next. Version 1.0.0 is stable and actively developed on GitHub. It distinguishes itself from cloud task managers by storing tasks locally in a JSON file (~/.taskqueue/tasks.json), requiring no internet, accounts, or servers. The CLI is less than 600 lines of TypeScript, uses blessed for TUI, and supports three color themes (amber, grey, slate) with hotkey switching. Works on Node.js 20+ with 24-bit color terminals.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install task-queue-tq","lang":"bash","label":"npm"},{"cmd":"yarn add task-queue-tq","lang":"bash","label":"yarn"},{"cmd":"pnpm add task-queue-tq","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Terminal UI rendering and input handling","package":"blessed","optional":false},{"reason":"Command-line argument parsing (e.g., --theme)","package":"commander","optional":false},{"reason":"File I/O for task persistence","package":"node:fs","optional":false},{"reason":"File path resolution for task storage","package":"node:path","optional":false}],"imports":[{"note":"Package exports a default function that starts the TUI. No named exports for individual modules like db or theme.","wrong":"const tq = require('task-queue-tq')","symbol":"tq (default export)","correct":"import tq from 'task-queue-tq'"},{"note":"Task is a type (interface) exported from types.ts. Use type import to avoid value import warning.","wrong":"import { Task } from 'task-queue-tq'","symbol":"Task","correct":"import type { Task } from 'task-queue-tq'"},{"note":"EnergyLevel is a union type ('low' | 'medium' | 'high'). Type import only.","wrong":"import { EnergyLevel } from 'task-queue-tq'","symbol":"EnergyLevel","correct":"import type { EnergyLevel } from 'task-queue-tq'"},{"note":"TaskType is a union type ('thinking' | 'build' | 'design' | 'admin'). Type import only.","wrong":"import { TaskType } from 'task-queue-tq'","symbol":"TaskType","correct":"import type { TaskType } from 'task-queue-tq'"}],"quickstart":{"code":"import tq from 'task-queue-tq';\n\n// Start the TUI with default amber theme\ntq();\n\n// Start with a specific theme\ntq({ theme: 'slate' });\n\n// Example: programmatically add a task before starting\n// (This is not directly exposed; use the CLI or modify tasks.json)\n// The package only exports the tq runner; data manipulation is CLI-only.","lang":"typescript","description":"Imports and starts the terminal task queue TUI, optionally passing a theme configuration."},"warnings":[{"fix":"Upgrade Node.js to version 20 or later. Use nvm or fnm to manage Node versions.","message":"Requires Node.js 20+ (ESM modules, AbortController for async cleanup). Older Node versions will throw 'ERR_REQUIRE_ESM' or 'SyntaxError'.","severity":"breaking","affected_versions":"<20.0.0"},{"fix":"Use import syntax. If your project is CJS, consider dynamic import: const tq = await import('task-queue-tq')","message":"Package is ESM-only. It does not provide a CommonJS build. Require('task-queue-tq') throws ERR_REQUIRE_ESM.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set TERM=xterm-256color or use a terminal that supports true color (e.g., Windows Terminal, iTerm2, modern gnome-terminal).","message":"Terminal must support 24-bit color (true color). In terminals like older Windows cmd or tmux with TERM=xterm, the UI may render with artifacts or missing colors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Back up the file manually if needed. To reset, run: rm ~/.taskqueue/tasks.json","message":"Task data is stored in ~/.taskqueue/tasks.json. Deleting or corrupting this file will lose all tasks. No backup mechanism is built in.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"No immediate action needed, but be aware of potential upstream incompatibilities.","message":"The 'blessed' dependency is unmaintained. Future versions may migrate to alternative TUI libraries like 'ink' or 'termkit'.","severity":"deprecated","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'/.taskqueue/tasks.json':61 '1.0.0':38 '20':95 '24':97 '600':73 'account':65 'activ':42 'amber':86 'bit':98 'bless':78 'cli':69 'cloud':50 'color':84,99 'develop':43 'distinguish':47 'driven':8 'enforc':15 'enter':24 'file':60 'finish':31 'focus':25 'github':45 'grey':87 'hotkey':90 'internet':64 'javascript':101 'json':59 'keyboard':7 'keyboard-driven':6 'less':71 'line':74 'local':56 'manag':52 'mode':26 'move':33 'nativ':11 'next':36 'node.js':94 'pull':20 'queue':4,13 'requir':62 'server':67 'singl':17 'single-task':16 'slate':88 'stabl':40 'store':54 'support':82 'switch':91 'task':3,12,18,23,51,55 'termin':2,10,100 'terminal-n':9 'theme':85 'three':83 'timer':29 'top':22 'tq':1 'tui':80 'typescript':76 'use':77 'version':37 'work':92","created_at":"2026-06-07T17:02:02.794312+00:00","updated_at":"2026-06-07T17:02:02.794312+00:00","problems":[{"fix":"Use dynamic import: const tq = await import('task-queue-tq'); or change your project to ESM (type: 'module' in package.json).","cause":"Package is ESM-only; require() does not work.","error":"const tq = require('task-queue-tq');\nError [ERR_REQUIRE_ESM]: require() of ES Module ... not supported."},{"fix":"Use Node 20+ or run with --experimental-modules flag (not recommended). Upgrade to Node 20+.","cause":"Node.js version <20 does not support ESM syntax without flags.","error":"SyntaxError: Unexpected token 'export'"},{"fix":"Ensure npm global bin is in PATH. Run: npm install -g task-queue-tq && tq. Alternatively use npx: npx task-queue-tq","cause":"Global install may not be in PATH or npm global bin directory is misconfigured.","error":"tq command not found"},{"fix":"Run: npm install in the cloned directory. If using globally installed version, ensure peer deps are met.","cause":"Missing dependency when running from source without npm install.","error":"Error: Cannot find module 'blessed'"},{"fix":"Set TERM=xterm-256color and use a true-color-capable terminal. Temporarily force color mode (if supported) or use a different theme.","cause":"Terminal lacks 24-bit color support or TERM variable is set incorrectly.","error":"Terminal does not display colors correctly (garbled UI)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"task-queue-tq","openapi_spec":null,"status_page":null,"smithery":null,"categories":["productivity"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}