> ## Documentation Index > Fetch the complete documentation index at: https://docs.kombai.com/llms.txt > Use this file to discover all available pages before exploring further. # Agent Plugins > Install the Kombai plugin in Codex or Claude Code so your coding agent can set up its connection to Kombai and hand design work to it. The Kombai plugin lets Codex or Claude Code connect to the Kombai desktop app for you. Once connected, the agent can hand UI design and implementation tasks to Kombai and bring the results back into your chat. [Installing the plugin](#install-the-plugin) adds the `kombai-workflow` skill to your agent. When you ask your agent to work with Kombai and it can't reach Kombai yet, it uses this skill to: * Install the Kombai desktop app if it's missing * Register Kombai's MCP server with the agent, which also installs Kombai's task skills * Check that the connection works Once Kombai is connected, the skill also guides how your agent works with it. Your agent hands each task to the matching Kombai task skill and asks Kombai's questions in your chat. See [What the plugin does](#what-the-plugin-does). ## Before you begin Make sure you have the following: * Codex or Claude Code, installed and opened at least once. * The Kombai desktop app, version 2.0.125 or later. If it isn't installed, the plugin can install it for you. See [What the plugin does](#what-the-plugin-does). * A Kombai account. You sign in through your browser, not through the agent. ## Install the plugin > [tab] Codex > > Install Kombai from the Codex plugin directory. > > **In the Codex app:** > > 1. Open the **Plugins** tab. > 2. Search for **Kombai** and open its details. > 3. Select the plus button to install it. > 4. Start a new chat. > > To call the plugin directly, type `@` and choose **Kombai**, or describe a task and mention Kombai. > [tab] Claude Code > > Install Kombai from the plugins page in the Claude Code desktop app. > > 1. Open **Settings** and select **Plugins**. > 2. Search for **Kombai**. > 3. Select **Add** next to the Kombai plugin. > 4. Start a new session. > > In the new session, ask Claude Code to use Kombai for a task. See [Start working with Kombai](#start-working-with-kombai). ## Start working with Kombai Ask your agent to use Kombai for a task. For example: ```text theme={null} Use Kombai to design a pricing page for this project. ``` If Kombai isn't connected yet, the agent sets it up first. When the setup is done, start a new task (Codex) or a new session (Claude Code), because a running session can't load a newly added MCP server. In the Codex desktop app, the agent offers to start the new task for you and passes your request along. Once Kombai is connected, the agent uses the task skills that Kombai installs, such as `design-with-kombai` and `code-with-kombai`. See [What you can ask Kombai to do](#what-you-can-ask-kombai-to-do) for the full list. To confirm that Kombai is connected, run: ```bash Codex theme={null} codex mcp get kombai --json ``` ```bash Claude Code theme={null} claude mcp get kombai ``` The command shows a `kombai` entry when the connection is set up. ## What the plugin does Once Kombai is connected, your agent can hand UI work to Kombai and bring the results back into your chat. ### What you can ask Kombai to do When the plugin connects Kombai, it also installs Kombai's task skills in your agent. Your agent picks the matching skill when you describe a task, or you can call one by name. * **Design UI:** Create pages, screens, and components on Kombai's canvas (`design-with-kombai`). * **Build UI in your project:** Implement a feature or change existing code in your workspace (`code-with-kombai`). * **Turn a canvas design into code:** Implement a design from a Kombai canvas in your codebase (`code-kombai-design`). * **Improve existing UI:** Polish or rework how a page or component looks (`improve-ui-with-kombai`). * **Review UI:** Get a UI and UX critique without any file changes (`review-ui-with-kombai`). * **Extract your design system:** Detect the colors, typography, spacing, radii, shadows, and components your codebase uses, and save them as a Kombai [design system](https://docs.kombai.com/design/design-system/overview.md) (`detect-design-system-with-kombai`). * **Describe your canvases:** List your canvases and describe the designs on them (`describe-kombai-canvas`). * **Check Kombai's status:** Check your sign-in, credits, plan, and app version, or open a Kombai chat or design in the app (`kombai-status`). * **Report a problem:** Send a bug report to the Kombai team, only when you ask for it (`report-to-kombai`). ### How tasks run in Kombai * **Each task is a Kombai chat:** The task starts a chat in the Kombai desktop app, in the same workspace as your agent. Kombai opens in the background, without taking focus. * **Results land in your project:** Designs appear on a canvas in your workspace, and code changes appear in your workspace files. Your agent reads the result and reports back in your chat. * **You can follow the chat live:** Your agent gives you a link to the Kombai chat and its canvas, so you can watch the work as it runs. See [View a chat from your coding agent](https://docs.kombai.com/features/mcp/kombai-mcp-server.md#view-a-chat-from-your-coding-agent). * **Kombai's questions come to your chat:** If Kombai needs an answer during a task, your agent shows the question in your chat and sends your reply back. In Codex, the question appears as a card you answer in. You can also answer in the Kombai app. * **Chats run on your local agent:** When you ask Codex or Claude Code to use Kombai, Kombai runs the chat on that same agent as a [local agent](https://docs.kombai.com/features/local-agents.md). It uses the agent's CLI installed on your computer and your own subscription. The chat runs on the model you last selected for that agent in Kombai's model dropdown, or on the agent's default model if you haven't selected one. For example, if you last selected **Codex ยท GPT-6-Astra** in Kombai, a chat from Codex runs on GPT-6-Astra. If the agent's CLI isn't installed, is older than the [minimum version](https://docs.kombai.com/features/local-agents.md#before-you-start), or isn't signed in, the chat runs on the model or model router selected in Kombai's Model dropdown, such as **Auto**. To always use that selection, turn off **Run delegated chats on the calling agent** under **Settings > Kombai MCP Server**. * **Follow-ups continue the same chat:** Ask your agent for changes, or open the chat in Kombai and continue there. ### How the plugin sets up Kombai * **Installs Kombai if it's missing:** The agent downloads the official build from `agent.kombai.com`, checks its signature, and installs it. Your agent asks you to approve the download and the install. Automatic install covers: * macOS on Apple Silicon (through Homebrew when it's available) * Windows x64 * Linux x64 On any other operating system or processor, such as an Intel Mac or Windows on ARM, the agent stops and gives you the [Kombai download page](https://agent.kombai.com/download). It does the same if the download fails its signature check. * **Registers Kombai with your agent:** The agent runs the Kombai app's `mcp install` command. The command adds Kombai to your agent's MCP configuration and installs Kombai's task skills, without opening a Kombai window. The agent runs this command outside its sandbox, so it asks for your permission first. * **Leaves sign-in to you:** If you aren't signed in, Kombai opens its sign-in page in your browser. Sign in there, then tell your agent to continue. You don't need to open the Kombai app. The agent never asks for your credentials. ## Troubleshooting > [accordion] Codex says its permissions don't allow the setup. What should I do? > > In the Codex desktop app, some chats can't run commands outside the sandbox. Codex refuses the request without asking you. Do one of the following: > > 1. Change the chat's permissions in the menu below the message box, for example to **Approve for me**, then tell Codex to continue. > 2. Run the command that Codex gives you in a terminal. > [accordion] Why do I see "Codex is not installed or has not created its configuration directory"? > > Kombai can't find your agent's configuration folder. Open Codex once, then retry. > > The same applies to Claude Code, where the message reads `Claude Code is not installed or has not created its configuration directory. Open Claude Code once and retry.` > [accordion] Why don't the Kombai tools appear after setup? > > A running session doesn't load newly added MCP servers. Start a new Codex task or a new Claude Code session. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.