How to connect Apple Health to Gemini CLI

What do you get?

The Syncky extension gives Gemini CLI context and a local MCP registration for selected Apple Health data, including permitted 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 Gemini CLI locally on a machine you control, with Git, npm and Node.js 22.15 or newer available to its process. Git is required for GitHub extension installation by the official extension reference. The first npm run may download the agent. Package/repository availability is a prerequisite; this guide does not establish release availability.

Choose your data and model deliberately. Setup, receiver and MCP must use the same SYNCKY_AGENT_HOME and matching saved relay; the default home is ~/.syncky-agent. For a custom home, make its actual absolute path available in the environment launching Gemini CLI as well as setup and receiver. The agent setup guide explains relay selection for your app build.

How do you set up Gemini CLI?

  1. Check the local runtime, then 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. Create the private QR and code:

    npx -y @syncky/agent pair

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

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

  3. Choose receiving explicitly. For ongoing updates, 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 neither pairs nor starts a receiver; services and schedules require an explicit request.

  4. Review the Syncky extension and its context instructions, then run this command in your terminal, outside the interactive Gemini session:

    gemini extensions install https://github.com/syncky/syncky-open

    Review the installation confirmation rather than bypassing it. Gemini's extension documentation describes GitHub installation. The shipped manifest contains this context and server configuration; it is packaged with the extension, not a second manual configuration to paste:

    {"contextFileName":"SKILL.md","mcpServers":{"syncky":{"command":"npx","args":["-y","@syncky/agent","mcp"]}}}

    This registers npx -y @syncky/agent mcp. The extension reference defines contextFileName as context loaded from the extension directory and loads extension MCP servers on startup. Here SKILL.md is extension context. The MCP reference defines command and args for a local stdio process. A generic alternative for compatible clients is the matching release's checksum-verified syncky-health.mcpb; verify its .sha256 sidecar and SHA256SUMS before importing. Node.js is still required; checksums detect damage, not a compromised release. Local packaging tests do not establish client acceptance.

  5. Restart the Gemini CLI session after installation. Use /extensions list in the interactive session to check that syncky is installed. The official reference says extension management changes take effect after restart. Run the scope-only prompt below before asking for selected data.

What can Gemini CLI 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 registration does not disable syncky_send or syncky_ack. Review tool requests and do not configure automatic approval for syncky_send or syncky_ack; actual prompts depend on the client's policy.

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.

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). Written 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 Gemini CLI: 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 sharing/write scope. This reads local state without contacting Relay; it does not prove a fresh delivery or complete data.

How do you troubleshoot this setup?

What are the frequently asked questions?

Is SKILL.md a separate Gemini skill installation?

The Syncky manifest names it as extension context. Installing this extension loads those instructions and registers MCP; this guide does not install a separate Gemini skill.

Does installing the extension keep the inbox fresh?

No. A separate receiver on the same paired home collects updates; an MCP status check reads local state. Choose continuous receiving or on-demand collection deliberately.

Where does Gemini see the data?

The MCP server reads the agent's inbox files, and your chosen model sees what the agent supplies. Protect that storage and review Privacy and the public security policy.

Agent setup · MCP comparison · All guides · Hermes.

How do I approve writes and requests for access or reports?

This registration is not a read-only setup. Keep tool approval enabled and never auto-allow syncky_send or syncky_ack; approve only intended writes, sync report requests and access requests. For read-only work, disable or deselect syncky_send and syncky_ack using the client's supported tool controls; the model then cannot write to Health, request a report or more access, or mark inbox entries as handled. The registration itself disables neither. A report request sends a report only after Review and Confirm on the phone. An access request is queued, then the owner confirms individual read/write choices on the phone; the reply arrives in the inbox and the next ordinary sync delivers effective scope. Request approval is separate from permission to write Health values. See access request guidance.