How to Contribute to DeepSeek-Reasonix: A Complete Guide for Developers

Fork the repository on GitHub, clone it locally, install Go 1.22 or higher, run make build to compile the binary, execute make test to validate your changes, and submit a pull request against the main-v2 branch following the project's coding standards.

DeepSeek-Reasonix is an open-source, single-binary Go agent that operates across terminal, desktop, browser, and VS Code ACP environments. Learning how to contribute to DeepSeek-Reasonix requires familiarity with its modular architecture, Makefile-driven build system, and extension protocol. This guide provides the exact file paths, commands, and code patterns you need to submit successful pull requests.

Setting Up Your Development Environment

Before writing code, configure your local environment to match the repository's requirements.

Fork and Clone the Repository

Start by creating your own copy of the codebase. Click Fork on the GitHub repository page, then clone your fork locally:

git clone https://github.com/<your-username>/DeepSeek-Reasonix.git
cd DeepSeek-Reasonix

Install Prerequisites

DeepSeek-Reasonix requires Go 1.22 or higher to build the static binary. Optionally, install Node.js if you plan to modify the UI components. Verify your Go installation:

go version

Building and Testing Your Changes

The project uses a Makefile to standardize build and test commands across platforms.

Compile the Binary with Make

Build the native binary for your current platform using the build target defined in the Makefile:

make build

This produces bin/reasonix (or bin/reasonix.exe on Windows). To cross-compile for all supported platforms (Darwin, Linux, and Windows for both AMD64 and ARM64), run:

make cross

The cross-compiled binaries output to the dist/ directory.

Run the Test Suite

Validate your changes by executing the full test suite:

make test

This command runs go test ./... across the SDK and internal packages. For targeted testing of specific components, specify the package path:

go test ./sdk/go/...
go test ./internal/worktree/...

Understanding the Architecture

Contributing effectively requires understanding how DeepSeek-Reasonix components interact.

Core Engine and Worktree Management

The Core Engine is a single static Go binary built from cmd/reasonix/main.go. It handles filesystem operations through the worktree package located in internal/worktree/worktree.go, which manages sandboxing and versioned checkpoints. When modifying filesystem interactions or sandbox logic, focus your changes on this file.

Go SDK and Extension Protocol

The Go SDK in sdk/go/sdk.go provides a programmatic API for extensions, with autogenerated types defined in sdk/go/types_generated.go. Extensions communicate with the engine through the protocol specified in docs/EXTENSION_PROTOCOL.md. The engine reads configuration from a TOML file (reasonix.toml) at startup, maintaining model-agnostic behavior.

Making Code Contributions

Follow these patterns when implementing new features or fixes.

Adding Features to the SDK

When extending the Go SDK, add methods to sdk/go/sdk.go. For example, to implement a new feature that calls a Reasonix extension:

// In sdk/go/sdk.go
// NewFeature calls the Reasonix extension "my_feature" and returns its result.
func (c *Client) NewFeature(ctx context.Context, input string) (string, error) {
    var resp struct{ Result string }
    if err := c.Call(ctx, "my_feature", map[string]any{"input": input}, &resp); err != nil {
        return "", err
    }
    return resp.Result, nil
}

After adding code, format and lint your changes:

go fmt ./sdk/go
go vet ./...
make test

Updating Documentation

Documentation resides in the docs/ directory. When adding CLI flags or capabilities, update the relevant markdown files such as docs/CLI.md. The README contains high-level installation instructions, while REASONIX.md covers central design concepts. All documentation changes must pass CI linting, though they are not compiled into the binary.

Submitting Your Pull Request

Before opening a PR, review the complete contribution policy in CONTRIBUTING.md, which covers code style requirements and the Contributor License Agreement (CLA) process.

Push your branch to your fork and open a pull request against the main-v2 branch. Ensure your submission includes:

• Code formatted with go fmt and vetted with go vet
• Passing tests from make test
• Updated documentation in docs/ if introducing new features or flags
• Descriptive commit messages explaining the rationale for changes

CI runs automatically on your pull request. Respond promptly to reviewer feedback and squash commits when requested.

Summary

• Fork the repository and clone it locally to begin your contribution to DeepSeek-Reasonix.
• Install Go 1.22+ and run make build to compile the binary, or make cross for multi-platform builds.
• Execute make test to verify all tests pass before submitting changes.
• Modify core logic in internal/worktree/worktree.go and SDK features in sdk/go/sdk.go.
• Target the main-v2 branch for all pull requests and follow the guidelines in CONTRIBUTING.md.

Frequently Asked Questions

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

Submit all pull requests against the main-v2 branch. This is the primary development branch where active features are integrated and tested before release.

Do I need Node.js to build DeepSeek-Reasonix?

Node.js is optional and only required if you plan to modify the UI components. The core engine is built entirely with Go 1.22+, and the standard contribution workflow uses only make build and make test.

How do I add a new method to the Go SDK?

Add your method to sdk/go/sdk.go using the existing Client struct. Use the Call method to invoke Reasonix extensions, define appropriate request and response structs, and run go fmt ./sdk/go followed by make test to validate your implementation.

Where is the contribution policy documented?

The complete contribution policy, including coding standards, CLA requirements, and review processes, is documented in CONTRIBUTING.md at the repository root. Refer to this file before submitting your first pull request.

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