# DeepSeek-Reasonix Architecture: Core Design of a Config-Driven Coding Agent

> Explore the DeepSeek-Reasonix architecture, a Go-based coding agent. Learn about its modular design, dual-model coordinator, context compaction, and permission-gated execution.

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

---

**DeepSeek-Reasonix is a lightweight, registry-based coding agent written in Go that orchestrates LLM providers, tools, and plugins through a modular architecture featuring a dual-model coordinator, context compaction, and permission-gated execution.**

DeepSeek-Reasonix (from the esengine/DeepSeek-Reasonix repository) implements a deliberately lean architecture using mostly standard-library Go. Its **DeepSeek-Reasonix architecture** centers on registry-based abstractions that allow providers and tools to self-register via `init()` functions, keeping the core agnostic of concrete implementations while enabling powerful extensibility through configuration alone.

## DeepSeek-Reasonix Core Architecture Layers

The system is organized into distinct layers that communicate through well-defined interfaces, enabling the agent to remain agnostic of specific LLM implementations or tool types.

### Configuration and CLI Entry Point

The application lifecycle begins in [`cmd/reasonix/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/cmd/reasonix/main.go), which handles CLI parsing and TOML configuration loading. This layer resolves provider and model names from [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml), initializes the registries, and launches the appropriate session mode (headless or TUI).

### Provider Registry and LLM Abstraction

At [`internal/provider/provider.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/provider.go), the **Provider** interface abstracts any LLM-compatible endpoint using a factory pattern. Providers self-register via `init()` functions and expose `Factory`, `Register`, and `New` methods. The concrete implementation in [`internal/provider/openai/openai.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/openai/openai.go) handles OpenAI-compatible APIs (including DeepSeek), parsing configuration blocks to instantiate streaming clients.

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

```

### Tool Registry and MCP Plugin System

The **Tool** interface defined in [`internal/tool/tool.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/tool.go) manages built-in file-system tools (`read_file`, `write_file`, etc.) via `RegisterBuiltin` and `Builtins`. External tools arrive through the plugin system at [`internal/plugin/plugin.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/plugin/plugin.go), which spawns MCP (Model Context Protocol) processes over stdio or HTTP as defined in [`internal/plugin/transport.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/plugin/transport.go). Plugins advertised via JSON-RPC are automatically adapted to the Tool interface and merged with the built-in registry.

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

```

### Agent Execution Loop

The core engine resides in [`internal/agent/agent.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/agent.go), implementing the **Session** type that manages `[]Message` and orchestrates the request-response cycle. The `Run` method assembles tool schemas, streams completions via `Provider.Stream`, and yields `Chunk` types (text, tool calls, or termination signals). When the model emits a `ChunkToolCall`, the agent locates the corresponding `Tool.Execute` implementation, runs the logic, and appends the result to the message history before re-prompting.

### Two-Model Collaboration Coordinator

When configuration specifies a `planner_model` distinct from the executor, the **Coordinator** in [`internal/agent/coordinator.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/coordinator.go) activates. This layer runs two isolated **Session** instances: first invoking `RunPlanner` to generate a structured plan, then passing that plan to `RunExecutor` while preserving each model’s cache-stable prefix. This separation allows high-capacity models to strategize while fast models handle implementation.

```toml
[agent]
planner_model = "deepseek-pro"

```

### Context Management and Permissions

To handle long conversations, [`internal/agent/compact.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/compact.go) monitors token usage via `compactRatio`. When the window reaches a configurable threshold, the **Compaction** layer folds older assistant and tool messages into summaries while preserving user turns verbatim. Security is enforced by [`internal/permission/decision.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/permission/decision.go), where the **Policy** and **Gate** types evaluate per-tool `Decision` levels (allow, ask, deny) before execution proceeds.

### Command System and Desktop UI

User interaction layers include the slash-command dispatcher at [`internal/command/command.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/command/command.go), which parses `/command` and `@` references to resolve local files or MCP resources. The Bubble-Tea based TUI in [`desktop/frontend/src/components/Composer.tsx`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/frontend/src/components/Composer.tsx) provides autocomplete menus for these commands and manages modal overlays for the permission gate.

## Execution Flow and Lifecycle

The **DeepSeek-Reasonix architecture** follows a predictable lifecycle:

1. **Startup**: CLI parses [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml), builds the **Provider** and **Tool** registries (built-ins plus MCP plugins).
2. **Session Creation**: A **Session** initializes with `[]Message` containing the system prompt from config.
3. **Model Streaming**: `Provider.Stream` yields **Chunk** structs until the model signals `ChunkDone` or a step limit is reached.
4. **Tool Execution**: Upon receiving `ChunkToolCall`, the agent checks permissions via the **Gate**, executes the **Tool**, and appends results.
5. **Loop**: The updated message list is re-sent to the provider until completion or termination.
6. **Collaboration (Optional)**: If configured, the **Coordinator** runs the planner session first, extracts the plan, and seeds the executor session with that context.

## Registry-Based Extensibility

All concrete implementations self-register through Go’s `init()` functions, meaning the core code never imports specific providers or tools directly. Adding new capabilities requires only updating [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) or dropping a plugin binary into the path—no recompilation of the agent core. This design keeps the binary single and static while supporting dynamic ecosystems of models and tools.

## Practical Configuration Examples

Running a headless session from the command line:

```bash

# Uses default config (writes a sample if missing)

reasonix run "Write a Python function that returns the nth Fibonacci number."

```

Defining a custom slash command in [`.reasonix/commands/review.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/.reasonix/commands/review.md):

```markdown
---
description: Review staged diff
argument-hint: [focus-area]
---
Review the staged diff. List bugs with file:line in $ARGUMENTS.

```

Users can then invoke `/review docs` in the TUI, which renders the markdown and sends it as the next user turn.

## Summary

- **DeepSeek-Reasonix** is a config-driven coding agent built primarily with Go standard libraries.
- **Registry-based design** allows providers and tools to self-register via `init()`, decoupling interfaces from implementations.
- **Core components** include the Provider Registry ([`internal/provider/provider.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/provider.go)), Tool Registry ([`internal/tool/tool.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/tool.go)), Agent Loop ([`internal/agent/agent.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/agent.go)), and Coordinator ([`internal/agent/coordinator.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/coordinator.go)).
- **Dual-model support** enables planner/executor separation for complex tasks.
- **Context compaction** and **permission gates** provide production-ready memory management and security.
- **Extensibility** is configuration-driven via TOML files and MCP plugins without core code changes.

## Frequently Asked Questions

### What makes DeepSeek-Reasonix different from other coding agents?

DeepSeek-Reasonix employs a **registry-based architecture** where providers and tools register themselves through Go’s `init()` mechanism, allowing the core to remain completely agnostic of specific LLM implementations or tool types. Unlike monolithic agents, it requires no code changes to add new models or capabilities—only configuration updates in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) or MCP plugin additions.

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

When `planner_model` is configured differently from the default executor model, the **Coordinator** (implemented in [`internal/agent/coordinator.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/coordinator.go)) instantiates two separate **Session** objects. It first runs the planner model to generate a structured plan, then passes that plan as initial context to the executor model. This preserves each model’s cache-stable prefix while allowing high-capacity models to handle strategy and faster models to handle implementation details.

### What is context compaction and why is it necessary?

Context compaction (defined in [`internal/agent/compact.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/compact.go)) monitors token usage per provider against a `compactRatio` threshold. When the conversation window fills, the system summarizes older assistant and tool messages into concise digests while keeping user messages verbatim. This prevents token limit errors during long coding sessions without losing conversational continuity.

### How do I add a custom LLM provider or tool?

For providers, define a new `[[providers]]` block in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) specifying the `kind` (e.g., `openai`) and endpoint details; the factory in [`internal/provider/provider.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/provider.go) instantiates it automatically. For tools, either add built-in Go code that calls `RegisterBuiltin` in [`internal/tool/tool.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/tool.go), or deploy an MCP-compatible binary and reference it in the `[[plugins]]` section of the configuration file.