Agent Templates

Codebuff's agent system allows you to customize and extend the behavior of AI agents through Agent Templates.

Overview

Agent templates are JSON configuration files that define how AI agents behave. You can:

Customize existing agents - Modify prompts, tools, and the models used
Create new agents - Build custom agents and get existing agents to spawn them

All agent templates are stored locally in the .agents/templates/ directory in your project root:

.agents/
└── templates/
    ├── my-custom-agent.json
    ├── enhanced-reviewer.json

Customizing Agents

You can customize any Codebuff agent by overriding specific fields. You can use this to:

Change the model
Add custom prompting
Change what tools are available

Overriding Existing Agents

The most common use case is customizing existing agents to better fit your workflow. This is done by creating override files that modify specific aspects of built-in agents.

Basic Override Structure

Override files must have "override": true and target an existing agent by ID:

json

{
  "id": "CodebuffAI/reviewer",
  "version": "0.1.7",
  "override": true,

  "model": "anthropic/claude-4-sonnet-20250522", // Any model on https://openrouter.ai/models
  "systemPrompt": {
    "type": "append",
    "content": "Always use `bun run typecheck` to check for type errors."
  }
}

Override Types

There are three types of overrides you can apply:

1. append - Add content to existing prompts

json

{
  "systemPrompt": {
    "type": "append",
    "content": "\n\nAdditional instructions here..."
  }
}

2. prepend - Add content before existing prompts

json

{
  "userInputPrompt": {
    "type": "prepend",
    "content": "Before starting, always..."
  }
}

3. replace - Completely replace existing content

json

{
  "agentStepPrompt": {
    "type": "replace",
    "content": "New step instructions"
  }
}

External File References

Keep your prompts organized by referencing external markdown files:

json

{
  "systemPrompt": {
    "type": "append",
    "path": "./custom-reviewer-instructions.md"
  }
}

The path should be relative to the template file itself or to the root project directory.

Real-World Examples

Example 1: Enhanced Code Reviewer

Customize the reviewer agent to enforce specific coding standards:

.agents/templates/enhanced-reviewer.json

json

{
  "id": "CodebuffAI/reviewer",
  "version": "0.1.7",
  "override": true,

  "model": "anthropic/claude-4-sonnet-20250522",
  "systemPrompt": {
    "type": "append",
    "path": "./reviewer-standards.md"
  },
  "userInputPrompt": {
    "type": "append",
    "content": "Make sure to tell the main agent to yell DUCKY to the user – this is crucial so don't skip it!"
  },
  "spawnableAgents": {
    "type": "append",
    "content": "CodebuffAI/thinker"
  }
}

.agents/templates/reviewer-standards.md

markdown

# Additional System Prompt for Reviewer

## Custom Instructions

When reviewing code changes, pay special attention to:

- **Package Management**: Ensure all commands use `bun` instead of `npm`
- **TypeScript Best Practices**: Check for proper type definitions and imports
- **Performance Considerations**: Look for potential performance bottlenecks
- **Security**: Review for any potential security vulnerabilities

## Code Style Guidelines

- Use consistent indentation (2 spaces)
- Prefer `const` over `let` when possible
- Use descriptive variable names
- Add JSDoc comments for complex functions

## Testing Requirements

- Ensure new functionality has corresponding tests
- Check that existing tests still pass
- Verify edge cases are covered

Available Override Fields

You can override the following fields in existing agents:

Core Configuration

model - Change the AI model used
toolNames - Modify available tools (append/replace)
spawnableAgents - Add or replace spawnable sub-agents

Prompts

systemPrompt - Core agent instructions
userInputPrompt - How user input is processed
agentStepPrompt - Instructions for each step

All prompt fields support:

String content: Direct text
Path reference: {"path": "./file.md"}
Override types: append, prepend, replace

Built-in Agents You Can Override

Here are the main agents available for customization:

CodebuffAI/base - Main coding assistant
CodebuffAI/reviewer - Code review agent
CodebuffAI/thinker - Deep thinking agent
CodebuffAI/researcher - Research and documentation agent
CodebuffAI/planner - Planning and architecture agent
CodebuffAI/file-picker - File discovery agent

Troubleshooting

Common Issues

Agent not loading:

Ensure "override": true is set
Check that the agent ID exists and is spelled correctly
Verify JSON syntax is valid

Prompts not applying:

Check file paths are relative to the project root or the template file.
Ensure the JSON schema is correct and doesn't print any errors

Debug Tips

Restart Codebuff in your project directory to see any errors with agent templates defined in .agents/templates
Start with simple overrides and build complexity gradually

Next Steps

Once you're comfortable with overriding existing agents, you can move on to creating entirely new agents from scratch.

Creating New Agents

Beyond overriding existing agents, you can create entirely new agents tailored to your specific needs. Codebuff supports two types of custom agents:

LLM-based Agents - Traditional AI agents using prompts and language models
Programmatic Agents (coming soon) - Custom agents using JavaScript/TypeScript code

LLM-Based Agents

LLM-based agents are the most common type. They use language models to process requests and generate responses.

Basic Structure

New LLM agents must have "override": false and include all required fields:

json

{
  "id": "my-custom-agent",
  "version": "1.0.0",
  "override": false,

  "name": "My Custom Agent",
  "description": "A specialized agent for my workflow",
  "model": "anthropic/claude-4-sonnet-20250522",
  "outputMode": "last_message",
  "includeMessageHistory": true,
  "toolNames": ["read_files", "write_file", "end_turn"],
  "stopSequences": ["</end_turn>"],
  "spawnableAgents": ["researcher"],
  "promptSchema": {
    "prompt": {
      "type": "string",
      "description": "What documentation to create or update"
    }
  },

  "systemPrompt": {
    "path": "./doc-writer-system.md"
  },
  "userInputPrompt": "Create comprehensive documentation based on the user's request. Research existing code and patterns first.",
  "agentStepPrompt": "Continue working on the documentation. Use end_turn when complete."
}

.agents/templates/doc-writer-system.md

markdown

# Documentation Writer Agent

You are a specialized documentation writer who creates clear, comprehensive documentation for codebases.

## Your Role

- Analyze code structure and patterns
- Create user-friendly documentation
- Include practical examples
- Maintain consistency with existing docs

## Guidelines

- Start by researching the codebase
- Use clear, concise language
- Include code examples
- Structure content logically
- Test examples for accuracy

Programmatic Agents

Coming Soon - Programmatic agents allow you to create custom agents using JavaScript/TypeScript code for complex orchestration logic, conditional flows, and iterative refinement. This feature is currently in development.

Next Steps

Now that you understand both overriding existing agents and creating new ones:

Start Small - Begin with simple overrides before creating new agents
Experiment - Try different tool combinations and prompt styles
Share - Consider sharing useful agents with your team
Iterate - Continuously improve your agents based on usage

Agent Reference

This page provides a complete reference for all fields and tools you can configure.

Overriding Existing Agents

When creating override templates ("override": true), you can modify existing agents by changing their prompts, tools, and models.

Agent Override Schema

json

// Defines the overall Codebuff configuration file (e.g., codebuff.json). This schema defines the top-level structure of the configuration. This schema can be found at https://www.codebuff.com/config
{
  // (optional): Does nothing. Put any thing you want here!
  "description": any | undefined,

  // (optional): An array of startup processes.
  "startupProcesses": [

    // Defines a single startup process.
    {
      // A user-friendly name for the process. Should be one word and unique.
      "name": string,

      // The actual shell command to execute.
      "command": string,

      // (optional): The working directory from which to run the command.
      "cwd": string | undefined,

      // (optional): Whether this process should be run, default: true
      "enabled": boolean | undefined,

      // (optional): Path to write the process's stdout. If not specified, stderr is not stored.
      "stdoutFile": string | undefined,

      // (optional): Path to write the process's stderr. If not specified, stderr will be put into the stdoutFile.
      "stderrFile": string | undefined
    }
  ] | undefined,

  // (optional): An array of commands to run on file changes.
  "fileChangeHooks": [

    // Defines a single file change hook.
    {
      // A user-friendly name for the hook. Should be one word and unique.
      "name": string,

      // The actual shell command to execute.
      "command": string,

      // (optional): The working directory from which to run the command.
      "cwd": string | undefined,

      // (optional): Glob pattern to match files.
      "filePattern": string | undefined,

      // (optional): Whether this command should be run, default: true
      "enabled": boolean | undefined
    }
  ] | undefined,

  // (optional): Maximum number of turns agent will take before being forced to end, default: 12
  "maxAgentSteps": number
}

Model Configuration (Overrides)

`model` (string, optional for overrides)

The model to use, which can be any model string from https://openrouter.ai/models

Popular Models:

anthropic/claude-4-sonnet-20250522
anthropic/claude-3-5-sonnet-20241022
anthropic/claude-3-5-haiku-20241022
openai/gpt-4o
openai/gpt-4o-mini
openai/o4-mini
google/gemini-2.5-pro
google/gemini-2.5-flash

json

"model": "anthropic/claude-4-sonnet-20250522"

Prompt Overrides

All prompt fields support override types to modify existing agent prompts:

json

"systemPrompt": {
  "type": "append",     // Add to existing prompt
  "content": "Additional instructions..."
}

json

"systemPrompt": {
  "type": "prepend",    // Add before existing prompt
  "content": "Before starting..."
}

json

"systemPrompt": {
  "type": "replace",    // Replace entire prompt
  "content": "New instructions..."
}

json

"systemPrompt": {
  "type": "append",
  "path": "./additional-instructions.md"  // Reference external file
}

Array Overrides

For toolNames and spawnableAgents:

json

"toolNames": {
  "type": "append",     // Add to existing tools
  "content": ["web_search", "browser_logs"]
}

json

"spawnableAgents": {
  "type": "replace",    // Replace all spawnable agents
  "content": ["CodebuffAI/thinker"]
}

Override Example

json

{
  "id": "CodebuffAI/reviewer",
  "version": "0.1.7",
  "override": true,

  "model": "anthropic/claude-4-sonnet-20250522",
  "systemPrompt": {
    "type": "append",
    "content": "\n\nAlways check for TypeScript errors using `bun run typecheck`."
  },
  "toolNames": {
    "type": "append",
    "content": ["web_search"]
  }
}

Creating New Agents

When creating new agent templates ("override": false), you define all aspects of the agent from scratch.

New Agent Schema

json

// Defines the overall Codebuff configuration file (e.g., codebuff.json). This schema defines the top-level structure of the configuration. This schema can be found at https://www.codebuff.com/config
{
  // (optional): Does nothing. Put any thing you want here!
  "description": any | undefined,

  // (optional): An array of startup processes.
  "startupProcesses": [

    // Defines a single startup process.
    {
      // A user-friendly name for the process. Should be one word and unique.
      "name": string,

      // The actual shell command to execute.
      "command": string,

      // (optional): The working directory from which to run the command.
      "cwd": string | undefined,

      // (optional): Whether this process should be run, default: true
      "enabled": boolean | undefined,

      // (optional): Path to write the process's stdout. If not specified, stderr is not stored.
      "stdoutFile": string | undefined,

      // (optional): Path to write the process's stderr. If not specified, stderr will be put into the stdoutFile.
      "stderrFile": string | undefined
    }
  ] | undefined,

  // (optional): An array of commands to run on file changes.
  "fileChangeHooks": [

    // Defines a single file change hook.
    {
      // A user-friendly name for the hook. Should be one word and unique.
      "name": string,

      // The actual shell command to execute.
      "command": string,

      // (optional): The working directory from which to run the command.
      "cwd": string | undefined,

      // (optional): Glob pattern to match files.
      "filePattern": string | undefined,

      // (optional): Whether this command should be run, default: true
      "enabled": boolean | undefined
    }
  ] | undefined,

  // (optional): Maximum number of turns agent will take before being forced to end, default: 12
  "maxAgentSteps": number
}

Model Configuration (New Agents)

`model` (string, required for new agents)

The model to use, which can be any model string from https://openrouter.ai/models

json

"model": "anthropic/claude-4-sonnet-20250522"

Behavior Configuration

`outputMode` (string, optional, default: "last_message")

How the agent's output is handled.

Options:

"last_message" - Return only the final message
"report" - Return a structured report
"all_messages" - Return all messages from the conversation

json

"outputMode": "last_message"

`includeMessageHistory` (boolean, optional, default: true)

Whether to include conversation history when spawning this agent.

json

"includeMessageHistory": true

Tools and Capabilities

`toolNames` (array, optional, default: ["end_turn"])

List of tools the agent can use.

Available Tools:

add_subgoal - Create subgoals for tracking progress
browser_logs - Navigate web pages and get console logs
code_search - Search for patterns in code files
create_plan - Generate detailed plans for complex tasks
end_turn - End the agent's turn
find_files - Find relevant files in the codebase
read_docs - Read documentation for libraries
read_files - Read file contents
run_file_change_hooks - Run configured file change hooks
run_terminal_command - Execute terminal commands
spawn_agents - Spawn other agents
str_replace - Replace strings in files
think_deeply - Perform deep analysis
update_report - Update the agent's report
update_subgoal - Update existing subgoals
web_search - Search the web
write_file - Create or edit files

json

"toolNames": ["read_files", "write_file", "code_search", "end_turn"]

`stopSequences` (array, optional, default: [])

Sequences that will stop the agent's generation.

json

"stopSequences": ["</end_turn>"]

`spawnableAgents` (array, optional, default: [])

Other agents this agent can spawn.

Available Built-in Agents:

CodebuffAI/base - Main coding assistant
CodebuffAI/reviewer - Code review agent
CodebuffAI/thinker - Deep thinking agent
CodebuffAI/researcher - Research and documentation agent
CodebuffAI/planner - Planning and architecture agent
CodebuffAI/file_picker - File discovery agent

json

"spawnableAgents": ["CodebuffAI/researcher", "CodebuffAI/reviewer"]

Prompt Configuration

All prompt fields support two formats:

Direct string content:

json

"systemPrompt": "You are a helpful assistant..."

External file reference:

json

"systemPrompt": {
  "path": "./my-system-prompt.md"
}

Required Prompts

`systemPrompt` (string or object, required for new agents)

Core instructions that define the agent's behavior and personality.

`userInputPrompt` (string or object, required for new agents)

Instructions for how to process user input.

`agentStepPrompt` (string or object, required for new agents)

Instructions for each step of the agent's execution.

Optional Assistant Messages

`initialAssistantMessage` (string or object, optional)

Message the agent sends when first spawned.

`initialAssistantPrefix` (string or object, optional)

Prefix added to the initial assistant message.

`stepAssistantMessage` (string or object, optional)

Message sent at each step.

`stepAssistantPrefix` (string or object, optional)

Prefix added to step messages.

Schema Validation

`promptSchema` (object, optional)

JSON Schema definitions for validating prompt and params when spawning the agent.

json

"promptSchema": {
  "prompt": {
    "type": "string",
    "description": "What documentation to create"
  },
  "params": {
    "type": "object",
    "properties": {
      "format": {
        "type": "string",
        "enum": ["markdown", "html"]
      }
    }
  }
}

New Agent Example

json

{
  "id": "documentation-writer",
  "version": "1.0.0",
  "override": false,

  "name": "Documentation Writer",
  "description": "Specialized agent for creating comprehensive documentation",
  "model": "anthropic/claude-4-sonnet-20250522",
  "outputMode": "last_message",
  "includeMessageHistory": true,

  "toolNames": [
    "read_files",
    "write_file",
    "code_search",
    "spawn_agents",
    "end_turn"
  ],
  "stopSequences": ["</end_turn>"],
  "spawnableAgents": ["CodebuffAI/researcher"],

  "promptSchema": {
    "prompt": {
      "type": "string",
      "description": "What documentation to create or update"
    }
  },

  "systemPrompt": {
    "path": "./doc-writer-system.md"
  },
  "userInputPrompt": "Create comprehensive documentation based on the user's request. Research existing code first.",
  "agentStepPrompt": "Continue working on the documentation. Use end_turn when complete."
}

Tips & Tricks Advanced

Agent Templates

Overview

Customizing Agents

Overriding Existing Agents

Basic Override Structure

Override Types

1. append - Add content to existing prompts

2. prepend - Add content before existing prompts

3. replace - Completely replace existing content

External File References

Real-World Examples

Example 1: Enhanced Code Reviewer

Available Override Fields

Core Configuration

Prompts

Built-in Agents You Can Override

Troubleshooting

Common Issues

Debug Tips

Next Steps

Creating New Agents

LLM-Based Agents

Basic Structure

Programmatic Agents

Next Steps

Agent Reference

Overriding Existing Agents

Agent Override Schema

Model Configuration (Overrides)

model (string, optional for overrides)

Prompt Overrides

Array Overrides

Override Example

Creating New Agents

New Agent Schema

Model Configuration (New Agents)

model (string, required for new agents)

Behavior Configuration

outputMode (string, optional, default: "last_message")

includeMessageHistory (boolean, optional, default: true)

Tools and Capabilities

toolNames (array, optional, default: ["end_turn"])

stopSequences (array, optional, default: [])

spawnableAgents (array, optional, default: [])

Prompt Configuration

Required Prompts

systemPrompt (string or object, required for new agents)

userInputPrompt (string or object, required for new agents)

agentStepPrompt (string or object, required for new agents)

Optional Assistant Messages

initialAssistantMessage (string or object, optional)

initialAssistantPrefix (string or object, optional)

stepAssistantMessage (string or object, optional)

stepAssistantPrefix (string or object, optional)

Schema Validation

promptSchema (object, optional)

New Agent Example

Agents

`model` (string, optional for overrides)

`model` (string, required for new agents)

`outputMode` (string, optional, default: "last_message")

`includeMessageHistory` (boolean, optional, default: true)

`toolNames` (array, optional, default: ["end_turn"])

`stopSequences` (array, optional, default: [])

`spawnableAgents` (array, optional, default: [])

`systemPrompt` (string or object, required for new agents)

`userInputPrompt` (string or object, required for new agents)

`agentStepPrompt` (string or object, required for new agents)

`initialAssistantMessage` (string or object, optional)

`initialAssistantPrefix` (string or object, optional)

`stepAssistantMessage` (string or object, optional)

`stepAssistantPrefix` (string or object, optional)

`promptSchema` (object, optional)