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

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
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, merging them with flag overrides.	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
Plugins (MCP)	internal/plugin	Enables external processes to expose JSON-RPC tools over stdio or HTTP.	internal/plugin/mcp.go
Memory system	internal/memory	Stores the evolving AGENTS.md hierarchy and checkpoint snapshots.	internal/memory/memory.go
Sandbox	internal/sandbox	Confines file-system writes to the configured workspace root.	internal/sandbox/sandbox.go
Web frontend	internal/serve	Serves the engine over HTTP/SSE for the browser-based UI.	internal/serve/server.go
Desktop app	desktop/	Wails-based GUI that reuses core engine packages.	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).
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 file at the repository root.

Development Setup and Build Process

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

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

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

// 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 configuration to use the new provider:

[[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 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.

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