Starship Integration

Overview

Integrate md-todo with Starship to see your todo stats right in your shell prompt.

Quick Start

1. Verify the Status Command Works

sidedraft-md-todo --status
sidedraft-md-todo --status ~/todos
sidedraft-md-todo --status ~/todos --format pending

2. Set Your Todo Path

Add this to your ~/.zshrc:

export SD_TODO_PATH="$HOME/todos"

3. Configure Starship

Add to ~/.config/starship.toml:

[custom.sdtodo]
command = "sidedraft-md-todo --status $SD_TODO_PATH"
when = "test -d $SD_TODO_PATH || test -f $SD_TODO_PATH"
format = "[$symbol$output]($style) "
symbol = "📝 "
style = "bold yellow"
description = "Show todo status from SideDraft Markdown ToDo"

4. Reload Your Shell

source ~/.zshrc

What You’ll See

Your prompt will now show:

~/projects/my-app on main  📝 3/5 [work]

Where:

📝 = todo indicator
3/5 = 3 pending out of 5 total todos
[work] = active category (only in folder mode)

Customization

Show Only Pending Count

[custom.sdtodo]
command = "sidedraft-md-todo --status $SD_TODO_PATH --format pending"
format = "[$symbol$output]($style) "
symbol = "✓ "
style = "bold green"

Output: ✓ 3

Show Category Only

[custom.sdtodo]
command = "sidedraft-md-todo --status $SD_TODO_PATH --format category"
format = "[$symbol$output]($style) "
symbol = "📂 "
style = "bold blue"

Output: 📂 work

Color-Coded by Pending Count

# Green if 0-2 pending
[custom.sdtodo_low]
command = "sidedraft-md-todo --status $SD_TODO_PATH"
when = "test $(sidedraft-md-todo --status $SD_TODO_PATH --format pending) -le 2"
format = "[$symbol$output]($style) "
symbol = "✓ "
style = "bold green"

# Yellow if 3-5 pending
[custom.sdtodo_med]
command = "sidedraft-md-todo --status $SD_TODO_PATH"
when = "test $(sidedraft-md-todo --status $SD_TODO_PATH --format pending) -le 5 && test $(sidedraft-md-todo --status $SD_TODO_PATH --format pending) -gt 2"
format = "[$symbol$output]($style) "
symbol = "📝 "
style = "bold yellow"

# Red if 6+ pending
[custom.sdtodo_high]
command = "sidedraft-md-todo --status $SD_TODO_PATH"
when = "test $(sidedraft-md-todo --status $SD_TODO_PATH --format pending) -gt 5"
format = "[$symbol$output]($style) "
symbol = "⚠️  "
style = "bold red"

Advanced: Per-Directory Categories

Show different categories based on your current directory:

# In ~/.zshrc
function set_todo_category() {
  case "$PWD" in
    */work/*) export SD_TODO_PATH="$HOME/todos/work" ;;
    */personal/*) export SD_TODO_PATH="$HOME/todos/personal" ;;
    *) export SD_TODO_PATH="$HOME/todos" ;;
  esac
}

# Run before each prompt
precmd_functions+=(set_todo_category)

Troubleshooting

Module Not Showing

# Check if sd-todo is in PATH
which sidedraft-md-todo

# Check if SD_TODO_PATH is set
echo $SD_TODO_PATH

# Test the command manually
sidedraft-md-todo --status $SD_TODO_PATH

Wrong Category Showing

# Check active category
cat $SD_TODO_PATH/.sd-todo-config

Slow Prompt

The status command is optimized to run in < 50ms. If you notice slowness:

# Measure execution time
time sidedraft-md-todo --status $SD_TODO_PATH

# If it's slow, check your todo file size
wc -l $SD_TODO_PATH/*.md