Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Latest commit

 

History

History
History
 
 

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Outline

@codebuff/sdk

Official SDK for Codebuff - AI coding agent and framework

Installation

npm install @codebuff/sdk

Prerequisites

Create a Codebuff account and get your Codebuff API key here.

Usage

Basic Example

import { CodebuffClient } from '@codebuff/sdk'

const client = new CodebuffClient({
  // Note: You need to pass in your own API key here.
  apiKey: process.env.CODEBUFF_API_KEY,
  cwd: process.cwd(),
  onError: (e) => console.error('Codebuff error:', e.message),
})

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

// Continue the same session with a follow-up
const run2 = await client.run({
  agent: 'base',
  prompt: 'Add unit tests for the calculator',
  previousRun: run1,
  handleEvent: (event) => {
    // Log all events
    console.log('Progress:', event)
  },
})

client.closeConnection()

Advanced Example with Custom Agents, Tools, and Images

import { z } from 'zod'
import {
  CodebuffClient,
  generateInitialRunState,
  withAdditionalMessage,
  getCustomToolDefinition,
} from '@codebuff/sdk'

const client = new CodebuffClient({
  // Note: You need to pass in your own API key here.
  apiKey: process.env.CODEBUFF_API_KEY,
  cwd: process.cwd(),
  onError: (e) => console.error('Codebuff error:', e.message),
})

// Create a run with an image
const emptyRun = await generateInitialRunState({ cwd: process.cwd() })
const runWithImage = withAdditionalMessage({
  runState: emptyRun,
  message: {
    role: 'user',
    content: [
      {
        type: 'image',
        image: new URL(
          'https://upload.wikimedia.org/wikipedia/en/a/a9/Example.jpg',
        ),
      },
    ],
  },
})

const result = await client.run({
  agent: 'my-custom-agent',
  prompt: 'Analyze this image and create code based on what you see',
  previousRun: runWithImage,

  // Custom agent definitions
  agentDefinitions: [
    {
      id: 'my-custom-agent',
      model: 'openai/gpt-5',
      displayName: 'Image Analyzer',
      instructionsPrompt:
        '1. describe all the details in the image. 2. answer the user prompt',
      // ... other AgentDefinition properties
    },
  ],

  // Custom tool definitions
  customToolDefinitions: [
    getCustomToolDefinition({
      toolName: 'fetch_api_data',
      description: 'Fetch data from an API endpoint',
      inputSchema: z.object({
        url: z.string().url(),
        method: z.enum(['GET', 'POST']).default('GET'),
        headers: z.record(z.string()).optional(),
      }),
      exampleInputs: [
        { url: 'https://api.example.com/data', method: 'GET' },
        {
          url: 'https://api.example.com/submit',
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
        },
      ],
      handler: async ({ url, method, headers }) => {
        const response = await fetch(url, { method, headers })
        const data = await response.text()
        return {
          toolResultMessage: `API Response: ${data.slice(0, 5000)}...`,
        }
      },
    }),
  ],

  handleEvent: (event) => {
    console.log('Agent progress:', event)
  },
})

client.closeConnection()

API Reference

client.run(options)

Runs a Codebuff agent with the specified options.

Parameters

  • agent (string, required): The agent to run. Use 'base' for the default agent, or specify a custom agent ID if you made your own agent config.

  • prompt (string, required): The user prompt describing what you want the agent to do.

  • params (object, optional): Additional parameters for the agent. Most agents don't use this, but some custom agents can take a JSON object as input in addition to the user prompt string.

  • handleEvent (function, optional): Callback function that receives every event during execution (assistant messages, tool calls, etc.). This allows you to stream the agent's progress in real-time. We will likely add a token-by-token streaming callback in the future.

  • previousRun (object, optional): JSON state returned from a previous run() call. Use this to continue a conversation or session with the agent, maintaining context from previous interactions.

  • projectFiles (object, optional): All the files in your project as a plain JavaScript object. Keys should be the full path from your current directory to each file, and values should be the string contents of the file. Example: { "src/index.ts": "console.log('hi')" }. This helps Codebuff pick good source files for context. Note: This parameter was previously named allFiles but has been renamed for clarity.

  • knowledgeFiles (object, optional): Knowledge files to inject into every run() call. Uses the same schema as projectFiles - keys are file paths and values are file contents. These files are added directly to the agent's context.

  • agentDefinitions (array, optional): Array of custom agent configurations. Each object should satisfy the AgentConfig type.

  • customToolDefinitions (array, optional): Array of custom tool definitions that extend the agent's capabilities. Each tool definition includes a name, Zod schema for input validation, and a handler function. These tools can be called by the agent during execution.

  • maxAgentSteps (number, optional): Maximum number of steps the agent can take before stopping. Use this as a safety measure in case your agent starts going off the rails. A reasonable number is around 20.

Returns

Returns a Promise that resolves to a RunState object which can be passed into subsequent runs via the previousRun parameter to resume the conversation.

License

MIT

Morty Proxy This is a proxified and sanitized view of the page, visit original site.