# How to Spawn Sub-Agents Using AgentTool in OpenClaude

> Learn how to spawn sub-agents using AgentTool in OpenClaude. Launch isolated agents for specialized tasks synchronously or in the background.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: how-to-guide
- Published: 2026-09-08

---

**OpenClaude's AgentTool lets the main Claude assistant launch isolated "sub-agents" (forked agents) to perform specialized tasks either synchronously or in the background.**

The **AgentTool** is a core component of the [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude) repository that enables recursive agent workflows. When you spawn sub-agents using AgentTool in OpenClaude, the system creates fresh `AgentSession` instances with independent prompt loops, optional Git work-tree isolation, and dedicated UI progress tracking.

## Understanding the AgentTool Architecture

The AgentTool implementation spans several modules in `src/tools/AgentTool/`, each handling specific lifecycle stages from definition loading to result finalization.

### Agent Definitions and Configuration

Agent configurations are resolved by **[`loadAgentsDir.ts`](https://github.com/Gitlawb/openclaude/blob/main/loadAgentsDir.ts)**, which scans both the built-in agents directory (`src/tools/AgentTool/built-in/`) and the user's local `agents/` folder. This module reads JSON/YAML agent definitions, merges configuration overrides, and validates the schema before execution.

Built-in agents like `plan`, `explore`, and `codeReviewer` ship with the repository and provide ready-made sub-agent behaviors for common tasks.

### Entry Point and Tool Invocation

The **[`AgentTool.tsx`](https://github.com/Gitlawb/openclaude/blob/main/AgentTool.tsx)** file serves as the primary entry point. When the system receives a tool use request with `"name": "agent"`, this component:

1. Parses the input payload containing the `agent` identifier and optional `prompt`
2. Resolves the target agent definition via the loader
3. Determines isolation level (`foreground`, `background`, or `worktree`)
4. Delegates to either `runAgent()` for synchronous execution or `resumeAgent()` for background scheduling

## Spawning Sub-Agents in Practice

OpenClaude supports three execution modes depending on your isolation and concurrency requirements.

### Foreground Execution with runAgent

For synchronous, blocking operations, **[`runAgent.ts`](https://github.com/Gitlawb/openclaude/blob/main/runAgent.ts)** contains the `runAgent()` function that:

- Instantiates a fresh `AgentSession` with the sub-agent's model and system prompt
- Optionally creates a temporary Git work-tree via `createAgentWorktree()` from [`src/utils/worktree.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/worktree.ts)
- Executes the sub-agent's prompt loop until completion or `maxSteps` exhaustion
- Returns a consolidated `ToolResult` to the parent agent

This mode blocks the main conversation turn until the sub-agent completes, making it suitable for quick, dependent tasks.

### Background Asynchronous Tasks

When `isolation: "background"` is specified (and the `DISABLE_BACKGROUND_TASKS` global flag is not set), **[`resumeAgent.ts`](https://github.com/Gitlawb/openclaude/blob/main/resumeAgent.ts)** schedules the sub-agent as an asynchronous task. This allows the main session to continue while the sub-agent runs in parallel.

The UI components in **[`UI.tsx`](https://github.com/Gitlawb/openclaude/blob/main/UI.tsx)** render progress indicators for background tasks, and upon completion, the parent can retrieve results through the standard tool result mechanism.

### Isolation with Git Worktrees

For repository operations that must not affect the main working directory, **[`src/utils/worktree.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/worktree.ts)** provides `createAgentWorktree()`. When `worktree: true` is set in the tool input, OpenClaude creates a temporary Git work-tree that the sub-agent can modify freely. This isolation ensures that exploratory code changes, searches, or refactoring attempts by sub-agents remain sandboxed until explicitly merged.

## Built-in and Custom Agent Types

The AgentTool supports both pre-configured agents shipped with OpenClaude and user-defined custom configurations.

### Using Built-in Agents

Built-in agents reside in `src/tools/AgentTool/built-in/` and include specialized agents like **[`planAgent.ts`](https://github.com/Gitlawb/openclaude/blob/main/planAgent.ts)** and **[`codeReviewerAgent.ts`](https://github.com/Gitlawb/openclaude/blob/main/codeReviewerAgent.ts)**. These agents come with optimized system prompts and step limits for specific workflows. Invoke them by name without additional configuration:

```typescript
{
  "type": "tool_use",
  "name": "agent",
  "input": {
    "agent": "plan",
    "prompt": "Create a 3-step outline for a blog post about AI safety.",
    "isolation": "foreground"
  }
}

```

### Defining Custom Agents

Users can create custom agent definitions in the `agents/` directory. Each definition specifies the model, system prompt, maximum steps, and default isolation level. The [`loadAgentsDir.ts`](https://github.com/Gitlawb/openclaude/blob/main/loadAgentsDir.ts) loader automatically picks up these files at runtime, making them available alongside built-in agents.

## Code Examples

The following examples demonstrate how to spawn sub-agents using AgentTool for different use cases.

### 1. Simple Foreground Sub-Agent Call

Use this pattern for synchronous tasks that must complete before the main conversation continues:

```typescript
import { AgentTool } from './tools/AgentTool/AgentTool.tsx';

// Tool use payload
{
  "type": "tool_use",
  "name": "agent",
  "input": {
    "agent": "plan",
    "prompt": "Create a 3-step outline for a blog post about AI safety.",
    "isolation": "foreground"
  }
}

```

The `AgentTool` parses this input, resolves the `plan` agent definition, and calls `runAgent()`. The sub-agent runs its reasoning loop and returns a single `ToolResult` that appears as the assistant's reply.

### 2. Background Sub-Agent with Work-Tree Isolation

Use this pattern for long-running repository analysis that should not block the main conversation:

```typescript
import { AgentTool } from './tools/AgentTool/AgentTool.tsx';

// Tool use payload
{
  "type": "tool_use",
  "name": "agent",
  "input": {
    "agent": "explore",
    "prompt": "Search the repo for any TODO comments and list them.",
    "isolation": "background",
    "worktree": true
  }
}

```

When `isolation` is `"background"`, the request delegates to `resumeAgent()`. The UI shows a progress bar, and the main conversation continues while the sub-agent works in an isolated Git work-tree. Upon completion, a notification emits and the result becomes available.

### 3. Custom User-Defined Agent

Assume you created [`agents/customAgent.json`](https://github.com/Gitlawb/openclaude/blob/main/agents/customAgent.json):

```json
{
  "name": "customAgent",
  "model": "claude-3-opus-20240307",
  "systemPrompt": "You are a helpful assistant that only returns JSON.",
  "maxSteps": 4,
  "isolation": "foreground"
}

```

Invoke your custom agent by name:

```typescript
{
  "type": "tool_use",
  "name": "agent",
  "input": {
    "agent": "customAgent",
    "prompt": "Summarize the README of this repository in one sentence."
  }
}

```

The `loadAgentsDir()` function discovers this definition, `runAgent()` instantiates a fresh session with the specified model, and the result returns to the parent turn.

## Summary

- **AgentTool** is the primary interface for spawning sub-agents in OpenClaude, implemented in [`src/tools/AgentTool/AgentTool.tsx`](https://github.com/Gitlawb/openclaude/blob/main/src/tools/AgentTool/AgentTool.tsx).
- **[`runAgent.ts`](https://github.com/Gitlawb/openclaude/blob/main/runAgent.ts)** handles synchronous foreground execution with full blocking behavior, while **[`resumeAgent.ts`](https://github.com/Gitlawb/openclaude/blob/main/resumeAgent.ts)** manages asynchronous background tasks.
- **Git work-tree isolation** via [`src/utils/worktree.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/worktree.ts) creates sandboxed environments for repository-modifying sub-agents.
- **Built-in agents** provide immediate utility for planning and code review, while the **`agents/` directory** supports custom JSON/YAML definitions.
- The **[`UI.tsx`](https://github.com/Gitlawb/openclaude/blob/main/UI.tsx)** components render progress and results for both foreground and background agent operations.

## Frequently Asked Questions

### What is the difference between foreground and background isolation when spawning sub-agents?

**Foreground isolation** blocks the parent agent's conversation turn until the sub-agent completes, returning a `ToolResult` synchronously via [`runAgent.ts`](https://github.com/Gitlawb/openclaude/blob/main/runAgent.ts). **Background isolation** delegates the task to [`resumeAgent.ts`](https://github.com/Gitlawb/openclaude/blob/main/resumeAgent.ts), allowing the main conversation to continue while the sub-agent executes asynchronously. Background tasks emit UI notifications upon completion rather than blocking the conversation flow.

### How does the work-tree isolation protect the main repository?

When you set `worktree: true` in the AgentTool input, `createAgentWorktree()` in [`src/utils/worktree.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/utils/worktree.ts) creates a temporary Git work-tree—a separate working directory linked to the same repository. The sub-agent operates in this isolated directory, so any file modifications, deletions, or git operations cannot affect the main working tree or the parent agent's environment. The work-tree is cleaned up automatically after the sub-agent finishes.

### Can I use a different model for the sub-agent than the parent Claude instance?

Yes. The agent definition JSON/YAML file specifies the `model` field independently of the parent session. When `runAgent()` creates the sub-agent's `AgentSession`, it uses the model specified in the definition (e.g., `claude-3-opus-20240307` or `claude-3-sonnet-20240229`), allowing lightweight sub-agents to use smaller models while complex tasks use larger ones, regardless of the parent agent's configuration.

### Where should I place custom agent definitions in my OpenClaude project?

Place custom agent definitions in the **`agents/` directory** at your project root. The [`loadAgentsDir.ts`](https://github.com/Gitlawb/openclaude/blob/main/loadAgentsDir.ts) loader automatically scans this directory at runtime, merging your custom JSON/YAML files with the built-in agents located in `src/tools/AgentTool/built-in/`. Ensure each file contains a valid agent definition with required fields: `name`, `model`, `systemPrompt`, and `maxSteps`.