Workflow

How to add design review to Codex

Save your API key once, then install the TheDesignAgent plugin from its marketplace, or add the MCP server to config.toml. Codex then gets a design brief before it builds a screen and a scored UX and visual review after.

To add design review to Codex, save your TheDesignAgent API key once, then install the plugin with two commands. Codex gets a design agent in its loop: Discover for a brief before it builds a screen, Ux and Visual for a scored review after, and a project memory shared by every agent on the repo.

Before you start

1. Save your key

Codex has no standard way for a plugin to ask for a key, so save it once on your machine:

npx -y --package=@thedesignagent/mcp thedesignagent login

It goes to ~/.thedesignagent/credentials, readable only by you. Every client and the thedesignagent CLI use it, and the THEDESIGNAGENT_API_KEY environment variable still wins when it's set.

2. Install the plugin

codex plugin marketplace add CMBurnett/the-design-agent-plugin
codex plugin add tda@thedesignagent

The plugin brings the MCP server and the skills that teach Codex the brief → build → review → fix loop (design-loop, setup, brief, review and design-md).

Or add just the MCP server

In ~/.codex/config.toml:

[mcp_servers.thedesignagent]
command = "npx"
args = ["-y", "--package=@thedesignagent/mcp", "thedesignagent-mcp"]

If you skipped step 1, add env = { THEDESIGNAGENT_API_KEY = "tda_..." } to that block. The package has two commands, so keep the --package form: a bare npx @thedesignagent/mcp won't start.

Or use the hosted server, with nothing to install and no key:

[mcp_servers.thedesignagent]
url = "https://www.thedesignagent.ai/mcp"

Then run codex mcp login thedesignagent and sign in to your TheDesignAgent account in the browser. The hosted server reviews public pages and preview deploys; for pages on localhost, use the local server above.

Without the plugin, tell Codex when to use the tools in your AGENTS.md: call Discover before building a screen, then Ux and Visual on the result.

Headless runs and CI: the same key file powers the thedesignagent CLI, so codex exec jobs and CI can score pages too. For example, npx -y --package=@thedesignagent/mcp thedesignagent check <url>.

Check it works

Ask Codex to build a small screen in a repo with a UI. The first Discover call for a new project asks Codex to scan the repo and send back a project model. That happens once; after it, briefs come back straight away. When the screen is built, Codex calls Ux and Visual and fixes the high-severity findings.

If something's wrong

An authentication error means the key wasn't found: rerun thedesignagent login or set the variable. More fixes are on the support page. Other clients: Claude Code and Grok Build and Cursor.

Common questions

How do I add design review to Codex?

Save your API key once with npx -y --package=@thedesignagent/mcp thedesignagent login, then run codex plugin marketplace add CMBurnett/the-design-agent-plugin and codex plugin add tda@thedesignagent. Codex then gets a design brief before each screen and a scored UX and visual review after.

Can I add TheDesignAgent to Codex without the plugin?

Yes. Add an mcp_servers.thedesignagent block to ~/.codex/config.toml that runs npx -y --package=@thedesignagent/mcp thedesignagent-mcp, and tell Codex in AGENTS.md to call Discover before building and Ux and Visual after.