Ask an agent. Apply it yourself.

Copy one sentence from TidyGrid, paste it into Claude Code, Codex or Cursor, and ask in plain words: “arrange my home screen by color”, “put all games in one folder”. Nothing to install. The agent changes the draft you see in TidyGrid. It cannot write to your device.

Paste one sentence

Open AI agents in TidyGrid's sidebar, pick an example or type what you want, and press Copy. Then paste the sentence into a coding agent that can run commands on your Mac. It looks like this:

Claude Code, Codex or Cursor

Paste into the agent.
Use TidyGrid on my Mac to arrange my home screen by icon color. First run "/Applications/TidyGrid.app/Contents/MacOS/tidygrid-mcp" guide in the terminal and follow it.

The path assumes TidyGrid is in your Applications folder; the Copy button in TidyGrid gives the exact path on your Mac. The agent runs tidygrid-mcp guide, reads what it prints, and works from there. Codex runs commands in a sandbox that blocks the connection to TidyGrid, so the first time it asks you to approve running the command outside the sandbox. The commands only talk to the TidyGrid app on your Mac.

Or add it as an MCP server

For agents that cannot run commands, such as the Claude desktop app, or if you would rather set it up once for good. TidyGrid shows these lines under the same panel, with a Copy button.

Claude Code

Run this in Terminal.
claude mcp add tidygrid -- "/Applications/TidyGrid.app/Contents/MacOS/tidygrid-mcp"

Codex

Run this in Terminal.
codex mcp add tidygrid -- "/Applications/TidyGrid.app/Contents/MacOS/tidygrid-mcp"

Cursor

Add this to ~/.cursor/mcp.json.
{
  "mcpServers": {
    "tidygrid": { "command": "/Applications/TidyGrid.app/Contents/MacOS/tidygrid-mcp" }
  }
}

Claude desktop app

Settings, Developer, Edit Config, then add this.
{
  "mcpServers": {
    "tidygrid": { "command": "/Applications/TidyGrid.app/Contents/MacOS/tidygrid-mcp" }
  }
}

How it works

  1. Open TidyGrid and connect your iPhone or iPad, or open the built-in sample phone to try it. Agent access is on unless you turned it off.
  2. Paste the sentence, or ask an agent that has the MCP server. It reads the layout and, for colour, the main colour of each icon.
  3. The agent checks a complete new layout and proposes it. It appears in the TidyGrid window as a draft, one step you can undo.
  4. Look it over, change anything you like, and press Apply yourself. TidyGrid backs up the current layout before it writes.

If TidyGrid is closed or agent access is off, the commands and tools answer with a message asking you to open TidyGrid.

The five tools

get_layout
Reads the current draft: the device and its grid, the Dock, every page with folders and widgets, the Shelf, the apps that are only in the App Library, and anything that would block applying.
get_icons
Returns the main colour of each app icon (hue, saturation, brightness), for arranging by colour. It sends no images.
evaluate_layout
Checks a complete layout without changing anything: unknown or repeated apps, pages or a Dock that are too full, and what would be left out.
propose_layout
Replaces the draft in the TidyGrid window with a new layout. Anything left out goes to the Shelf and has to be placed before you can apply. You can undo it like any other change.
list_backups
Lists the layout backups saved for the connected device. Restoring one is done by you in the app.

The same tools as commands, which is what the pasted sentence uses. Output is JSON.

tidygrid-mcp guide
Prints everything the agent needs: the commands, the steps and the layout format.
tidygrid-mcp layout
Same as get_layout.
tidygrid-mcp icons
Same as get_icons.
tidygrid-mcp check FILE
Same as evaluate_layout, for a layout saved as a JSON file.
tidygrid-mcp propose FILE
Same as propose_layout.
tidygrid-mcp backups
Same as list_backups.

What an agent cannot do

  • Write to your iPhone or iPad. There is no tool for it. Applying is a button in the TidyGrid window.
  • Install, delete or rename apps, or change icons. It can only move what is already on the device.
  • Add widgets or change their settings. Widgets have to stay on pages.
  • Reach your device or TidyGrid from another computer. The commands and the MCP server talk to the app over a private local connection on your Mac.

A plain-text version of this page for agents: /llms.txt