ericblue/mac-agent-gateway/mag-reminders

⚠️ 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

Tool access: MCP first, HTTP as fallback

This skill works from two kinds of client, and which one you are determines how to call MAG.

If the mag-mcp tools are available, use them

Look for a tool whose name ends in mag_status and call it first. The tool name is prefixed differently per client:

• Claude Code: mcp__mag-mcp__mag_status, mcp__mag-mcp__reminders_list, ...
• Cowork (desktop-bridged): the same short names under the device bridge prefix — search

your available tools for reminders_list.

Tools in this skill are referred to by short name; call whichever concrete tool your session exposes. Do not hard-code a prefix — search for the short name and call the match. A skill that assumes one prefix silently finds nothing on the other client.

• mag_status
• reminders_list
• reminders_lists
• reminders_create
• reminders_update
• reminders_complete
• reminders_delete
• reminders_manage_list

mag_status returns MAG's health and its live capability flags. If a call fails with a 403, that capability is switched off in MAG's config — report that rather than retrying.

If no MCP tool is present, use the HTTP API below

Agents that reach MAG over HTTP (OpenClaw, remote hosts, SSH tunnels) should use the curl recipes documented in the rest of this skill.

Important — Cowork cannot use the HTTP path. Cowork runs inside a Linux VM with an egress allowlist and no route to the host's loopback, so curl http://localhost:8123 will fail there no matter how MAG is configured. In Cowork the MCP tools are the only way in. If neither the tools nor a reachable MAG are available, say so and stop — do not fall back to running remindctl or imsg directly.

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:

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:

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"
  }
}

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