{
  "markdown": "<p align=\"center\">\n  <img src=\"docs/logo.svg\" alt=\"remi\" width=\"80\">\n</p>\n\n<h1 align=\"center\">remi</h1>\n\n<p align=\"center\"><strong>The CLI that Apple should have built for Reminders.</strong></p>\n\nCreate lists, add reminders, organize them into sections, and have everything sync across all your Apple devices — from the terminal.\n\n<p align=\"center\">\n  <img src=\"docs/demo.gif\" alt=\"remi demo\" width=\"500\">\n</p>\n\n## Why remi?\n\n- **Sections with iCloud sync** — the only CLI that supports Apple Reminders sections. Create them, assign reminders, move between them, and it all syncs.\n- **Natural language** — `--due \"next tuesday\"`, `--repeat \"every 2 weeks on monday,friday\"`\n- **Fuzzy matching** — type `remi list shopping` instead of `remi list \"Groceries / Shopping List\"`\n- **Agent-first** — structured JSON output, Claude Code plugin, skills.sh skill, OpenClaw compatible\n- **Fast** — compiled Swift helpers, no Electron, no GUI\n\n### vs other tools\n\n| | remi | [remindctl](https://github.com/steipete/remindctl) | [reminders-cli](https://github.com/keith/reminders-cli) |\n|---|---|---|---|\n| Sections | **Yes** | No | No |\n| Section sync (iCloud) | **Yes** | N/A | N/A |\n| Recurrence | **Yes** | Yes | No |\n| Natural language dates | **Yes** | Yes | No |\n| JSON output | **Yes** | Yes | No |\n| AI agent integration | **Yes** | Partial | No |\n\n## Install\n\n```bash\nbrew tap mattheworiordan/tap && brew install remi\n```\n\nOr via npm:\n\n```bash\nnpm install -g @mattheworiordan/remi\n# or run without installing\nnpx @mattheworiordan/remi lists\n```\n\n## Quick start\n\n```bash\nremi lists                                              # See all lists\nremi list \"Groceries\"                                   # View a list (fuzzy: remi list groceries)\nremi add \"Groceries\" \"Buy milk\" --section \"Dairy\"       # Add to a section\nremi today                                              # What's due today?\nremi complete \"Groceries\" \"milk\"                        # Fuzzy complete\n```\n\n## Usage\n\n### Check what's due\n\n```bash\nremi today                    # Due today\nremi overdue                  # Past due\nremi upcoming --days 7        # Coming up\nremi search \"dentist\"         # Search across all lists\n```\n\n### Manage reminders\n\n```bash\nremi add \"Work\" \"Review PR\" --due \"next friday\" --priority high\nremi add \"Work\" \"Standup\" --due tomorrow --repeat daily\nremi complete \"Work\" \"standup\"\nremi update \"Work\" \"Review PR\" --due \"in 3 days\"\nremi delete \"Work\" \"Review PR\" --confirm\n```\n\nDates: `tomorrow`, `next tuesday`, `in 3 days`, or `YYYY-MM-DD`\nRecurrence: `daily`, `weekly`, `monthly`, `every 2 weeks`, `every 3 months on monday,friday`\n\n### Organize with sections\n\n```bash\nremi sections \"Groceries\"                                # List sections\nremi create-section \"Groceries\" \"Produce\"                # Create a section\nremi add \"Groceries\" \"Bananas\" --section \"Produce\"       # Add to a section\nremi move \"Groceries\" \"Bananas\" --to-section \"Dairy\"     # Move between sections\n```\n\nSections sync to iCloud via CRDT vector clocks. See [how it works](docs/APPLE_REMINDERS_INTERNALS.md).\n\n### JSON output\n\nEvery command supports `--json` for machine-readable output:\n\n```bash\nremi today --json\n# {\"success\": true, \"data\": [...]}\n```\n\n## AI agent integration\n\nremi is designed for AI agents. Use it as an MCP server, Claude Code plugin, or skill:\n\n### MCP server\n\n```json\n{\n  \"mcpServers\": {\n    \"remi\": {\n      \"command\": \"remi\",\n      \"args\": [\"--mcp\"]\n    }\n  }\n}\n```\n\n16 tools: `remi_lists`, `remi_add`, `remi_complete`, `remi_move`, `remi_today`, `remi_search`, and more — all with fuzzy matching and structured responses.\n\n### Other integrations\n\n```bash\n# Claude Code plugin\nclaude plugin marketplace add mattheworiordan/remi\n\n# skills.sh\nnpx skills add mattheworiordan/remi\n\n# OpenClaw\nclawhub install remi\n```\n\n## Permissions\n\nOn first run, macOS will ask you to grant Reminders access (click Allow). Section features also need Full Disk Access for your terminal app.\n\n```bash\nremi authorize    # Guides you through both\nremi doctor       # Shows what's granted\n```\n\n## Requirements\n\n- macOS 13+ (Ventura or later)\n- Node.js 18+\n- Xcode Command Line Tools (`xcode-select --install`)\n\n## How it works\n\nremi uses three layers because Apple never exposed sections in their public API:\n\n| Layer | What | Why |\n|-------|------|-----|\n| **EventKit** | Reminder CRUD, queries, recurrence | Stable public API |\n| **ReminderKit** | Section CRUD | Private framework — only way to create sections that sync |\n| **SQLite + Token Maps** | Section membership | Direct database writes with CRDT vector clocks for iCloud sync |\n\nThe [full reverse-engineering story](docs/APPLE_REMINDERS_INTERNALS.md) explains what we discovered about Apple's undocumented sync architecture.\n\n## Contributing\n\n```bash\ngit clone https://github.com/mattheworiordan/remi.git && cd remi\nnpm install && npm run build:swift && npm run build\nnpm test                        # Unit tests\nnpm run test:integration        # Integration tests (needs Reminders access)\n```\n\n## License\n\nMIT — [Matthew O'Riordan](https://github.com/mattheworiordan)\n",
  "bytes": 5102,
  "sha": "b398b39f00fdd124767b3ae7b423cb5b5a05f00dcc0fc6cd9d516aef5968e704",
  "repo_slug": "mattheworiordan/remi",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mattheworiordan_remi_3a1471f6/readme"
}