RTM Reminder Zsh Plugin

July 29, 2025 · View on GitHub

A lightweight Zsh plugin that displays urgent Remember The Milk tasks after each command execution. Clean, non-intrusive, and terminal-only.

Features

📋 Shows urgent RTM tasks after command execution
⚡ Smart caching to avoid excessive API calls
🔧 Configurable via simple shell config file
🚀 Zero dependencies (except rtm CLI)
🤫 Quiet when no urgent tasks

Prerequisites

Zsh shell
Remember The Milk CLI installed and configured
RTM CLI logged in to your account

Installation

Option 1: Manual Installation

Clone this repository:

git clone https://github.com/aranel616/rtm-reminder-zsh.git ~/.config/rtm-reminder-zsh

Add to your ~/.zshrc:

source ~/.config/rtm-reminder-zsh/rtm-reminder-zsh.plugin.zsh

Reload your shell:
```
source ~/.zshrc
```

Option 2: Oh My Zsh (Clone)

Clone to Oh My Zsh custom plugins directory:

git clone https://github.com/aranel616/rtm-reminder-zsh.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/rtm-reminder-zsh

Add to your ~/.zshrc plugins list:
```
plugins=(... rtm-reminder-zsh)
```
Reload your shell:
```
source ~/.zshrc
```

Option 3: Oh My Zsh (Symlink Development)

For development or if you have the repo cloned elsewhere:

Clone the repository (if not already cloned):

git clone https://github.com/aranel616/rtm-reminder-zsh.git ~/code/rtm-reminder-zsh

Create symlink to Oh My Zsh plugins:

ln -sfn ~/code/rtm-reminder-zsh ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/rtm-reminder-zsh

Add to your ~/.zshrc plugins list:
```
plugins=(... rtm-reminder-zsh)
```
Reload your shell:
```
source ~/.zshrc
```

Option 4: Zinit/Zplug

For Zinit:

zinit load "aranel616/rtm-reminder-zsh"

For Zplug:

zplug "aranel616/rtm-reminder-zsh"

Configuration

Create a config file at ~/.config/rtm-reminder-zsh/config:

# Copy the example config (adjust path based on installation method)
# For Manual Installation:
cp ~/.config/rtm-reminder-zsh/config/config.example ~/.config/rtm-reminder-zsh/config

# For Oh My Zsh Installation (clone or symlink):
mkdir -p ~/.config/rtm-reminder-zsh
cp ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/rtm-reminder-zsh/config/config.example ~/.config/rtm-reminder-zsh/config

# Edit the configuration
nano ~/.config/rtm-reminder-zsh/config

Configuration Options

Option	Default	Description
`URGENCY_QUERY`	`'dueBefore:today or dueWithin:"1h"'`	RTM query to find urgent tasks
`MAX_TASKS`	`2`	Maximum number of tasks to display
`CHECK_INTERVAL_MINUTES`	`5`	How often to check for tasks (in minutes)
`SORT_TYPE`	`'lsd'`	RTM sort command (ls/lsd/lsp)
`SHOW_DIVIDER`	`true`	Show divider line above reminders
`DIVIDER_TEMPLATE`	`'simple'`	Divider style template
`DIVIDER_CHAR`	`'─'`	Character for divider line
`DIVIDER_FORMAT`	`''`	Custom Oh-My-Zsh format string

Example Configuration

# Show only overdue tasks
URGENCY_QUERY='dueBefore:today'

# Show up to 3 tasks
MAX_TASKS=3

# Check every 10 minutes
CHECK_INTERVAL_MINUTES=10

# Use styled divider (requires Oh-My-Zsh)
DIVIDER_TEMPLATE='styled'

Divider Customization

The plugin supports highly customizable dividers that are compatible with Oh-My-Zsh prompt formatting.

Divider Templates

Template	Description	Example
`simple`	Basic line across screen	`────────────────────────────────`
`styled`	Blue styled line	────────────────────────────────
`user`	Include username	`john ─────────────────────────`
`time`	Include current time	`14:30 ───────────────────────`
`custom`	Use `DIVIDER_FORMAT`	Fully customizable

Oh-My-Zsh Compatible Custom Formats

When using DIVIDER_TEMPLATE='custom', you can use full zsh prompt expansion:

# Colored divider with username and hostname
DIVIDER_FORMAT='%{$fg[cyan]%}%n@%m%{$reset_color%} %{$fg[blue]%}${(l:$((COLUMNS-10))::─:)}%{$reset_color%}'

# Time-stamped divider
DIVIDER_FORMAT='%D{%H:%M:%S} %{$fg[green]%}${(l:$((COLUMNS-9))::═:)}%{$reset_color%}'

# Fancy divider with RTM branding
DIVIDER_FORMAT='%{$fg_bold[yellow]%}── RTM ──${(l:$((COLUMNS-9))::─:)}%{$reset_color%}'

Zsh Prompt Expansion Reference

The plugin supports all standard zsh prompt sequences:

%n - Username
%m - Hostname
%D{format} - Date/time (e.g., %D{%H:%M})
%{...%} - Literal escape sequences for colors
${(l:width::char:)} - Left-pad with character to width
$fg[color] - Oh-My-Zsh color variables
$reset_color - Reset colors

Color Examples

# Available colors (Oh-My-Zsh)
$fg[red] $fg[green] $fg[yellow] $fg[blue] $fg[magenta] $fg[cyan] $fg[white]
$fg_bold[color] $fg_no_bold[color] $reset_color

# Rainbow divider
DIVIDER_FORMAT='%{$fg[red]%}──%{$fg[yellow]%}──%{$fg[green]%}──%{$fg[cyan]%}──%{$fg[blue]%}──%{$fg[magenta]%}${(l:$((COLUMNS-12))::─:)}%{$reset_color%}'

Usage

Once installed, the plugin runs automatically. After each command execution, it will:

Check if the configured interval has passed
Query RTM for urgent tasks
Display a clean list of tasks (if any)
Cache the result to avoid excessive API calls

Example output:

$ ls -la
total 48
drwxr-xr-x  6 user  staff   192 Jan 15 10:30 .
drwxr-xr-x  3 user  staff    96 Jan 15 10:29 ..
-rw-r--r--  1 user  staff  1234 Jan 15 10:30 README.md

📋 RTM Reminders:
  • Call dentist - Due today
  • Submit report - Due in 30 minutes

$

Customization

Custom RTM Queries

The plugin uses RTM's query syntax. Examples:

# High priority tasks due soon
URGENCY_QUERY='priority:1 and dueBefore:tomorrow'

# Tasks from specific lists
URGENCY_QUERY='list:Work and dueBefore:today'

# Overdue tasks only
URGENCY_QUERY='dueBefore:today'

Performance Tuning

Set CHECK_INTERVAL_MINUTES=0 to check after every command (not recommended)
Increase interval for less frequent checks and better performance
The plugin creates cache files in ~/.cache/rtm-reminder-zsh/

Troubleshooting

Plugin not working

Check if RTM CLI is installed and working:
```
rtm ls
```
Verify plugin is loaded:
```
echo $RTM_REMINDER_PLUGIN_DIR
```

Check if config file exists and is readable:

ls -la ~/.config/rtm-reminder-zsh/config

No tasks showing

Test your RTM query directly:

rtm lsd "dueBefore:today or dueWithin:\"1h\""

Check the cache file timestamp:

cat ~/.cache/rtm-reminder-zsh/last_check

License

MIT License - feel free to modify and share!

✨ Vibe coded by Claude Code ✨

Contributing

Issues and pull requests welcome! This plugin is designed to be lightweight and maintainable.