Building plugins

The SDK

dev.nuclr:platform-sdk is published to Maven Central and is the whole contract between a plugin and the application: a handful of interfaces, a plugin context, and the model types a panel or a viewer works with.

<dependency>
    <groupId>dev.nuclr</groupId>
    <artifactId>platform-sdk</artifactId>
    <version>5.0.0</version>
    <scope>provided</scope>
</dependency>

The scope matters: the host supplies the SDK at runtime, and a copy bundled inside your plugin would be loaded by a different classloader than the one the application hands you objects from. Keep it provided.

The SDK uses Lombok internally. Since JDK 23 javac no longer runs annotation processors that merely sit on the classpath, so a plugin that uses Lombok has to opt back in - either <proc>full</proc> on the compiler plugin, or Lombok declared in <annotationProcessorPaths>.

SDK 5.0.0 changes

SDK 5.0.0 adds a host-owned credential store for secrets such as API tokens, passwords and access keys. It is deliberately separate from the ordinary settings store: credentials are persisted by the operating system, scoped to the plugin's stable ID, and are never copied into a plaintext settings file.

import java.util.Optional;

import dev.nuclr.platform.NuclrCredentialException;
import dev.nuclr.platform.NuclrCredentialStore;

NuclrCredentialStore credentials = context.getCredentialStore();

try {
	Optional<String> token = credentials.get("access-token");
	credentials.set("access-token", userEnteredToken);
} catch (NuclrCredentialException e) {
	// Show a safe recovery message; never log token or secret values.
}

Credential operations may block or prompt to unlock the OS store, so call get, set and delete off the Swing event-dispatch thread. Keys must be nonblank and contain neither NUL nor |. Keep returned secrets only as long as needed: do not log them, cache them, or use settings as a plaintext fallback. Use the settings store for non-secret preferences.

Migration from 4.0.0

1. Change the Maven dependency to 5.0.0 and set platformSdkVersion to 5.0.0 in plugin.json.
2. Move passwords, tokens and keys out of NuclrSettings and into context.getCredentialStore().
3. Handle NuclrCredentialException without exposing the secret, and provide a useful recovery path when the OS store is unavailable.
4. No changes are required to the three plugin interfaces or their lifecycle unless you want to use credential storage.

The three plugin types

BaseNuclrPlugin is a sealed interface with exactly three permitted subtypes. Implement one of them - never the base directly - and declare the matching type in the manifest. Everything a plugin says about itself lives in that manifest; the interface only describes what it does.

All three share the lifecycle on BaseNuclrPlugin - preinit(context), init(), updateTheme(...), unload() - plus focus callbacks, uuid() for instance identity, and act(...) for the actions the host and other plugins send. The context gives you the event bus, the current theme, a namespaced settings store and the locale.

Threading is the one rule worth repeating: supports(...) can run on a background thread because deciding whether you can open something may touch the filesystem or the network, and openResource(...) must do its work asynchronously, poll the supplied cancel flag, and push every UI change back onto the event-dispatch thread.

The plugin.json manifest

Every bundle carries a plugin.json at its root, and one bundle may ship several plugins. It is the only source of a plugin's identity.

{
  "schemaVersion": 1,
  "version": "1.0.0",
  "platformSdkVersion": "5.0.0",
  "plugins": [
    {
      "class": "com.example.MyQuickViewPlugin",
      "type": "QuickView",
      "id": "com.example.myplugin.quickview",
      "name": "My Quick Viewer",
      "version": "1.0.0",
      "description": "Example quick view plugin.",
      "author": "Your Name",
      "license": "Apache-2.0",
      "developer": "Community",
      "singleton": true,
      "priority": 100
    }
  ]
}

Let Maven fill the version in - declare "version": "${project.version}" and filter only plugin.json. Bundles routinely carry icons and native libraries that must be copied byte-for-byte.

Packaging and signing

A plugin ships as a ZIP whose root holds:

plugin.json          the manifest above
my-plugin.jar        your classes
lib/                 runtime dependencies - never the SDK, which is provided
...                  any assets you need

Commander verifies a bundle's detached signature before it loads anything from it. Plugins installed from this site are signed; a bundle you build yourself is not, so it loads through the route below.

Running your own build

A bundle you built carries no signature the application can check, so three things must hold before it will load:

1. Turn on Developer mode in Settings (Ctrl P, under Advanced). Turning it off again unloads every local plugin immediately and keeps them from loading at the next start.
2. Accept the risk warning once - and again if its wording changes.
3. Approve the bundle itself - open the plugin manager with F11 and use Install from file…. The approval is recorded against the SHA-256 of the exact bytes you saw, so a ZIP that merely appears in the folder is never loaded.

After that it behaves like any other plugin: it can be enabled and disabled, it is still subject to the published blacklist, and the plugin manager marks it unverified throughout. What it may not do is take an id that belongs to a signed plugin.

Building it with an AI agent

What this page teaches a person is also packaged for a coding agent, as an Agent Skill - a folder the agent reads before it writes anything, so that asking for a quick viewer for some format produces a complete, packaged, validated bundle rather than a plausible-looking sketch. It is the open skill format rather than any one vendor's, and it is Apache-2.0, like the SDK.

git clone https://github.com/nuclrdev/skills.git

Copy or symlink skills/nuclr-commander-plugins/ into whichever directory your agent reads skills from; an agent that installs straight from Git can be given the repository URL and that subdirectory instead. From then on it selects the skill by itself when you ask for a plugin, and you can name it explicitly as nuclr-commander-plugins.

Inside the folder:

• SKILL.md - how to establish the contract, choose one of the three types, and what counts as finished.
• A self-contained snapshot of the SDK contract, plus one reference per plugin type: the lifecycle and threading rules, the manifest, and the Maven bundle layout.
• scripts/validate_plugin.py - a standalone checker, no Maven and no Commander install required.

python3 scripts/validate_plugin.py my-plugin --archive target/my-plugin-1.0.0.zip

The validator is worth running whether or not an agent wrote the code: it checks the SDK dependency and its scope, the manifest's schema, required fields and vocabulary, priority and role per type, id and class uniqueness, the flat ZIP layout, that no ${...} placeholder survived into the packaged manifest, that the SDK is not bundled, and that every class the manifest declares is really in the JAR. It needs Python 3.10 or newer, and exits non-zero on any error.

An agent writing the bundle changes nothing about how it loads: it is still unsigned, so it takes the three steps above, and it is still your plugin. Run the tests, install the ZIP, and confirm in the plugin manager that the build you just made is the one that loaded.

Examples on GitHub

Every panel and viewer a fresh install ships with is a plugin built against this same SDK, each published from its own repository.

File panels browser panes

• nuclrdev/plugin-filepanel-fs2 The local filesystem panel - the reference implementation: function-key rows, its own dialogs, copy and move engines, and a terminal for the embedded console.
• nuclrdev/plugin-filepanel-zip Archives as a panel: entries that have no real path on disk, which is the smallest step away from the local filesystem.
• nuclrdev/plugin-filepanel-s3 A remote, credentialed backend: listings arrive a page at a time and every call can fail or hang.
• nuclrdev/plugin-filepanel-docker Something that is not a filesystem at all - containers, images and volumes presented as one.
• nuclrdev/plugin-filepanel-github One bundle shipping a panel and the quick viewers that go with it.

Quick viewers preview panes

• nuclrdev/plugin-quick-viewer-text The plainest complete viewer - start here if you are writing your first plugin.
• nuclrdev/plugin-quick-viewer-image Decoding off the event thread, then painting on it.
• nuclrdev/plugin-quick-viewer-markdown A viewer with real third-party dependencies in lib/.
• nuclrdev/plugin-quick-viewer-pdf Rendering a heavy format page by page, with the cancel flag actually respected.
• nuclrdev/plugin-quick-viewer-archive A viewer that answers for many extensions, and how priority settles who wins.

Fullscreen whole-window tools

• nuclrdev/plugin-screenpanel-text-editor The F4 editor: a plugin with the Editor role and the whole window to itself.
• nuclrdev/plugin-screenpanel-hex-editor One bundle declaring both roles - a hex Editor and a read-only Viewer.

These are the official plugins; the plugin catalogue lists every published one, each with its README, its versions and a link to its source.