Skip to main content
Preview mode overview showing component selection and hierarchy

​
Overview

Preview Mode provides an embedded browser experience within Vibe Kanban, allowing you to test and iterate on your web applications without leaving the development environment. This feature eliminates the need to switch between your browser and Vibe Kanban by providing live preview capabilities and precise component selection tools. Key Benefits:
  • Embedded viewing: See your application running directly in Vibe Kanban
  • Precise component selection: Click to select specific UI components for targeted feedback
  • Seamless workflows: No context switching between tools

​
Prerequisites

Before using Preview Mode, ensure you have:
  1. Development server script configured for your project
  2. Web Companion installed in your application (for component selection)
  3. Project running a web application that serves to localhost

​
Setting Up Preview Mode

1

Configure Development Server Script

Navigate to your project settings and configure the development server script that starts your local development environment.Common examples:
  • npm run dev (Vite, Next.js)
  • npm start (Create React App)
  • yarn dev (Yarn projects)
  • pnpm dev (PNPM projects)
Development server script configuration interface
Ensure your development server prints the URL (e.g., http://localhost:3000) to stdout/stderr for automatic detection.
2

Install Web Companion

For precise component selection, install the vibe-kanban-web-companion package in your application.
Recommended: Use the “Install companion automatically” button in the Preview tab to have Vibe Kanban create a task that installs and configures the companion for you.
Install companion automatically button in Preview tab
Manual Installation:Add the dependency to your project:
npm install vibe-kanban-web-companion
Then add the companion to your application:
  • Create React App
  • Next.js
  • Vite
Add to your src/index.js or src/index.tsx:
import { VibeKanbanWebCompanion } from 'vibe-kanban-web-companion';
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <VibeKanbanWebCompanion />
    <App />
  </React.StrictMode>
);
The Web Companion is automatically tree-shaken from production builds, so it only runs in development mode.
3

Start Development Server

In your task’s full screen mode, click the Dev button (▶️) to start your development server.
Starting development server from task interface
The system will:
  • Launch your configured development script
  • Monitor the output for URL detection

​
Using Preview Mode

​
Accessing the Preview

Once your development server is running and a URL is detected:
  1. Navigate to Preview tab in the task details panel
  2. View embedded application in the iframe
  3. Interact with your app directly within Vibe Kanban
Preview mode showing embedded application with toolbar controls

​
Preview Toolbar Controls

The preview toolbar provides essential controls for managing your preview experience:
Preview toolbar showing refresh, copy URL, and open in browser controls
  • Refresh: Reload the preview iframe
  • Copy URL: Copy the development server URL to clipboard
  • Open in Browser: Open the application in your default browser

​
Component Selection

When the Web Companion is installed, you can precisely select UI components for targeted feedback:
1

Activate Selection Mode

Click the floating Vibe Kanban companion button in the bottom-right corner of your application to activate component selection mode.
Component selection interface showing selectable elements highlighted
2

Choose Component Depth

When you click a component, Vibe Kanban shows a hierarchy of components from innermost to outermost. Select the appropriate level for your feedback:
  • Inner components: For specific UI elements (buttons, inputs)
  • Outer components: For broader sections (cards, layouts)
Component depth selection showing hierarchy of selectable components
3

Provide Targeted Feedback

After selecting a component, write your follow-up message. The coding agent will receive:
  • Precise DOM selector information
  • Component hierarchy and source file locations
  • Your specific instructions about what to change
No need to describe “the button in the top right” - the agent knows exactly which component you mean!

​
Troubleshooting

If the preview doesn’t load automatically, ensure your development server prints the URL to stdout/stderr for automatic detection. Supported URL formats:
  • http://localhost:3000
  • https://localhost:3000
  • http://127.0.0.1:3000
  • http://0.0.0.0:5173
URLs using 0.0.0.0 or :: are automatically converted to localhost for embedding.
⌘I