Categories

What Are Categories?

Categories are separate markdown files in a folder, each representing a different context (work, personal, shopping, etc.).

Setup

Single File (Default)

sd-todo ~/todos.md

One file, all todos mixed together.

Categories (Folder Mode)

sd-todo ~/todos

One folder, multiple category files.

Quick Start

# Start with a folder
$ sd-todo ~/todos

# You're in the default category
[default] >

# Create a work category
[default] > cat new work
Created category: work
Switched to category: work

# Add work todos
[work] > add Finish project
[work] > add Review code

# Create personal category
[work] > cat new personal
Switched to category: personal

# Add personal todos
[personal] > add Buy milk

# Switch back to work
[personal] > cat work
Switched to category: work

# Your work todos are here
[work] > list
1 [ ] Finish project
2 [ ] Review code

Commands

cat                  # Show all categories
cat work            # Switch to 'work' category
cat new urgent      # Create 'urgent' category
cat delete old      # Delete 'old' category

Cross-Category Listing

sd-todo list all              # All todos from all categories
sd-todo list all p            # All pending from all categories
sd-todo list cat work         # Todos from "work" category
sd-todo list cat work personal # Todos from multiple categories

Use Cases

Separate Work and Personal

~/todos/
+-- work.md         -> Work tasks
+-- personal.md     -> Personal tasks

Multiple Projects

~/todos/
+-- project-a.md    -> Project A tasks
+-- project-b.md    -> Project B tasks
+-- project-c.md    -> Project C tasks

GTD Style

~/todos/
+-- inbox.md        -> New tasks
+-- next.md         -> Next actions
+-- waiting.md      -> Waiting for
+-- someday.md      -> Someday/maybe

File Structure

~/todos/
+-- .sd-todo-config    # Remembers active category
+-- default.md         # Default category
+-- work.md           # Work category
+-- personal.md       # Personal category

Each file is plain markdown:

- [ ] Task one
- [x] Task two
- [ ] Task three

Migration

Keep Single File

sd-todo ~/todos.md  # No changes needed!

Switch to Categories

mkdir ~/todos
mv ~/todos.md ~/todos/default.md
sd-todo ~/todos

Archive with Categories

Each category gets its own archive files:

~/todos/
+-- Work.md                    # Active todos
+-- Work_archive_2026.md       # 2026 completed
+-- Personal.md
+-- Personal_archive_2026.md

Archives are organized by year and preserve all metadata. Use sd-todo archive to archive completed todos in the current category, and sd-todo archive stats to view completion statistics.

Tips

  1. Quick Switch: cat work for instant context switch
  2. List Categories: cat to see all your categories
  3. Stays Active: Your category choice is remembered
  4. Git Friendly: Each category = separate file = better diffs
  5. Edit Directly: Edit .md files with any text editor

Prompt Indicator

[work] >        # You're in 'work' category
[personal] >    # You're in 'personal' category
>               # Single-file mode (no categories)