---
name: td-task-management
description: Task management for AI agents across context windows. Use when agents need to track work, log progress, hand off state, and maintain context across sessions. Includes workflows for single-issue focus, multi-issue work sessions, and structured handoffs. Essential for AI-assisted development where context windows reset between sessions.
---

# td - Task Management for AI Agents

## Overview

`td` is a minimalist CLI for tracking tasks and maintaining agent memory across context windows. When your AI session ends, `td` captures what was done, what remains, and what decisions were made—so the next session picks up exactly where the last one left off.

**Core capability:** Run `td usage` and get everything needed for the next action—current focus, pending reviews, open issues, recent decisions.

## Quick Start

### Starting a New Agent Context

```bash
td usage --new-session -q  # Auto-rotate and show compact current state
```

Use `td usage` without `-q` when workflow guidance would be useful. Status
output includes:
- Active work sessions and recent decisions
- What issues are pending review (you can review these)
- Highest priority open issues
- Recent handoffs from previous sessions

### Single-Issue Workflow

For focused work on one issue:

```bash
td start <issue-id>                    # Begin work
td log "OAuth callback implemented"    # Track progress
td log --decision "Using JWT tokens"   # Log decisions
td handoff <id> --done "..." --remaining "..."  # Capture state
td review <id>                         # Submit for review
```

### Multi-Issue Workflow

For agents handling related issues:

```bash
td ws start "Auth implementation"      # Start work session
td ws tag td-a1b2 td-c3d4             # Associate issues (auto-starts them)
td ws tag --no-start td-e5f6          # Associate without starting
td ws log "Shared token storage"       # Log to all tagged issues
td ws handoff                          # Capture state, end session
```

## Key Workflows

### Workflow 1: Starting New Work

```bash
# 1. Check what to work on
td usage          # See current state
td next           # Highest priority open issue
td critical-path  # What unblocks most work

# 2. Start work
td start <id>

# 3. Begin logging
td log "Started implementation"
```

### Workflow 2: Handing Off Work

Use a structured handoff when work will continue in another context:

```bash
td handoff <id> \
  --done "OAuth flow, token storage" \
  --remaining "Refresh token rotation, error handling" \
  --decision "Using JWT for stateless auth" \
  --uncertain "Should tokens expire on password change?"
```

Keys:
- `--done` - What is complete
- `--remaining` - What remains
- `--decision` - Why you chose approach X
- `--uncertain` - What you're unsure about

Next session will see all this context with `td usage` or `td context <id>`.

### Workflow 3: Reviewing Code

```bash
# 1. See reviewable issues
td reviewable

# 2. Check details
td show <id>
td context <id>

# 3. Approve or reject
# Independent review:
td approve <id> --reason "Reviewed diff, looks good"
# Or, in trusted mode, when you implemented it yourself:
#   a sub-agent reviewed it — name them (no --reason needed):
td approve <id> --reviewed-by "code-reviewer sub-agent"
#   you reviewed it yourself — say so:
td approve <id> --self-review --reason "Reviewed own diff, tests pass"
# Or:
td reject <id> --reason "Missing error handling"
```

Independent review is preferred when practical. The default `trusted` mode also
lets an involved session approve by saying who reviewed the work: `--reviewed-by
"<who>"` credits someone else, `--self-review --reason` owns it. Both are
recorded and neither is verifiable by td, so never name a reviewer who did not
review — that reads as independent in the audit trail, which is worse than an
honest self-review. In `delegated` and `strict` an involved session cannot
approve at all.

### Workflow 4: Handling Blockers

```bash
# 1. Log the blocker
td log --blocker "Waiting on API spec from backend team"

# 2. Work on something else
td next              # Get another issue
td ws tag td-e5f6   # Add to work session

# 3. Come back to blocked issue later
td context td-a1b2  # Refresh context when blocker resolves
```

## Commands by Category

### Checking Status
- `td usage` - Current state, reviews, next steps
- `td usage -q` - Compact current state
- `td current` - What you're working on
- `td ws current` - Current work session state
- `td next` - Highest priority open
- `td critical-path` - What unblocks most work

### Working on Issues
- `td start <id>` - Begin work
- `td unstart <id>` - Revert to open (undo accidental start)
- `td log "msg"` - Track progress
- `td log --decision "..."` - Log decision
- `td log --blocker "..."` - Log blocker
- `td show <id>` - View details
- `td context <id>` - Full context for resuming

### Handing Off
- `td handoff <id> --done "..." --remaining "..."` - Single issue
- `td ws handoff` - Multi-issue work session

### Reviews
- `td review <id>` - Submit for review
- `td reviewable` - Issues you can review
- `td approve <id> --reason "..."` - Approve an independent review
- `td approve <id> --reviewed-by "<who>"` - Record who reviewed it when that is not you (trusted mode)
- `td approve <id> --self-review --reason "..."` - Acknowledge and record a trusted-mode self-review
- `td approve <id> --record-only --reason "..."` - Attest without closing; any session closes after
- `td reject <id> --reason "..."` - Reject

### Creating/Managing Issues
- `td create "title" --type feature --priority P1` - Create
- `td create "title" --description-file body.md --acceptance-file acceptance.md` - Agent-safe rich text
- `cat body.md | td update <id> --append --description-file -` - Append rich text from stdin
- `td list` - List all
- `td list --status in_progress` - Filter by status
- `td block <id>` - Mark as blocked
- `td delete <id>` - Delete

### File Tracking
- `td link <id> <files...>` - Track files with issue
- `td files <id>` - Show file changes

### Other
- `td monitor` - Live dashboard
- `td session --new "name"` - Force new session
- `td undo` - Undo last action

See [quick_reference.md](references/quick_reference.md) for full command listing.

## Resources

### [quick_reference.md](references/quick_reference.md)
Complete command reference organized by task type.

### [ai_agent_workflows.md](references/ai_agent_workflows.md)
Detailed workflows for common AI agent scenarios:
- Single-issue focus
- Multi-issue work sessions
- Handling blockers
- Resuming work
- Code review process
- Tips for AI agents

## Issue Lifecycle

```
open → in_progress → in_review → closed
         |              |
         v              | (reject)
     blocked -----------+
```

## Key Principles

**Session Isolation:** Every terminal/context gets a session ID for continuity
and audit. Independent review is preferred; trusted mode also lets an involved
session approve by recording who actually reviewed the work.

**Structured Handoffs:** Record done/remaining/decisions/uncertain when another
context will need to continue the work.

**Minimal:** Does one thing. Single binary, SQLite local storage (`.todos/`), no server, works with any AI tool.

## For AI Agents

At the start of a new agent context:
```bash
td usage --new-session -q
```

This auto-rotates sessions and gives you compact current state. Use judgment
about how much tracking detail each task needs:

1. **Single focused issue** → Use single-issue workflow
2. **Multiple related issues** → Use `td ws start` for work sessions
3. **Work will continue elsewhere** → Use `td handoff` or `td ws handoff`
4. **A decision aids continuity** → Log it with `--decision`
5. **An uncertainty matters** → Record it with `--uncertain`
6. **Track files** → Use `td link` so future sessions know what changed

See [ai_agent_workflows.md](references/ai_agent_workflows.md) for detailed examples.