Skip to main content
The Codebuff SDK provides a programmatic interface for running AI coding agents in your applications. Use it to automate code generation, refactoring, testing, and more.

​
When to Use the SDK

Use the SDK when you want to:
  • Integrate Codebuff agents into your own applications
  • Automate coding tasks in CI/CD pipelines
  • Build custom development tools powered by AI
  • Create workflows that combine multiple agent runs
  • Programmatically control agent behavior
Use the CLI when you want to:
  • Interactively chat with agents during development
  • Quickly iterate on code changes
  • Use agents in your terminal workflow

​
Installation

npm install @codebuff/sdk

​
Prerequisites

Create a Codebuff account and get your Codebuff API key.

​
Basic Example

import { CodebuffClient } from '@codebuff/sdk'

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

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

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

main()

​
Key Concepts

​
Agents

Agents are AI models configured with specific instructions, tools, and capabilities. You can use:

​
Run State

Each client.run() call returns a RunState object containing:
  • sessionState: Internal state for continuing conversations
  • output: The agent’s final output or error

​
Events

The handleEvent callback receives real-time events as the agent executes:
  • Tool calls and results
  • Text responses
  • Subagent spawns
  • Errors

​
Next Steps

CodebuffClient

Learn about client configuration and methods

Running Agents

Master the client.run() method

Custom Agents

Create your own AI agents

Custom Tools

Extend agents with custom capabilities

Build docs developers (and LLMs) love

Get started for freeTalk to us