---
title: 'Creating Your First Agent'
section: 'walkthroughs'
tags: ['walkthrough', 'agents', 'getting-started', 'publishing']
order: 1
---

# Creating Your First Agent

## Video Walkthrough

<div
  style={{
    position: 'relative',
    paddingBottom: '56.25%',
    height: 0,
    overflow: 'hidden',
    maxWidth: '100%',
  }}
>
  <iframe
    src="https://www.youtube.com/embed/mR2OOHv5p_4"
    title="Creating Your First Codebuff Agent"
    frameBorder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
    allowFullScreen
    style={{
      position: 'absolute',
      top: 0,
      left: 0,
      width: '100%',
      height: '100%',
    }}
  ></iframe>
</div>

## Install and Initialize

```bash
npm install -g codebuff
```

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

```bash
codebuff
```

Then inside the CLI:

```
/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:

```
@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](https://www.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.
]
```


