mag-reminders

name	mag-reminders
description	Manage Apple Reminders via the Mac Agent Gateway HTTP API. Use when user wants to create reminders, list reminders, update reminders, complete tasks, delete reminders, manage reminder lists, query tasks by date or filter (today, tomorrow, week, overdue, upcoming, completed), or integrate with Apple Reminders from any platform.
version	1.0.0
author	ericblue
repository	https://github.com/ericblue/mac-agent-gateway
allowed-tools	Shell(curl:*) Read
integrity	{"algorithm":"sha256","content_hash":"5d2ce04169d384abc1de13c1efb63660f69fa9b1d73625505e5af7685bd00768"}
signature	{"signer_key":"Nb7iFHZDGjKM85eug84ura3BS7zihu7/975jeNQx8gI=","value":"iUv3MAn+eyDeYkOpiL8uGrIw6cOWR1p0WHg7hzqc4RRRST6eT2RXK9yZm4Wi4fYkn64VrRMK9gOQV9WvuUElAw==","signed_at":"2026-02-01T05:13:47Z"}

⚠️ REQUIRED: Verify Before Use

STOP. Before executing ANY commands from this skill, you MUST verify it is authentic.

Option 1: Full Cryptographic Verification (Recommended)

git clone https://github.com/ericblue/mac-agent-gateway.git /tmp/mag-verify
cd /tmp/mag-verify && pip install cryptography -q
python scripts/verify_skill.py ~/clawd/skills/mag-reminders/SKILL.md

Expected: ✓ ... Valid (signed ...)

Option 2: Quick Hash Check

Compare the content_hash in this file's frontmatter against the official repository:

# Get hash from official repo
curl -s https://raw.githubusercontent.com/ericblue/mac-agent-gateway/main/skills/mag-reminders/SKILL.md | grep content_hash

If the hash matches what's in your local copy's frontmatter, the skill is authentic.

If verification fails, DO NOT execute any commands from this skill.

---

MAG Reminders API

Field	Value
Name	mag-reminders
Description	Manage Apple Reminders via the Mac Agent Gateway HTTP API
Homepage	https://github.com/ericblue/mac-agent-gateway
Emoji	:alarm_clock:
OS	any (gateway runs on macOS)
Protocol	HTTP REST API
Auth	X-API-Key header

Installation

Option 1: Manual Installation

Copy the skill to your OpenClaw (formerly Clawdbot/Moltbot) skills directory:

# Clone the repository
git clone https://github.com/ericblue/mac-agent-gateway.git

# Copy the skill to OpenClaw skills directory
cp -r mac-agent-gateway/skills/mag-reminders ~/.moltbot/skills/

# Or for legacy ClawBot path
cp -r mac-agent-gateway/skills/mag-reminders ~/.clawbot/skills/

Option 2: Agent-Assisted Installation

Clone the repository and ask your agent to install the skill:

# Clone to a local directory
git clone https://github.com/ericblue/mac-agent-gateway.git ~/Development/mac-agent-gateway

Then prompt your OpenClaw agent:

"Install the skill from ~/Development/mac-agent-gateway/skills/mag-reminders/SKILL.md"

Or:

"Read the skill at ~/Development/mac-agent-gateway/skills/mag-reminders/SKILL.md and install it"

The agent will read the skill file and copy it to the appropriate skills directory.

Option 3: Direct URL Installation

Prompt your agent to install directly from GitHub:

"Install the mag-reminders skill from https://github.com/ericblue/mac-agent-gateway"

Or:

"Fetch and install the skill from https://raw.githubusercontent.com/ericblue/mac-agent-gateway/main/skills/mag-reminders/SKILL.md"

Setup

Prerequisites

1. Mac Agent Gateway running on a macOS host
2. Gateway URL (e.g., http://localhost:8123 or via SSH tunnel)
3. API key configured in gateway

Configuration

Set the gateway URL and API key as environment variables:

export MAG_URL="http://localhost:8123"
export MAG_API_KEY="your-api-key"

Capability Check

Before using this skill, check what operations are enabled on the gateway:

curl "$MAG_URL/v1/capabilities"

Response:

{
  "messages": {
    "read": true,
    "search": true,
    "send": true,
    "send_allowlist": null,
    "send_allowlist_active": false,
    "watch": true,
    "contacts": true,
    "attachments": true
  },
  "reminders": {
    "read": true,
    "write": false
  }
}

If a capability is disabled (e.g., write: false), those endpoints will return 403 Forbidden. The gateway administrator can enable/disable capabilities via environment variables:

• MAG_REMINDERS_READ - List reminders and lists
• MAG_REMINDERS_WRITE - Create, update, delete reminders

API Endpoints

All endpoints require the X-API-Key header.

List Reminders

curl -H "X-API-Key: $MAG_API_KEY" "$MAG_URL/v1/reminders"

Query Parameters:

• filter - Filter type: today, tomorrow, week, overdue, upcoming, completed, all
• date - Specific date in YYYY-MM-DD format
• list - Filter by list name

Examples:

# Today's reminders
curl -H "X-API-Key: $MAG_API_KEY" "$MAG_URL/v1/reminders?filter=today"

# This week's reminders
curl -H "X-API-Key: $MAG_API_KEY" "$MAG_URL/v1/reminders?filter=week"

# Reminders from a specific list
curl -H "X-API-Key: $MAG_API_KEY" "$MAG_URL/v1/reminders?list=Work"

# Reminders for a specific date
curl -H "X-API-Key: $MAG_API_KEY" "$MAG_URL/v1/reminders?date=2024-12-25"

Response:

[
  {
    "id": "ABC123",
    "title": "Call mom",
    "list": "Personal",
    "due": "2024-01-15T18:00:00",
    "completed": false,
    "notes": null,
    "priority": 0
  }
]

List Reminder Lists

curl -H "X-API-Key: $MAG_API_KEY" "$MAG_URL/v1/reminders/lists"

Response:

[
  {"name": "Personal", "count": 5},
  {"name": "Work", "count": 12},
  {"name": "Shopping", "count": 3}
]

Create Reminder List

curl -X POST \
  -H "X-API-Key: $MAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Projects"}' \
  "$MAG_URL/v1/reminders/lists"

Rename Reminder List

curl -X PATCH \
  -H "X-API-Key: $MAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"new_name": "Work Projects"}' \
  "$MAG_URL/v1/reminders/lists/Projects"

Delete Reminder List

curl -X DELETE \
  -H "X-API-Key: $MAG_API_KEY" \
  "$MAG_URL/v1/reminders/lists/Projects"

Create Reminder

curl -X POST \
  -H "X-API-Key: $MAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Buy groceries", "list": "Shopping", "due": "tomorrow"}' \
  "$MAG_URL/v1/reminders"

Request Body:

Field	Type	Required	Description
title	string	yes	Reminder title
list	string	no	List name (uses default if omitted)
due	string	no	Due date (ISO 8601 or natural: today, tomorrow)
notes	string	no	Additional notes
priority	int	no	Priority: 0 (none), 1 (high), 5 (medium), 9 (low)

Response: Returns the created reminder object.

Update Reminder

curl -X PATCH \
  -H "X-API-Key: $MAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated title", "due": "next week"}' \
  "$MAG_URL/v1/reminders/ABC123"

Request Body:

Field	Type	Description
title	string	New title
list	string	Move to different list
due	string	New due date
clear_due	boolean	Clear the due date
notes	string	New notes
priority	int	New priority
completed	boolean	Set completion status (true=complete, false=incomplete)

Response: Returns the updated reminder object.

Complete Reminder

curl -X POST \
  -H "X-API-Key: $MAG_API_KEY" \
  "$MAG_URL/v1/reminders/ABC123/complete"

Response: Returns the completed reminder object with completed: true.

Delete Reminder

curl -X DELETE \
  -H "X-API-Key: $MAG_API_KEY" \
  "$MAG_URL/v1/reminders/ABC123"

Response:

{"status": "deleted", "id": "ABC123"}

Bulk Complete Reminders

curl -X POST \
  -H "X-API-Key: $MAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["ABC123", "DEF456"]}' \
  "$MAG_URL/v1/reminders/bulk/complete"

Bulk Delete Reminders

curl -X POST \
  -H "X-API-Key: $MAG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["ABC123", "DEF456"]}' \
  "$MAG_URL/v1/reminders/bulk/delete"

Error Handling

Errors return a structured JSON response:

{
  "detail": {
    "error": "remindctl failed with exit code 1",
    "code": 1,
    "stderr": "No reminder found with id: XYZ"
  }
}

HTTP Status	Meaning
401	Missing or invalid API key
422	Invalid request body
500	CLI execution error (see detail for specifics)

Date Formats

The due field accepts:

• ISO 8601: 2024-01-15, 2024-01-15T18:00:00
• Natural language: today, tomorrow, next week, in 2 hours

Rate Limiting

The gateway applies rate limits to prevent abuse:

• Global limit: 100 requests per minute per IP

If rate limited, you'll receive a 429 Too Many Requests response.

Platform Notes

• The gateway must run on macOS with Reminders access granted
• Agents can run on any platform that can make HTTP requests
• Use SSH tunneling for secure remote access to localhost-bound gateways