Troubleshooting Agent Customization

1. Restart Vesper Code 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

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

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

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

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

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

export default definition

Use valid override types: "append", "prepend", or "replace".

Restart Vesper Code to reload templates. Verify override syntax has "override": true and a valid override type.

Check spawnableAgents configuration and verify agent names have no typos.

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