Quick fixes for common agent customization issues.

1. Restart Codebuff to reload templates
2. Check JSON syntax: cat your-agent-file.json | jq
3. Verify file paths are relative to project root
4. Ensure "override": true is set for overrides

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

Fix: Check agent ID spelling, file location (.agents/templates/), JSON syntax (cat file.json | jq)

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": "..."
  }
}

{
  "id": "my-agent",
  "override": false,
  "displayName": "My Agent"
  // ❌ Missing required fields for new agents
}

Fix: Include all required fields for new agents:

{
  "id": "my-agent",
  "version": "1.0.0",
  "override": false,
  "displayName": "My Agent",
  "purpose": "Brief description of the agent's purpose",
  "model": "anthropic/claude-4-sonnet-20250522",
  "systemPrompt": "You are a helpful assistant...",
  "instructionsPrompt": "Process the user's request...",
  "stepPrompt": "Continue working on the task..."
}

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": "anthropic/claude-3-5-haiku-20241022" // 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.json
│ └── my-prompts.md

2. Verify file permissions:

ls -la .agents/templates/

3. Check for hidden characters or encoding issues:

file .agents/templates/*.json

Begin with minimal overrides and add complexity gradually:

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

• JSON validator: cat file.json | jq
• File existence: ls -la .agents/templates/
• Syntax check: Most editors highlight JSON 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"

If you're still experiencing issues:

1. Check the logs: Look for specific error messages when starting Codebuff
2. Simplify: Remove customizations until it works, then add back gradually
3. Community: Join our Discord for real-time help
4. Documentation: Review the Agent Reference for complete field descriptions

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

• id, version, override: false
• displayName, purpose, model
• systemPrompt, instructionsPrompt, stepPrompt

• Agent templates: .agents/templates/*.json
• External prompts: .agents/templates/*.md
• Project root: ./ (for absolute paths)