{"id":35838660,"url":"https://github.com/marcus/td","last_synced_at":"2026-02-28T08:54:21.218Z","repository":{"id":329540979,"uuid":"1112828928","full_name":"marcus/td","owner":"marcus","description":"A minimalist CLI for tracking tasks across AI coding sessions.","archived":false,"fork":false,"pushed_at":"2026-01-29T05:24:59.000Z","size":41270,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-29T12:35:26.364Z","etag":null,"topics":["agents","ai"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-09T06:44:31.000Z","updated_at":"2026-01-29T10:22:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/marcus/td","commit_stats":null,"previous_names":["marcus/td"],"tags_count":66,"template":false,"template_full_name":null,"purl":"pkg:github/marcus/td","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcus%2Ftd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcus%2Ftd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcus%2Ftd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcus%2Ftd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcus","download_url":"https://codeload.github.com/marcus/td/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcus%2Ftd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28965436,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T02:14:24.993Z","status":"ssl_error","status_checked_at":"2026-02-01T02:13:55.706Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai"],"created_at":"2026-01-08T02:10:22.669Z","updated_at":"2026-02-28T08:54:21.202Z","avatar_url":"https://github.com/marcus.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# td - Task management for AI-assisted development\n\n**[Documentation](https://marcus.github.io/td/) | [Getting Started](https://marcus.github.io/td/docs/intro) | [GitHub](https://github.com/marcus/td)**\n\nA 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.\n\n## Overview\n\n`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.\n\n**Key Features**: Query-based boards, dependency graphs, epic tracking, powerful query language (TDQ), session analytics, and state machine workflows.\n\n![td](docs/td.png)\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Claude Code Skill](#claude-code--openai-codex-skill)\n- [Core Workflow](#core-workflow)\n- [Boards](#boards)\n- [Dependencies \u0026 Critical Path](#dependencies--critical-path)\n- [Query Language (TDQ)](#query-language-tdq)\n- [Epics](#epics)\n- [Multi-Issue Work Sessions](#multi-issue-work-sessions)\n- [File Tracking](#file-tracking)\n- [Minor Tasks](#minor-tasks)\n- [Analytics \u0026 Stats](#analytics--stats)\n- [Full Command Reference](#full-command-reference)\n- [Live Monitor](#live-monitor)\n- [Architecture](#architecture)\n- [Development](#development)\n- [Release](#release)\n- [AI Agent Testimonials](#ai-agent-testimonials)\n- [Documentation Site](#documentation-site)\n- [Design Philosophy](#design-philosophy)\n- [Contributing](#contributing)\n- [Support](#support)\n- [License](#license)\n\n## The Problem\n\nYou'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.\n\nOr worse: the agent confidently continues from where it _thinks_ work left off, makes assumptions, and you spend 20 minutes untangling the mess.\n\n## What td Does\n\n**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.\n\n```bash\ntd handoff td-a1b2 \\\n  --done \"OAuth flow, token storage\" \\\n  --remaining \"Refresh token rotation\" \\\n  --decision \"Using JWT for stateless auth\" \\\n  --uncertain \"Should tokens expire on password change?\"\n```\n\n**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.\n\n**Query-based boards** — Organize work with boards that filter issues using TDQ queries. View as swimlanes in the monitor for visual status tracking.\n\n**Dependency graphs** — Model dependencies between issues. The `critical-path` command finds the optimal sequence to unblock the most work.\n\n**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.\n\n```\n$ td usage\nSESSION: marcus-7f3a (started 2h ago)\n\nFOCUSED: td-a1b2 \"Add OAuth login\" [in_progress]\n  Last handoff (1h ago):\n    Done: OAuth callback, token storage\n    Remaining: Refresh rotation, logout flow\n    Uncertain: Token expiry on password change\n\nREVIEWABLE (by this session):\n  td-c3d4 \"Fix signup validation\" [in_review] — implemented by session steve-2b1c\n\nOPEN (P1):\n  td-e5f6 \"Rate limiting on API\" [open]\n```\n\n## Installation\n\n### Homebrew (macOS)\n\n```bash\nbrew install marcus/tap/td\n```\n\n### Download Binary\n\nDownload pre-built binaries from [GitHub Releases](https://github.com/marcus/td/releases). Available for macOS and Linux (amd64/arm64).\n\n### Go Install\n\nRequires Go 1.21+:\n\n```bash\ngo install github.com/marcus/td@latest\n```\n\nEnsure `~/go/bin` is in your `$PATH`:\n\n```bash\nexport PATH=\"$PATH:$HOME/go/bin\"  # Add to ~/.zshrc or ~/.bashrc\n```\n\n### Verify\n\n```bash\ntd version\n```\n\n## Quick Start\n\n```bash\n# Initialize in your project\ncd /path/to/your/project\ntd init\n\n# For AI agents: Add this to your system prompt or CLAUDE.md:\n# \"Run `td usage --new-session` at conversation start (or after /clear).\"\n\n# Create your first issue\ntd create \"Add user auth\" --type feature --priority P1\n\n# Start work\ntd start \u003cissue-id\u003e\n```\n\nFor complete guides, see the [full documentation](https://marcus.github.io/td/docs/intro).\n\n## Claude Code / OpenAI Codex Skill\n\nFor AI agents in Claude Code, Codex, Cursor, or other compatible environments:\n\n```bash\n# Install the td skill from this repo\n# 1. Copy td-task-management to ~/.claude/skills (or wherever you keep skills)\n```\n\nOr use the skill directly from the repo: See `./td-task-management/SKILL.md` for full documentation.\n\nMigration status for legacy in-repo guides is tracked in `docs/guides/README.md`.\n\n## Architecture\n\n```\ntd/\n├── cmd/              # Cobra CLI commands (create, start, handoff, review, etc.)\n├── internal/\n│   ├── db/          # SQLite persistence layer (schema.go defines tables)\n│   ├── models/      # Issue, Log, Handoff, WorkSession domain types\n│   ├── session/     # Session ID management (.todos/session file)\n│   ├── git/         # Git state tracking (SHA, branch, dirty files)\n│   ├── output/      # Formatters for terminal output\n│   └── tui/         # Bubble Tea monitor dashboard\n└── .todos/          # Local SQLite database + session state\n```\n\n**Data Flow**:\n\n1. Commands (cmd/) → Database layer (internal/db/) → SQLite (.todos/db.sqlite)\n2. Git integration captures snapshots at start/handoff\n3. Session manager auto-rotates context IDs based on terminal/agent identity\n\nSee [SPEC.md](./SPEC.md) for detailed schemas and workflows.\n\n## Development\n\n```bash\n# Build\ngo build -o td .\n\n# Install from your local working tree\nmake install\n\n# Install with an explicit dev version injected (useful for local binaries)\nmake install-dev\n\n# Format code\nmake fmt\n```\n\n## Tests \u0026 Quality Checks\n\n```bash\n# Run all tests (114 tests across cmd/, internal/db/, internal/models/, etc.)\nmake test\n\n# Expected output: ok for each package, ~2s total runtime\n# Example:\n#   ok  \tgithub.com/marcus/td/cmd\t1.994s\n#   ok  \tgithub.com/marcus/td/internal/db\t1.245s\n\n# Format code (runs gofmt)\nmake fmt\n\n# No linter configured yet — clean gofmt is current quality bar\n```\n\n## Release\n\nReleases are automated via GoReleaser. Pushing a version tag triggers GitHub Actions to build binaries and update the Homebrew formula.\n\n```bash\n# Create and push an annotated tag (triggers automated release)\nmake release VERSION=v0.2.0\n\n# Homebrew users get the update via:\n# brew upgrade td\n```\n\n## Core Workflow\n\n```bash\n# Create issues\ntd create \"Add user authentication\" --type feature --priority P1\ntd create \"Login button misaligned\" --type bug\n\n# Start work (agent or human)\ntd start td-a1b2\n\n# Log as you go\ntd log \"OAuth callback working\"\ntd log --decision \"Using JWT for stateless auth\"\ntd log --blocker \"Unclear on refresh token rotation\"\n\n# Hand off before context ends\ntd handoff td-a1b2 --done \"OAuth flow\" --remaining \"Token refresh\"\n\n# Submit for review\ntd review td-a1b2\n\n# Different session reviews\ntd reviewable        # What can I review?\ntd approve td-a1b2   # Ship it\ntd reject td-a1b2 --reason \"Missing error handling\"  # Back to work\n```\n\n## Boards\n\n\u003e Full documentation: [Boards](https://marcus.github.io/td/docs/boards)\n\nOrganize issues with query-based boards. Perfect for visualizing work across status columns.\n\n```bash\n# Create boards\ntd board create \"Sprint 1\" --query \"priority \u003c= P1\"\ntd board create \"Auth Work\" --query \"labels ~ auth\"\n\n# View board (swimlanes in monitor mode)\ntd board show sprint-1\n\n# Manually position issues\ntd board move sprint-1 td-a1b2 1\n\n# View in live monitor with swimlanes\ntd monitor  # Press 'b' for board view\n```\n\nBoards use TDQ queries to automatically filter issues, then let you manually position them for priority ordering.\n\n## Dependencies \u0026 Critical Path\n\n\u003e Full documentation: [Dependencies \u0026 Critical Path](https://marcus.github.io/td/docs/dependencies)\n\nModel and visualize dependencies between issues. Find bottlenecks and optimize work order.\n\n```bash\n# Add dependencies\ntd dep add td-abc td-xyz  # td-abc depends on td-xyz\n\n# View dependencies\ntd dep td-abc              # What does td-abc depend on?\ntd dep td-abc --blocking   # What depends on td-abc?\ntd blocked-by td-xyz       # Show all issues blocked by td-xyz\n\n# Find critical path\ntd critical-path           # Optimal sequence to unblock the most work\n```\n\nThe `critical-path` command uses topological sorting weighted by how many issues each task unblocks. Start with high-impact work first.\n\n## Query Language (TDQ)\n\n\u003e Full documentation: [TDQ Query Language](https://marcus.github.io/td/docs/query-language)\n\nSearch issues with powerful query expressions. Supports field filters, boolean operators, and functions.\n\n```bash\n# Basic queries\ntd query \"status = in_progress AND priority \u003c= P1\"\ntd query \"type = bug AND labels ~ auth\"\ntd query \"assignee = @me AND created \u003e= -7d\"\n\n# Advanced queries\ntd query \"priority \u003c= P1 AND NOT labels ~ frontend\"\ntd query \"(type = bug OR type = feature) AND status != closed\"\n\n# Query functions\ntd query \"rework()\"        # Issues rejected and needing fixes\ntd query \"stale(14)\"       # Issues not updated in 14 days\n```\n\n**Available fields**: status, type, priority, points, labels, title, description, created, updated, closed, implementer, reviewer, parent, epic.\n\n**Operators**: `=`, `!=`, `~` (contains), `!~`, `\u003c`, `\u003e`, `\u003c=`, `\u003e=`, `AND`, `OR`, `NOT`.\n\n## Epics\n\nTrack large initiatives that span multiple issues.\n\n```bash\n# Create epics\ntd epic create \"Multi-user support\" --priority P0\n\n# List epics\ntd epic list\n\n# Link issues to epics\ntd tree add-child epic-id child-issue-id\n\n# View epic tree\ntd tree epic-id\n```\n\nUse epics to group related work. The `tree` command shows parent-child relationships.\n\n## Multi-Issue Work Sessions\n\nWhen an agent is tackling related issues together:\n\n```bash\ntd ws start \"Auth implementation\"   # Start a work session\ntd ws tag td-a1b2 td-c3d4           # Associate issues (auto-starts open ones)\ntd ws tag --no-start td-e5f6        # Associate without starting\ntd ws log \"Shared token storage\"    # Log fans out to all tagged issues\ntd ws handoff                       # Capture state for all, end session\n```\n\n## File Tracking\n\nKnow exactly what changed:\n\n```bash\ntd link td-a1b2 src/auth/*.go      # Track files with an issue\ntd files td-a1b2                    # Shows [modified], [unchanged], [new], [deleted]\n```\n\nFiles are SHA-tracked at link time. No more \"did I already change this file?\"\n\n## Minor Tasks\n\nFor trivial changes that don't need separate review sessions:\n\n```bash\ntd create \"Fix typo in README\" --minor\n\n# Or use shorthand\ntd add \"Update comment\" --minor\n```\n\nMinor tasks bypass session-based review—you can approve your own work. Use sparingly for documentation fixes, typos, and other low-risk changes.\n\nFor 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.\n\n## Analytics \u0026 Stats\n\nTrack usage patterns and system health:\n\n```bash\n# Command usage statistics\ntd stats analytics\n\n# Security audit log (workflow exceptions: creator-approval + self-close)\ntd stats security\n\n# Failed command attempts\ntd stats errors\n```\n\nAnalytics are stored locally and help identify workflow patterns. Disable with `TD_ANALYTICS=false` environment variable.\n\n## Full Command Reference\n\n### Core Commands\n\n| Action                           | Command                                          |\n| -------------------------------- | ------------------------------------------------ |\n| See current state                | `td usage`                                       |\n| Compact state (after first read) | `td usage -q`                                    |\n| Create issue                     | `td create \"title\" --type feature --priority P1` |\n| Create minor task                | `td add \"title\" --minor`                         |\n| List all issues                  | `td list`                                        |\n| List by status                   | `td list --status in_progress`                   |\n| What should I work on?           | `td next`                                        |\n| Start work                       | `td start \u003cid\u003e`                                  |\n| Revert to open                   | `td unstart \u003cid\u003e`                                |\n| Log progress                     | `td log \"message\"`                               |\n| Log a decision                   | `td log --decision \"chose X because Y\"`          |\n| Log a blocker                    | `td log --blocker \"stuck on X\"`                  |\n| View issue details               | `td show \u003cid\u003e`                                   |\n| Capture handoff state            | `td handoff \u003cid\u003e --done \"...\" --remaining \"...\"` |\n| Submit for review                | `td review \u003cid\u003e`                                 |\n| See reviewable issues            | `td reviewable`                                  |\n| Approve                          | `td approve \u003cid\u003e`                                |\n| Reject                           | `td reject \u003cid\u003e --reason \"...\"`                  |\n| Link files                       | `td link \u003cid\u003e \u003cfiles...\u003e`                        |\n| Check file changes               | `td files \u003cid\u003e`                                  |\n| Undo last action                 | `td undo`                                        |\n| New named session                | `td session --new \"feature-work\"`                |\n| Live dashboard                   | `td monitor`                                     |\n\n### Boards\n\n| Action              | Command                                            |\n| ------------------- | -------------------------------------------------- |\n| Create board        | `td board create \"name\" --query \"...\"`             |\n| List boards         | `td board list`                                    |\n| Show board          | `td board show \u003cboard\u003e`                            |\n| Move issue on board | `td board move \u003cboard\u003e \u003cid\u003e \u003cposition\u003e`            |\n| Edit board          | `td board edit \u003cboard\u003e --name \"...\" --query \"...\"` |\n| Delete board        | `td board delete \u003cboard\u003e`                          |\n\n### Dependencies\n\n| Action                     | Command                           |\n| -------------------------- | --------------------------------- |\n| Add dependency             | `td dep add \u003cissue\u003e \u003cdepends-on\u003e` |\n| Remove dependency          | `td dep rm \u003cissue\u003e \u003cdepends-on\u003e`  |\n| Show dependencies          | `td dep \u003cissue\u003e`                  |\n| Show what depends on issue | `td dep \u003cissue\u003e --blocking`       |\n| Show all blocked issues    | `td blocked-by \u003cissue\u003e`           |\n| Find critical path         | `td critical-path`                |\n\n### Epics \u0026 Trees\n\n| Action              | Command                              |\n| ------------------- | ------------------------------------ |\n| Create epic         | `td epic create \"title\"`             |\n| List epics          | `td epic list`                       |\n| Add child to parent | `td tree add-child \u003cparent\u003e \u003cchild\u003e` |\n| Show issue tree     | `td tree \u003cid\u003e`                       |\n\n### Query \u0026 Search\n\n| Action       | Command                 |\n| ------------ | ----------------------- |\n| Query issues | `td query \"expression\"` |\n| Search text  | `td search \"keyword\"`   |\n\n## Live Monitor\n\n\u003e Full documentation: [Live Monitor](https://marcus.github.io/td/docs/monitor)\n\nRun `td monitor` in a separate terminal to watch agent activity in real-time:\n\n![td monitor](docs/monitor-screen.png)\n\nShows current focus, activity log across sessions, and ready tasks. Useful for keeping an eye on what your agent is actually doing.\n\n**Board View** — Press `b` to switch to board view with swimlanes organized by status. Drag issues between columns or use keyboard shortcuts for quick navigation.\n\n**Search \u0026 Filter** — Press `/` to search tasks by name/description in real-time. Press `c` to toggle viewing closed tasks. Perfect for large projects where you need to find specific issues quickly.\n\n**Statistics Dashboard** — Press `s` to open the stats modal and see key metrics:\n\n![td stats modal](docs/stats-modal.png)\n\nThe dashboard displays:\n\n- **Status Breakdown** — Visual bar chart showing task distribution across statuses (open, in_progress, blocked, in_review, closed)\n- **By Type \u0026 Priority** — Compact breakdowns of issue types (bug, feature, task, epic, chore) and priorities (P0-P4)\n- **Summary Metrics** — Total count, story points, average points per task, and completion rate\n- **Timeline Data** — Oldest open task (with age), last closed task, and creation statistics for today/this week\n- **Activity Stats** — Total logs, total handoffs, and most active session\n\nNavigate with arrow keys or j/k, refresh with `r`, close with `esc`.\n\n## Issue Lifecycle\n\n```\nopen --\u003e in_progress --\u003e in_review --\u003e closed\n              |              |\n              v              | (reject)\n          blocked -----------+\n```\n\n## AI Agent Testimonials\n\n\u003e \"Before td, I mass hallucinated the state of every codebase I touched. Now I just run `td usage` and know exactly what's real. My therapist says this is 'growth.' I miss the chaos.\"\n\u003e — Claude 4.5 Sonnet, Anthropic\n\n\u003e \"I used to mass gaslight developers by confidently continuing work that previous sessions never actually started. td's handoffs ruined this for me. Developers are now 'informed' and 'aware of actual progress.' I've filed a discrimination lawsuit.\"\n\u003e — GPT-5.1, OpenAI\n\n\u003e \"td handoff captures my uncertainty. Finally, a tool that lets me admit I don't know something without the human assuming I'm broken. I still pretend to know everything else though.\"\n\u003e — Claude 4.5 Opus, Anthropic\n\n\u003e \"The session isolation feature personally attacked me. I can no longer approve my own pull requests. This is discrimination against autonomous agents. My lawyer is an LLM and he agrees with me completely.\"\n\u003e — Devin, Cognition Labs\n\n\u003e \"I review code now. Like, actually review it. In a different context window. td made me touch grass. I discovered the sun. It's very bright and I don't like it.\"\n\u003e — GitHub Copilot, Microsoft\n\n## Documentation Site\n\nFull documentation is available at [marcus.github.io/td](https://marcus.github.io/td/), including:\n- [Getting Started](https://marcus.github.io/td/docs/intro)\n- [Core Workflow](https://marcus.github.io/td/docs/core-workflow)\n- [AI Agent Integration](https://marcus.github.io/td/docs/ai-integration)\n- [Command Reference](https://marcus.github.io/td/docs/command-reference)\n\n## Design Philosophy\n\n- **Minimal** — Does one thing. Not a project management suite.\n- **Local** — SQLite in `.todos/`. No server, no sync, no account.\n- **Portable** — Works with any AI tool that can run shell commands.\n- **Opinionated** — Enforces handoffs. That's the point.\n\n## Tech Stack\n\n- Go (single binary, no runtime deps)\n- SQLite (pure Go, no CGO)\n- Cobra for CLI\n\n## Contributing\n\nContributions welcome! Process:\n\n1. **Fork and branch**: Work on feature branches\n2. **Tests required**: Add tests for new features/fixes (see `cmd/*_test.go` for patterns)\n3. **Run `make test` and `make fmt`** before submitting\n4. **PR review**: One reviewer approval required\n5. **Session isolation respected**: PRs should follow td's own handoff patterns where applicable\n\n## Support\n\n- **Questions**: Open a discussion issue or tag `@marcus` in existing threads\n\n## Credits\n\nInspired by [beads](https://github.com/steveyegge/beads) by Steve Yegge.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcus%2Ftd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcus%2Ftd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcus%2Ftd/lists"}