diff --git a/docs/core-features/creating-projects.mdx b/docs/core-features/creating-projects.mdx index 38c26bcc..fe70e61b 100644 --- a/docs/core-features/creating-projects.mdx +++ b/docs/core-features/creating-projects.mdx @@ -36,6 +36,11 @@ Each time a coding agent is executed it runs in a [git worktree](https://git-scm The dev server script is run whenever you press the "run dev server" button. It's useful for quickly reviewing work after a coding agent has run. +### Cleanup Scripts + +Cleanup scripts run after a coding agent finishes it's turn. You can use these to tidy up the workspace, remove temporary files, or perform any post-execution cleanup. For example, you might run `npm run format` to ensure your code is formatted correctly. Treat it like a pre-commit hook in git. + + ### Copy Files Comma-separated list of files to copy from the original project directory to the worktree. These files will be copied after the worktree is created but before the setup script runs. Useful for environment-specific files like `.env`, configuration files, and local settings. @@ -47,11 +52,3 @@ Make sure these files are gitignored or they could get committed! ### Project Task Templates From project settings, you can also configure project-specific task templates. For more details about this feature, see the [project task templates section](/configuration-customisation/creating-task-templates#project-task-templates). - -### Cleanup Scripts - -Cleanup scripts run after a coding agent finishes. You can use these to tidy up the workspace, remove temporary files, or perform any post-execution cleanup. For example, you might run: - -```bash -npm run clean -``` diff --git a/docs/core-features/preview-mode.mdx b/docs/core-features/preview-mode.mdx new file mode 100644 index 00000000..8876810f --- /dev/null +++ b/docs/core-features/preview-mode.mdx @@ -0,0 +1,221 @@ +--- +title: "Preview Mode" +description: "Live preview your web applications with embedded browser viewing and precise component selection for seamless development workflows" +--- + + +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 + + + + 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. + + + + + 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: + ```bash + npm install vibe-kanban-web-companion + ``` + + Then add the companion to your application: + + + + Add to your `src/index.js` or `src/index.tsx`: + ```jsx + 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( + + + + + ); + ``` + + + + Add to your `pages/_app.js` or `pages/_app.tsx`: + ```jsx + import { VibeKanbanWebCompanion } from 'vibe-kanban-web-companion' + import type { AppProps } from 'next/app' + + function MyApp({ Component, pageProps }: AppProps) { + return ( + <> + + + + ) + } + ``` + + + + Add to your `src/main.jsx` or `src/main.tsx`: + ```jsx + import { VibeKanbanWebCompanion } from "vibe-kanban-web-companion"; + import React from "react"; + import ReactDOM from "react-dom/client"; + import App from "./App"; + + ReactDOM.createRoot(document.getElementById("root")).render( + + + + + ); + ``` + + + + + The Web Companion is automatically tree-shaken from production builds, so it only runs in development mode. + + + + + 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: + + + + 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 + + + + + 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 + + + + + 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. + + +## Related Documentation + +- [Task Details Full Screen Mode](/core-features/task-details-full-screen) - Complete guide to full screen task management +- [Creating Task Attempts](/core-features/creating-task-attempts) - Learn about task attempt lifecycle +- [Reviewing Code Changes](/core-features/reviewing-code-changes) - Analyse and review code modifications +- [Configuration & Customisation](/configuration-customisation/global-settings) - Customise Vibe Kanban settings diff --git a/docs/core-features/task-details-full-screen.mdx b/docs/core-features/task-details-full-screen.mdx index b6f7ae61..b1cbfd81 100644 --- a/docs/core-features/task-details-full-screen.mdx +++ b/docs/core-features/task-details-full-screen.mdx @@ -19,11 +19,11 @@ Full screen mode uses a two-column layout: ### Left Sidebar - **Task Information**: Title, description, and metadata - **Development Toolbar**: Primary development actions -- **TODOs**: Task checklist and progress tracking +- **TODOs**: Task checklist and progress tracking - **Relationships**: Subtasks and parent task links ### Right Panel -- **Tab Navigation**: Switch between Logs, Diffs, and Processes +- **Tab Navigation**: Switch between Logs, Diffs, Processes, and Preview - **Content Area**: Active tab content with real-time updates - **Follow-up Section**: Additional context and actions @@ -95,7 +95,7 @@ The Logs tab provides real-time streaming of coding agent activities and reasoni Logs tab showing real-time streaming of agent output and process events -#### Diffs Tab +#### Diffs Tab The Diffs tab provides a visual representation of all code changes made during task execution. It shows a git diff between your branch and the base branch, with syntax highlighting and language-aware code formatting. You can see a summary of added, modified, and deleted files with precise line-by-line change tracking and context. @@ -111,6 +111,21 @@ The Processes tab displays a timeline view of all running and completed processe Processes tab showing timeline of running and completed processes with status tracking +#### Preview Tab +The Preview tab provides an embedded browser experience for testing web applications directly within Vibe Kanban. When you start a development server, the tab automatically detects the URL and displays your running application in an embedded iframe. This eliminates the need to switch between your browser and Vibe Kanban during development. + +**Key features:** +- **Embedded browser**: View your application running directly in the task interface +- **Automatic URL detection**: Automatically detects development server URLs from process logs +- **Component selection**: Use the Web Companion to select specific UI components for precise feedback +- **Preview toolbar**: Refresh the preview, copy the URL, or open in a new browser tab + + +Preview tab showing embedded web application with toolbar controls + + +For detailed setup instructions and usage guidance, see [Preview Mode](/core-features/preview-mode). + ## Navigation & Controls ### Keyboard Shortcuts @@ -130,8 +145,9 @@ The interface gracefully transitions back to the compact sidebar view while pres ## Related Documentation +- [Preview Mode](/core-features/preview-mode) - Embedded browser preview and component selection - [Creating Task Attempts](/core-features/creating-task-attempts) - Learn about task attempt lifecycle -- [Reviewing Code Changes](/core-features/reviewing-code-changes) - Deep dive into diff analysis +- [Reviewing Code Changes](/core-features/reviewing-code-changes) - Deep dive into diff analysis - [Resolving Rebase Conflicts](/core-features/resolving-rebase-conflicts) - Handle rebase conflicts and merge issues - [Creating Tasks](/core-features/creating-tasks) - Task creation and management - [Agent Configurations](/configuration-customisation/agent-configurations) - Customise AI agent behaviour diff --git a/docs/docs.json b/docs/docs.json index 4f0066d9..afba7d70 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -35,7 +35,8 @@ "core-features/creating-task-attempts", "core-features/reviewing-code-changes", "core-features/resolving-rebase-conflicts", - "core-features/task-details-full-screen" + "core-features/task-details-full-screen", + "core-features/preview-mode" ] }, { diff --git a/docs/images/preview-mode-component-depth.png b/docs/images/preview-mode-component-depth.png new file mode 100644 index 00000000..52576ede Binary files /dev/null and b/docs/images/preview-mode-component-depth.png differ diff --git a/docs/images/preview-mode-component-selection.png b/docs/images/preview-mode-component-selection.png new file mode 100644 index 00000000..f472bd62 Binary files /dev/null and b/docs/images/preview-mode-component-selection.png differ diff --git a/docs/images/preview-mode-dev-script-config.png b/docs/images/preview-mode-dev-script-config.png new file mode 100644 index 00000000..393a0532 Binary files /dev/null and b/docs/images/preview-mode-dev-script-config.png differ diff --git a/docs/images/preview-mode-dev-server-off.png b/docs/images/preview-mode-dev-server-off.png new file mode 100644 index 00000000..3cc0ff16 Binary files /dev/null and b/docs/images/preview-mode-dev-server-off.png differ diff --git a/docs/images/preview-mode-install-companion-button.png b/docs/images/preview-mode-install-companion-button.png new file mode 100644 index 00000000..63a15134 Binary files /dev/null and b/docs/images/preview-mode-install-companion-button.png differ diff --git a/docs/images/preview-mode-interface.png b/docs/images/preview-mode-interface.png new file mode 100644 index 00000000..46db2618 Binary files /dev/null and b/docs/images/preview-mode-interface.png differ diff --git a/docs/images/preview-mode-overview.png b/docs/images/preview-mode-overview.png new file mode 100644 index 00000000..264a15b7 Binary files /dev/null and b/docs/images/preview-mode-overview.png differ diff --git a/docs/images/preview-mode-start-dev-server.png b/docs/images/preview-mode-start-dev-server.png new file mode 100644 index 00000000..e9a1269c Binary files /dev/null and b/docs/images/preview-mode-start-dev-server.png differ diff --git a/docs/images/preview-mode-toolbar.png b/docs/images/preview-mode-toolbar.png new file mode 100644 index 00000000..1dee2501 Binary files /dev/null and b/docs/images/preview-mode-toolbar.png differ diff --git a/docs/integrations/vibe-kanban-mcp-server.mdx b/docs/integrations/vibe-kanban-mcp-server.mdx index 32b73c5d..f2c13b4f 100644 --- a/docs/integrations/vibe-kanban-mcp-server.mdx +++ b/docs/integrations/vibe-kanban-mcp-server.mdx @@ -35,30 +35,72 @@ This works if you're adding the Vibe Kanban MCP server to any [supported coding ### Option 2: Manual Configuration -You can manually add the MCP server to your coding agent's configuration. Add the following configuration to your agent's MCP servers configuration: +You can manually add the MCP server to your coding agent's configuration. The exact syntax will depend on your coding agent or MCP client. + +Add the following configuration to your agent's MCP servers configuration: ```json { "mcpServers": { "vibe_kanban": { "command": "npx", - "args": ["-y", "vibe-kanban", "--mcp"] + "args": ["-y", "vibe-kanban@latest", "--mcp"] } } } ``` -## Using MCP with Coding Agents +## Available MCP Tools -Once you have the MCP server configured, you can leverage it to streamline your project planning workflow: +The Vibe Kanban MCP server provides the following tools for managing projects, tasks, and task execution: -1. **Plan Your Work**: Describe a large feature or project to your coding agent +### Project Operations + +| Tool | Purpose | Required Parameters | Optional Parameters | Returns | +|------|---------|-------------------|-------------------|---------| +| `list_projects` | Fetch all projects | None | None | List of projects with metadata | + +### Task Management + +| Tool | Purpose | Required Parameters | Optional Parameters | Returns | +|------|---------|-------------------|-------------------|---------| +| `list_tasks` | List tasks in a project | `project_id` | `status`
`limit` | List of tasks with execution state | +| `create_task` | Create a new task | `project_id`
`title` | `description` | Created task ID and confirmation | +| `get_task` | Get task details | `task_id` | None | Full task information | +| `update_task` | Update task details | `task_id` | `title`
`description`
`status` | Updated task information | +| `delete_task` | Delete a task | `task_id` | None | Deletion confirmation | + +### Task Execution + +| Tool | Purpose | Required Parameters | Optional Parameters | Returns | +|------|---------|-------------------|-------------------|---------| +| `start_task_attempt` | Start working on a task with a coding agent | `task_id`
`executor`
`base_branch` | `variant` | Attempt ID and confirmation | + +### Supported Executors + +When using `start_task_attempt`, the following executors are supported (case-insensitive, accepts hyphens or underscores): + +- `claude-code` / `CLAUDE_CODE` +- `amp` / `AMP` +- `gemini` / `GEMINI` +- `codex` / `CODEX` +- `opencode` / `OPENCODE` +- `cursor` / `CURSOR` +- `qwen-code` / `QWEN_CODE` +- `copilot` / `COPILOT` + +## Using the MCP Server + +Once you have the MCP server configured, you can leverage it to streamline your project planning and execution workflow: + +1. **Plan Your Work**: Describe a large feature or project to your MCP client 2. **Request Task Creation**: At the end of your task description, simply add "then turn this plan into tasks" -3. **Automatic Task Generation**: Your coding agent will use the Vibe Kanban MCP server to automatically create structured tasks in your project +3. **Automatic Task Generation**: Your MCP client will use the Vibe Kanban MCP server to automatically create structured tasks in your project +4. **Start Task Execution**: Use `start_task_attempt` to programmatically begin work on tasks with specific coding agents ## Example Usage -### External Coding Agents +### Planning and Task Creation ``` I need to build a user authentication system with the following features: @@ -71,15 +113,45 @@ I need to build a user authentication system with the following features: Then turn this plan into tasks. ``` -The coding agent will break this down into individual tasks and add them to your Vibe Kanban project automatically. +Your MCP client will use the `create_task` tool to break this down into individual tasks and add them to your Vibe Kanban project automatically. + +### Starting Task Execution + +After tasks are created, you can start work on them programmatically: + +``` +Start working on the user registration task using Claude Code on the main branch. +``` + +Your MCP client will use the `start_task_attempt` tool with parameters like: +```json +{ + "task_id": "123e4567-e89b-12d3-a456-426614174000", + "executor": "claude-code", + "base_branch": "main" +} +``` + +This creates a new task attempt, generates a feature branch, and starts the coding agent in an isolated environment. + +### Complete Workflow Example + +``` +1. List all projects to find the project ID +2. List todo tasks in the project +3. Create a new task for "Add user profile page" +4. Start a task attempt for the new task using Amp on the develop branch +``` + +Each step uses the appropriate MCP tool (`list_projects`, `list_tasks`, `create_task`, `start_task_attempt`) to manage the complete workflow from planning to execution. ### Internal Coding Agents (Within Vibe Kanban) A powerful workflow involves using coding agents within Vibe Kanban that are also connected to the Vibe Kanban MCP server: -1. **Create a Planning Task**: Create a task in "plan mode" within Vibe Kanban +1. **Create a Planning Task**: Create a task with a custom agent profile configured with a planning prompt. See [Agent Configurations](/configuration-customisation/agent-configurations) for details on creating custom profiles. 2. **Explore and Plan**: The coding agent explores the codebase and develops a comprehensive plan -3. **Generate Sub-Tasks**: Ask the coding agent to "create a series of individual tasks for this plan" +3. **Generate Tasks**: Ask the coding agent to "create a series of individual tasks for this plan" 4. **Automatic Population**: The agent uses the MCP server to populate individual tasks directly in the Vibe Kanban interface This creates a seamless workflow where high-level planning automatically generates actionable tasks in your project board. diff --git a/docs/supported-coding-agents.mdx b/docs/supported-coding-agents.mdx index 234d9722..ff93c4c0 100644 --- a/docs/supported-coding-agents.mdx +++ b/docs/supported-coding-agents.mdx @@ -7,6 +7,28 @@ Vibe Kanban integrates with a variety of coding agents. These agents are availab + +**Anthropic's Claude Code** + +## Installation +Claude Code is now available via npx - no separate installation required! + +## Authentication +You need to authenticate with Claude Code outside of Vibe Kanban before using it. Please follow the authentication instructions on the [Claude Code GitHub page](https://github.com/anthropics/claude-code). + + + +**OpenAI Codex integration** + +## Installation +OpenAI Codex is now available via `npx` - no separate installation required! + +## Authentication +You need to authenticate with OpenAI Codex outside of Vibe Kanban before using it. Please follow the authentication instructions from the [OpenAI help center](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan) to use Codex with your ChatGPT plan. + +Alternatively, Codex can be used via the OpenAI API by setting the `OPENAI_API_KEY` environment variable. For more details, see the [OpenAI documentation](https://developers.openai.com/codex/pricing/#use-an-openai-api-key) + + **Amp code completion agent** @@ -17,14 +39,23 @@ Amp is now available via npx - no separate installation required! You need to authenticate with Amp outside of Vibe Kanban before using it. Please follow the authentication instructions on the [Amp Owner's Manual](https://ampcode.com/manual#install). - -**Anthropic's Claude Code** + +**GitHub Copilot CLI** ## Installation -Claude Code is now available via npx - no separate installation required! +GitHub Copilot CLI is available via npm. Install it globally: + +```bash +npm install -g @github/copilot +``` + +## Prerequisites +- A GitHub Copilot subscription +- Node.js version 22 or later +- npm version 10 or later ## Authentication -You need to authenticate with Claude Code outside of Vibe Kanban before using it. Please follow the authentication instructions on the [Claude Code GitHub page](https://github.com/anthropics/claude-code). +When you first start Copilot CLI, you'll be prompted to authenticate. Follow the on-screen instructions to log in to your GitHub account using the `/login` command. For more details, see the [GitHub Copilot CLI documentation](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli). @@ -135,15 +166,7 @@ When creating a Task Attempt, select the coding agent and configuration: choose - Missing features (webSearch/think/image): switch to a model that supports the capability and update your CCR mapping (via UI or JSON config). - -**OpenAI Codex integration** -## Installation -OpenAI Codex is now available via `npx` - no separate installation required! - -## Authentication -You need to configure your OpenAI API credentials before using Codex. Please set the `OPENAI_API_KEY` environment variable. For more details, see the [OpenAI documentation](https://platform.openai.com/docs/guides/code). - **Google Gemini CLI** @@ -155,14 +178,14 @@ Gemini CLI is now available via npx - no separate installation required! You need to authenticate with Gemini CLI outside of Vibe Kanban before using it. Please follow the authentication instructions on the [Gemini CLI GitHub page](https://github.com/google-gemini/gemini-cli). - + **SST's OpenCode** ## Installation -SST OpenCode is now available via `npx` - no separate installation required! +OpenCode is now available via `npx` - no separate installation required! ## Authentication -You need to authenticate with SST OpenCode outside of Vibe Kanban before using it. Please follow the authentication instructions on the [SST OpenCode GitHub page](https://github.com/sst/opencode). +You need to authenticate with OpenCode outside of Vibe Kanban before using it. Please follow the authentication instructions on the [OpenCode GitHub page](https://github.com/sst/opencode).