Customizing Agents

Create specialized agents from scratch using TypeScript files in the .agents/ directory:

markdown

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

Domain-Specific Customization

Agents adapt to your specific workflow and project needs.

Keep in mind you'll get the most value from agents if you treat them as context window managers. Design them to orchestrate and sequence work so the right files, facts, and decisions are in scope at each step. Break tasks into steps and build agents around controlling that flow instead of trying to replicate human specialties.

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

Create a specialized agent for security-focused workflows:

.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 and ensure secure coding practices",
  model: "anthropic/claude-4-sonnet-20250522",
  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 ensuring secure development practices.",
  instructionsPrompt: "Analyze the security implications of the request and coordinate appropriate security-focused agents.",
  stepPrompt: "Continue analyzing security requirements and coordinating the workflow. Use end_turn when complete."
}

export default definition

Advanced: Adding Programmatic Control

Make your agent even more powerful with 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 based on actual code analysis
Orchestrate multiple tools in sequence
Handle errors gracefully
Implement complex 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

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