Task Management

The /tasks skill and its backing CLI (.claude/tools/tasks.py) provide persistent task tracking inside a documentation project. Tasks, projects, tags, and logs live in a SQLite database at .claude/tasks.db, surviving across conversations.

Invoking the skill

/tasks <action> [details]

The skill parses free-form text and dispatches to one of four sub-agents:

Intent	Sub-agent	Model	Examples
Create tasks or projects	task-creator	haiku	”add a bug for broken links”
View or query	task-viewer	haiku	”show the agenda”, “list priority A tasks”
Update state, tags, logs	task-updater	haiku	”mark task 5 done”, “tag task 3 with frontend”
Break down features	project-planner	sonnet	”plan the authentication feature”

CLI tool

All sub-agents call the same CLI:

uv run --script .claude/tools/tasks.py <command> [args] [options]

The tool requires Python 3.11+ and typer. uv run --script handles dependency installation automatically.

Task CRUD

add

Create a task.

uv run --script .claude/tools/tasks.py add "Fix broken sidebar links" \
  --priority A \
  --project docs-cleanup \
  --tags "bug,frontend" \
  --deadline 2026-03-25

Option	Short	Description
`--body`	`-b`	Task body or description
`--state`	`-s`	Initial state (default: `TODO`)
`--priority`	`-p`	`A`, `B`, or `C`
`--project`		Project name (auto-creates if missing)
`--parent`		Parent task ID for subtasks
`--effort`		Effort estimate (`30m`, `2h`, `1d`)
`--scheduled`		Scheduled date (`YYYY-MM-DD`)
`--deadline`		Deadline date (`YYYY-MM-DD`)
`--tags`	`-t`	Comma-separated tag names

The project is created automatically if it does not exist. Tags are also auto-created. The initial state change is logged.

get

Retrieve a task with its tags, properties, subtasks, and recent log entries.

uv run --script .claude/tools/tasks.py get 5

Returns the full task object including up to 10 recent log entries.

update

Modify task fields. State changes are logged automatically.

uv run --script .claude/tools/tasks.py update 5 --state DONE
uv run --script .claude/tools/tasks.py update 5 --priority A --deadline 2026-04-01

Accepts the same options as add (except --tags). When state changes to DONE or CANCELLED, the closed_at timestamp is set. Reopening a closed task clears closed_at.

delete

Delete a task and cascade to its subtasks, tags, properties, and log entries.

uv run --script .claude/tools/tasks.py delete 5

list

Query tasks with filters.

uv run --script .claude/tools/tasks.py list --project docs-cleanup --priority A
uv run --script .claude/tools/tasks.py list --tag bug --state TODO
uv run --script .claude/tools/tasks.py list --deadline-before 2026-04-01 --include-done

Option	Short	Description
`--state`	`-s`	Filter by state
`--priority`	`-p`	Filter by priority
`--project`		Filter by project name
`--tag`		Filter by tag name
`--parent`		Filter by parent task ID
`--scheduled-before`		Tasks scheduled on or before date
`--deadline-before`		Tasks due on or before date
`--limit`	`-n`	Max results (default: 50)
`--include-done`		Include `DONE`/`CANCELLED` tasks

Results are ordered by priority (A first), then by creation date descending. DONE and CANCELLED tasks are excluded by default.

State workflow

Tasks move through these states:

TODO → NEXT → IN_PROGRESS → DONE
                           → CANCELLED
      WAITING ←→ (any active state)

Valid states: TODO, NEXT, IN_PROGRESS, WAITING, DONE, CANCELLED.

Every state change is recorded in the task log with the transition (e.g., TODO -> IN_PROGRESS). Setting state to DONE or CANCELLED writes a closed_at timestamp.

Fails if the project name already exists.

project-list

Lists all projects with task counts grouped by state.

uv run --script .claude/tools/tasks.py project-list

project-delete

Deletes a project. Tasks in the project become unassigned (they are not deleted).

uv run --script .claude/tools/tasks.py project-delete "docs-cleanup"

Properties

Arbitrary key-value pairs on tasks. Useful for metadata that does not fit the standard fields.

uv run --script .claude/tools/tasks.py prop-set 5 assignee "ryan"
uv run --script .claude/tools/tasks.py prop-del 5 assignee

Properties use upsert semantics — setting a key that exists overwrites the value.

Log

Each task has a log of timestamped entries. State changes are logged automatically. You can also add notes manually.

uv run --script .claude/tools/tasks.py log 5 "Investigated — root cause is stale cache"
uv run --script .claude/tools/tasks.py log-list 5 --limit 10

Log entry types: state_change, note, clock.

Views

Five read-only views provide org-mode-style overviews.

agenda

Overdue items plus upcoming deadlines and scheduled tasks within a date range.

uv run --script .claude/tools/tasks.py agenda --days 14

Returns tasks grouped by date, with each task marked as overdue or upcoming.

backlog

Unscheduled TODO and NEXT tasks, grouped by priority. These are tasks with no scheduled or deadline date.

uv run --script .claude/tools/tasks.py backlog --project docs-cleanup

All tasks in the NEXT state — the GTD “next actions” list.

uv run --script .claude/tools/tasks.py next --limit 10

stuck

Projects that have TODO tasks but no NEXT or IN_PROGRESS tasks. These projects need attention to move work forward.

uv run --script .claude/tools/tasks.py stuck

summary

Dashboard with counts by state, priority, overdue count, and tasks due this week.

uv run --script .claude/tools/tasks.py summary

Database

The SQLite database lives at .claude/tasks.db relative to the git root. It uses WAL journal mode and foreign keys.

Schema

Six tables:

Table	Purpose
`projects`	Named project containers
`tasks`	Core task records with state, priority, dates
`tags`	Tag name registry
`task_tags`	Many-to-many task-tag associations
`task_properties`	Key-value properties per task
`task_log`	Timestamped log entries per task

The schema is created automatically on first use. Indexes cover state, priority, project_id, parent_id, deadline, scheduled, and task_id on the log table.

Cascading deletes

Deleting a task cascades to its subtasks, tag associations, properties, and log entries. Deleting a project sets project_id to null on its tasks — the tasks survive.