# Child Agent Protocol in oh-my-codex: Understanding the 6 Concurrent Agent Limit

> Understand the oh-my-codex child agent protocol and its 6 concurrent agent limit. Learn how it prevents resource exhaustion and enables safe task delegation for efficient orchestration.

- Repository: [Bellman/oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
- Tags: internals
- Published: 2026-04-03

---

**The child agent protocol in oh-my-codex establishes a leader-worker orchestration contract that caps parallelism at 6 concurrent agents to prevent resource exhaustion while enabling safe task delegation.**

The child agent protocol governs how distributed AI agents collaborate within the oh-my-codex framework. This lightweight coordination system ensures that complex tasks can be broken into isolated, verifiable subtasks without overwhelming system resources or creating circular dependencies.

## How the Child Agent Protocol Works

The protocol defines strict roles for **leader** and **worker** agents, enforces a hard concurrency limit, and mandates upward reporting for any blockers or scope changes.

### Leader Responsibilities

According to [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) (lines 78-81), the leader agent owns three critical functions:

- **Choose the execution mode** and maintain the user-facing brief throughout the session
- **Delegate bounded, verifiable subtasks** with explicit ownership to worker agents
- **Integrate results**, decide follow-up actions, and perform final verification

The leader never delegates open-ended planning to workers; each task must have clear boundaries and a single owner.

### Worker Responsibilities

As defined in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) (lines 83-86), workers operate under strict constraints:

- Execute only the assigned slice without rewriting the global plan or switching execution modes
- Stay within the allocated write scope and report file-conflict issues or blockers upward
- Ask the leader to broaden scope or resolve ambiguity instead of freelancing or making architectural decisions

Workers finish their assigned role and do **not** recursively orchestrate additional agents unless explicitly instructed by the leader.

### The 6-Agent Concurrency Ceiling

The protocol enforces a **maximum of 6 concurrent child agents** to balance parallel throughput with predictable resource consumption. This limit prevents uncontrolled resource usage and simplifies state management within the `.omx/` runtime directory (AGENTS.md#L87-L95).

Additional binding rules include:
- Child prompts must stay under the authority of [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md)
- The `worker` role is a team-runtime surface, not a general-purpose role
- Model inheritance is preferred; explicit model overrides are only used when truly required

## Implementation in oh-my-codex Source Code

The canonical definition resides in **[`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md)** at the repository root, specifically lines 76-96. A template copy exists at **[`templates/AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/templates/AGENTS.md)** for project scaffolding.

Runtime state tracking occurs in **`.omx/state/`**, where the leader monitors active worker counts against the 6-agent limit. When skills invoke agents via [`prompts/executor.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/prompts/executor.md), they reference the `$executor` surface that respects these concurrency constraints.

## Practical Code Examples

### Delegating Workers from a Leader Script

The following YAML demonstrates a leader spawning three workers (well under the 6-agent limit):

```yaml

# leader.yaml – a “plan” skill following the protocol

steps:
  - name: generate‑readme
    invoke: $executor
    args:
      prompt: |
        Write a concise README for the `src/utils` module.
    as: worker‑readme

  - name: lint‑sources
    invoke: $executor
    args:
      prompt: |
        Run ESLint on `src/**/*.ts` and output JSON.
    as: worker‑lint

  - name: test‑coverage
    invoke: $executor
    args:
      prompt: |
        Execute `npm test -- --coverage` and return the coverage report.
    as: worker‑coverage

```

Each worker (`worker‑readme`, `worker‑lint`, `worker‑coverage`) operates in isolation, owns its specific output, and cannot modify the global plan.

### Reporting Blockers Upward

When a worker encounters an obstacle, it must report the blocker instead of attempting to resolve it:

```markdown

# worker‑lint output

> **BLOCKER**: ESLint crashed on `src/helpers/parse.ts` because `parserOptions.project` is missing.
> Please ask the leader to provide a proper tsconfig or narrow the file set.

```

This follows protocol rule 3: workers report blockers upward rather than freelancing solutions.

### Handling Blockers and Respawning

The leader receives the blocker and may spawn an additional worker (now 4 of 6 allowed):

```yaml

# continuation in leader.yaml

steps:
  - name: fix‑tsconfig
    invoke: $executor
    args:
      prompt: |
        Add `parserOptions.project: "./tsconfig.json"` to the ESLint config.
    as: worker‑fix‑config

```

The total active agents remains under the 6-agent ceiling, maintaining safe parallelism.

## Summary

- The **child agent protocol** creates a strict leader-worker hierarchy defined in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md)
- **Leaders** own planning, delegation, and integration; **workers** execute bounded slices without recursive orchestration
- A **hard limit of 6 concurrent agents** prevents resource exhaustion and simplifies state management in `.omx/state/`
- Workers must **report blockers upward** rather than resolving them independently
- The `$executor` surface in skill files invokes workers while enforcing the protocol's concurrency and authority constraints

## Frequently Asked Questions

### What happens if I try to spawn more than 6 concurrent child agents?

The oh-my-codex runtime enforces the 6-agent ceiling defined in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) (lines 87-95). Attempts to exceed this limit will queue additional workers or trigger a protocol violation error, depending on the specific executor implementation. This bound ensures predictable resource usage within the `.omx/` runtime directory.

### Can a worker spawn its own child agents?

No. Workers are explicitly prohibited from recursive orchestration unless the leader explicitly instructs otherwise. According to the protocol, workers "finish their assigned role and do **not** recursively orchestrate." Only the leader may spawn new workers, maintaining clear ownership chains and preventing circular delegation.

### Where is the concurrent agent count tracked?

The active agent count is managed within the **`.omx/state/`** runtime directory. This state store allows the leader to monitor current workers against the 6-agent limit and coordinate hand-offs without race conditions or resource leaks.

### How does model inheritance work in the child agent protocol?

The protocol prefers **model inheritance**, where child workers automatically use the same model configuration as the leader. Explicit model overrides are permitted only when truly required for specific subtasks (e.g., requiring a different context window for a particular file analysis). This default inheritance reduces configuration overhead and maintains consistent behavior across the agent team.