/orchard

name: orchard
description: "Use the local Orchard app to interact with macOS Apple apps and services: Calendar, Reminders, Clock, Mail, Contacts, Notes, Music, Weather, Messages, Location/Maps, and Apple Shortcuts. Two execution paths reach the same running Orchard.app: the `orchard` CLI (default — use this if you have a Bash/shell tool, e.g. Claude Code, Codex CLI, Cursor) and a stdio MCP server, `orchard mcp`, exposed as prefixed MCP tools (fallback for sandboxes that cannot run the macOS CLI, e.g. Claude Cowork, bridged through Claude Desktop). Use when a task asks to read or manage local calendar events, reminders, Apple Mail, contacts, notes, iMessage/SMS, Apple Music playback/library, weather, current time/timezones, geocoding, routes, current location, or local Shortcuts."
metadata:
  version: "0.7.8"
  updated: "2026-10-06"
  tested_with:
    orchard_app: "0.6.4 (19)"
    orchard_cli: "0.6.4"

Orchard

Orchard exposes 52 Apple-app tools (Calendar, Reminders, Mail, Notes, Messages, Music, Weather, Contacts, Clock, Location/Maps, Shortcuts) through one running Orchard.app, reachable over two transports that carry the same tool set. **Default to the CLI.** Read "Which Channel" below first — it costs you nothing to check and prevents wasted turns.

Which Channel

Decide by looking at your own tool list first. Having a Bash tool is NOT enough to prove you can reach the CLI — sandboxed agents (e.g. Claude Cowork) have a Bash that runs inside an isolated Linux VM where the macOS CLI does not exist, while Orchard's MCP tools are still bridged in by the host.

• **You have a Bash/shell tool** (Claude Code, Codex CLI, Cursor, or any terminal-capable agent — the large majority of sessions) → try the **CLI first**. Continue to "Quick Start" below. It is cheaper than MCP (this file plus one on-demand reference beats preloading 52 MCP schemas), and it self-documents via `--help`.
• **You have no Bash/shell tool at all** → skip straight to `references/mcp-tools.md` and call the Orchard MCP tools (names ending in `__calendar_info`, `__mail_read`, etc.) directly. "Quick Start", "Known Pitfalls", and "Common Workflows" below are written for the CLI and do not apply to you. "Core Rules" still applies — read it, it describes the tools, not the transport.

If you have Bash but `scripts/resolve-orchard.sh --route` reports `missing_app`, check your tool list for Orchard MCP tools before concluding anything:

• **Orchard MCP tools ARE in your tool list** → your shell is sandboxed away from the user's Mac (Claude Cowork's Linux VM is the typical case), but the host has bridged Orchard's MCP server in. Switch to the MCP channel: read `references/mcp-tools.md` and use those tools. Do not tell the user anything is broken — nothing is.
• **No Orchard MCP tools either** → Orchard.app genuinely isn't installed or running on this Mac. Stop and tell the user to install/launch Orchard.app. Do not hunt further — every channel proxies to that same app.

Quick Start (CLI)

Resolve the CLI path first, then call that path for every command.

Run the bundled resolver first. If your current working directory is not this skill directory, use the absolute path to `scripts/resolve-orchard.sh`.

ORCHARD_BIN="$(./scripts/resolve-orchard.sh --bin)"
ORCHARD_ROUTE="$(./scripts/resolve-orchard.sh --route)"
ORCHARD_APP_PATH="$(./scripts/resolve-orchard.sh --app)"
"$ORCHARD_BIN" --version

Route rules:

• `global_cli`: use the globally installed `orchard` command. Do not reject it because it points at a Debug app; development machines often do that.
• `bundle_cli`: use the bundled `orchard-cli` inside `Orchard.app`. Continue the task. Optionally tell the user they can install the CLI tool from Orchard later for shell-wide `orchard` access.
• `missing_app`: see "Which Channel" above — check your tool list for Orchard MCP tools before telling the user anything is broken.

Prefer `--json` for machine-readable output. Orchard returns an outer JSON envelope:

{"output":"...string, object, or array...","success":true}

The `output` value may already be a JSON object/array, plain text, JSON text, or prose followed by JSON such as `Found 2 events:\n{...}`. If `output` is a string that contains JSON, strip text before the first JSON object/array and parse the nested payload before reasoning over records. (This envelope is a CLI-only convenience — see `references/mcp-tools.md` if you're on the MCP channel instead, where results look different.)

For the full command matrix, read `references/commands.md`.

Known Pitfalls (CLI)

• When testing an alternate app build, stop the installed app first, use that build's absolute bundled CLI path, set `ORCHARD_NO_AUTOLAUNCH=1`, and verify the GUI process path/socket owner. A CLI version alone does not identify the running executor.
• Use `"$ORCHARD_BIN" <domain> <command> ...`, not a hard-coded `orchard`, unless `command -v orchard` was the selected route.
• Check leaf-command help with `"$ORCHARD_BIN" <domain> <command> --help` or `"$ORCHARD_BIN" help <domain> <command>`; both print the same output.
• In zsh loops, never pass a multi-word command through a scalar like `"$ORCHARD_BIN" $cmd`; zsh keeps it as one argument. Use an array, or `eval` only for trusted static command strings.
• Negative numeric values must use the equals form: `--lng1=-122.4194`, `--lon=-117.1201`. With a space (`--lng1 -122.4194`) the parser reads the value as a new flag and fails with a usage error; shell quoting does not help because quotes never reach argv.
• `orchard mail read` supports `--date-from`/`--date-to` (ISO 8601) and `--offset` for time windows and pagination. If the installed CLI rejects these flags (older builds), fall back to `--limit` plus local `date_sent` filtering and state possible truncation when results hit the limit.
• Treat help output and the installed CLI as source of truth. If this skill and CLI disagree, run `"$ORCHARD_BIN" <domain> <command> --help` a