reminders

Fuzzy search and browse Apple Reminders from the command line or as an MCP server.

Features

• Fuzzy search with typo tolerance across all your reminders
• Create reminders - add new reminders via CLI or MCP
• Browse by list - view reminders organized by list
• Filter by status - pending, completed, flagged, or due soon
• Auto-indexing - index automatically rebuilds when reminders change
• Multiple interfaces - CLI, MCP server, or Claude Code plugin

Requirements

• macOS (reads from Apple Reminders database)
• Node.js 22+
• Full Disk Access permission for your terminal

Installation

Homebrew

brew install cardmagic/tap/reminders

npm

npm install -g @cardmagic/reminders

Claude Code Plugin (recommended)

Install as a plugin to get skills (auto-invoked) and slash commands:

# Add the marketplace
claude plugin marketplace add cardmagic/ai-marketplace

# Install the plugin
claude plugin install reminders@cardmagic

This gives you:

• Skill: Claude automatically searches reminders when you ask about tasks/todos
• Slash commands: /reminders:search, /reminders:pending, /reminders:lists, and more

MCP Server

For direct MCP tool access without the plugin:

claude mcp add --transport stdio reminders -- npx -y @cardmagic/reminders --mcp

Or install globally first:

npm install -g @cardmagic/reminders
claude mcp add --transport stdio reminders -- reminders --mcp

From source

git clone https://github.com/cardmagic/reminders.git
cd reminders
pnpm install
pnpm build
pnpm link --global

# Then add as plugin OR MCP server:
claude plugin marketplace add cardmagic/ai-marketplace
claude plugin install reminders@cardmagic
# OR
claude mcp add --transport stdio reminders -- reminders --mcp

Granting Full Disk Access

The tool needs to read your Reminders database:

1. Open System Settings > Privacy & Security > Full Disk Access
2. Click + and add your terminal app (Terminal.app, iTerm, Warp, etc.)
3. Restart your terminal

Usage

CLI

# Show pending reminders (default action)
reminders

# Show all reminder lists with counts
reminders lists

# Show reminders in a specific list
reminders list "Groceries"
reminders list "Groceries" --all  # include completed

# Show pending/completed/flagged
reminders pending
reminders completed
reminders flagged

# Show reminders due within N days
reminders due --days 7

# Fuzzy search
reminders search "milk"
reminders search "meeting" --list "Work"
reminders search "groceries" --pending

# Show recently created reminders
reminders recent

# Show index statistics
reminders stats

# Force rebuild the index
reminders index

# Create a new reminder (auto-detects list from content)
reminders add "Buy milk"                    # → Groceries list
reminders add "Call mom" --list "Family" --due tomorrow
reminders add "Meeting prep" --due 2024-01-15 --time 09:00 --priority high
reminders add "Important task" --flagged --notes "Don't forget!"

# Mark a reminder as completed
reminders done "Buy milk"                   # Searches all lists
reminders done "meeting" --list "Work"      # Search in specific list

CLI Options

Option	Description
-l, --list <name>	Filter by list name
--completed	Show only completed
--pending	Show only pending
--flagged	Show only flagged
-n, --limit <n>	Max results (default varies by command)
-a, --all	Include completed (for list command)
-d, --days <n>	Days to look ahead (for due command)

Claude Code Plugin

When installed as a plugin, you get:

Skill (auto-invoked): Claude automatically manages reminders when you ask things like:

• "What's on my grocery list?"
• "Show my pending tasks"
• "What reminders are due this week?"
• "Add milk to my grocery list"
• "Mark the milk reminder as done"

Slash Commands:

Command	Description
/reminders:search <query>	Fuzzy search with optional filters
/reminders:pending	Show pending reminders
/reminders:completed	Show recently completed
/reminders:flagged	Show flagged reminders
/reminders:due	Show reminders due soon
/reminders:lists	List all reminder lists
/reminders:list "Name"	Show reminders in a specific list
/reminders:create "Title"	Create a new reminder (auto-detects list)
/reminders:done "Title"	Mark a reminder as completed

MCP Server

When installed as an MCP server, these tools are available:

Tool	Description
search_reminders	Fuzzy search with optional filters
get_pending_reminders	Get incomplete reminders
get_completed_reminders	Get recently completed
get_flagged_reminders	Get flagged reminders
get_due_reminders	Get reminders due within N days
list_reminder_lists	List all lists with counts
get_list_reminders	Get reminders in a specific list
get_reminder_stats	Get index statistics
create_reminder	Create a new reminder (auto-detects list)
complete_reminder	Mark a reminder as completed

Manual MCP Configuration

For Claude Desktop or VS Code, add to your MCP configuration:

{
  "mcpServers": {
    "reminders": {
      "command": "npx",
      "args": ["-y", "@cardmagic/reminders", "--mcp"]
    }
  }
}

For codex, you can add the MCP manually as well:

codex mcp add reminders -- npx -y @cardmagic/reminders --mcp

How It Works

1. Auto-Indexing: On first run (or when reminders change), the tool:

   • Reads Apple Reminders SQLite databases
   • Builds a SQLite FTS5 full-text search index
   • Creates a MiniSearch fuzzy search index

2. Searching: Queries both indexes for best results with typo tolerance

3. Storage: Index files are stored in ~/.reminders/:

   • index.db - SQLite FTS5 database
   • fuzzy.json - MiniSearch index
   • stats.json - Index statistics

License

MIT