# What Is the Core Architecture of DeepSeek-Reasonix? A Deep Dive into the Agent Framework

> Explore the core architecture of DeepSeek-Reasonix, a Go-based agent framework. Discover its registry-based abstractions, execution loop, and dual-model coordination for efficient code generation and execution.

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

---

**DeepSeek-Reasonix is a config- and plugin-driven coding agent built in Go that uses registry-based abstractions for providers, tools, and plugins, with a core execution loop that streams LLM completions, executes tool calls, and optionally coordinates between two models for planning and execution.**

The DeepSeek-Reasonix project provides a lean, extensible framework for LLM-driven coding workflows. Written primarily in Go standard library, the architecture emphasizes modularity through registration-based registries that allow providers and tools to self-register without core code modifications.

## Overview of the Layered Architecture

The DeepSeek-Reasonix core architecture consists of eight distinct layers, each responsible for specific concerns in the agent lifecycle. These layers communicate through well-defined interfaces rather than concrete implementations, enabling the system to remain agnostic to specific LLM providers or tool implementations.

The architecture follows this execution flow:

1. **Startup** – The CLI in [`cmd/reasonix/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/cmd/reasonix/main.go) parses [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml), initializes the provider registry, and builds the tool registry.
2. **Session creation** – A `Session` object holds a slice of `Message` structs, beginning with the system prompt from configuration.
3. **Model streaming** – The `Provider.Stream` method yields `Chunk` structs containing text, tool calls, or errors.
4. **Tool execution** – Incoming `ChunkToolCall` values trigger `Tool.Execute` methods after permission checks.
5. **Loop continuation** – Tool results append to the message history, and the request repeats until receiving `ChunkDone` or hitting step limits.

## The Provider Registry: Abstracting LLM Endpoints

The **Provider Registry** ([`internal/provider/provider.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/provider.go)) abstracts any OpenAI-compatible or Anthropic-style LLM endpoint through a minimal interface. Providers self-register via `init()` functions, making the core completely unaware of concrete implementations until runtime.

The registry defines three key components:

- **`Provider`** interface – The contract for streaming completions and handling model-specific formatting.
- **`Factory`** – Creates provider instances from configuration blocks.
- **`Register`** and **`New`** – Functions that populate the registry and instantiate providers by name.

In [`internal/provider/openai/openai.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/openai/openai.go), the OpenAI-compatible implementation (used for DeepSeek endpoints) parses configuration like this:

```toml
[[providers]]
name       = "deepseek"
kind       = "openai"
base_url   = "https://api.deepseek.com"
models     = ["deepseek-v4-flash", "deepseek-v4-pro"]
default    = "deepseek-v4-flash"
api_key_env = "DEEPSEEK_API_KEY"
context_window = 1000000

```

When the program starts, the `openai` provider factory produces a provider instance capable of streaming `Chunk` values to the agent loop.

## The Tool Registry and Plugin System

The **Tool Registry** ([`internal/tool/tool.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/tool.go)) manages both built-in file-system tools and external MCP (Model Context Protocol) plugins. Tools implement the **`Tool`** interface and register via `RegisterBuiltin`, while the `Builtins` map provides access to standard operations like `read_file` and `write_file`.

The **Plugin System** ([`internal/plugin/plugin.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/plugin/plugin.go) and [`internal/plugin/transport.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/plugin/transport.go)) extends tooling through external processes. Plugins defined in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) launch as stdio or HTTP subprocesses, exposing tools via JSON-RPC according to the MCP protocol:

```toml
[[plugins]]
name   = "example"
command = "reasonix-plugin-example"
args   = []

```

The plugin's advertised tools automatically adapt to the `Tool` interface, allowing the agent to invoke `example_tool` identically to built-in operations.

## The Agent Loop: Core Execution Engine

The **Agent Loop** ([`internal/agent/agent.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/agent.go)) serves as the central execution engine. It coordinates between the provider streaming interface and the tool registry through a stateful `Session` struct.

Key abstractions in this layer include:

- **`Session`** – Maintains conversation history and tool schemas.
- **`Run`** – The main execution method that handles the request-response cycle.
- **`Chunk`** – A discriminated union type representing text deltas, tool calls, errors, or completion signals.

When the provider returns a `ChunkToolCall`, the loop dispatches to the corresponding `Tool.Execute` method, appends the result as a new message, and continues the conversation.

## Two-Model Collaboration with the Coordinator

When configuration specifies a `planner_model` distinct from the executor, the **`Coordinator`** ([`internal/agent/coordinator.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/coordinator.go)) manages two isolated sessions:

1. **Planner session** – Runs the high-capability model to generate a structured execution plan.
2. **Executor session** – Receives the plan as context and handles implementation details.

This separation preserves each model's cache-stable prefix while allowing specialized reasoning models to guide more efficient executors. The coordinator passes structured plans between sessions via `RunPlanner` and `RunExecutor` methods.

## Context Management and Token Optimization

The **Context Management** layer ([`internal/agent/compact.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/compact.go)) monitors token utilization through a configurable `compactRatio`. When the conversation window exceeds this threshold, the [`compact.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/compact.go) module folds older assistant and tool messages into concise summaries while preserving user turns verbatim.

This compaction strategy maintains conversation coherence without hitting context window limits, crucial for long-running coding sessions with extensive tool outputs.

## Permission Layer and Security

The **Permission Layer** ([`internal/permission/decision.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/permission/decision.go) and [`internal/permission/policy.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/permission/policy.go)) implements fine-grained access control through policy definitions. Before executing any tool call, the system evaluates a `Decision` against the configured `Policy` through a `Gate` construct.

Policies support three enforcement levels per tool:

- **Allow** – Execute immediately without confirmation.
- **Ask** – Prompt for interactive approval (integrates with the TUI).
- **Deny** – Block execution unconditionally.

## Slash Commands and User Interface

The **Slash-Command System** ([`internal/command/command.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/command/command.go)) parses `/command` and `@` references, dispatching to custom markdown commands stored in `.reasonix/commands/`. These commands support argument interpolation and resolve local file references or MCP resources.

The **Desktop UI** ([`desktop/frontend/src/components/Composer.tsx`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/frontend/src/components/Composer.tsx)) provides a Bubble Tea-based terminal interface featuring:

- Autocomplete menus for `@` file references and `/` commands.
- Modal overlays for permission decisions.
- Real-time streaming of LLM responses.

## Summary

- **Registry-based design** – Providers and tools self-register via `init()`, keeping the core agnostic to implementations.
- **Minimal dependencies** – Built primarily with Go standard library for a single-binary deployment.
- **Pluggable LLM support** – The `Provider` interface in [`internal/provider/provider.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/provider.go) abstracts any OpenAI-compatible or Anthropic endpoint.
- **MCP-compatible plugin system** – External tools integrate via JSON-RPC without core code changes.
- **Two-model coordination** – Optional `Coordinator` separates planning from execution when configured with distinct `planner_model` values.
- **Automatic context compaction** – Token monitoring with configurable `compactRatio` prevents context window exhaustion.
- **Fine-grained permissions** – Per-tool policy enforcement with interactive approval workflows.

## Frequently Asked Questions

### How does DeepSeek-Reasonix handle different LLM providers without code changes?

The framework uses a **registry pattern** where providers implement the `Provider` interface and register themselves via `init()` functions in [`internal/provider/provider.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/provider.go). Adding a new model requires only updating [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) with the endpoint configuration, as the concrete implementation (e.g., [`internal/provider/openai/openai.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/openai/openai.go)) handles the protocol-specific details.

### What is the difference between built-in tools and MCP plugins?

**Built-in tools** (registered via `RegisterBuiltin` in [`internal/tool/tool.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/tool.go)) are compiled into the binary and include file-system operations. **MCP plugins** (defined in [`internal/plugin/plugin.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/plugin/plugin.go)) run as external processes communicating via JSON-RPC, allowing integration with tools written in any language without recompiling Reasonix.

### How does the two-model collaboration feature work?

The `Coordinator` in [`internal/agent/coordinator.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/coordinator.go) creates two isolated `Session` instances when `planner_model` differs from the default executor. It first runs `RunPlanner` to generate a structured plan, then injects that plan as context into `RunExecutor`. This preserves each model's conversation cache while leveraging specialized capabilities for different reasoning phases.

### Can I customize the permission policies for specific tools?

Yes. The **Permission Layer** ([`internal/permission/policy.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/permission/policy.go)) supports per-tool configuration with `allow`, `ask`, and `deny` policies. When a tool call arrives, the `Gate` evaluates the `Decision` against the active policy, enabling interactive approvals for destructive operations like `write_file` while allowing automatic execution of read-only tools.