Connect an agent

Potlot designs with agent CLIs you already use, signed in with your own account. Here is how it finds them, how to pick one, and how to connect an agent from your terminal.

Supported agents

Potlot runs these command-line agents. Install the one you use by following its own documentation, then sign in from a terminal with the command in the last column.

Open Settings › Agents to see which ones Potlot found. Each agent shows Connected or Not connected, and a missing one shows its sign-in command with a copy button. After you install or sign in, click Refresh.

Antigravity in headless mode rejects tools that need approval. On first use, Potlot adds a single mcp(potlot/*) rule to permissions.allow in ~/.gemini/antigravity-cli/settings.json. Shell commands and file writes stay denied.

How Potlot finds the CLI

For each agent, Potlot looks in this order:

1. 1A path you set in ~/.potlot/config.json (see below).
2. 2Your PATH.
3. 3The usual install folders: ~/.local/bin, /opt/homebrew/bin, /usr/local/bin, ~/.npm-global/bin, ~/.bun/bin and ~/.cargo/bin.

The folder list matters because an app opened from the Dock gets a short PATH, so a CLI your terminal finds may not be visible to Potlot.

If your CLI lives somewhere else, set its full path in ~/.potlot/config.json with claude_path, codex_path, cursor_path, antigravity_path or pi_path:

{
  "claude_path": "/path/to/claude"
}

Choose the agent and model

The model button sits at the bottom right of the composer. Click it to open a searchable list of models, grouped by agent. Agents Potlot cannot run show Not available with the reason. Models that cannot see screenshots are marked No images; an agent on such a model designs without looking at the canvas.

A new conversation starts with the model you used last. Follow-ups in a conversation stay with that conversation's agent; start a new conversation to switch.

Claude Code permissions

When Claude Code wants to use a tool that needs approval, a Permission request card appears in the conversation with Allow and Deny. File access inside the document's folder is allowed without asking.

With Claude Code selected, the model picker also shows Auto permissions: Claude approves its own tool calls instead of asking you. You can turn it on from a permission card with Switch to Auto, which allows that request and keeps auto mode for this and future conversations. Turn it off again from the model picker.

Potlot Agent (no CLI)

Potlot Agent is the built-in agent. It is still being tested, so it stays out of the agent list until you turn it on. It calls an OpenAI-compatible API with your own key. Set these values in ~/.potlot/config.json, then restart Potlot:

{
  "builtin_agent": true,
  "agent_base_url": "https://your-provider.example/v1",
  "agent_api_key": "your-key",
  "agent_model": "model-id"
}

Without agent_base_url and agent_api_key, Potlot Agent uses a provider you already configured in Pi: the first one with a key, unless agent_pi_provider names one. The key is read from Pi's config each time and never copied. One run stops after 40 model calls or 2 million tokens by default (agent_max_steps, agent_max_tokens).

Connect Claude Code or another MCP client

You can also drive Potlot from an agent in your own terminal. potlot mcp is a stdio MCP server. While the app is open it attaches to the app's daemon, so the agent edits the same document you see. With no daemon running, it runs on its own, headless.

For Claude Code, add this to ~/.claude.json:

{
  "mcpServers": {
    "potlot": {
      "type": "stdio",
      "command": "/path/to/potlot",
      "args": ["mcp"]
    }
  }
}

The desktop app ships this binary as potlot-daemon, next to the app's own executable. On macOS that is /Applications/Potlot.app/Contents/MacOS/potlot-daemon. Other MCP clients use the same command and mcp argument.

In Codex, allow Potlot's tools one by one, for example -c 'mcp_servers.potlot.tools.execute.approval_mode="approve"', and the same for read_skill, get_style and get_app_state.

Next, make your first design.

Something unclear, missing or broken? Write to feedback@anaknegeri.dev.