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

> Explore OpenClaude's nine built-in agents including helper, filesystem, and code-reviewer. Understand their requirements, tools, and model preferences in this comprehensive guide.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: tutorial
- Published: 2026-09-05

---

**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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/promptCategory.ts). When invoking an agent, you can reference it by its type identifier in query sources or SDK calls.

```typescript
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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/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.