Personal Todo

Personal Todo Manager

Manage personal todos in a single markdown file (~/.todos.md) with priorities, deadlines, notes, and due date reminders.

File Location

All todos are stored in: ~/.todos.md

File Format

# Todos

## Active

- [ ] [P1] Task description @due(2025-01-25)
  - Note: Additional context or details here
  - Note: Can have multiple notes

- [ ] [P2] Another task @due(2025-01-30)

- [ ] [P3] Task without deadline

## Completed

- [x] [P2] Finished task @due(2025-01-18) @done(2025-01-17)
  - Note: Any notes preserved

Priority Levels

Commands

View Todos

Show all active todos (default view):

Show my todos

Show overdue and due soon:

What's overdue?
What's due this week?

Filter by priority:

Show my P1 todos
Show urgent tasks

Add Todos

Basic todo:

Add todo: Review PR for feature branch

With priority:

Add P1 todo: Fix production bug
Add todo [P2]: Prepare presentation

With deadline:

Add todo: Submit report @due(2025-01-25)
Add P1 todo: Client call prep due 2025-01-21

With notes:

Add todo: Research competitor pricing
  Note: Focus on enterprise tier
  Note: Check G2 reviews

Update Todos

Mark complete:

Complete: Review PR for feature branch
Mark done: Fix production bug

Change priority:

Change "Submit report" to P1
Reprioritize "Research" to P3

Update deadline:

Change deadline for "Submit report" to 2025-01-28
Remove deadline from "Research"

Add note to existing:

Add note to "Client call": Scheduled for 2pm EST

Remove/Archive

Delete todo:

Delete todo: Old task I don't need

Archive all completed:

Archive completed todos

Implementation Instructions

Reading the File

TODO_FILE="$HOME/.todos.md"

if [ -f "$TODO_FILE" ]; then
  cat "$TODO_FILE"
else
  echo "No todos file found. Creating empty file."
  cat > "$TODO_FILE" << 'EOF'
# Todos

## Active

## Completed
EOF
fi

Parsing Todos

Each todo line follows this pattern:

- [ ] [P{1-4}] {description} @due(YYYY-MM-DD)

Parse with regex:

^- \[([ x])\] \[P([1-4])\] (.+?)(?:\s+@due\((\d{4}-\d{2}-\d{2})\))?(?:\s+@done\((\d{4}-\d{2}-\d{2})\))?$

Groups:

1. Status: space = incomplete, x = complete
2. Priority: 1-4
3. Description: task text
4. Due date (optional): YYYY-MM-DD
5. Done date (optional): YYYY-MM-DD

Notes are indented lines starting with - Note::

^  - Note: (.+)$

Adding a Todo

1. Read the file
2. Find the ## Active section
3. Insert new todo after the section header
4. Maintain priority ordering (P1 first, then P2, etc.)

# Example: Add "Fix bug" as P1 due 2025-01-22
NEW_TODO="- [ ] [P1] Fix bug @due(2025-01-22)"

# Insert after ## Active, before first non-P1 item or end of section

Completing a Todo

1. Find the todo line by description match
2. Change [ ] to [x]
3. Add @done(YYYY-MM-DD) with today's date
4. Move from ## Active to ## Completed

TODAY=$(date +%Y-%m-%d)
# Transform: - [ ] [P1] Task @due(2025-01-20)
# To:        - [x] [P1] Task @due(2025-01-20) @done(2025-01-20)

Checking Overdue

TODAY=$(date +%Y-%m-%d)

# Extract todos with @due() and compare dates
grep -E '^\- \[ \].*@due\(' "$TODO_FILE" | while read -r line; do
  due_date=$(echo "$line" | grep -oP '@due\(\K[0-9-]+')
  if [[ "$due_date" < "$TODAY" ]]; then
    echo "OVERDUE: $line"
  fi
done

Due Date Reminders

When showing todos, highlight:

• OVERDUE: Due date < today (show in red/urgent)
• TODAY: Due date = today (show prominently)
• THIS WEEK: Due within 7 days (show with warning)

TODAY=$(date +%Y-%m-%d)
WEEK_AHEAD=$(date -d "+7 days" +%Y-%m-%d)

# Categorize each todo by urgency

Display Format

When showing todos to user, format as:

## Overdue (2)
- [P1] Fix production bug (was due Jan 18)
- [P2] Submit quarterly report (was due Jan 19)

## Due Today (1)
- [P1] Client call prep

## Due This Week (3)
- [P2] Review PR @due(Jan 22)
- [P2] Prepare presentation @due(Jan 24)
- [P3] Update documentation @due(Jan 25)

## Other Active (2)
- [P3] Research competitor pricing
- [P4] Organize bookmarks

Example Session

User: Add P1 todo: Prepare board deck due 2025-01-23 Note: Include Q4 financials Note: Max 15 slides

Agent: Added P1 todo with deadline Jan 23:

- [ ] [P1] Prepare board deck @due(2025-01-23)
  - Note: Include Q4 financials
  - Note: Max 15 slides

User: What's due this week?

Agent:

## Due This Week (Jan 20-26)

TODAY (Jan 20):
- [P1] Client call prep @due(2025-01-20)

TOMORROW (Jan 21):
- [P2] Review feature PR @due(2025-01-21)

LATER THIS WEEK:
- [P1] Prepare board deck @due(2025-01-23)
  - Note: Include Q4 financials
  - Note: Max 15 slides
- [P3] Team sync prep @due(2025-01-24)

User: Complete: Client call prep

Agent: Marked complete:

- [x] [P1] Client call prep @due(2025-01-20) @done(2025-01-20)

Moved to Completed section.

Edge Cases

1. Duplicate descriptions: Match by most recent or ask for clarification
2. No todos file: Create with template on first use
3. Malformed lines: Preserve as-is, warn user
4. Empty sections: Keep section headers, show "No items"
5. Past due dates on new todos: Warn but allow (might be intentional backlog)

File Backup

Before any write operation, create backup:

cp "$TODO_FILE" "$TODO_FILE.bak"

Keep last 5 backups:

for i in 4 3 2 1; do
  [ -f "$TODO_FILE.bak.$i" ] && mv "$TODO_FILE.bak.$i" "$TODO_FILE.bak.$((i+1))"
done
mv "$TODO_FILE.bak" "$TODO_FILE.bak.1"