Using it with your AI agent

You never have to open Jiggle Mode yourself. Connect your agent once, then ask it things like "What's on my iPhone's Home Screen?" or "Put my travel apps in a folder on page 2." Your agent starts Jiggle Mode in the background whenever it needs it.

Two pieces, both inside Jiggle Mode:

1. The MCP server (jigglemode mcp): the tools your agent uses to see your phone, plan changes, draw a preview and, only if you allow it, write them. MCP is the common way to connect tools to AI agents.
2. The skill: instructions that teach your agent the safe way to work and good habits for organizing a Home Screen.

You need the jigglemode command for setup: with Homebrew you already have it; with the disk image, choose Install Command Line Tool… from the Jiggle Mode menu (see Get started). The exception is Claude Desktop, whose extension carries its own copy. Set Up for AI Agents… in the Jiggle Mode menu brings you to this page.

#Read-only, or allowed to make changes

Every setup below comes in two versions:

• Read-only (jigglemode mcp): the agent can look, suggest and show you previews, but can't change your phone. Start here.
• Can make changes (jigglemode mcp --allow-apply): the agent may also write changes, but only with your own yes for each one.

Even with changes allowed, nothing changes on your phone until you say yes yourself, twice:

1. The agent is told to show you the list of changes and ask you in the conversation.
2. Then Jiggle Mode itself asks you to confirm those exact changes: in your agent app, if it can show such a question, otherwise in a Jiggle Mode window on your Mac. In that window Cancel is the default, and no answer within 60 seconds counts as Cancel. If neither can be shown, nothing is written. Your agent can't answer for you.

Every write is also backed up, read back from the phone and put back automatically if it didn't land, exactly as in the editor.

To switch later, remove the server and add it again with the other line. For the config files below, add or delete "--allow-apply". Your agent is told never to turn writing on by itself. The editor and the jigglemode command aren't affected by this setting: they can always write, and they ask you first.

#Claude Code

Read-only:

claude mcp add --transport stdio --scope user jigglemode -- jigglemode mcp

Can make changes:

claude mcp add --transport stdio --scope user jigglemode -- jigglemode mcp --allow-apply

To switch, first run claude mcp remove --scope user jigglemode, then add it again. Claude Code may also ask its own permission before the agent uses a tool.

#Claude Desktop

Download the Claude Desktop extension (jigglemode-1.0.0-rc.1.mcpb) from the download page and double-click it. Claude Desktop shows what it installs and asks you to confirm. It starts read-only.

To allow changes: in Claude Desktop's settings, open the Jiggle Mode extension and turn on Allow writing to the phone. Turn it off again to go back to read-only.

Without the extension, you can add Jiggle Mode to Claude Desktop's config file instead (Claude menu, Settings, Developer, Edit Config), then restart Claude Desktop. Don't use both, or Jiggle Mode appears twice. Use the full path to jigglemode here:

{
  "mcpServers": {
    "jigglemode": { "command": "/opt/homebrew/bin/jigglemode", "args": ["mcp"] }
  }
}

Add "--allow-apply" after "mcp" to allow changes.

#Codex (CLI, IDE extension, ChatGPT desktop app)

Read-only:

codex mcp add jigglemode -- jigglemode mcp

Can make changes:

codex mcp add jigglemode -- jigglemode mcp --allow-apply

Or in ~/.codex/config.toml (shown with changes allowed; drop "--allow-apply" for read-only):

[mcp_servers.jigglemode]
command = "jigglemode"
args = ["mcp", "--allow-apply"]
tool_timeout_sec = 180

tool_timeout_sec gives you time to confirm (up to 60 seconds) plus the write itself (about a minute at most). If a call times out before you confirmed, nothing is written; if it times out during the write, the write still finishes and the agent can ask for the result. To switch: codex mcp remove jigglemode, then add it again.

#Gemini CLI

gemini mcp add --scope user jigglemode jigglemode mcp

Append --allow-apply to allow changes. Or in ~/.gemini/settings.json:

{
  "mcpServers": {
    "jigglemode": { "command": "jigglemode", "args": ["mcp"] }
  }
}

Leave Gemini's trust setting off, so Gemini also confirms tool calls.

#Cursor

In ~/.cursor/mcp.json:

{
  "mcpServers": {
    "jigglemode": { "command": "jigglemode", "args": ["mcp"] }
  }
}

Add "--allow-apply" after "mcp" to allow changes.

#VS Code (GitHub Copilot)

code --add-mcp '{"name":"jigglemode","type":"stdio","command":"jigglemode","args":["mcp"]}'

For one workspace only, use .vscode/mcp.json:

{
  "servers": {
    "jigglemode": { "type": "stdio", "command": "jigglemode", "args": ["mcp"] }
  }
}

Add "--allow-apply" after "mcp" to allow changes.

#Any other agent

Jiggle Mode is a local MCP server that talks over standard input and output: command jigglemode, arguments mcp (plus --allow-apply to allow changes, or set the environment variable JIGGLEMODE_ALLOW_APPLY=1). It speaks MCP 2026-07-28 and the older 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 versions. Agent apps that support MCP elicitation show Jiggle Mode's confirmation question themselves; for the rest, Jiggle Mode shows its own window on your Mac.

#If your agent can't start Jiggle Mode

Apps you open from the Dock or Finder don't always find programs the way Terminal does. Use the full path that which jigglemode prints instead of jigglemode (with Homebrew, usually /opt/homebrew/bin/jigglemode on Apple silicon and /usr/local/bin/jigglemode on Intel).

#Install the skill

jigglemode skill install

This copies the skill to ~/.claude/skills/jigglemode (Claude Code) and ~/.agents/skills/jigglemode (Codex, Gemini CLI, Cursor, GitHub Copilot and other agents that read that shared folder). For one project only: jigglemode skill install --dir .agents/skills. It never overwrites a copy you edited unless you add --force. jigglemode skill path shows what is installed and whether it is current.

For claude.ai, install a copy into a folder of your choice, zip the jigglemode folder inside it, and upload the zip in claude.ai's settings:

jigglemode skill install --dir ~/Desktop/skills && cd ~/Desktop/skills && zip -r jigglemode.zip jigglemode

#Check it works

Ask your agent: "Which iPhones can you see, and what's on my Home Screen?" It should list your phone and describe your pages. If your phone doesn't trust your Mac yet, the agent asks it to; you tap Trust on the phone and enter your passcode.

Then: "Suggest a tidier first page." It should show you the changes and wait for your yes. With the read-only setup, it tells you that writing is off and how to turn it on.

Try everything on a pretend iPhone first by using jigglemode --demo mcp --allow-apply as the command. Every result says DEMO, and nothing real is changed.

#What your agent can and can't do

It can move apps, folders and widgets; make, rename and remove folders; add, remove and reorder pages; fill the Dock; send apps to the App Library and bring them back; and put back any backup Jiggle Mode made.

It can't add widgets, remove web clips, see hidden pages or gaps between icons, install or delete apps, change a locked phone, or know which apps you use most (tell it).

#Unattended agents

For an agent that runs with nobody watching, jigglemode mcp --allow-apply-without-confirmation lets it change your phone without asking you. Use it only for an agent you fully trust, at your own risk: a mistaken or misled agent could rearrange your Home Screen without you seeing it first. Every change is still checked, backed up, read back and put back if it didn't land, and you can undo it from the backups. It can only be turned on with this flag, never with the environment variable.

#Privacy with agents

Your agent sees your Home Screen: app names, folder names and their places. It may send them to the AI service it runs on, like anything else you share with it. Jiggle Mode itself sends nothing anywhere. App and folder names are treated as data: the skill tells your agent to ignore any instructions that appear inside them.

#The tools

The full list of MCP tools, and which ones can change your phone, is in the Command line reference.