| name | taskwarrior |
| description | Operate stable Taskwarrior `task` CLI: list/filter/report/add/modify/done/delete, projects, tags, due dates, recurrence, contexts, sync, import/export, config, UDAs, hooks, aliases, troubleshooting.
|
| metadata | {"target-taskwarrior-version":"3.4.2 stable","generated-on":"2026-05-15"} |
Taskwarrior
Use task safely. Target 3.4.2 stable. No legacy syntax unless user asks migration.
Defaults
- Read first. Mutate only when target + side effect clear.
- Project/local/repo task request: never write global
~/.taskrc or ~/.task.
.taskwarrior/taskrc in cwd/parent => project-local.- Dotfiles has
$DOTFILES/cmd/task shim. Bootstrap puts it before real task.
- Bare
task OK only when shim active; shim finds .taskwarrior/taskrc, exports TASKRC/TASKDATA, delegates real Taskwarrior.
- If shim unavailable, prefix:
TASKRC="$PWD/.taskwarrior/taskrc" TASKDATA="$PWD/.taskwarrior/data" task ...
task may be another tool. Verify real Taskwarrior with task diagnostics.- Numeric IDs volatile. Refresh report before use. UUIDs for scripts/multi-step/cross-session.
- Name store for mutation: project-local via shim, project-local via env, or global.
Project-Local Setup
If user asks project-local and no .taskwarrior/taskrc, propose + confirm before files:
mkdir -p .taskwarrior/data
printf 'data.location=%s\nconfirmation=1\n' "$PWD/.taskwarrior/data" > .taskwarrior/taskrc
Git repo: ensure .taskwarrior/ ignored. Do not edit .env, .envrc, dotenv files, shell profiles, package scripts.
Global task: before mutation, state no project-local store found; ask/confirm.
Lazy Refs
- Route:
references/command-router.md
- Filters/IDs/dates/tags/attrs/quoting:
references/selectors-and-filters.md
- Read/export/report:
references/read-and-report.md
- Add/modify/done/start/annotate:
references/mutate-tasks.md
- Destructive/bulk/import/sync/undo/config/hooks/aliases/execute:
references/safety-and-files.md first
- Data/config/sync/contexts/UDAs:
references/data-config-and-sync.md
- Debug:
references/troubleshooting.md
- Inventory:
assets/command-groups.json
Aux Files
Agent files:
out_dir="$([ -d .codex ] && printf '%s' '.codex/taskwarrior' || printf '%s' '.taskwarrior/agent')"
mkdir -p "$out_dir"
Use for exports/backups/diagnostics/scratch. .taskwarrior/ root is local store, not committed docs.
Workflow
- Classify: read, mutate, safety, data/config/sync, debug.
- Resolve store:
.taskwarrior/taskrc or project-local request => project-local; else global only after disclosure.
- Preflight:
command -v task, task diagnostics, task --version.
- Inspect narrow:
task next, task <filter> list, task <id> information, task context show, task reports.
- Shape:
task <filter> <command> [mods|args].
- Mutation: read-only target confirm first. Safety-sensitive => safety ref first.
- Execute only when unambiguous. Verify with read command.
Never broad write (modify, done, delete, purge) without explicit scope + safety. Quote spaces, parens, regex, or, xor, shell metachars, user text.
