How to Contribute to the DeepSeek-Reasonix Project: A Complete Developer's Guide

To contribute to the DeepSeek-Reasonix project, fork the repository, work against the main-v2 branch, follow Go formatting standards with gofmt, and submit pull requests that include cache-impact metadata for any changes affecting prompts, memory, or tool registration.

DeepSeek-Reasonix is a Go-based AI coding agent that runs as a single static binary or as a Wails-based desktop application. The repository follows a strict modular architecture where each logical layer lives under its own internal/* package, making it essential for contributors to understand the codebase organization before submitting changes.

Understanding the Modular Architecture

The project separates concerns into distinct internal packages. Each layer has a specific responsibility and documented entry point:

Layer	Package	Purpose	Key File
CLI entry point	cmd/reasonix	Parses flags, loads configuration, and starts the engine	cmd/reasonix/main.go
Agent core	internal/agent	Orchestrates sessions including planning, tool execution, and memory handling	internal/agent/agent.go
Terminal UI	internal/cli	Provides the TUI, sub-commands like setup and run, and the configuration wizard	internal/cli/setup.go
Configuration	internal/config	Loads TOML files from project, user, and global locations with flag overrides	internal/config/
Tooling	internal/tool/builtin	Implements built-in tools (bash, read_file, write_file) via the tool.Tool interface	internal/tool/builtin/
Provider abstraction	internal/provider	Wraps OpenAI-compatible endpoints (DeepSeek, OpenAI, Azure) via provider.Provider interface	internal/provider/openai/provider.go
Plugins (MCP)	internal/plugin	Enables external JSON-RPC tools over stdio or HTTP	internal/plugin/
Memory system	internal/memory	Manages the AGENTS.md hierarchy, checkpoint snapshots, and auto-memory extraction	internal/memory/
Sandbox	internal/sandbox	Confines file-system writes to the workspace root with write-allow lists	internal/sandbox/
Web frontend	internal/serve	Serves the engine over HTTP/SSE for browser-based UI	internal/serve/
Desktop app	desktop/	Wails-based GUI as a separate Go module sharing internal packages	desktop/

Setting Up Your Development Environment

Before contributing, verify your local environment can build and test the project:

1. Fork the repository and clone your fork:

   git clone https://github.com/YOUR_USERNAME/DeepSeek-Reasonix.git
   cd DeepSeek-Reasonix

2. Checkout the active development branch:

   git checkout main-v2

3. Build the binary and run the test suite:

   make build    # Creates ./bin/reasonix
   
   make test     # Runs the full test suite
   

The build process requires Go and Make. The make build command compiles the CLI binary, while make test validates changes against the existing test harness.

Contribution Workflow

Follow these steps to ensure your contribution meets repository standards:

1. Create a feature branch from main-v2 with a descriptive name.

2. Adhere to Go conventions:

   • Run gofmt -w . before committing to ensure consistent formatting
   • Wrap errors using fmt.Errorf("...: %w", err) for proper error chaining
   • Never call os.Exit or write to stdout/stderr from library code—only the CLI layer in cmd/reasonix may exit

3. Add comprehensive tests for new behavior. Reference existing test patterns in internal/agent/*_test.go.

4. Document cache impact if you modify prompt construction, memory prefixes, or tool registration. Add a Cache-impact: line to your PR body (e.g., Cache-impact: low – added new builtin tool).

5. Validate your changes:

   make test

6. Commit using Conventional Commits style (e.g., feat: add grep tool, fix: handle nil config).

7. Submit a PR targeting main-v2. The CI pipeline automatically validates formatting, linting, test passing, and cache-impact metadata.

Code Examples

Building and Running the CLI Locally

# Clone and enter the repository

git clone https://github.com/esengine/DeepSeek-Reasonix.git
cd DeepSeek-Reasonix

# Build the binary

make build

# Run the setup wizard to create reasonix.toml

./bin/reasonix setup

# Execute a task

./bin/reasonix run "refactor the error handling in internal/agent/session.go"

Adding a New Built-in Tool

Create a new file in internal/tool/builtin/ implementing the tool.Tool interface:

// internal/tool/builtin/greet.go
package builtin

import (
    "context"
    "encoding/json"
    "reasonix/internal/tool"
)

type greetTool struct{}

func (g greetTool) Name() string        { return "greet" }
func (g greetTool) Description() string { return "Returns a friendly greeting" }
func (g greetTool) Schema() tool.Schema { return tool.Schema{} }
func (g greetTool) ReadOnly() bool      { return true }

func (g greetTool) Execute(ctx context.Context, args json.RawMessage) (any, error) {
    return map[string]string{"message": "Hello from Reasonix!"}, nil
}

func init() { tool.RegisterBuiltin(greetTool{}) }

Test your implementation:

make test ./internal/tool/builtin/...

Implementing a Custom Provider

Add support for new LLM endpoints by implementing the provider.Provider interface:

// internal/provider/custom/custom.go
package custom

import (
    "context"
    "reasonix/internal/provider"
)

type customProvider struct {
    cfg provider.Config
}

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

func (p *customProvider) Stream(ctx context.Context, prompt string) (<-chan provider.Response, error) {
    // Implementation for your specific LLM API
    out := make(chan provider.Response)
    // ... streaming logic ...
    return out, nil
}

func New(cfg provider.Config) (provider.Provider, error) {
    return &customProvider{cfg: cfg}, nil
}

func init() { provider.Register("custom", New) }

Configure the provider in reasonix.toml:

[[providers]]
name = "my-custom"
kind = "custom"
base_url = "https://my-llm.example.com/v1"
api_key_env = "MY_API_KEY"

Summary

• DeepSeek-Reasonix uses a modular Go architecture with clear separation between CLI, agent core, tools, and providers.
• Target the main-v2 branch for all contributions and follow the seven-step workflow.
• Mandatory requirements: gofmt formatting, error wrapping with %w, no os.Exit in library code, and cache-impact documentation for relevant changes.
• Extension points: Implement tool.Tool for new capabilities, provider.Provider for new LLM backends, and register via init() functions.
• Reference CONTRIBUTING.md in the repository root for the authoritative checklist and commit message standards.

Frequently Asked Questions

What branch should I target when contributing to DeepSeek-Reasonix?

Always target the main-v2 branch when submitting pull requests. This is the active development branch where all new features and bug fixes are integrated. The CI pipeline automatically validates PRs against this branch for formatting, testing, and metadata requirements.

How do I add a new built-in tool to the project?

Create a new Go file in internal/tool/builtin/ that implements the tool.Tool interface, including Name(), Description(), Schema(), ReadOnly(), and Execute() methods. Register the tool in an init() function using tool.RegisterBuiltin(). Ensure the tool is read-only if it doesn't modify the filesystem, and add tests following the patterns in internal/agent/*_test.go.

What is the cache-impact metadata requirement?

The cache-impact line in your PR body indicates whether your changes affect cached components like prompt construction, memory prefixes, or tool registration. This metadata helps maintainers understand performance implications. Format it as Cache-impact: low/medium/high - description, even for changes with no impact (e.g., Cache-impact: none - documentation fix).

Can I contribute to the desktop application separately from the CLI?

Yes, the desktop application in the desktop/ directory is a separate Go module using the Wails framework, but it shares the same internal packages as the CLI. When contributing desktop-specific features, ensure you still follow the same Go formatting standards and test the desktop build with make build from the root, which compiles both components.

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