topydo_skill

Overview

This skill provides a command-line interface to manage todo.txt tasks using topydo. It lets you add, list, complete, prioritize, tag, and organize tasks with support for dependencies, due/start dates, recurrence, projects, and contexts. It runs on macOS, Linux, and Windows and requires Python 3 and pip to install. Use it when you prefer a fast, scriptable, plain-text workflow for task management.

How this skill works

topydo reads and writes tasks in the todo.txt format and exposes a rich CLI for common operations: add, ls, do, pri, tag, dep, postpone, archive and more. It parses metadata inside task lines (priority, creation date, due:t, t:, rec:, +projects, @contexts, star:1) and supports advanced filters, sorting, grouping, and JSON output. Configuration files control filenames, display options, identifiers, and sort rules so results can be tailored for interactive use or integration into scripts.

When to use it

• When you keep tasks in a todo.txt plain-text file and want a powerful CLI to manage them.
• When you need dependencies, recurrence, due/start dates, or subtasks in a lightweight system.
• When you prefer scriptable task operations or want to integrate task actions into shell workflows.
• When you need to filter, sort, group, or export tasks (including JSON) for other tools.
• When you want cross-platform consistency across macOS, Linux, and Windows.

Best practices

• Store todo.txt and done.txt in a consistent path via ~/.topydo or a project .topydo file.
• Enable human-readable stable IDs (identifiers = text) for reproducible references in scripts.
• Use projects (+Project) and contexts (@Context) to group and filter tasks quickly.
• Tag due:, t:, rec: and star:1 consistently so sorting/importance works reliably.
• Use ls filters and -s sort strings to build focused views (e.g., due:today, desc:importance).

Example use cases

• Add a task with priority, project, and due date: topydo add "(A) Write report +Work due:tomorrow"
• List only high-priority tasks due this week: topydo ls "(>C)" due:<=fri -s desc:due
• Mark multiple tasks done or archive completed tasks as part of a daily workflow: topydo do 1 2 && topydo archive
• Create dependencies and visualize them with graphviz for project planning: topydo dep add 2 to 1 && topydo dep dot 1 | dot -Tpng -o deps.png
• Export tasks as JSON for integration into dashboards or external scripts: topydo ls -f json