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

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:

MCP Server

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

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