Skip to main content

Getting Started

td is a minimalist CLI for tracking tasks across AI coding sessions. It acts as external memory for your project -- so the next agent session picks up exactly where the last one left off, without pasting context or re-explaining state.

The Problem​

Context loss across AI sessions is expensive. An agent does meaningful work, the session ends, and the next session has no idea what happened. You paste context, get misunderstandings, waste time re-orienting. Or worse: the agent confidently continues from the wrong state, undoing good work or duplicating effort.

There's no structured way to say "here's what's done, here's what remains, here's what I was uncertain about."

How td Solves It​

Three mechanisms eliminate context loss:

  • Structured handoffs -- Each session records what's done, what remains, decisions made, and uncertainties. The next session reads this instead of guessing.
  • Audited review -- Independent review is preferred. In the default trusted mode, an involved session may instead record who actually reviewed the work (--reviewed-by "<who>") or acknowledge a self-review (--self-review --reason); every path stays visible in the review history.
  • Single-command context -- td usage gives the incoming session everything it needs: current issues, recent logs, pending handoffs, and what to work on next.

Installation​

Homebrew (macOS)​

brew install marcus/tap/td

Download Binary​

Download pre-built binaries from GitHub Releases. Available for macOS and Linux (amd64/arm64).

Go Install​

# Requirements: Go 1.21+
go install github.com/marcus/td@latest

# Ensure ~/go/bin is in PATH
export PATH="$PATH:$HOME/go/bin"

Verify​

td version
tip

If td version prints nothing, confirm that ~/go/bin is in your shell's PATH and restart your terminal.

Quick Start​

cd /path/to/your/project
td init

# Create first issue
td create "Add user auth" --type feature --priority P1

# Start work
td start td-a1b2

# Log progress
td log "OAuth callback working"

# Hand off before context ends
td handoff td-a1b2 --done "OAuth flow" --remaining "Token refresh"

# Submit for review
td review td-a1b2
info

Issue IDs like td-a1b2 are generated automatically when you create an issue. Use td list to see your current issues and their IDs.

Setting Up with AI Agents​

Add this to your CLAUDE.md, system prompt, or agent instructions:

Use td when durable task context will help. At the start of a new agent
context, run `td usage --new-session -q`. Run `td usage` for workflow guidance.

This gives the agent current work, recent activity, and pending reviews without repeating the full workflow on every context.

Works with Claude Code, Cursor, Codex, Copilot, and Gemini CLI.

Next Steps​

  • Core Workflow -- Issue lifecycle, logging, handoffs, and reviews in depth
  • Boards -- Visual overview of issue status across your project
  • Query Language -- Filter and search issues with structured queries