内容摘录
td - Task management for AI-assisted development
**Documentation | Getting Started | GitHub**
A minimalist CLI for tracking tasks across AI coding sessions. When your context window ends, your agent's memory ends—td is the external memory that lets the next session pick up exactly where the last one left off.
Overview
td is a lightweight CLI for tracking tasks across AI coding sessions. It provides structured handoffs (done/remaining/decisions/uncertain) so new sessions continue from accurate state instead of guessing. Session-based review workflows prevent "works on my context" bugs. Works with Claude Code, Cursor, Copilot, and any AI that runs shell commands.
**Key Features**: Query-based boards, dependency graphs, epic tracking, powerful query language (TDQ), session analytics, and state machine workflows.
!td
Table of Contents
Installation
Quick Start
Claude Code Skill
Core Workflow
Boards
Dependencies & Critical Path
Query Language (TDQ)
Epics
Multi-Issue Work Sessions
File Tracking
Minor Tasks
Analytics & Stats
Full Command Reference
Live Monitor
Architecture
Development
Release
AI Agent Testimonials
Documentation Site
Design Philosophy
Contributing
Support
License
The Problem
You're using Claude Code, Cursor, Codex, or Copilot. Your AI agent does great work, then the session ends. New session starts. It has no idea what happened. You paste in context. It misunderstands. You correct it. Repeat.
Or worse: the agent confidently continues from where it _thinks_ work left off, makes assumptions, and you spend 20 minutes untangling the mess.
What td Does
**Structured handoffs** — Not "here's what I did" but specifically: what's done, what remains, what decisions were made, what's uncertain. The next session doesn't guess.
**Session isolation** — Every terminal/context window gets an ID (automatically). The session that writes code can't approve it. A different session has to review. This isn't process theater—it forces actual handoffs and catches the "works on my context" bugs.
**Query-based boards** — Organize work with boards that filter issues using TDQ queries. View as swimlanes in the monitor for visual status tracking.
**Dependency graphs** — Model dependencies between issues. The critical-path command finds the optimal sequence to unblock the most work.
**Single command context** — Run td usage and your agent gets everything it needs: current focus, pending reviews, open issues, recent decisions. No prompt engineering required.
Installation
Homebrew (macOS)
Download Binary
Download pre-built binaries from GitHub Releases. Available for macOS and Linux (amd64/arm64).
Go Install
Requires Go 1.21+:
Ensure ~/go/bin is in your $PATH:
Verify
Quick Start
For complete guides, see the full documentation.
Claude Code / OpenAI Codex Skill
For AI agents in Claude Code, Codex, Cursor, or other compatible environments:
Or use the skill directly from the repo: See ./td-task-management/SKILL.md for full documentation.
Migration status for legacy in-repo guides is tracked in docs/guides/README.md.
Architecture
**Data Flow**:
Commands (cmd/) → Database layer (internal/db/) → SQLite (.todos/db.sqlite)
Git integration captures snapshots at start/handoff
Session manager auto-rotates context IDs based on terminal/agent identity
See SPEC.md for detailed schemas and workflows.
Development
Tests & Quality Checks
Release
Releases are automated via GoReleaser. Pushing a version tag triggers GitHub Actions to build binaries and update the Homebrew formula.
Core Workflow
Boards
Full documentation: Boards
Organize issues with query-based boards. Perfect for visualizing work across status columns.
Boards use TDQ queries to automatically filter issues, then let you manually position them for priority ordering.
Dependencies & Critical Path
Full documentation: Dependencies & Critical Path
Model and visualize dependencies between issues. Find bottlenecks and optimize work order.
The critical-path command uses topological sorting weighted by how many issues each task unblocks. Start with high-impact work first.
Query Language (TDQ)
Full documentation: TDQ Query Language
Search issues with powerful query expressions. Supports field filters, boolean operators, and functions.
**Available fields**: status, type, priority, points, labels, title, description, created, updated, closed, implementer, reviewer, parent, epic.
**Operators**: =, !=, ~ (contains), !~, <, >, <=, >=, AND, OR, NOT.
Epics
Track large initiatives that span multiple issues.
Use epics to group related work. The tree command shows parent-child relationships.
Multi-Issue Work Sessions
When an agent is tackling related issues together:
File Tracking
Know exactly what changed:
Files are SHA-tracked at link time. No more "did I already change this file?"
Minor Tasks
For trivial changes that don't need separate review sessions:
Minor tasks bypass session-based review—you can approve your own work. Use sparingly for documentation fixes, typos, and other low-risk changes.
For non-minor tasks, td now supports a balanced review policy (on by default): the creator can approve only if a different session implemented the issue, and the approval must include a reason. Implementers still cannot approve their own implementation.
Analytics & Stats
Track usage patterns and system health:
Analytics are stored locally and help identify workflow patterns. Disable with TD_ANALYTICS=false environment variable.
Full Command Reference
Core Commands
| Action | Command |
| -------------------------------- | ------------------------------------------------ |
| See current state | td usage |
| Compact state (after first read) | td usage -q |
| Create issue | td create "title" --type feature --priority P1 |
| Create minor task | td add "title" --minor |
| List all issues | td list |
| List by status | td list --status in_progress |
| What should I work on? | td next |
| Start work | td start <id> |
| Revert to open | td unstart <id> |
| Log …