Task management system using markdown checkboxes in .llm/todo.md with skills for planning, implementing, and tracking tasks across git worktrees

version
1.42.0
GitHub stars
20

Install

/plugin install markdown-tasks@motlin-claude-code-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add motlin/claude-code-plugins.

Contents

Discovered from source

Skills 1

Markdown Task Management

The task list lives in .llm/todo.md. Inspect and change it only through the scripts below: the file grows large, and the scripts return just the task you need instead of loading the whole list into context.

<plugin-root> is ${CLAUDE_PLUGIN_ROOT} in Claude Code. In Codex, it is the plugin root that contains this skills/tasks/SKILL.md file.

Every script exits 0 on success and 1 on error.

Scripts

task_get.py - Extract Next Task

python <plugin-root>/scripts/task_get.py .llm/todo.md

Prints the first [ ] task with all indented context lines below it. Exits 1 when the file does not exist.

To see more of the queue, select incomplete tasks by 1-based position. Positions count only [ ] tasks; [x], [!], and [>] tasks are skipped.

python <plugin-root>/scripts/task_get.py .llm/todo.md --index 3
python <plugin-root>/scripts/task_get.py .llm/todo.md --range 1-10
python <plugin-root>/scripts/task_get.py .llm/todo.md --limit 10

Each selected task prints as its checkbox line and context, with a blank line between tasks. --index and a --range that starts past the last incomplete task exit 1; a --range or --limit that runs past the end prints the tasks that exist.

task_add.py - Add New Task

python <plugin-root>/scripts/task_add.py .llm/todo.md "Task description
  Context line 1
  Context line 2"

Appends a [ ] task, creating .llm/todo.md if needed and preserving indentation in multi-line strings.

Add a batch of tasks in one shell command, chaining one call per task with &&, so concurrent sessions writing the same file are unlikely to interleave:

python <plugin-root>/scripts/task_add.py .llm/todo.md "First task
  Context line 1" && \
python <plugin-root>/scripts/task_add.py .llm/todo.md "Second task"

task_mark.py - Mark Task

python <plugin-root>/scripts/task_mark.py .llm/todo.md
python <plugin-root>/scripts/task_mark.py .llm/todo.md --marker='!' --reason='precommit failed on the parser rewrite'

Changes the first [ ] to [x], or to any single non-space character passed as --marker. Exits 1 when no incomplete task remains.

--reason appends an indented line to the end of the task body:

- [!] Require authentication on API routes.
  Reuse `validateJwt` from `/workspace/project/src/auth/tokens.ts`.
  Blocked 2026-08-19 session 94aec27b: validateJwt does not exist; the repo uses `verifyToken`

The reason travels with the task through archive and recovery, and task_get.py hands it to the next attempt. Quote the concrete failure (the failing command, the assertion, the missing symbol) rather than restating the task.

The line's label follows the marker: Blocked for !, Completed for x, Claimed for >, and Marked [<marker>] for any other.

--reason is required with --marker='!'; without it the script exits 1 and leaves the file untouched.

To mark a task other than the first, name it:

python <plugin-root>/scripts/task_mark.py .llm/todo.md --index 3 --marker='>'
python <plugin-root>/scripts/task_mark.py .llm/todo.md --title 'Require authentication on API routes.'

--index counts [ ] tasks the same way task_get.py does. --title matches the first [ ] or [>] task whose text after the checkbox equals the title exactly, so it can complete or block a task that was claimed with [>]. Positions shift once a task is marked, so prefer --title when marking several tasks in turn. A missing title or out-of-range index exits 1 and leaves the file untouched.

task_archive.py - Archive Task List

python <plugin-root>/scripts/task_archive.py .llm/todo.md

Moves the file to .llm/YYYY-MM-DD-todo.md. Blocked [!] tasks are carried forward into a fresh .llm/todo.md, still marked [!]. Prints the archive path and the carried-forward count.

task_unblock.py - Recover Blocked Tasks

python <plugin-root>/scripts/task_unblock.py .llm --dry-run
python <plugin-root>/scripts/task_unblock.py .llm

Scans every .llm/*todo*.md, including the live .llm/todo.md, and moves each [!] task into .llm/todo.md as an open [ ] task stamped with an indented Recovered <yyyy-mm-dd> session <session-id> line. Existing Blocked lines are kept. Recovery is a move, so re-running cannot duplicate a task; emptied archive files stay on disk. Exits 0 when nothing is blocked.

Recovery rewrites historical archives. Always run --dry-run first and confirm the report with the user.

Task Format

A task starts with one of these markers:

  • [ ] - Ready
  • [x] - Completed
  • [!] - Blocked after a failed attempt
  • [>] - Claimed by a session that is working on it

Each task is extracted and executed in isolation, so it must carry all the context needed to implement it in indented lines:

  • Absolute file paths
  • Exact function/class names
  • Existing patterns to follow
  • Dependencies and prerequisites
  • Expected outcome

Repeat shared context in every related task. Never reference other tasks.

Plan Files

Before adding tasks from a plan, store the plan at .llm/plans/<yyyy-mm-dd>-<descriptive-name>.md (for example, 2025-12-04-thread-safety-tests.md), creating the directory if needed. A Claude Code plan-mode file under ~/.claude/plans/ is moved there, not copied. Include the archived plan's absolute path in every task.

Sponsors

Details

Marketplace
motlin/claude-code-plugins
Source
plugins/markdown-tasks
Author
Craig Motlin
Category
Productivity

More from motlin/claude-code-plugins

All 30