Complete reference for all agent definition fields:

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

"id": "code-reviewer"

Human-readable name for the agent.

"displayName": "Code Review Specialist"

Prompt for when and why to spawn this agent. Include the main purpose and use cases. This field is key if the agent is intended to be spawned by other agents.

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

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

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

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") — Increase or decrease how much the model "thinks" before answering. Higher effort typically improves quality for hard tasks at the cost of more reasoning tokens.

Notes:

• Patterned after OpenRouter's "max tokens for reasoning." Higher effort maps to a higher internal reasoning token budget. See OpenRouter docs for background.
• Only supported by models that expose reasoning features. When unsupported, these options are ignored.

Example:

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

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)

"outputMode": "last_message"

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

"includeMessageHistory": true

JSON Schema for structured output (when outputMode is "structured_output"). Defines the expected shape of the JSON object the agent will return.

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

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

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

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:

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

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

All prompt fields support two formats:

1. Direct string content:

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

2. External file reference:

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

Background information for the agent. Fairly optional - prefer using instructionsPrompt for agent instructions.

Instructions for the agent. This is the best way to shape the agent's behavior and is inserted after each user input.

Prompt inserted at each agent step. Powerful for changing behavior but usually not necessary for smart models.

🚀 This is what makes Codebuff agents truly powerful! Unlike traditional prompt-based agents, handleSteps lets you write actual code to control agent behavior.

Programmatically control the agent's execution using a TypeScript generator function. This enables:

• Dynamic decision making based on tool results
• Complex orchestration between multiple tools and agents
• Conditional branching based on file contents or agent responses
• Iterative refinement until desired results are achieved
• State management across multiple steps

What You Can Yield:

Tool Call Pattern:

const { toolResult, toolError } = yield {
  toolName: 'read_files',
  input: { paths: ['file.ts'] }
}
// Now you can use toolResult to make decisions!

Example:

handleSteps: function* ({ agentState, prompt, params }) {
  // First, read some files
  const { toolResult } = yield {
    toolName: 'read_files',
    input: { paths: ['src/index.ts', 'src/config.ts'] }
  }
  // Then spawn a thinker agent
  yield {
    toolName: 'spawn_agents',
    input: {
      agents: [{
        agent_type: 'thinker',
        prompt: 'Analyze this code structure'
      }]
    }
  }

  // Let the agent take over from here
  yield 'STEP_ALL'
}

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

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

Real-World Example:

  // 1. Dynamically find relevant files
  const { toolResult: searchResults } = yield {
    toolName: 'code_search',
    input: { pattern: params.searchPattern || 'TODO' }
    }

  // 2. Parse results and decide what to read
  const files = JSON.parse(searchResults || '[]')
  if (files.length > 0) {
    const { toolResult: fileContents } = yield {
      toolName: 'read_files',
      input: { paths: files.slice(0, 10) }
  }

    // 3. Conditionally spawn different agents based on content
    if (fileContents?.includes('security')) {
      yield {
        toolName: 'spawn_agents',
        input: {
          agents: [{
            agent_type: 'security-reviewer',
            prompt: `Review security implications in: ${files.join(', ')}`
          }]
        }
      }
    }
}

  // 4. Let the LLM handle the rest with context
**Why This Matters:**
- Traditional agents rely solely on prompts and hope the LLM makes the right decisions
- With `handleSteps`, you have **deterministic control** over the agent's workflow
- You can implement complex logic that would be impossible with prompts alone
- Results from one tool directly inform the next action programmatically

### Agent Example
**.agents/documentation-writer.ts**
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 creating comprehensive documentation, API docs, or user guides",
  model: "anthropic/claude-4-sonnet-20250522",
  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 comprehensive 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