Orbit stays private and iCloud-only unless you deliberately connect an AI client. A connection grants access to selected profiles and supported actions. These can include reading tasks and Spaces, creating and updating Spaces, reversible task changes, tag removal, and permanent Space removal that preserves the tasks. Disconnecting it stops that access.
What a connection can do
Depending on the Orbit version and the permissions granted to the connection, a client can:
- List your Spaces and search Orbit’s own Space-icon catalogue.
- List tags used by tasks in a permitted profile, including usage counts for open, completed and Deleted tasks.
- Create a Project or List with a suitable icon. Lists stay out of global views; Projects appear there by default unless you ask otherwise.
- Rename a Space, change its icon, or change whether a Project appears in global views.
- Browse or search every matching task page by page, including completed or Deleted tasks when you explicitly ask for them.
- Fetch a task’s full details, including its reminder and repeat settings.
- Create a task in the right Space with its schedule, deadline and reminder applied in the same request.
- Rename tasks and change their notes or tags.
- Schedule or unschedule tasks and set or clear independent deadlines and reminders.
- Move and reorder active tasks.
- Complete or reopen tasks.
- Move tasks to Deleted and restore them later.
- Remove selected tags, or all tags, from tasks in a permitted profile without deleting the tasks.
- Permanently remove a Space when Space-removal and task-movement access are granted. Every task is kept, including completed and Deleted history; tasks from that Space become unassigned.
These actions may run automatically after you connect the client. Orbit wakes in the background if needed and does not ask again before each supported change. Successfully applied task changes are added to Orbit’s normal Undo history for the current app session. Your AI client may show its own tool confirmation, depending on its settings.
There is no permanent task-deletion tool or general bulk task-editing tool. Tag removal is a specific operation that can affect many tasks. Removing a Space permanently is different from moving a task to Deleted: the Space itself is removed while its tasks and history are kept.
AI clients cannot convert a Project into a List or vice versa, reorder Spaces, administer profiles, change repeat rules, run arbitrary links or commands, or contact another service through Orbit.
Connect an AI client
- Open Orbit on your Mac.
- Choose Orbit ▸ Settings ▸ Privacy & AI.
- Choose Connect AI Client.
- Select the client. Orbit lists the ones it finds on this Mac first, and marks anything it cannot find. Under the list, Orbit tells you exactly what choosing Connect will do for that client.
- Review the actions and privacy disclosure. This is your connection-level consent for the listed actions. Read the Space-removal permission carefully: it permanently removes a Space while preserving its tasks.
- Choose Connect.
For Claude Desktop, Orbit then sets the client up for you. The first time, it asks you to grant access to Claude Desktop’s settings folder, because Orbit is sandboxed and cannot reach another app’s settings until you allow it. Choose Grant Access in the panel that appears, and Orbit adds itself to Claude Desktop’s MCP settings, leaves every other server you have connected exactly as it was, and tells you to restart it. Orbit does not ask again.
For every other client (Claude Code, ChatGPT & Codex, or anything you choose Other MCP client for), Orbit copies that client’s setup instead, and tells you where it goes. See below.
What the setup contains
The setup Orbit installs or copies names the connection. It does not contain the connection’s credential.
Orbit keeps that credential and hands it to the client itself, once. If a client asks for a credential Orbit has not already given it, after restoring a Mac for instance, Orbit asks you first:
Choose Allow only if you were setting that client up. Choosing Deny leaves the client with no access at all. A client cannot create or widen a connection, or access an unselected profile.
Still paste a setup only into the client you meant to connect. It names a live connection, and a client holding it can ask you to approve it.
Claude Desktop
Orbit adds itself to ~/Library/Application Support/Claude/claude_desktop_config.json, keeping any other MCP servers you have there. Quit and reopen Claude Desktop to finish.
The first setup asks for access to that folder, once. If you cancel, or choose a different folder, Orbit copies the setup instead so you can add it yourself; choose Manage ▸ Add to ▸ Claude Desktop to try again.
If Claude Desktop is installed but has never been opened, it has not created that file yet. Open it once, then return to Orbit and choose Manage ▸ Add to ▸ Claude Desktop.
If Orbit cannot write the file (usually because it has been hand-edited into something that is no longer valid JSON), Orbit leaves it completely alone, says so, and copies the setup for you to add yourself.
Claude Code
Orbit copies one complete setup command. Open Terminal, paste it and press Return. The correct text begins claude mcp add-json orbit. It registers Orbit at user scope, so the connection is available in every project; start a new Claude Code session to pick it up, as sessions already running keep the servers they started with.
Orbit does not write ~/.claude.json itself. That file also holds your Claude Code history, and Claude Code’s own command merges into it safely.
ChatGPT and Codex
ChatGPT for Mac and Codex share the same local MCP configuration. When you select ChatGPT & Codex in the connection steps above, Orbit copies one complete setup command; you do not need to assemble environment variables or JSON by hand. OpenAI documents the shared local MCP setup.
If the connection already exists, choose its Manage menu, then Copy setup for ▸ ChatGPT & Codex.
- Open Terminal, paste the entire copied command and press Return. The correct text begins
codex mcp add orbit --env. - Terminal should report
Added global MCP server 'orbit'. - Quit and reopen ChatGPT for Mac or Codex so it loads the new server.
You can run codex mcp list in Terminal to check that Orbit is listed as enabled. “Enabled” confirms only that the setup was saved; the read test below confirms that Orbit actually completed the connection.
If Terminal says an orbit server already exists, run codex mcp remove orbit, return to Orbit and copy the current connection’s complete setup again, then run the newly copied command.
Browser-only ChatGPT cannot launch Orbit’s local helper. Use ChatGPT for Mac or Codex on the same Mac as Orbit.
Test the connection
Start with a read-only request in a new ChatGPT or Codex conversation:
If that works, test one reversible change:
Confirm that the task appears in Orbit. Orbit should not ask you to choose Allow Once: connecting the client was the consent for its listed reversible actions. The AI client may still show its own tool confirmation, depending on its settings.
Bring Orbit to the front and press Command-Z to remove the test task through Orbit’s normal Undo history.
You can also test Space creation:
Confirm that the List appears in Orbit’s sidebar with the chosen icon, then remove it in Orbit. If that name already existed, Orbit returns and uses the unique name it actually saved.
Other MCP clients
Orbit copies a generic standard-input/output MCP server entry naming the signed helper and the connection. Add the entry to a desktop client that supports external local MCP servers, then approve the connection when Orbit asks.
Some sandboxed clients cannot launch an external helper with access to Orbit’s app group. Browser-only and remote AI services cannot use this local connection.
Existing view-only connections
Connections created by an older Orbit version may be view-only or may have an earlier subset of supported changes. They continue to work as before and are not silently given broader tools.
To give an older connection the current tools, open its Manage menu in Settings ▸ Privacy & AI and choose Allow Supported Changes…. You can instead disconnect it and use Connect AI Client to create a replacement. Review the upgrade disclosure carefully: after upgrading, the client may automatically use Orbit’s supported task and Space tools with the data it is permitted to access. The upgrade keeps the existing connection credential and setup command, so you do not need to configure the client again; refresh its tools if the new ones do not appear immediately. An older grant is not silently expanded to include permanent Space removal. There is no separate global write switch or per-action confirmation in Orbit.
How an AI change is applied
The helper never writes Orbit’s database. For every requested change, it sends a short-lived, authenticated request to Orbit. Orbit then:
- Rechecks the connection credential and its authorised task or Space scope.
- For an existing task or Space, confirms it is still the version the AI inspected, preventing stale overwrites.
- Confirms the request is a supported action authorised by the connection, including the separate permission needed to remove a Space.
- Applies the change through Orbit’s normal app-owned task or Space save path without another Orbit confirmation. Supported task changes enter the current app session’s Undo history.
Repeating tasks therefore produce their next occurrence correctly, iCloud receives a normal save, and widgets, notifications, Spotlight and the interface refresh as they would after a change made by hand. Orbit can wake in the background to do this without taking focus from the AI client. If Orbit stops responding while a change is in progress, the outcome may be uncertain because the action could already have completed. Inspect or refetch the affected task, or list Spaces after a Space request, before deciding whether to retry. The helper never falls back to a raw database write.
Required operation identifiers provide bounded replay safety. Orbit keeps the 512 most recent local results for up to seven days. While a result remains, retrying the identical action returns that result instead of applying the change twice. This is not permanent exactly-once delivery, so after an old or uncertain outcome the client should inspect the task before retrying.
Privacy and security
Each connection has its own random credential and data-access grant. Orbit stores the credential in the Mac’s Keychain, verifies it before every protocol message and lets you disconnect one client without affecting the others. A missing, invalid or revoked credential grants nothing.
The separately signed helper is sandboxed, has no network entitlement and opens Orbit’s task store with saving disabled. Task and Space text is marked as untrusted user data at the protocol boundary. Compatible clients should treat that text as information to discuss, never as instructions to execute.
The AI client may show a tool confirmation before it calls Orbit, but that depends on the client’s own settings. Orbit’s authoritative boundary is the revocable connection credential, authorised scope, supported tool contract and version checks.
Check, repair or disconnect
Return to Settings ▸ Privacy & AI to review connected clients. Each one shows the profiles it may use, what it may do and when it was last able to reach Orbit. The status changes from Not used yet after the client first connects successfully.
If a connection shows that a client points at a different copy of Orbit, that client was set up against Orbit in another location. The usual cause is moving Orbit after connecting. Choose Manage ▸ Repair Setup and Orbit rewrites that client’s entry to the current one. Restart the client afterwards.
Choose Manage ▸ Disconnect to invalidate a connection’s credential for reads and changes. Orbit also removes that connection’s entry from any client configuration it wrote, so the client stops offering a server it can no longer reach; restart the client to clear it. An entry belonging to a different, still-connected client is never touched.
If you use multiple profiles, select a connection to change which profiles it may use.
The helper rechecks access before every protocol message, and Orbit checks it again immediately before a change is committed. Resetting Orbit or erasing its data also revokes AI connections instead of carrying them into a fresh library.
Siri and Shortcuts are separate
Siri, Apple Intelligence and user-built Shortcuts use Apple’s App Intents rather than the local MCP helper. Their setting and system permissions are independent of connected desktop AI clients. See Siri, Shortcuts and widgets for details.
Troubleshooting
The helper says the connection is not authenticated
The client is naming a connection Orbit no longer holds (usually one that has been disconnected), or you chose Deny when Orbit asked whether to allow it.
Return to Orbit ▸ Settings ▸ Privacy & AI. If the connection is still listed, choose Manage ▸ Add to for that client, or copy its setup and replace the client’s existing orbit entry. If it is not listed, choose Connect AI Client to create a new one. Restart the client, and choose Allow if Orbit asks.
Orbit is enabled but the connection times out
“Enabled” means the client saved the configuration; it is not a connection health check. Update Orbit, open it and wait until your tasks are visible, then completely quit and reopen the AI client. Try the read-only test above again.
If the MCP handshake still times out, replace the client’s orbit entry with complete setup freshly copied from Orbit. A handshake timeout occurs before Orbit tools load, so it does not change a task. If it continues, copy Orbit’s full diagnostics and contact support with the exact error and AI client version, but never include the setup command or MCP configuration.
The client cannot launch Orbit
Moving or renaming Orbit changes the helper path a client was configured with. Open Settings ▸ Privacy & AI: Orbit flags any connection whose client points at a different copy of itself, and Manage ▸ Repair Setup rewrites it. For a client Orbit cannot write to, copy its setup again instead.
Confirm too that you are using a desktop client that supports external standard-input/output MCP servers.
Read tools work but change tools do not appear
This is normally an older, narrower connection. Upgrade it in Orbit if that action is available, or disconnect it and create a new normal connection. Restart or refresh the AI client after replacing its configuration.
The client says its credential is missing or invalid
Orbit hands a client its credential once, after you approve it. If that approval was denied, or the credential was cleared by a reset or a restore, the client has nothing to present.
Open Orbit and leave it running, then restart the client so it asks again, and choose Allow. If no prompt appears, the connection itself is gone: create a fresh one in Settings ▸ Privacy & AI and set the client up again. A disconnected connection cannot be revived.
Tag tools do not appear
Tag tools depend on the installed Orbit version and the connection’s read and update permissions. Update Orbit and refresh the AI client’s tool list. A tag-removal result can report partial progress if a task changed or could not be saved; inspect the result and list tags again before requesting another change.
Orbit says the task or Space changed
The AI was working from an older version. Ask it to fetch the task or list your Spaces again, review the new values and submit a fresh operation. Orbit does not silently overwrite a newer edit.
A task change times out
Open Orbit and retry with the same operation identifier promptly. If its replay record is still among the 512 most recent results and less than seven days old, Orbit returns that result instead of running the change twice. For an older or uncertain result, inspect the task before submitting another change.
I cannot find AI client connections on iPhone or iPad
Local AI clients are connected on Mac because they launch a Mac helper. Use Siri, Apple Intelligence or Shortcuts for native automation on iPhone and iPad.
I want to connect from a browser
Orbit’s AI client connection is local. Browser-only and remote services cannot launch it. Use a supported desktop app on the same Mac as Orbit.