/td

name: td
description: Manage tasks and issues with the td CLI. Use for creating, tracking, querying, and handing off work items. Covers task lifecycle, session management, structured handoffs, epics, dependencies, and boards.

td — Task & Session Management

td is a local-first task management CLI optimized for AI-assisted development workflows. It tracks issues, sessions, structured handoffs, and progress logs.

Session Workflow

Every session follows this pattern:

1. **Start** — Load context and begin a new session:

   td usage --new-session    # Full context dump (issues, logs, handoffs)
   td status                 # Quick dashboard: focus, reviews, blocked, ready

2. **Pick work** — Find what to work on:

   td next                   # Highest-priority open issue
   td ready                  # All open issues sorted by priority
   td list --mine            # Issues assigned to current session

3. **Start an issue** — Set focus and mark in-progress:

   td start <issue-id>       # Sets focus + status to in_progress

4. **Log progress** — Track decisions, blockers, attempts:

   td log "Implemented auth middleware"              # Progress (default)
   td log --blocker "Waiting on API key from team"   # Blocker
   td log --decision "Using JWT over session tokens"  # Decision
   td log --tried "Attempted Redis caching"           # Attempted approach
   td log --result "Redis too complex, using in-memory" # Result
   td log --hypothesis "Rate limiting might fix 429s"   # Hypothesis

5. **Handoff** — Capture structured state before ending session:

   td handoff <issue-id> \
     --done "Implemented login endpoint" \
     --done "Added JWT validation" \
     --remaining "Add refresh token flow" \
     --remaining "Write tests for auth middleware" \
     --decision "Using RS256 for JWT signing" \
     --uncertain "Should we support OAuth2 providers?"

6. **Submit for review** — When work is complete:

   td review <issue-id>      # Submit for review (preferred)

7. **Review** — Different session approves or rejects:

   td reviewable             # What can I review?
   td approve <issue-id>     # Ship it → closed
   td reject <issue-id> --reason "Need tests"  # Back to in_progress

Creating Issues

# Basic
td create "Fix login redirect bug"

# Full options
td create "Add OAuth2 support" \
  --type feature \
  --priority P1 \
  --description "Support Google and GitHub OAuth2 providers" \
  --labels "auth,backend" \
  --parent <epic-id>

# Types: task (default), bug, feature, epic, chore
# Priorities: P0 (critical) → P4 (minimal)
# Points: Fibonacci — 1, 2, 3, 5, 8, 13, 21

Querying Issues

Quick filters

td list                           # All open issues
td list --all                     # Include closed
td list --type bug                # Only bugs
td list --priority P0             # Only critical
td list --status in_progress      # In progress
td list --labels auth             # By label
td list --epic <epic-id>          # All tasks in an epic
td list --sort priority            # Sort by field
td list --long                    # Detailed output
td list --json                    # JSON output

TDQ query language

td query "status = open AND type = bug"
td query "priority <= P1"                    # P0 and P1
td query "created >= -7d"                    # Last 7 days
td query "title ~ auth OR description ~ auth"
td query "log.type = blocker"                # Issues with blockers
td query "implementer = @me AND is(in_progress)"
td query "descendant_of(<epic-id>)"          # All children of epic
td query "rework()"                          # Rejected issues

Saved boards

td board create "Active Bugs" "type = bug AND is(open)"
td board create "My Work" "implementer = @me AND NOT is(closed)"
td board list                                # Show all boards
td board show "Active Bugs"                  # Run saved query

Issue Lifecycle

open → in_progress → in_review → closed
  ↕        ↕            ↕
blocked  blocked      rejected → in_progress (rework)

Review workflow (preferred for non-trivial work)

td start <id>           # open → in_progress (sets focus)
# ... do work, log progress ...
td handoff <id> --done "..." --remaining "..."   # capture state
td review <id>          # in_progress → in_review (requires handoff)

# Different session reviews:
td reviewable           # what can I review?
td approve <id>         # in_review → closed (ship it)
td reject <id> --reason "Missing error handling"  # in_review → in_progress (back to work)

Other transitions

td block <id>           # → blocked
td unblock <id>         # → open
td close <id>           # → closed (skip review, for admin closes only)
td reopen <id>          # → open

Guidelines

• **Always use `review` → `approve`/`reject`** for non-trivial work — don't skip to `close`
• `close` is for admin purposes only: duplicates, won't-fix, trivial/minor tasks
• Session isolation: the session that implements can't approve its own work
• `reject` sends work back to `in_progress` for rework — always include a `--reason`

Dependencies

td dep add <id> <depends-on-id>     # A depends on B
td dep rm <id> <depends-on-id>      # Remove dependency
td depends-on <id>                  # What does this issue need?
td blocked-by <id>                  # What's waiting on this issue?
td critical-path <id>               # Longest dependency chain

Epics & Hierarchy

# Create an epic
td create "Auth System" --type epic --priority P1

# Add child tasks
td create "Login endpoint" --parent <epic-id>
td create "JWT validation" --parent <epic-id>

# View hierarchy
td tree <epic-id>                   # Visual tree
td list --epic <epic-id>            # All descendants
td epic list