Codebuff

Agent Reference

Loading agent definition types...

Core Configuration

id (string, required)

Unique identifier for this agent. Must contain only lowercase letters, numbers, and hyphens.

json
"id": "code-reviewer"

displayName (string, required)

Human-readable name for the agent.

json
"displayName": "Code Review Specialist"

spawnerPrompt (string, optional)

Tells other agents when to spawn this one.

json
"spawnerPrompt": "Spawn this agent for thorough code review, focusing on bugs, security issues, and best practices"

Model Configuration

model (string, required)

The model to use, which can be any model string from Openrouter.

json
"model": "anthropic/claude-sonnet-4.5"

Reasoning Options (reasoningOptions, object, optional)

Controls model reasoning behavior using OpenRouter-style settings.

Fields:

  • enabled (boolean, default: false) — Turn reasoning mode on for supported models.
  • exclude (boolean, default: false) — If true, omit model-revealed reasoning content from responses (when available), returning only the final answer.
  • effort ("low" | "medium" | "high") — How much the model thinks before answering. Higher = better for hard tasks, more tokens.

Only works on models that support reasoning. Ignored otherwise.

Example:

ts
// .agents/thinker.ts
const definition = {
  id: 'thinker',
  // ... other fields ...
  reasoningOptions: {
    enabled: true,
    exclude: false,
    effort: 'high',
  },
}

Behavior Configuration

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

How the agent's output is handled.

Options:

  • "last_message" - Return only the final message (default)
  • "all_messages" - Return all messages from the conversation
  • "structured_output" - Return a structured JSON object (use with outputSchema)
json
"outputMode": "last_message"

includeMessageHistory (boolean, optional, default: false)

Whether to include conversation history from the parent agent when spawning this agent.

json
"includeMessageHistory": true

outputSchema (object, optional)

JSON Schema for structured output (when outputMode is "structured_output").

json
"outputMode": "structured_output",
"outputSchema": {
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "issues": {
      "type": "array",
      "items": { "type": "string" }
    },
    "score": { "type": "number" }
  },
  "required": ["summary", "issues"]
}

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_subgoal - Update existing subgoals
  • web_search - Search the web
  • write_file - Create or edit files
  • set_output - Set an output JSON object
json
"toolNames": ["read_files", "write_file", "code_search", "end_turn"]

spawnableAgents (array, optional, default: [])

Other agents this agent can spawn. Use the fully qualified agent ID from the agent store (publisher/name@version) or the agent ID from a local agent file.

⚠️ Important: When referencing built-in agents, you must specify both publisher and version (e.g., codebuff/reviewer@0.0.1). Omit publisher/version only for local agents defined in your .agents/ directory.

Referencing Agents:

  • Published/built-in agents: "codebuff/file-picker@0.0.1" (publisher and version required!)
  • Local agents: "my-custom-agent" (just the agent ID)

Available Built-in Agents:

json
"spawnableAgents": ["codebuff/researcher@0.0.1", "my-local-agent"]

Prompt Configuration

All prompt fields support two formats:

  1. Direct string content:
json
"systemPrompt": "You are a helpful assistant..."
  1. External file reference:
json
"systemPrompt": {
  "path": "./my-system-prompt.md"
}

Prompt Fields (all optional)

systemPrompt (string or object, optional)

Background information. Usually instructionsPrompt is better.

instructionsPrompt (string or object, optional)

Instructions inserted after each user input. Best way to shape behavior.

stepPrompt (string or object, optional)

Inserted at each agent step.

Programmatic Control

handleSteps (generator function, optional)

Generator function for programmatic control over tool calls and LLM steps.

Yield ValueWhat It Does
Tool call objectExecute a tool and get its result
'STEP'Run one LLM generation step
'STEP_ALL'Let the agent run until completion
returnEnd the agent's turn immediately

Tool Call Pattern:

typescript
const { toolResult, toolError } = yield {
  toolName: 'read_files',
  input: { paths: ['file.ts'] },
}
// use toolResult or handle toolError

Example:

typescript
handleSteps: function* ({ prompt }) {
  const { toolResult } = yield {
    toolName: 'read_files',
    input: { paths: ['src/index.ts', 'src/config.ts'] },
  }


  yield {
    toolName: 'spawn_agents',
    input: {
      agents: [{ agent_type: 'thinker', prompt: 'Analyze this code structure' }],
    },
  }


  yield 'STEP_ALL'
}

Schema Validation

inputSchema (object, optional)

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

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

Example combining tools

typescript
const { toolResult: searchResults } = yield {
  toolName: 'code_search',
  input: { pattern: params.searchPattern || 'TODO' },
}


const files = JSON.parse(searchResults || '[]').slice(0, 10)
if (files.length) {
  yield { toolName: 'read_files', input: { paths: files } }
}


if (files.some((file) => file.includes('security'))) {
  yield {
    toolName: 'spawn_agents',
    input: {
      agents: [
        {
          agent_type: 'security-reviewer',
          prompt: `Review security implications in: ${files.join(', ')}`,
        },
      ],
    },
  }
}


yield 'STEP_ALL'

Agent Example

.agents/documentation-writer.ts

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


const definition: AgentDefinition = {
  id: "documentation-writer",
  version: "1.0.0",
  publisher: "mycompany",


  displayName: "Documentation Writer",
  spawnerPrompt: "Spawn this agent for writing documentation, API docs, or user guides",
  model: "anthropic/claude-sonnet-4.5",
  outputMode: "last_message",
  includeMessageHistory: true,


  toolNames: [
    "read_files",
    "write_file",
    "code_search",
    "spawn_agents",
    "end_turn"
  ],
  spawnableAgents: ["codebuff/researcher@0.0.1"],


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


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


export default definition
Creating New AgentsTroubleshooting Agent Customization