vibe

Vibe is a lightweight coding supervisor that integrates with Claude Code to automate complex SDLC workflows through multi-stage pipelines and intelligent retry logic. It uses a client-daemon architecture to manage long-running jobs, track status across multiple projects, and provide a persistent interface for monitoring and control.

Key Features

• Client-Daemon Architecture - Run long-lived automation jobs in the background with a persistent daemon.
• Multi-stage Pipelines - Automated feature development from planning to validation.
• Claude Code Integration - Headless execution of prompts with session tracking and job-level isolation.
• Intelligent Retry Logic - Automatically calls Claude to fix failed project checks. Retry any failed job from its failure point with vibe retry.
• Job Lifecycle Control - Pause, resume, cancel, retry, or approve generated plans for full operator control.
• Real-time Monitoring - Live SSE-based log streaming with automatic reconnection and incremental event replay.
• Quota Ceiling Management - Enforce rolling-window utilization limits on Claude Code; jobs auto-pause and resume when quota recovers.
• Composable Role System - Context-aware agent personas (Architect, Developer, etc.).
• Git & GitHub Integration - Automatic branch management and PR creation.
• Graduated Quality Gates — Gate criteria support on_failure policies: fail (terminate pipeline), retry (re-attempt the stage), or warn (log a warning and continue). Exit criteria now validate stage outputs automatically.
• Queue Introspection — vibe queue shows per-project queue state with running and pending jobs. Supports --json for machine-readable output.
• Crash Recovery — The daemon recovers pending and in-progress jobs on restart. Queued jobs are re-enqueued in original order; running jobs are marked interrupted for manual resume.
• Custom Run Types — Define your own pipeline shapes via YAML. The three-tier registry resolves run types from project .vibe/run_types/, global ~/.vibe/run_types/, then bundled defaults. Validate custom definitions with vibe pipeline validate.
• Stage Type Classification — Stages declare a stage_type (research or implementation). Research stages are restricted to read-only tools; implementation stages get full write access. All bundled pipelines annotate every stage.
• Manual Gates — Any stage can require operator approval via gate: {type: manual}. The executor pauses the job and waits for vibe approve / vibe reject before continuing.
• Job Priority — Promote or demote queued jobs with vibe promote and vibe demote. Higher-priority jobs dispatch first within each project; ties break by FIFO order.
• Stage Executor Protocol — Pipelines orchestrate shell commands alongside Claude. Stages declare an executor_type (claude, command, or checks) and the engine routes to the appropriate backend. Command stages require a command list in YAML (string form rejected for safety).
• Pipeline Families — Run types classify as research or implementation. Research pipelines run concurrently per project; implementation pipelines get exclusive access. A security rule derives the effective family from stage metadata: any command executor or implementation stage forces the family to implementation, preventing concurrency bypass.
• Parallel Research Scheduling — Multiple research jobs (e.g., discovery runs) execute simultaneously on the same project. A read/write lock model grants shared access to research jobs and exclusive access to implementation jobs. Same-branch conflicts are detected and serialized.
• Gate Timing — Gates support a timing field: before (default) pauses before stage execution for plan approval; after pauses after execution for output review.
• Abandon Operation — vibe abandon stops a job and deletes its git branch. Running jobs get a graceful stop (202); paused/queued jobs are cleaned up immediately (200); terminal jobs return 409.
• Daemon API Authentication — The daemon generates a bearer token on startup. All mutating requests (POST, DELETE) require Authorization: Bearer <token>. The CLI reads the token automatically. Unauthenticated requests currently receive a deprecation warning.
• Run Type Selection — vibe run --type <name> selects the pipeline shape (default: feature). Shorthand aliases vibe discovery and vibe fix remain available.
• Pipeline Inspection — vibe pipeline show <name> displays the full run type definition including stages, gates, criteria, and family. vibe pipeline init scaffolds a .vibe/run_types/ directory with a documented template.
• Extensible Criterion Model — The criterion type field accepts both built-in enum values and custom string types. Custom criteria carry arbitrary parameters via extra_config for project-specific validation.

Desktop Application

The desktop application is a Tauri v2 native app (React + TypeScript) that provides a graphical interface for managing daemon connections, projects, and jobs.

Layout

The shell is divided into three regions:

• Top bar — Project switcher dropdown on the left (click to switch projects or register a new one); command palette search bar in the center; New Job button, theme toggle, connection indicator, and settings gear on the right.
• Sidebar — Research and Coding navigation items with keyboard shortcuts visible on hover; a separator; Settings below the separator; daemon connection status at the very bottom (click to open the connection screen).
• Main content — Renders the active screen or a live job execution/results view when a job is open.

Research Screen

The Research screen is a two-panel thinking workspace for conducting AI-assisted research before committing to implementation work.

• Left panel (280px): Mixed chronological list of conversations and research pipelines. Two creation buttons: "+ Chat" (starts an interactive conversation) and "+ Pipeline" (opens the prompt chain composer). Each item shows type icon, name, activity summary, cost, and relative timestamp.
• Right panel: Content view for the selected item. Conversations show a full chat thread with streaming responses. Research pipelines show the compose view (drafting), execution view (running), or results view (completed).

Research activities run with a shared read lock and do not mutate the codebase.

Coding Screen

The Coding screen presents a three-column kanban board showing the project's job queue:

• To Do — Queued features (large cards) and one-shot jobs (compact cards), ordered by submission time.
• In Progress — Currently executing item with live elapsed time and pipeline stage name.
• Done — Completed, failed, and cancelled items in reverse chronological order with total duration and cost.

Feature cards display title, description, task and sprint counts, and a "View details" link to the Feature Detail screen. Job cards show short ID, run type badge, and status metadata. New jobs can be submitted directly from the kanban header. Toast notifications appear when jobs reach terminal states.

Feature Detail Screen

The Feature Detail screen is the command center for a multi-sprint feature effort, reached by clicking a feature card's "View details" link.

• Left panel (240px): Sprint timeline — vertical chronological sequence of sprint nodes and deviation check nodes. Overall progress bar at top. Clicking a sprint node loads its task list on the right. Deviation check nodes appear between sprints showing running, passed, or drift-detected states.
• Right panel: Task list for the selected sprint. Each task card shows status, pipeline stage bar, and inline approve/reject controls when the task is awaiting plan approval. Selecting a deviation check node shows the drift analysis and three-option decision flow (accept corrective task / ignore and continue / revise remaining roadmap).

Keyboard Shortcuts

Action	Shortcut
Research screen	Cmd+1
Coding screen	Cmd+2
Settings screen	Cmd+,
Command palette	Cmd+K
New job	Cmd+N

Connection flow

On first launch the app presents a full-screen connection gate. Enter the daemon address to connect. On subsequent launches the app reads the saved address and auto-connects, showing a spinner while the connection is established. If auto-connect fails, the gate is shown again with the error. Once connected, the last active project is restored automatically.

Running the desktop app

cd desktop
npm run tauri dev    # Development with hot reload
npm run tauri build  # Production build

Installation

Prerequisites

• Python >= 3.14
• uv package manager
• Claude Code CLI installed and configured

Quick Start

1. Initialize project:

   git clone https://github.com/deti/vibe.git
   cd vibe
   make init

2. Start the daemon:

   vibe daemon start

3. Register your project (path must be absolute and accessible by the daemon):

   vibe project add my-project /path/to/your/project

4. Run a pipeline:

   # Feature development (default run type)
   vibe run --project my-project "Implement async support for the database layer"
   
   # Explicit run type selection
   vibe run --project my-project --type fix "Fix race condition in session token refresh"
   
   # Shorthand aliases
   vibe discovery --project my-project "Audit logging coverage across all API endpoints"

5. Monitor progress:

   vibe status
   vibe logs --follow

Pipeline Management

# List available run types and their stages
vibe pipeline types

# Validate a custom run type YAML before deploying
vibe pipeline validate path/to/my-pipeline.yaml

# List local pipeline runs
vibe pipeline list

# Plan only (no execution) — useful for review before committing
vibe pipeline plan --type feature "Add caching layer to API responses"

# Show full definition of a run type (stages, gates, criteria, family)
vibe pipeline show feature

# Scaffold a custom run type template
vibe pipeline init
# Creates .vibe/run_types/custom.yaml with documented fields

Job Priority

Queued jobs dispatch in FIFO order by default. Use promote and demote to adjust priority:

# Bump a queued job up in priority
vibe promote abc123

# Lower a queued job's priority
vibe demote abc123

# View current queue state including priority, lock mode, and parallelism
vibe queue

Job Lifecycle

Beyond pause, resume, and cancel, two additional lifecycle commands are available:

# Abandon a job — stops execution and deletes the git branch
vibe abandon abc123

# Abandon the most recent active job (no ID needed)
vibe abandon

abandon differs from cancel: cancel preserves the branch for later inspection, while abandon deletes it for a clean slate.

Core Concepts

Vibe revolves around a few core entities:

• Daemon: The background process that manages job queues, executes tasks, and persists state.
• Project: A registered directory where Vibe can run jobs. Jobs are isolated per project.
• Job: A single unit of work (e.g., a pipeline run) with its own state, logs, and artifacts.
• Pipeline: A multi-stage workflow that Vibe orchestrates. Three run types are bundled (feature, discovery, fix), and you can define custom ones via YAML.
• Stage Type: Each pipeline stage is classified as research (read-only) or implementation (code-mutating). Research stages are restricted to read-only tools for safety.
• Gate: A stage-level configuration that controls whether the pipeline pauses for operator approval (manual) or advances automatically (auto). Gates support a timing field: before (default) fires before stage execution; after fires after stage execution for output review.
• Executor: The backend that runs a pipeline stage. claude invokes Claude Code, command runs a shell command, and checks runs the project check suite directly. The create_executor() factory selects the backend from stage metadata.
• Pipeline Family: A run type's concurrency classification — research (shared access, parallel-eligible) or implementation (exclusive access, serialized). Declared in the run type YAML via the family field; overridden at runtime if stage metadata implies implementation.

Documentation

For detailed concepts, command reference, and configuration options, see the Usage Guide.

---

Development

Running Tests

make test

Or with coverage:

make test-cov

Linting

make lint

This runs ruff check and ruff format on the codebase.

Project Structure

vibe/
├── src/vibe/
│   ├── daemon/               # Background server (Starlette/Uvicorn)
│   ├── cli/                  # CLI client (Click)
│   ├── pipeline/             # Pipeline state machine and execution logic
│   │   └── executors/        # Stage executor backends (Claude, command, manual gate)
│   ├── providers/            # AI provider integrations (Claude)
│   ├── models/               # Pydantic models for roles and pipelines
│   ├── renderers/            # Tool-native output renderers (Claude Code, Cursor)
│   ├── defaults/             # Bundled YAML role and run type definitions
│   ├── checks.py             # Check execution and retry logic
│   └── roles.py              # Role resolution and prompt assembly
├── tests/                    # Comprehensive test suite
├── desktop/                 # Desktop application (Tauri v2 + React)
│   ├── src/                 # React application source
│   │   ├── screens/         # Top-level views (Research, Coding, Settings)
│   │   ├── components/      # UI components and design system
│   │   └── lib/             # Daemon client, hooks, providers
│   └── src-tauri/           # Tauri v2 Rust shell and config
└── .vibe/                    # Project configuration directory

What's New

• Gate Timing: Gates now support timing: before (pre-execution approval) and timing: after (post-execution review). Default is before for backward compatibility.
• Abandon Command: vibe abandon [JOB_ID] stops a job and deletes its git branch. Supports running, paused, interrupted, and queued jobs.
• Daemon API Authentication: Bearer token authentication on all mutating API routes. Token is auto-generated on daemon startup and read by the CLI transparently.
• Run Type Selection on vibe run: The --type / -t flag selects any registered run type (default: feature). Replaces the need for separate vibe discovery / vibe fix aliases for common types.
• Pipeline Inspection: vibe pipeline show <name> displays the full run type definition. vibe pipeline init scaffolds a custom run type template in .vibe/run_types/.
• Extensible Criterion Types: The Criterion.type field now accepts custom string types alongside built-in enums. Custom criteria use extra_config for arbitrary parameters, supporting project-specific validation without code changes.
• Job Status: Abandoned: New terminal status for jobs stopped via vibe abandon. Distinct from cancelled — abandoned jobs have their branches deleted.
• Stage Executor Protocol: Stages now dispatch through a pluggable executor interface. Set executor_type: command to run shell commands as pipeline stages, or executor_type: checks to run the project check suite. The default (claude) preserves existing behavior.
• Pipeline Families: Run types declare a family field (research or implementation). Research-family pipelines run concurrently per project; implementation-family pipelines require exclusive access. A derived effective family prevents declared research pipelines from bypassing serialization when they contain code-mutating stages.
• Parallel Research Scheduling: Multiple research jobs execute simultaneously on the same project via a read/write lock model. Implementation jobs wait for exclusive access. vibe queue shows lock mode (parallel or serialized) and vibe jobs shows wait reasons for blocked jobs.
• New SSE Event Types: stage_started, stage_blocked, gate_waiting, stage_retrying, and gate_result provide finer-grained pipeline execution visibility.
• Enhanced Queue Display: vibe queue shows lock mode (parallel/serialized), priority, and pending count. vibe jobs shows run type, family tag, queue position, and wait reason.
• Configurable Review Cycle Names: Quality gate policies accept custom review_stage, fix_stage, and validate_stage names, enabling custom pipelines with non-default review cycles.
• Custom Run Types: Define pipeline shapes via YAML with a three-tier registry (project, global, bundled). Validate with vibe pipeline validate.
• Stage Type Classification: Stages declare stage_type: research or stage_type: implementation. Research stages enforce read-only tool access.
• Manual Gates: Any stage can pause for operator approval via gate: {type: manual} in the run type YAML. Not limited to plan review.
• Job Priority: vibe promote and vibe demote adjust dispatch priority for queued jobs. Higher priority dispatches first; FIFO breaks ties.
• Pipeline Subcommands: vibe pipeline types lists available run types; vibe pipeline validate checks custom YAML; vibe pipeline list shows local runs.
• Unified Dispatch: All run types (bundled and custom) use the same generic execution path. No special-casing by pipeline name.
• Daemon-based execution: Jobs now run in a persistent background process.
• Job Control: Added pause, resume, cancel, and approve commands for fine-grained job management.
• Job Retry: vibe retry <job_id> [context...] re-runs a failed job from its failure point, preserving completed stage artifacts.
• Live Logs: Real-time streaming of job logs with vibe logs --follow. Automatically reconnects on connection loss using SSE event IDs.
• Quota Ceiling Management: Configure providers.claude_code.quota_ceilings in vibe.yaml to cap Claude Code utilization. Jobs pause automatically when the ceiling is breached and resume when quota recovers.
• Artifact Management: Retrieve and view generated files via vibe artifacts.
• Metric-based Checks: vibe.yaml check steps now support automated pass/fail based on extracted metrics (e.g., test coverage).
• Gate Failure Policies: Criteria now support on_failure: fail, retry, or warn for graduated quality gate responses.
• Exit Criteria Activation: Pipeline stages validate their output through exit criteria. Bundled pipelines use on_failure: warn for backward compatibility.
• Queue Command: vibe queue shows per-project queue state. Use --json for machine-readable output.
• Crash Recovery: The daemon automatically recovers all job states on restart. Running jobs are marked interrupted for resume; queued jobs are re-enqueued in original order; paused and awaiting-approval jobs retain project ownership.
• Security Hardening: Race condition protection on concurrent approve/reject operations; YAML safety linting enforced via ruff.