go-reminder

A command-line reminder app that watches your markdown todo list and notifies you 8 hours before scheduled tasks.

Features

• 📝 Markdown-based - Write tasks in simple markdown format
• 🔔 Desktop Notifications - Native Linux notifications via notify-send
• 🔊 Sound Alerts - Multiple sound fallbacks for different systems
• 📂 File Watching - Automatically detects changes to your todo file
• 💾 Persistent State - Remembers triggered reminders across restarts
• 🚀 Autostart - Optional auto-start on login (Arch Linux)
• 🕐 Timezone Support - Configurable timezone for accurate scheduling

Installation

Quick Install

# Build from source
git clone <repository-url>
cd go-reminder
go build -o go-reminder .

# Install to PATH
sudo cp go-reminder /usr/local/bin/

Verify Installation

go-reminder --version
go-reminder help

Quick Start

1. Set Up Your Todo File

Create a markdown file (e.g., ~/todos.md):

# My Tasks

- [ ] Morning standup @2026-03-11 09:00
- [ ] Submit report @2026-03-11 17:00
- [ ] Team meeting @2026-03-12 14:00

Format: - [ ] Task description @YYYY-MM-DD HH:MM

2. Configure go-reminder

# Set your todo file
go-reminder config set ~/todos.md

# Set your timezone
go-reminder timezone set Asia/Jakarta

# (Optional) Enable autostart on login
go-reminder autostart enable

3. Start the Reminder

go-reminder start

That's it! The app will watch your file and notify you 8 hours before each task.

Usage

Commands

go-reminder [command]

Commands:
  start                     Start watching reminders (uses configured file)
  start <file.md>           Start watching a specific markdown file

  config                    Show current configuration
  config set <file.md>      Set the markdown file path

  timezone                  Show current timezone
  timezone set <timezone>   Set timezone (e.g., UTC, America/New_York)

  autostart enable          Enable autostart on login (Arch Linux)
  autostart disable         Disable autostart

  state                     Show triggered reminders count
  state clear               Clear all trigger state

  help, --help, -h          Show help
  --version                 Show version

Examples

# Start with default configured file
go-reminder start

# Start with a specific file
go-reminder start /path/to/tasks.md

# Change timezone
go-reminder timezone set Europe/Berlin

# Check configuration
go-reminder config

# Clear trigger history (allows reminders to trigger again)
go-reminder state clear

# Disable autostart
go-reminder autostart disable

Configuration

Configuration is stored in ~/.config/go-reminder/config.json

{
  "markdown_file": "/home/user/todos.md",
  "timezone": "Asia/Jakarta",
  "autostart": true
}

How It Works

1. File Watching - Monitors your markdown file for changes using fsnotify
2. Periodic Checks - Scans for triggers every 30 seconds
3. Trigger Window - Activates 8 hours before scheduled time
4. Notifications - Sends desktop notification + plays sound
5. State Persistence - Saves triggered state to prevent duplicates
6. Auto-Cleanup - Removes old trigger state after 24 hours

Requirements

System Requirements

• Linux (tested on Arch Linux)
• Go 1.25+ (for building)

Optional Dependencies (for notifications)

• notify-send (libnotify) - Desktop notifications
• zenity - Fallback notifications
• paplay (PulseAudio) - Sound playback
• aplay (ALSA) - Fallback sound
• beep - PC speaker fallback

Install on Arch Linux:

sudo pacman -S libnotify zenity pulseaudio-alsa

File Format

# Any markdown file

## Section headers work fine

- [ ] Task one @2026-03-11 10:00
- [x] Completed tasks are also parsed @2026-03-11 11:00
- [ ] Task with spaces   @2026-03-12 15:30

### Notes

- Empty task names are ignored
- Invalid dates are skipped with a warning
- Both [ ] and [x] checkboxes are parsed

Troubleshooting

No sound playing

Check if sound files exist:

ls /usr/share/sounds/freedesktop/stereo/alarm-clock-elapsed.oga

Test sound manually:

paplay /usr/share/sounds/freedesktop/stereo/alarm-clock-elapsed.oga

No desktop notification

Test notify-send:

notify-send "Test" "This is a test notification"

Reminder triggers multiple times

Clear the state:

go-reminder state clear

Autostart not working

1. Ensure your desktop environment supports .desktop files
2. Check the desktop file: cat ~/.config/autostart/go-reminder.desktop
3. Verify the binary path is correct

File not found errors

Ensure the path is absolute:

go-reminder config set /home/user/todos.md

Development

Build

go build -o go-reminder .

Test

go test -v ./...

Run Tests with Coverage

go test -cover ./...

Project Structure

go-reminder/
├── main.go          # Main application logic
├── config.go        # Configuration management
├── state.go         # Persistent trigger state
├── main_test.go     # Unit tests
├── go.mod           # Go module file
└── README.md        # This file

License

MIT License - See LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: go test -v ./...
5. Submit a pull request

Changelog

See CHANGELOG for version history.

Support

For issues and feature requests, please open an issue on the repository.

---

Built with ❤️ using Go