pesterme

A CLI tool that pesters you about recurring tasks when you open your terminal.

Never forget to change your HVAC filter, backup your data, or review your budget again. pesterme tracks recurring tasks and displays color-coded reminders based on how overdue they are.

Features

• 📅 Recurring reminders - Set up tasks with custom intervals (days, weeks, months, years)
• 🎨 Color-coded status - Visual indicators from green (due today) to red (seriously overdue)
• 🔔 Terminal integration - See reminders automatically when you open your terminal
• 💾 Git backup - Optional automatic backup to a git repository
• ⏰ Snooze support - Postpone tasks temporarily when needed
• 📊 Completion history - Track when tasks were completed

Installation

npm install -g pesterme

Install from Source

git clone <repository-url>
cd pesterme
npm install
npm run build
npm link

Quick Start

# Add your first reminder
pesterme add "Change air filter" --every 3 months

# View all reminders
pesterme

# Mark a task as done (resets the timer)
pesterme done 1

# Set up automatic display on terminal startup
pesterme install

Usage Examples

# Add recurring reminders
pesterme add "Change HVAC filter" --every 3 months
pesterme add "Backup external drive" --every 2 weeks
pesterme add "Review budget" --every 1 month
pesterme add "Water plants" --every 7 days
pesterme add "Annual checkup" --every 1 year

# View all reminders
pesterme list

# Complete a task
pesterme done 1

# Snooze a reminder
pesterme snooze 2 --for 1 week

# Delete a reminder
pesterme delete 3

# Configure git backup
pesterme config --git-repo ~/backup/pesterme-data
pesterme config --auto-push

# Hide upcoming reminders when running 'pesterme' (e.g., on shell startup)
# Note: 'pesterme list' always shows all reminders including upcoming
pesterme config --hide-upcoming

# Show upcoming reminders in all contexts
pesterme config --show-upcoming

# View current configuration
pesterme config

Status Colors

Reminders are color-coded to help you prioritize:

• White - Upcoming (future due date)
• Green 🟢 - Due today
• Yellow 🟡 - Overdue 1-3 days
• Orange 🟠 - Overdue 4-7 days
• Red 🔴 - Overdue 8+ days

Shell Integration

Install shell integration to see reminders automatically when you open your terminal:

pesterme install

Supports zsh and bash. Restart your terminal after installation to activate.

To uninstall:

pesterme uninstall

Commands

• pesterme or pesterme list - Show all reminders
• pesterme add <name> --every <amount> <unit> - Add a new reminder
• pesterme done <id> - Mark reminder as complete
• pesterme snooze <id> --for <amount> <unit> - Postpone a reminder
• pesterme delete <id> - Delete a reminder
• pesterme config - View or modify settings
• pesterme install - Install shell integration
• pesterme uninstall - Remove shell integration

Documentation

Full documentation available in docs/usage.md

Data Storage

All data is stored in ~/.config/pesterme/:

• reminders.json - Your reminders and completion history
• config.json - Configuration settings

License

GLP-V2.0