Troubleshooting Agent Customization

Quick fixes for common agent customization issues.

1. Restart Codebuff to reload agent definitions
2. Check TypeScript syntax: Run bun run typecheck in your .agents/ directory
3. Verify file paths are relative to project root
4. Ensure your agent exports a default definition

Error: Agent 'my-custom-agent' not found

Fix: Check agent ID spelling, file location (.agents/), and that your TypeScript file has export default definition

Validation error: spawnableAgents contains invalid agent 'researcher-typo'

Fix: Check spelling against built-in agents list, use exact IDs

Error: Cannot resolve prompt file './my-prompt.md'

Causes:

• File doesn't exist at specified path
• Incorrect relative path resolution
• File permissions issue

Solutions:

1. Use paths relative to project root: .agents/templates/my-prompt.md
2. Verify file exists: ls -la .agents/templates/my-prompt.md
3. Check file permissions are readable

{
  "systemPrompt": {
    "type": "add", // ❌ Invalid
    "content": "..."
  }
}

Fix: Use valid override types:

{
  "systemPrompt": {
    "type": "append", // ✅ Valid: append, prepend, replace
    "content": "..."
  }
}

// ❌ Missing required fields for new agents
const definition = {
  id: 'my-agent',
  displayName: 'My Agent'
}

Fix: Include all required fields for new agents:

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

const definition: AgentDefinition = {
  id: 'my-agent',
  displayName: 'My Agent',
  model: 'anthropic/claude-sonnet-4.5',
  toolNames: ['read_files', 'write_file', 'end_turn'],
  instructionsPrompt: 'Process the user\'s request...',
}

export default definition

Fix: Use project root relative paths: .agents/templates/my-prompt.md, verify file exists

Symptoms:

• Agent behaves like default version
• Custom instructions ignored

Debug Steps:

1. Check override is properly applied:

# Restart Codebuff to reload templates
codebuff

2. Verify override syntax:

{
  "id": "CodebuffAI/reviewer", // ✅ Exact match required
  "override": true, // ✅ Must be true for overrides
  "systemPrompt": {
    "type": "append", // ✅ Valid override type
    "content": "Custom instructions..."
  }
}

Symptoms:

• Unexpected agents being created
• Missing expected specialized agents

Solutions:

1. Check spawnableAgents configuration:

{
  "spawnableAgents": {
    "type": "replace", // Use "replace" to override completely
    "content": ["researcher", "thinker"]
  }
}

2. Verify agent names are correct (no typos)

Causes:

• Complex prompts causing slow generation
• Too many tools enabled
• Large context from message history

Solutions:

1. Simplify prompts and remove unnecessary instructions
2. Limit toolNames to only required tools
3. Set includeMessageHistory: false for stateless agents
4. Use faster models for simple tasks:

{
  "model": "openai/gpt-5-mini" // Faster model
}

Causes:

• Using expensive models unnecessarily
• Agents spawning too many sub-agents
• Large context windows

Solutions:

1. Use cost-effective models:

{
  "model": "google/gemini-2.5-flash" // More economical
}

2. Limit spawnable agents:

{
  "spawnableAgents": [] // Prevent sub-agent spawning
}

Symptoms:

• No custom agents available
• Validation errors on startup

Debug Steps:

1. Check directory structure:

your-project/
├── .agents/
│   ├── my-agent.ts
│   ├── types/
│   │   └── agent-definition.ts
│   └── prompts/
│       └── my-prompts.md

2. Verify file permissions:

ls -la .agents/

3. Check TypeScript compiles:

cd .agents && bun run typecheck

Begin with minimal overrides and add complexity gradually:

{
  "id": "CodebuffAI/reviewer",
  "override": true,
  "model": "anthropic/claude-sonnet-4.5"
}

• TypeScript check: cd .agents && bun run typecheck
• File existence: ls -la .agents/
• Syntax check: Most editors highlight TypeScript errors

Restart Codebuff to see validation errors:

codebuff  # Look for error messages on startup

Add one override at a time to isolate issues:

1. Test basic override (model change)
2. Add simple prompt override
3. Add external file reference
4. Add tool modifications

Track your agent templates in git to easily revert problematic changes:

git add .agents/
git commit -m "Add custom reviewer agent"

1. Check logs for error messages on startup
2. Remove customizations until it works, then add back one at a time
3. Join Discord
4. See the Agent Reference

• "append" - Add to existing content
• "prepend" - Add before existing content
• "replace" - Replace entire content

• id — Unique identifier
• displayName — Human-readable name
• model — The LLM to use (e.g., anthropic/claude-sonnet-4.5)
• toolNames — Array of tools the agent can use
• instructionsPrompt — What the agent should do

• Agent definitions: .agents/*.ts
• Type definitions: .agents/types/agent-definition.ts
• External prompts: .agents/prompts/*.md