Expected Directory Structure for DeepSeek-Reasonix: Complete Guide

DeepSeek-Reasonix organizes its codebase into distinct layers—internal/ for the core Go engine, desktop/ for the Wails frontend, sdk/go/ for embeddable libraries, and npm/ for Node distribution—enforcing strict import boundaries that prevent frontend code from leaking into business logic.

The DeepSeek-Reasonix repository follows a purpose-driven layout designed to support cross-platform builds and single-binary distribution. Understanding the expected directory structure is essential for contributors embedding the engine into custom tools or extending the desktop application.

Top-Level Layout Overview

The repository root separates concerns into seven primary domains. Each top-level directory owns a specific responsibility and maintains strict import rules as defined in REASONIX.md.

Directory	Purpose
internal/	Core Go engine containing business logic, providers, agents, and utilities.
desktop/	Desktop frontend built with Wails and WebView2; consumes internal/control only.
sdk/go/	Go SDK exposing a thin client library for embedding Reasonix in other programs.
npm/	Node CLI wrapper distributing pre-built native binaries via npm.
docs/	Human-readable documentation and GitHub Pages source files.
scripts/	Release automation, signature verification, and CI helper scripts.
site/	Static site assets (TypeScript, CSS, images) for documentation generation.

Additional top-level files include README.md for installation instructions, REASONIX.md for project conventions, Makefile for build automation, and .goreleaser.yaml for cross-compilation configuration.

Core Engine Layer (internal/)

The internal/ directory houses the pure business logic of DeepSeek-Reasonix. This layer implements the agent-loop, workspace sandboxing, checkpoint/rewind functionality, and the unified controller that frontends invoke.

Key sub-packages include:

• internal/worktree/ – Workspace handling and file operations sandbox
• internal/boot/ – Initialization and configuration loading
• internal/agent/ – Core agent loop and reasoning implementation
• internal/control/ – The only public-facing internal package that frontends may import

According to the layering rules in REASONIX.md, no code within internal/ may import from desktop/ or other frontend layers. This ensures the engine remains portable across CLI, desktop, and HTTP server contexts.

Frontend and SDK Components

Desktop Application (desktop/)

The desktop/ directory contains the Wails-based frontend utilizing WebView2. Platform-specific files such as window_state.go and updater_windows.go handle window management and auto-updates.

All UI code calls into internal/control.Controller as implemented in desktop/workspace.go. The import relationship is strictly one-way: desktop/ imports internal/control, but internal/ never imports desktop/.

Go SDK (sdk/go/)

Located at sdk/go/, this directory provides a public API wrapper defined in sdk/go/sdk.go. It enables other Go programs to embed the Reasonix engine without directly depending on internal packages.

package main

import (
	"context"
	"log"

	"github.com/esengine/DeepSeek-Reasonix/sdk/go"
)

func main() {
	// Initialize a Reasonix instance with a config file
	r, err := reasonix.New(context.Background(), "reasonix.example.toml")
	if err != nil {
		log.Fatalf("init error: %v", err)
	}
	
	// Run a simple command
	out, err := r.Run("implement the TODOs in main.go")
	if err != nil {
		log.Fatalf("run error: %v", err)
	}
	log.Println("Result:", out)
}

Distribution and Documentation

Node Wrapper (npm/)

The npm/ directory packages the native binary for Node.js distribution. The wrapper script at npm/reasonix/bin/reasonix.js downloads the pre-built static binary and exposes the reasonix CLI globally after npm i -g reasonix.

Documentation (docs/ and site/)

User-facing documentation lives in docs/ as Markdown files, which also serve as the source for the GitHub Pages site. The site/ directory contains TypeScript configurations and styling assets for the static site generator.

Release Automation (scripts/)

Release validation scripts reside in scripts/, including validate-cli-release-manifest.sh for artifact verification. These tools enforce project conventions defined in REASONIX.md alongside the repolint utility.

Build and CI Configuration

The repository root contains several configuration files critical for building and distribution:

• Makefile – Provides targets such as make build and make cross for compilation
• .goreleaser.yaml – Configures cross-compilation of the single static binary
• .github/workflows/ – Houses CI/CD pipelines for testing, linting, and documentation impact analysis
• go.mod / go.sum – Define Go module dependencies and lock files

End-to-end testing occurs in prod_test/ and prod_fast_test/, validating the complete engine and frontend integration in production-like environments.

Working with the Repository

Initializing the Engine via Go SDK

Import the SDK and instantiate a new Reasonix controller with a configuration file:

ctrl, err := reasonix.New(context.Background(), "config.toml")
if err != nil {
    log.Fatal(err)
}
result, err := ctrl.Run("refactor authentication logic")

Running the Desktop Application

Build and run the Wails frontend using the provided Makefile targets. The desktop layer initializes the controller through internal/control.NewController() as shown in desktop/workspace.go:

ctrl, err := control.NewController()
if err != nil { 
    log.Fatal(err) 
}
ctrl.HandleUserInput("what is the weather tomorrow?")

Installing via npm

After packaging, install the CLI globally:

npm i -g reasonix
reasonix setup          # configure provider & model

reasonix run "write a Go function that sums ints"

Executing Tests

Run the comprehensive test suite using Make or Go directly:

make test                 # unit tests + prod_test

go test ./internal/...    # validate core packages only

Summary

• internal/ contains the core Go engine with strict layering rules preventing frontend imports
• desktop/ houses the Wails+WebView2 frontend and exclusively imports internal/control
• sdk/go/ provides a public embedding API via sdk.go for third-party Go applications
• npm/ distributes pre-built binaries through a Node.js wrapper script
• docs/ and site/ maintain user documentation and static site generation assets
• scripts/ and .github/workflows/ handle release automation and CI validation

Frequently Asked Questions

What is the purpose of the internal/ directory?

The internal/ directory contains DeepSeek-Reasonix's core Go engine, including packages for workspace management (internal/worktree/), agent logic (internal/agent/), and the control interface (internal/control/). This directory enforces strict architectural boundaries where frontend code cannot be imported, ensuring business logic remains platform-agnostic and testable across CLI, desktop, and server contexts.

How does the desktop frontend communicate with the core engine?

The desktop frontend in desktop/ communicates exclusively through internal/control.Controller. As implemented in desktop/workspace.go, the UI layer initializes a controller instance and passes user input via methods like HandleUserInput(). This one-way import relationship ensures the engine remains decoupled from WebView2 and platform-specific window management code.

Can I embed DeepSeek-Reasonix in my own Go application?

Yes, through the Go SDK located in sdk/go/. The sdk.go file exposes a public API that wraps the internal engine, allowing you to instantiate Reasonix with reasonix.New() and execute commands via the Run() method without importing internal packages directly. This is the supported method for embedding the engine in external Go programs.

Where are the release automation scripts located?

Release automation scripts reside in the scripts/ directory, including artifact validation tools like validate-cli-release-manifest.sh. The .github/workflows/ directory contains CI/CD pipelines for continuous integration, while .goreleaser.yaml configures cross-platform binary compilation. Together, these tools enforce the conventions defined in REASONIX.md during the release process.

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