# RTM Reminder Zsh Plugin

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](https://github.com/darrenburns/rtm) installed and configured
- RTM CLI logged in to your account

## Installation

### Option 1: Manual Installation

1. Clone this repository:
   ```bash
   git clone https://github.com/aranel616/rtm-reminder-zsh.git ~/.config/rtm-reminder-zsh
   ```

2. Add to your `~/.zshrc`:
   ```bash
   source ~/.config/rtm-reminder-zsh/rtm-reminder-zsh.plugin.zsh
   ```

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

### Option 2: Oh My Zsh (Clone)

1. Clone to Oh My Zsh custom plugins directory:
   ```bash
   git clone https://github.com/aranel616/rtm-reminder-zsh.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/rtm-reminder-zsh
   ```

2. Add to your `~/.zshrc` plugins list:
   ```bash
   plugins=(... rtm-reminder-zsh)
   ```

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

### Option 3: Oh My Zsh (Symlink Development)

For development or if you have the repo cloned elsewhere:

1. Clone the repository (if not already cloned):
   ```bash
   git clone https://github.com/aranel616/rtm-reminder-zsh.git ~/code/rtm-reminder-zsh
   ```

2. Create symlink to Oh My Zsh plugins:
   ```bash
   ln -sfn ~/code/rtm-reminder-zsh ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/rtm-reminder-zsh
   ```

3. Add to your `~/.zshrc` plugins list:
   ```bash
   plugins=(... rtm-reminder-zsh)
   ```

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

### Option 4: Zinit/Zplug

For Zinit:
```bash
zinit load "aranel616/rtm-reminder-zsh"
```

For Zplug:
```bash
zplug "aranel616/rtm-reminder-zsh"
```

## Configuration

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

```bash
# 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

```bash
# 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 | <span style="color:blue">────────────────────────────────</span> |
| `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:

```bash
# 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

```bash
# 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:

1. Check if the configured interval has passed
2. Query RTM for urgent tasks
3. Display a clean list of tasks (if any)
4. 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:

```bash
# 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

1. Check if RTM CLI is installed and working:
   ```bash
   rtm ls
   ```

2. Verify plugin is loaded:
   ```bash
   echo $RTM_REMINDER_PLUGIN_DIR
   ```

3. Check if config file exists and is readable:
   ```bash
   ls -la ~/.config/rtm-reminder-zsh/config
   ```

### No tasks showing

1. Test your RTM query directly:
   ```bash
   rtm lsd "dueBefore:today or dueWithin:\"1h\""
   ```

2. Check the cache file timestamp:
   ```bash
   cat ~/.cache/rtm-reminder-zsh/last_check
   ```

## License

MIT License - feel free to modify and share!

✨ *Vibe coded by [Claude Code](https://claude.ai/code)* ✨

## Contributing

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