Todo

After installation, confirm it works: todo version

Core Principles

1. Always confirm destructive actions — before deleting tasks, ask the user to confirm unless they explicitly said "delete".
2. Show context after mutations — after adding, editing, completing, or deleting a task, run list so the user sees the current state.
3. Use appropriate priorities — if the user's language implies urgency (e.g. "urgent", "ASAP", "critical", "blocker"), use -p high. If casual (e.g. "whenever", "someday", "nice to have"), use -p low. Default to -p medium.
4. Parse natural dates — convert the user's natural language dates into the formats todo accepts. See the date format reference below.
5. Be proactive — if the user adds a task without a due date but the context implies one (e.g. "before Friday's meeting"), suggest setting one.

Command Reference

Add a task

todo add "<title>" [-d "<description>"] [-p <low|medium|high>] [-D "<due_date>"]

Examples:

todo add "Deploy v2.0 to production" -p high -D "2026-03-10T14:00:00Z"
todo add "Write unit tests for auth" -d "Cover login, logout, and token refresh" -p medium
todo add "Read Go blog post" -p low

List tasks

todo list                    # Active tasks (pending + in-progress), sorted by priority then due date
todo list -a                 # All tasks including done
todo list -p high            # Only high priority
todo list -s in-progress     # Only in-progress
todo list -s pending -p high # Pending + high priority

Show task details

todo show <id>

Edit a task

todo edit <id> [-t "<new_title>"] [-d "<new_description>"] [-p <priority>] [-s <status>] [-D "<due_date>"]
todo edit <id> -D ""         # Clear the due date

Mark a task as done

todo done <id>

Delete a task

todo delete <id>

Configuration

todo config set ntfy_url "<ntfy_topic_url>"    # ntfy push notifications
todo config set postback_url "<webhook_url>"    # generic webhook
todo config get ntfy_url
todo config get postback_url

Daemon

todo daemon                  # Start daemon (checks every 60s)
todo daemon -i 30            # Check every 30 seconds

The daemon can also be run via Docker:

# From the cloned todod repo directory:
docker compose up -d    # Start
docker compose logs -f  # View logs
docker compose down     # Stop

Date Formats

todo accepts these date formats for the -D flag:

Always calculate the actual date from the current date/time before passing to todo. Use date command if needed to compute relative dates:

date -d "+3 days" +%Y-%m-%d          # 3 days from now
date -d "next friday" +%Y-%m-%d      # Next Friday

Workflows

When the user wants to add a task

1. Extract title, priority, due date, and description from their message
2. Run the add command with appropriate flags
3. Run list to show the updated task list

When the user wants to see their tasks

1. Determine if they want all tasks or filtered (by status/priority)
2. Run the appropriate list command
3. If there are overdue tasks (due date in the past, still pending), proactively mention them

When the user wants to update a task

1. If they reference a task by name/description rather than ID, run list first to find the ID
2. Run the edit command with only the changed fields
3. Run show <id> to confirm the changes

When the user wants to complete a task

1. If referenced by name, find the ID via list first
2. Run done <id>
3. Run list to show remaining tasks

When the user wants to delete a task

1. If referenced by name, find the ID via list first
2. Confirm with the user before deleting (unless they were explicit)
3. Run delete <id>
4. Run list to show remaining tasks

When the user asks about overdue or due-soon tasks

1. Run list and examine the due dates in the output
2. Highlight any tasks that are overdue or due within 24 hours
3. Suggest actions (complete, reschedule, or escalate priority)

When the user wants a summary or review

1. Run list -a to get all tasks
2. Provide a summary: count by status, count by priority, any overdue
3. Suggest next actions (e.g. "You have 3 high-priority tasks pending, 2 are overdue")

When the user wants to set up notifications

Two channels are supported — configure one or both:

1. ntfy (recommended for phone push notifications): config set ntfy_url "https://ntfy.sh/<topic>"
2. postback (generic webhook): config set postback_url "<url>"

Steps:

1. Ask which channel(s) they want
2. For ntfy: run config set ntfy_url "<url>", suggest installing the ntfy app and subscribing to the topic
3. For postback: run config set postback_url "<url>"
4. Start the daemon: suggest todo daemon or docker compose up -d (from the cloned repo directory)
5. Both channels fire independently — a notification succeeds if at least one channel delivers

Bulk operations

When the user wants to operate on multiple tasks (e.g. "mark all high priority as in-progress"), iterate through the tasks:

1. Run list with appropriate filters to get IDs
2. Parse the output to extract IDs
3. Run the operation for each ID
4. Show the final list result

Status Values

Priority Values

Error Handling

• If a command fails, read the error message and explain it to the user in plain language
• If a task ID is not found, run list -a to help find the correct task
• If the database doesn't exist yet, any command will auto-create it — no special setup needed

Important Notes

• The todo binary must be in $PATH — see Setup section above if not found
• Data is stored at ~/.local/share/todo/todo.db
• All times displayed are in local timezone
• The list command hides done tasks by default — use -a to see them
• Task IDs are stable integers that auto-increment — they don't change when other tasks are deleted