​

Agents

​

What is an Agent?

• Has a specific purpose (e.g., finding files, editing code)
• Uses a selected AI model optimized for its task
• Has access to specific tools (read files, search code, etc.)
• Can spawn other agents to delegate subtasks
• Follows custom prompts tailored to its role

​

Built-in Agents

​

Base Agent (base2)

• Plans and breaks down user requests
• Spawns specialized agents in parallel
• Manages context and coordinates workflow
• Validates and reviews changes
• Runs tests and verification commands

spawnableAgents: [
  'file-picker',
  'code-searcher',
  'directory-lister',
  'glob-matcher',
  'researcher-web',
  'researcher-docs',
  'commander',
  'thinker',
  'editor',
  'code-reviewer',
  'context-pruner',
]

• spawn_agents - Delegate to specialized agents
• read_files - Read file contents
• read_subtree - Read entire directory trees
• write_todos - Track task progress
• str_replace - Make precise code edits
• write_file - Create or overwrite files
• propose_str_replace / propose_write_file - Propose changes
• ask_user - Request clarification from user
• skill - Load specialized workflows
• set_output - Return structured output

// Core Mandates:
// - Understand first, act second: Always gather context BEFORE editing
// - Quality over speed: Fewer, well-informed agents are better
// - Validate assumptions: Use researchers to verify libraries/APIs
// - Spawn multiple agents in parallel for speed

​

File Picker (file-picker)

1. Spawns a file-lister agent with the user’s prompt
2. File-lister returns paths to potentially relevant files
3. Automatically reads the discovered files
4. Returns a concise analysis with file paths and summaries

• Finding files related to a feature or bug
• Discovering architecture patterns
• Locating dependencies or imports

{
  agent_type: 'file-picker',
  prompt: 'Find authentication-related files and middleware'
}

​

Code Searcher (code-searcher)

• All project files (respects .gitignore)
• Hidden directories: .agents, .claude, .github, .gitlab, .circleci, .husky

• Finding where a function is used
• Searching for TODO comments
• Finding error messages
• Locating specific patterns or imports

{
  agent_type: 'code-searcher',
  prompt: 'Find all usages of the authenticate function',
  params: {
    flags: '-i'  // case-insensitive
  }
}

​

Directory Lister (directory-lister)

• Exploring project structure
• Understanding directory organization
• Finding what files exist in a specific location

​

Commander (commander)

• Runs single terminal command
• Analyzes output based on what’s requested
• Can return raw output or LLM summary
• Configurable timeout (default 30s, set to -1 for infinite)

inputSchema: {
  prompt: {
    type: 'string',
    description: 'What information from the command output is desired'
  },
  params: {
    command: string,        // Required: command to run
    timeout_seconds: number, // Default 30, -1 for no timeout
    rawOutput: boolean      // true = return raw, false = LLM summary
  }
}

• Running tests (npm test, pytest)
• Type checking (tsc --noEmit)
• Linting (eslint .)
• Git operations (git status, git diff)
• Build commands (npm run build)

{
  agent_type: 'commander',
  prompt: 'Check if there are any type errors',
  params: {
    command: 'npx tsc --noEmit',
    timeout_seconds: 60
  }
}

​

Editor (editor)

1. Receives full conversation context
2. Uses <think> tags to plan implementation
3. Makes file changes using tool calls
4. Returns all changes as structured output

instructionsPrompt: `
You are an expert code editor. Write out ALL the code changes 
needed in a single comprehensive response.

Important: You can not make any other tool calls besides editing files. 
You cannot read more files, write todos, spawn agents, or set output.
`

• Implementing features after context is gathered
• Making precise code changes
• Refactoring code
• Fixing bugs

​

Code Reviewer (code-reviewer)

• After implementing changes
• To catch potential bugs
• To ensure code quality
• To validate against requirements

1. Reviews all file changes made
2. Checks for logic errors, edge cases
3. Validates against coding standards
4. Suggests improvements

​

Context Pruner (context-pruner)

1. Runs automatically between steps (never manually spawned)
2. Checks if context exceeds maxContextLength (default 200k tokens)
3. Summarizes conversation if needed:
   • Preserves user messages
   • Summarizes tool calls and results
   • Keeps error messages and important info
   • Removes <think> tags to save tokens
4. Compresses to ~10% of max context

// Triggers on:
// - Context exceeds max limit
// - Prompt cache will miss (>5 min gap)

// Preserves:
// - User messages (truncated to 15k chars)
// - File changes (diffs)
// - Error messages
// - Ask_user answers
// - Agent spawn results (excluding blacklist)

// Removes:
// - <think> blocks
// - Verbose tool results
// - Old summaries

• file-picker
• code-searcher
• directory-lister
• glob-matcher
• researcher-web
• researcher-docs
• commander
• code-reviewer

​

Thinker (thinker)

• Complex architectural decisions
• Algorithm design
• Debugging tricky issues
• Planning multi-step refactors

​

Researcher Agents

• Learning about unfamiliar libraries
• Finding API documentation
• Checking best practices
• Looking up error messages

​

Glob Matcher (glob-matcher)

• Finding all files of a certain type (**/*.test.ts)
• Matching specific patterns
• Bulk file operations

​

Agent Lifecycle

1. Spawn: Parent agent spawns with prompt and params
2. Initialize: Agent receives context (messages, system prompt, tools)
3. Execute: handleSteps generator runs
4. Tool Calls: Agent uses tools to accomplish tasks
5. LLM Steps: Agent sends messages to LLM for reasoning
6. Complete: Agent returns output to parent

​

Agent Modes

​

DEFAULT Mode

• Balanced quality and speed
• Spawns editor, code-reviewer, thinker
• Uses Claude Opus 4.6
• Includes todos and followup suggestions

​

MAX Mode

• Maximum quality and thoroughness
• Spawns editor-multi-prompt (multiple implementation proposals)
• Spawns code-reviewer-multi-prompt
• Reads more files for context (12-20 files)
• Uses Claude Opus 4.6
• Higher credit usage

​

FAST Mode

• Speed prioritized
• Base agent does edits directly (no editor agent)
• Minimal validation
• Extremely concise responses
• Lower credit usage

​

FREE Mode

• Uses free/cheaper models
• Minimax M2.5 for base agent
• Commander-lite, editor-lite, code-reviewer-lite
• Good for simple tasks

​

Best Practices

​

Let Agents Delegate

// Good: Let base agent coordinate
"Add authentication to the API"
// Base agent will spawn:
// - file-picker (find auth files)
// - code-searcher (find existing patterns)
// - editor (implement changes)
// - commander (run tests)
// - code-reviewer (validate)

​

Spawn in Parallel

// From base2.ts:
// Spawn multiple file-pickers in parallel to explore 
// different parts of codebase simultaneously

​

Gather Context First

// From base2.ts system prompt:
// "Understand first, act second: Always gather context 
// and read relevant files BEFORE editing files."

​

Use the Right Model

• File discovery: Gemini Flash
• Commands: Gemini Flash Lite
• Editing: Claude Opus or GPT-5
• Reasoning: Claude Opus or GPT-5

​

Creating Custom Agents

export default {
  id: 'my-agent',
  displayName: 'My Agent',
  model: 'openai/gpt-5.1',
  
  spawnerPrompt: 'When and why to spawn this agent',
  
  toolNames: ['read_files', 'write_file'],
  
  instructionsPrompt: `
    Your detailed instructions here.
    What should the agent do?
  `,
  
  handleSteps: function* ({ agentState, prompt, params, logger }) {
    // Control agent behavior programmatically
    yield { toolName: 'read_files', input: { paths: ['file.ts'] } }
    yield 'STEP' // Let LLM think
  }
}

​

Next Steps