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

> Learn how to contribute to the DeepSeek-Reasonix project. Follow this developer's guide to fork, format, and submit pull requests for effective collaboration.

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

---

**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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/cmd/reasonix/main.go) |
| **Agent core** | `internal/agent` | Orchestrates sessions including planning, tool execution, and memory handling | [`internal/agent/agent.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:
   ```bash
   git clone https://github.com/YOUR_USERNAME/DeepSeek-Reasonix.git
   cd DeepSeek-Reasonix
   ```

2. Checkout the active development branch:
   ```bash
   git checkout main-v2
   ```

3. Build the binary and run the test suite:
   ```bash
   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**:
   ```bash
   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

```bash

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

```go
// 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:

```bash
make test ./internal/tool/builtin/...

```

### Implementing a Custom Provider

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

```go
// 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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml):

```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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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.