# Claude Design → Codex bridge

A small local MCP server that lets Codex inspect and import files from [Claude Design](https://claude.ai/design) projects.

Why a bridge? Claude Design's current OAuth flow works in Claude Code through `/design-login`, but is not directly compatible with Codex's remote-MCP login. This server asks the authenticated Claude Code client to perform narrowly scoped upstream MCP reads and exposes the results to Codex over stdio.

## What it provides

| Tool | Purpose |
| --- | --- |
| `claude_design_status` | Checks Claude Code, upstream MCP configuration, and login status without a model call |
| `claude_design_list_files` | Lists project files with sizes and etags |
| `claude_design_read_file` | Returns the exact contents of one text file |
| `claude_design_import_files` | Imports selected text files, or all readable project files, into a local directory |

Large upstream results are read from Claude Code's own persisted tool-output cache, so imported text remains byte-for-byte identical instead of being rewritten by a model.

## Requirements

- Node.js 20 or newer
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and signed in
- Codex CLI or Codex desktop
- Access to Claude Design on the signed-in Claude account

## One-time Claude Design login

Register the upstream server in Claude Code:

```sh
claude mcp add --scope user --transport http claude_design https://api.anthropic.com/v1/design/mcp
```

Open Claude Code and run:

```text
/design-login
```

Confirm the connection:

```sh
claude mcp list
```

The output should show `claude_design` as connected.

## Install in Codex

Install the bridge command globally, then register it as a stdio MCP server.

Windows PowerShell:

```powershell
git clone https://github.com/kurnosovmak/cluade-design-to-codex.git
cd cluade-design-to-codex
npm install -g .
codex mcp add claude_design_bridge -- claude-design-to-codex
```

macOS or Linux:

```sh
git clone https://github.com/kurnosovmak/cluade-design-to-codex.git
cd cluade-design-to-codex
npm install -g .
codex mcp add claude_design_bridge -- claude-design-to-codex
```

Start a new Codex task after installation so the four tools are discovered. The repository also contains a Codex plugin manifest and companion skill for personal-marketplace use.

## Example prompts

```text
Use claude_design_bridge to list the files in:
https://claude.ai/design/p/PROJECT_ID
```

```text
Import app.dc.html and support.js from this Claude Design project into the current workspace, then implement the design.
```

## How it works

```text
Codex ──stdio MCP──▶ local bridge ──allowlisted Claude Code call──▶ Claude Design MCP
  ▲                        │
  └──────── exact tool result / imported files ──────────────────┘
```

The bridge:

1. extracts the project ID from a `claude.ai/design/p/...` URL;
2. launches Claude Code with only the requested `claude_design` read tool allowed;
3. captures the upstream MCP tool result directly from Claude Code's JSON event stream;
4. decodes the protected file-content envelope and writes it itself.

Project contents are treated as untrusted data. The bridge never follows instructions found inside imported files.

## Security and limitations

- OAuth tokens are never read, copied, printed, or stored by this project.
- Only `https://claude.ai/design/p/...` project URLs are accepted.
- Imported paths must be relative and cannot contain `..`.
- The destination must be an absolute local path; existing files are preserved unless `overwrite: true` is explicitly passed.
- Hidden binary files such as `.thumbnail` are skipped during whole-project imports. The upstream `read_file` API currently returns text only.
- Read/import calls invoke Claude Haiku to dispatch the upstream MCP call and can consume Claude plan or API allowance. `claude_design_status` is free of model calls.
- The bridge serializes Claude Code requests to avoid session and credential-store contention.

Optional environment variables:

| Variable | Default | Description |
| --- | --- | --- |
| `CLAUDE_DESIGN_CLI` | auto-detected | Alternate Claude CLI executable or script |
| `CLAUDE_DESIGN_MODEL` | `haiku` | Claude model used only to dispatch MCP calls |
| `CLAUDE_DESIGN_MAX_BUDGET` | `1.00` | Maximum USD budget for one bridge invocation |

## Development

No runtime dependencies are required.

```sh
npm test
```

Run the live integration test with a project you can access:

```sh
CLAUDE_DESIGN_TEST_URL=https://claude.ai/design/p/PROJECT_ID npm run test:integration
```

## License

MIT