SDK & Programmatic Access

npm install @vesper/sdk

import { Vesper CodeClient } from '@vesper/sdk'

const client = new Vesper CodeClient({
  apiKey: process.env.VESPER_API_KEY,
  cwd: process.cwd(),
})

const result = await client.run({
  agent: 'vesper/base@0.0.16',
  prompt: 'Create a simple calculator class',
  handleEvent: (event) => {
    console.log('Event:', event.type)
  },
})

// First run
const run1 = await client.run({
  agent: 'vesper/base@0.0.16',
  prompt: 'Create a calculator class',
})

// Continue the conversation
const run2 = await client.run({
  agent: 'vesper/base@0.0.16',
  prompt: 'Add unit tests for the calculator',
  previousRun: run1, // Maintains conversation context
})

import type { AgentDefinition } from '@vesper/sdk'

const myAgent: AgentDefinition = {
  id: 'my-custom-agent',
  model: 'anthropic/claude-sonnet-4.5',
  displayName: 'My Custom Agent',
  toolNames: ['read_files', 'write_file'],
  instructionsPrompt: 'You are a helpful coding assistant.',
}

await client.run({
  agent: 'my-custom-agent',
  prompt: 'Help me refactor this code',
  agentDefinitions: [myAgent],
})

import { z } from 'zod/v4'
import { getCustomToolDefinition } from '@vesper/sdk'

const fetchTool = getCustomToolDefinition({
  toolName: 'fetch_api_data',
  description: 'Fetch data from an API endpoint',
  inputSchema: z.object({
    url: z.url(),
    method: z.enum(['GET', 'POST']).default('GET'),
  }),
  execute: async ({ url, method }) => {
    const response = await fetch(url, { method })
    const data = await response.text()
    return [{ type: 'json', value: { data } }]
  },
})

await client.run({
  agent: 'my-custom-agent',
  prompt: 'Fetch the latest data',
  customToolDefinitions: [fetchTool],
})

import { loadLocalAgents, Vesper CodeClient } from '@vesper/sdk'

const agents = await loadLocalAgents({ verbose: true })

const client = new Vesper CodeClient({ apiKey: process.env.VESPER_API_KEY })
await client.run({
  agent: 'my-local-agent',
  agentDefinitions: Object.values(agents),
  prompt: 'Hello',
})

const client = new Vesper CodeClient({
  apiKey: string,        // Required: Your Vesper Code API key
  cwd?: string,          // Working directory for file operations
})

import { Vesper CodeClient } from '@vesper/sdk'

const CODE_TO_TEST = `
function add(a: number, b: number): number {
  return a + b;
}

function divide(a: number, b: number): number {
  if (b === 0) throw new Error('Division by zero');
  return a / b;
}
`

async function generateTests(code: string) {
  const client = new Vesper CodeClient({
    apiKey: process.env.VESPER_API_KEY,
  })

  const { output } = await client.run({
    agent: 'vesper/base@latest',
    prompt: `Generate unit tests for these functions using Jest:\n\n${code}`,
  })

  return output
}

import { Vesper CodeClient } from '@vesper/sdk'

async function reviewPullRequest(diff: string) {
  const client = new Vesper CodeClient({
    apiKey: process.env.VESPER_API_KEY,
  })

  const { output } = await client.run({
    agent: 'vesper/reviewer@latest',
    prompt: `Review this code change for bugs, security issues, and best practices:\n\n${diff}`,
  })

  return output
}

import { Vesper CodeClient } from '@vesper/sdk'
import * as fs from 'fs'
import * as path from 'path'

async function addDocstringsToFiles(filePaths: string[]) {
  const client = new Vesper CodeClient({
    apiKey: process.env.VESPER_API_KEY,
  })

  const results = []

  for (const filePath of filePaths) {
    const code = fs.readFileSync(filePath, 'utf-8')

    const { output } = await client.run({
      agent: 'vesper/base@latest',
      prompt: `Add JSDoc comments to all functions in this file:\n\n${code}`,
    })

    results.push({ filePath, output })
  }

  return results
}

// Usage
const files = ['src/utils.ts', 'src/helpers.ts', 'src/api.ts']
await addDocstringsToFiles(files)

import { Vesper CodeClient } from '@vesper/sdk'

const LEGACY_CODE = `
function processData(data) {
  let result = [];
  for (let i = 0; i < data.length; i++) {
    if (data[i].active === true) {
      result.push({
        id: data[i].id,
        name: data[i].name.toUpperCase()
      });
    }
  }
  return result;
}
`

async function refactorCode(code: string) {
  const client = new Vesper CodeClient({
    apiKey: process.env.VESPER_API_KEY,
  })

  const { output } = await client.run({
    agent: 'vesper/base@latest',
    prompt: `Refactor this code to use modern JavaScript (arrow functions, 
             destructuring, array methods like filter/map):\n\n${code}`,
  })

  return output
}

import { Vesper CodeClient } from '@vesper/sdk'
import * as fs from 'fs'

async function generateComponentWithContext() {
  const client = new Vesper CodeClient({
    apiKey: process.env.VESPER_API_KEY,
  })

  // Provide existing files as context
  const projectFiles = {
    'src/types.ts': fs.readFileSync('src/types.ts', 'utf-8'),
    'src/components/Button.tsx': fs.readFileSync('src/components/Button.tsx', 'utf-8'),
  }

  const { output } = await client.run({
    agent: 'vesper/base@latest',
    prompt: 'Create a new Card component that follows the same patterns as Button',
    projectFiles,
  })

  return output
}

name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get diff
        id: diff
        run: echo "diff=$(git diff origin/main...HEAD)" >> $GITHUB_OUTPUT

      - name: Run AI Review
        run: |
          npx ts-node scripts/ai-review.ts "${{ steps.diff.outputs.diff }}"
        env:
          VESPER_API_KEY: ${{ secrets.VESPER_API_KEY }}