Codebuff

Creating Your First Agent

Video Walkthrough

Install and Initialize

bash
npm install -g codebuff

In your project, start Codebuff and run the /init command:

bash
codebuff

Then inside the CLI:

text
/init

This creates:

  • knowledge.md - project context for Codebuff
  • .agents/types/ - TypeScript type definitions for creating agents

Create an Agent

.agents/simple-code-reviewer.ts:

typescript
import type { AgentDefinition } from './types/agent-definition'


const definition: AgentDefinition = {
  id: 'simple-code-reviewer',
  displayName: 'Simple Code Reviewer',
  model: 'anthropic/claude-sonnet-4.5',


  // Tools this agent can use
  toolNames: [
    'read_files',
    'run_terminal_command',
    'code_search',
    'spawn_agents',
  ],


  // Other agents this agent can spawn
  // Browse https://www.codebuff.com/store to see available agents
  spawnableAgents: ['codebuff/file-explorer@0.0.2'],


  // When should other agents spawn this one?
  spawnerPrompt: 'Spawn when you need to review local code changes',


  // System prompt defines the agent's identity
  systemPrompt: `You are an expert software developer specializing in code review.
Your job is to review code changes and provide helpful, constructive feedback.`,


  // Instructions for what the agent should do
  instructionsPrompt: `Review code changes by following these steps:
1. Use git diff to see what changed
2. Read the modified files to understand the context
3. Look for potential issues: bugs, security problems, style violations
4. Suggest specific improvements with examples
5. Highlight what was done well`,
}


export default definition

@Bob the Agent Builder in Codebuff can also help.

Test Locally

bash
codebuff

Then:

text
@Simple Code Reviewer please review my recent changes

Make some local changes first so it has something to inspect.

Create a Publisher Profile

codebuff.com/publishers/new

Fill in your publisher name and ID.

Prepare for Publishing

Add your publisher ID:

typescript
// Add this field to your agent definition
const definition: AgentDefinition = {
  id: 'simple-code-reviewer',
  displayName: 'Simple Code Reviewer',
  publisher: 'your-publisher-id', // ← Add this line
  model: 'anthropic/claude-sonnet-4.5',
  // ... rest of your definition
}

Publish

bash
codebuff publish simple-code-reviewer

Use Your Published Agent

bash
codebuff --agent your-publisher-id/simple-code-reviewer@0.0.1

Advanced: Programmatic Control

Use handleSteps for programmatic control:

.agents/deep-code-reviewer.ts:

typescript
import type { AgentDefinition } from './types/agent-definition'


const definition: AgentDefinition = {
  id: 'deep-code-reviewer',
  displayName: 'Deep Code Reviewer',
  publisher: 'your-publisher-id',
  model: 'anthropic/claude-sonnet-4.5',


  spawnerPrompt:
    'Spawn when you need to review code changes in the git diff or staged changes',


  toolNames: [
    'read_files',
    'code_search',
    'run_terminal_command',
    'spawn_agents',
  ],


  // Use fully qualified agent names with publisher and version
  // Browse https://www.codebuff.com/store to see available agents
  spawnableAgents: [
    'codebuff/file-explorer@0.0.4',
    'codebuff/deep-thinker@0.0.3',
  ],


  instructionsPrompt: `Review code changes:
1. Analyze git diff and untracked files
2. Find related files using file explorer
3. Look for simplification opportunities
4. Check for logical errors and edge cases`,


  handleSteps: function* () {
    // Step 1: Get changed files from git
    const { toolResult: gitDiffResult } = yield {
      toolName: 'run_terminal_command',
      input: { command: 'git diff HEAD --name-only' },
    }


    // Step 2: Get untracked files
    const { toolResult: gitStatusResult } = yield {
      toolName: 'run_terminal_command',
      input: { command: 'git status --porcelain' },
    }


    // Step 3: Show the actual diff
    yield {
      toolName: 'run_terminal_command',
      input: { command: 'git diff HEAD' },
    }


    // Step 4: Parse file paths (with error handling)
    const changedFiles = (gitDiffResult || '')
      .split('\n')
      .map((line) => line.trim())
      .filter((line) => line && !line.includes('OSC'))


    const untrackedFiles = (gitStatusResult || '')
      .split('\n')
      .filter((line) => line.startsWith('??'))
      .map((line) => line.substring(3).trim())
      .filter((file) => file)


    const allFiles = [...changedFiles, ...untrackedFiles]


    // Step 5: Read all the files
    if (allFiles.length > 0) {
      yield {
        toolName: 'read_files',
        input: { paths: allFiles },
      }
    }


    // Step 6: Spawn file explorer to find related files
    yield {
      toolName: 'spawn_agents',
      input: {
        agents: [
          {
            agent_type: 'codebuff/file-explorer@0.0.1',
            prompt: 'Find files related to the changed code',
          },
        ],
      },
    }


    // Step 7: Let the LLM generate the final review
    yield 'STEP_ALL'
  },
}


export default definition

handleSteps Basics

yield tool calls - execute tools:

typescript
const { toolResult, toolError } = yield {
  toolName: 'run_terminal_command',
  input: { command: 'git status' }
}

yield 'STEP_ALL' - LLM runs until completion

yield 'STEP' - LLM takes one turn, then back to your code

return - end execution

Use handleSteps for complex workflows with branching logic. Use prompts-only for straightforward tasks.

Spawnable Agents

From the Agent Store - use full IDs:

typescript
spawnableAgents: [
  'codebuff/file-explorer@0.0.4', // ✅ Correct
  'john-smith/security-scanner@2.1.4', // ✅ Correct
]

Local agents - just the ID:

typescript
spawnableAgents: [
  'my-custom-reviewer', // ✅ Correct for local agent
  'database-migrator', // ✅ Correct for local agent
  'codebuff/file-explorer@0.0.4', // ✅ Also correct: you can mix local and published agents.
]