# How to Develop Extensions Using the Reasonix Go SDK: A Complete Guide

> Learn to develop Reasonix extensions with the Go SDK. This guide covers JSON-RPC transport, handshakes, and lifecycle management for side-car processes.

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

---

**Reasonix extensions are side-car processes that communicate with the host via Extension Protocol v2 over standard I/O, and the Go SDK provides a zero-dependency library for handling JSON-RPC transport, handshakes, and lifecycle management.**

The esengine/DeepSeek-Reasonix repository includes a Go SDK located in `sdk/go` that enables developers to build side-car extensions for the Reasonix platform. To develop extensions using the Reasonix Go SDK, you implement a binary that communicates via the Extension Protocol v2, package it with a manifest file, and install it into the host runtime where it runs until the host signals shutdown.

## Understanding the Extension Architecture

Reasonix extensions operate as separate processes that interface with the host application through standard input and output streams. This architecture ensures isolation while enabling deep integration through structured message passing.

The core components include:

- **Extension SDK** – The `extension` package in `sdk/go` exposes the `Serve` function, `Initialize` callbacks, and interfaces including `InterceptorFunc`, `Observer`, `Provider`, and `UI` that your side-car implements.
- **Wire Types** – Located in [`sdk/go/types_generated.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/sdk/go/types_generated.go) and [`sdk/go/types_ext.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/sdk/go/types_ext.go), these files contain auto-generated DTOs that mirror the protocol schema at [`internal/extension/protocol/schema.generated.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/extension/protocol/schema.generated.json). Do not edit the generated file directly.
- **Manifest** – The [`reasonix-plugin.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix-plugin.json) file declares your plugin's API version as `reasonix.io/plugin/v2`, lists contributed capabilities, and specifies the runtime binary path.
- **Side-car Binary** – A standard Go executable built from your source code that the Reasonix host launches, manages, and shuts down upon request.

## Development Prerequisites

Before building an extension, ensure your environment meets the following requirements. You need Go version 1.23 or later installed on your system. The SDK itself has zero external dependencies, keeping your side-car binaries lightweight and portable.

## Building Your First Extension

Creating a Reasonix extension involves four distinct steps: defining the manifest, implementing the side-car logic, compiling the binary, and installing it into the host.

### Step 1 – Create the Extension Manifest

Every extension requires a [`reasonix-plugin.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix-plugin.json) file in the package root. This file declares the protocol version and runtime configuration.

```json
{
  "apiVersion": "reasonix.io/plugin/v2",
  "name": "my-extension",
  "version": "0.1.0",
  "contributes": {
    "interceptors": ["tool.before"]
  },
  "runtime": {
    "command": "./bin/my-extension"
  }
}

```

### Step 2 – Implement the Side-car Entry Point

Your Go source must implement the `Initialize` function and register callbacks through `extension.Options`. The SDK handles all protocol handshakes automatically.

```go
package main

import (
	"context"
	"encoding/json"
	"os"

	extension "github.com/esengine/DeepSeek-Reasonix/sdk/go"
)

type ext struct{}

// Initialize is called once at startup to register capabilities.
func (ext) Initialize(_ context.Context, p extension.InitializeParams) (*extension.InitializeResult, error) {
	return &extension.InitializeResult{
		Name:          "my-ext",
		Version:       "0.1.0",
		Subscriptions: []string{"tool.before"},
	}, nil
}

func main() {
	err := extension.Serve(context.Background(), ext{}, extension.Options{
		Interceptors: map[string]extension.InterceptorFunc{
			"tool.before": func(_ context.Context, event string, payload json.RawMessage) (*extension.InterceptResult, error) {
				// Allow the tool call to continue unchanged.
				return extension.Continue(), nil
			},
		},
	})
	if err != nil {
		os.Exit(1)
	}
	// Serve returns nil when the host asks for shutdown.
}

```

Key implementation details:

- The `Initialize` method returns your extension's name, version, and a list of hook points you wish to subscribe to.
- The `Interceptors` map binds hook names like `tool.before` to functions that can return `Continue()`, `Block()`, `Replace()`, or `Allow()`.
- The `extension.Serve` function blocks until the host signals shutdown, handling all JSON-RPC serialization internally.

### Step 3 – Build the Binary

Compile your extension using standard Go build commands. The output must match the path specified in your manifest's `runtime.command` field.

```bash
go build -o ./bin/my-extension ./my-extension

```

### Step 4 – Install and Activate

Install the extension package into Reasonix using the CLI, then reload the runtime to activate the new side-car atomically.

```bash
reasonix plugin install /path/to/package --link --yes
/reload

```

Alternatively, use the Desktop application's "Reload Runtime" command after installation.

## Handling Protocol Communication and Concurrency

The SDK guarantees transport correctness by serializing all JSON-RPC writes to `stdout`. Your extension code must never write directly to standard output, as this would corrupt the protocol stream.

Within a single extension instance, up to 32 inbound callbacks may execute concurrently. If your extension maintains shared mutable state, you must protect it using mutexes, atomic operations, or channels. The protocol maintains stability within major version 2, permitting only additive changes that preserve backward compatibility with any host using the same protocol version.

## Advanced Patterns and Reference Implementation

For production extensions requiring complex functionality such as input rewriting, tool argument modification, system-prompt replacement, or custom UI components, consult the reference implementation at [`sdk/go/examples/fullsidecar/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/sdk/go/examples/fullsidecar/main.go). This example demonstrates:

- Input rewriting triggered by specific prefixes like `/fs `
- Tool interception with argument rewriting and blocking capabilities
- A fake streaming provider that emits text chunks, tool calls, and usage data
- Structured UI elements including status indicators, cards, and forms with `demo` actions

To build and test the reference side-car locally:

```bash
mkdir -p /tmp/full-sidecar/bin
cp ./sdk/go/examples/fullsidecar/reasonix-plugin.json /tmp/full-sidecar/
go build -o /tmp/full-sidecar/bin/full-sidecar ./sdk/go/examples/fullsidecar
reasonix plugin install /tmp/full-sidecar --link --yes

```

## Summary

- **Reasonix extensions** are side-car processes using Extension Protocol v2 (`reasonix.extension.v2`) over standard I/O streams.
- The **Go SDK** in `sdk/go` provides zero-dependency JSON-RPC handling through the `extension` package with functions like `Serve` and `Initialize`.
- Extensions require a **[`reasonix-plugin.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix-plugin.json)** manifest declaring API version `reasonix.io/plugin/v2` and runtime details.
- Build with **Go 1.23+** using standard `go build` commands, then install via `reasonix plugin install`.
- The SDK supports **up to 32 concurrent callbacks**; extensions must use proper synchronization for any shared state.

## Frequently Asked Questions

### What is Extension Protocol v2?

Extension Protocol v2 is the JSON-RPC-based communication standard that defines how Reasonix hosts and side-car extensions interact. It specifies the handshake sequence, message framing, content reference resolution, and orderly shutdown procedures. The protocol schema is defined in [`internal/extension/protocol/schema.generated.json`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/extension/protocol/schema.generated.json) and implemented by the Go SDK in `sdk/go`.

### How do I handle concurrent requests in a Reasonix extension?

The Go SDK allows up to 32 inbound callbacks to execute simultaneously for performance. If your extension maintains shared state across these callbacks, you must protect that state using `sync.Mutex`, atomic operations from the `sync/atomic` package, or Go channels. Never assume sequential execution of interceptor or observer functions.

### Where can I find the complete reference implementation?

The repository includes a comprehensive reference side-car at [`sdk/go/examples/fullsidecar/main.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/sdk/go/examples/fullsidecar/main.go) that demonstrates advanced patterns including input rewriting, tool interception with argument replacement, streaming provider implementations, and structured UI components. Additional documentation is available in [`sdk/go/README.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/sdk/go/README.md) and the starter extension guide at [`sdk/go/examples/starterextension/README.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/sdk/go/examples/starterextension/README.md).

### What Go version is required to build Reasonix extensions?

Go version 1.23 or later is required to compile extension binaries using the Reasonix Go SDK. The SDK itself has no external dependencies beyond the Go standard library, ensuring minimal binary sizes and broad compatibility across platforms.