Skip to main content
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 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.

​
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.
  • A Kombai account. You sign in through your browser, not through the agent.

​
Install the plugin

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.

​
Start working with Kombai

Ask your agent to use Kombai for a task. For example:
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 for the full list. To confirm that Kombai is connected, run:
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 (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.
  • 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 agent: A new chat from Codex or Claude Code runs on that same agent inside Kombai, on your own subscription. If the agent can’t run in Kombai on your machine, the chat uses Kombai’s models instead. To always use Kombai’s models, open Settings > Kombai MCP Server in Kombai and turn off Run delegated chats on the calling agent. Kombai uses credits either way.
  • 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. 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

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.
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.
A running session doesn’t load newly added MCP servers. Start a new Codex task or a new Claude Code session.