Advanced

Custom Modules

Shiro supports three ways to extend it with custom modules: compiled-in Go modules, subprocess binaries, and HTTP microservices.

Module Types

builtin

Compiled-in

Go modules compiled directly into the shiro binary via shiro add module + shiro build. Best performance.

subprocess

Subprocess Binary

External binary on PATH (shiro-<name>) or in .shiro/plugins/. Communicates via stdin/stdout JSON.

http

HTTP Microservice

Any HTTP server that implements the Shiro module API. Language-agnostic — Python, Node, Rust, etc.

Compiled-in Go Module

Use shiro add module to register a Go module from GitHub, then shiro build to recompile the binary.

bash

# Register the module (adds to .shiro/modules/registry.yaml)
shiro add module github.com/your-org/your-shiro-module

# Rebuild shiro with the new module compiled in
shiro build

shiro build auto-generates the registry import in internal/cli/registry.go, runs go mod tidy, and recompiles.

Registry entry format

.shiro/modules/registry.yaml

modules:
  your-module:
    name: your-module
    type: builtin
    package: github.com/your-org/your-shiro-module
    factory: NewYourModule
    version: "1.0.0"
    description: "Description of your module"
    source: https://github.com/your-org/your-shiro-module

Subprocess Binary Module

Drop any executable named shiro-<name> into .shiro/plugins/ or anywhere on PATH. Shiro discovers and registers it automatically at startup.

bash

# Place binary in plugins dir
cp ./shiro-mymodule .shiro/plugins/
chmod +x .shiro/plugins/shiro-mymodule

# Or install to PATH
sudo cp ./shiro-mymodule /usr/local/bin/
chmod +x /usr/local/bin/shiro-mymodule

The binary communicates via stdin/stdout JSON:

json

// Shiro sends to stdin:
{
  "action": "your_operation",
  "config": { "key": "value" },
  "context": { "steps": { ... } }
}

// Binary responds on stdout:
{
  "output": { "result": "...", "success": true },
  "error": ""
}

For metadata, respond to "action": "__metadata__":

json

// Shiro sends: {"action": "__metadata__"}
// Binary responds:
{
  "name": "mymodule",
  "description": "Does something useful",
  "input_schema": {
    "key": { "type": "string", "description": "...", "required": true }
  },
  "output_schema": {
    "result": { "type": "string", "description": "..." }
  }
}

HTTP Microservice Module

.shiro/modules/registry.yaml

modules:
  my-http-module:
    name: my-http-module
    type: http
    endpoint: http://localhost:8080
    description: "My HTTP module"

The service must implement two endpoints — see the API Contract for the full spec.

Using Custom Modules in Workflows

Once registered, custom modules are referenced by name in type just like built-in modules.

json

{
  "id": "my_step",
  "type": "your-module",
  "config": {
    "key": "value"
  }
}

📖

Want to build a module from scratch?

See the Module Development guide for a step-by-step walkthrough, and the API Contract for the exact Go interface.