
markdown-tasks
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-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add motlin/claude-code-plugins.
Contents
Discovered from sourceSkills 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- narrationv1.42.0
- offline-claude-code-guidev1.14.0
- orchestrationv1.42.0
- plans-dashboardv1.42.0
- plugin-and-skill-devv1.42.0
- pushoverv1.14.0
- recapv1.42.0
- stop-phrase-guardv1.42.0
- temporal-datav1.42.0
- tmux-titlesv1.42.0
- upstream-syncv1.42.0
- worktree-setupv1.42.0
- bash-guardsv1.42.0
- buildv1.42.0
- builtin-tasksv1.14.0
- burnv1.42.0
- codev1.42.0
- code-walkthroughv1.42.0
- demov1.42.0
- ghostty-titlesv1.42.0
- gitv1.42.0
- git-guardsv1.42.0
- githubv1.42.0
- herdr-rebootv1.42.0