API Reference

API Reference

Quick Reference

• SDK Package: @codebuff/sdk (npm)
• Auth Method: API Key (Bearer token)
• Response Format: JSON
• SDK Version: 0.10.7

SDK API

CodebuffClient

The primary entry point for programmatic use.

import { CodebuffClient } from '@codebuff/sdk'

const client = new CodebuffClient({
  apiKey: string,          // Required: API key
  cwd: string,             // Required: Working directory
  onError?: (error) => void,  // Optional: Error handler
})

(sdk/src/client.ts)

client.run()

Execute an agent run.

Parameter	Type	Required	Description
agent	string	✅	Agent ID to run (base, base-max, custom)
prompt	string	✅	Natural language instruction
agentDefinitions	AgentDefinition[]	❌	Custom agent definitions
customToolDefinitions	ToolDefinition[]	❌	Custom tool definitions
handleEvent	(event) => void	❌	Progress event handler

(sdk/src/run.ts)

TypeScript Example

const result = await client.run({
  agent: 'base',
  prompt: 'Add error handling to all API endpoints',
  handleEvent: (event) => {
    console.log('Progress:', event)
  },
})

AgentDefinition

Define a custom agent.

Field	Type	Required	Description
id	string	✅	Unique agent identifier
displayName	string	✅	Human-readable name
model	string	✅	LLM model identifier (OpenRouter format)
toolNames	string[]	❌	Allowed tools
instructionsPrompt	string	❌	System prompt
handleSteps	AsyncGenerator	❌	Programmatic step generator

(sdk/src/types/)

CLI Commands

Command	Description	Usage
codebuff	Start interactive chat	codebuff [prompt]
codebuff login	Authenticate via GitHub	codebuff login
codebuff publish	Publish agents to Store	codebuff publish [agent-ids]
codebuff --agent <id>	Run specific agent	codebuff --agent git-committer
codebuff --continue	Resume conversation	codebuff --continue [id]
codebuff --free	Free (cost-optimized) mode	codebuff --free
codebuff --max	Max (high-capability) mode	codebuff --max
codebuff --plan	Planning mode	codebuff --plan
codebuff --cwd <dir>	Set working directory	codebuff --cwd ./project
codebuff --version	Print version	codebuff -v

(cli/src/index.tsx:100-127)

Slash Commands (In-CLI)

Command	Description
/init	Initialize agent infrastructure
/help	Show help information
/image	Analyze an image
/referral	View referral code
/usage	Check credit usage

(cli/src/commands/command-registry.ts)

Tool Definitions

All 33 built-in tools available to agents:

File Operations

Tool	Parameters	Description
read_files	paths: string[]	Read contents of multiple files
write_file	path: string, content: string	Create or overwrite a file
str_replace	path: string, old: string, new: string	Replace text in a file
apply_patch	patch: string	Apply a unified diff patch
find_files	query: string	Find files by name or pattern
glob	pattern: string	Glob pattern file search
list_directory	path: string	List directory contents
read_subtree	path: string	Read directory tree structure

Code Intelligence

Tool	Parameters	Description
code_search	query: string	Semantic code search
read_docs	source: string	Read documentation
web_search	query: string	Search the web

Terminal

Tool	Parameters	Description
run_terminal_command	command: string	Execute shell command
browser_logs	—	Capture browser console logs

Agent Orchestration

Tool	Parameters	Description
spawn_agents	configs: AgentConfig[]	Spawn sub-agents
spawn_agent_inline	config: AgentConfig	Spawn inline sub-agent
end_turn	—	End current agent turn
task_completed	summary: string	Mark task as complete

Planning & Reasoning

Tool	Parameters	Description
create_plan	plan: string	Create execution plan
think_deeply	thought: string	Deep reasoning step
add_subgoal	goal: string	Add a subgoal
update_subgoal	id: string, status: string	Update subgoal status
write_todos	todos: string[]	Write todo list

Communication

Tool	Parameters	Description
ask_user	question: string	Ask user a question
add_message	message: string	Add to conversation
set_messages	messages: Message[]	Set conversation messages
suggest_followups	suggestions: string[]	Suggest follow-up actions
set_output	output: string	Set agent output

Misc

Tool	Parameters	Description
skill	name: string	Execute a skill
lookup_agent_info	id: string	Look up agent details
propose_str_replace	...	Propose a code change
propose_write_file	...	Propose file creation
run_file_change_hooks	...	Run post-change hooks

(common/src/tools/list.ts, common/src/tools/params/tool/)

Error Codes

Code	Name	Description
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions
402	Payment Required	Insufficient credits
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

API keys should never be exposed in client-side code. Use server-side proxying or environment variables.

Related Pages

• SDK Integration — Step-by-step SDK guide
• Custom Agents — Agent definition guide
• Architecture — System architecture