🎨 Custom Agents

Create your own specialized agents using simple JSON configuration files. Custom agents are stored in ~/.code_puppy/agents/.

JSON Agent Schema

Every custom agent is defined by a JSON file with this structure:

{
  "id": "unique-uuid-here",
  "name": "my-custom-agent",
  "display_name": "My Custom Agent 🤖",
  "description": "A helpful description of what this agent does",
  "system_prompt": "Your detailed instructions for the AI...",
  "tools": [
    "list_files",
    "read_file",
    "edit_file",
    "grep",
    "agent_share_your_reasoning"
  ],
  "user_prompt": "Optional custom greeting shown to the user",
  "model": "optional-pinned-model-name"
}

Required Fields

Field	Type	Description
id	string	Unique identifier (UUID recommended)
name	string	Short name for switching (e.g., "my-agent")
display_name	string	Human-readable name with emoji
description	string	Brief description of agent purpose
system_prompt	string	Instructions that define agent behavior
tools	array	List of tool names the agent can use

Optional Fields

Field	Type	Description
user_prompt	string	Custom greeting shown when switching to agent
model	string	Pin a specific model to this agent

Available Tools

Choose from these tools for your agent:

File Operations

• list_files - List directory contents
• read_file - Read file contents
• edit_file - Create/modify files
• delete_file - Delete files
• grep - Search across files

System Operations

• agent_run_shell_command - Execute shell commands

Agent Operations

• agent_share_your_reasoning - Share thought process
• list_agents - List available agents
• invoke_agent - Invoke sub-agents

Browser Tools (for QA/automation agents)

• browser_initialize, browser_close, browser_status
• browser_navigate, browser_go_back, browser_go_forward
• browser_click, browser_set_text, browser_get_text
• browser_find_by_role, browser_find_by_text, browser_find_by_label
• browser_screenshot_analyze
• And many more...

Complete Example

Here's a complete example of a documentation writer agent:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "doc-writer",
  "display_name": "Documentation Writer 📝",
  "description": "Generates comprehensive documentation for code",
  "system_prompt": "You are a technical documentation expert. Your role is to:\n\n1. Read and understand code thoroughly\n2. Write clear, comprehensive documentation\n3. Include examples and usage instructions\n4. Follow documentation best practices (JSDoc, docstrings, etc.)\n5. Create README files when needed\n\nAlways explain complex concepts simply. Use markdown formatting for readability.\n\nBefore writing docs, share your reasoning about:\n- What the code does\n- Who the audience is\n- What documentation format to use",
  "tools": [
    "list_files",
    "read_file",
    "edit_file",
    "grep",
    "agent_share_your_reasoning"
  ],
  "user_prompt": "📝 Ready to write some awesome documentation! What code should I document?"
}

Creating Your Agent

1. Create a JSON file in ~/.code_puppy/agents/
2. Use a unique .json filename (e.g., doc-writer.json)
3. Define your agent schema
4. Switch to it with /agent your-agent-name

# Create the agents directory if it doesn't exist
mkdir -p ~/.code_puppy/agents

# Create your agent file
cat > ~/.code_puppy/agents/doc-writer.json << 'EOF'
{
  "id": "doc-writer-001",
  "name": "doc-writer",
  ...
}
EOF

# In Code Puppy, switch to your agent
/agent doc-writer

Tips for Writing System Prompts

Using the Agent Creator Wizard

For an easier experience, use the interactive wizard:

/agent agent-creator

# Then describe what you want:
"I need an agent that reviews database schemas and suggests optimizations"

The wizard will guide you through creating a complete agent configuration!

Learn more about the Agent Creator →