dot-tasks 0.1.9

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 updates in the repo instead of chat history. It is shared here in case the same approach is useful to others.

Quick Start

Quick start commands:

# Initialize .tasks/ dir in the current project
dot-tasks init
# Create a new todo task with an initial summary.
dot-tasks create rename-variables-for-vibes --summary "Refactor variable names for maximum vibes"
# Move the task from todo/ to doing/ and create its plan.md.
dot-tasks start rename-variables-for-vibes
# Append a progress note while work is in progress.
dot-tasks log-activity rename-variables-for-vibes --note "Replaced cryptic names with vibes-based naming"
# Mark the task complete and move it to done/.
dot-tasks complete rename-variables-for-vibes

Task directory layout

.tasks/
  todo/
  doing/
  done/
  trash/

Each task lives in .tasks/<status-bucket>/<created-date>-<task_name>/ and contains:

• task.md (canonical metadata frontmatter + task body)
• activity.md (append-only audit log)
• plan.md (created when the task is started)

Typical workflow:

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

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.

Optional due dates

Due dates are stored in task frontmatter as an optional ISO due_date: YYYY-MM-DD. They contain no time or timezone. Explicit create --due-date, update --due-date, and update --clear-due-date options remain available for scripts regardless of the interactive feature setting.

Due dates are enabled by default. Their interactive prompts and human-readable output can be disabled:

settings:
  due_dates:
    enabled: true
  list_table:
    columns:
      - name: task_name
        width: 32
      - name: due_date
        width: 10

When due dates are enabled, init offers due_date in the list-column selector and selects it by default; users may unselect it. When due dates are disabled, the column is omitted from the selector and suppressed from list output. In Rich terminal output, dates before today render in red and dates due today render in orange for todo and doing tasks. Completed tasks are not highlighted.

The interactive date picker starts at today after choosing to set a date. Use left/right to select year, month, or day; up/down to adjust it; type digits to replace a segment; and press Enter to accept.

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.

Typical agent workflow:

1. Capture or refine a task spec with dot-tasks create.
2. If asked what to work on, check dot-tasks list (defaults to todo|doing) and propose the top few options with a short rationale.
3. Move selected work into active state with dot-tasks start.
4. Log meaningful progress with dot-tasks log-activity --note ... as work evolves.
5. Close the loop with dot-tasks complete when acceptance criteria are met.

You can set up agent integration pieces either during dot-tasks init or with standalone commands:

• During dot-tasks init (interactive flow), dot-tasks can 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

Example Project

For a full demo of the workflow, see examples/basic-demo/ and the walkthrough in examples/basic-demo/README.md.