dt-task-cli

module
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 26, 2026 License: MIT

README

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

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.3.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.

Direct macOS archives are prebuilt native binaries and are not Apple-notarized. Use the Homebrew Formula below for a local source build without that Gatekeeper warning.

Homebrew (source build)

Install from the public tap:

brew install deepaktiwari09/tap/dt-task
dt-task version

The Formula builds the Go source locally, so macOS does not need an Apple-notarized prebuilt binary. Upgrade later with brew upgrade deepaktiwari09/tap/dt-task.

If upgrading from the old Cask, remove it once, then install the Formula:

brew uninstall --cask dt-task
brew install 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 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

Directories

Path Synopsis
cmd
dt-task command
internal
cli

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL