# App menu
Source: https://docs.kombai.com/account/app-menu
These options are present in Kombai's top menubar. You can start a new chat, open history, access quick settings, expand Kombai in editor, and view account.
## New chat
To open a new chat in Kombai, click icon or use ⌥⌘N keyboard shortcut on macOS.
## History
Click the icon to view your chat history. Select a chat to load it from the history.
## Expand in editor
Kombai can be opened directly in the editor alongside your workspace files. When expanded, Kombai appears as a tab at the same level as your code files, allowing you to use the file explorer and Kombai simultaneously.
To expand Kombai in editor, click in the top menubar.
## Quick settings
Click the icon to open the [Settings](/account/settings) page.
## Subscription and Billing
Click the to open the **Subscription and Billing** page. It lets you manage and explore plans and view your remaining plan credits.
## Help section
Help section lets you log out, check credits logs, refer docs, report a bug, send feedback, and contact support. To open the help section, click the in the top menubar.
# Cancellation
Source: https://docs.kombai.com/account/cancellation
Learn how to cancel your subscription or undo a cancellation.
## Cancel your subscription
1. Navigate to the [Kombai dashboard](https://agent.kombai.com).
2. Go to the **Your Plan** page from the sidebar.
3. Scroll down to the **Billing & Invoices** section.
4. Click **Cancel Plan**.
5. You'll be redirected to Stripe's portal, where you can confirm the cancellation.
Your current plan will remain active until the end of the billing period.
## Undo cancellation
If you are a paid user and have mistakenly cancelled your subscription, you can undo the cancellation before the billing period ends.
1. Navigate to the [Kombai dashboard](https://agent.kombai.com).
2. Go to the **Your Plan** page from the sidebar.
3. Scroll down to the **Billing & Invoices** section.
4. Click **Don't Cancel Plan**.
## What happens when I cancel the plan
1. When you cancel your paid subscription, you will retain access to all existing credits until the end of the current billing period.
2. Once the billing period ends, your account will move to the free plan. Your credits will reset to 150 (the maximum rollover limit for free users), and any remaining credits from your previous subscription will not roll over.
3. When you reactivate your subscription after moving to the free plan, your account will start fresh with the credits from your new purchase. Any credits from your previous subscription that have already expired will not roll over or be restored.
# Credits
Source: https://docs.kombai.com/account/credits
Credits are the standard unit of measurement for Kombai usage. The number of credits a task consumes depends on its complexity, length, and the model or [model router](/features/models) used.
Credits are primarily consumed based on LLM tokens (used for tasks like planning and output generation) during active task processing. Actions like viewing completed tasks or previewing output in the browser do not consume credits.
You will not be charged credits for tasks that fail due to a technical issue on our end.
We are continuously working to optimize system efficiency to reduce the number of credits consumed per task.
## Credit usage and models
Models and [model routers](/features/models) let you control the trade-off between performance (quality, capabilities, speed) and credit consumption. The model or router you select applies a specific credit multiplier to the base credit usage of a task.
For example, a task that consumes 10 credits on a `1x` model would consume approximately 5 credits on a `0.5x` model and 25 credits on a `2.5x` model. See [Models](/features/models) for the full list of models and routers and their credit multipliers.
You can switch between models and routers in further conversations within the same chat to optimize credit usage for different stages of development.
## Get more credits
Users on free plan can get more credits by upgrading to the Pro plan. You can opt for a monthly credit bundle as part of the Pro plan. Once the current bundle is exhausted, you can renew the plan with the same or a different bundle.
| Monthly credits | Monthly billing | Annual billing | Extra credits |
| --------------- | --------------- | --------------------- | --------------------- |
| `2,000` | `$20` | `$192 ($16/month)` | `0% extra credits` |
| `4,200` | `$40` | `$384 ($32/month)` | `5% extra credits` |
| `6,400` | `$60` | `$576 ($48/month)` | `6.67% extra credits` |
| `8,700` | `$80` | `$768 ($64/month)` | `8.75% extra credits` |
| `11,000` | `$100` | `$960 ($80/month)` | `10% extra credits` |
| `22,000` | `$200` | `$1,920 ($160/month)` | `10% extra credits` |
| `33,000` | `$300` | `$2,880 ($240/month)` | `10% extra credits` |
| `44,000` | `$400` | `$3,840 ($320/month)` | `10% extra credits` |
| `55,000` | `$500` | `$4,800 ($400/month)` | `10% extra credits` |
| `110,000` | `$1,000` | `$9,600 ($800/month)` | `10% extra credits` |
## Buy one-time credits
Pro users can purchase one-time credit packs that are added to their account immediately. You can also buy multiple packs at once.
| Pack | Price |
| :--------------- | :----- |
| `1,000` credits | `$11` |
| `10,000` credits | `$110` |
1. [Launch Kombai extension](/get-started/set-up/ide-extension#launch-kombai-extension) in your IDE and sign-in.
2. Click at the top.
3. In the **Buy one-time credits** section, select the number of credit packs you want to purchase.
4. Click **Buy credits**.
5. Complete the payment in Stripe's portal.
1. Navigate to the [Kombai dashboard](https://agent.kombai.com).
2. Go to the **Your Plan** page from the sidebar.
3. Click **Buy One-Time Credits**.
4. Select the number of credit packs you want to purchase.
5. Click **Buy credits**.
6. Complete the payment in Stripe's portal.
Purchased one-time credits are subject to the same rollover limits as your plan credits (up to 5x your monthly credit limit for Pro users). They remain in your account until consumed, the rollover limit is reached, or the plan is cancelled.
## Check credit usage
You can track the credit usage history for all your Kombai chats on the **Credit Logs** page. You can also check the credits consumed in an individual chat at the end of that conversation.
1. Click the icon on top.
2. Click **Credit Logs**.
You will see the remaining credits in your plan and your credit usage history.
Click at the end of a conversation. A popover will open, displaying the number of credits used in that chat.
## Check allocated credits
1. Click the icon on top.
2. Click **Credit Logs**.
3. Click **Allocation**.
## Credit rollovers
### Users on free plan
* For users on free plan, unused credits roll over at the start of each month.
### Users on paid plans
* For users on monthly plan, unused credits roll over at the end of each billing cycle.
* For users on annual plan, unused credits roll over every month on the same date they purchased the plan.
* For users upgrading from free plan to a paid plan, unused credits will roll over to the new plan.
* For users upgrading from a paid plan to a higher paid plan, unused credits will roll over to the new plan.
### Users who cancel their plan
* For users who cancel their plan, up to 150 unused credits will roll over to the free plan.
### Rollover limits
* **Free plan:** Unused credits can roll over up to 150 credits (0.5x the monthly limit).
* **Monthly plans:** Unused credits can roll over up to 5x the monthly credit limit.
* **Annual plans:** Unused credits can roll over up to 12x the monthly credit limit (equivalent to the annual limit).
* **Team plan:** All unused credits will roll over the team's billing cycle renewal date without any limit.
## FAQs
All new users receive 150 credits upon signing up. Free plan users also receive 50 credits per day, up to a maximum of 300 credits each month.
Your monthly credit limit refreshes on the same date and time your subscription started.
The "credits used" displayed after each message represents the **total cumulative credit usage for the entire chat**. It includes credits consumed by all messages within that conversation.
# Pricing
Source: https://docs.kombai.com/account/pricing
Kombai offers three plans: Free, Pro, and Enterprise.
## Free Plan
* 300 credits / month
* 150 credits on sign-up
* 50 credits daily
* Credit rollovers up to 0.5x monthly limit
## Pro plan
* Monthly credits based on your chosen credit bundle (`2,000`, `4,200`, `6,400`, `8,700`, `11,000`, `22,000`, `33,000`, `44,000`, `55,000`, `110,000` credits)
* Credit rollovers up to 5x monthly limit
* Email support
* No AI training on your data
* SOC2 compliance
## Enterprise plan
* Custom context engine to ensure high accuracy for complex component libraries & tech stacks
* Centralized invoice/ PO billing
* Dedicated support
* Onboarding services
* SOC2 compliance & security evaluations
* No AI training on your data
## Pro plan pricing
The Pro plan includes a set number of credits and supports both monthly and annual billing. Annual billing offers additional benefits, such as a lower monthly rate and higher rollover limits for unused credits. Once the current bundle is used up, the plan can be renewed with the same or a different bundle.
| Monthly credits | Monthly billing | Annual billing | Extra credits |
| --------------- | --------------- | --------------------- | --------------------- |
| `2,000` | `$20` | `$192 ($16/month)` | `0% extra credits` |
| `4,200` | `$40` | `$384 ($32/month)` | `5% extra credits` |
| `6,400` | `$60` | `$576 ($48/month)` | `6.67% extra credits` |
| `8,700` | `$80` | `$768 ($64/month)` | `8.75% extra credits` |
| `11,000` | `$100` | `$960 ($80/month)` | `10% extra credits` |
| `22,000` | `$200` | `$1,920 ($160/month)` | `10% extra credits` |
| `33,000` | `$300` | `$2,880 ($240/month)` | `10% extra credits` |
| `44,000` | `$400` | `$3,840 ($320/month)` | `10% extra credits` |
| `55,000` | `$500` | `$4,800 ($400/month)` | `10% extra credits` |
| `110,000` | `$1,000` | `$9,600 ($800/month)` | `10% extra credits` |
# Settings
Source: https://docs.kombai.com/account/settings
The Settings page is a central hub to manage Kombai settings and access key features. It brings together Tech Stack, Context Graphs, Models, Design Mode, External MCP Servers, Rules, Commands & Skills, Kombai Browser, and Other settings, along with links to external resources like Support and Docs.
## Settings Tabs
To open the Settings page, click the icon in Kombai's top menubar.
The Tech Stack page lets you define the libraries and frameworks used in your repo. Learn more in the [Tech Stack overview](/features/overview).
The Context Graphs page lets you manage how Kombai indexes and understands your codebase. See [Context Graphs](/context/context-graphs) for details.
The Models page lets you control which model routers and models appear in the chat dropdown. Toggle any entry on or off to show or hide it. See [Models](/features/models) for details.
The Design Mode page includes the **High creativity** setting. Turn it on to generate highly creative designs with a bias towards complex animations. It is best suited to landing pages and hero sections that need to stand out.
Designs generated with High creativity open in a browser-sized view on the canvas. Scroll inside the browser-sized view to see the full content and its animations.
See [Design Mode](/design/overview#high-creativity) for details.
The External MCP Servers page lets you configure Model Context Protocol (MCP) servers to extend Kombai's capabilities. See [MCP](/features/mcp) for details.
The Rules, Commands & Skills page lets you manage custom instructions, automation workflows, and reusable skills. Each has an **Individual** sub-tab for your own and project-level items, and a **Team** sub-tab for sharing across your team. See [Rules](/features/rules), [Commands](/features/commands), and [Agent Skills](/features/agent-skills) for details.
* **Allow agent to access Browser**: Toggle the browser mode. When enabled, the assistant can interact with web pages.
* **Test Connection**: Validate that the Kombai browser executable is reachable and working correctly.
* **Profiles & Session Sync**: Import sessions and cookies from your local Google Chrome profiles to bypass logins.
Read [Kombai Browser Overview](/browser/overview) doc.
Use the **Other** page to configure command approvals and conversation compaction.
* **Command approval**: Choose how Kombai handles approval before running terminal commands.
* **Ask Every Time**: Ask for approval before each command.
* **Auto-approve for me**: Let Kombai approve commands on your behalf.
* **Bypass permissions**: Run every command without asking for approval.
* **Auto compact threads**: Automatically summarize long conversation histories to optimize context usage and improve response speed.
To reach out to the support team.
To access the full documentation portal to explore detailed guides and references.
# Subscription
Source: https://docs.kombai.com/account/subscription
Learn how to upgrade your plan, downgrade your plan, view past invoices, and change payment method.
## Upgrade your free plan to a paid plan
You can upgrade from either the Kombai extension in your IDE or the Kombai dashboard.
1. [Launch Kombai extension](/get-started/set-up/ide-extension#launch-kombai-extension) in your IDE and sign-in.
2. Click at the top.
3. Select a credit bundle from the dropdown.
4. Click **Upgrade plan**.
5. Click **Open**.
6. Complete the subscription in Stripe's portal.
1. Navigate to the [Kombai dashboard](https://agent.kombai.com).
2. Click **Upgrade Plan** button. Or go to **Your Plan** page from the sidebar.
3. Select a credit bundle from the **Credit Bundle** dropdown under **Upgrade to Pro** section.
4. Click **Upgrade**.
5. Complete the subscription in Stripe's portal.
## Upgrade your paid plan to a higher paid plan
1. [Launch Kombai extension](/get-started/set-up/ide-extension#launch-kombai-extension) in your IDE and sign-in.
2. Click at the top.
3. Select a higher credit bundle from the dropdown.
4. Click **Upgrade plan**.
5. Click **Open**.
6. Complete the subscription in Stripe's portal.
Unused and unexpired credits in your account always roll over when you
upgrade. You never lose existing credits by upgrading. Learn more about
[Credit rollovers](/account/credits#credit-rollovers).
### Upgrading monthly plans to higher monthly plans
* When you switch from a monthly plan to a higher monthly plan, you're charged immediately for the price of your new plan.
* Any unused credits from your monthly plan roll over into your new monthly plan.
* Your new monthly plan starts on the upgrade date, and your renewal date resets to that same day each month.
### Upgrading monthly plans to annual plans
* When you switch from a monthly plan to an annual plan, you're charged immediately for the annual price of your new plan.
* Any unused credits from your monthly plan roll over into your new annual plan.
* Your annual plan starts on the upgrade date, and your renewal date resets to that same day each year.
### Upgrading annual plans to higher annual plans
* When you upgrade your plan, you are only charged prorated amounts based on how much time is left in your current billing cycle.
* For example, if you’re on a `$192` yearly plan and switch to a `$576` yearly plan halfway through the year, the unused `$96` from your old plan is applied as an adjustment. You’ll then be charged `$288` for the remaining half of the cycle on the `$576` plan, minus the `$96` adjustment. This means you’ll pay an additional `$192` overall for that year.
* Your renewal date does not change. From the next billing cycle onward, you’ll be charged the full `$576` each year for your upgraded plan.
* You also receive enough additional credits to bring you up to the new plan's full monthly allocation for the month in which you upgrade, plus you get that full allocation again on each monthly anniversary for the rest of your billing cycle.
## Renew your same plan
When your credits in the current plan are over, you can also renew the same plan instead of upgrading to a higher plan. This will reset your billing cycle to the start of the newly renewed plan.
1. [Launch Kombai extension](/get-started/set-up/ide-extension#launch-kombai-extension) in your IDE and sign-in.
2. Click at the top.
3. Select the same plan from the dropdown.
4. Click **Restart plan**.
5. Click **Open**.
6. Complete the renewal in Stripe's portal.
1. Navigate to the [Kombai dashboard](https://agent.kombai.com).
2. Go to the **Your Plan** page from the sidebar.
3. Select the same credit bundle from the **Credit Bundle** dropdown.
4. Click **Restart plan**.
5. Complete the renewal in Stripe's portal.
## Downgrade your plan
You can downgrade to a lower credit bundle from either the Kombai extension in your IDE or the Kombai dashboard.
1. [Launch Kombai extension](/get-started/set-up/ide-extension#launch-kombai-extension) in your IDE and sign-in.
2. Click at the top.
3. Select a lower credit bundle from the dropdown.
4. Click **Downgrade plan**.
5. Click **Open**.
6. Authorize the payment in Stripe's portal.
1. Navigate to the [Kombai dashboard](https://agent.kombai.com).
2. Go to the **Your Plan** page from the sidebar.
3. Select a lower credit bundle from the **Credit Bundle** dropdown.
4. Click **Downgrade**.
5. Authorize the payment in Stripe's portal.
## View past invoices
1. Navigate to the [Kombai dashboard](https://agent.kombai.com).
2. Go to the **Your Plan** page from the sidebar.
3. Scroll down to the **Billing & Invoices** section.
4. Click **View Past Invoices**.
5. You'll be redirected to Stripe's portal, where you can view your past invoices.
## Change your payment method
1. Navigate to the [Kombai dashboard](https://agent.kombai.com).
2. Go to the **Your Plan** page from the sidebar.
3. Scroll down to the **Billing & Invoices** section.
4. Click **Change Payment Method**.
5. You'll be redirected to Stripe's portal, where you can change your payment method.
# Autonomous agent operations
Source: https://docs.kombai.com/browser/autonomous-agent-operations
Kombai can autonomously navigate and interact with the browser to perform tasks.
Kombai can perform actions like navigating to different pages, clicking on buttons, and filling out forms to test your applications. To start using the browser autonomously, ask Kombai to perform a task in the Kombai Browser.
## Capabilities
Kombai can test navigations inside your application with actions like visiting
a page, switching between tabs, or navigating to different routes.
Kombai can open new tabs, list and switch between open tabs, and close tabs or
the whole browser window to test multi-page and multi-window flows.
Kombai can identify interactive elements in your interface and test the
clickability of these elements. It can perform clicks, double clicks,
right-clicks and hover actions on any visible element on the webpage like
buttons, links, and form fields.
Kombai can identify an input field and type text into it. It fills out forms,
submits data, and interacts with text areas and search boxes.
Kombai can scroll lengthy pages to reveal more content, find specific
elements, and explore large documents.
Kombai can take screenshots to understand page layouts, verify visual
elements, and provide visual confirmation of its browser actions.
Kombai can select a rectangular region of the page and detect the elements
inside it, returning a cropped image along with the matched elements. This helps
when an area is easier to point at by coordinates than to describe by selector.
Kombai can read the page's DOM structure and the computed CSS of any element,
covering layout, typography, color, spacing, borders, flex/grid, transforms, and
more. It uses this to understand how the UI is built before it suggests or makes
changes.
On React apps, Kombai can map any element to its nearest React component and
read the component's name, props, state, and source file location. This traces
what you see on screen back to the code that renders it.
Kombai can detect the UI frameworks running on a page (such as React, with its
version) to tailor how it inspects and edits the application.
Kombai can read the CSS custom properties (variables) declared on the page, such
as your color, spacing, and typography tokens, so its style changes stay
consistent with your design system.
Kombai can make live, in-page changes to preview a result before writing any
code, including applying or removing CSS, editing text, moving or deleting
elements, and injecting fonts or animations.
After editing your source, Kombai can wait for the dev server's next Hot Module
Replacement event (Vite, Webpack, Next.js, Turbopack, Remix, Parcel, esbuild)
before re-inspecting. This enables a reliable edit, reload, and verify loop.
Kombai can monitor the browser console to troubleshoot problems and check page
behavior by reading JavaScript errors, network warnings, and debugging output.
Kombai can monitor the page's HTTP requests and responses, allowing it to
track API calls, analyze payloads, check status codes, and diagnose network
issues.
Kombai can measure the page's performance, including Core Web Vitals (LCP, CLS,
INP, FID) with good / needs-improvement / poor ratings, loading metrics (FCP,
TTFB, TBT, TTI), transfer size, and JavaScript heap usage, to help identify and
optimize performance bottlenecks.
Kombai can audit the current page for accessibility and SEO issues and report
what to fix.
# Capabilities
Source: https://docs.kombai.com/browser/capabilities
Learn how to use the extension's element selector, snipping tool, CSS editor, and DOM editor.
## Send DOM elements as context
Kombai includes and tools to help you select or snip DOM elements and attach them to the browser extension's chat window.
Follow the steps in the [Element Selector](#element-selector) and [Snipping tool](#snipping-tool) sections below to use these tools.
### Element selector
1. Click the icon in the browser extension's chat window. Alternatively, press ⌘ + ⌥ + . on macOS.
2. Click the DOM element you want to send to Kombai. When you click, Kombai captures a screenshot of both the element and the entire page.
3. Add any additional instructions you want to send to Kombai.
4. Click the **Send to agent** button.
### Snipping tool
1. Click the icon in the browser extension's chat window. Alternatively, press ⌘ + ⌥ + S on macOS.
2. Hold and drag the mouse over the UI area you want to snip. Snipped DOM elements and their screenshots will be captured and attached as context.
3. Add any additional instructions you want to send to Kombai.
4. Click the **Send to agent** button.
## Send visually edited CSS styles to Kombai as context
You can select an element and visually edit its CSS to preview how that element will look like before sending the changes to Kombai for implementation. You can visually edit the position, layout, appearance, and font styles of the selected element.
1. Click the icon in the browser extension's chat window. Alternatively, press ⌘ + ⌥ + . on macOS.
2. Click the DOM element you want to send to Kombai.
3. Go to the **Design** tab in the Kombai extension and edit the CSS values visually based on the available dropdowns and input boxes.
4. Ask Kombai to implement changes and send the message to agent.
## Edit site texts live and send them to Agent
The text editor lets you edit texts in your webpage live and send them to Agent for code implementation. You can edit the text of any element on the page, including headings, paragraphs, buttons, and input fields.
1. Click the icon in the browser extension's chat window. Alternatively, press ⌘ + ⌥ + T on macOS.
2. Click on a text element on the page to make it editable.
3. Edit the text.
4. Click the **Send to agent** button.
## Use DOM editor to visually rearrange and delete DOM elements
You can use the DOM editor to visually drag and rearrange DOM elements or delete them from the UI.
### Drag and rearrange DOM elements
1. Click the icon in the browser extension's chat window. Alternatively, press ⌘ + ⌥ + E on macOS.
2. Click and hold a UI element on the page and drag it to a new position to rearrange it.
3. Click the **Send to agent** button.
### Delete DOM elements
1. Click the icon in the browser extension's chat window.
2. Click a UI element on the page and press the Delete / Backspace key on your keyboard to delete the element.
3. Click the **Send to agent** button.
## Capture sections onto your design canvas with Web Capture
The **Web Capture** tool lets you grab any section of a live page, or the entire page, and bring it onto your Kombai [design canvas](/design/canvas), where you can iterate on it or use it as inspiration.
1. Click the icon in the browser extension's chat window.
2. Hover over the page and click a section to capture it. To capture the entire page instead, click **Capture full page** in the Web Capture panel.
3. Captured items appear as cards in the Web Capture panel. Use **Highlight in page** to locate a capture on the page, or **Clear all** to remove them.
4. Press Esc to exit Web Capture mode.
## Preview multiple screens
You can use multiple browser tabs to preview different screens of your app simultaneously. This enables you to select elements from other screens that you want to refer to in your current browser tab.
For example, if you have the **Homepage** open and want to add an avatar from the **Accounts** page:
1. Open the Accounts page in a new tab.
2. Select the avatar element.
3. Return to the previous tab (Homepage).
You will see the avatar's DOM element highlighted in yellow. You can then ask Kombai to add the avatar to the Homepage.
## Send browser data
The browser extension automatically attaches all available browser data to your messages as context. Beyond DOM elements and applied CSS changes, it captures the entire DOM tree, console logs, network errors, and performance metrics (Web Vitals).
Using this data, Kombai fixes console and network errors, boosts page performance, refactors UI components, and edits your UI with precision.
### Example prompts
1. Fix console errors in my app.
2. Create a new `` component to group the tagged cards together.
3. Identify slow network requests and suggest improvements.
4. Give me the current performance metrics of the page.
# Get Started
Source: https://docs.kombai.com/browser/get-started
Set up and launch the Kombai Browser extension, explore the extension UI, and import Chrome profiles.
## Launch Kombai Browser
Here are two ways to launch the Kombai Browser:
Follow the steps below to launch the Kombai Browser without running a specific project:
1. Click the icon. In the desktop app, it's in the [top bar](/get-started/navigating-the-desktop-app#top-bar) above the chat, and also in the row below the chat input on the home screen. A green dot on the icon means the browser is already running.
2. Click the icon.
Follow the steps below to preview your project in the Kombai Browser:
1. Ask Kombai in the chat to run your project.
2. Once the server is running, a localhost link will appear in the chat stream.
3. Click the link to load your project's preview in the Kombai Browser.
If you want Kombai to autonomously control the browser, you can ask Kombai in the chat to perform your task in the browser.
## Extension UI
Kombai Browser has a pre-installed extension that lets you update the UI with built-in tools and send the data back to the agent as context. The browser extension is divided into four parts:
### Chat selector
The browser extension has a chat selector at the top that lets you choose which chat to send your messages to. You can either send your messages to an existing chat or start a new one.
The selector has two sections:
1. **Send to an active chat**: Lists the chats you currently have open. Pick one, and your message is appended as the next message in that same thread, so the agent keeps all the context of that conversation.
2. **Send to a new chat**: Lists your [projects](/get-started/navigating-the-desktop-app#projects). Pick one, and your message starts a new chat inside that project.
Use the search box at the top to filter chats and projects by name.
### Chat input window
The chat input window is the main area where you can type messages and send them to the Kombai agent. All attached DOM elements and CSS changes are displayed at the top of this window.
The send button offers two actions:
1. **Send to agent**: It sends your message and the attached context to Kombai immediately.
2. **Add to Chat**: It stages the attached context in the Kombai chat without sending.
### Layers
The **Layers** section, located below the chat input window, contains the entire DOM tree of the current page. Scroll within the Layers section to view the page's DOM structure. Click on an element to attach it to the chat input window.
### Design and CSS
The **Design** and **CSS** tabs, located below **Layers**, let you visually edit the CSS of the current page, view a table of all applied CSS properties, and edit the CSS properties directly in the table.
The visual editor includes the following capabilities:
1. **Text Styles**: Experiment with various font families, weights, sizes, colors, line heights, letter spacings, text alignments, and text cases.
2. **Appearance**: Change the opacity and corner radius of an element.
3. **Position**: Move elements across the X, Y, and Z axes or enable absolute positioning.
4. **Layout**: Edit the flow, dimensions, padding, and margin of an element.
5. **Background**: Add solid colors or gradients as backgrounds and adjust opacity.
6. **Border**: Add borders with solid colors or gradients and adjust the opacity, style, width, and direction.
7. **Shadow & Blur**: Add drop shadows, inner shadows, layer blurs, and background blurs to a UI element.
8. **Animation**: Choose from the available animation types and adjust duration, delay, timing, and iteration count.
Once you have made your changes in the editor, click the **Send to agent** button to send the changes to the agent.
## Import cookies from Chrome profiles
By default, the Kombai agent operates within its own dedicated Chrome profile to keep it separate from your regular web browsing. As a result, it appears as a distinct application in your dock and won't have any of your accounts logged in.
To use your existing Chrome profiles, you need to import them into the Kombai Browser. When you import a Chrome profile, Kombai only downloads the cookies of that specific Chrome profile.
This feature is currently supported only on Mac.
### Import a Chrome profile
Follow these steps to import an existing Chrome profile:
1. Click the icon in Kombai's top menubar to open the [Settings](/account/settings) page.
2. Navigate to the **Kombai Browser** tab.
3. Under, **Profiles & Session Sync** section, click the icon next to the profile you want to import.
4. Click **Proceed** and authenticate.
5. Click **Mark as Default** to make this profile the default in the Kombai Browser.
### How to make a profile default
You can also make a Chrome profile default. This is handy when you work with multiple profiles inside the Kombai Browser.
When you set a Chrome profile as the default in Kombai and launch the Kombai Browser, it will use the saved cookies from that default profile. To use another profile in the Kombai Browser, you need to make that profile default.
Here's how to make a profile default:
1. Click the icon in Kombai's top menubar to open the [Settings](/account/settings) page.
2. Navigate to the **Kombai Browser** tab.
3. Under, **Profiles & Session Sync** section, hover over a profile.
4. Click the pin icon to make it default.
### Sync cookies
When you import a Chrome profile, Kombai downloads your cookies at that specific time. If you later log into new sites in your regular Chrome browser, those sessions won't be available in the Kombai Browser automatically.
Here's how to sync your cookies:
1. Click the icon in Kombai's top menubar to open the [Settings](/account/settings) page.
2. Navigate to the **Kombai Browser** tab.
3. Under **Profiles & Session Sync** section, click the icon next to the profile you want to resync.
# Overview
Source: https://docs.kombai.com/browser/overview
Kombai can launch, access, and operate a Chrome browser, enabling you to test development websites & web applications, and perform automated browser-based operations. It automatically downloads the browser the first time you set up Kombai.
You can manually perform browser operations using the element selector, snipping, text-editing, DOM-editing, and Web Capture tools, along with a visual styles editor, inside the Kombai Browser Extension, or let Kombai autonomously control the browser to perform tasks and test applications.
Use the Kombai Browser Extension to edit CSS, update text, and send DOM elements back to Kombai as context.
Let Kombai autonomously navigate, click, and interact with web pages to
execute tests and tasks.
# Context Graphs
Source: https://docs.kombai.com/context/context-graphs
Kombai builds Context Graphs for the reusable code items (aka “reusables”) in your codebase, including components, stateful primitives (e.g. hooks, stores and modules), design tokens, types, and constants. This gives Kombai a deep, semantic understanding of your project and enables consistent reuse of these items during code generation.
## Introduction to Context Graphs
Kombai's Context Graphs offer a purpose-built, domain-specific alternative to the vector-based indexing prevalent in the general-purpose coding agents.
General-purpose agents typically use embedding models to generate embeddings for code snippets, and leverage vector databases to search for nearest embedding-based matches. While this is effective for finding mechanical similarity between text strings, it often misses the crucial, domain-specific context needed for frontend development - such as how a component actually looks and what it functionally does. Furthermore, it is practically impossible to add external dependencies (like custom npm component libraries) to these standard indices.
As a result, these agents often struggle to find the appropriate code to reuse, particularly in mature, high-complexity repositories. They often hallucinate important aspects of the reusable code items (e.g. props of a component) or just skip reusing existing code, leading to unacceptably low code quality.
Kombai adopts a more human-like method to understand the reusable parts of a repository. Given a source, Kombai first identifies the relevant reusable code items. Then, it builds a use-case-specific understanding of how they work, which it stores as a Context Graph. For example, for reusable components, the Context Graph includes their primary purpose, appearance, behaviors, props and dependencies.
This approach results in better reuse of existing code, higher code quality and greater accuracy in complex tasks.
## Creating Context Graphs
You can create Context Graphs by indexing either the source code or Storybook from current workspace and NPM packages.
### Index Reusable Source Code
You can index subfolders of your current workspace that contain supported reusables, to create their Context Graphs.
Here's how to index source code from a subfolder:
![Current Workspace indexing]()
1. Click the icon below the chat input box to open the **Context Graph** popover.
2. Click the icon on the top-right corner of the popover to open the **Context Graphs** tab in the **Settings** page.
3. Click **Add your first Context Graph** / **Add new** button.
4. Click **Reusable source code** -> **Current workspace** in the modal.
5. Browse and select a subfolder from your workspace to index and continue.
6. Click **Build Context Graph**.
Once all the components are indexed, they will appear in the UI as accordions. Click on an accordion to view a quick summary of Kombai's understanding of the components.
To build a Context Graph for a NPM package, index one of the following:
* A local folder outside of this workspace that contains the source code of the package
* A URL of the git repository that contains the source code of the package
* In this case, the git credentials present in your current workspace must have cloning permissions of the git repository.
Here's how to index source code from an NPM package:
![NPM Package indexing]()
1. Click the icon below the chat input box to open the **Context Graph** popover.
2. Click the icon on the top-right corner of the popover to open the **Context Graphs** tab in the **Settings** page.
3. Click **Add your first Context Graph** / **Add new** button.
4. Click **Reusable source code** -> **NPM Package** in the modal.
* Add your Git repository URL and the Branch and continue.
* If your NPM package source is stored locally, switch to **Local Folder** tab, add path to the folder or browse your folder and continue.
5. Click **Build Context Graph**.
Once all the components are indexed, they will appear in the UI as accordions. Click on an accordion to view a quick summary of Kombai's understanding of the components.
### Index Storybook
We recommend you to use **Index Storybook** feature along with **Index Reusable Source Code** feature to get the best results.
You can index a local folder from your system that contain your stories to create their Context Graphs.
Here's how to index stories from a local folder:
![Local Folder Storybook indexing]()
1. Click the icon below the chat input box to open the **Context Graph** popover.
2. Click the icon on the top-right corner of the popover to open the **Context Graphs** tab in the **Settings** page.
3. Click **Add your first Context Graph** / **Add new** button.
4. Click **Storybook** -> **Local Folder** in the modal.
5. Browse and select a local folder from your system to index and continue.
6. Click **Build Context Graph**.
Once all the stories are indexed, they will appear in the UI as accordions. Click on an accordion to view a quick summary of Kombai's understanding of the components.
To build a Context Graph using Storybook files from a Git repository, index the URL of the git repository that contains the stories. In this case, the git credentials present in your current workspace must have cloning permissions of the git repository.
Here's how to index stories stories from a GitHub repo:
![Git Repository Storybook indexing]()
1. Click the icon below the chat input box to open the **Context Graph** popover.
2. Click the icon on the top-right corner of the popover to open the **Context Graphs** tab in the **Settings** page.
3. Click **Add your first Context Graph** / **Add new** button.
4. Click **Storybook** -> **GitHub repository** in the modal.
5. Add your Git repository URL and the Branch and continue.
6. Click **Build Context Graph**.
Once all the components are indexed, they will appear in the UI as accordions. Click on an accordion to view a quick summary of Kombai's understanding of the components.
Index Storybook feature is currently available to our users on Team plan.
### Use ContextRules to provide custom instructions for the indexing process
During the indexing process to build Context Graphs, Kombai analyzes a given source to identify relevant reusables based on established coding patterns (e.g. `index.ts` or `index.js` to identify exported components).
To provide additional guidance on how Kombai should identify reusable code items from your repo, you can specify relevant instructions in a `ContextRules.md` (filename not case sensitive) file in the `./.kombai/rules/` folder in your workspace.
This is particularly useful when Kombai indexes a repo but misses out on some code elements you consider to be reusable. You can check the list of reusable items returned by Kombai after indexing to spot such gaps, add appropriate instructions in the `ContextRules.md` file and re-index the source.
### Multiple Context Graphs
You can index multiple sources in Kombai, to create a separate Component Graph for each source (e.g. a local folder and a private npm package). For a given task, the agent has access to all the Context Graphs available in the current project.
## Managing Context Graphs
### Re-indexing Context Graphs
To manually update a Context graph, select the **Rebuild** option for the related card in **Context Graphs** page. When this option is selected, Kombai will rerun the indexing process to create a Context Graph from the latest version of the source code.
### Removing context graphs
To remove a Context Graph, click the actions menu () on the related card in the **Context Graphs** page and select **Remove**. Once removed, the agent won't consider the said Context Graph for future tasks.
### Using `stack.json` to sync Context Graphs
If the [`Sync with stack.json`](/features/overview#stack-json-file) toggle on the Tech Stack page is turned on, Kombai will automatically save the type, path, and name of the indexed Context Graphs to this file. Once you push this file to your remote Git repository, Kombai will automatically detect the Context Graphs from `stack.json` for all team members working on this repository.
## Using Context Graphs
For any given task, Kombai's coding agent can automatically access all indexed Context Graphs. You can also attach specific items from the Context Graphs by using the `Indexed Context Items` option in the `@` menu of the chat input.
Context Graphs are used by Kombai in conjunction with other available contexts and instructions, such as prompts, rules, commands, skills and local files found via agentic search. You can provide additional instructions on how the agent should use the indexed context via prompts and rules.
## How it works
Kombai follows a two step process to build Context Graphs, all executed via dedicated subagents.
### Phase 1: Discovering reusable code items
#### In current workspace
When a user inputs a folder in the current workspace, Kombai discovers all the code items that are likely to be reused. To understand what might be reusable, it relies on common naming conventions and organizational structures across different frameworks and languages as well as contextual inference on the project's conventions.
Below are the major types of reusable items it looks for:
* UI Components (from extensions like `.tsx`, `.jsx`, `.vue`, `.svelte`, `.cljs` etc.)
* Hooks (for React), Composables (for Vue) and Modules (for Angular)
* State Management: e.g. Redux slices (`*.slice.ts`), Zustand stores, Jotai atoms (`*.jotai.ts`), and Kea logic files (`*Logic.ts`) etc.
* Utility and Helper Functions
* Design Tokens and Styling
* Icons and Assets
* Type Definitions
* Services and API Clients
* Other Specialized Patterns: e.g. GraphQL operations, internationalization (i18n) locale files, form systems, chart components, and animation data (Lottie JSON)
#### In NPM packages
When a user inputs a NPM package, Kombai analyzes all exports in a two substeps, and tries to figure out all the code items that are reusable.
First, it discovers all the entry points by analyzing the configuration layer of a package to determine how it exposes its functionality to consumers.
Below are some of the analyses it performs in this step:
* **Manifest Analysis:** reads `package.json` to find `main`, `module`, `exports`, `types`, and `style` fields.
* **Subpath Mapping:** It maps export subpaths (e.g., `./components`, `./hooks`) to their corresponding source files.
* **Build Config Correlation:** If entry points point to distribution folders (e.g., `dist/`, `lib/`), the agent correlates them with source directories (e.g., `src/`) to find the original implementation.
* **TypeScript Resolution:** Analyzes `tsconfig.json` to resolve path aliases (e.g., `@/*` -> `src/*`) and identify root directories.
* **Monorepo Detection:** Detects if the root is a monorepo (Lerna, Nx, Turborepo, Pnpm Workspaces) and can selectively index sub-packages.
Then, it recursively follows the logical flow of code, and not just the physical directory tree, to identify all the export. Below are some of the analyses it performs in this step:
* **Re-export Traversal:** If an entry point (like `index.ts`) simply re-exports from other files, the agent follows those paths until it finds the actual definitions.
* **External vs. Internal:** It distinguishes between items implemented within the package and those re-exported from third-party `node_modules`. External re-exports are indexed with metadata pointing to the original package.
* **Cycle Detection:** The agent maintains a traversal chain to prevent infinite loops in complex re-export structures.
* **Framework specific support:** It detects and processes framework specific code patterns. E.g. it processes `ng-package.json` files for Angular libraries, ensuring correct entry point discovery for the Angular ecosystem
### Phase 2: Creating semantic context for each reusable item
Once the reusable code items are identified, Kombai analyzes them using parallel subagents to develop an easily reusable context for each of them.
The agent reads the source to extract semantic meaning, determining not just the name but their purpose, usage, behaviors and dependencies. Each item is also assigned a **Type** (component, hook, function, store, etc.) and a **UI Category** (layout, navigation, data display, etc.).
## Troubleshoot
Please make sure that following pre-requisites are fulfilled:
* The git url is of a valid repo - this should typically be of the format [https://github.com/\{org}/\{repo}.git](https://github.com/\{org}/\{repo}.git)
* The branch name used is of a valid branch
* The git credentials present in your system has view permissions for the Git URL and branch you are trying touse
* Once these pre-requisites are confirmed, please retry running the indexing process.
If you are getting an error that indicates that the process was timed out, it might be because the target repository is too large. In that case, please try selecting one of the subpackages from the subpackage selection menu that comes up after you enter the url.
If you face persistent errors, please reach out to `support@kombai.com` with a screenshot and details of the error you are facing.
This message means Kombai likely needs additional guidance to understand the patterns of the reusable code items in your source. Please see [this](#use-contextrules-to-provide-custom-instructions-for-the-indexing-process) section for more details.
If the issue persists, please reach out to [support@kombai.com](mailto:support@kombai.com) with a screenshot, details of the source you are trying to index and patterns of the reusable code items (e.g. components, hooks or types) in that repo.
# @Mentions
Source: https://docs.kombai.com/context/mentions
`@Mentions` lets you attach Canvas designs, individual designs, Excalidraw diagrams, Figma links, files, folders, indexed items, and terminals to the context.
## @Canvas
Use `@Canvas` to attach a Canvas from [Design Mode](/design/canvas) to the Kombai chat. Type `@Canvas` in the chat input, then select the Canvas you want to attach.
Provide context for full-page layouts, including sidebars, headers, and main content areas.
Verify layout patterns and design consistency across all designs within a specific Canvas.
## @Designs
Use `@Designs` to attach individual designs from a Canvas to the Kombai chat. Type `@Designs` in the chat input, then select the design you want to attach.
Reference individual designs for precise code generation of specific pages or complex components.
Request specific modifications, style updates, or additions to an existing design in your Canvas.
## @Excalidraw
Use `@Excalidraw` to paste Excalidraw elements into the Kombai chat. Type `@Excalidraw` in the chat input to open a **Paste JSON** dialog where you can paste copied Excalidraw elements. The pasted content is sent to Kombai as a JSON context that it can interpret and work with.
Provide hand-drawn wireframes or UI sketches as visual context to generate functional code and layouts.
Refine, extend, or modify existing architecture diagrams and flowcharts by pasting them back into the chat.
You can also paste copied Excalidraw elements directly into the chat input without using the `@Excalidraw` menu.
## @Figma
Use `@Figma` to attach Figma links to the Kombai chat. Type `@Figma` in the chat input, then paste the Figma link you want to attach.
Reference Figma links for high-fidelity code implementation that matches your design's layout and styling.
Tag multiple Figma designs to explain how the app should look in different states like Loading, Error, and Success.
Ask specific questions about layout, spacing, or color choices within your linked Figma design.
## @Files
Use `@Files` to attach files from your codebase to the Kombai chat. Type `@Files` in the chat input, then select the file you want to attach.
Get explanations for complex logic or request refactoring of large components into smaller, reusable parts.
Attach specific files to provide implementation details, configuration constants, or architectural context for new code generation.
You can also drag and drop files into the input box, or type `@` to quickly
select from your three most recently opened files.
## @Folders
Use `@Folders` to attach codebase folders containing multiple files to the Kombai chat. Type `@Folders` in the chat input, then select the folder you want to attach.
Reference a folder before asking Kombai to scaffold a new feature following that folder's existing structure and patterns.
Ask questions that require connecting logic and data flow across several related components or files.
## @Indexed Items
Use `@Indexed Items` to attach specific items from your [Context Graphs](/context/context-graphs) to the Kombai chat. Type `@Indexed Items` in the chat input, then select the item you want to attach.
Manually select specific indexed components or hooks you want Kombai to use for a particular task.
Ask about the props, internal logic, or implementation details of a specific indexed item.
## @Terminals
Use `@Terminals` to attach the terminal state (logs, errors, and output) to the Kombai chat. Type `@Terminals` in the chat input, then select the terminal you want to attach. You can also select a portion of the terminal output, right-click, and **Add to Kombai** to attach it to the chat.
Resolve peer dependency warnings, version mismatches, and installation failures with lockfile conflicts.
Troubleshoot build failures and API route errors using logs and error messages directly from your terminal.
# Compaction
Source: https://docs.kombai.com/context/thread-compaction
Longer conversations in a single thread can exceed the model’s context window, leaving you unable to continue with that thread.
Compaction solves this by condensing older messages in a thread into a high-density summary. This immediately restores available tokens upto a certain extent, letting you continue with the thread for a longer period of time. It also allows the Agent to focus fully on your most recent queries while maintaining a clear understanding of the thread history.
## When is compaction triggered
Kombai monitors your context usage in a thread and dynamically decides the best points to compact context. Below are two common scenarios when Kombai will trigger compaction automatically:
* **Context window saturation:** When the thread consumes the majority (typically above 90%) of the available context window.
* **Cache expiry:** To optimize costs, Kombai auto-compacts the thread when the cache is close to expiring and context usage is at 50-60%. Some examples of cache expiry include switching the **model** and changing the **thinking effort**.
If you edit or restore a message, the previous compaction is reset, which may temporarily increase context usage. As you continue the conversation, Kombai will re-evaluate and trigger compaction again if necessary.
## How context is managed
The context window is shared across several elements beyond your message history:
* **Infrastructure overhead:** Tools, system prompts, skills, and RAG attachments typically occupy 15–35% of the window, depending on your tech stack.
* **Persistent rules:** Project and User Rules are never compacted. They remain in their full form to ensure the Agent strictly adheres to your constraints at all times.
## Toggle auto-compaction
Compaction is enabled by default. If you prefer to manage the context window manually, you can disable **Auto compact threads** on the **Other** tab under [Settings](/account/settings) page.
## Manually compact a thread
You can trigger compaction at any time by clicking the icon at the end of your thread and selecting **Compact thread**.
## Why compact a thread
1. **Extended conversations:** Restore available tokens to maintain a single, continuous thread for long-term projects.
2. **Optimized performance:** Experience faster response times as compaction will reduce the massive overhead of uncompressed history.
3. **Preserved context:** Retain critical information and decision points through intelligent summarization while discarding redundant data.
4. **Cost efficiency:** Dramatically reduce token consumption in API calls by compressing the massive context.
# Canvas
Source: https://docs.kombai.com/design/canvas
Every design you create in Kombai is stored in a Canvas. It is where you interact with your designs, iterate on them, and access the rest of the Design Mode features.
## Open a Canvas
There are two ways to open a Canvas in Design Mode:
* **Prompt Kombai directly:** Ensure Design pill is selected in the chat input and describe what you want to build. Kombai will generate the design in a Canvas and open it automatically.
* **Create one manually:** Click the **Designs** button below the chat input to go to the Canvas Gallery page. Click **Create a new Canvas**, select a folder, enter a name for the canvas, and click the **Create** button.
## Canvas Gallery
The Canvas Gallery page is the central hub for managing all your designs. It shows all your canvases as cards.
To open the Canvas Gallery, click the **Designs** button below the chat input. From there, click **Create a new Canvas** to start a new one, or click a canvas card to open an existing one.
## Organize canvases with folders
Canvases can live in folders to keep large projects tidy. These folders are created inside your project directory, so your canvas organization is reflected in your repo as well.
### Create a canvas in a folder
1. Open the Canvas Gallery and click **Create a new Canvas**.
2. In the dialog, click the **Folder** field to pick an existing folder, or type a new folder path to create the folder inline.
3. Enter a **Name** and click **Create**.
### Browse canvases by folder
If **All Canvases** is selected in the top folder dropdown in the Canvas Gallery, the page lists all your canvases as cards.
To filter the list to a specific folder, click the top folder dropdown on the Canvas Gallery page and select a specific folder. The list will update to show only canvases in that folder.
### Move or rename a canvas
* **From the gallery:** open the canvas card's **⋮** menu and choose **Move to folder** or **Rename**. Moves apply immediately and can be undone from the confirmation toast.
* **From the canvas editor:** use the folder path in the breadcrumb bar to move or rename the canvas you have open.
## Canvas toolbars
The Canvas has a **bottom toolbar**, a **top toolbar**, and a **zoom bar**. The bottom toolbar is always visible, floating at the bottom center of the Canvas. The top toolbar appears at the top center when you select a design. The zoom bar floats at the bottom right.
### Bottom toolbar
The bottom toolbar gives you access to Canvas navigation tools and the core Design Mode features.
| Icon | Action | Shortcut |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| / | **Select** to interact with designs on the Canvas (default), or **Pan** to click and drag around the infinite Canvas. A single merged control — click the caret to switch modes. | V / H |
| | Snip a portion of the design and attach it to the chat window. | S |
| | Select any element in a design and adjust it in the [design editor](./editor) panel. | E |
| | Add a text node to the Canvas for annotations, labels, or notes. | T |
| | Add comments on your designs. Use comments to leave feedback or notes for yourself or your team. | C |
### Top toolbar
The top toolbar appears when you select a design. It provides four actions: **Open in browser**, **Add to context**, **Generate**, and **Code design** (a **Code element** button replaces **Code design** when an element inside the design is selected). When space is limited, some actions collapse into an overflow menu.
Opens the selected design in your browser, sized to the viewport that best matches the design's width (mobile, tablet, or desktop).
Attaches the selected design to the chat window as context. This is useful when you want to reference the design in a prompt without generating code immediately.
It provides options to generate Versions or Variants, or regenerate the entire design:
* **Generate Versions:** Generates Versions based on the selected device, breakpoint, and mode.
* **Generate Variants:** Generates a new Variant of the selected design. Hover over the categories to pick a preset, or choose **Surprise Me**.
* **Regenerate Design:** Regenerates the selected design.
Attaches the selected design to the chat input and sends a prompt to the agent to generate code for it.
### Zoom bar
| Icon | Action |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Zoom | Click to see various zoom options for the designs. |
| | Open the **Collaborate on design** modal to share your canvas and Design Systems with your team. See [Collaboration](/design/collaboration) for details. |
| / | Toggle where the Canvas is displayed. Shows **Open in editor** () when viewing in the browser, or **Open in browser** () when viewing in the IDE. |
| | Open the help docs. |
## Attach Canvas and Designs in chat
You can attach an entire Canvas or individual designs to the Kombai chat as context for code generation or design questions.
**Attach a Canvas:**
1. Type `@Canvas` in the chat input.
2. Select the Canvas you want to attach.
3. Write your prompt and send.
**Attach a Design:**
1. Type `@Designs` in the chat input.
2. Select the individual design you want to attach.
3. Write your prompt and send.
## Right-click menu options
### Right-click on a design
Here are the options you see when you right-click on a design within the Canvas:
| Option | Shortcut | Description |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Add to context | | Attach the selected design to the chat window as context. |
| Focus | ⇧2 | Bring the selected design into focus on the Canvas. |
| Cut | ⌘X | Cut the selected design. |
| Copy | ⌘C | Copy the selected design. |
| Paste | ⌘V | Paste a copied design onto the Canvas. |
| Duplicate | ⌘D | Duplicate the selected design. |
| Delete | delete | Delete the selected design. |
| Viewport | | Resize the design to a preset or custom dimension. Opens a submenu with **Content Height** (full natural height), **Mobile** (375 × 812), **Tablet** (768 × 1024), **Desktop** (1440 × 800), and **Custom...** |
| Generate Versions | | Generate device- or mode-specific versions of the selected design. See [Generate Versions](#generate-versions). |
| Generate Variants | | Generate a new variant of the selected design by targeting specific aspects for improvement. See [Generate Variants](#generate-variants). |
| Regenerate design | | Regenerate the selected design from scratch using the same original prompt. |
| Edit | | Opens a submenu with **Edit Design**, which activates the Edit tool to adjust the design in the [design editor](./editor) panel. |
| Open in browser | | Opens a submenu with **Open** (opens the design in the browser) and **Copy Link** (copies a shareable link to the design). |
| Export | | Opens a submenu with **Copy as PNG**, **Copy as HTML**, **Save as PNG**, and **Save as HTML**. |
| Apply | | Opens an **Apply** submenu listing your saved Design Systems. Select one to regenerate the design using its tokens. |
| Select element | | Enter element selection mode to select an individual element within the design. |
### Right-click on an element
When you select a specific element within a design using the **Edit** tool, right-clicking on it shows the following options:
| Option | Description |
| ---------------------- | --------------------------------------------------------------- |
| Add element to context | Attach only the selected element to the chat window as context. |
| Generate Image | Generate an AI image for the selected element. |
| Generate Video | Generate an AI video for the selected element. |
### Right-click on an empty area
Here are the options you see when you right-click on an empty area of the Canvas:
| Option | Shortcut | Description |
| -------------- | -------- | ------------------------------------------------------------------------ |
| Paste | ⌘V | Paste a copied design onto the Canvas. |
| Import designs | | Import one or more `.html` files from disk as new designs on the Canvas. |
| Zoom in | | Zoom into the Canvas. |
| Zoom out | | Zoom out of the Canvas. |
| Focus | ⇧2 | Bring the selected design into focus on the Canvas. |
## Generate Versions vs Generate Variants
Both options create new designs from an existing one, but they serve different purposes.
| | Generate Versions | Generate Variants |
| ----------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Purpose** | Adapt a design to a different device size or color mode | Explore a different direction for the same design |
| **What changes** | Viewport width or light/dark mode | Visual style, layout, interactions, responsiveness, or custom aspects |
| **What stays the same** | Content and overall design intent | The core design intent and prompt |
| **When to use** | You need a mobile, tablet, or dark mode version of a finished design | You want to iterate on or improve an existing design |
| **Output** | A version optimized for the selected device and mode | One or more variant designs based on the selected improvement category |
## Generate Versions
You can ask Kombai to create device-specific and dark/light mode versions of a design using the **Generate Versions** option in the top toolbar or from the right-click menu on a design.
Choose a target device breakpoint for the version.
| Device | Width |
| ------ | ------------------------------- |
| Mobile | 390 px |
| Tablet | 768 px |
| Laptop | 1280 px |
| Custom | Enter a custom width in pixels. |
Choose **Light** or **Dark** mode for the version.
Click **Generate Version** to create the version.
## Generate Variants
Generate Variants lets you create new variants of a selected design by targeting specific aspects for improvement.
Click on the design on the Canvas you want to create a variant of.
Click the **Generate** dropdown in the top toolbar and hover over **Generate
Variants** to see the pre-defined categories of presets for variants.
Choose a category and sub-option. Kombai sends a prompt to the agent along
with your selected design and generates the variant.
The pre-defined categories for variants and their sub-options are described below:
### Improve styles
Refine the visual appearance of your design.
| Option | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------ |
| **Surprise me** | Let Kombai choose a style improvement automatically. |
| **Suggest a style direction** | Get a new overall style direction for the design. |
| **Soften** | Make the design softer with gentler colors, rounded edges, and lighter contrasts. |
| **Intensify** | Make the design bolder with stronger colors, sharper contrasts, and heavier visual weight. |
| **Pop colors** | Increase color vibrancy and saturation across the design. |
| **Add depth** | Introduce shadows, layering, and dimension to create a more three-dimensional feel. |
| **Improve typography** | Enhance font choices, sizing, spacing, and typographic hierarchy. |
### Improve structure
Adjust the layout and spatial organization of your design.
| Option | Description |
| -------------------- | ----------------------------------------------------------------------------------- |
| **Surprise me** | Let Kombai choose a structural improvement automatically. |
| **Rearrange layout** | Reorganize how sections and elements are positioned on the page. |
| **Simplify** | Reduce visual clutter by removing unnecessary elements and streamlining the layout. |
| **Enrich** | Add more content and detail to make the design more comprehensive. |
| **Fix hierarchy** | Improve the visual hierarchy so the most important elements stand out clearly. |
| **Adjust density** | Change how tightly or loosely elements are spaced across the design. |
### Improve interactions
Add or enhance motion and interactive elements.
| Option | Description |
| ---------------- | --------------------------------------------------------------- |
| **All aspects** | Improve all interactive aspects of the design at once. |
| **Animations** | Add or refine animations and transitions throughout the design. |
| **Add sparkles** | Add subtle decorative micro-interactions and sparkle effects. |
### Improve responsiveness
Optimize the design for different screen sizes.
| Option | Description |
| ----------------- | ----------------------------------------------- |
| **All aspects** | Improve responsiveness across all device sizes. |
| **Mobile** | Optimize the design for mobile screens. |
| **Tablet** | Optimize the design for tablet screens. |
| **Large screens** | Optimize the design for large desktop screens. |
### Surprise Me
Below the preset categories, the **Surprise Me** option lets Kombai pick an improvement direction for the design on its own and generate a variant based on it.
## Regenerate design
Regenerates the selected design from scratch using the same original prompt. Use this when you want a completely fresh take on the design rather than an incremental improvement. Select a design, click the **Generate** dropdown in the top toolbar, and click **Regenerate design**.
## FAQs
If Kombai has generated the designs but they are not appearing on the Canvas, please reopen the current Canvas tab in your IDE.
You can reopen it in either of these ways:
1. Click the `.canvas` file directly in your repository.
2. Open the **Canvas Gallery** in Kombai and select your Canvas.
If the issue persists, please reach out to [support@kombai.com](mailto:support@kombai.com).
# Collaboration
Source: https://docs.kombai.com/design/collaboration
Design Mode stores all of its artifacts as files: [Canvases](./canvas) live as `.canvas` files inside the `.kombai/canvas/` folder at the root of your project, and [Design Systems](./design-system/overview) live as `.ds` files in your user-wide Kombai library. Because Canvases are files in your project, you can collaborate on designs using the same tools and workflows you already use for code.
To quickly access sharing options, click the icon in the [Canvas zoom bar](./canvas#zoom-bar) to open the **Collaborate on design** modal. The modal features tabs (**Entire Canvas**, **Design**, and **Design System**), each with specific sharing instructions.
## Comments
Use comments to leave feedback, ask questions, or add notes directly to your designs. Click the icon in the [Canvas bottom toolbar](./canvas#bottom-toolbar) to activate the comment tool, then click anywhere on a design to place a comment.
Comments are useful for:
* **Leaving design feedback**: Point out specific elements that need changes, suggest improvements, or approve sections.
* **Adding context for teammates**: Explain design decisions or flag areas that need attention before code generation.
* **Personal notes**: Bookmark parts of a design you want to revisit or iterate on later.
## Git as a collaboration system
Because every Canvas is a file on your disk, your existing Git workflow doubles as a design collaboration system. When you commit and push your `.kombai/` folder, your entire team gets access to the same Canvases.
Design Systems are stored in your user-wide Kombai library (`~/.kombai/design-systems/`), not in the project, so they are not shared by committing the `.kombai/` folder. See [Sharing Design Systems](#sharing-design-systems) below for how to share them.
### Recommended workflow
1. **Create a branch** for your design work, just like you would for a feature.
2. **Design on the Canvas** as you go.
3. **Commit and push** the `.kombai/` folder changes (including `.canvas` files in `.kombai/canvas/`).
4. **Open a pull request** so your team can review the design files alongside any code changes.
5. **Merge to main** once approved, making the designs available to everyone.
This keeps your design artifacts in sync with your codebase and gives you the full benefits of Git—branching, history, diffs, and code reviews—for your design work.
## Sharing individual artifacts
Since all Design Mode artifacts live as files on disk, you can share specific files directly with a teammate without going through a full Git workflow. This is especially useful for quick, informal collaboration.
### Sharing an entire Canvas
**Via Git:**
Commit your `.canvas` file from `.kombai/canvas/` to your repository. Anyone on your team who pulls the repository will have access to the Canvas, including all designs stored within it.
**Manually:**
1. Locate your Canvas file inside `.kombai/canvas/`.
2. Send the `.canvas` file to your teammate through any channel (e.g., Slack, email, or a shared drive).
3. Your teammate saves the file under `.kombai/canvas/` in their local project.
4. They can now open and use the shared Canvas in their Design Mode session.
**Important:** Sharing a Canvas does not include Design Systems. Design Systems are stored separately and must be shared using the steps in the Design Systems section below.
### Sharing individual designs
Designs live inside your Canvas. To share them, you need to share the Canvas they belong to:
1. **Share the entire Canvas**: Follow the steps in the [Sharing an entire Canvas](#sharing-an-entire-canvas) section above.
2. **Share only select designs**: Copy the specific designs to a new Canvas first. Then, share that new Canvas using the steps in the [Sharing an entire Canvas](#sharing-an-entire-canvas) section.
### Sharing Design Systems
Design Systems live in your user-wide Kombai library at `~/.kombai/design-systems/`, so they can't be shared by committing project files. Instead:
1. Locate the `.ds` file for your Design System inside `~/.kombai/design-systems/`.
2. Send the file to your teammate through any channel (e.g., Slack, email, or a shared drive).
3. Your teammate saves the file under `~/.kombai/design-systems/` in their own library — or anywhere inside their project, where Kombai will discover it automatically.
4. They can now use the shared Design System in their Design Mode session.
## Sharing examples
* **Two designers collaborating on a page**: One person designs the hero section and commits the `.canvas` file to a branch. The other person pulls the branch, opens the Canvas, adds the features section, and commits the updated file back.
* **Sharing a Design System across projects**: Design Systems are shared across your projects automatically — the library at `~/.kombai/design-systems/` is user-wide, so a Design System you create is available in every project on your machine.
* **Sharing design direction**: Your design system team creates a Design System and sends the `.ds` file to the team. Everyone saves it to their own library and uses it as a template for generating new designs.
This file-based approach ensures there's no lock-in to a specific design tool or platform—your design assets are portable, versioned, and always accessible.
# Design Settings
Source: https://docs.kombai.com/design/design-settings
Design Settings give you control over how thoroughly Kombai explores and refines designs during generation.
## Variants
Variants determine how many independent design options Kombai generates in a single prompt. Instead of producing one result, Kombai creates multiple versions. Each version takes a different visual direction, so you can compare and pick the one that fits best.
You can set the number of Variants to **1**, **2**, or **3**.
## Passes
Passes determine how many times Kombai iterates on and refines each generated design. On each Pass, Kombai reviews and improves the previous result — tightening spacing, improving visual hierarchy, and making the design more polished.
You can set the number of Passes to **1**, **2**, or **3**. When multiple Passes are selected, only the final result is shown.
## Configure Design Settings
Both settings are accessible from the chat box.
1. In the chat box, click the button to open the Design Settings popover.
2. Open the **Variations** dropdown and select **1**, **2**, or **3**.
3. Open the **Passes** dropdown and select **1**, **2**, or **3**.
# Create a Design System
Source: https://docs.kombai.com/design/design-system/create
There are five ways to create a Design System, all available from the **+ Create** button on the **My design systems** tab of the [Design System Gallery](./overview#design-system-gallery). Whichever method you choose, clicking the final button in the modal sends a prompt to the agent, which generates the Design System and saves it as a `.ds` file in your project.
Use this to extract a Design System directly from an existing codebase on disk, its CSS, Tailwind config, and other design tokens.
1. Click **+ Create** and select **Import from codebase**.
2. In the **Import from codebase** modal, enter the **Codebase path** or click **Browse** to select a folder.
3. Enter a **Name** for the Design System, and optionally add **Notes** describing anything specific it should focus on.
4. Click **Generate**.
Use this to extract a Design System from one or more Figma files.
1. Click **+ Create** and select **Import from Figma design**.
2. In the **Import from Figma design** modal, paste one or more **Figma URLs** (comma-separate multiple files).
3. Enter a **Name**, and optionally add **Notes**.
4. Click **Generate**.
Use this when you already have a `Design.md` file describing your design language.
1. Click **+ Create** and select **Import from Design.md**.
2. In the **Import from Design.md** modal, paste the contents of your `Design.md` file into the **Design.md contents** field.
3. Enter a **Name**.
4. Click **Create**.
Use this to extract a Design System from an existing design saved on one of your Canvases.
1. Click **+ Create** and select **Import from Kombai design**.
2. In the **Import from Kombai design** modal, select a **Canvas** from the dropdown. Click **+ Add project** if the project you want isn't listed yet.
3. Select the **Design** you want to extract the Design System from.
4. Enter a **Name**, and optionally add **Notes**.
5. Click **Generate**.
Use this to extract a Design System from a live website.
1. Click **+ Create** and select **Import from URL**.
2. In the **Import from URL** modal, paste the **Website URL**.
3. Enter a **Name**, and optionally add **Notes**.
4. Click **Generate**.
You can also ask Kombai to generate a Design System directly via chat, for example by pasting a website or Figma URL and asking it to extract the Design System from it.
# Manage a Design System
Source: https://docs.kombai.com/design/design-system/manage
Once a Design System is created, you can edit its tokens, apply it to designs, attach it to the chat as context, or delete it.
## Edit a Design System
You edit a Design System by editing its underlying `.ds` file — Markdown with a YAML front-matter block — directly from its detail page.
1. Open the Design System's detail page and click **Edit**.
2. The source editor opens alongside a live preview, so you can edit any token or prose section directly and see the result.
3. Click **Save** to apply the changes, or **Cancel** to discard them.
## Apply a Design System
Applying a Design System regenerates the selected design using its tokens, while preserving the original layout and content.
1. Select the design on the Canvas you want to apply the Design System to.
2. Right-click the selection to open the context menu. Under the **Design System** section, open the **Apply** submenu.
3. Select the Design System you want. Kombai sends a prompt to the agent to regenerate the selected design using the Design System's tokens.
The [Design System Gallery](./overview#design-system-gallery) is where you browse and manage your systems — applying a system to a design is done from the Canvas context menu above.
## Attach a Design System in chat
To attach a Design System to the chat as context:
1. Ensure Design pill is turned on in the chat input box.
2. Click the icon in the chat input to open the **Design System** popover.
3. Select the Design System you want to attach to the chat as context.
## Delete a Design System
Deleting a Design System is permanent and cannot be undone.
1. Open the [Design System Gallery](./overview#design-system-gallery) and switch to the **My design systems** tab.
2. On the row or card for the Design System you want to delete, open the menu.
3. Select **Delete**.
# Overview
Source: https://docs.kombai.com/design/design-system/overview
A Design System captures a project's full visual identity — palette, typography, spacing, elevation, and more — so Kombai can generate and code designs that are consistent with it.
A Design System is a structured, file-based spec of a product's visual language. Instead of managing separate color palettes, type scales, and freeform style notes, a Design System brings every layer of a visual identity together, from brand colors and typography down to spacing, elevation, grids, and usage guidelines, in a single artifact that Kombai can read, edit, and apply consistently across your designs and code.
Kombai can generate a Design System from an existing codebase, a Figma file, a `Design.md` file, a design on your Canvas, or a live website. Every Design System is stored as a `.ds` file in your user-wide Kombai library at `~/.kombai/design-systems/`, so it is available across all your projects. A `.ds` file placed anywhere inside a project is also discovered automatically. A `.ds` file is Markdown with a YAML front-matter block — the front matter holds the structured tokens, and the Markdown body holds the prose guidance.
## Design System structure
A Design System has two layers: a YAML **front matter** block holding the structured tokens, and a Markdown **body** holding prose guidance organized into sections.
The front matter holds the hard data: the color palette and its semantic roles (e.g. `background.canvas`, `text.primary`, `border.focus`), gradients, font families and text styles, spacing, radius, shadows and elevation levels, border widths and styles, opacity levels, motion durations and easings, breakpoints, component specs, asset patterns, icon glyphs, and motion patterns.
The body is organized into the following sections. Click each to see what it covers.
How to apply the system when building UI — which token to reach for, usage and scarcity constraints, and the system's voice.
Usage of each brand and accent color in the palette.
Usage of each surface and background color across pages, cards, and containers.
Usage of each text color — headings, body copy, secondary text, and links.
Usage of status, overlay, and semantic colors (success, warning, error, info) for badges, links, and highlights.
Font families and what each carries, type principles, and recommended substitutes.
Max content width, grid columns, gutters, and whitespace philosophy.
Per-component collapsing rules across breakpoints — nav, hero, grids, footer, and touch targets.
Radius-scale usage plus photography and illustration geometry.
The imagery and media narrative, including generation prompts for reusable assets.
Icon style and usage narrative; the icon glyphs themselves live in the front matter.
A one-line usage note per component covered by the Design System.
The motion narrative — signature transitions and any JS-, video-, or canvas-driven motion that can't be expressed as CSS tokens.
Recommended practices for applying the Design System.
Anti-patterns to avoid, e.g. color pairings or spacing rules that break the system.
Distinctive, system-specific details: signature components, brand gradients, color-block patterns, and decorative depth.
Catch-all for actionable caveats, known gaps, and edge cases that don't fit another section.
## Design System Gallery
The Design System Gallery is where you browse, create, and manage Design Systems. It has two tabs:
* **Public design systems:** A curated library of Design Systems extracted from popular, real-world products (e.g. Discord, Stripe, Nike). Use the category filters at the top (for example **AI & LLM**, **Fintech**, or **Ecommerce**) to narrow down the list, or use **My design systems** to build your own.
* **My design systems:** All the Design Systems you've created or imported into your workspace. Each row shows the Design System's name, its color palette, its typography, and when it was last modified.
## View a Design System
Click on a Design System card or row to open its detail page. The detail page shows:
* The Design System's **name**, **slug**, and an AI-generated description summarizing its overall visual identity.
* The sections listed in [Design System structure](#design-system-structure), with the individual tokens shown as cards, each with a swatch or value, its token name, and its raw value (e.g. a hex code). Click the copy icon on any card to copy its value. Click **Edit** to edit the raw Markdown source of the `.ds` file directly.
See [Create a Design System](./create) for the different ways to generate one, and [Manage a Design System](./manage) for how to edit, apply, attach, and delete one.
# Edit Designs
Source: https://docs.kombai.com/design/editor
The design editor is a full visual editor built into the Canvas. It works like a standard design tool: select any element in a design, adjust its styles through visual controls, edit text and raw CSS/HTML directly, rearrange layers, and draw new shapes and freehand sketches, all without sending a prompt to the agent.
## Open the editor
1. Click the **Edit** tool in the bottom toolbar of the Canvas.
2. Click on the design you want to edit.
You can also right-click a design and select **Edit** > **Edit Design** to start editing it.
Click **Save** on top of the editor to save your changes, or **Discard** to revert. You can also visit the specific states of your design changes using the **Undo** and **Redo** icons before **Back to chat**.
## The editor panel
The panel has three parts: the **Layers** tree at the top, the **insert tools**, and the **property tabs** that populate when you select an element.
### Layers
The Layers tree shows every element in the design in nesting order. Each row is labeled with a friendly name and its underlying HTML tag (for example `nav`, `ul`, `li`, `section`, `video`, `div`, `span`).
* Click a layer to select it and load its properties into the property tabs.
* **Cmd/Ctrl-click** to add or remove layers from a multi-selection, or **Shift-click** to select a range. With two or more layers selected, the Layers title bar becomes a batch toolbar with **Wrap in container**, **Hide/Show**, and **Delete**.
* **Drag a layer** in the tree to reorder it or move it into another container.
* Double-click a text element on the Canvas to edit its content inline.
* Hover a layer to reveal the visibility toggle and the **⋯** menu (**Wrap**, **Unwrap**, **Copy**, and **Delete**).
Keyboard shortcuts when a layer is selected:
* **Arrow keys:** move the selection up and down, and expand or collapse a layer.
* **Delete / Backspace:** delete the selected layer or layers.
* **Cmd/Ctrl + C / V:** copy and paste an element. You can paste it into another design in the same session.
* **Cmd/Ctrl + Z** and **Shift + Cmd/Ctrl + Z:** undo and redo.
### Insert tools
The insert tools let you add new content to the Canvas. Select a tool, then click or drag on the Canvas to place it.
| Tool | Icon | What it adds |
| --------- | -------------------- | ----------------------------------------------------------- |
| Select | | Return to selecting and moving existing elements (default). |
| Text | | A text node. |
| Rectangle | | A rectangle shape. |
| Circle | | A circle or ellipse shape. |
| Arrow | | An arrow. |
| Line | | A straight line. |
| Free draw | | A freehand sketch, captured as an SVG path. |
See [Add shapes and drawings](#add-shapes-and-drawings) for how these behave on an empty Canvas versus inside an existing design.
### Property tabs
When an element is selected, the panel shows tabs for editing it:
* **Styles:** visual controls for the element's CSS. See [Styles](#styles).
* **Element:** element-specific properties. The tab and its contents adapt to the selected element's type (for example, a **Video** tab for `