Claude Code Research

Vibe Kanban Orchestration

5 min read

Vibe Kanban Orchestration

Overview

Vibe Kanban is an open-source orchestration tool designed to streamline AI coding agent workflow management, specifically built to help developers get “10X more out of Claude Code, Gemini CLI, Codex, Amp and other coding agents.” It provides a Kanban-style interface for managing AI-assisted development tasks with powerful orchestration capabilities.

Core Architecture

Technology Stack

  • Backend: Rust (55.8%)
  • Frontend: TypeScript (40.7%)
  • Authentication: GitHub OAuth
  • Interface: Kanban-style task management

Key Components

  1. Executor System: Abstracts different AI agents behind a common interface
  2. Process Service: Manages lifecycle of AI agent processes
  3. MCP Integration: Multi-Agent Communication Protocol for agent coordination
  4. Isolated Worktrees: Git-based isolation for parallel task execution

Installation and Setup

Basic Installation

# Install via npx
npx vibe-kanban

Prerequisites

  • Rust
  • Node.js (>=18)
  • pnpm (>=8)
  • Claude Code CLI (@anthropic-ai/claude-code)

Configuration Steps

  1. Launch Vibe Kanban: Run npx vibe-kanban to start the application
  2. Access MCP Settings: Navigate to “MCP Servers” page in the UI
  3. Select Claude: Choose “Claude” from the executor dropdown
  4. Add Configuration: Click “Add Vibe-Kanban MCP” to auto-populate configuration
  5. Save Settings: Apply changes to integrate with Claude Code

Configuration Files

  • Claude Config: ~/.config/claude/claude_desktop_config.json
  • MCP Config: Managed through Vibe Kanban UI
  • Environment: NODE_NO_WARNINGS=1 set internally for Claude execution

Integration Architecture

ClaudeExecutor Implementation

The integration centers around the ClaudeExecutor struct which implements the Executor trait:

  1. Process Spawning:

    • Command: npx -y @anthropic-ai/claude-code
    • Task prompt passed via stdin
    • Execution in isolated Git worktree

  2. Output Streaming:

    • Real-time stdout/stderr streaming
    • Database persistence of outputs
    • JSONL format parsing

  3. Log Normalization:

    • Converts Claude’s JSONL to NormalizedConversation
    • Extracts assistant messages and tool uses
    • Generates concise content for display

  4. Session Management:

    • ClaudeFollowupExecutor for continuous interactions
    • Uses --resume=session_id flag
    • Maintains conversation context

MCP Server Integration

Vibe Kanban exposes tool methods via JSON-RPC:

  • create_task
  • list_projects
  • list_tasks
  • set_task_status

Workflow Patterns

1. Basic Task Execution

// Task creation workflow
1. Create task with clear description
2. Select Claude as executor
3. Monitor real-time execution
4. Review changes in isolated worktree
5. Merge changes if satisfied

2. Follow-up Iterations

// Iterative development pattern
1. Initial task execution
2. Review Claude's output
3. Provide follow-up prompt
4. Claude resumes with session context
5. Continue until task complete

3. Parallel Orchestration

// Multi-task coordination
1. Create multiple tasks
2. Each gets isolated Git worktree
3. Execute tasks in parallel
4. No interference between tasks
5. Merge completed work selectively

Best Practices

Task Definition

  • Clear Descriptions: Provide detailed, unambiguous task descriptions
  • Scope Management: Break large features into manageable tasks
  • Context Inclusion: Include relevant background in task descriptions

Execution Management

  • Isolated Development: Leverage Git worktrees for safety
  • Real-time Monitoring: Watch execution logs for early intervention
  • Session Continuity: Use follow-ups for complex, iterative tasks

Code Review Workflow

  1. Diff Inspection: Use integrated diff viewer
  2. Change Validation: Test Claude’s changes in isolation
  3. Selective Merging: Cherry-pick successful changes
  4. Version Control: Maintain clean Git history

Advanced Orchestration Patterns

1. SPARC Methodology Integration

When combined with methodologies like SPARC (Specification, Pseudocode, Architecture, Refinement, Completion), Vibe Kanban enables:

  • Structured agent collaboration
  • Phase-based development
  • Clear handoffs between stages

2. Multi-Agent Coordination

// Example: Full-stack feature development
Task 1: Backend API (Claude)
Task 2: Frontend UI (Gemini)
Task 3: Tests (Claude)
Task 4: Documentation (Claude)
// All execute in parallel, isolated worktrees

3. Continuous Development Flow

  • No daily planning overhead
  • Seamless task-to-task transitions
  • Maintain development momentum
  • Context preservation across sessions

Integration with Other Tools

Claude-Flow Compatibility

Vibe Kanban can work alongside tools like Claude-Flow for:

  • Enterprise-grade orchestration
  • Swarm intelligence patterns
  • Advanced MCP tool integration

Project Archaeology

Use Vibe Kanban to coordinate Claude Code’s analysis capabilities:

# Analyze codebase structure
claude-code analyze-directory ./src
 
# Results managed as Vibe Kanban task

Performance Optimization

Resource Management

  • Process Lifecycle: Automatic cleanup of completed processes
  • Memory Efficiency: Streaming output vs. buffering
  • Parallel Limits: Configure based on system resources

Context Preservation

  • Session IDs: Maintain conversation continuity
  • Worktree Persistence: Keep work available for follow-ups
  • Log Normalization: Efficient storage and retrieval

Common Use Cases

1. Feature Development

  • Create feature task
  • Claude implements in isolated branch
  • Iterate with follow-ups
  • Review and merge

2. Bug Fixing

  • Describe bug in task
  • Claude investigates and fixes
  • Test in isolation
  • Deploy fix

3. Refactoring

  • Define refactoring goals
  • Claude executes systematically
  • Review changes incrementally
  • Ensure tests pass

4. Documentation

  • Task for documentation needs
  • Claude generates/updates docs
  • Review for accuracy
  • Publish changes

Troubleshooting

Common Issues

  1. Session Loss: Ensure session_id extracted correctly
  2. Worktree Conflicts: Clean up stale worktrees
  3. Process Hanging: Monitor ProcessService logs
  4. Output Parsing: Check JSONL format compliance

Debug Commands

# Check Claude CLI availability
npx -y @anthropic-ai/claude-code --version
 
# Verify MCP server
npx -y vibe-kanban --mcp
 
# Test executor spawn
# Check logs in Vibe Kanban UI

Future Considerations

Scalability

  • Multiple Claude instances
  • Load balancing strategies
  • Queue management
  • Priority scheduling

Enhanced Integration

  • Custom executor parameters
  • Advanced MCP tools
  • Webhook notifications
  • CI/CD pipeline integration

claude-code vibe-kanban orchestration ai-agents workflow-management mcp task-automation development-tools

Graph View

Backlinks