Plugins

Overview

Plugins extend server-side agent behavior and TUI behavior. Server plugin loading is in packages/nikcli/src/plugin/index.ts. Plugin installation and config patching are in packages/nikcli/src/plugin/installer.ts. TUI plugin runtime lives under packages/tui/src/plugin.

Install a plugin

nikcli plugin @scope/my-plugin
nikcli plugin @scope/my-plugin --global
nikcli plugin @scope/my-plugin@1.2.3 --force

The install task performs four steps:

1. Resolve and install the package target.
2. Read plugin metadata from package.json.
3. Detect server and/or TUI targets from manifest or exports.
4. Patch nikcli.json and/or tui.json in the selected scope.

Config patching

patchPluginConfig uses jsonc-parser edits instead of string hacks. It can patch server config plugin and TUI config depending on detected targets. Duplicate detection compares package names, not only the full versioned spec.

{
  "plugin": [
    "@scope/my-plugin"
  ]
}

Server runtime

Server plugin loading starts with internal plugins that are imported directly. Then configured plugins plus external built-ins are loaded. If a plugin path is not file://, nikcli installs the package before importing it.

1. Build plugin input, including SDK client and runtime helpers.
2. Load internal auth/notification plugins.
3. Copy configured plugin specifiers from config.
4. Add external built-ins unless NIKCLI_DISABLE_DEFAULT_PLUGINS is set.
5. Ignore old Codex/Copilot auth plugin specs that are now first-party.
6. Install and import package specifiers.
7. Load v1 server export when present, otherwise invoke exported plugin functions.
8. Deduplicate duplicate function references from named and default exports.

TUI runtime

TUI plugin APIs are built in packages/tui/src/plugin/api.tsx and loaded by plugin/runtime.ts. Plugins can add routes, commands, dialogs, keybinds, and UI surfaces while the TUI app is running.

A plugin that throws while rendering is contained: the slot or route renders nothing and the crash surfaces as a single error toast instead of taking the TUI down.

TUI plugin discovery and hot reload

Local TUI plugins are discovered from plugin/tui/ and plugins/tui/ inside every config root — the project .nikcli directories, the global config dir, NIKCLI_CONFIG_DIR, and the managed dir. Anything else is declared in tui.json. The extra tui level matters: {plugin,plugins}/*.{ts,js} is the server plugin loader's territory, so a TUI plugin placed directly there is loaded as a server plugin and fails.

.nikcli/
  tui.json            # optional: declare plugins with options
  plugin/tui/hud.tsx  # discovered automatically

Editing a local plugin swaps that one plugin in the running TUI, typically within ~100 ms. Other plugins — including built-ins — are never touched, in-memory state kept in api.storage.memory survives, and a broken save keeps the last working version alive with one error toast until the file is fixed. npm package plugins do not hot reload: their entrypoints resolve into the package cache and are immutable for the session.

Built-in plugins

Internal built-ins are directly imported and do not depend on package installation. They include Codex auth, GitHub Copilot auth, xAI auth, Cursor auth, Cloudflare Workers/Gateway auth, and the notification plugin. External built-ins are appended from the built-in list unless disabled.

NIKCLI_DISABLE_DEFAULT_PLUGINS=1 nikcli

Internal TUI feature plugins

Beyond the auth and notification plugins, the TUI ships a set of internal feature plugins that ship inside packages/tui/src/feature-plugins/. They run in-process and don't need to be installed:

Each one — its commands, slash aliases, KV keys and internals — is documented in TUI feature plugins, which doubles as the reference for the plugin API since the internal plugins use exactly the API an npm plugin gets.

Plugin manifest

The installer reads package metadata with readPluginPackage. Target detection accepts explicit plugin target metadata and also detects packages that expose ./server and/or ./tui exports. A package with only main or string exports is treated as a server plugin.

{
  "name": "@scope/my-plugin",
  "version": "1.0.0",
  "exports": {
    "./server": "./dist/server.js",
    "./tui": "./dist/tui.js"
  },
  "oc-plugin": ["server", "tui"]
}

Skills

Skills are related but not the same as plugins. Skills are prompt/context assets discovered by skill/skill.ts. The skill glob scans skill/**/SKILL.md and skills/**/SKILL.md under config directories, plus external sources unless disabled.

Notifications

Notifications are implemented as an internal plugin created by createNotifyPlugin. It reads notifications.notify and notifications.todo, applies rate limits, retry/backoff, circuit breaker behavior, quiet hours, and connector-backed Slack or Discord delivery.

{
  "notifications": {
    "notify": {
      "enabled": true,
      "events": {
        "sessionIdle": true,
        "sessionError": true,
        "permissionAsked": true,
        "questionAsked": true
      },
      "slack": { "enabled": true, "connector": "slack", "channel": "#builds" }
    }
  }
}

Failure modes

Source anchors