dt-task
dt-task is a small, offline-first CLI for turning product ideas into actionable PRD tasks and a realistic daily plan.
It keeps work readable and private:
- PRD tasks are Markdown files in the project’s
.task/ directory.
- Personal project registration, journals, timers, and analytics live in
~/.dt-task/.
- No daemon, cloud account, telemetry, or runtime network calls.
What it helps with
dt-task gives a developer one short workflow for:
- capturing an idea before it is forgotten;
- refining it into a PRD with an outcome and acceptance criteria;
- seeing remaining, blocked, due, and draft work;
- planning today and carrying unfinished work into tomorrow;
- recording focus time and estimate accuracy;
- reviewing progress across multiple projects;
- running independent Codex tasks in isolated Git worktrees;
- giving coding agents a safe, consistent task workflow.
Tasks use stable names such as:
.task/0001.[backlog].implement-login.md
The task number is global and never reused. Status changes update the filename and the YAML metadata inside the Markdown file.
Install
Release archive (recommended)
Open the latest release, download the archive matching your OS and CPU, then put the binary on PATH.
macOS/Linux example:
tar -xzf dt-task_0.2.0_darwin_arm64.tar.gz
mkdir -p ~/.local/bin
install -m 0755 dt-task ~/.local/bin/dt-task
dt-task version
Use darwin_amd64 for Intel macOS, linux_amd64 or linux_arm64 for Linux, and the matching Windows .zip archive for Windows. Add ~/.local/bin to PATH if it is not already there.
Always verify the downloaded archive with checksums.txt when scripting an installation.
Homebrew (macOS)
Install from the public tap:
brew install --cask deepaktiwari09/tap/dt-task
dt-task version
Upgrade later with brew upgrade --cask deepaktiwari09/tap/dt-task.
Build from source
Requires Go 1.26 or newer:
go install github.com/deepaktiwari09/dt-task-cli/cmd/dt-task@latest
dt-task version
Start using it
Run this in any project:
dt-task init --alias my-project
init creates .task/, repairs missing task structure on reruns, creates or updates .gitignore with canonical /.task/ and /.worktrees/ entries, and registers the project locally. The .task/ and .worktrees/ directories are intentionally ignored so each developer keeps local task/worktree state after cloning the same repository.
Capture a quick idea:
dt-task capture "Fix login redirect"
Create a complete PRD task non-interactively:
dt-task task create --title "Implement login" --problem "Users lose their original destination" --outcome "Users return to the page they requested" --acceptance "Redirect preserves the original path" --estimate 90 --priority P1 --tags auth,frontend
Interactive prompts are used only when a terminal is available. Scripts and CI must provide the required flags.
Daily workflow
Start the day. The plan shows carried work, planned work, drafts, blockers, due items, estimates, and capacity warnings:
dt-task day start
dt-task task list --status backlog
Move a task into work and record focus time:
dt-task task status 1 planned
dt-task task start 1
# work
dt-task task stop 1
dt-task task status 1 done
If work is blocked, keep the reason with the task:
dt-task task status 1 blocked --blocker "Waiting for API contract"
dt-task task status 1 resume
Close the day. Unfinished work is carried to the next day automatically:
dt-task day end --note "API contract still pending"
Review results:
dt-task analytics --days 7
dt-task analytics --all-time
Parallel Codex worktrees
Initialize a project to seed its current Git branch as the worktree base:
dt-task init --alias my-project
dt-task project config set worktree_branch_prefix deepak/codex
dt-task project config set worktree_setup_command "pnpm install"
Create a worktree. The command prints ready-to-run commands for a new Warp tab:
dt-task worktree create fix-login
dt-task worktree list
dt-task worktree path fix-login
dt-task worktree remove fix-login
Each worktree lives under .worktrees/ and receives a separate deepak/codex/<slug> branch. Worktree commands do not commit, merge, or change task status. Review changes before using --force during removal.
Common task operations
dt-task task list # remaining tasks in this project
dt-task task list --all-projects # aggregate registered projects
dt-task task show 1 # read one PRD
dt-task task edit 1 # edit with $EDITOR and validate
dt-task task depend add 1 2 # task 1 depends on task 2
dt-task project config get # project-specific defaults
dt-task project config set <key> <value>
dt-task worktree create <slug> # isolated Git checkout
dt-task worktree list
dt-task worktree path <slug>
dt-task worktree remove <slug>
dt-task task archive 1 # keep it searchable, hide from active work
dt-task task delete 1 # move it to project trash
dt-task task restore 1 # restore from trash
dt-task doctor # check storage health
dt-task doctor --fix # backup, then repair safe issues
Use --project <alias> when working outside a registered project directory:
dt-task --project my-project task list
Use --json for scripts. JSON data goes to stdout; diagnostics go to stderr. Exit codes are 0 for success, 1 for state/I/O failures, and 2 for usage or validation errors.
Global agent skills
The bundled dt-task skill teaches Codex and other compatible agents to inspect remaining work, refine PRDs, update status/dependencies, run timers, plan days, and use JSON output safely. The separate dt-task-worktree skill teaches parallel development with isolated Git worktrees in Warp tabs.
Install or update them globally:
dt-task skill
Check both supported installation targets without changing files:
dt-task skill --status
The command installs matching copies of both skills under CODEX_HOME/skills/ (or ~/.codex/skills/ when CODEX_HOME is unset) and ~/.agents/skills/. Existing copies are backed up before replacement. No agent content or project paths are sent over the network.
Update dt-task
Homebrew users:
brew update
brew upgrade --cask deepaktiwari09/tap/dt-task
Archive users should download the newest archive from the latest release, replace the existing binary, and verify:
dt-task version
Go users can update to the newest source release with:
go install github.com/deepaktiwari09/dt-task-cli/cmd/dt-task@latest
Shell completion
# zsh
dt-task completion zsh > "${fpath[1]}/_dt-task"
# bash
dt-task completion bash > ~/.local/share/bash-completion/completions/dt-task
Restart the shell after installing completion.
Data, safety, and documentation
Task files remain readable Markdown. Project .task/ data is ignored by Git; global journals and registries stay in the user’s home directory. Mutations use locks, validation, backups where needed, temporary files, and atomic renames.
Run dt-task doctor after moving or restoring task data. See business logic, the release checklist, and the release-readiness task list for deeper storage, workflow, QA, and release details.
Command index
dt-task init
dt-task capture
dt-task task create|list|show|edit|status|depend|start|stop|archive|delete|restore|purge
dt-task day start|status|end
dt-task analytics
dt-task project list|rename|remove|config
dt-task worktree create|list|path|remove
dt-task doctor [--fix]
dt-task config get|set|edit
dt-task skill [--status]
dt-task completion bash|zsh
dt-task version