tq

Git-first agent-centric task queue using simple markdown files

To install dependencies:

bun install

To lint the codebase:

bun run lint

To run the CLI:

bun run index.ts -- --help

The CLI entrypoint is tq.

Configuration

tq stores machine and global workspace settings in ~/.config/tq/config.toml (or $XDG_CONFIG_HOME/tq/config.toml). Global task data lives under ~/.local/share/tq/tasks (or $XDG_DATA_HOME/tq/tasks).

Example config:

[machine]
name = "workstation"

[workspaces]
"/path/to/project" = "a1b2"

If machine.name is omitted, tq falls back to USER or LOGNAME when claiming tasks.

Workspace resolution

tq prefers local mode whenever a .tasks directory exists in the workspace root. If .tasks is missing, tq uses global mode and looks up the workspace id in the config before resolving the tasks directory under the global base path. If the workspace is not registered, tq reports an error and asks you to run tq init --mode global.

Initialization

Use tq init to set up task storage for the current workspace. By default it uses local mode and creates a .tasks directory in the workspace. Use tq init --mode global to register the workspace in the config and create its tasks directory under the global data path. Global mode does not create .tasks in the project repo.

Creating tasks

Use tq create to write a new task file with defaults and commit it to the tasks repository. The command returns the new task id.

tq create "Add task filters" -d "Support filtering by status." -p 1

status defaults to open, priority defaults to 2, created_by is set to the current machine name, and claimed_by/claimed_at start empty.

Updating tasks

Use tq update <id> to change task metadata or replace the description. Only name, status, priority, and description can be edited.

tq update ab12 -s in_progress -p 1 -d "Start implementing filters"

Listing tasks

Use tq list to list tasks. Filters can be repeated within a field (OR), and different fields are combined with AND semantics.

Filter flags:

• -n name
• -s status
• -p priority
• -c claimed_by
• -C created_at
• -U updated_at
• --mine created_by matches the current user

Long-form flags are also accepted: --name, --status, --priority, --claimed-by, --created, --updated, and --mine. Timestamps are normalized to ISO 8601 strings before matching.

tq list -s open -s in_progress -p 1

Use --json to emit structured output:

tq list --json

By default tq list only shows issues that are ready to work on. Use tq list --all to include claimed, closed and cancelled tasks.

Showing tasks

Use tq show <id> to display full task details, including the description.

tq show ab12

Use --json for structured output:

tq show ab12 --json

Claiming and finishing tasks

Use tq claim <id> to claim a task. Claiming sets the status to in_progress, fills claimed_by with the configured machine name (or USER/LOGNAME), and stamps claimed_at.

tq claim ab12

Use tq close <id> to mark a task as done and tq cancel <id> to mark it as cancelled.

tq close ab12
tq cancel ab12

Task repository

Each tasks directory is a git repository. tq initializes the repo on first use, creates an initial commit, and records every task change with a concise commit message. If a remote is configured, tq pulls before mutating tasks and pushes after each successful commit.

Use tq git <args> to run git commands inside the tasks repository:

tq git status -sb

Task format

Each task is a Markdown file named <id>.md, where the id is 4 lowercase alphanumeric characters ([a-z0-9]). Task metadata lives in a frontmatter block at the top of the file, followed by the task description.

---
name: "Review queue"
created_at: "2026-01-27T10:00:00.000Z"
created_by: "machine_name"
updated_at: "2026-01-27T10:00:00.000Z"
status: "open"
claimed_by: ""
claimed_at: ""
priority: 2
---

Describe the work in Markdown here.

priority is an integer from 0 to 4. If it is missing when loading a task, tq defaults it to 2.