[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_124":125},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":-5,"_41":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":54,"_55":-5,"_56":48,"_57":58,"_59":60,"_61":-5,"_62":-5,"_63":-5,"_64":-5,"_65":66,"_67":68,"_69":70,"_71":72,"_73":74,"_75":-5,"_76":-5,"_77":-5,"_78":48,"_79":-5,"_80":81,"_82":83,"_84":85,"_86":87,"_88":89,"_90":91},"apiUrl","https://odel.app/api","creator","deverman","moduleId","focusrelaymcp","@deverman/focusrelaymcp","displayName","FocusRelay","tagline","Connect AI tools to OmniFocus on macOS to find, review, and safely update tasks and projects.","iconKey","https://avatars.githubusercontent.com/u/802318?v=4","category","local","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","pricingModel","free","creatorUserId","system:external-import","createdAt",1784175989000,"updatedAt",1788778833000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.deverman%2Ffocusrelay","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",45,"upstreamUpdatedAt",1786942433000,"detectedTransport","detectedAuthType","probeStatus","lastProbedAt","githubRepoUrl","https://github.com/deverman/FocusRelayMCP","githubRepoFullName","deverman/FocusRelayMCP","releaseId","ext-deverman-focusrelaymcp","version","0.10.0-beta","descriptionMarkdown","# FocusRelay — Fast Swift OmniFocus MCP Server and CLI for macOS\n\n## Plan your day and keep OmniFocus up to date with AI\n\nFocusRelay is a fast, native Swift MCP server and CLI that helps AI assistants\nread and safely update OmniFocus using documented OmniFocus APIs.\n\n[Install with Homebrew](#install-the-omnifocus-mcp-server-with-homebrew) ·\n[See what it can do](#ask-review-update) ·\n[Star FocusRelay](https://github.com/deverman/FocusRelayMCP) ·\n[Contribute](#help-shape-focusrelay)\n\n![Demo: Ask an AI assistant about your OmniFocus tasks](https://raw.githubusercontent.com/deverman/FocusRelayMCP/master/imgs/omnifocusaiquery.gif)\n\nAsk about the work already in OmniFocus, review the answer, and make approved\nchanges without clicking through long task lists.\n\n## Ask. Review. Update.\n\nFocusRelay is designed for targeted questions and compact answers, so the\nassistant does not need your entire OmniFocus database for routine requests.\n\nTry prompts like:\n\n- “Help me process my OmniFocus inbox in a small batch.”\n- “How many flagged items do I have?”\n- “Show me the first three available tasks in my inbox.”\n- “Find my task called [task name], flag it, and verify the change.”\n- “Set [task name] due tomorrow at 5 PM in my local timezone and verify the\n change.”\n\nIn clients that expose MCP server prompts, select `process_inbox`. In OpenCode,\nrun `/focusrelay:process_inbox` to start the guided workflow.\nCLI-based agents can retrieve the exact same instructions with\n`focusrelay workflow get process_inbox`; use `focusrelay workflow list` to\ndiscover available workflows without loading their full text.\n\nThese workflows were tested with multiple MCP-capable models in OpenCode.\nUpdates target stable OmniFocus IDs and can verify the saved result. If names\nare duplicated, ask to see the candidates before changing anything.\n\nThe current release can:\n\n- guide supported MCP clients and CLI-based agents through a bounded,\n approval-first inbox workflow;\n- find and count tasks using dates, flags, tags, projects, availability, inbox\n state, completion, estimates, and text search;\n- review projects, folders, tags, task counts, and stalled work;\n- update names, notes, flags, dates, estimates, tags, project settings, and\n review intervals;\n- mark active and on-hold projects reviewed using OmniFocus's native review\n timestamp and next-review semantics;\n- drop, restore, complete, reactivate, and move existing tasks;\n- complete, reactivate, change status, and move existing projects;\n- preview a proposed change and verify the saved result.\n\nThe current release updates existing tasks and projects. Creating or\ndeleting items is not supported; creation is tracked in\n[#82](https://github.com/deverman/FocusRelayMCP/issues/82) and\n[#83](https://github.com/deverman/FocusRelayMCP/issues/83).\n\n## Why FocusRelay?\n\n### Keep the assistant focused\n\nFocusRelay exposes nine model-facing tools: seven read tools plus `edit_tasks`\nand `edit_projects` for supported changes. Combining seven editing tools into\ntwo reduced the full catalog from 14 tools to 9 and cut context usage by\n7–13% in controlled model tests, leaving more room for the user's actual work.\nInternal diagnostics stay in the CLI, count commands avoid returning long item\nlists, and field selection keeps responses compact.\n\n### Native Swift speed at real-library scale\n\nFocusRelay is compiled as native Swift and installed with Homebrew, with no\nNode.js or Python runtime in the request path. Single-pass filtering and\nearly-stop pagination keep focused inbox reads near one second in testing at\nthousands-of-tasks scale. The same core powers a CLI for precise, low-context\nqueries.\n\n### Run where OmniFocus understands its data\n\nThe Swift server dispatches work to a lightweight bridge plug-in that runs\ninside OmniFocus’s Omni Automation context. It uses documented APIs and native\nstatuses, keeping results aligned with OmniFocus without reading its private\ndatabase.\n\n### Make changes you can check\n\nEdit tools target stable IDs and support previews, per-item results, compact\nreturn fields, and optional verification. A failed save, update, or verification\nis reported as a failure—not success.\n\nFocusRelay handles OmniFocus work in order, tells assistants to wait for each\nupdate, and reports overload clearly instead of letting requests collide.\nWhen an MCP client disconnects, its FocusRelay process exits cleanly rather\nthan remaining in the background.\n\nSee the [latest release notes](https://github.com/deverman/FocusRelayMCP/blob/master/docs/release-notes-v0.12.0-beta.md) for the\nuser-facing changes and upgrade requirements.\n\n## Privacy and security\n\nFocusRelay runs locally on your Mac. Its Swift server communicates on-device\nwith a bridge plug-in that accesses OmniFocus through documented APIs.\nFocusRelay has no hosted cloud service and does not send your OmniFocus data to\na FocusRelay-operated service.\n\nYour MCP client and chosen AI model may transmit tool inputs and results under\ntheir own privacy terms. Review those settings before using FocusRelay with\nsensitive data.\n\n## Install the OmniFocus MCP server with Homebrew\n\nRequirements:\n\n- macOS 26 or later on Apple silicon;\n- OmniFocus 4;\n- Homebrew;\n- an MCP-compatible assistant or a shell-capable AI agent.\n\n### 1. Install and trust the formula\n\nHomebrew 6 requires explicit trust for formulae from non-official taps. Trust\nonly the FocusRelay formula, then install it:\n\n```bash\nbrew tap deverman/focus-relay\nbrew trust --formula deverman/focus-relay/focusrelay\nbrew install focusrelay\n```\n\nFormula-specific trust authorizes FocusRelay without trusting every current or\nfuture formula in the tap. See Homebrew’s\n[Tap Trust documentation](https://docs.brew.sh/Tap-Trust) for details.\n\n### 2. Run guided setup\n\nRun the installed setup command:\n\n```bash\nfocusrelay setup\n```\n\nIt finds the Homebrew-bundled plug-in, verifies that its version matches the\nbinary, detects every supported OmniFocus plug-in folder, and previews the\nsource and destinations before asking permission to copy anything. Existing\nplug-ins remain in place until their replacement has been copied successfully.\nRerunning setup reports copies that are already current.\n\nSetup also prints the client-neutral MCP command and arguments. Add\n`--client claude-code`, `--client codex`, or `--client opencode` for a known\nclient example; FocusRelay prints the configuration but does not edit it.\n\nFor automation, review the same plan first and then opt in explicitly:\n\n```bash\nfocusrelay setup --dry-run\nfocusrelay setup --non-interactive\n```\n\nBuilding from source? Continue using `./scripts/install-plugin.sh`; it is a\nthin development entry point for this same Swift setup implementation.\n\n### 3. Restart OmniFocus\n\nQuit OmniFocus completely and reopen it so the updated plugin is loaded:\n\n```bash\nosascript -e 'tell application \"OmniFocus\" to quit'\nsleep 2\nopen -a \"OmniFocus\"\n```\n\n### 4. Check readiness and add FocusRelay to your AI assistant\n\nFocusRelay currently supports terminal-based MCP clients: Claude Code,\nOpenCode, Codex CLI, and other clients launched from a terminal. Desktop\napplications such as Claude Desktop and ChatGPT's desktop app are not yet\nsupported: macOS restricts their access to the OmniFocus data FocusRelay\nrelies on. Desktop-app support is tracked in\n[#196](https://github.com/deverman/FocusRelayMCP/issues/196).\n\nConfigure a local stdio MCP server with:\n\n- command: `/opt/homebrew/bin/focusrelay`\n- arguments: `serve`\n\n

Claude Code configuration

\n\nClaude Code registers MCP servers from the command line, so no file editing is\nrequired:\n\n```bash\nclaude mcp add --scope user focusrelay -- /opt/homebrew/bin/focusrelay serve\n```\n\n`--scope user` makes FocusRelay available in every project on your Mac. Use\n`--scope project` instead to share the server with collaborators through a\nchecked-in `.mcp.json`, or omit the flag to enable it only in the current\ndirectory.\n\nConfirm the server is registered and reachable:\n\n```bash\nclaude mcp list\n```\n\nFocusRelay should report `✔ Connected`. Remove it later with\n`claude mcp remove --scope user focusrelay`.\n\n

\n\n

OpenCode configuration example

\n\n```json\n{\n \"mcp\": {\n \"focusrelay\": {\n \"type\": \"local\",\n \"command\": [\"/opt/homebrew/bin/focusrelay\", \"serve\"],\n \"enabled\": true\n }\n }\n}\n```\n\n

\n\nOn the first query, OmniFocus asks whether to allow the automation. Choose\n**Run Script**. If the prompt is hidden, bring OmniFocus to the front.\n\nAfter restarting OmniFocus, verify that its loaded plug-in matches the binary:\n\n```bash\nfocusrelay setup --check-readiness\nfocusrelay list-tasks --fields id,name --limit 1\n```\n\nThen ask:\n\n> How many flagged items do I have in OmniFocus?\n\n

Manual download or source build

\n\nDownload the latest binary and `FocusRelayBridge.omnijs` from\n[GitHub Releases](https://github.com/deverman/FocusRelayMCP/releases), or build\non macOS 26 or later with the Swift 6.3.3 toolchain selected by the checked-in\n`.swift-version`:\n\n```bash\ngit clone https://github.com/deverman/FocusRelayMCP.git\ncd FocusRelayMCP\nswift build -c release\n./scripts/install-plugin.sh\n```\n\nAfter installing the plugin, restart OmniFocus completely and run\n`focusrelay setup --check-readiness`.\n\n

\n\n## Use FocusRelay as an OmniFocus MCP server or CLI\n\nMCP lets compatible assistants discover FocusRelay and choose the right action.\nThe CLI is useful for scripts, debugging, and agents that already have shell\naccess.\n\nThe examples below target the current Homebrew release and source build.\n\n```bash\n# Discover or retrieve the same workflows exposed as MCP prompts\nfocusrelay workflow list\nfocusrelay workflow get process_inbox\n\n# Count without returning every matching task\nfocusrelay task-counts --flagged true\n\n# Return only three task names\nfocusrelay list-tasks \\\n --inbox-only true \\\n --available-only true \\\n --limit 3 \\\n --fields name\n\n# Preview a change without touching OmniFocus\nfocusrelay edit-tasks \\\n --operation update \\\n --flagged true \\\n --preview-only \\\n --return-fields id,name,flagged\n```\n\nRun `focusrelay --help` for the command list. For write examples and safety\nrules, see [Safe Update Workflows for CLI and MCP](https://github.com/deverman/FocusRelayMCP/blob/master/docs/mutation-workflows.md).\n\n## Compare FocusRelay with other OmniFocus MCP servers\n\nFocusRelay combines a native Swift server with a bridge plug-in that executes\ninside OmniFocus. Swift keeps MCP fast and compact; the bridge gets fresh data\nand applies changes through documented OmniFocus APIs.\n\n✅ Available · 🟡 Coming next · 🟠 Backlog · ◇ Project roadmap · — Not currently documented\n\n| Capability | **FocusRelay** | [OmniFocus-MCP](https://github.com/themotionmachine/OmniFocus-MCP) | [Enhanced](https://github.com/jqlts1/omnifocus-mcp-enhanced) | [OmnifocusMCP](https://github.com/vitalyrodnenko/OmnifocusMCP) | [Operator](https://github.com/HelloThisIsFlo/omnifocus-operator) |\n| --- | --- | --- | --- | --- | --- |\n| Runtime | **Native Swift · Homebrew** | TypeScript · npx | TypeScript · npx | Native Rust · Homebrew; Python and TypeScript available | Python · uvx |\n| OmniFocus access | **Bridge plug-in inside Omni Automation; documented APIs** | JXA and Omni Automation through `osascript` | Omni Automation through `osascript` | Omni Automation through `osascript` | Internal SQLite read cache; OmniJS fallback |\n| Public MCP tools | **9, with seven read tools plus `edit_tasks` and `edit_projects`; 11 after planned creation tools [#82](https://github.com/deverman/FocusRelayMCP/issues/82) and [#83](https://github.com/deverman/FocusRelayMCP/issues/83)** | 12 | 18 | 45 | 11 |\n| Find, filter, and count tasks | ✅ | ✅ | ✅ | ✅ | ✅ |\n| Update existing tasks | ✅ | ✅ | ✅ | ✅ | ✅ |\n| Update existing projects | ✅ | ✅ | ✅ | ✅ | ◇ v1.5 roadmap |\n| Preview and post-save verification | ✅ Every write tool; per-target results | — | — | — | — |\n| Drop projects without deleting them | ✅ | ✅ | — | ✅ | — |\n| Create tasks and subtasks | 🟡 [#82](https://github.com/deverman/FocusRelayMCP/issues/82) | ✅ | ✅ | ✅ | ✅ |\n| Create projects | 🟡 [#83, including inbox-task conversion](https://github.com/deverman/FocusRelayMCP/issues/83) | ✅ | ✅ | ✅ | ◇ v1.5 roadmap |\n| Planned-date updates | 🟠 [#16](https://github.com/deverman/FocusRelayMCP/issues/16) | ✅ | ✅ | ✅ | — |\n| Repeating tasks | 🟠 [#93](https://github.com/deverman/FocusRelayMCP/issues/93) | ✅ | — | ✅ | ✅ |\n| Custom perspective contents | 🟠 [#10](https://github.com/deverman/FocusRelayMCP/issues/10) | ✅ | ✅ | — | — |\n| Permanently delete tasks and projects | — | ✅ | ✅ | ✅ | — |\n\nThis comparison reflects each project’s public documentation on July 15, 2026;\n“Not documented” is not a claim that a feature is impossible. The other public\nREADMEs do not describe an equivalent per-target preview and post-save\nverification contract.\n\nPreview resolves IDs and validates the change without saving it. Verification\nruns after OmniFocus saves, reads the affected values back, and reports a\nmismatch as a failure. These are MCP tool arguments, so Codex, Claude Code,\nOpenCode, and other standard stdio MCP clients can use them; whether a model\nchooses them without being asked depends on the model and client. For important\nchanges, ask it to “preview first, then apply with verification.”\n\n## Help shape FocusRelay\n\nSee [GitHub Issues](https://github.com/deverman/FocusRelayMCP/issues) for planned\nwork. If FocusRelay earns a place in your workflow,\n[star the repository](https://github.com/deverman/FocusRelayMCP) so more\nOmniFocus users can find it.\n\nWant to help? Pick an issue, propose a use case, or open a focused pull request.\nSee [CONTRIBUTING.md](https://github.com/deverman/FocusRelayMCP/blob/master/CONTRIBUTING.md) to get started.\n\n## Troubleshooting\n\n### The bridge times out\n\n1. Bring OmniFocus to the front and accept the first **Run Script** prompt.\n2. Confirm FocusRelay Bridge is enabled under **Automation → Configure\n Plug-ins…**.\n3. Run `focusrelay setup`, quit OmniFocus completely, and reopen it.\n4. Run `focusrelay setup --check-readiness`.\n\n### Results look stale after an upgrade\n\nThe plugin JavaScript is cached by OmniFocus. Run `focusrelay setup`, restart\nOmniFocus completely, and check with `focusrelay setup --check-readiness`.\nProject and tag catalogs cache for five minutes; task queries are always fresh.\n\n### The plugin and binary versions do not match\n\nUpgrading the Homebrew formula replaces the binary but leaves the copies of the\nplugin already installed for OmniFocus untouched, so a skipped step 2 can\nstrand the plugin many releases behind.\n\nRun guided setup again, restart OmniFocus, and check the loaded version:\n\n```bash\nfocusrelay setup\n# Fully restart OmniFocus\nfocusrelay setup --check-readiness\n```\n\nSetup checks that every expected copy—including the preferred iCloud location\nwhen plug-in sync is enabled—is available before changing files, and preserves\neach existing copy until its replacement has been copied and verified. It\nupdates destinations one at a time, so if a later destination fails, an earlier\none may already have been updated. Correct the reported problem and rerun setup\nbefore restarting OmniFocus. A healthy readiness result means the loaded\nplug-in, every installed copy, and the binary agree.\n\n### A time-based result looks wrong after travel\n\nRestart the MCP client and OmniFocus so FocusRelay picks up the current macOS\ntimezone.\n\n## Development\n\n```bash\nswift build\nswift test\n```\n\nFocusRelay uses Swift Testing from the Swift toolchain. Production query changes\nmust follow the documented\n[Omni Automation contract](https://github.com/deverman/FocusRelayMCP/blob/master/docs/omni-automation-contract.md).\n\n## License\n\nFocusRelay is available under the [MIT License](https://github.com/deverman/FocusRelayMCP/blob/master/LICENSE).\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_108":109,"_110":111,"_112":113,"_114":115,"_116":117,"_118":119},"requiredSecrets",[],"tags",[94,95,96,97,98,99,100,101,102,103,104,105,106,107],"assets",[],"stats",{"_92":81,"_93":81},"ratingAvg","reviewCount","ai","ai-agent","automation","claude","cli","homebrew","llm","macos","omni-automation","omnifocus","omnifocus-mcp","productivity","swift","task-management","topics",[94,95,96,97,98,99,100,101,120,121,122,123,102,103,104,105,106,107],"license","MIT","language","Swift","registryName","io.github.deverman/focusrelay","homepage","https://github.com/deverman/FocusRelayMCP#install-the-omnifocus-mcp-server-with-homebrew","packages",[],"mcp","mcp-server","model-context-protocol","modelcontextprotocol","ENV",{"_126":127,"_128":129,"_130":131},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]