Kombai

View saved version →

---
name: about-kombai
description: Answer the user's questions about Kombai itself (what it is, which agents it works with, accounts and guest mode, credits and plans, where designs and data live, sharing, privacy, updates and support). Use when the user asks about Kombai rather than for design work.
---

When running in Codex's sandbox, request approved execution outside it **before the first
command below** and for every later Kombai CLI command. Use
`sandbox_permissions: "require_escalated"` on the execution tool call. The commands need network
access and write `~/.kombai`; `npx` may contact the package registry before Kombai starts.
Do not try the restricted command first. If this chat cannot approve the required access,
explain the restriction and wait for the user to change its permissions; do not retry inside
the sandbox.

Run `npx -y @kombai/cli@0.1.5 skill faq` and answer from what it prints; it is this skill's full text.

If that command fails before it prints anything:

- **`npx` or `node` not found.** Kombai needs Node.js 20 or later. Tell the user, give them the steps for their OS, and wait; do not install Node yourself.
  - macOS: `brew install node` if Homebrew is installed, otherwise the LTS installer from https://nodejs.org.
  - Windows: `winget install OpenJS.NodeJS.LTS`, otherwise the LTS .msi from https://nodejs.org.
  - Linux: nvm (https://github.com/nvm-sh/nvm), then `nvm install --lts`. The distro's package is often older than 20.

  When they say it is installed, run the command again. If `node` is still not found, ask them to restart this agent or its editor, so it picks up the new PATH; do not ask them to install again.
- **`CLI_NODE_TOO_OLD`.** The same steps upgrade Node; with nvm, `nvm install --lts` then `nvm alias default lts/*`. If the error comes back after an upgrade, an older `node` is first on PATH: show the user `which -a node` (`where node` on Windows).
- **Windows PowerShell says running scripts is disabled.** Run `npx.cmd` in place of `npx`.
- **The network is blocked** (a sandboxed shell). Request approved execution outside the sandbox as above; do not retry inside it. Node is not missing.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: get-started-with-kombai
description: Kombai's onboarding in Codex. Sets Kombai's canvas view up if this Codex doesn't have it yet, checks the user is signed in, and shows prompts to try in a new chat. Run by the plugin's setup and by Codex's Try now after an install, and whenever the user asks to set Kombai up, get started with it, or see what to try. Not for design requests; those are work-with-kombai's.
---

When running in Codex's sandbox, request approved execution outside it **before the first
command below** and for every later Kombai CLI command. Use
`sandbox_permissions: "require_escalated"` on the execution tool call. The commands need network
access and write `~/.kombai` and Codex's `config.toml`; `npx` may contact the package registry before Kombai
starts. Do not try the restricted command first. If this chat cannot approve the required access,
explain the restriction and wait for the user to change its permissions; do not retry inside
the sandbox.

The user can run this as often as they like. Do each step without asking first, and do no design work here.

Kombai's plugin id in this Codex is `kombai@<marketplace>`, where `<marketplace>` is the folder after
`plugins/cache/` in this skill's own path: `~/.codex/plugins/cache/openai-curated-remote/kombai/…` gives
`kombai@openai-curated-remote`.

The prompts to try, each the request a new chat starts with (the same ones as the CLI's starters card):

- Design a standout UI for my website
- Explore design directions on canvas
- Redesign this section for my app

To show them as links, build each in exec as `codex://threads/new?prompt=` followed by
`encodeURIComponent('[@Kombai](plugin://<id>) ' + prompt)` with Kombai's plugin id, then `(` and `)` as `%28` and
`%29`. End your reply with **Try one in a new chat:** and the links as a list, each `[@Kombai <prompt>](link)`, so a
link reads as what it puts in the new chat's message box, unsent, with Kombai mentioned. Give a link no other title.

First look for Kombai's tools in this chat: in exec, `ALL_TOOLS.filter((t) => t.name.startsWith('mcp__kombai'))`.
Then follow one of the two paths below.

**If `canvas_app` is there**, Kombai's view is set up and this chat has it:

1. Run `npx -y @kombai/cli@0.1.5 whoami`. If the user isn't signed in, sign them in as
   `npx -y @kombai/cli@0.1.5 skill sign-in` says.
2. If `starters_card` is there too, call it with `plugin` set to Kombai's plugin id, and end your turn with one
   line, such as "Pick one to try." Don't list the prompts in text. If it isn't (an older Kombai CLI), show the
   prompts as links instead.

**If it isn't there**, set Kombai's view up:

1. Run `npx -y @kombai/cli@0.1.5 mcp install codex`. It adds Kombai's canvas view to Codex: Kombai's MCP server, in
   the user's own Codex config. It answers `added` or `replaced` (set up now) or `already` (set up before).
2. If it answered with `disabled: true`, Kombai's view is turned off in the user's Codex config (`enabled = false`),
   so no chat gets it: tell the user the canvas can't be shown until they turn it back on, show no links, and stop.
   If it answered `notStarting: true`, Kombai's server isn't starting in Codex, so no chat gets the view either: tell
   the user the canvas can't be shown and why that may be (the answer says), show no links, and stop.
   If it answered `codexApp: false`, this is Codex in a terminal or an IDE, which shows no canvas view and can't open
   a link to a new chat: run step 3, tell the user Kombai is ready and that they can ask for a design right here, list
   the prompts as plain text, not links, and stop.
3. Run `npx -y @kombai/cli@0.1.5 whoami`. If the user isn't signed in, sign them in as
   `npx -y @kombai/cli@0.1.5 skill sign-in` says.
4. Tell the user in one line that Kombai is ready and that a new chat shows its canvas beside the chat. This chat
   can't, because Codex gives a chat only the MCP servers it had when it started. Then show the prompts as links.

   If the use

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: kombai-workflow
description: Set up or repair Codex's connection to the installed Kombai desktop app for UI design and implementation work. Use when the user asks to work with Kombai, especially when its local MCP tools are missing; do not activate for ordinary coding without Kombai.
---

# Work with Kombai

Kombai's installed desktop app owns the local `kombai` MCP server. This plugin supplies instructions only. The app may open in the background for a tool call, but it runs normally, not headlessly. Use the Kombai tools already available to the current Codex task when possible.

## Recover a missing connection

If the `kombai` MCP tools are unavailable, inspect `codex mcp get kombai --json` and check whether the Kombai desktop app is installed. An MCP entry in Codex is separate from the app installation. Resolve an installed app's executable from the actual installation or operating-system app metadata; do not guess a path, use a source checkout, or invent a localhost port.

Identify which Kombai build the user requested before choosing an executable. If they request Kombai Dev or another non-production build, check that build's installation and the MCP entry's executable and gateway paths. Never substitute an installed production build. The `kombai` entry is shared across app builds, so another build can replace it; verify the entry again before beginning work with the requested build.

- If the requested build is absent and it is the production build, install it yourself; do not send the user to a download page. Use only the official build from agent.kombai.com, verify its signature before running anything from it, and tell the user in one line what you installed. Your client may ask the user to approve the download or the install; that is expected.
  - macOS on Apple Silicon: with Homebrew, `brew install --cask kombai-io/kombai/kombai`. Otherwise download `https://agent.kombai.com/desktop/download/mac/arm64/Kombai.dmg`, attach it with `hdiutil attach -nobrowse -readonly`, check `codesign --verify --deep --strict` and `spctl --assess --type execute` on `Kombai.app` (both must pass), copy it to `/Applications` (or `~/Applications` when that is not writable), then detach the image and delete the download.
  - Windows x64: download `https://agent.kombai.com/desktop/download/win/x64/Kombai-Setup.exe`, check that `Get-AuthenticodeSignature` reports `Valid` for signer `Kombai INC`, then run it and wait for it to finish (it installs for the current user).
  - Linux x64: download `https://agent.kombai.com/desktop/download/linux/x64/Kombai.AppImage` to `~/Applications` and make it executable.
  - Anything else (an Intel Mac, ARM Windows or Linux), a failed signature check, or a download that is not the installer: stop, say why, and give https://agent.kombai.com/download. Never run an installer from anywhere else.
  - For Kombai Dev or another non-production build, use the build supplied by the user or their team; never substitute production. After installation, check again and continue registration.
- If the requested build is installed but its MCP entry is missing or stale, run that build's executable with `mcp install codex`. This registration command exits without opening a Kombai window. If your shell runs commands in a sandbox, run that command outside it from the first try, asking for escalated or unsandboxed execution the way your client does. Inside a sandbox the executable cannot reach the window server or Kombai's local bridge: on macOS it crashes before printing anything, with exit code 134, and the user sees a crash dialog. Exit code 134 with no output from a sandboxed run means exactly that, not a broken Kombai: run the command again outside the sandbox. Do not attempt to run an executable from this plugin package.
- This task's permissions may not let you run anything outside the sandbox: escalation can be switched off, so a request is refused before the user is asked. The Codex desktop app does this in a ch

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: work-with-kombai
description: Design UI with Kombai. Designs go on a Kombai canvas, which the Codex app shows beside the chat; design systems are .ds files in the Kombai account and need no canvas. Use when the user asks to work with Kombai, for a design, mockup, variants or a design system, or pastes a Kombai canvas link; not for ordinary coding.
---

When running in Codex's sandbox, request approved execution outside it **before the first
command below** and for every later Kombai CLI command. Use
`sandbox_permissions: "require_escalated"` on the execution tool call. The commands need network
access and write `~/.kombai`; `npx` may contact the package registry before Kombai starts.
Do not try the restricted command first. If this chat cannot approve the required access,
explain the restriction and wait for the user to change its permissions; do not retry inside
the sandbox.

**First, before anything else, even `npx -y @kombai/cli@0.1.5 skill`:** in the Codex app, look for Kombai's
`canvas_app` tool. Codex lists no MCP tool up front, so search inside exec with
`ALL_TOOLS.filter((t) => t.name.endsWith('canvas_app'))`. If it doesn't exist, Kombai's view isn't set up in Codex
yet: set it up without asking, with `npx -y @kombai/cli@0.1.5 mcp install codex` (outside the sandbox, like every
Kombai command), tell the user in one line, then follow its `next`. When it answers `notStarting: true` (Kombai's
server isn't starting in Codex) or `codexApp: false` (this Codex isn't the app, so it shows no view), its `next` starts
no new task: follow it, and carry on in this task as it says. Otherwise it moves the work to a new task: one offer,
with a link that opens it with the request filled in, and on yes a new task that carries the request; the new task's
prompt starts with Kombai's mention. Then do no design work in this task: it can't show the canvas. Kombai's
plugin id in this Codex is `kombai@<marketplace>`, where `<marketplace>` is the folder after `plugins/cache/` in
this skill's own path: `~/.codex/plugins/cache/openai-curated-remote/kombai/…` gives `kombai@openai-curated-remote`.

Once `canvas_app` exists, it is the only way to show a canvas here: call it with the canvas id right after
`kombai canvas create`, before you write any design, or when you first use a canvas that isn't already open beside
the chat. No browser, no in-app browser, and no canvas link unless the user asks for one; show no link when the view
isn't there either.

Run `npx -y @kombai/cli@0.1.5 skill` and follow what it prints; it is this skill's full text.

If that command fails before it prints anything:

- **`npx` or `node` not found.** Kombai needs Node.js 20 or later. Tell the user, give them the steps for their OS, and wait; do not install Node yourself.
  - macOS: `brew install node` if Homebrew is installed, otherwise the LTS installer from https://nodejs.org.
  - Windows: `winget install OpenJS.NodeJS.LTS`, otherwise the LTS .msi from https://nodejs.org.
  - Linux: nvm (https://github.com/nvm-sh/nvm), then `nvm install --lts`. The distro's package is often older than 20.

  When they say it is installed, run the command again. If `node` is still not found, ask them to restart this agent or its editor, so it picks up the new PATH; do not ask them to install again.
- **`CLI_NODE_TOO_OLD`.** The same steps upgrade Node; with nvm, `nvm install --lts` then `nvm alias default lts/*`. If the error comes back after an upgrade, an older `node` is first on PATH: show the user `which -a node` (`where node` on Windows).
- **Windows PowerShell says running scripts is disabled.** Run `npx.cmd` in place of `npx`.
- **The network is blocked** (a sandboxed shell). Request approved execution outside the sandbox as above; do not retry inside it. Node is not missing.

Referenced files: 1 — file references are metadata, not package contents.