backlog

Query and return tasks matching a filter expression. Returns a JSON array of task objects with all fields (uuid, id, description, status, priority, due, tags, urgency, etc). Use this for browsing, searching, and reading task data. For just a count, use task_count instead. Filter syntax supports: attribute matching (project:X, status:pending, priority:H), tags (+bug, -old), virtual tags (+OVERDUE, +ACTIVE, +BLOCKED, +READY), date comparisons (due.before:friday), and boolean operators (and, or, parentheses). Empty filter returns all pending tasks.

Create a new pending task and return its UUID. Only 'description' is required; all other fields are optional. The task gets a stable numeric ID and UUID for cross-session references. To record already-completed work, use task_log instead. To copy an existing task, use task_duplicate.

Update one or more tasks matching a filter. Only provided fields are changed — omitted fields are left untouched (partial update). The filter can match multiple tasks; all matches are updated with the same changes. Returns the count of modified tasks. Use task_done/task_delete/task_start/task_stop for status changes instead.

Mark a task as completed, setting its status to 'completed' and recording the end timestamp. The task remains in the database and appears in completed task queries. If the task is a recurring instance, completing it may trigger generation of the next instance. To record work that was already done without creating a pending task first, use task_log instead.

Soft-delete a task by setting its status to 'deleted'. The task remains in the database and can be restored with task_undo. To permanently remove a deleted task from the database, use task_purge after deleting. Deleted tasks are excluded from default queries but visible with 'status:deleted' filter.

Add a timestamped text note to a task. Annotations are short, append-only notes for tracking progress, decisions, or handoff context across sessions. Multiple annotations can be added to the same task. For longer structured content (specs, designs, context docs), use task_doc_write instead. To remove an annotation, use task_denotate with the exact text.

Mark a task as actively being worked on by recording a start timestamp. Started tasks appear in +ACTIVE queries and get a higher urgency score. Use task_stop when pausing work, or task_done when finished. Only one task needs to be active at a time, but multiple active tasks are allowed.

Stop actively working on a task by clearing the start timestamp. The task returns to pending status and no longer appears in +ACTIVE queries. Use this when pausing work on a task. To finish it, use task_done instead.

Undo the most recent single operation (add, modify, delete, done, start, stop, annotate). Restores the previous state of the affected task. Can be called repeatedly to undo multiple operations in reverse order. Returns 'Nothing to undo.' if the operation log is empty (e.g. after a checkpoint).

Get the full JSON details for a single task by ID or UUID. Returns all fields including annotations, dependencies, docs, and computed urgency. Use this when you need complete details for one specific task. For querying multiple tasks, use task_list with a filter instead.

Return a JSON array of all project names that have at least one pending or recurring task. Useful for discovering available projects before filtering with task_list. To see tasks in a specific project, use task_list with filter 'project:name'.

Return a JSON array of all tags that have at least one pending or recurring task. Useful for discovering available tags before filtering with task_list. To see tasks with a specific tag, use task_list with filter '+tagname'.

Remove a specific annotation from a task by exact text match. The annotation text must match exactly (case-sensitive). Use task_info to see all annotations on a task before removing. To add annotations, use task_annotate.

Permanently and irreversibly remove a deleted task from the database. The task must already have status 'deleted' (use task_delete first). This cannot be undone — the task data is erased. Use task_archive for bulk cleanup of old completed/deleted tasks instead.

Bulk-create tasks from a JSON array. Each object must have a 'description' field; all other fields (project, tags, priority, due, status, depends, recur) are optional. Tasks are created atomically in a single batch. Returns the count of imported tasks. Use this for migrating data or creating multiple tasks at once. For creating a single task interactively, use task_add instead.

Return the count of tasks matching a filter as a plain number. More efficient than task_list when you only need the count, not the task data. Uses the same filter syntax as task_list.

Record a task that is already completed, creating it directly in 'completed' status with an end timestamp. Use this to log work that was done outside the task system, or to record completed items retroactively. Unlike task_add followed by task_done, this is a single operation. Logged tasks appear in completed task queries and standups.

Create a new pending task by copying an existing one, optionally overriding specific fields. The copy gets a new UUID and ID. Start/end timestamps and status are reset. Use this when you need a similar task with small variations. For creating from scratch, use task_add instead.

Attach or replace a markdown document on a task (spec, design, context, handoff notes). Each task can have one document. Writing replaces any existing doc. Automatically adds +doc tag and has_doc:true to the task for filtering. For short notes, use task_annotate instead. To read the doc back, use task_doc_read. To remove it, use task_doc_delete.

Read the markdown document attached to a task. Returns the document content as text, or an error if no document is attached. Use task_list with filter '+doc' to find tasks that have documents attached.

Remove the markdown document attached to a task. Clears the +doc tag and has_doc field. The document content is permanently deleted. To update a document instead of removing it, use task_doc_write.

Move completed and deleted tasks older than N days to a quarterly archive segment, keeping the active set small and fast. Archived tasks are removed from the active database but can be loaded later with task_archive_load. This is a bulk maintenance operation — for removing individual tasks, use task_delete or task_purge instead.

Return a JSON array of available archive segment paths (e.g. 'archive/archive-2026-Q1.json'). Each segment contains tasks archived during that quarter. Use task_archive_load with the segment name to inspect archived tasks.

Load and return tasks from an archive segment as a read-only JSON array for inspection. Archived tasks are not restored to the active database — this is view-only. Use task_archive_list to discover available segments first.