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:
- 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
-
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 -
Start an issue — Set focus and mark in-progress:
td start <issue-id> # Sets focus + status to in_progress -
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 -
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?" -
Submit for review — When work is complete:
td review <issue-id> # Submit for review (preferred) -
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/rejectfor non-trivial work — don't skip toclose closeis for admin purposes only: duplicates, won't-fix, trivial/minor tasks- Session isolation: the session that implements can't approve its own work
rejectsends work back toin_progressfor 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 # 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-sessionortd 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