Installation

This guide will walk you through installing @dao/vibe-check and configuring it for your first project.

Prerequisites

Before you begin, ensure you have:

• Node.js 18 or later - Check with node --version
• A package manager - We recommend Bun, but npm, pnpm, and yarn work too
• TypeScript project - Vibe-check is TypeScript-first
• Claude Code access - You’ll need the @anthropic-ai/claude-code SDK

Tip

First time with Claude Code SDK? Check the Claude Code documentation to get started.

Installation

Install vibe-check and its peer dependencies:

bun

bun add -D @dao/vibe-check vitest vite

npm

npm install --save-dev @dao/vibe-check vitest vite

pnpm

pnpm add -D @dao/vibe-check vitest vite

yarn

yarn add -D @dao/vibe-check vitest vite

Note

Peer Dependencies:

• vitest ^3.2.0 - Test runner
• vite ^5.0.0 - Build tool

Configuration

Step 1: Create Vitest Config

Create a vitest.config.ts file in your project root:

vitest.config.ts

import { defineVibeConfig } from '@dao/vibe-check/config';

export default defineVibeConfig({
  // Your custom Vitest configuration here (optional)
});

Tip

What does defineVibeConfig do?

It configures Vitest with sensible defaults for agent testing:

• Registers vibe-check reporters (VibeCostReporter, VibeHtmlReporter)
• Sets default timeout to 5 minutes (agents need more time)
• Auto-registers custom matchers
• Configures test worker pool (50% of CPU cores)

Step 2: Advanced Configuration (Optional)

You can customize the configuration by passing Vitest options:

vitest.config.ts

import { defineVibeConfig } from '@dao/vibe-check/config';

export default defineVibeConfig({
  test: {
    // Increase timeout for complex workflows
    timeout: 600000, // 10 minutes

    // Limit concurrent tests to reduce API rate limits
    maxConcurrency: 2,

    // Run tests sequentially (not recommended for CI)
    poolOptions: {
      threads: {
        singleThread: true
      }
    },

    // Custom test file patterns
    include: ['**/*.vibe.test.{ts,js}'],
  },

  // Bundle cleanup configuration
  cleanup: {
    maxAgeDays: 30,        // Delete bundles older than 30 days
    minFreeDiskMb: 1000,   // Clean up when <1GB free space
    disabled: false,       // Enable automatic cleanup
  },
});

Step 3: TypeScript Configuration

Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "types": ["vitest/globals", "@dao/vibe-check"]
  }
}

This enables:

• Vitest global types (describe, it, expect)
• Vibe-check custom matchers (TypeScript autocomplete)
• Extended TestContext interface

Verification

Let’s verify the installation with a simple test.

Create a Test File

Create tests/hello.vibe.test.ts:

import { vibeTest } from '@dao/vibe-check';

vibeTest('installation works', async ({ runAgent, expect }) => {
  const result = await runAgent({
    prompt: 'Say "Hello from vibe-check!"'
  });

  // Verify we got a result
  expect(result).toBeDefined();
  expect(result.bundleDir).toBeTruthy();

  // Check metrics were captured
  expect(result.metrics.totalTokens).toBeGreaterThan(0);
  expect(result.metrics.totalCostUsd).toBeGreaterThan(0);
});

Run the Test

bun

bun run vitest

npm

npm run vitest

pnpm

pnpm vitest

yarn

yarn vitest

Expected Output

You should see:

✓ tests/hello.vibe.test.ts (1)
  ✓ installation works

Test Files  1 passed (1)
     Tests  1 passed (1)

Vibe Check Cost Summary
─────────────────────────────
Total Cost: $0.0043
Total Tokens: 1,247

HTML Report: .vibe-artifacts/reports/index.html

Tip

Open the HTML report to see the full conversation transcript, timeline, and captured context!

Project Structure

After installation, your project should look like:

your-project/
├── tests/                        # Your test files
│   └── hello.vibe.test.ts
├── .vibe-artifacts/              # Auto-generated (gitignored)
│   ├── bundles/                  # Run artifacts
│   │   └── {test-id}/
│   │       ├── summary.json
│   │       ├── events.ndjson
│   │       ├── hooks.ndjson
│   │       └── files/
│   └── reports/
│       └── index.html            # HTML report
├── vitest.config.ts              # Vitest configuration
├── tsconfig.json                 # TypeScript configuration
└── package.json

Add to .gitignore

The .vibe-artifacts/ directory can grow large. Add it to your .gitignore:

# Vibe Check artifacts
.vibe-artifacts/

Caution

CI/CD Consideration:

If you want to preserve artifacts in CI, exclude .vibe-artifacts/reports/ from gitignore and configure bundle cleanup:

export default defineVibeConfig({
  cleanup: {
    maxAgeDays: 7,  // More aggressive cleanup in CI
  }
});

Troubleshooting

Module not found: ‘@dao/vibe-check’

Solution: Ensure the package is installed in your project (not globally):

bun install  # or npm install

Custom matchers not recognized in TypeScript

Solution: Add @dao/vibe-check to your tsconfig.json types:

{
  "compilerOptions": {
    "types": ["@dao/vibe-check"]
  }
}

Test timeout errors

Solution: Increase the test timeout in your config:

export default defineVibeConfig({
  test: {
    timeout: 600000  // 10 minutes
  }
});

Claude Code SDK errors

Solution: Ensure you have the SDK installed:

bun add @anthropic-ai/claude-code

And set your API key:

export ANTHROPIC_API_KEY="your-api-key"

Permission errors with .vibe-artifacts/

Solution: The directory is created automatically. If you see permission errors:

mkdir -p .vibe-artifacts
chmod 755 .vibe-artifacts

Next Steps

Now that vibe-check is installed and configured:

• Quickstart → - Write your first test in 5 minutes
• API Reference → - Explore the complete API
• Configuration Guide → - Advanced configuration options

---

Package Dependencies Reference

For reference, here are vibe-check’s dependencies:

Peer Dependencies (you must install):

• vitest ^3.2.0
• vite ^5.0.0

Dependencies (installed automatically):

• @anthropic-ai/claude-code - Claude Code SDK
• zod - Runtime validation
• zod-to-json-schema - Schema conversion for structured outputs
• p-limit - Concurrency control
• pathe - Cross-platform path handling
• fs-extra - File system utilities
• minimatch - Glob pattern matching

Dev Dependencies (for development):

• typescript ^5.5.0
• @types/node ^20.11.0
• tsup - Build tool