Build a plugin

sysc-shell launches each plugin as a separate process and exchanges versioned JSON Lines over standard input and output. In sysc-plugins, each plugin has a manifest and implementation under plugins/, plus a command under cmd/.

Use an example plugin

Use Cat as a small example. It declares org.sysc.cat, a bar widget and a panel in manifest.json. Its command at cmd/sysc-plugin-cat uses the SDK client, answers the handshake, and serves views.

For a new plugin in sysc-plugins, add these pieces:

plugins/<dir>/manifest.json
plugins/<dir>/*.go
cmd/sysc-plugin-<dir>/main.go

Use the same suffix for the plugin directory and command: plugins/<dir>/ pairs with cmd/sysc-plugin-<dir>/main.go, and the manifest must set exec to bin/sysc-plugin-<dir>. The packager derives the command path from <dir> and rejects a different exec; the release validator checks the same path in tagged archives.

Keep the directory name stable because the release workflow uses it in the tag. Give the manifest a reverse-domain ID and keep the name, description and version aligned with the published catalog entry.

Connect the process

Create a plugin/v1.Client with stdin and stdout. Call Handshake before sending any other message. Pass the identity from your manifest. Write diagnostics to stderr; stdout carries protocol messages only.

c := v1.NewClient(os.Stdin, os.Stdout)
if _, err := c.Handshake(v1.Identity{
    ID: "org.example.clock", Name: "Clock", Version: "0.1.0",
}); err != nil {
    fmt.Fprintln(os.Stderr, err)
    return err
}

Then handle host messages such as view.open, input.event, settings.changed, view.resync and host.shutdown. The host assigns each view_id and gives each opened view its available dimensions. Send a snapshot for the current revision, or a patch against the revision the host has already accepted. See Protocol for handshake and error behavior.

Declare plugin needs

Add host capabilities to the manifest only when a feature needs them. List external commands under requires.commands. Give each interactive node an ID, accessible name, role and supported events. Check every view with v1.Validate and the host layout linter before asking for review.

Keep user data and credentials out of fixtures, logs and screenshots. A plugin process runs as the same user as sysc-shell, so host capabilities do not restrict ordinary operating-system access. Read the manifest, UI rules and testing steps before release.

The sysc-plugins authoring guide and the sysc-shell SDK source define the interfaces for this revision.