Skip to content
Vibe Check

Explanation

Understand the architecture, design decisions, and implementation details behind vibe-check.

Quick Navigation

Section titled “Quick Navigation”

Core Concepts

Foundational ideas that shape how vibe-check works

Architecture

Internal systems and how components interact

Design Decisions

Rationale behind key API and architecture choices

Core Concepts

Section titled “Core Concepts”

Foundational principles that guide vibe-check’s design.

Dual API Surface

Section titled “Dual API Surface”

Why vibe-check provides two distinct APIs for testing and automation.

Topics covered:

  • vibeTest vs vibeWorkflow semantics
  • Use case alignment
  • API design philosophy
  • Shared primitives

Key insights:

  • Tests focus on assertions and quality gates
  • Workflows focus on orchestration and cumulative context
  • Both share the same underlying primitives
  • API choice signals intent clearly

Auto-Capture

Section titled “Auto-Capture”

How vibe-check automatically captures execution context without manual instrumentation.

Topics covered:

  • Hook-based capture mechanism
  • What gets captured (files, tools, git state)
  • Correlation of pre/post events
  • Non-blocking capture design

Key insights:

  • Zero-instrumentation approach
  • Comprehensive context capture
  • Graceful degradation on failures
  • Lazy loading for memory efficiency

Lazy Loading

Section titled “Lazy Loading”

Memory-efficient file access through deferred content loading.

Topics covered:

  • Content-addressed storage
  • On-demand file loading
  • Memory footprint optimization
  • API design for lazy access

Key insights:

  • Scales to 100+ file changes
  • Minimal memory footprint
  • Transparent lazy accessors
  • Reporter-friendly disk bundles

Architecture

Section titled “Architecture”

Internal systems and component interactions.

Architecture Overview

Section titled “Architecture Overview”

High-level system architecture and component relationships.

Topics covered:

  • Core components (test, workflow, runner, context manager)
  • Data flow through the system
  • Vitest integration patterns
  • Reporter architecture

Key insights:

  • Vitest-native design
  • Fixture-based dependency injection
  • Hybrid storage (disk + meta)
  • Reporter lifecycle integration

Context Manager

Section titled “Context Manager”

The orchestrator for capture, processing, and injection of execution context.

Topics covered:

  • Capture phase (hook file writes)
  • Processing phase (correlation, extraction)
  • Injection phase (RunResult population)
  • Error handling and graceful degradation

Key insights:

  • Three-phase lifecycle
  • Event correlation algorithm
  • Non-blocking hook writes
  • Failure isolation

Run Bundle

Section titled “Run Bundle”

The disk-based artifact storage structure.

Topics covered:

  • Bundle directory structure
  • Content-addressed file storage
  • Metadata format
  • Retention policies

Key insights:

  • 30-day default retention
  • Content deduplication
  • Deterministic paths
  • Reporter accessibility

Hook Integration

Section titled “Hook Integration”

How vibe-check integrates with Claude Code hooks for data capture.

Topics covered:

  • Supported hook types
  • Hook configuration
  • Capture mechanism
  • Event correlation

Key insights:

  • Non-intrusive capture
  • Correlation via timestamps
  • Tool call pairing (PreTool + PostTool)
  • Timeline reconstruction

Design Decisions

Section titled “Design Decisions”

Rationale behind key architectural and API choices.

Design Rationale

Section titled “Design Rationale”

Why vibe-check was designed the way it was.

Topics covered:

  • Why Vitest v3 as foundation?
  • Why dual API surface?
  • Why hybrid storage (disk + meta)?
  • Why lazy loading?
  • Why workspace context design?

Key insights:

  • Vitest maturity and ecosystem
  • Semantic clarity through API split
  • Scalability through lazy loading
  • DX-first design principles

Reading Paths

Section titled “Reading Paths”

For Framework Users

Section titled “For Framework Users”

If you’re using vibe-check and want to understand how it works:

  1. Dual API Surface - Understand vibeTest vs vibeWorkflow
  2. Auto-Capture - Learn what gets captured automatically
  3. Architecture Overview - High-level system understanding

For Contributors

Section titled “For Contributors”

If you’re contributing to vibe-check or deeply debugging:

  1. Architecture Overview - System architecture
  2. Context Manager - Capture orchestration
  3. Run Bundle - Storage structure
  4. Hook Integration - Hook capture mechanics
  5. Design Rationale - Why things are the way they are

For Framework Designers

Section titled “For Framework Designers”

If you’re building similar tools or studying design patterns:

  1. Design Rationale - Design choices and tradeoffs
  2. Dual API Surface - API design philosophy
  3. Lazy Loading - Memory optimization patterns
  4. Context Manager - Orchestration patterns
Section titled “Related Documentation”

Tutorials

Section titled “Tutorials”

How-To Guides

Section titled “How-To Guides”

API Reference

Section titled “API Reference”
  • Core APIs - Function signatures and usage
  • Types - TypeScript interface documentation