task-queue-tq

library1.0.0jsnpmunverified

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.

productivity

npm install task-queue-tq

package ↗

INSTALL

IMPORT

SIG · TASK-QUEUE-TQ

task-queue-tq

productivityjavascriptv1.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

tq (default export)

✓ import tq from 'task-queue-tq'

✗ const tq = require('task-queue-tq')

Package exports a default function that starts the TUI. No named exports for individual modules like db or theme.

Task

✓ import type { Task } from 'task-queue-tq'

✗ import { Task } from 'task-queue-tq'

Task is a type (interface) exported from types.ts. Use type import to avoid value import warning.

EnergyLevel

✓ import type { EnergyLevel } from 'task-queue-tq'

✗ import { EnergyLevel } from 'task-queue-tq'

EnergyLevel is a union type ('low' | 'medium' | 'high'). Type import only.

TaskType

✓ import type { TaskType } from 'task-queue-tq'

✗ import { TaskType } from 'task-queue-tq'

TaskType is a union type ('thinking' | 'build' | 'design' | 'admin'). Type import only.

Imports and starts the terminal task queue TUI, optionally passing a theme configuration.

import tq from 'task-queue-tq'; // Start the TUI with default amber theme tq(); // Start with a specific theme tq({ theme: 'slate' }); // Example: programmatically add a task before starting // (This is not directly exposed; use the CLI or modify tasks.json) // The package only exports the tq runner; data manipulation is CLI-only.

Debug

Known issues

breakingRequires Node.js 20+ (ESM modules, AbortController for async cleanup). Older Node versions will throw 'ERR_REQUIRE_ESM' or 'SyntaxError'.

fix

Upgrade Node.js to version 20 or later. Use nvm or fnm to manage Node versions.

affects: <20.0.0

gotchaPackage is ESM-only. It does not provide a CommonJS build. Require('task-queue-tq') throws ERR_REQUIRE_ESM.

fix

Use import syntax. If your project is CJS, consider dynamic import: const tq = await import('task-queue-tq')

affects: >=1.0.0

gotchaTerminal 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.

fix

Set TERM=xterm-256color or use a terminal that supports true color (e.g., Windows Terminal, iTerm2, modern gnome-terminal).

affects: >=1.0.0

gotchaTask data is stored in ~/.taskqueue/tasks.json. Deleting or corrupting this file will lose all tasks. No backup mechanism is built in.

fix

Back up the file manually if needed. To reset, run: rm ~/.taskqueue/tasks.json

affects: >=1.0.0

deprecatedThe 'blessed' dependency is unmaintained. Future versions may migrate to alternative TUI libraries like 'ink' or 'termkit'.

fix

No immediate action needed, but be aware of potential upstream incompatibilities.

affects: >=1.0.0

Errors

Common errors & fixes

const tq = require('task-queue-tq'); Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.

Package is ESM-only; require() does not work.

fix

Use dynamic import: const tq = await import('task-queue-tq'); or change your project to ESM (type: 'module' in package.json).

SyntaxError: Unexpected token 'export'

Node.js version <20 does not support ESM syntax without flags.

fix

Use Node 20+ or run with --experimental-modules flag (not recommended). Upgrade to Node 20+.

tq command not found

Global install may not be in PATH or npm global bin directory is misconfigured.

fix

Ensure npm global bin is in PATH. Run: npm install -g task-queue-tq && tq. Alternatively use npx: npx task-queue-tq

Error: Cannot find module 'blessed'

Missing dependency when running from source without npm install.

fix

Run: npm install in the cloned directory. If using globally installed version, ensure peer deps are met.

Terminal does not display colors correctly (garbled UI)

Terminal lacks 24-bit color support or TERM variable is set incorrectly.

fix

Set TERM=xterm-256color and use a true-color-capable terminal. Temporarily force color mode (if supported) or use a different theme.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

blessedrequiredTerminal UI rendering and input handling

commanderrequiredCommand-line argument parsing (e.g., --theme)

node:fsrequiredFile I/O for task persistence

node:pathrequiredFile path resolution for task storage

Agent activity

37 hits · last 30 days

node

OpenAI (training)

Resources

packagetask-queue-tq ↗