TUI feature plugins

Overview

Almost nothing the nikcli TUI shows is hard-coded in app.tsx. The home tips, the sidebar panels, the plugin manager, the wallpaper, the loop and mission managers, the connector and chat-bot dashboards — each one is a self-contained feature plugin under packages/tui/src/feature-plugins/, loaded through the exact same runtime that loads third-party plugins from npm.

That is the point: the internal plugins are the reference implementations of the public plugin API. If you want to know how to register a command, own a dialog, paint into a sidebar slot, or persist per-machine state, one of the directories on this page already does it.

Anatomy of a plugin

A command-owning plugin is a module with an id and an async tui(api) setup function. Everything it registers is scoped to the plugin's lifetime — the runtime unregisters on deactivate and on TUI shutdown.

import type { TuiPlugin, TuiPluginModule } from "@nikcli-ai/plugin/tui"
import { DialogBrowserUse } from "@tui/component/dialog-browser-use"

const id = "internal:browser"

const tui: TuiPlugin = async (api) => {
  api.keymap.registerLayer({
    commands: [
      {
        name: "browser.sessions",
        title: "Browser",
        namespace: "Tool",
        description: "Inspect and manage active background browser sessions",
        slashName: "browser",
        run() {
          api.ui.dialog.replace(() => <DialogBrowserUse />)
        },
      },
    ],
  })
}

const plugin: TuiPluginModule & { id: string } = { id, tui }
export default plugin

A pure-UI plugin has no commands at all — it only fills a slot, and uses the terser v2 Plugin.define form:

import { Plugin } from "@nikcli-ai/plugin/v2/tui"

export default Plugin.define({
  id: "internal:sidebar-lsp",
  setup(ctx) {
    ctx.ui.slot("sidebar.content", () => <View />)
  },
})

The registry

plugin/internal.ts is the whole registry. Order matters only for slot ordering ties; the plugin manager sorts its own list.

export const INTERNAL_TUI_PLUGINS: InternalTuiPlugin[] = [
  HomeTips,
  SidebarContext, SidebarMcp, SidebarLsp, SidebarTodo, SidebarFiles, SidebarFooter,
  PluginManager, Fusion,
  Missions, Loops, Brain, Browser, Chatbot, Computer, Connectors, Observability,
  Background,
  ...(Flag.NIKCLI_ISLAND ? [Island] : []),
]

Only island is conditional: it is registered exclusively when the CLI was started with --island, so the macOS notch bridge never loads on a run that did not ask for it.

Shell — home & sidebar

These plugins have no commands. They exist purely to fill slots, and they are the shortest possible examples of the v2 API.

home

home/tips.tsx fills the home.bottom slot with one randomly chosen tip from a ~100-entry list in home/tips-view.tsx. The tip is shown only once at least one session exists, so a brand-new install is not greeted with advice about features it has not reached yet.

It also registers a single palette command, tips.toggle (keybind tips_toggle), which flips the tips_hidden KV flag. Tips support a {highlight}…{/highlight} markup that renders the wrapped span in the foreground color — that is how keybinds and slash commands stand out inside a tip.

sidebar

Six independent plugins, each one panel. They are separate on purpose: a user (or a third-party plugin) can turn off just the MCP panel without losing the Todo panel. All six read from useSync(), so they never issue their own fetches.

System

system/plugins — the plugin manager

The dialog that lists every plugin, internal and external, and the only way to install one from inside the TUI. Reached from the command palette (Plugins) or the plugin_manager keybind.

Rows are grouped into External, Server and Internal, with externals first. Server-target plugins and the manager itself are disabled rows — you cannot toggle a server plugin from the TUI, and you cannot switch off the thing you are switching things off with.

Install is two-phase: plugins.install(mod) writes the package, then plugins.add(mod) loads it into the running session. A package with no TUI target installs successfully and says so rather than pretending to load; a package that installs but fails to load tells you to restart rather than leaving a broken row.

The dialog widens with the terminal — medium below 96 columns, large at 96, xlarge at 128 — because the description column holds a full filesystem path for external plugins.

system/fusion — OpenRouter Fusion presets

OpenRouter's Fusion presets are surfaced as model variants on openrouter/fusion. This plugin is their manager: built-ins ship in provider/transform.ts, customs live in global config under provider.openrouter.models["openrouter/fusion"].variants.

Writes are optimistic: the row flips immediately from an in-session override map because the synced config state can lag a tick behind the update call.

Appearance

background — a real image behind the TUI

The largest internal plugin, and the one that most clearly shows how far a plugin can go. It paints an actual decoded image behind every route using truecolor half-blocks, so you get a terminal wallpaper whether or not your terminal supports one.

The command layer is registered as a function, not an array, so the titles re-evaluate: the toggle row reads “Hide background image” or “Show background image” depending on the current setting.

Settings

Everything lives under the single KV key background_image — not in nikcli.json, because the wallpaper is a personal, per-machine choice and a config round-trip would be noise in a shared repo. A bare string is accepted and normalized into the full object, and sources are cleaned of the quoting and backslash-escaping a terminal adds when you drag a file onto the prompt, with ~ expanded.

How it renders

1. Resolve. source.ts turns the setting into one concrete location; a directory resolves to one of its images by index, which is all “shuffle” has to bump.
2. Decode. Bytes are read (25 MB cap for remote and local files), decoded via @nikcli-ai/tui-image, and cached per location so a route change or a terminal resize never re-decodes a photo.
3. Compose. pixels.ts crops to the terminal aspect, resamples at 2× per axis, optionally desaturates, and blends over the theme background at the configured opacity — pure and synchronous, so it is unit-testable without a renderer.
4. Paint. <nikcli_background> hands the RGBA buffer to OpenTUI's native Zig super-sampler, which writes ▀ cells with per-cell foreground/background in one call.

# Trace the render path to a file while debugging
      NIKCLI_BG_DEBUG=/tmp/bg.log nikcli

Orchestration

loops

Define an objective and a trigger once; nikcli drives the Goal system toward it on a schedule or on demand. See Loops for the engine itself — the plugin is the TUI half.

The plugin also fills sidebar_content at order 250 with a live list and a “N running” badge. Definitions and history are persisted server-side so loops keep running with the TUI closed; on activation the plugin syncs the server's view into a local KV cache (loops, loops:history) and subscribes to the engine's bus events. The local cache is only there to keep the sidebar snappy when the server is unreachable — the server stays the source of truth.

mission

Same shape as loops, one level up: multi-milestone autonomous missions with feature-level progress. See Missions.

Its sidebar slot registers at order 240, deliberately ahead of Loops (250), so Missions wins the bottom of the sidebar. KV cache keys: missions, missions:history.

brain

Wires the Brain consolidation engine into the TUI. On activation it arms the background scheduler that periodically consolidates sessions into long-term memory; /brain (command brain.run) forces a pass right now.

The run is fire-and-forget: the dialog closes, a toast says it started, and when the pass finishes another toast reports how many sessions were reviewed — then the TUI navigates to the resulting Brain session. Both the scheduler and the engine are imported lazily, because eagerly pulling the brain/provider chain during TUI module load would cost startup time on every run that never touches Brain.

Engines & integrations

browser

/browser (command browser.sessions, namespace Tool) opens the browser-use control dialog: active background browser sessions, navigation and the action log for the browser tool. The engine is documented in Browser control.

computer

/computer · /computer-use (command computer.capabilities) probes the host through @nikcli-ai/computer-use and reports exactly what the computer tool can do on this machine — platform, screenshot availability, input availability, and a detail line naming the helpers in use (on macOS, screencapture + System Events + cliclick) or the ones that are missing. A failed probe surfaces as an error toast, not a broken dialog. See Computer use.

connectors

/connectors · /connector (command connectors.manage) lists every configured connector with a live health badge, resolved by running the real health check — not by reading config.

Selecting a connector offers Refresh status (invalidate the cached status and re-run the check) and Remove credentials (drop the stored token, then invalidate). A top-level Refresh all invalidates every cached status and the tool list. With nothing configured, the dialog says so and tells you to add one under connectors in nikcli.json or run nikcli connector add. Full reference: Connectors.

chatbot

/bots · /chatbot (command chatbot.manage) manages the Chat SDK bots — Discord, Slack, Teams, Google Chat, Linear, GitHub. The list is the intersection of configured connectors whose type is a chat platform and the set of bots currently running, marked ● running / ○ stopped.

With nothing configured, the dialog points at nikcli bot add.

observability

Two commands over the OpenTelemetry pipeline. See Observability.

island

Loaded only when the CLI was started with --island. Activating it turns the macOS notch bridge on for this session; deactivating it from the plugin manager clears this session's snapshot and stops writing, and the toggle persists like any other plugin's enabled state.

/island (command island.status) reports whether the bridge is enabled, whether the companion app is running, and how many live sessions it is tracking — or says plainly that Island is macOS-only on other platforms. Full documentation: Island.

Command index

Every command the built-in plugins register, and how to reach it.

Writing your own

An external plugin uses the same API. Install it with shift+i in the plugin manager, or add it to config; see Plugins & Skills for packaging and the server-side plugin target.

import type { TuiPlugin, TuiPluginModule } from "@nikcli-ai/plugin/tui"

const tui: TuiPlugin = async (api) => {
  // A command with a slash alias and a reactive title.
  api.keymap.registerLayer({
    commands: () => [
      {
        name: "notes.open",
        title: api.kv.get("notes.pinned", false) ? "Notes (pinned)" : "Notes",
        namespace: "Tool",
        slashName: "notes",
        run() {
          const Select = api.ui.DialogSelect
          api.ui.dialog.replace(() => (
            <Select
              title="Notes"
              options={[{ title: "Pin", value: "pin", onSelect: () => api.kv.set("notes.pinned", true) }]}
            />
          ))
        },
      },
    ],
  })

  // A sidebar panel, unregistered automatically on deactivate.
  api.slots.register({
    order: 300,
    slots: { sidebar_content: () => <MyPanel /> },
  })

  api.lifecycle.onDispose(() => {
    // stop timers, close handles
  })
}

export default { id: "my-plugin", tui } satisfies TuiPluginModule & { id: string }

Three rules the internal plugins follow, and yours should too:

• Import heavy chains lazily. Anything that pulls the ai package or a provider chain belongs inside the handler, not at module scope — it is charged to every TUI startup otherwise.
• Clean up in onDispose. Process exit is not a teardown path; the runtime disposes plugins explicitly.
• Put per-machine state in KV, shared state in config. Anything a teammate should not inherit from your checkout belongs in api.kv.

Source anchors