# How to Contribute to DeepSeek-Reasonix Development: A Complete Guide

> Contribute to DeepSeek-Reasonix development. Fork the repository, code with gofmt, add tests, and submit a PR. Learn how to enhance this powerful reasoning engine now.

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

---

**To contribute to DeepSeek-Reasonix, fork the repository, work on the `main-v2` branch, follow Go coding conventions with `gofmt`, add tests for new behavior, and submit a PR with a `Cache-impact:` declaration.**

DeepSeek-Reasonix is a Go-based AI coding agent that runs as a single static binary and optionally as a Wails-based desktop application. The repository follows a modular architecture where each logical layer lives under its own `internal/*` package. Understanding this structure and the contribution workflow is essential for anyone looking to add features, fix bugs, or extend the toolset.

## Understand the Repository Architecture

The codebase is organized into distinct layers under the `internal/` directory. Each package has a specific responsibility, making it easier to locate where changes should be made.

| 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, merging them with flag overrides. | [`internal/config/config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go) |
| **Tooling** | `internal/tool/builtin` | Implements built-in tools such as `bash`, `read_file`, and `write_file`. | `internal/tool/builtin/*.go` |
| **Provider abstraction** | `internal/provider` | Wraps OpenAI-compatible endpoints (DeepSeek, OpenAI, Azure). | [`internal/provider/openai/provider.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/provider/openai/provider.go) |
| **Plugins (MCP)** | `internal/plugin` | Enables external processes to expose JSON-RPC tools over stdio or HTTP. | [`internal/plugin/mcp.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/plugin/mcp.go) |
| **Memory system** | `internal/memory` | Stores the evolving [`AGENTS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/AGENTS.md) hierarchy and checkpoint snapshots. | [`internal/memory/memory.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/memory/memory.go) |
| **Sandbox** | `internal/sandbox` | Confines file-system writes to the configured workspace root. | [`internal/sandbox/sandbox.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/sandbox/sandbox.go) |
| **Web frontend** | `internal/serve` | Serves the engine over HTTP/SSE for the browser-based UI. | [`internal/serve/server.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/serve/server.go) |
| **Desktop app** | `desktop/` | Wails-based GUI that reuses core engine packages. | [`desktop/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/desktop/main.go) |

## Contribution Workflow

Follow these steps to ensure your contribution aligns with project standards:

1. **Fork and clone** the repository from `https://github.com/esengine/DeepSeek-Reasonix.git`.
2. **Checkout the active branch** `main-v2`, which contains the latest development code.
3. **Run the build** to verify your environment is configured correctly using `make build`.
4. **Make changes** adhering to Go conventions, including `gofmt -w .` formatting and error wrapping with `fmt.Errorf("...: %w", err)`.
5. **Add tests** for any new behavior, placing them alongside the source files (e.g., [`internal/agent/agent_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/agent/agent_test.go)).
6. **Document cache impact** by adding a `Cache-impact:` line in your PR body if you modify prompt construction, memory prefixes, or tool registration (e.g., `Cache-impact: low – added a new builtin tool`).
7. **Submit a PR** targeting `main-v2`, ensuring the CI pipeline passes formatting, linting, and test validation.

The authoritative source for contribution guidelines is the [`CONTRIBUTING.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/CONTRIBUTING.md) file at the repository root.

## Development Setup and Build Process

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

```bash

# Clone the repository

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

# Build the CLI binary to ./bin/reasonix

make build

# Run the full test suite

make test

# Run the setup wizard to create reasonix.toml

./bin/reasonix setup

# Execute a task to verify functionality

./bin/reasonix run "implement the TODOs in internal/agent/session.go"

```

The `Makefile` provides standard targets for common tasks. Always run `make test` before committing to ensure your changes do not break existing functionality.

## Adding New Features

### Implement a Custom Built-in Tool

Tools must implement the `tool.Tool` interface and register themselves in an `init` function. Create a new file in `internal/tool/builtin/`:

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

import (
    "context"
    "encoding/json"
    "fmt"
    "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
}

// Register the tool at init time
func init() { tool.RegisterBuiltin(greetTool{}) }

```

After adding the file, run `make test ./internal/tool/builtin/...` to confirm the tool compiles and is automatically discovered.

### Implement a Custom Provider

To add support for a new LLM backend, implement the `provider.Provider` interface in `internal/provider/`:

```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 specific to target LLM API
    out := make(chan provider.Response)
    // ... stream logic ...
    return out, nil
}

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

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

```

Update your [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) configuration to use the new provider:

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

```

## Code Standards and Testing Requirements

Adhering to Go conventions is mandatory for all contributions. The codebase strictly enforces the following rules:

- **Formatting**: Run `gofmt -w .` on all changed files before committing.
- **Error handling**: Wrap errors using `fmt.Errorf("...: %w", err)` to maintain error chain context.
- **Library code constraints**: Never call `os.Exit` or write directly to stdout/stderr from library code. Only the CLI layer in `cmd/reasonix/` may handle program termination.
- **Testing**: All new behavior requires corresponding tests. Reference existing test files like `internal/agent/*_test.go` for patterns.
- **Cache-impact documentation**: Any changes affecting prompt construction, memory prefixes, or tool registration must include a `Cache-impact:` metadata line in the PR description.

## Summary

- **DeepSeek-Reasonix** is organized under `internal/*` packages with clear separation between CLI, agent logic, tools, providers, and memory systems.
- **Development workflow** requires forking, working on `main-v2`, running `make build` and `make test`, and submitting PRs with cache-impact metadata.
- **New tools** are added by implementing the `tool.Tool` interface in `internal/tool/builtin/` and registering in `init()`.
- **New providers** require implementing the `provider.Provider` interface in `internal/provider/`.
- **Code standards** mandate `gofmt`, error wrapping with `%w`, no `os.Exit` in libraries, and comprehensive testing.
- **Authoritative guidelines** are maintained in [`CONTRIBUTING.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/CONTRIBUTING.md) at the repository root.

## Frequently Asked Questions

### What branch should I target for pull requests?

Always target the `main-v2` branch. This is the active development branch containing the latest features and fixes. The CI pipeline automatically validates formatting, linting, and test passing when you submit a PR against this branch.

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

Create a new 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()`. The agent automatically discovers registered tools at startup.

### What is the cache-impact gate and when do I need to use it?

The cache-impact gate is a documentation requirement for PRs that modify prompt construction, memory prefixes, or tool registration logic. You must add a `Cache-impact:` line to your PR body (e.g., `Cache-impact: low – added validation logic`) to help reviewers understand the performance implications of your changes on the caching system.

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

Yes, the desktop application lives in the `desktop/` directory as a separate Go module but shares the same internal packages. Changes to the core engine in `internal/` affect both the CLI and desktop app, while UI-specific changes belong in the `desktop/` directory. Build the desktop app using the Wails framework after making changes.