Built-in Agents in OpenClaude: Complete Guide to Types and Requirements

OpenClaude provides nine built-in agents—including helper, filesystem, code-reviewer, test-runner, explore, plan, leaky, broken, and badLimit—that are automatically available to every user, each defined by an AgentDefinition schema specifying required tools, model preferences, and optional turn or step limits.

OpenClaude ships with a comprehensive set of built-in agents designed to handle common development workflows ranging from file system operations to multi-phase code exploration. These agents are defined in the Gitlawb/openclaude repository and are accessible via the SDK without requiring manual registration, making them immediately available for interactive tasks and automated workflows.

Understanding the AgentDefinition Schema

Every built-in agent in OpenClaude conforms to the AgentDefinition schema located in src/entrypoints/sdk/agentDefinitions.ts. This file exports SdkAgentDefinitionInput and SdkInjectedAgentDefinition types, along with the AgentDefinitionSchema that validates agent configurations at runtime.

An agent definition specifies:

• tools: An array of allowed tool names (e.g., ["file-system"]) or ["*"] to permit any tool
• disallowedTools: Tools explicitly prohibited for this agent
• model: A specific model string (e.g., gpt-4) or inheritance from the parent thread
• maxTurns and maxSteps: Optional limits on interaction cycles

The schema ensures that every built-in agent declares its capabilities and constraints before execution begins.

Core Productivity Built-in Agents

These four agents handle the most common development tasks and are referenced frequently in the test suite.

helper Agent

The helper agent serves as the general-purpose assistant for most interactive tasks. It requires no special tools and can work with any tools allowed to the user, making it the default choice for open-ended queries.

• Required tools: None (works with any user-allowed tools)
• Source: Referenced in tests/sdk/sdk-v2-lifecycle.test.ts

filesystem Agent

The filesystem agent provides read/write access to the local file system. Unlike the helper agent, it explicitly requires the file-system tool exposed by the CLI.

• Required tools: file-system
• Source: Referenced in tests/sdk/sdk-v2-lifecycle.test.ts

code-reviewer Agent

The code-reviewer agent analyzes code to highlight potential bugs and suggest improvements. It depends on the built-in code-review tool to perform static analysis.

• Required tools: code-review
• Source: Referenced in tests/sdk/query-methods.test.ts

test-runner Agent

The test-runner agent executes project test suites and reports results. It requires the test-run tool to interface with testing frameworks.

• Required tools: test-run
• Source: Referenced in tests/sdk/query-methods.test.ts

Multi-Phase Workflow Built-in Agents

These agents implement a two-phase architecture for complex codebase operations, documented in src/utils/messages/planMode.ts.

explore Agent

The explore agent performs parallel scans of a codebase to locate relevant fragments before any implementation plan is created. It uses the explore sub-agent tool (EXPLORE_AGENT.agentType) to distribute search tasks across multiple contexts.

• Required tools: EXPLORE_AGENT.agentType
• Purpose: Phase-1 context gathering
• Source: src/utils/messages/planMode.ts

plan Agent

The plan agent designs concrete implementations after the explore phase has collected sufficient context. It utilizes the plan sub-agent tool (PLAN_AGENT.agentType) to structure implementation steps.

• Required tools: PLAN_AGENT.agentType
• Purpose: Phase-2 implementation design
• Source: src/utils/messages/planMode.ts

Diagnostic and Testing Built-in Agents

Three specialized agents exist primarily for testing OpenClaude's internal error handling and limit enforcement.

leaky Agent

The leaky agent demonstrates memory-leak behavior for testing purposes. It requires no special tools and is used primarily in internal test suites to verify resource cleanup.

• Required tools: None
• Use case: Memory leak detection tests
• Source: tests/sdk/sdk-v2-lifecycle.test.ts

broken Agent

The broken agent intentionally throws errors to verify error-handling pathways. It helps ensure the system gracefully manages agent failures.

• Required tools: None
• Use case: Error handling verification
• Source: tests/sdk/sdk-v2-lifecycle.test.ts

badLimit Agent

The badLimit agent triggers step-limit violations to test enforcement logic. It is often configured with maxSteps or maxTurns parameters to force a limit breach and verify boundary checks.

• Required tools: None
• Configuration: Paired with maxSteps or maxTurns limits
• Source: tests/sdk/sdk-v2-lifecycle.test.ts

Configuring Tool and Model Requirements

Built-in agents specify their capabilities through the tools array in their definition. If omitted or set to ["*"], the agent can call any tool not explicitly listed in disallowedTools, which always overrides the allowed list.

Model selection follows an inheritance pattern implemented in src/utils/model/agent.ts. The getDefaultSubagentModel function determines the effective model when a built-in agent does not specify one explicitly, typically inheriting from the parent thread's configuration. Agents may request specific models via the model property to override this behavior.

Turn and step limits are enforced through maxTurns and maxSteps properties, bounding the number of interaction cycles an agent may perform before termination.

Referencing Built-in Agents in Practice

Built-in agents are referenced using the format agent:builtin:<agentType> as implemented in src/utils/promptCategory.ts. When invoking an agent, you can reference it by its type identifier in query sources or SDK calls.

import { AgentDefinition } from './src/entrypoints/sdk/agentDefinitions';

// Example of referencing a built-in agent in a query context
const querySource = {
  agent: 'agent:builtin:filesystem',
  tools: ['file-system'],
  model: 'gpt-4'
};

// The SDK validates against AgentDefinitionSchema
// which checks for required tools and limits

For custom configurations that extend built-in behavior, the SDK validates all inputs against AgentDefinitionSchema to ensure compliance with the expected shape before execution.

Summary

• OpenClaude provides nine built-in agents: helper, filesystem, code-reviewer, test-runner, explore, plan, leaky, broken, and badLimit.
• Agent requirements are defined in src/entrypoints/sdk/agentDefinitions.ts through the AgentDefinition schema.
• filesystem, code-reviewer, and test-runner require specific tools (file-system, code-review, and test-run respectively).
• explore and plan agents implement a two-phase workflow using EXPLORE_AGENT.agentType and PLAN_AGENT.agentType.
• leaky, broken, and badLimit serve internal testing purposes for memory leaks, error handling, and limit enforcement.
• Agents inherit models via getDefaultSubagentModel in src/utils/model/agent.ts unless explicitly overridden.
• Requirements are enforced through the tools array, disallowedTools overrides, and optional maxTurns/maxSteps limits.

Frequently Asked Questions

What are all the built-in agents available in OpenClaude?

OpenClaude includes nine built-in agents: helper (general-purpose), filesystem (file system access), code-reviewer (static analysis), test-runner (test execution), explore (parallel codebase scanning), plan (implementation design), leaky (memory leak testing), broken (error handling verification), and badLimit (limit enforcement testing). The productive agents (helper through plan) are available for general use, while the diagnostic agents are primarily used in internal test suites.

How do tool requirements work for built-in agents?

Built-in agents specify tool requirements through the tools array in their AgentDefinition. For example, the filesystem agent requires ["file-system"] while the helper agent accepts any available tools. The disallowedTools array takes precedence and can block specific tools even if they appear in the allowed list. If tools is set to ["*"] or omitted, the agent can access any tool not explicitly disallowed.

Can I override the model used by a specific built-in agent?

Yes, built-in agents can specify a model property in their definition to request a specific model (e.g., gpt-4). If omitted, the agent inherits the parent thread's model through the getDefaultSubagentModel function in src/utils/model/agent.ts. This inheritance chain ensures consistent model usage across agent hierarchies while allowing specific overrides when computational requirements demand different capabilities.

What happens when the badLimit agent reaches its step limit?

The badLimit agent is specifically designed to trigger step-limit violations for testing purposes. When it reaches its configured maxSteps or maxTurns threshold (as defined in tests/sdk/sdk-v2-lifecycle.test.ts), it forces a limit breach that verifies the enforcement logic implemented in OpenClaude's execution engine. This ensures that production agents respect their configured boundaries and terminate gracefully when limits are exceeded.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}