# Personal Todo

> Manage personal todos in a markdown file with priorities, deadlines, notes, and due date reminders

- Skill: `shakudo-io/personal-todo` (Agent Skill)
- Install (CLI): `npx skillmds@latest add shakudo-io/personal-todo`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shakudo-io/personal-todo/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Shakudo-io (https://skillmd.com/u/shakudo-io)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/shakudo-io/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

```markdown
# 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

| Priority | Meaning | Use For |
|----------|---------|---------|
| P1 | Urgent | Must do today, blocking issues |
| P2 | High | Important, do this week |
| P3 | Medium | Should do, can wait |
| P4 | Low | Nice to have, someday |

## 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

```bash
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.)

```bash
# 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`

```bash
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

```bash
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)

```bash
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:
```bash
cp "$TODO_FILE" "$TODO_FILE.bak"
```

Keep last 5 backups:
```bash
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"
```