How ADHD Implements Branch Isolation During the Diverge Phase

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

The foundation of isolation resides in the callLLM function located in 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.

// 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

While the wrapper provides the container, 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 (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.

// 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 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: 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: Implements callLLM, which wraps the Claude Agent SDK query in a stateless manner—the core of the isolation guarantee.
• 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: Supplies the per-branch cognitive frames that are injected into each isolated query without cross-pollination.
• 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 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 lines 61-69.
• Architectural Separation: Parallel execution via Promise.all in 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 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 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 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 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.

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