task-notes

PyPI | GitHub | 中文文档

task-notes is an LLM/agent-friendly task CLI that stores project plans in Markdown checklists.

It supports nested task trees, selector-based operations (1, 1.2, 2.1.3), rich terminal output, and machine-safe JSON mode.

Install

From PyPI:

pip install task-notes

With uvx (no global install):

uvx --from task-notes task --help

Install as a global tool with uv:

uv tool install task-notes
task --help

Quick Start

task new app-redesign "Clarify scope" "Implement features" "Ship"
task add app-redesign --parent 2 "Implement ls/show output"
task show app-redesign
task next app-redesign
task check app-redesign --path 1
task edit app-redesign --path 2.1 "Implement ls/show/tree output"

Commands

task ls [--json]
task show <project> [--json]
task next <project> [--json]
task new <project> <content...> [--json]
task add <project> [--parent <selector>] <content...> [--json]
task edit <project> --path <selector> <content> [--json]
task edit <project> -i [--json]
task del <project> --path <selector> [--json]
task rm <project> [--json]
task check <project> --path <selector> [--json]
task uncheck <project> --path <selector> [--json]
task toggle <project> --path <selector> [--json]
task version [--json]

Data Directory and Safety

• Default tasks directory: ~/.task-notes
• You can override with --tasks-dir <path>
• Non-default directories are blocked by default
• To allow a non-default directory, explicitly add:

--unsafe-external-dir

Example:

task --unsafe-external-dir --tasks-dir ./tasks ls

Interactive Edit

task edit <project> -i

Keys:

• Up/Down or j/k: move cursor
• Space: select target task
• Enter: confirm selection
• q or Esc: cancel

JSON Output (Recommended for Tools/LLMs)

task show app-redesign --json

In automation, prefer --json to avoid parsing terminal formatting.

Development

Run tests:

uv run python -m unittest discover -s tests -p 'test_*.py' -v

Build and check package:

uv build
uvx twine check dist/*