Quick Start • Install • AI Agent Integration • Example Project • DeepWiki
dot-tasks is a simple CLI for managing project-level tasks in a local .tasks/ directory, using human- and agent-readable files.
It started as a personal workflow tool: keep task specs in files, let agents work from those specs, and keep progress records in the repo instead of chat history. It is shared here in case the same approach is useful to others.
dot-tasks keeps each task's metadata in task.md frontmatter (status, dates, dependencies, tags, a one-line summary, and whichever fields your project configures) and manages it through commands. The task description and any other files your project keeps in a task folder (plans, notes, session records) are edited directly, like ordinary files. Your project describes its own workflow in .tasks/README.md; the tool does not prescribe one.
Quick Start
Quick start commands:
# Initialize .tasks/ dir in the current project
dot-tasks init
# Create a new todo task with a one-line summary and a priority; prints the task.md path.
dot-tasks create rename-variables-for-vibes summary="Refactor variable names for maximum vibes" priority=p1
# Move the task from todo/ to doing/.
dot-tasks start rename-variables-for-vibes
# Print the task folder (to open or add files there).
dot-tasks path rename-variables-for-vibes
# Mark the task complete and move it to done/.
dot-tasks complete rename-variables-for-vibes
Task directory layout
.tasks/
README.md # your project's workflow doc (starter written by `init`)
config.yaml # settings, including the task fields
templates/
task.md # optional: the body new tasks start from
todo/
doing/
done/
trash/
Each task lives in .tasks/<status-bucket>/<created-date>-<task_name>/. The folder moves when the status changes, so refer to tasks by name or id, not by path (dot-tasks path <task> resolves one).
dot-tasks writes only task.md. Any other file in the folder (plan.md, notes.md, sessions/…) belongs to your project, and dot-tasks view lists it.
task.md
---
task_id: t-20261119-WF8R
task_name: prove-lemma-3
summary: Prove the variance bound in Lemma 3.
status: todo
date_created: '2026-11-19'
date_started: null
date_completed: null
depends_on: []
tags: [theory]
priority: p1
kind: theory
---
## Done when
- …
- Frontmatter.
task_id,task_name,status, the dates,depends_onandtagsare structural: they change only through commands (create,start,complete,update --tag/--depends-on/--status,rename).summaryand the configured fields (herepriorityand a project-definedkind) are values: set them withkey=valueoncreate/update, or edit them by hand. Keys you add by hand are kept as written. - Body. Free-form Markdown, written in your editor.
createstarts it from.tasks/templates/task.mdif that file exists, otherwise it is empty. The CLI never edits the body after creation.
Typical workflow:
| Step | What happens | Command(s) | Files touched |
|---|---|---|---|
| Make note of new to-do | Write down the task spec. Often I have an agent draft a spec from a rough note. | dot-tasks create |
Creates task dir .tasks/todo/<created-date>-<task_name>/ with task.md |
| Choose task to work on | Scan what is in todo/doing and pick the next task to start. |
dot-tasks list |
read-only inspection of .tasks/ |
| Start active work | Move the task to active status when work begins. | dot-tasks start |
Move task from .tasks/todo/ to .tasks/doing/ |
| Work loop | Edit the task description and the files your workflow keeps (plans, notes, records). | none, edit files directly | task.md body, project files in the task folder |
| Finish and archive state | Mark done when the work is finished, preserving its files. | dot-tasks complete |
task directory moves to .tasks/done/ |
Installation
Install via pip (PyPI)
pip install dot-tasks
Quick check:
dot-tasks --help
Install Latest from GitHub
Install the latest from GitHub:
pip install "git+https://github.com/Awni00/dot-tasks.git"
Development Install (with uv)
git clone https://github.com/Awni00/dot-tasks.git
cd dot-tasks
uv sync --dev
uv run dot-tasks --help
Editable install:
uv pip install -e ".[dev]"
Commands
| Command | Purpose | Typical usage |
|---|---|---|
init |
Create .tasks/, write/update managed config settings and a starter .tasks/README.md (if missing); can also append the dot-tasks section to AGENTS.md and install the skill via npx skills. |
dot-tasks init |
install-skill |
Install the canonical dot-tasks skill via npx skills. |
dot-tasks install-skill [--yes] |
add-agents-snippet |
Add or update the canonical dot-tasks section in AGENTS policy markdown. |
dot-tasks add-agents-snippet [--agents-file <path>] [--yes] |
create |
Add a new task to todo/ and print the path of its task.md. |
dot-tasks create <task_name> [summary="..."] [field=value ...] [--tag <tag>] [--depends-on <task>] |
start |
Move a task to doing/ (checks dependencies; --force overrides). |
dot-tasks start <task_name> |
complete |
Move a task to done/. |
dot-tasks complete <task_name> |
list |
List tasks by status, field and tag filters (rich/plain/JSON depending on context). | `dot-tasks list [todo |
tags |
Show task counts by tag with optional status filter (rich/plain/JSON depending on context). | `dot-tasks tags [todo |
view |
Show full details for one task, including clickable links to task.md and every other file in its folder. |
dot-tasks view <task_name> [--json] |
path |
Print the absolute path of a task's folder. | dot-tasks path <task_name> |
graph |
Visualize task dependencies as a DAG in terminal output (tree or layers modes). |
`dot-tasks graph [--mode tree |
update |
Update the summary, fields, tags, dependencies or status (interactive form when no changes are given). | dot-tasks update <task_name> [field=value ...] [field= ...] [--tag <tag>] [--depends-on <task>] [--status ...] |
rename |
Rename a task. | dot-tasks rename <task_name> <new_task_name> |
delete |
Move a task to trash/, or delete permanently with --hard. |
dot-tasks delete <task_name> [--hard] |
Interactive create and interactive update use a single tag selector flow with an optional + add new tag(s) path.
Status filter supports todo|doing style multi-select and all. Default is todo|doing.
Task fields
Fields are set and filtered with key=value; key= clears a field (or, in list, matches tasks where it is unset):
dot-tasks create prove-lemma-3 summary="Prove the variance bound in Lemma 3." priority=p1 kind=theory
dot-tasks update prove-lemma-3 due_date=2026-12-01
dot-tasks update prove-lemma-3 due_date=
dot-tasks list all kind=theory kind=writing # same key twice: either value
dot-tasks list priority=p0 due_date= # different keys: all must match
A project chooses its fields in .tasks/config.yaml. An entry is either the name of a built-in field or a definition with a type (choice, date or text):
settings:
fields:
- priority # built-in: choice p0, p1, p2, p3 (default p2)
- due_date # built-in: date
- name: kind # project-defined
type: choice
values: [theory, experiment, writing, literature]
- name: effort # built-in, overridden
values: [hours, days, weeks]
default: days
- Built-ins:
priority(choice p0–p3, default p2, colour-ranked),effort(choice s/m/l/xl, default m),due_date(date),owner(text). A config withoutfieldsuses all four; a newinitselectspriority,effortanddue_date. - Types:
choicevalues come fromvalues;ranked: truecolours the first values (as forpriority).datevalues areYYYY-MM-DD; past dates on open tasks are highlighted red, today's orange, and the interactive date picker uses left/right for year/month/day and up/down to change them.textis free text. - Validation: setting an unknown field or an invalid value fails with the allowed choices. A stored value that no longer fits (for example after you rename a choice) is reported as a warning on each command and left in place.
- List columns: any configured field,
summary,task_name,task_id,status,deps,createdandcompletedcan be a column insettings.list_table.columns.
Tag examples:
dot-tasks list --tag bug
dot-tasks list todo|doing --tag backend --tag api --all-tags
dot-tasks list all
dot-tasks tags
dot-tasks tags todo --sort name
AI Agent Integration
dot-tasks is designed so humans and agents can work from the same file-based task state in .tasks/ instead of relying on chat context.
The pieces:
.tasks/README.md: your project's workflow doc. It says when to create tasks, which files a task keeps (e.g.plan.md, per-session AI-use records), what to record when wrapping up and before completing.initwrites a starter skeleton; edit it to fit the project.- AGENTS.md section: a short trigger that tells agents the project uses dot-tasks and to read
.tasks/README.mdbefore working on a task. dot-tasksskill: a compact command and data-model reference.
The CLI itself never prints workflow guidance, so commands stay the same for humans and agents.
You can set up agent integration pieces either during dot-tasks init or with standalone commands:
- During
dot-tasks init(interactive flow),dot-taskscan optionally append the AGENTS section and install the skill. - Standalone commands:
dot-tasks install-skill
dot-tasks install-skill --yes
dot-tasks add-agents-snippet
dot-tasks add-agents-snippet --agents-file TEAM_AGENTS.md --yes
Project workflow doc
.tasks/README.md is plain Markdown that you own. A research project might say:
## Files in a task folder
- `task.md` body: starts from `.tasks/templates/task.md` (Done when, Outcome, Human review).
- `sessions/<date>-<session-id>.md`: one AI-use record per session (model, who did what,
outcome, initial and major prompts), written at wrap-up from `.tasks/templates/session.md`.
## Before completing a task
- Fill Outcome and Human review. Abandoned work is completed with an explanatory Outcome
and the `dropped` tag.
Its body template, .tasks/templates/task.md, puts reminders where the agent writes:
## Done when
## Outcome
<!-- Filled at wrap-up. Abandoned work: explain why and tag `dropped`. -->
## Human review
Migrating from 0.1
0.2.0 removes the workflow the tool used to hardcode and makes the task format configurable. It is not backward compatible on the command line:
- Files:
startno longer createsplan.md, and no command writesactivity.md. Existingplan.mdandactivity.mdfiles stay in their task folders as ordinary files. - Commands:
log-activityis removed.--priority,--effort,--owner,--due-date,--clear-due-date,--summaryand--spec-readinessare replaced bykey=valuearguments (priority=p1,due_date=,summary="..."). - Fields:
spec_readinessis no longer a field (existing values stay in the files as custom keys).blocked_byis no longer stored;viewshows the same information asblocks. The summary is a frontmatter field; old tasks keep their## Summarybody section. - Settings:
settings.task_body_sectionsandsettings.due_datesare replaced by.tasks/templates/task.mdandsettings.fields. Rundot-tasks initonce: it moves your body sections into the template (except Summary) and removes the retired settings. - New:
dot-tasks path <task>, configurable typed fields,listfield filters, and a starter.tasks/README.mdfrominit.
To refresh agent instructions, run dot-tasks add-agents-snippet and dot-tasks install-skill, then write your workflow in .tasks/README.md.
Example Project
For a full demo of the workflow, see examples/basic-demo/ and the walkthrough in examples/basic-demo/README.md.
Metadata
Release files for dot-tasks 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dot_tasks-0.2.1.tar.gz | 89.7 kB | With provenance | Details for dot_tasks-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dot_tasks-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for dot_tasks-0.2.1-py3-none-any.whl |
Total release size: 141.3 kB
Release files / dot_tasks-0.2.1.tar.gz
| Download URL | dot_tasks-0.2.1.tar.gz |
|---|---|
| Size | 89.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d65816e2e0e50c1b33feade6ea48ef421c147fbf7df99c3370c14ade1ea29155
|
|
BLAKE2b-256 checksum How to use checksums |
bbc42a5d2a3bf3846a2ac60b35740dd4a8cb3992e0130ce312c20f442a2267a7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / dot_tasks-0.2.1-py3-none-any.whl
| Download URL | dot_tasks-0.2.1-py3-none-any.whl |
|---|---|
| Size | 51.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3e6fb88c01ddb8162f32faba4844f058b96c522141306caaf521294211a79b7c
|
|
BLAKE2b-256 checksum How to use checksums |
9ee2a00ee32cc2cdae65150e0d501a9670ab69e181cd93cb55b86b37d85cbcf7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for dot-tasks 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for dot_tasks-0.2.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.