Plugins and modding with NodalForge

The idea: where settings stop, plugins start#

Nodal’s philosophy is that you should use the app exactly the way you want to use it. Settings cover the common cases: colors, fonts, layout, which provider to use. But every workflow has odd corners that no settings page will ever anticipate. A plugin system is the answer to the corners. NodalForge is its name, and the plan is that you or an AI coding agent can write a plugin that does almost anything in the app, from a tiny desktop widget to a new window type inside Tab Mode.

This fits the way Nodal is made. A tool built by AI agents is naturally extended by AI agents, so the intended loop is conversational: describe the plugin you want, let an agent build it against a documented API, and try it in a safe test copy of the app before you trust it.

Status, plainly#

The sidebar already has a NodalForge entry, and Settings has a Plugins page, but in the ordinary build the plugin host is switched off. In Plugin Lab and in the developer build it is on, each under its own application identity and profile so a lab never touches the data of your working copy.

How a plugin is isolated#

Real isolation, in Nodal, comes from Electron and Chromium process separation, not from any plugin framework. That is a recorded decision and a deliberate one, because the framework that wires plugins together does not sandbox them.

• Plugins that draw UI run in a sandboxed window with context isolation on, Node integration off and a narrow preload bridge. They can show a sidebar, a Tab Mode window or a free-floating widget.
• Background-only plugins run in a Node-capable utilityProcess, a separate operating-system process, so a crash or hang in a plugin cannot take down the app.
• A versioned handshake comes first. On startup a plugin declares its manifest version and the capabilities it wants. The host validates compatibility and grants only what matched, and denies everything it did not grant.
• Bounded restarts. A crashing or hung plugin is restarted up to three times within 60 seconds, after short delays of 1, 2 and 4 seconds. After that it is disabled automatically, the app shows a safe-mode indicator and you can re-enable it manually.

The lab documentation is candid about a limit. The declared capabilities are protocol checks, not operating-system restrictions: a background plugin in a utility process has Node’s filesystem and process authority. That is acceptable for the trusted, bundled example in the lab, and it is exactly why loading arbitrary downloaded code needs a separate trust and permission design before it is allowed.

Cordis: the wiring engine#

For composing the host’s own modules, Nodal uses Cordis, an MIT-licensed TypeScript framework for service injection, typed event buses and disposable registrations, from the same team behind the Koishi bot ecosystem. It was chosen because it runs natively inside Electron’s Node process with no sidecar, and it makes hot reload and teardown clean, since every registration returns a disposer. Nodal pins a specific release candidate version and treats it as pre-1.0 software.

Two corrections were made before the decision closed and are worth repeating. First, Cordis does not provide a sandbox; plugins in it run fully in-process. Second, using Cordis does not make plugins for other Cordis hosts work in Nodal, because each host defines its own service surface. The Nodal-owned plugin API in the example deliberately contains no Cordis types, so the framework could be replaced later. A roll-your-own, VS Code or Obsidian style plugin API is the staged alternative to compare against once there is real evidence, with a dependency-injection container held in reserve.

The first plugin: SpaceWatcher#

The example plugin is SpaceWatcher, a small disk-space widget that came over from ToolTab v1 (see the v1 page). To try it in Plugin Lab you open NodalForge, enable SpaceWatcher, pick the volumes to watch (none are selected automatically) and open the widget. Clicking the disk summary expands it to show each volume with its last reading time, a Refresh button, a lock-position option and an always-on-top option. The initial low-space threshold is ten percent available.

• It reads available bytes and percentage once a minute and on Refresh. It reports no file contents, scans no directories, deletes nothing and sends no operating-system notifications.
• A missing drive stays listed as unavailable; a failed read keeps the last value and marks it stale.
• The widget follows your theme live through a read-only theme bridge, uses the bundled fonts and respects the reduced-motion setting.
• The widget window is sandboxed with a strict content security policy, a separate non-persistent session and denied permissions. The main process checks the exact window, frame and document of each request before honoring it, and the widget cannot call the terminal, account, clipboard or theme-write handlers.

Measured on the installed lab build, the disabled state ran five Electron processes and the enabled state seven, with the worker using about 100 MiB. Both added processes disappeared after every disable. The measurements show clean teardown; they do not claim a leak-free guarantee over long runs.

What plugins are meant to become#

The longer-term shapes recorded in the plans are modest and concrete:

• A replaceable sidebar and plugin-opened windows in Tab Mode, so a plugin can host a dashboard, a log tail or a custom control panel next to your agents.
• A section in the notification center, the planned third section beside Agent Mode and Tab Mode.
• An Agent Simulator plugin, a synthetic command-line agent you can open in a window to test your own plugin’s reaction to session and notification data without a real provider.
• A host-level sandbox for agent commands, expected to take a plugin-shaped form. The idea of running agents inside a virtual machine or operating-system environment was deliberately deferred until plugin implementation begins, when it can be specified with real requirements. See the roadmap for the personal-VM idea.
• Shared themes, layouts and plugins, and an optional route to submit one for inclusion in the app by default, always at your choice. Nothing is shared or submitted unless you decide.

What is deliberately not done#

There is no public plugin marketplace and no public SDK. Before that can change the plans require a package trust model, origin and navigation restrictions, a defined preload surface, IPC capability grants, permission prompts, an update policy and crash recovery. Third-party Cordis access stays out of the first public proof. Theme marketplaces and shared theme libraries are similarly later scope. The plugin host is also off by default in the ordinary build, which keeps the everyday app small and predictable.

How to follow along#

NodalForge work is done in the open. Plugin Lab results, test counts and caveats are recorded alongside the code, and the owner builds new pieces live; the livestream page on the creator hub tells you when. To see how plugins relate to the rest of the system read the architecture page, and to see the visual half of customization read the theming page.