Configuration Types

Configuration types for defining agents, running executions, and configuring workflows in vibe-check.

RunAgentOptions

Options for runAgent() and wf.stage() calls.

interface RunAgentOptions {
  prompt: string | PromptMessage[];
  agent?: AgentConfig;
  model?: string;
  workspace?: string;
  timeout?: number;
  maxTurns?: number;
  mcpServers?: Record<string, MCPServerConfig>;
}

Properties

prompt

prompt: string | PromptMessage[]

Task prompt for the agent. Can be a simple string or structured messages from prompt() helper.

String Prompt:

const result = await runAgent({
  prompt: '/implement user authentication'
});

Structured Prompt (with prompt helper):

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

const result = await runAgent({
  prompt: prompt({
    text: 'Implement the design from this mockup',
    images: ['./mockup.png'],
    files: ['./requirements.md']
  })
});

See Also:

• prompt() Helper → - Creating structured prompts
• Multi-Modal Prompts → - Using images and files

---

agent

agent?: AgentConfig

Agent configuration (defaults to global agent if not specified).

Example:

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

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

const result = await runAgent({
  prompt: '/task',
  agent: sonnetAgent
});

See Also:

• defineAgent() → - Creating agents
• AgentConfig - Agent configuration interface

---

model

model?: string

Override model for this run (overrides agent’s default model).

Available Models:

• claude-sonnet-4-5-20250929 - Fast, cost-effective (recommended default)
• claude-opus-4-20250514 - Most capable, higher cost
• claude-haiku-4-20250514 - Fastest, lowest cost

Example:

// Use Opus for complex task
const result = await runAgent({
  prompt: '/complex architectural refactor',
  model: 'claude-opus-4-20250514'
});

// Use Haiku for simple task
const result = await runAgent({
  prompt: '/format code',
  model: 'claude-haiku-4-20250514'
});

See Also:

• Cost Optimization → - Model selection strategies

---

workspace

workspace?: string

Working directory for the agent.

Example:

const result = await runAgent({
  prompt: '/build',
  workspace: '/path/to/project'
});

Workflow Context:

In workflows, workspace can be set at workflow level or per-stage:

vibeWorkflow('multi-repo', async (wf) => {
  // Uses default workspace
  await wf.stage('build app', { prompt: '/build' });

  // Override for different repo
  await wf.stage('deploy docs', {
    prompt: '/deploy',
    workspace: '/path/to/docs-repo'
  });
}, {
  defaults: {
    workspace: '/path/to/app-repo'
  }
});

---

timeout

timeout?: number

Execution timeout in milliseconds.

Example:

const result = await runAgent({
  prompt: '/long-running-task',
  timeout: 600_000  // 10 minutes
});

Default: 300,000ms (5 minutes)

---

maxTurns

maxTurns?: number

Maximum agent turns (request/response cycles) before stopping.

Example:

const result = await runAgent({
  prompt: '/simple task',
  maxTurns: 5  // Stop after 5 turns max
});

Use Cases:

• Limit cost for exploratory tasks
• Prevent infinite loops
• Enforce efficiency constraints

---

mcpServers

mcpServers?: Record<string, MCPServerConfig>

MCP (Model Context Protocol) server configurations for this run.

Example:

const result = await runAgent({
  prompt: '/analyze files',
  mcpServers: {
    filesystem: {
      command: 'npx',
      args: ['@modelcontextprotocol/server-filesystem', './src'],
      allowedTools: ['read_file', 'list_directory']
    }
  }
});

See Also:

• MCP Servers → - MCP integration guide
• MCPServerConfig - MCP configuration interface

---

AgentConfig

Configuration for agents created with defineAgent().

interface AgentConfig {
  name: string;
  model?: string;
  systemPrompt?: string;
  mcpServers?: Record<string, MCPServerConfig>;
  defaults?: {
    workspace?: string;
    timeout?: number;
    maxTurns?: number;
  };
}

Properties

name

name: string

Agent identifier (appears in logs and reports).

Example:

const agent = defineAgent({
  name: 'code-reviewer',
  model: 'claude-opus-4-20250514'
});

---

model

model?: string

Default model for this agent.

Example:

const fastAgent = defineAgent({
  name: 'formatter',
  model: 'claude-haiku-4-20250514'
});

const powerAgent = defineAgent({
  name: 'architect',
  model: 'claude-opus-4-20250514'
});

---

systemPrompt

systemPrompt?: string

Custom system prompt for the agent.

Example:

const securityAgent = defineAgent({
  name: 'security-auditor',
  systemPrompt: `You are a security expert.
    Focus on identifying vulnerabilities and suggesting fixes.
    Always check for: SQL injection, XSS, authentication issues, and secret exposure.`
});

---

mcpServers

mcpServers?: Record<string, MCPServerConfig>

Default MCP servers for this agent.

Example:

const dbAgent = defineAgent({
  name: 'database-agent',
  mcpServers: {
    postgres: {
      command: 'npx',
      args: ['@modelcontextprotocol/server-postgres'],
      env: {
        DATABASE_URL: process.env.DATABASE_URL
      },
      allowedTools: ['query', 'schema']
    }
  }
});

---

defaults

defaults?: {
  workspace?: string;
  timeout?: number;
  maxTurns?: number;
}

Default options for runs with this agent.

Example:

const buildAgent = defineAgent({
  name: 'builder',
  defaults: {
    workspace: '/path/to/repo',
    timeout: 600_000,  // 10 minutes
    maxTurns: 20
  }
});

---

WorkflowOptions

Options for vibeWorkflow().

interface WorkflowOptions {
  timeout?: number;
  defaults?: {
    workspace?: string;
    model?: string;
  };
}

Properties

timeout

timeout?: number

Total workflow timeout in milliseconds (applies to entire workflow, not per-stage).

Example:

vibeWorkflow('deployment', async (wf) => {
  // All stages combined must finish within 15 minutes
  await wf.stage('build', { prompt: '/build' });
  await wf.stage('test', { prompt: '/test' });
  await wf.stage('deploy', { prompt: '/deploy' });
}, {
  timeout: 900_000  // 15 minutes total
});

---

defaults

defaults?: {
  workspace?: string;
  model?: string;
}

Default configuration inherited by all stages.

Example:

vibeWorkflow('multi-stage', async (wf) => {
  // All stages use defaults
  await wf.stage('stage1', { prompt: '/task1' });
  await wf.stage('stage2', { prompt: '/task2' });

  // Override for specific stage
  await wf.stage('stage3', {
    prompt: '/task3',
    model: 'claude-opus-4-20250514'  // Override
  });
}, {
  defaults: {
    workspace: process.cwd(),
    model: 'claude-sonnet-4-5-20250929'
  }
});

---

MCPServerConfig

MCP (Model Context Protocol) server configuration.

interface MCPServerConfig {
  command: string;
  args?: string[];
  env?: Record<string, string>;
  allowedTools?: string[];
}

Properties

command

command: string

Executable command to start the MCP server.

Example:

{
  command: 'npx'
}

---

args

args?: string[]

Command-line arguments.

Example:

{
  command: 'npx',
  args: ['@modelcontextprotocol/server-filesystem', './src']
}

---

env

env?: Record<string, string>

Environment variables for the server.

Example:

{
  command: 'npx',
  args: ['@modelcontextprotocol/server-postgres'],
  env: {
    DATABASE_URL: process.env.DATABASE_URL,
    NODE_ENV: 'production'
  }
}

---

allowedTools

allowedTools?: string[]

Whitelist of allowed tools (security).

Example:

{
  command: 'npx',
  args: ['@modelcontextprotocol/server-filesystem', './src'],
  allowedTools: ['read_file', 'list_directory']  // No write access
}

Security Best Practice: Always specify allowedTools to limit what the agent can do.

---

PromptMessage

Message format for structured prompts (from prompt() helper).

interface PromptMessage {
  type: 'text' | 'image' | 'file';
  content: string | Buffer;
  mimeType?: string;
}

Created by prompt() helper:

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

const messages = prompt({
  text: 'Implement this design',
  images: ['./mockup.png'],
  files: ['./spec.md']
});

const result = await runAgent({ prompt: messages });

See Also:

• prompt() → - Helper function
• Multi-Modal Prompts → - Usage guide

---

Complete Examples

Agent Definition

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

const architect = defineAgent({
  name: 'system-architect',
  model: 'claude-opus-4-20250514',
  systemPrompt: `You are a system architect specializing in scalable, maintainable designs.
    Focus on: modularity, separation of concerns, and future extensibility.`,
  mcpServers: {
    filesystem: {
      command: 'npx',
      args: ['@modelcontextprotocol/server-filesystem', './src'],
      allowedTools: ['read_file', 'list_directory']
    }
  },
  defaults: {
    workspace: process.cwd(),
    timeout: 600_000,
    maxTurns: 30
  }
});

Run Configuration

vibeTest('complex implementation', async ({ runAgent, expect }) => {
  const result = await runAgent({
    prompt: '/implement OAuth2 flow with PKCE',
    agent: architect,
    model: 'claude-opus-4-20250514',  // Override for this run
    workspace: './packages/auth',
    timeout: 900_000,  // 15 minutes
    maxTurns: 40,
    mcpServers: {
      database: {
        command: 'npx',
        args: ['@modelcontextprotocol/server-postgres'],
        env: {
          DATABASE_URL: process.env.TEST_DB_URL
        },
        allowedTools: ['query', 'schema']
      }
    }
  });

  expect(result.files).toHaveChangedFiles(['src/auth/**']);
  expect(result.tools.failed()).toHaveLength(0);
});

Workflow Configuration

vibeWorkflow('deployment pipeline', async (wf) => {
  // Stage 1: Build with Sonnet (fast)
  await wf.stage('build', {
    prompt: '/build production bundle',
    model: 'claude-sonnet-4-5-20250929'
  });

  // Stage 2: Security audit with Opus (thorough)
  await wf.stage('security audit', {
    prompt: '/audit security vulnerabilities',
    model: 'claude-opus-4-20250514'
  });

  // Stage 3: Deploy with Haiku (simple task)
  await wf.stage('deploy', {
    prompt: '/deploy to production',
    model: 'claude-haiku-4-20250514'
  });
}, {
  timeout: 1_200_000,  // 20 minutes total
  defaults: {
    workspace: process.cwd(),
    model: 'claude-sonnet-4-5-20250929'
  }
});

Multi-Modal Configuration

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

vibeTest('implement from design', async ({ runAgent, expect }) => {
  const result = await runAgent({
    prompt: prompt({
      text: `Implement the login page based on the mockup and spec.
             Use the component library from design-system.md.`,
      images: ['./designs/login-mockup.png'],
      files: [
        './specs/auth-requirements.md',
        './docs/design-system.md'
      ]
    }),
    model: 'claude-opus-4-20250514',
    workspace: './packages/web'
  });

  expect(result.files).toHaveChangedFiles(['src/pages/login.tsx']);
});

---

Configuration Precedence

When multiple configuration sources are present, they override in this order (highest to lowest):

1. Run-level options (highest priority)

   await runAgent({
     prompt: '/task',
     model: 'claude-opus-4-20250514'  // ← Highest priority
   });

2. Agent defaults

   const agent = defineAgent({
     name: 'my-agent',
     defaults: {
       model: 'claude-sonnet-4-5-20250929'  // ← Medium priority
     }
   });

3. Workflow defaults (for workflows only)

   vibeWorkflow('wf', async (wf) => { ... }, {
     defaults: {
       model: 'claude-haiku-4-20250514'  // ← Low priority (workflow only)
     }
   });

4. Global defaults (lowest priority)

   • Built-in framework defaults

Example:

const agent = defineAgent({
  name: 'builder',
  model: 'claude-sonnet-4-5-20250929',
  defaults: {
    timeout: 300_000
  }
});

// This run will use:
// - model: 'claude-opus-4-20250514' (run-level override)
// - timeout: 600_000 (run-level override)
// - workspace: agent.defaults.workspace (from agent)
const result = await runAgent({
  agent,
  prompt: '/task',
  model: 'claude-opus-4-20250514',  // Override agent's model
  timeout: 600_000  // Override agent's timeout
});

---

See Also

• defineAgent() → - Creating agents
• runAgent() → - Running agents
• vibeWorkflow() → - Building workflows
• prompt() → - Structured prompts
• MCP Servers → - MCP integration
• Cost Optimization → - Model selection