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

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, which handles CLI parsing and TOML configuration loading. This layer resolves provider and model names from reasonix.toml, initializes the registries, and launches the appropriate session mode (headless or TUI).

Provider Registry and LLM Abstraction

At 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 handles OpenAI-compatible APIs (including DeepSeek), parsing configuration blocks to instantiate streaming clients.

[[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 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, which spawns MCP (Model Context Protocol) processes over stdio or HTTP as defined in internal/plugin/transport.go. Plugins advertised via JSON-RPC are automatically adapted to the Tool interface and merged with the built-in registry.

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

Agent Execution Loop

The core engine resides in 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 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.

[agent]
planner_model = "deepseek-pro"

Context Management and Permissions

To handle long conversations, 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, 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, which parses /command and @ references to resolve local files or MCP resources. The Bubble-Tea based TUI in 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, 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 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:

# 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:

---
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), Tool Registry (internal/tool/tool.go), Agent Loop (internal/agent/agent.go), and Coordinator (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 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) 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) 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 specifying the kind (e.g., openai) and endpoint details; the factory in internal/provider/provider.go instantiates it automatically. For tools, either add built-in Go code that calls RegisterBuiltin in internal/tool/tool.go, or deploy an MCP-compatible binary and reference it in the [[plugins]] section of the configuration file.

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