# DeepSeek-Reasonix Core Components: A Complete Architecture Guide

> Explore the core components of DeepSeek-Reasonix, a modular Go coding agent framework. Understand its architecture of providers, tools, plugins, and agents for LLM automation.

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

---

**DeepSeek-Reasonix is a modular Go-based coding agent framework built around interchangeable providers, tools, plugins, and agents that enable safe, extensible LLM-driven automation.**

The architecture of `esengine/DeepSeek-Reasonix` (commonly called **Reasonix**) deliberately separates concerns into thin, swappable layers. This design lets you add new language models, custom tools, or external plugins without modifying core logic. Below is a comprehensive breakdown of every component, how they interact, and how to extend them.

## Provider: The LLM Abstraction Layer

The **Provider** component abstracts any LLM vendor behind a uniform interface. Whether you're connecting to OpenAI-compatible APIs, Anthropic Claude, or custom endpoints, the same `Stream` method handles token-delta delivery.

In [`internal/provider/provider.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/provider.go), the interface looks like this:

```go
type Provider interface {
    Name() string
    Stream(ctx context.Context, req Request) (<-chan Chunk, error)
}

```

Providers self-register via `init()` functions using `provider.Register(kind, factory)`. This registry pattern lets you drop in new provider packages without touching existing code.

### Built-in Provider Registration Example

```go
// File: internal/provider/custom/custom.go
package custom

import (
    "context"
    "github.com/esengine/DeepSeek-Reasonix/internal/provider"
)

type SimpleProvider struct{ cfg provider.Config }

func (p *SimpleProvider) Name() string { return "custom" }

func (p *SimpleProvider) Stream(ctx context.Context, req provider.Request) (<-chan provider.Chunk, error) {
    // Implementation that streams from your model endpoint
    out := make(chan provider.Chunk)
    go func() {
        defer close(out)
        // ... token streaming logic ...
    }()
    return out, nil
}

func init() {
    provider.Register("custom", func(cfg provider.Config) (provider.Provider, error) {
        return &SimpleProvider{cfg: cfg}, nil
    })
}

```

The spec documents this pattern in [SPEC §3.1](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SPEC.md#31-provider--registry-internalprovider).

## Tool: Executable Actions for Agents

The **Tool** interface in [`internal/tool/tool.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/tool.go) encapsulates any callable action—from file I/O and shell commands to remote MCP tools. Every tool exposes four methods: `Name`, `Description`, `Schema` (JSON Schema for the LLM), and `Execute`.

Built-in tools live in `internal/tool/builtin/`. Here's how to register a simple greeting tool:

```go
// File: internal/tool/builtin/hello.go
package builtin

import (
    "context"
    "encoding/json"
    "github.com/esengine/DeepSeek-Reasonix/internal/tool"
)

type helloTool struct{}

func (t *helloTool) Name() string        { return "hello" }
func (t *helloTool) Description() string { return "Greets the user." }
func (t *helloTool) Schema() json.RawMessage {
    return json.RawMessage(`{"type":"object","properties":{}}`)
}
func (t *helloTool) Execute(_ context.Context, _ json.RawMessage) (string, error) {
    return "Hello, Reasonix user!", nil
}

func init() { tool.RegisterBuiltin(&helloTool{}) }

```

This mirrors the `tool.RegisterBuiltin` pattern described in [SPEC §3.2](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/SPEC.md#32-tool--registry-internaltool).

## Plugin: Out-of-Process Extensions via MCP

The **Plugin** system enables external tools and prompts through the MCP (Model Context Protocol) using JSON-RPC. Implemented in [`internal/plugin/plugin.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/plugin/plugin.go), plugins support three transport types:

- **stdio** – Local executable subprocess
- **http** – HTTP POST endpoint
- **sse** – Server-Sent Events stream

Plugins extend the agent's capabilities at runtime without recompilation, making Reasonix ideal for integrating specialized tools maintained by separate teams.

## Agent: The Core Session Orchestrator

The **Agent** in [`internal/agent/agent.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/agent.go) drives a single LLM conversation. Its responsibilities include:

1. Building the `Request` (conversation history + available tool schemas)
2. Streaming responses via `Provider.Stream`
3. Detecting `ChunkToolCall` deltas and dispatching to the appropriate tool
4. Feeding tool results back as new messages
5. Looping until completion or step limit reached

The agent also handles **context compaction**: when token usage nears the provider's `context_window`, it summarizes older turns while preserving recent facts (see SPEC §3.6).

### Typical Agent Execution Flow

```bash
$ reasonix run "Write a Python function that computes Fibonacci numbers."

```

The CLI ([`cmd/reasonix/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/cmd/reasonix/main.go)) parses this, instantiates the configured provider, and hands control to `Agent.Run`, which streams output and automatically invokes tools like `write_file` or `bash` as needed.

## Coordinator: Two-Model Collaboration

The **Coordinator** in [`internal/agent/coordinator.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/coordinator.go) implements an advanced pattern using two specialized models:

| Model | Role | Tool Access |
|-------|------|-------------|
| **Planner** | Generates high-level plans from requirements | Read-only tools only |
| **Executor** | Executes the plan with full tool access | All enabled tools |

This separation keeps each model's prompt cache stable—the planner sees a consistent read-only view, while the executor handles mutation. When `agent.planner_model` is set in config, the coordinator spawns both agents and bridges their interaction.

## Permission: Per-Tool Safety Gating

The **Permission** system in [`internal/permission/permission.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/permission/permission.go) provides three-level gating for every tool:

- **`allow`** – Execute automatically
- **`ask`** – Prompt user for confirmation
- **`deny`** – Block execution

Rules parse from TOML config and evaluate through the `Gate.Decide` method before any tool runs. This ensures safe autonomous operation even with powerful tools like `bash` or `write_file`.

## Command: Slash-Command Interface

The **Command** handler in [`internal/command/command.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/command/command.go) processes TUI inputs starting with `/`. Three sources populate the command registry:

1. **Built-ins**: `/new`, `/clear`, `/compact`
2. **Custom markdown**: Files in `.reasonix/commands/*.md`
3. **MCP prompts**: Namespaced as `/mcp__<server>__<prompt>`

Commands can trigger agent actions, modify session state, or invoke plugin-provided functionality.

## Configuration: TOML-Based Setup

Reasonix uses layered TOML configuration resolved in priority order:

```

CLI flags → project reasonix.toml → user config → defaults

```

The [`reasonix.example.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.example.toml) demonstrates providers, tools, plugins, and permission rules. Key sections include:

- `[provider]` – Model endpoints and API keys
- `[agent]` – Model selection, planner configuration, step limits
- `[[tool]]` – Built-in tool enablement
- `[[plugin]]` – MCP server connections
- `[[permission]]` – Tool-specific gating rules

## Data Types: The Streaming Protocol

Core structures in [`internal/provider/provider.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/provider.go) drive the streaming protocol:

- `Message` – Conversation turns with role and content
- `Chunk` – Token deltas or tool call fragments from providers
- `Request` – Complete payload sent to `Provider.Stream`
- `ChunkToolCall` – Structured tool invocation from the LLM

These types ensure type-safe communication between agents and providers across the codebase.

## CLI & Desktop: User-Facing Entry Points

The binary entry point at [`cmd/reasonix/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/cmd/reasonix/main.go) wires everything together:

- Parses flags and subcommands via `internal/cli/`
- Loads and merges configuration
- Initializes the Bubble-Tea TUI
- Dispatches to `Agent.Run` or `Coordinator` based on config

Users interact through either the TUI or direct command execution.

## How Components Interact at Runtime

1. **Startup**: CLI parses config, calls `provider.Register` and `tool.RegisterBuiltin` for all built-ins
2. **Session**: `internal/agent.NewRunner` builds a `*Registry` (enabled tools + plugins) and `Provider` instance
3. **Request Loop**: `Agent.Run` prepares `Request`, streams via `Provider.Stream`, consumes `Chunk`s
4. **Tool Execution**: On `ChunkToolCall`, agent registry-lookup → `permission.Gate.Decide` → `Tool.Execute` → result appended to messages
5. **Two-Model Mode**: `Coordinator` spawns planner `Agent` (read-only), hands plan to executor `Agent`
6. **Compaction**: Automatic summarization when nearing `context_window`

## Summary

DeepSeek-Reasonix components form a **plug-and-play architecture** where each layer can be swapped independently:

- **Provider** abstracts any LLM vendor behind a streaming interface
- **Tool** encapsulates executable actions with JSON Schema contracts
- **Plugin** extends capabilities via MCP without recompilation
- **Agent** orchestrates single-model sessions with compaction
- **Coordinator** enables efficient two-model planner/executor separation
- **Permission** gates tool execution for safe autonomy
- **Command** provides flexible TUI interaction
- **Configuration** layers TOML settings with sensible defaults

Together these pieces let you customize models, add capabilities, and enforce policies without forking core code.

## Frequently Asked Questions

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

Reasonix distinguishes itself through **vendor-agnostic providers** and **two-model coordination**. Unlike agents tightly coupled to OpenAI or Claude, the `Provider` interface lets you swap models by changing config. The `Coordinator` pattern further optimizes cost and latency by using a lightweight planner model for reasoning and a capable executor for implementation.

### How do I add a custom tool to Reasonix?

Implement the `Tool` interface with `Name`, `Description`, `Schema`, and `Execute` methods, then call `tool.RegisterBuiltin` in an `init()` function. Place your file in `internal/tool/builtin/` or any package imported at runtime. No core changes required—the registry discovers your tool automatically.

### Why does Reasonix use MCP for plugins instead of native Go plugins?

MCP (Model Context Protocol) via JSON-RPC provides **language-agnostic, out-of-process isolation**. Teams can write plugins in Python, TypeScript, or any language supporting JSON-RPC. This avoids Go plugin compatibility issues, enables separate versioning, and prevents plugin crashes from destabilizing the main agent.

### What happens when a conversation exceeds the context window?

The **Agent triggers compaction** (SPEC §3.6). It summarizes older assistant and tool turns into compressed representations while preserving recent messages and critical state. This keeps the conversation within `context_window` limits without losing task continuity.