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

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 and sdk/go/types_ext.go, these files contain auto-generated DTOs that mirror the protocol schema at internal/extension/protocol/schema.generated.json. Do not edit the generated file directly.
• Manifest – The 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 file in the package root. This file declares the protocol version and runtime configuration.

{
  "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.

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.

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.

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

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 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 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 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 and the starter extension guide at 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.

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