Skip to main content

​
Quick Start with SDK

The Codebuff SDK allows you to run AI coding agents programmatically in your Node.js applications.

​
Installation

npm install @codebuff/sdk

​
Basic SDK Usage

Here’s a simple example of running the base Codebuff agent: 
import { CodebuffClient } from '@codebuff/sdk'

const client = new CodebuffClient({
  apiKey: process.env.CODEBUFF_API_KEY,
  cwd: process.cwd(),
})

const result = await client.run({
  agent: 'codebuff/[email protected]',
  prompt: 'Create a simple calculator class',
  handleEvent: (event) => {
    console.log('Event:', JSON.stringify(event))
  },
})

if (result.output.type === 'error') {
  console.error('Error:', result.output.message)
} else {
  console.log('Success!', result.output)
}

​
Continuing a Conversation

You can continue a session by passing the previous run state: 
// First run
const runState1 = await client.run({
  agent: 'codebuff/[email protected]',
  prompt: 'Create a simple calculator class',
  handleEvent: (event) => {
    console.log('Codebuff Event', JSON.stringify(event))
  },
})

// Continue with follow-up
const runState2 = await client.run({
  agent: 'codebuff/[email protected]',
  prompt: 'Add unit tests for the calculator',
  previousRun: runState1, // Pass the previous state
  handleEvent: (event) => {
    console.log('Codebuff Event', JSON.stringify(event))
  },
})

​
CLI Usage

​
Installation

npm install -g codebuff

​
Running Codebuff CLI

cd your-project
codebuff
Then just tell Codebuff what you want:
  • “Fix the SQL injection vulnerability in user registration”
  • “Add rate limiting to all API endpoints”
  • “Refactor the database connection code for better performance”

​
Initialize Custom Agents

Start Codebuff and run the /init command to set up custom agent development: 
codebuff
Then inside the CLI: 
/init
This creates: 
knowledge.md               # Project context for Codebuff
.agents/
└── types/                 # TypeScript type definitions
    ├── agent-definition.ts
    ├── tools.ts
    └── util-types.ts

​
Handling Events

The handleEvent callback receives every event during execution: 
const result = await client.run({
  agent: 'codebuff/[email protected]',
  prompt: 'Add error handling to API endpoints',
  handleEvent: (event) => {
    switch (event.type) {
      case 'agent_start':
        console.log('Agent started:', event.agentId)
        break
      case 'tool_call':
        console.log('Tool called:', event.toolName)
        break
      case 'text_response':
        console.log('Response:', event.text)
        break
      case 'error':
        console.error('Error occurred:', event.message)
        break
    }
  },
})

​
Streaming Output

You can stream the agent’s output in real-time: 
const result = await client.run({
  agent: 'codebuff/base2@latest',
  prompt: 'Review this code for bugs',
  handleStreamChunk: (chunk) => {
    if (typeof chunk === 'string') {
      process.stdout.write(chunk)
    }
  },
})

​
Error Handling

Always check the output type to handle errors: 
const result = await client.run({
  agent: 'codebuff/[email protected]',
  prompt: 'Add authentication',
  handleEvent: (event) => {
    if (event.type === 'error') {
      console.error('Runtime error:', event.message)
    }
  },
})

if (result.output.type === 'error') {
  console.error('Run failed:', result.output.message)
  process.exit(1)
}

console.log('Run succeeded:', result.output)

​
Configuration Options

The CodebuffClient constructor accepts several options: 
const client = new CodebuffClient({
  // Required: Your API key from https://www.codebuff.com/api-keys
  apiKey: process.env.CODEBUFF_API_KEY,
  
  // Optional: Working directory for file operations
  cwd: process.cwd(),
  
  // Optional: Custom error handler
  onError: (error) => {
    console.error('Codebuff error:', error.message)
  },
})

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us