Todo Instant

Manage a todos.md task list at your project root with support for adding, completing, removing, and listing tasks with optional due dates and sorted priorities.

When to Use This Command

Run this command when...

• You need a lightweight, file-based todo list without setting up external project management tools
• You want to add tasks with optional due dates and have them automatically sorted by urgency
• You need to mark tasks complete, undo completions, or remove tasks by their numbered position
• You want a markdown-based todo file that is version-controlled alongside your code
• You need to quickly check which tasks are past due or see the next actionable item in your list

Quick Start

Copy
# .claude/commands/todo-instant.yaml
name: Todo Instant
description: File-based project todo manager with due dates
inputs:
  - name: action
    description: "add, complete, remove, undo, list, past due, next"
  - name: args
    description: "Task description or task number"
    default: ""

Copy
# Add a task with a due date
claude "todo add 'Fix navigation bug' tomorrow"

# List all tasks
claude "todo list"

# Complete task number 1
claude "todo complete 1"

# Show next actionable task
claude "todo next"

Output:
  # Project Todos

  ## Active
  1. [ ] Fix navigation bug | Due: 03-16-2026
  2. [ ] Update API docs
  3. [ ] Refactor auth module | Due: 03-20-2026

  ## Completed
  1. [x] Setup CI pipeline | Done: 03-14-2026

Core Concepts

Concept	Description
Project Root Detection	Finds the project root by looking for .git, package.json, or similar markers
Markdown Format	Tasks stored in todos.md using checkbox syntax with optional due date metadata
Due Date Sorting	Active tasks with due dates appear before undated tasks; sorted by date ascending
Numbered References	Tasks are numbered sequentially for easy reference in complete, remove, and undo commands
Active/Completed Sections	Completed tasks move from the Active section to the Completed section with a Done timestamp

todos.md Structure:
  ┌──────────────────────────────────────────┐
  │ # Project Todos                          │
  │                                          │
  │ ## Active                                │
  │ - [ ] Task with date | Due: 03-20-2026  │
  │ - [ ] Task without date                 │
  │                                          │
  │ ## Completed                             │
  │ - [x] Finished | Done: 03-14-2026       │
  └──────────────────────────────────────────┘

Configuration

Parameter	Type	Default	Description
action	string	"list"	Command: add, complete, remove, undo, list, past due, next
description	string	""	Task description text (for add action)
due_date	string	""	Due date: specific date, "tomorrow", "next week", or relative like "4 days"
number	integer	0	Task number to target for complete, remove, or undo actions
count	integer	all	Number of tasks to display for list action

Best Practices

1. Use due dates for time-sensitive work -- Tasks with due dates are automatically sorted to the top, making it impossible to miss deadlines buried in a long list.
2. Run todo next at the start of each session -- This shows the highest-priority active task, giving you a clear starting point without scrolling through the full list.
3. Commit todos.md with your code -- Keeping the todo file in version control lets teammates see what you are working on and what is pending, improving coordination.
4. Use past due to catch slipping tasks -- Running this regularly surfaces tasks that have missed their deadlines so you can either complete them or adjust the due dates.
5. Keep task descriptions actionable -- "Fix navigation bug in mobile menu" is better than "navigation". Specific descriptions reduce context-switching cost when you return to a task.

Common Issues

1. todos.md not found -- The command creates todos.md automatically on first use. If the file was deleted, running any command will recreate it with the basic Active/Completed structure.
2. Task number out of range -- Task numbers are assigned dynamically based on the current list. Run todo list first to see current numbering before using complete, remove, or undo.
3. Date format confusion -- Dates are stored in MM-DD-YYYY format by default. Natural language inputs like "tomorrow" and "next week" are converted automatically, but ambiguous formats like "03/04" may be misinterpreted.