How Two-Model Collaboration (Planner + Executor) Works in DeepSeek-Reasonix

DeepSeek-Reasonix runs two LLMs simultaneously—a lightweight planner that creates concise execution plans and a full-featured executor that implements them—keeping each in isolated, cache-stable sessions to preserve prefix caches and minimize token costs.

DeepSeek-Reasonix is an open-source coding agent that optimizes inference costs through a sophisticated two-model collaboration pattern. By isolating a low-frequency planner and a tool-rich executor in independent sessions, the system preserves KV-cache prefixes and eliminates expensive re-prefixing when switching between strategic planning and tactical execution.

The Coordinator Architecture

The collaboration is orchestrated by the Coordinator type defined in internal/agent/coordinator.go. This struct manages two distinct LLM instances while ensuring their conversation histories remain isolated to maintain cache stability.

Separate Sessions for Cache Stability

The Coordinator maintains independent sessions for each model to prevent context contamination. The planner receives its own Session (plannerSess) while the executor operates through the standard Agent session. Both sessions initialize with a shared, cache-stable system prompt containing project memory from REASONIX.md and AGENTS.md plus the skill index.

type Coordinator struct {
    planner     provider.Provider
    plannerSess *Session          // planner’s own session
    plannerSystem string
    ...
    executor    *Agent            // full tool‑using executor
}

Source: lines 43-48 of internal/agent/coordinator.go【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/agent/coordinator.go#L43-L48】

Because the planner and executor each maintain their own session, their prefixes are never mixed. The prefix—comprising the system prompt, memory files, and skill index—is built once at session creation and subsequently only appended with turn messages. This architectural choice preserves the prefix cache for both models independently, as detailed in docs/SPEC.md section 3.5【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/docs/SPEC.md#L162-L176】.

The Planning Phase

When processing user input, the Coordinator.Run method first evaluates shouldPlan to determine if planning is required. When triggered, the planner executes using a compact system prompt (DefaultPlannerPrompt) combined with standing project context (PlannerPromptWithContext). Crucially, the planner operates with read-only research tools and never encounters write-enabled tools.

Source: Run method lines 59-71 and prompt definitions lines 20-41【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/agent/coordinator.go#L59-L71】【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/agent/coordinator.go#L20-L41】

The planner emits a structured, ordered plan as a "phase" event before handing control to the executor.

Executor Hand-Off

The generated plan is inserted into a special executorHandoffMarker and formatted via formatHandoff into a single input string passed to the executor. The executor then operates exactly as a standard single-model Agent, utilizing all available tools including write operations.

Source: hand-off constant line 31 and usage line 76-78【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/agent/coordinator.go#L31-L32】【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/agent/coordinator.go#L76-L78】

Configuration and Usage

Enabling Two-Model Mode

Activate the two-model collaboration by specifying distinct models in your reasonix.toml configuration file:

default_model = "deepseek-flash"   # executor

planner_model = "deepseek-pro"    # low‑frequency planner

planner_max_steps = 0             # 0 = unlimited planner rounds

When planner_model is defined, internal/boot/boot.go detects this setting during initialization and constructs a Coordinator rather than a standard single Agent.

Source: boot.Build lines 21-23【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/boot/boot.go#L21-L23】

Programmatic Integration

Embed the two-model workflow directly in Go applications:

ctx := context.Background()
ctrl, _ := boot.Build(ctx, boot.Options{
    Model: "deepseek-flash",                // executor
    // planner_model is read from config; you could also set it here
})
// ctrl.Controller implements Runner – it will be a Coordinator
ctrl.Controller.Run(ctx, "refactor the auth package")

The Build function automatically instantiates the Coordinator when it detects agent.planner_model in the configuration, wireing the planner and executor with their respective cache-stable sessions.

Summary

• Architecture: The Coordinator type in internal/agent/coordinator.go manages dual sessions for planner and executor LLMs.
• Cache Stability: Independent sessions ensure each model's prefix (system prompt + memory + skills) remains cache-stable and append-only.
• Capability Separation: The planner uses read-only tools for strategic planning, while the executor employs full write-capable toolsets for implementation.
• Activation: Set planner_model in reasonix.toml or pass it through boot.Options to enable the two-model collaboration.
• Hand-off: Plans transfer via executorHandoffMarker from the low-frequency planner to the full-featured executor without session mixing.

Frequently Asked Questions

What makes the sessions "cache-stable" in DeepSeek-Reasonix?

The sessions are cache-stable because each model maintains its own isolated Session instance with a fixed prefix composed of the system prompt, REASONIX.md memory, and skill index. Since this prefix is built once at initialization and only appended with new turn messages, the underlying KV-cache remains valid across interactions, avoiding expensive re-computation when switching between the planner and executor.【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/docs/SPEC.md#L162-L176】

Why does the planner only have access to read-only tools?

Restricting the planner to read-only research tools prevents premature writes during the strategic planning phase. This separation ensures the planner focuses on creating concise, ordered execution plans without side effects, while the executor handles all file modifications and state changes using the complete toolset。【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/agent/coordinator.go#L20-L41】

How do I configure different models for the planner and executor?

Define the planner_model field in your reasonix.toml configuration file alongside your default_model. The internal/boot/boot.go initialization logic detects this field and automatically constructs a Coordinator instead of a standard Agent, wiring the two specified models into their respective cache-stable sessions.【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/boot/boot.go#L21-L23】

Can the planner run multiple reasoning steps before handing off?

Yes. The planner_max_steps configuration controls how many reasoning rounds the planner executes before generating the final plan. Setting this to 0 allows unlimited planner rounds, enabling complex multi-step strategic analysis before the executor receives the hand-off marker and begins implementation.【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/README.md#L58-L61】

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