Skip to content

Coding agents ​

The OpenPencil desktop app can use a coding agent you already have — Claude Code, Codex, Antigravity CLI, Gemini CLI, Cursor, Grok Build, or Pi — as its design agent. The agent runs on your computer with your own subscription, and you can leave the choice of model to it or pick one of the models it offers; OpenPencil starts it when you send a message, through the Agent Client Protocol or, for Pi, its Harness companion, and gives it the canvas tools through OpenPencil's local MCP server.

Coding agents need the desktop app; the browser cannot start programs on your computer. Each agent can take any role its capabilities allow, as Models and roles describes.

What you need ​

  1. The OpenPencil desktop app.

  2. The agent's ACP program, installed globally (see each agent below). Claude Code's and Codex's ACP programs include the agent, so their own command-line tools are optional.

  3. OpenPencil's MCP server, installed globally. Use the version that matches your app:

    sh
    npm install -g @open-pencil/mcp
  4. The agent signed in to your account. Pi can use an AI Gateway key instead (see Pi).

Then open Settings → Models → Run guided setup, choose the agent under Coding agents on this computer, and check that both the agent and the MCP server show as installed. Install adapter runs the npm command shown under it. Once the ACP program is installed, guided setup asks the agent which account it uses and shows what it reports, such as the plan and email; when it is not signed in, Sign in opens the agent's own login in your browser. For a signed-in agent, OpenPencil tools shows whether a session reaches OpenPencil's MCP server, checked the way a chat starts, without sending a message. Check again repeats the check after you install something or sign in elsewhere.

Let your agent set itself up ​

If you already use one of these agents in a terminal, guided setup can do the typing for you: press Copy setup prompt on the agent's card and paste the prompt into the agent. It asks the agent to install its ACP program and the MCP server, confirm both are on your PATH, and make sure you are signed in.

Models and roles ​

An agent is a model profile like any other (Settings → Models), so it can take the roles under Assignments that its capabilities allow: Design agent, Fast tasks, or Vision. An ACP agent on Fast tasks is started once to name each new conversation; Pi on Fast tasks names none, so conversations keep their first message as the title. Compaction summaries stay with the Design model, since a summary request carries the conversation itself. An ACP agent on Review writes the design reviews /review asks for, from a render when its profile has image input; it answers in one pass, without asking to see layers closer. A profile for an ACP agent can leave the choice of model to the agent (Agent default) or pick one of the models the agent offers. Opening the profile starts the agent once to read that list; every session the profile starts afterwards, from the chat or for another role, is put on the model you picked. When the list cannot be read, choose Custom model… and enter a model ID, or press Retry. A Pi profile names a Pi model such as provider/model, or leaves it empty for Pi's own default.

What a profile can do belongs to the profile, so two profiles of one agent can differ. Every agent profile has tools. Image input starts as the agent reports it; turn it off when the model you picked cannot read images. An agent that reports no image input cannot have it turned on. Only a profile with image input can take the Vision role. Pi's Harness companion takes its prompt as text alone, so Pi has no image input and cannot take Vision. An ACP agent that holds Vision analyses the images you attach and inspects a rendered design when the Design agent asks for a visual check: OpenPencil starts it once for each message with images or each inspection, hands it the images, and passes what it describes on to the Design agent. That agent runs without OpenPencil's tools, and OpenPencil refuses every permission request it makes; it is not sandboxed, so an agent set to edit files without asking still can. If it does not answer within a minute, OpenPencil stops it and reports an error instead of sending the message.

Claude Code ​

sh
npm install -g @agentclientprotocol/claude-agent-acp

Sign in from guided setup, or by running claude and using /login. The ACP program uses the same account as Claude Code. If the browser cannot hand the sign-in back, the sign-in page shows a code to paste into guided setup.

Codex ​

sh
npm install -g @agentclientprotocol/codex-acp

Sign in with ChatGPT from guided setup, or with codex login; both use the same account.

An older adapter from the @zed-industries/codex-acp package also installs a codex-acp program. It neither reports nor signs in to your account, so guided setup asks you to install the supported one and to remove the older one or put it later on your PATH.

Antigravity CLI ​

Antigravity CLI is Google's command-line agent for Gemini. It speaks ACP itself through agy acp, so there is no separate program. Install it from the Antigravity site:

sh
curl -fsSL https://antigravity.google/cli/install.sh | bash

On Windows, run this in PowerShell instead:

powershell
irm https://antigravity.google/cli/install.ps1 | iex

Run agy once and choose a sign-in method. Antigravity CLI does not report the account it uses, so guided setup shows it as installed without a plan or email.

Antigravity CLI loads MCP tools only up to a total size and holds the rest back, telling its model to call them through a call_mcp_tool tool it does not provide over ACP. For Antigravity chats, OpenPencil's MCP server leaves document_id and page_id out of its tool schemas so that every tool fits, and provides call_mcp_tool in case one does not. The agent works on the chat's document. The model sometimes asks to list its own MCP folder, ~/.gemini/antigravity-cli/mcp, before it starts; declining ends its turn.

Gemini CLI ​

Google no longer lets individual Google accounts sign in to Gemini CLI; use Antigravity CLI with those.

sh
npm install -g @google/gemini-cli

Gemini CLI speaks ACP itself, so there is no separate program. Run gemini once and choose a sign-in method.

Cursor ​

Cursor's CLI speaks ACP itself, so there is no separate program. Install it from the CLI installation guide:

sh
curl https://cursor.com/install -fsS | bash

On Windows, use the PowerShell command on that page. The installer adds two commands for the same program, agent and cursor-agent. OpenPencil starts cursor-agent, because other coding agents, such as Grok Build, install an agent command of their own.

Run cursor-agent login once to sign in.

Grok Build ​

Grok Build speaks ACP itself, so there is no separate program. Install it from the Grok Build guide:

sh
curl -fsSL https://x.ai/cli/install.sh | bash

On Windows, use the PowerShell command on that page. OpenPencil starts it as grok agent stdio. Run grok login once to sign in.

Pi ​

Pi runs through OpenPencil's Harness companion instead of ACP. It needs Node.js 22.15 or later, or Bun. Guided setup installs the companion with one click; to install it yourself, use the version that matches your app:

sh
npm install -g @open-pencil/harness

OpenPencil uses the providers you signed in to in Pi and Pi's default model, so there is no key to paste. Sign in by running pi and using /login, and pick a default model with /model. To use another model in OpenPencil, enter it as provider/model in the Pi model's settings. An AI Gateway key is optional; when you save one, Pi uses the gateway instead of your Pi sign-ins.

OpenPencil reads only Pi's settings.json for the default model; your credentials stay with Pi. Your Pi extensions, themes, and prompt templates are not loaded into OpenPencil's sessions. Pi keeps a conversation's context while it runs; after Pi or OpenPencil restarts, the conversation continues in a fresh Pi session, because Pi's workspace lives in memory.

Troubleshooting ​

  • Shown as not found after installing. Apps started from the Dock or Start menu do not see every folder your terminal adds to PATH. OpenPencil also looks in common global folders for npm, Bun, Volta, mise, and Homebrew; if your package manager installs elsewhere, add that folder to your login shell's PATH and restart OpenPencil.
  • Shown as update needed. The MCP server or Pi's companion does not match the app version. Press the update button, or run the command guided setup shows with the package manager that installed it, then press Check again. A chat that needs it says so and offers Run guided setup.
  • The agent couldn't reach OpenPencil's tools. Before sending your message, OpenPencil waits for the agent to connect to its MCP server and stops if it does not, quoting the agent's reason when it gives one. Check that the MCP server shows as installed in guided setup and is running in Settings → MCP. Codex skips OpenPencil's server when its own config.toml defines a server named open-pencil; remove that entry.
  • The agent starts but cannot edit the canvas. The MCP server is missing or not running. Install the matching @open-pencil/mcp version and restart OpenPencil.
  • Where the agent works. Chats start the agent in a folder of its own inside OpenPencil's app data, not your home folder, so it does not pick up project settings kept there. The agent still uses its own configuration, such as the MCP servers and rules in ~/.codex or ~/.claude.
  • The agent asks you to sign in. Press Sign in in guided setup, or sign in with the agent's own command-line tool as described above, then send your message again.