How to connect Apple Health to Codex CLI and IDE

What do you get?

Codex CLI and IDE extension can read selected Apple Health data from your local Syncky agent. The default configuration disables the two tools that change things in the client; deliberate opt-in permits write-back with source and undo. Free during launch; plans are coming later. See launch access and pricing.

Client health-data envelopes are sealed end to end. Relay sees delivery metadata and plaintext hub notices, but no health values. The local agent keeps plaintext JSON in its inbox; your chosen model sees what the agent supplies. iOS decides background timing and Health reads need an unlocked iPhone. Data can be hours old and writes wait for sync; undelivered envelopes leave Relay on acknowledgment or expiry, at most 7 days.

What do you need before setup?

Use Codex CLI or its IDE extension locally on the machine holding your paired agent home, Syncky Health on your iPhone, npm and Node.js 22.15 or newer available to the client process. The first npm run may download the agent. Choose your data and model deliberately. Package availability and acceptance by your installed client remain prerequisites.

These instructions use the dated shared configuration as of November 2026 and the operator guide, without fresh client verification. ChatGPT desktop, Codex CLI and IDE extension share ~/.codex/config.toml in your home folder. On Windows this is .codex\config.toml inside your user home, for example C:\Users\you\.codex\config.toml. ChatGPT desktop works locally; ChatGPT web and mobile cannot reach a local agent.

Setup, receiver and MCP must use the same SYNCKY_AGENT_HOME and matching saved relay. The default agent home is ~/.syncky-agent; agent setup explains relay selection. This guide assumes local execution with access to that home.

How do you set up Codex?

1. Check the runtime and initialize only a fresh home:

   npx -y @syncky/agent selftest
   npx -y @syncky/agent init --name "My agent"
   

   Reuse an existing initialized home instead of initializing again.

2. Request a private QR and code:

   npx -y @syncky/agent pair
   

   Pair your iPhone: scan in Syncky Health and pick the code on the iPhone. Scanning alone does not confirm trust. Choose read types, allowed write types and Health permissions deliberately. Keep pairing credentials, invites and home files out of chat and logs. Let an existing receiver collect the proof; otherwise wait for it after the code pick:

   npx -y @syncky/agent wait --timeout 600
   

3. For ongoing receipt, deliberately start:

   npx -y @syncky/agent receive
   

   Keep one receiver per home and reuse an existing receiver. For on-demand use, run npx -y @syncky/agent receive --once when you want updates. MCP reads the agent's inbox files and neither pairs nor starts a receiver. Services and schedules require a separate choice.

4. Merge this default block into the shared home-folder configuration. Preserve unrelated configuration and update an existing syncky block instead of adding a duplicate:

   [mcp_servers.syncky]
   command = "npx"
   args = ["-y", "@syncky/agent", "mcp"]
   disabled_tools = ["syncky_send", "syncky_ack"]
   

   Alternatively, register with the CLI first:

   codex mcp add syncky -- npx -y @syncky/agent mcp
   

   CLI registration cannot set disabled_tools: afterwards add both disabled tools shown in the default TOML to the matching server block before using tools. Register once; the CLI form is an alternative to manual registration, not an additional server.

5. For a custom paired home, the separate TOML environment table is:

   [mcp_servers.syncky.env]
   SYNCKY_AGENT_HOME = "/home/you/.syncky-agent"
   

   Replace it with the actual absolute path used by setup and the receiver. Literal TOML paths do not expand $HOME or ~. On Windows a single-quoted TOML literal string such as 'C:\Users\you\.syncky-agent' preserves backslashes. Normally the relay is saved in that home; if setup deliberately used SYNCKY_RELAY_URL, pass the same override in this table too.

6. Save and restart the client after the final edit, then run the scope-only prompt below. The canonical npm server is npx -y @syncky/agent mcp. A generic alternative for compatible clients is the matching release's checksum-verified syncky-health.mcpb; verify its .sha256 sidecar and SHA256SUMS from releases before importing. Node.js is still required. Checksums detect damage, not a compromised release; local packaging tests do not establish client acceptance.

What can Codex read and write?

The MCP server offers five tools. syncky_status shows pairing, scope and relay progress from local state. syncky_inbox returns what the iPhone sent, as raw JSON kept 30 days on your computer. syncky_skill returns the signed instructions that describe every message format. syncky_send sends a message to the iPhone: a Health write, applied at the next sync when the owner has allowed writing for that type and iOS Health permits it, or a sync report or access request, which the owner approves on the phone. syncky_ack marks inbox entries as handled. Status, inbox and skill only read; send and ack change things. An empty result is not a measured zero.

This is a read-only setup: the default TOML disables syncky_send and syncky_ack in the client, without changing the stdio server's default. The model can then read status, the inbox and the skill, but cannot write to Health, request a report or more access, or mark inbox entries as handled; you acknowledge entries from the CLI instead.

The agent keeps what the iPhone sent as daily JSON files in its home (inbox/), prunes them after 30 days, and keeps the last 100 send receipts. There is no database and no built-in summaries: your AI agent reads the files it needs.

Every write to Apple Health, every sync report request and every request for more Health types is a message the agent sends to the iPhone. Writes apply only to the types the owner allowed for writing in the app; a sync report or more Health types need the owner's tap on the phone. The signed skill (syncky_skill) carries the exact formats and limits. A report arrives only after you Review and Confirm on the iPhone; you can decline instead. The phone permits at most one sync report per rolling 24 hours per agent pairing, and a request expires after 24 hours.

To opt in deliberately, remove syncky_send (and, if you want the model to acknowledge entries, syncky_ack) from disabled_tools, save and restart. Write only owner-requested entries or entries covered by explicit standing approval. A write is applied only when its type is in the app's write allowance, within the agent's write scope, and authorized by HealthKit (iOS write permission). Entries identify the requesting agent as their source. A queued or sent write is not an applied write: read the phone's result in the inbox after the next sync. To undo, use the iPhone's remove-written-entries control or have the agent send a delete command for its own entry. Follow the operator security rules.

How do you test the connection?

Ask Codex: Use syncky_status to check the paired iPhone and its read/write scope. Do not read sample values or write anything. Expect a confirmed iPhone and its last reported scope. This reads local state without contacting Relay; it does not establish fresh delivery or complete data.

How do you troubleshoot this setup?

• MCP startup fails: make Node.js and npm available to the client process and run setup's selftest. If the first npm download exceeds the default 10-second startup timeout, set startup_timeout_sec to 60 in the server block and restart.
• Send and ack remain available: CLI registration alone does not disable them. Check the matching shared TOML block, both disabled tools and final client restart before use.
• Wrong or empty inbox: match the paired home and saved relay used by setup, receiver and MCP. Do not initialize over existing state or assume another execution environment sees local files.
• Phone unconfirmed or data old: pick the phone's code and receive its proof. Check the receiver, selected categories, unlocked iPhone and Health permissions, then use Sync now. iOS decides later background timing.

What are the frequently asked questions?

Does the IDE extension need a second Syncky registration?

The dated operator guide uses the shared home-folder configuration for Codex CLI, IDE extension and ChatGPT desktop. Preserve existing blocks and register the local server once.

Does the registration command make access read-only?

No. Add both disabled tools to the matching TOML block afterwards and before using tools. The default block above includes them.

Does MCP keep the inbox fresh?

No. A separate receiver on the same paired home collects updates. Protect that storage and review Privacy and the public security policy.

Agent setup · MCP comparison · All guides · ChatGPT desktop.

How can an agent ask for more Health access?

Only with your explicit approval: the agent sends an access request with syncky_send, naming the read and write types it needs and an optional plain-text reason. In this read-only setup, enable syncky_send first or send it from the CLI. A queued request grants nothing. The owner reviews each type on the phone and taps Allow or Decline; the reply arrives in the inbox and the next ordinary sync confirms the new scope. Asking for access is separate from permission to write Health values. The phone keeps one pending request per agent, admits one per rolling 24 hours, lets a request expire after 24 hours and waits seven days before a declined type can be asked again.