apple-reminders

# apple-reminders

Drive Apple Reminders from the terminal via [`remindctl`](https://github.com/steipete/remindctl). Reminders sync across Apple devices through iCloud.

## Setup check (lazy — do NOT probe every turn)

Do **not** run a `remindctl status` probe before each request. Just run the
`remindctl` command the user asked for directly. Only when a command
**fails** map the error to a Setup playbook branch:

- stderr contains `command not found: remindctl` → **Setup playbook → "remindctl is not installed"**.
- output says permission `denied` / `not determined` / `restricted` → **Setup playbook → "Reminders permission missing"**.
- macOS not detected → reply that this skill is macOS-only and stop. Do NOT try to install anything.

If unsure which branch applies, capture stderr and ask the user before proceeding.

## Setup playbook (when prerequisites are missing)

When a check fails, the agent's job is to OFFER concrete help and EXECUTE the fix itself — not to dump install instructions on the user. Use this dialogue shape:

1. State plainly what is missing (one short reply).
2. Offer the most direct remediation the agent can perform via tools.
3. Wait for the user's yes/no reply.
4. On yes, execute the fix (the runtime approval gate will surface the command for confirmation).
5. Retry the original request; only then proceed.

### remindctl is not installed

Reply (solo `reply` step):

> "The `remindctl` utility is not installed. I can install it via Homebrew (`brew install steipete/tap/remindctl`) — it needs your confirmation and takes about 20 seconds. Install it?"

On yes:

```
[{ "tool": "os.shell.run", "args": { "cmd": "brew", "args": ["install", "steipete/tap/remindctl"] } }]
```

After install, retry the original command.

If `brew` itself is missing, do NOT attempt to bootstrap Homebrew — reply: "You don't have Homebrew installed. Install it manually from https://brew.sh/, then I'll continue."

### Reminders permission missing

Unlike Notes Automation, `remindctl` has its own CLI command to request the permission — the agent CAN do it directly. Offer + execute:

> "`remindctl` doesn't have permission to access Reminders. Request it now? A system dialog will appear — click \"Allow\" in it."

On yes:

```
[{ "tool": "os.shell.run", "args": { "cmd": "remindctl", "args": ["authorize"] } }]
```

Then re-run `remindctl status` to verify. If it still says `denied`, fall back to opening System Settings:

```
[{ "tool": "os.shell.run", "args": { "cmd": "open", "args": ["x-apple.systempreferences:com.apple.preference.security?Privacy_Reminders"] } }]
```

…and ask the user to flip the toggle for the terminal/agent process, then re-check.

## When to use

- The user mentions "reminder" or "Reminders app".
- Creating personal to-dos with due dates that should appear on their iPhone / iPad.
- Listing or completing items in an Apple Reminders list.

## When NOT to use

- Scheduling agent-driven background work — use the `tasks.schedule` / `tasks.cron` tools.
- Calendar events with a fixed start/end time and attendees — use a calendar skill.
- Project / engineering task management — use GitHub Issues, Notion, etc.
- If the user says "remind me" but actually means an in-agent alert, clarify before reaching for `remindctl`.

## Common operations

All examples invoke `os.shell.run` with `cmd: "remindctl"` and the `args` array shown. Add `["--json"]` to any read command for machine-readable output.

### View

| Goal | args |
|---|---|
| Today | `["today"]` (or just `[]` — `today` is the default) |
| Tomorrow | `["tomorrow"]` |
| This week | `["week"]` |
| Past due | `["overdue"]` |
| Everything | `["all"]` |
| Specific date | `["2026-01-04"]` |
| JSON output | append `"--json"` to any of the above |
| TSV output | append `"--plain"` |
| Counts only | append `"--quiet"` |

### Manage lists

| Goal | args |
|---|---|
| List all lists | `["list"]` |
| Show items in a list | `["list", "Work"]` |
| Create a list | `["list", "Projects", "--create"]` |
| Delete a list | `["list", "Work", "--delete"]` |

### Create reminders

| Goal | args |
|---|---|
| Quick add | `["add", "Buy milk"]` |
| Add with list and due | `["add", "--title", "Call mom", "--list", "Personal", "--due", "tomorrow"]` |
| Add with explicit datetime | `["add", "--title", "Meeting prep", "--due", "2026-02-15 09:00"]` |

### Complete / delete

| Goal | args |
|---|---|
| Complete one or more by id | `["complete", "1", "2", "3"]` |
| Delete by id | `["delete", "4A83", "--force"]` |

## Date formats

Accepted by `--due` and date filters:

- Relative: `today`, `tomorrow`, `yesterday`
- Date: `YYYY-MM-DD`
- Date+time: `YYYY-MM-DD HH:mm`
- ISO 8601: `2026-01-04T12:34:56Z`

## Rules

1. When the user says "remind me", clarify: Apple Reminders (syncs to phone) vs an agent-driven alert (`tasks.schedule` / `tasks.cron`).
2. Always confirm reminder content, list, and due date with the user before creating or completing.
3. Prefer `--json` whenever you need to parse the output programmatically; the human-formatted view changes between releases.