API Reference

Complete technical reference for all vibe-check APIs, types, and utilities.

Quick Navigation

Core APIs

Functions you’ll use in every test and workflow.

Types

TypeScript interfaces and types for context, results, and configuration.

Utilities

Helper functions for configuration and test setup.

---

Core APIs

Essential functions for testing and automation.

vibeTest

Write tests with custom matchers, fixtures, and auto-captured context.

vibeTest('example', async ({ runAgent, expect }) => {
  const result = await runAgent({ prompt: 'implement feature X' });
  expect(result).toHaveChangedFiles(['src/index.ts']);
});

vibeWorkflow

Build multi-stage automation workflows with cumulative context.

const builder = defineAgent({ name: 'builder', model: 'claude-sonnet-4' });
const tester = defineAgent({ name: 'tester', model: 'claude-sonnet-4' });

vibeWorkflow('deploy', async (wf) => {
  await wf.stage('build', { agent: builder, prompt: '/build' });
  await wf.stage('test', { agent: tester, prompt: '/test' });
});

defineAgent

Create reusable agent definitions with configuration.

const myAgent = defineAgent({
  name: 'my-agent',
  model: 'claude-sonnet-4',
  maxTurns: 10
});

runAgent

Execute agents directly outside of tests/workflows.

const myAgent = defineAgent({ name: 'my-agent', model: 'claude-sonnet-4' });

const result = await runAgent({
  agent: myAgent,  // Optional: defaults to claude-sonnet-4
  prompt: 'implement feature',
  workspace: '/path/to/repo'
});

judge

Evaluate agent output quality with LLM-based rubrics.

const judgeResult = await judge(result, {
  rubric: {
    criteria: [
      { name: 'correctness', weight: 0.7 },
      { name: 'style', weight: 0.3 }
    ]
  }
});

---

Types

TypeScript interfaces for all vibe-check objects.

Context Interfaces

• VibeTestContext - Test fixture context
• WorkflowContext - Workflow orchestration context
• AgentExecution - Real-time execution monitoring

Result Interfaces

• RunResult - Complete agent run results
• PartialRunResult - In-progress execution state
• FileChange - File modification details
• ToolCall - Tool invocation records

Evaluation Types

• Rubric & JudgeResult - Quality evaluation types

Configuration

• Configuration Types - Agent and test configuration options

Matchers

• Custom Matchers - All available assertion matchers

---

Utilities

Helper functions for configuration and setup.

defineVibeConfig

Configure vibe-check defaults, reporters, and globals.

export default defineVibeConfig({
  reporters: ['cost', 'html'],
  defaults: {
    workspace: '/path/to/repo',
    maxTurns: 10
  }
});

---

Usage Patterns

Testing Pattern

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

const agent = defineAgent({
  name: 'test-agent',
  model: 'claude-sonnet-4'
});

vibeTest('should implement feature', async ({ runAgent, expect }) => {
  const result = await runAgent({
    agent,
    prompt: 'implement feature X',
    workspace: '/path/to/repo'
  });

  expect(result).toHaveChangedFiles(['src/feature.ts']);
  expect(result).toCompleteAllTodos();
});

Automation Pattern

import { vibeWorkflow, defineAgent } from '@dao/vibe-check';

const builder = defineAgent({ name: 'builder' });
const tester = defineAgent({ name: 'tester' });

vibeWorkflow('ci-pipeline', async (wf) => {
  const build = await wf.stage('build', {
    agent: builder,
    prompt: '/build'
  });

  await wf.stage('test', {
    agent: tester,
    prompt: '/test'
  });
}, { defaults: { workspace: '/repo' } });

Evaluation Pattern

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

defineTestSuite({
  matrix: {
    agent: [sonnetAgent, opusAgent, haikuAgent],
    maxTurns: [8, 16]
  },
  test: ({ agent, maxTurns }) => {
    vibeTest(`${agent.name} with ${maxTurns} turns`, async ({ runAgent, judge }) => {
      const result = await runAgent({ agent, prompt: 'task', maxTurns });
      const judgeResult = await judge(result, { rubric });
      expect(judgeResult.passed).toBe(true);
    });
  }
});

---

Related Documentation

• Getting Started - Tutorials for learning vibe-check
• How-To Guides - Task-oriented guides for common use cases
• Explanation - Architecture and design deep dives