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

> Explore the two-model collaboration in DeepSeek-Reasonix. A planner and executor work together in separate sessions to create efficient execution plans, reduce costs, and preserve cache.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: deep-dive
- Published: 2026-06-22

---

**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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/REASONIX.md) and [`AGENTS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/AGENTS.md) plus the skill index.

```go
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) configuration file:

```toml
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

```go
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) configuration file alongside your `default_model`. The [`internal/boot/boot.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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】