TD.md

name	description
td	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. Close — When work is complete:

   td close <issue-id>       # Mark done
   td review <issue-id>      # Submit for review first

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)

td start <id>           # open → in_progress (sets focus)
td block <id>           # → blocked
td unblock <id>         # → open
td review <id>          # → in_review (requires handoff)
td approve <id>         # → closed
td reject <id>          # → in_progress (rework)
td close <id>           # → closed (skip review)
td reopen <id>          # → open

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                        # List all epics with progress

Session Management

td session "working on auth"        # Name current session
td session --new                    # Start fresh session
td whoami                           # Show current session identity
td focus <id>                       # Set focus without starting
td unfocus                          # Clear focus
td resume <id>                      # Show context + set focus

Inspecting Issues

td show <id>                        # Full detail with logs, handoffs, comments
td show <id> --children             # Include child issues
td comments <id>                    # List comments
td comment <id> "Note about this"   # Add a comment

Useful Shortcuts

td status                # Dashboard: session, focus, reviews, blocked, ready
td next                  # Highest-priority open issue
td ready                 # Open issues sorted by priority
td blocked               # All blocked issues
td in-review             # Issues awaiting review
td reviewable            # Issues you can review
td deleted               # Soft-deleted issues
td restore <id>          # Restore deleted issue

Guidelines

• Always start sessions with td usage --new-session or td status
• Log as you go — decisions, blockers, and attempts are valuable for future sessions
• Handoff before stopping — structured handoffs make resumption seamless
• Use epics to group related work and track progress
• Use dependencies to make blocking relationships explicit
• Use boards to save frequently-used queries
• P0 = drop everything, P1 = do next, P2 = default, P3 = backlog, P4 = someday