vibe-kanban/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

Core Development

• pnpm run dev - Start both frontend (port 3000) and backend (port 3001) with live reload
• pnpm run check - Run cargo check and TypeScript type checking - always run this before committing
• pnpm run generate-types - Generate TypeScript types from Rust structs (run after modifying Rust types)

Testing and Validation

• pnpm run frontend:dev - Start frontend development server only
• pnpm run backend:dev - Start Rust backend only
• cargo test - Run Rust unit tests from backend directory
• cargo fmt - Format Rust code
• cargo clippy - Run Rust linter

Building

• ./build-npm-package.sh - Build production package for distribution
• cargo build --release - Build optimized Rust binary

Architecture Overview

Tech Stack

• Backend: Rust with Axum web framework, SQLite + SQLX, Tokio async runtime
• Frontend: React 18 + TypeScript, Vite, Tailwind CSS, Radix UI
• Package Management: pnpm workspace monorepo
• Type Sharing: Rust types exported to TypeScript via ts-rs

Core Concepts

Vibe Kanban is an AI coding agent orchestration platform that manages multiple coding agents (Claude Code, Gemini CLI, Amp, etc.) through a unified interface.

Project Structure:

• /backend/src/ - Rust backend with API endpoints, database, and agent executors
• /frontend/src/ - React frontend with task management UI
• /backend/migrations/ - SQLite database schema migrations
• /shared-types/ - Generated TypeScript types from Rust structs

Executor System: Each AI agent is implemented as an executor in /backend/src/executors/:

• claude.rs - Claude Code integration
• gemini.rs - Google Gemini CLI
• amp.rs - Amp coding agent
• dev_server.rs - Development server management
• echo.rs - Test/debug executor

Key Backend Modules:

• /backend/src/api/ - REST API endpoints
• /backend/src/db/ - Database models and queries
• /backend/src/github/ - GitHub OAuth and API integration
• /backend/src/git/ - Git operations and worktree management
• /backend/src/mcp/ - Model Context Protocol server implementation

Database Schema

SQLite database with core entities:

• projects - Coding projects with GitHub repo integration
• tasks - Individual tasks assigned to executors
• processes - Execution processes with streaming logs
• github_users, github_repos - GitHub integration data

API Architecture

• RESTful endpoints at /api/ prefix
• WebSocket streaming for real-time task updates at /api/stream/:process_id
• GitHub OAuth flow with PKCE
• MCP server exposed for external tool integration

Development Guidelines

Type management

• First ensure that src/bin/generate_types.rs is up to date with the types in the project
• Always regenerate types after modifying Rust structs: Run pnpm run generate-types
• Backend-first development: Define data structures in Rust, export to frontend
• Use #[derive(Serialize, Deserialize, PartialEq, Debug, Clone, TS)] for shared types

Code Style

• Rust: Use rustfmt, follow snake_case naming, leverage tokio for async operations
• TypeScript: Strict mode enabled, use @/ path aliases for imports
• React: Functional components with hooks, avoid class components

Git Integration Features

• Automatic branch creation per task
• Git worktree management for concurrent development
• GitHub PR creation and monitoring
• Commit streaming and real-time git status updates

MCP Server Integration

Built-in MCP server provides task management tools:

• create_task, update_task, delete_task
• list_tasks, get_task, list_projects
• Requires project_id for most operations

Process Execution

• All agent executions run as managed processes with streaming logs
• Process lifecycle: queued → running → completed/failed
• Real-time updates via WebSocket connections
• Automatic cleanup of completed processes

Environment Configuration

• Backend runs on port 3001, frontend proxies API calls in development
• GitHub OAuth requires GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET
• Optional PostHog analytics integration
• Rust nightly toolchain required (version 2025-05-18 or later)

Testing Strategy

• Run pnpm run check to validate both Rust and TypeScript code
• Use cargo test for backend unit tests
• Frontend testing focuses on component integration
• Process execution testing via echo executor

Key Dependencies

• axum - Web framework and routing
• sqlx - Database operations with compile-time query checking
• octocrab - GitHub API client
• rmcp - MCP server implementation
• @dnd-kit - Drag-and-drop task management
• react-router-dom - Frontend routing