Orchard

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)

• 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 and adapt.

Core Rules

These describe the tools themselves, not either transport — they apply whether you're on the CLI or the MCP channel.

• Use ISO 8601 timestamps for all date ranges. Include timezone offsets when the user means local time, e.g. 2026-06-03T08:00:00+08:00.
• Convert relative dates before calling Orchard. "Yesterday 08:00" must become a concrete timestamp.
• Before creating calendar events or reminders, list calendars/lists and choose the right writable target. Do not dump everything into a default list/calendar unless the user explicitly asks.
• Before update/delete/mark/cancel operations, read the target and capture its ID.
• Treat destructive operations as real local mutations. For deletes, bulk updates, sending mail/messages, and scheduled sends, confirm intent unless the user explicitly requested the action.
• Before running an Apple Shortcut, list or open the matching shortcut first. Use shortcuts run only with --confirm and --reason (CLI) / confirm+reason (MCP), and confirm with the user unless they explicitly requested that exact run.
• Never print huge email bodies or private data unnecessarily. Fetch summaries first, then read full content only for messages that matter.

Common Workflows (CLI)

Daily Context

"$ORCHARD_BIN" clock time --timezone Asia/Shanghai --json
"$ORCHARD_BIN" weather get --location Jinan --granularity daily --start-date YYYY-MM-DD --end-date YYYY-MM-DD --json
"$ORCHARD_BIN" calendar info --type events --from YYYY-MM-DDT00:00:00+08:00 --to YYYY-MM-DDT00:00:00+08:00 --json
"$ORCHARD_BIN" reminder info --type reminders --status incomplete --json

When summarizing reminders, filter stale/completed/noisy records yourself if Orchard returns more than requested.

Mail Triage

"$ORCHARD_BIN" mail refresh --json
"$ORCHARD_BIN" mail read --type list --limit 100 --json
"$ORCHARD_BIN" mail read --type list --date-from 2026-07-01T00:00:00+08:00 --date-to 2026-07-15T00:00:00+08:00 --limit 100 --json
"$ORCHARD_BIN" mail read --type content --message-id MESSAGE_ID --json

Mail listing supports --limit, --mailbox, --account, --offset for pagination, and --date-from/--date-to (ISO 8601) for time windows. If the result count equals the limit, page with --offset or say the scan may be truncated instead of pretending coverage is complete. On older builds that reject the date/offset flags, fall back to --limit plus local date_sent filtering.

Only fetch full email bodies for likely important mail: accounts, billing, support, customer, legal, platform review, security, collaboration, or anything the user asked to inspect.

Calendar And Reminder Writes

"$ORCHARD_BIN" calendar info --type calendars --json
"$ORCHARD_BIN" calendar create --title "Call" --start 2026-06-03T15:00:00+08:00 --end 2026-06-03T15:30:00+08:00 --calendar-id CALENDAR_ID --alarms 15 --json

"$ORCHARD_BIN" reminder info --type lists --json
"$ORCHARD_BIN" reminder create --title "Follow up" --list-id LIST_ID --due-date 2026-06-03T18:00:00+08:00 --priority 5 --json

Priority is 0-9, but lower is more urgent: 0 = none, 1 = high, 5 = medium, 9 = low. Mark complete with:

"$ORCHARD_BIN" reminder update --reminder-id REMINDER_ID --completed true --json

Repeating events and reminders use the --repeat flag family (same rules as Calendar.app's Custom repeat sheet):

# Every 2 weeks on Mon and Fri, 10 occurrences
"$ORCHARD_BIN" calendar create --title "Standup" --start 2026-06-01T10:00:00+08:00 --end 2026-06-01T10:30:00+08:00 \
  --repeat weekly --repeat-interval 2 --repeat-days-of-week mon,fri --repeat-count 10 --json

# First Monday of each month, until a date (inclusive)
"$ORCHARD_BIN" calendar create --title "Review" --start 2026-06-01T14:00:00+08:00 --end 2026-06-01T15:00:00+08:00 \
  --repeat monthly --repeat-days-of-week mon --repeat-set-positions 1 --repeat-until 2027-06-30 --json

# Daily reminder — recurring reminders REQUIRE --due-date
"$ORCHARD_BIN" reminder create --title "Drink water" --due-date 2026-06-01T09:00:00+08:00 --repeat daily --json

--repeat is daily|weekly|monthly|yearly (on update, none removes recurrence). Companions: --repeat-interval N · --repeat-days-of-week mon,fri · --repeat-days-of-month 1,15,-1 (monthly; -1 = last day) · --repeat-months 1-12 / --repeat-weeks-of-year / --repeat-days-of-year (yearly) · --repeat-set-positions 1 or -1 (combine with another repeat field) · end with --repeat-until DATE or --repeat-count N (mutually exclusive).

All occurrences of a recurring event share one event id. calendar update/calendar delete take --occurrence-date DATE to target a specific occurrence (without it, the first occurrence is used) and --span this-event|future-events to control reach — delete defaults to this-event (only that occurrence); update defaults to this-event unless the repeat rule itself changes, which applies to future-events automatically.

Notes And Contacts

Search before creating duplicates:

"$ORCHARD_BIN" contacts search --query "Alice" --limit 10 --json
"$ORCHARD_BIN" notes search --query "project name" --limit 20 --json

Notes content is HTML for create/update. If the user gives Markdown, convert it to simple HTML first.

Messages

"$ORCHARD_BIN" messages read --type chats --query "search term" --limit 20 --json
"$ORCHARD_BIN" messages read --type messages --chat "+15551234567" --limit 50 --json
"$ORCHARD_BIN" messages send --to "+15551234567" --text "Text here" --service iMessage --json

Confirm before sending unless the user directly instructs sending exact text.

Shortcuts

"$ORCHARD_BIN" shortcuts list --summary --json
"$ORCHARD_BIN" shortcuts open --name "Shortcut name" --json
"$ORCHARD_BIN" shortcuts run --name "Shortcut name" --input "Text" --confirm --reason "User requested this exact shortcut run" --json

Prefer shortcuts list --summary before running. Use --input-path and --output-path for file handoff.

Troubleshooting (CLI)

• If a command asks for macOS privacy permissions, tell the user which app/service needs permission and retry after permission is granted.
• You normally never see Orchard.app is not running: CLI 0.6.2+ auto-launches the app on demand (open -b tech.5km.orchard, polls up to ~10s, retries once — both channels share this). If a command reports the app could not be started or did not become ready, or an older CLI still returns the plain "not running" error, start "$ORCHARD_APP_PATH" when it is non-empty (otherwise open -a Orchard), wait a few seconds, then retry once with the same ORCHARD_BIN. Set ORCHARD_NO_AUTOLAUNCH=1 only when a script needs a fast, definitive failure instead of the launch wait.
• For persistent or confusing failures, run "$ORCHARD_BIN" doctor — read-only diagnostics covering the socket, the CLI symlink, Skill installs, MCP config entries, and CLI/app version drift (exits 1 when something fails). "$ORCHARD_BIN" status --json reports login/Pro state, per-feature switches, and macOS permission status in one call; neither command launches the app.
• If a tool errors with "'X' is currently disabled", the switch can be flipped with "$ORCHARD_BIN" features enable <feature> — ask the user before changing their settings. Pro-tier features still require a Pro subscription; the server enforces this either way.
• If a command returns Invalid response from Orchard.app, treat it as an Orchard.app bridge/permission/runtime issue, not necessarily a CLI syntax issue. Retry once, then ask the user to check that Orchard.app is running and has the relevant macOS privacy permissions.
• If Apple Mail, Calendar, or Reminders data looks stale, run the relevant refresh/list command again and state the timestamp of the scan.
• If --json output contains a long HTML email body, summarize only the relevant parts; do not paste the entire body.
• If a flag is not accepted, trust "$ORCHARD_BIN" <domain> <command> --help for the installed version and adapt.

MCP Channel (No Bash — e.g. Claude Cowork)

If "Which Channel" routed you here (no Bash tool, or Bash is sandboxed away from this Mac while Orchard MCP tools are present): read references/mcp-tools.md now. It is self-contained — real tool names, required parameters, parameter-shape gotchas — because this channel has no --help to discover syntax from. Two things worth knowing before you start:

• Tool name prefix varies by host. Your tool list will show these tools as mcp__<something>__<tool_name> — e.g. mcp__orchard__calendar_info under a manual config, or mcp__plugin_orchard_orchard__calendar_info when Orchard ships as a plugin (Cowork's likely case). Never hardcode the middle segment: match on whatever ends in __<tool_name> against the names in references/mcp-tools.md.
• Results are content blocks, not the CLI's JSON envelope. {"output":...,"success":...} is a CLI-only wrapper. On MCP you get a content array plus a separate isError flag. When a tool emits a human-readable prefix followed by JSON, the two arrive as separate text blocks — the last block is clean, parseable JSON, so parse that one directly instead of stripping prose off the front. Plain-text results pass through as a single block unchanged.

Everything in Core Rules above still applies — it describes the tools, not the transport.