Help

Short answers to the questions people ask first.

Getting started

Install

Drag AgentDesign to the Applications folder and open it from there. A copy opened straight from the disk image, or from a folder you cannot change, cannot update itself.

Make your first project

Choose New Project… in the File menu, then give it a name and the platforms it is for. Your agent fills it with designs.

Connect your agent

Open Settings, choose Agents, then Connect my agents, and say yes to the files it lists. Or choose Run Setup Again… in the Help menu for a guide with steps.

Review your first screen after you connect. The guide shows what to ask your agent and how to pin feedback.

To add AgentDesign to your agent by hand, use the lines for your agent below.

Claude Code

Run it in a terminal.

claude mcp add --scope user agentdesign -- "/Applications/AgentDesign.app/Contents/MacOS/agentdesign" mcp --root "<your designs folder>"

Restart Claude Code, then ask it: "List my AgentDesign projects."

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json, add it inside mcpServers.

{
  "mcpServers": {
    "agentdesign": {
      "args": [
        "mcp",
        "--root",
        "<your designs folder>"
      ],
      "command": "/Applications/AgentDesign.app/Contents/MacOS/agentdesign"
    }
  }
}

Quit and reopen Claude Desktop.

Codex

~/.codex/config.toml

[mcp_servers.agentdesign]
command = "/Applications/AgentDesign.app/Contents/MacOS/agentdesign"
args = ["mcp", "--root", "<your designs folder>"]

Restart Codex, then ask it: "List my AgentDesign projects."

Cursor

~/.cursor/mcp.json, add it inside mcpServers.

{
  "mcpServers": {
    "agentdesign": {
      "args": [
        "mcp",
        "--root",
        "<your designs folder>"
      ],
      "command": "/Applications/AgentDesign.app/Contents/MacOS/agentdesign"
    }
  }
}

Restart Cursor, then ask it: "List my AgentDesign projects."

Another client

your client's MCP settings, as a stdio server

"/Applications/AgentDesign.app/Contents/MacOS/agentdesign" mcp --root "<your designs folder>"

Restart the client, then ask it: "List my AgentDesign projects."

Connect over HTTP instead

Some tools want an address, not a command. Run the agentdesign program with serve where the lines above have mcp. It listens on 127.0.0.1, port 4817, so only this computer can reach it. Every request must carry the bearer token kept in the file http-token, inside the AgentDesign folder of Application Support, or in the file named by AGENTDESIGN_TOKEN_FILE.

Comments as they land

Run agentdesign watch in a terminal, or point Claude Code's Monitor at it, and it prints one line for every comment or reply written from now on. Add --project with a project id to watch one project. It writes nothing and reads no token, and it exits with 2 when --project names a project that does not exist.

Pass comments to Codex

To hand each line to a Codex session, pipe it to codex queue, naming the session by its id or its name: agentdesign watch | while read -r line; do codex queue --thread SESSION --message "$line" < /dev/null; done

More about how it fits together

The How it works page on the website explains the three parts and the setup in three steps.

How it works

Projects

A project is one app's designs: its screens, flows, components, notes and docs. The Project menu in the toolbar switches between them.

Screens

A screen is one picture of your app, made by your agent with the MCP tools. Every change is kept as a revision, so an earlier one can be opened and restored.

Flows

A flow lays screens out in columns, with arrows between them, to show how a person moves through the app.

Components

A component is a piece your agent reuses on many screens, such as a button or a card.

Notes and docs

Notes are short texts your agent leaves on a project. Docs are longer pages in Markdown: your agent writes them, and you can drop Markdown files in a project's docs folder.

Versions

A version is a release: the screens as they were when it went live. The version picker in the toolbar shows any of them.

Option boards

An option board holds several ideas for one question side by side, until one is picked.

Decisions

Decisions are what you and your agent settled in this project, and the questions still open. Your agent records one when you settle a rule or choose between options, and you can record one yourself. The Decisions page lists them. A decision you made can only be replaced or withdrawn by you.

House rules

House rules are rules your agent reads before it works on this project. Only you can change them: on the Decisions page, choose House rules, edit the text and choose Save. Every agent that connects to the project is shown them first.

Comments

You can comment on a screen. Your agent reads the open comments before it changes the screen, and marks each one addressed.

Captures

A capture is a picture of the real app, kept beside its design so the two can be compared. A capture manifest must keep its pictures in the manifest's own folder; a manifest that points outside it is refused.

The Obsidian mirror

A project can be mirrored into an Obsidian vault on your computer, as plain files. You turn it on in Settings, or an agent turns it on when it creates a project in an existing Obsidian vault you have.

Where your files are

Everything is plain files in your designs folder, by default projects inside the AgentDesign folder of Application Support. Choose another folder in Settings, General, under Designs folder.

Check a build without a screenshot

Your agent can compare a running build with a screen from a file your own UI test writes, so no screenshot is needed. It asks for capture_compare with a hierarchy_path. Each named part of the design is looked for in the build by its accessibility identifier (iOS) or test tag (Android), and the answer says what moved, what is the wrong size, what is missing and what is not on the screen. Color, type and images are not checked. The short test that writes the file, for iOS and for Android, is in schema_get under the topic captures. AgentDesign runs nothing on your devices for this.

Demo and license

The free demo

This is the free demo. It has every feature and holds one project and two versions, with every screen you make. A second project or a third version waits for a license.

Buy or renew

Open Settings, choose License, then Buy full version; or Renew for the new versions. What a license covers, and what it costs, is on the pricing page.

Activate your key

Open Settings, choose License, paste the key into License key, and choose Activate.

Find a lost key

Use Find my key on the website, with the email address and the receipt number from your purchase.

Move your license to another computer

On the old computer, open Settings, choose License, then Move this license to another computer. AgentDesign returns to the free demo on this computer. Nothing is deleted: your designs stay where they are.

Updates

How updates arrive

AgentDesign asks downloads.getagentdesign.com (Cloudflare) for the latest version 45 seconds after it starts, then once a day. The request carries no account, license or computer ID. Cloudflare sees your IP address and the app's user agent, as with any web request. Updates are signed, and install only when you quit or choose Restart now. To stop these checks, turn off Check for updates automatically.

Check now, or turn it off

Open Settings, choose About. There you can choose Check Now, or turn off Check for updates automatically.

When your updates have ended

The app tells you when a version is newer than your license covers. Open Settings, choose License, then Renew.

Troubleshooting

My agent cannot see AgentDesign's tools

Restart your agent first: the lines under Connect your agent say so for each one. Then check that what you added matches those lines. In Settings, Agents, choose Test Connection to check the AgentDesign side. Still stuck? Choose Run Setup Again… in the Help menu.

Over HTTP, every request is refused

A request with no bearer token, or the wrong one, is answered 401. Send the token kept in the file named under Connect over HTTP instead, as Authorization: Bearer <token>.

An HTML design will not draw

HTML designs are drawn with Google Chrome. When it is missing, the app says: Install Google Chrome to draw HTML designs. Install Chrome, then open the design again.

The app says my designs folder is busy

The message is: Your designs folder is busy. Try again in a moment.

A file is named as damaged

The app names the file and leaves it out. Restore the file from a backup or from git.

I have reached the demo's limit

The free demo holds one project and two versions, with every screen you make. Open Settings, License.

My key is refused

The app does not update

macOS will not open AgentDesign

Move AgentDesign to your Applications folder and open it from there. Your agent needs the app to stay in one place.

My agent says "Not connected"

Its connection to AgentDesign dropped partway through a session. Restart the agent first. If it cannot wait, tell it to run the same tool from a shell with agentdesign call, for example agentdesign call project_list. The rules are the same as over MCP.

I want to report a problem

Write to hello@getagentdesign.com. Your agents can also leave notes about the tools. Open Settings, choose Agents, find Notes from your agents, and choose Email to AgentDesign…. Opens a draft in your mail app. Nothing is sent until you send it. Read it first: it holds what your agents wrote.

Privacy in short

Your designs stay on your computer

Your designs are plain files in a folder on your computer. They never leave it through us.

What the app asks of the internet

The app has no account, no analytics, no telemetry and no crash reports that reach us. It contacts us only when you activate or move a license key, and to look for updates.

Your agents

An agent you connect may send what it reads to its own AI provider, under your agreement with that provider. Check its terms before you connect it to confidential designs.

The full policy

Read the privacy page for everything, with who we are and why.