@@ -13,30 +13,30 @@ Install with `mise use -g cargo:https://git.secluded.site/yatd@latest` or
skill with `td skill`, then somehow referring to td when telling the agent to
do something involving td. It shouldn't invoke the skill unless you mention td,
allowing your agent to use other todo/issue tools in other repos even with this
-global skill. Td IDs are prefixed with `td-`, so pasting the ID should be
-enough of a mention.
+global skill.
+
+Inspired by [alosec/td].
+
+[alosec/td]: https://github.com/alosec/td/
## Sync Bootstrapping
-When bringing a project to a second machine, do **not** run `td init` again.
-Initialize once on the first machine, then bootstrap the second machine by
-running `td sync` and entering the wormhole code from the first machine.
+When syncing a project to another machine, do **not** run `td init` on
+the other machine. Initialize just once on the first machine, then
+bootstrap others by running `td sync` on the first machine, then `td
+sync wormhole-code` on another.
```sh
-# Machine A (already initialized project)
+# Machine A (already initialized)
td sync
# Machine B (same repo checkout, no td project yet)
-td sync <code-from-machine-a>
+td sync 5-lurid-gecko
```
Running `td init` on both machines creates different `project_id` values and
prevents sync from merging them.
-Inspired by [alosec/td].
-
-[alosec/td]: https://github.com/alosec/td/
-
```
$ td --help
Todo tracker for AI agents
@@ -44,31 +44,35 @@ Todo tracker for AI agents
Usage: td [OPTIONS] <COMMAND>
Commands:
- init Initialize .td directory
- create Create a new task [aliases: add]
- list List tasks [aliases: ls]
- show Show task details
- log Append a work log entry to a task
- update Update a task
- done Mark task(s) as closed [aliases: close]
- rm Delete task(s)
- reopen Reopen task(s)
- dep Manage dependencies / blockers
- label Manage labels
- search Search tasks by title or description
- ready Show tasks with no open blockers
- next Recommend next task(s) to work on
- stats Show task statistics (always JSON)
- compact Vacuum the database
- export Export tasks to JSONL (one JSON object per line)
- import Import tasks from a JSONL file
- skill Install the agent skill file (SKILL.md)
- help Print this message or the help of the given subcommand(s)
+ init Initialize a central project and bind the current directory to it
+ use Bind the current directory to an existing project
+ projects List all known projects in central storage
+ create Create a new task [aliases: add]
+ list List tasks [aliases: ls]
+ show Show task details
+ log Append a work log entry to a task
+ update Update a task
+ done Mark task(s) as closed [aliases: close]
+ rm Delete task(s)
+ reopen Reopen task(s)
+ dep Manage dependencies / blockers
+ label Manage labels
+ search Search tasks by title or description
+ ready Show tasks with no open blockers
+ next Recommend next task(s) to work on
+ stats Show task statistics (always JSON)
+ compact Vacuum the database
+ export Export tasks to JSONL (one JSON object per line)
+ import Import tasks from a JSONL file
+ sync Sync project state with a peer via magic wormhole
+ skill Install the agent skill file (SKILL.md)
+ help Print this message or the help of the given subcommand(s)
Options:
- -j, --json Output JSON
- -h, --help Print help
- -V, --version Print version
+ -j, --json Output JSON
+ --project <PROJECT> Select a project explicitly (overrides cwd binding)
+ -h, --help Print help
+ -V, --version Print version
```
## Contributions
@@ -3,20 +3,21 @@ name: managing-tasks-with-td
description: Manages tasks with the td CLI. Use when tracking work items, creating todos, managing task dependencies, or when the user mentions td, tasks, or todos in a project using td. When the project obviously uses something else, or the user doesn't mention td explicitly, do not read.
---
-Don't forget the single quotes around `'EOF'` HEREDOCs; they disable shell
-interpolation, preventing it from messing up Markdown in the description.
+Don't forget the single quotes around `'EOF'` HEREDOCs; they disable
+shell interpolation, preventing it from messing up Markdown in the
+description.
## Projects and initialisation
-Storage is central (`~/.local/share/td/`), not per-directory. Each project
-is a named Loro CRDT document. Directories are bound to projects via
-`td init` or `td use`; the binding is resolved by longest-prefix match on
-the canonical path. You can also override with `--project <name>` or the
-`TD_PROJECT` env var.
+Storage is central (`~/.local/share/td/`), not per-directory. Each
+project is a named Loro CRDT document. Directories are bound to projects
+via `td init` or `td use`; the binding is resolved by longest-prefix
+match on the canonical path. You can also override with `--project
+<name>` or the `TD_PROJECT` env var.
-For multi-machine setup, initialize only once. On the second machine, bootstrap
-from the first with `td sync` instead of `td init` so both sides share the same
-project identity.
+For multi-machine setup, initialize only once. On others, bootstrap from
+the first with `td sync` instead of `td init` so both sides share the
+same project identity.
```bash
td init myproject # create project + bind cwd to it
@@ -30,13 +31,13 @@ TD_PROJECT=other td list # env override
## General reference
-These are not your most-used commands, nor are they the most critical, but you
-still need reference for them. The sections following are more important than
-this one and thus contain more instruction.
+These are not your most-used commands, nor are they the most critical,
+but you still need reference for them. The sections following are more
+important than this one and thus contain more instruction.
Task IDs are 26-character ULIDs. Most commands accept a unique prefix as
-shorthand (e.g. the first 7 characters shown in table output). If the prefix
-is ambiguous, td will tell you.
+shorthand (e.g. the first 7 characters shown in table output). If the
+prefix is ambiguous, td will tell you.
Deletion is a soft delete (sets `deleted_at` and marks the task closed).
Deleted tasks are hidden from `list`/`ready`/`next` but still visible to
@@ -68,9 +69,10 @@ Flags:
- -e effort: low, medium (default), high
- -t type -d desc -l labels (csv)
-Titles and bodies should stand on their own a year from now, not requiring
-additional context to understand the nuances but including those nuances
-directly at task creation or by adding them later through logs.
+Titles and bodies should stand on their own a year from now, not
+requiring additional context to understand the nuances but including
+those nuances directly at task creation or by adding them later through
+logs.
```bash
td create "Panic in token_refresh when OAuth provider returns HTTP 429" \
@@ -118,7 +120,16 @@ td create "Child task" --parent td-a1b2c3 # for splitting tasks into smaller chu
## Dependencies
-These are a core part of td; use them liberally, but appropriately. The `next` and `ready` commands both filter tasks with blockers so you have an easier time ordering work. Blocker relationships also make obvious opportunities for parallel work. When there are opportunities for parallelisation, and you have a subagent tool with write capabilities, and the tasks are small, ask the user whether they want you to invoke subagents for them. If the tasks aren't quite scoped well enough yet, ask whether they would like you to interview/question them regarding the gaps that need filling. DO NOT parallelise work without EXPLICIT user confirmation.
+These are a core part of td; use them liberally, but appropriately. The
+`next` and `ready` commands both filter tasks with blockers so you have
+an easier time ordering work. Blocker relationships also make obvious
+opportunities for parallel work. When there are opportunities for
+parallelisation, and you have a subagent tool with write capabilities,
+and the tasks are small, ask the user whether they want you to invoke
+subagents for them. If the tasks aren't quite scoped well enough yet,
+ask whether they would like you to interview/question them regarding the
+gaps that need filling. DO NOT parallelise work without EXPLICIT user
+confirmation.
```bash
td dep add td-child td-blocker # child waits for blocker to close
@@ -139,9 +150,26 @@ td reopen td-a1b2c3 # only on explicit user request
## Logging and looking for work
-These, and `show` of course, but that one's self-explanatory, are your most-run `td` commands.
-