Finding Work

# List all tasks
taskgraph list

# List tasks with a specific status
taskgraph list --status=<status>

# List tasks with subtasks
taskgraph list --with-subtasks

# List tasks with a specific status and include subtasks
taskgraph list --status=<status> --with-subtasks

# Watch for changes and auto-refresh
taskgraph list --watch
taskgraph list -w

# Compact output format
taskgraph list --compact
taskgraph list -c

# Watch mode with compact output
taskgraph list -w -c

# Hide the header
taskgraph list --no-header

# Show the next task to work on: dependencies done, then priority,
# then most unblocked work, then fewer dependencies, then lowest ID
taskgraph next

# Take the next task nobody has started: set it in-progress and record
# who claimed it (session ID, else your user name) in one locked write,
# so two sessions never get the same task. Setting it back to pending
# releases it.
taskgraph next --claim

# Show details of a specific task
taskgraph show <id>
# or
taskgraph show --id=<id>

# View a specific subtask (e.g., subtask 2 of task 1)
taskgraph show 1.2

# Draw all tasks as a tree: each task sits under the dependency it waits on
# longest, other dependencies are listed after its title, and the next
# task is marked "← next". Loops and missing dependency IDs are called out.
taskgraph graph

# Only one task and the tasks drawn under it
taskgraph graph --id=3

# Machine-readable tree, with bottlenecks, criticalPath and per-node
# `inferred` dependencies
taskgraph graph --format json

# Follow a task's unfinished dependencies down to the root causes: work
# that is ready to start, deferred or blocked tasks, dependency IDs that
# match no task, and dependency loops (including a task that lists itself).
# Each root cause comes with the command that fixes it.
taskgraph why <id>
# or
taskgraph why --id=<id>

# Subtasks work too
taskgraph why 3.2

# Machine-readable explanation
taskgraph why <id> --format json

# Print what an agent needs at the start of a session: the tag, the task
# in progress with how to tell it's done (acceptance criteria, else test
# strategy), the next three ready tasks in `next` order, and the five
# workflow rules, with free text in single quotes. Under 40 lines, 80
# columns wide when piped.
taskgraph prime

# Another tag, or the same context as JSON
taskgraph prime --tag=feature-auth
taskgraph prime --json

# Only the in-progress tasks with no note since a time (ISO); prints
# nothing when every one has a note. The plugin's Stop hook uses it.
taskgraph prime --unnoted-since=2026-10-23T09:00:00Z