| name | tda |
| description | Work tasks from the tda task manager as an AI agent — find a claimable task (globally or for the current repo), claim it, pull ancestor context, refine into subtasks, log progress notes, and complete it. Use when asked to "work on the next task", "pick a task", or to create/update tasks in tda. |
tda for agents
tda is a keyboard-first task manager with a JSON CLI. Every command prints
JSON (except context, which prints Markdown). IDs are ULIDs; short unique
prefixes are accepted in the TUI, but pass full ids from JSON output. Full
command + flag reference: reference/cli.md — read it when
you need a flag you don't remember.
The CLI is safe to run while a human has the TUI open: the TUI owns the db and
serves your commands over a socket, so your writes show up live in their view.
See "Concurrency" in reference/cli.md.
Your identity (whoami)
You act under one actor id, shaped <harness>/<model>, e.g.
claude-code/opus-4-8 or opencode/gpt-5. Pick it once from your own
harness + model and reuse it as <me> everywhere below. There is no tda
command that knows who you are — the id is yours to supply.
State it up front. When you find, claim, assign, or note a task — or when
the user asks "whoami" / /tda whoami — say which actor id you are using, e.g.
"Acting as claude-code/opus-4-8." So the user (and other agents sharing the
store) can see who did what.
Users assign work to you with tda assign <id> <actor>; an unassigned todo
task is claimable by anyone.
The work loop
- Find a task:
- for the current repo:
tda next --as <me> --claimable --here
- globally:
tda next --as <me> --claimable
--claimable returns only tasks you may actually claim: todo,
unassigned-or-assigned-to-you, not blocked. First hit = highest priority.
- Claim it:
tda claim <id> --as <me> → status becomes wip, you are
recorded as the claimer. A denial (already claimed, assigned to someone
else, blocked) is a normal outcome — pick the next task.
- Start clean: clear your context (or spawn a fresh subagent) and seed it
with
tda context <id> — a self-contained Markdown brief: ancestor
titles+notes (the "why"), the task itself, its children, and the workspace.
- Go to the code:
Workspace: <name> — /path in the context (or
.workspace.path in tda show <id>) is the folder to cd into. A task
without a workspace is folder-independent.
- Refine while working:
- child task:
tda add "subtask" --parent <id> --status todo
- sibling follow-up (e.g. "user review", "todo later"): read
.parent
from tda show <id>, then tda add "..." --parent <parent> --status draft
- dependency:
tda link <blocker> <blocked> --kind blocks
- Log progress:
tda note <id> "what happened" --as <me> — appends a
timestamped entry to the notes, never overwrites. Use it for decisions,
blockers, and hand-off state. (tda set --notes replaces — avoid.)
- Finish:
tda set <id> --status done. To release without finishing:
tda note the state, then tda set <id> --status todo (or paused if it
should not be offered as work).
Other useful commands
tda show <id> — full task + parent, breadcrumb, children, blocked,
inherited workspace. The one-stop read.tda q --status todo --tag x --under <id> | --here — structured queries.tda find "text" — free-text search over titles/notes.tda ls [<id>] [--tree] — children / subtree listing.tda add --batch — batch-create from stdin, 2-space indent = depth; titles
support @assignee, #tag, and [due/recurrence] syntax.
Workspaces (task ↔ repo binding)
-
tda ws init (run in a repo) creates a root task bound to that folder;
tda ws prints the workspace root for the cwd.
-
The task stores the workspace name + a default path. On a machine where
the path differs, override it in ~/.config/tda/tui.toml:
[workspaces]
proj = "/home/me/src/proj"
Database
--db <path> > nearest ancestor .tda/tda.db (tda db init) > the global
~/.local/share/tda/tda.db. tda db path shows what resolves.
