VibeSyncLab Documentation

Welcome to VibeSyncLab — the intent compiler that transforms your development vision into production-grade, architecturally sound code. This documentation will walk you through everything you need to start syncing your Vibes.

Prerequisites

• Node.js 20+ or Bun 1.1+
• Git 2.40+
• A GitHub account with repository access
• A VibeSyncLab API key (free tier available)

Installation

Install the VibeSyncLab CLI globally using your preferred package manager:

Using npm

npm install -g @vibesynclab/cli

Using Bun

bun add -g @vibesynclab/cli

Using Homebrew (macOS / Linux)

brew tap vibesynclab/tap
brew install vibesync

Verify installation:

vibesync --version
# VibeSyncLab CLI v2.4.0

Authenticate

Link your VibeSyncLab account:

vibesync auth login

This opens a browser window to complete OAuth authentication. Your API key is securely stored in your system keychain.

Configuration

Initialize VibeSyncLab in your project root:

vibesync init

This creates a vibesync.config.ts file in your project:

import { defineConfig } from '@vibesynclab/core'

export default defineConfig({
  // Project metadata
  name: 'my-app',
  version: '1.0.0',

  // Architecture preferences
  architecture: 'clean-architecture',
  language: 'typescript',
  runtime: 'node',

  // Guardrail settings
  guardrails: {
    enforce: ['solid-principles', 'no-circular-deps'],
    maxFileLength: 300,
    maxFunctionComplexity: 10,
  },

  // Type sync configuration
  typeSync: {
    enabled: true,
    targets: ['frontend/src/types', 'backend/src/types'],
    format: 'typescript',
  },

  // GitHub integration
  github: {
    repo: 'your-org/your-repo',
    baseBranch: 'main',
    autoCommit: true,
  },
})

Intent-to-Schema (I2S) Engine

The I2S Engine is the heart of VibeSyncLab. It serves as a buffer layer between your natural-language intent and the final generated code, ensuring every output is architecturally sound.

How It Works

1. Intent Parsing — Your natural-language description is parsed into a semantic intent graph, identifying entities, relationships, constraints, and business rules.
2. Schema Generation — The intent graph is mapped to a formal architecture schema (directory structure, module boundaries, data models, API contracts).
3. Validation — The schema is checked against your configured guardrails and existing codebase for compatibility.
4. Code Synthesis — Compliant code is generated module-by-module, with full test coverage and environment configuration.

Example Usage

vibesync generate \
  --vibe "User authentication module with JWT tokens, \
          refresh token rotation, rate limiting, \
          and role-based access control" \
  --pattern clean-architecture \
  --output src/modules/auth

This produces:

src/modules/auth/
├── domain/
│   ├── entities/
│   │   ├── User.ts
│   │   └── Token.ts
│   ├── repositories/
│   │   └── IAuthRepository.ts
│   └── use-cases/
│       ├── LoginUseCase.ts
│       ├── RefreshTokenUseCase.ts
│       └── ValidatePermissionUseCase.ts
├── infrastructure/
│   ├── repositories/
│   │   └── AuthRepository.ts
│   ├── middleware/
│   │   ├── rateLimiter.ts
│   │   └── authGuard.ts
│   └── config/
│       └── jwt.config.ts
├── presentation/
│   ├── controllers/
│   │   └── AuthController.ts
│   ├── routes/
│   │   └── auth.routes.ts
│   └── validators/
│       └── auth.validators.ts
└── __tests__/
    ├── LoginUseCase.test.ts
    ├── RefreshToken.test.ts
    └── AuthController.integration.test.ts

Vibe Interpreter

The Vibe Interpreter is the first stage of the I2S pipeline. It uses LLM semantic graph analysis to extract structured meaning from fuzzy, incomplete, or ambiguous descriptions.

Capabilities

• Entity Extraction — Identifies core domain entities and their relationships.
• Constraint Inference — Detects implied constraints (e.g., "OAuth2" implies token storage, redirect URIs, scope management).
• Ambiguity Resolution — When a description is too vague, VibeSyncLab will prompt you with clarifying questions instead of guessing.
• Context Awareness — Analyzes your existing codebase to understand naming conventions, patterns in use, and dependency preferences.

Interactive Mode

vibesync interpret --interactive

? Describe your feature:
> I need a payment processing module

? VibeSyncLab detected these aspects. Confirm or refine:
  ├─ Payment gateway integration (Stripe / PayPal / custom?)
  ├─ Transaction history storage
  ├─ Webhook handling for async events
  └─ Refund/dispute workflow

? Select gateway: Stripe
? Include subscription billing? Yes

✓ Intent graph generated — 14 entities, 8 use cases, 3 API routes

Architectural Guardrails

Guardrails are VibeSyncLab's enforcement mechanism. They ensure that generated code always adheres to your chosen architectural pattern and quality standards.

Built-in Guardrails

• solid-principles — Enforces SOLID across all generated classes and modules.
• no-circular-deps — Prevents circular dependency chains.
• clean-boundaries — Ensures domain logic never depends on infrastructure.
• no-spaghetti — Rejects tangled, overly-coupled code structures.
• test-coverage — Requires minimum 80% test coverage for generated modules.
• max-complexity — Limits cyclomatic complexity per function.

Custom Guardrails

Define your own guardrails in the config:

guardrails: {
  enforce: ['solid-principles', 'no-circular-deps'],
  custom: [
    {
      name: 'no-any-types',
      rule: 'Reject any use of the `any` type in TypeScript.',
      severity: 'error',
    },
    {
      name: 'max-file-exports',
      rule: 'Each file may export at most 5 symbols.',
      severity: 'warning',
    },
  ],
}

Type-Safe Sync

Type-Safe Sync keeps your front-end and back-end type definitions in lock-step. When you generate or modify a Vibe, type definitions are automatically propagated to all configured targets.

Supported Languages

• TypeScript (primary)
• Go (struct generation)
• Python (Pydantic models)
• Rust (serde structs)

Usage

# Sync types after a generate or update
vibesync type-sync

# Watch mode — auto-syncs on file changes
vibesync type-sync --watch

API Contract Generation

Type-Safe Sync can also generate OpenAPI 3.1 specifications from your Vibes:

vibesync openapi generate --output docs/api-spec.yaml

Legacy Bridge

The Legacy Bridge module enables VibeSyncLab to understand and integrate with existing codebases. It creates an abstraction layer so that new Vibes can be cleanly embedded alongside legacy code.

How It Works

1. Scan — The bridge analyzes your existing codebase to build a dependency graph and identify integration points.
2. Abstract — It generates interface contracts that represent the boundaries of your legacy system.
3. Bridge — New Vibes are generated to depend on these abstractions, not concrete legacy implementations.
4. Migrate — Optionally, the bridge can suggest incremental refactoring steps to modernize legacy modules.

Usage

# Analyze existing codebase
vibesync bridge scan --path src/legacy

# Generate bridge interfaces
vibesync bridge abstract --output src/bridges

# Generate new module that integrates with legacy
vibesync generate \
  --vibe "New reporting dashboard" \
  --bridge src/bridges/legacy-data.bridge.ts

API Reference

VibeSyncLab exposes a programmatic API for integration into CI/CD pipelines, custom tooling, and IDE extensions.

Core API

import { VibeSyncLab } from '@vibesynclab/core'

const lab = new VibeSyncLab({
  apiKey: process.env.VIBESYNC_API_KEY,
  configPath: './vibesync.config.ts',
})

// Generate code from a Vibe
const result = await lab.generate({
  vibe: 'REST API for user management with CRUD operations',
  pattern: 'clean-architecture',
  output: 'src/modules/users',
})

console.log(result.files)       // Generated file paths
console.log(result.schema)      // Architecture schema
console.log(result.testReport)  // Test execution results

Event Hooks

lab.on('schema:generated', (schema) => {
  // Review schema before code generation
  console.log('Schema ready for review:', schema)
})

lab.on('file:created', (filePath) => {
  console.log('Generated:', filePath)
})

lab.on('guardrail:violation', (violation) => {
  console.warn('Guardrail triggered:', violation.rule, violation.message)
})

CLI Commands

Core Commands

vibesync init              # Initialize project config
vibesync generate          # Generate code from a Vibe
vibesync update            # Incrementally update existing modules
vibesync type-sync         # Synchronize type definitions
vibesync bridge scan       # Scan legacy codebase
vibesync bridge abstract   # Generate bridge interfaces

Utility Commands

vibesync auth login        # Authenticate with VibeSyncLab
vibesync auth logout       # Remove stored credentials
vibesync config validate   # Validate configuration file
vibesync doctor            # Diagnose environment issues
vibesync upgrade           # Upgrade CLI to latest version

Flags

--vibe, -v        Inline Vibe description (string)
--pattern, -p     Architecture pattern (string)
--output, -o      Output directory (path)
--dry-run         Preview changes without writing files
--interactive     Enable interactive prompts
--verbose         Show detailed logs
--json            Output results as JSON

Frequently Asked Questions

Does VibeSyncLab replace my IDE or AI assistant?

No. VibeSyncLab is designed to sit between you and your AI tools. It acts as an architectural layer — you can still use your favorite IDE, Copilot, or ChatGPT. VibeSyncLab ensures the output is structured and production-ready.

What happens when I change my requirements?

VibeSyncLab performs incremental updates. It diffs your new intent against the existing schema and only modifies what's necessary. It never does a destructive full rewrite unless explicitly requested.

Can I use VibeSyncLab with an existing project?

Absolutely. The Legacy Bridge module is specifically designed for this scenario. Run vibesync bridge scan to analyze your existing codebase, and VibeSyncLab will generate new modules that integrate cleanly.

What languages and frameworks are supported?

VibeSyncLab currently supports TypeScript, JavaScript, Go, Python, and Rust for code generation. Framework support includes Express, Fastify, NestJS, Next.js, Nuxt, Gin, FastAPI, and Actix. More are being added continuously.

Is my code sent to external servers?

Your Vibe descriptions are processed through the I2S Engine, which runs partially on VibeSyncLab's cloud infrastructure. However, your source code never leaves your machine — only the intent graph and schema are transmitted. Enterprise customers can opt for a fully self-hosted deployment.

How is VibeSyncLab priced?

VibeSyncLab offers a free tier with 50 syncs per month, suitable for individual developers. Team and Enterprise plans offer unlimited syncs, self-hosted options, and priority support. Visit our pricing page for details.