# How ADHD Implements Branch Isolation During the Diverge Phase

> Discover how ADHD ensures branch isolation during the diverge phase. Learn how separate LLM sessions with fresh Claude Agent SDK queries prevent shared context for robust parallel processing.

- Repository: [Udit Akhouri/adhd](https://github.com/UditAkhourii/adhd)
- Tags: internals
- Published: 2026-08-19

---

**ADHD guarantees branch isolation during the diverge phase by spawning each parallel branch in a separate, stateless LLM session using fresh Claude Agent SDK queries, ensuring zero shared context, KV-cache, or message history between branches.**

The UditAkhourii/adhd repository implements a strict **branch isolation** mechanism during its divergence phase to eliminate cross-contamination between parallel reasoning paths. Unlike traditional Tree-of-Thought approaches where branches may leak context through shared sessions, ADHD enforces complete separation by architectural design. This implementation relies on three coordinated mechanisms that together uphold the "branch isolation invariant" documented in the source code.

## The Three Pillars of Branch Isolation

ADHD achieves isolation through a combination of stateless wrappers, unique system prompts per branch, and parallel execution patterns that prevent any shared state.

### Stateless LLM Wrapper in [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts)

The foundation of isolation resides in the `callLLM` function located in [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts). According to lines 1-7, this wrapper creates a fresh Claude Agent SDK `query` for every single branch invocation. Each call uses only the `claude_code` preset combined with the branch-specific system prompt, explicitly avoiding any cached KV-store or shared message history.

```typescript
// src/llm.ts – stateless query wrapper
export async function callLLM(opts) {
  const iter = query({
    prompt: opts.userPrompt,
    options: {
      model: opts.model,
      systemPrompt: { type: "preset", preset: "claude_code", append: opts.systemPrompt },
      tools: [],                     // no tools → pure generation
    },
  });
  // The query runs in a brand‑new Claude session; nothing is shared with other calls.
}

```

Because `callLLM` instantiates a new `query` object for each invocation, the underlying LLM session starts with zero context from previous branches. This stateless design ensures that the model's internal KV-cache remains isolated to the individual call.

### Branch-Specific System Prompts in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)

While the wrapper provides the container, [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) provides the isolation policy through the `DIVERGE_SYSTEM` prompt. Lines 61-69 define this prompt, which is passed to a brand-new `query` instance for each branch. Since the prompt is injected into a fresh session, the model's context window starts from scratch for that specific branch, carrying no residue from sibling branches.

This mechanism guarantees that each branch processes only its assigned cognitive frame without exposure to alternative frames or previous outputs from other branches.

### Parallel Promise.all Fan-Out

The divergence loop in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) (lines 4-6) orchestrates parallel execution using `Promise.all` with a concurrency limiter. The engine spawns N branches simultaneously, with each branch's `divergeBranch` routine independently invoking the stateless `callLLM` wrapper.

```typescript
// src/engine.ts – diverge loop (simplified)
import pLimit from "p-limit";
import { callLLM } from "./llm.js";

async function runDivergence(problem, context, frames, ideasPerFrame, model) {
  const limit = pLimit(concurrency);
  const branches = await Promise.all(
    frames.map(f => limit(() => divergeBranch(problem, context, f, ideasPerFrame, model)))
  );
  // each `divergeBranch` internally calls `callLLM`, which creates a fresh query()
}

```

Since each branch executes `divergeBranch` independently within the `Promise.all` array, and each of those calls triggers a separate `callLLM` invocation, no branch can access the conversation history or cached tokens of another. As documented in [`documentation/how-it-works.md`](https://github.com/UditAkhourii/adhd/blob/main/documentation/how-it-works.md) lines 73-74: "branches[i] never sees branches[j] during divergence — by construction."

## Key Source Files and Responsibilities

The branch isolation architecture spans multiple files in the UditAkhourii/adhd repository:

- **[`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts)**: Orchestrates the parallel fan-out with `Promise.all`; contains the `DIVERGE_SYSTEM` prompt and the `divergeBranch` function that invokes fresh LLM calls.
- **[`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts)**: Implements `callLLM`, which wraps the Claude Agent SDK `query` in a stateless manner—the core of the isolation guarantee.
- **[`documentation/how-it-works.md`](https://github.com/UditAkhourii/adhd/blob/main/documentation/how-it-works.md)**: Provides the high-level description of the isolation invariant at lines 42-49, noting that "Each divergent branch is its own `query()` call … a fresh, stateless session with no shared KV‑cache, no shared message history."
- **[`src/frames.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/frames.ts)**: Supplies the per-branch cognitive frames that are injected into each isolated query without cross-pollination.
- **[`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts)**: Defines the `Branch` and `Idea` structures used to collect isolated results from independent sessions.

## Summary

- **Stateless by Design**: The `callLLM` wrapper in [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts) creates a fresh Claude SDK `query` for every branch, ensuring no shared KV-cache or message history.
- **Prompt Isolation**: Each branch receives the `DIVERGE_SYSTEM` prompt in a virgin context, as implemented in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) lines 61-69.
- **Architectural Separation**: Parallel execution via `Promise.all` in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) lines 4-6 guarantees that branch A executes independently of branch B by construction.
- **Invariant Enforcement**: The documentation at [`documentation/how-it-works.md`](https://github.com/UditAkhourii/adhd/blob/main/documentation/how-it-works.md) lines 42-49 explicitly codifies this as the "branch isolation invariant," distinguishing ADHD from traditional Tree-of-Thought approaches that suffer from anchoring effects.

## Frequently Asked Questions

### What prevents branches from sharing the KV-cache during divergence?

The `callLLM` function in [`src/llm.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/llm.ts) instantiates a brand-new Claude Agent SDK `query` object for each branch invocation. Because this call uses no cached conversation history or shared session state, the underlying LLM's KV-cache remains confined to that single query instance. As stated in the documentation at lines 42-49, each branch operates as "a fresh, stateless session."

### How does ADHD differ from standard Tree-of-Thought implementations?

Traditional Tree-of-Thought approaches often reuse the same LLM session or context window across branches, leading to anchoring effects where early branches bias later ones. ADHD eliminates this by enforcing **branch isolation**—each parallel branch runs in a completely separate LLM session with no visibility into other branches' prompts or outputs, ensuring truly independent reasoning paths.

### Where is the branch isolation invariant formally documented?

The invariant is explicitly described in [`documentation/how-it-works.md`](https://github.com/UditAkhourii/adhd/blob/main/documentation/how-it-works.md) at lines 42-49 and lines 73-74. The documentation states that branches never see each other during divergence "by construction" and defines each divergent branch as its own isolated `query()` call with zero shared resources.

### Can the isolation mechanism handle high concurrency without resource contention?

Yes. The divergence phase in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) uses `pLimit` to manage concurrency while maintaining isolation. Because each `divergeBranch` call is independent and stateless, increasing the number of parallel branches scales horizontally without creating resource contention in the LLM sessions themselves—each remains a separate, isolated query.