Customizing Agents

Create agents with TypeScript files in the .agents/ directory:

markdown

.agents/
├── my-custom-agent.ts
├── security-coordinator.ts
└── types/
└── agent-definition.ts

Domain-Specific Customization

Design agents to manage context flow: orchestrate steps so the right files and facts stay in scope, instead of trying to mimic job titles.

Tip: Use specialty reviewers as spawnable subagents that your context-manager agent calls at the right time in the workflow.

Reasoning Options (optional)

For models that support it, you can enable and tune reasoning directly on your agent:

const definition = {
  id: 'reviewer',
  // ... other fields ...
  reasoningOptions: {
    enabled: true, // turn on reasoning if supported
    exclude: false, // include reasoning traces when available
    effort: 'medium', // low | medium | high
  },
}

Effort roughly corresponds to a larger internal "max tokens for reasoning."
If the selected model doesn't support reasoning, these options are safely ignored.

Example: Security Coordinator Agent

This example uses reviewer, researcher, and file-picker as spawnable subagents:

.agents/security-coordinator.ts

typescript

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

const definition: AgentDefinition = {
  id: 'security-coordinator',
  version: '1.0.0',

  displayName: 'Security Coordinator',
  spawnerPrompt:
    'Spawn this agent to coordinate security-focused development workflows',
  model: 'anthropic/claude-sonnet-4.5',
  outputMode: 'last_message',
  includeMessageHistory: true,

  toolNames: ['read_files', 'spawn_agents', 'code_search', 'end_turn'],
  spawnableAgents: [
    'codebuff/reviewer@0.0.1',
    'codebuff/researcher@0.0.1',
    'codebuff/file-picker@0.0.1',
  ],

  inputSchema: {
    prompt: {
      type: 'string',
      description: 'Security analysis or coordination task',
    },
  },

  systemPrompt:
    'You are a security coordinator responsible for secure development practices.',
  instructionsPrompt:
    'Analyze the security implications of the request and coordinate security-focused agents.',
  stepPrompt:
    'Continue analyzing security requirements and coordinating the workflow. Use end_turn when complete.',
}

export default definition

Adding Programmatic Control

typescript

const definition: AgentDefinition = {
  id: 'security-coordinator',
  // ... other fields ...

  handleSteps: function* ({ prompt, params }) {
    // 1. Scan for security vulnerabilities
    const { toolResult: scanResults } = yield {
      toolName: 'code_search',
      input: {
        pattern: '(eval|exec|dangerouslySetInnerHTML|process\.env)',
        flags: '-i',
      },
    }

    // 2. If vulnerabilities found, spawn security reviewer
    if (scanResults) {
      yield {
        toolName: 'spawn_agents',
        input: {
          agents: [
            {
              agent_type: 'security-reviewer',
              prompt: `Review these potential security issues: ${scanResults}`,
            },
          ],
        },
      }
    }

    // 3. Let the agent handle the rest
    yield 'STEP_ALL'
  },
}

With handleSteps, your agent can:

Make decisions from tool output
Orchestrate tools in sequence
Handle errors
Run conditional logic

Available Fields

Core:

id
displayName
model
version
publisher

Tools:

toolNames
spawnableAgents

Prompts:

spawnerPrompt
systemPrompt
instructionsPrompt
stepPrompt

Input/Output:

inputSchema
outputMode
outputSchema
includeMessageHistory

Programmatic:

handleSteps

Troubleshooting

Agent not loading: Check TypeScript syntax, file must export default AgentDefinition

Type errors: Import types from './types/agent-definition'

Prompts not applying: Verify file paths are relative to .agents/ directory

Running specific agents:

Check TypeScript: bun run typecheck in .agents/ directory
Restart Codebuff to see errors
Test with --agent <agent-id> to debug specific agents