# Td Task Management > 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. - Skill: `marcus/td-task-management` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add marcus/td-task-management` - Raw SKILL.md: https://api.skillmd.com/api/skills/marcus/td-task-management/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: marcus (https://skillmd.com/u/marcus) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/marcus/td-task-management --- # 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 # Begin work td log "OAuth callback implemented" # Track progress td log --decision "Using JWT tokens" # Log decisions td handoff --done "..." --remaining "..." # Capture state td review # 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 # 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 \ --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 `. ### Workflow 3: Reviewing Code ```bash # 1. See reviewable issues td reviewable # 2. Check details td show td context # 3. Approve or reject # Independent review: td approve --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 --reviewed-by "code-reviewer sub-agent" # you reviewed it yourself — say so: td approve --self-review --reason "Reviewed own diff, tests pass" # Or: td reject --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 ""` 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 ` - Begin work - `td unstart ` - Revert to open (undo accidental start) - `td log "msg"` - Track progress - `td log --decision "..."` - Log decision - `td log --blocker "..."` - Log blocker - `td show ` - View details - `td context ` - Full context for resuming ### Handing Off - `td handoff --done "..." --remaining "..."` - Single issue - `td ws handoff` - Multi-issue work session ### Reviews - `td review ` - Submit for review - `td reviewable` - Issues you can review - `td approve --reason "..."` - Approve an independent review - `td approve --reviewed-by ""` - Record who reviewed it when that is not you (trusted mode) - `td approve --self-review --reason "..."` - Acknowledge and record a trusted-mode self-review - `td approve --record-only --reason "..."` - Attest without closing; any session closes after - `td reject --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 --append --description-file -` - Append rich text from stdin - `td list` - List all - `td list --status in_progress` - Filter by status - `td block ` - Mark as blocked - `td delete ` - Delete ### File Tracking - `td link ` - Track files with issue - `td files ` - 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.