How do I give Codex, Gemini CLI, or Cursor hands on my Mac?

Waldo is not tied to one agent. He speaks MCP, the open standard agents use to pick up tools. If your agent speaks it too, it can borrow his hands.

What is the one setting every agent needs?

Every MCP agent takes the same server: the command waldo with the argument mcp. In the common JSON form:

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

Install and grant first. You need macOS, Rust and the Xcode command line tools.

git clone https://github.com/justusewaldo/waldo
cd waldo && make install && waldo grant

The full steps are in the install section. Then add Waldo to your agent, as below.

How do I add Waldo to Codex?

Codex keeps its MCP servers in ~/.codex/config.toml, one [mcp_servers.<name>] table each, as OpenAI’s Codex MCP docs describe. Add this:

[mcp_servers.waldo]
command = "waldo"
args = ["mcp"]

Or add it from the command line:

codex mcp add waldo -- waldo mcp

How do I add Waldo to Gemini CLI?

Gemini CLI reads mcpServers from its settings.json: ~/.gemini/settings.json for your user, or .gemini/settings.json in one project, per the Gemini CLI MCP docs. Add this:

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

Or add it from the command line. Gemini CLI adds servers to the project by default, so ask for your user:

gemini mcp add --scope user waldo waldo mcp

How do I add Waldo to Cursor?

Cursor reads ~/.cursor/mcp.json for every project, or .cursor/mcp.json in one project, per Cursor’s MCP docs. Cursor’s format names the type of a local server:

{
  "mcpServers": {
    "waldo": { "type": "stdio", "command": "waldo", "args": ["mcp"] }
  }
}

Why does macOS ask for permission again?

macOS asks permission for whichever app starts Waldo. For most people that is the terminal, and waldo grant covers it. An agent that runs inside an editor starts Waldo from that editor, so macOS asks again, for that app.

Grant it in System Settings, under Privacy & Security: Accessibility, and Screen & System Audio Recording.

A missing Screen Recording grant is silent. see returns a black screenshot and no window names, without saying why. The control list still works. If your agent reports a black screen, this is the first thing to check.

Does Waldo behave the same with every agent?

Yes. The rules live in Waldo, not in the agent:

• The hard stops. Four kinds of act always stop and ask you first: money, sending as you, passwords, and destructive changes. The agent cannot give its own yes. Read how the hard stops work.
• The panic corner. Shove your pointer into the top-left corner of the screen. Every tool, for every agent, stops until you say go.
• The record. Every tool call and every gate answer is one line in a local log. waldo log prints the last lines.
• Any model. Claude, GPT, Gemini, DeepSeek, Grok, Qwen, Llama, Mistral, or your own. Waldo is the hands. Your agent and its model do the thinking.

Your agent’s own rules still apply on top. Some agents ask before each tool call until you allow them.

What should I ask first?

Start your agent and ask in plain words:

Open System Settings and tell me which apps can record the screen.

Waldo works behind you. A press goes straight to the control. The app does not come to the front and your pointer does not move. You keep working while it works.

Using Claude Code? make register does the setup for you. See Claude Code on your Mac. For what the tools can do, see Waldo’s MCP server. The code is on GitHub.

Sources

• Model Context Protocol in Codex, OpenAI
• Gemini CLI documentation on MCP servers, Google
• Model Context Protocol (MCP), Cursor