Custom Agents

Custom Agents

Quick Reference

• Who: Developer
• Where: Terminal → .agents/ directory in your project
• Time: ~10 minutes to create first agent
• Prerequisites: Codebuff CLI installed, basic TypeScript knowledge

Prerequisites

• Installed Codebuff CLI
• Familiarity with TypeScript
• A project with .agents/ directory (run /init to create)

Step-by-Step Guide

Step 1: Initialize Agent Infrastructure

1. Launch Codebuff in your project:

   codebuff

2. Run the init command:

   /init

3. This creates the agent scaffolding:

   .agents/
   └── types/
       ├── agent-definition.ts
       ├── tools.ts
       └── util-types.ts

(cli/src/init/init-app.ts)

Step 2: Create an Agent Definition

Create a new file in your project, e.g. my-agent.ts:

export default {
  id: 'git-committer',
  displayName: 'Git Committer',
  model: 'openai/gpt-5-nano',
  toolNames: ['read_files', 'run_terminal_command', 'end_turn'],

  instructionsPrompt:
    'You create meaningful git commits by analyzing changes.',

  async *handleSteps() {
    // Analyze what changed
    yield { tool: 'run_terminal_command', command: 'git diff' }
    yield { tool: 'run_terminal_command', command: 'git log --oneline -5' }
    // Let the LLM craft a commit message and execute
    yield 'STEP_ALL'
  },
}

Step 3: Available Tools

Your agent can use any of these 33 built-in tools:

Category	Tools
File Ops	read_files, write_file, str_replace, apply_patch, find_files, glob, list_directory, read_subtree
Code	code_search, read_docs, web_search
Terminal	run_terminal_command, browser_logs
Agent	spawn_agents, spawn_agent_inline, end_turn, task_completed
Planning	create_plan, think_deeply, add_subgoal, update_subgoal, write_todos
Communication	ask_user, add_message, suggest_followups

(common/src/tools/list.ts:41-76)

Step 4: Choose a Model

Any model available on OpenRouter:

Model	Identifier	Best For
Claude 3.5 Sonnet	anthropic/claude-3.5-sonnet	Complex coding
GPT-4o	openai/gpt-4o	General purpose
GPT-5 Nano	openai/gpt-5-nano	Fast, cost-effective
DeepSeek Coder	deepseek/deepseek-coder	Code-focused
Qwen Coder	qwen/qwen-2.5-coder-32b	Multilingual code

Step 5: Run Your Agent

codebuff --agent git-committer

Expected Results

• ✅ Agent definition loads from your project
• ✅ Agent executes with the specified model and tools
• ✅ Programmatic steps run first, then LLM takes over for remaining work

FAQ

Q: Can agents spawn other agents?

A: Yes! Use the spawn_agents or spawn_agent_inline tools in your agent definition. The spawned agents run independently with their own context.

Q: Can I publish my agent?

A: Yes! See the Agent Publishing guide to publish to the Agent Store.

Related

• Agent Publishing — Publish to the Agent Store
• SDK Integration — Run agents programmatically
• CLI Interactive Chat — Use built-in agents