Plugins

Extend the terminal with commands, middleware, panels, and more.

Plugin Interface

A plugin is an object that implements TerminalPlugin. All fields are optional except name.

types.ts
interface TerminalPlugin {
  name: string
  version?: string
  commands?: Command[]
  statusBarItems?: StatusBarItemType[]
  panels?: Array<{
    id: string
    component: ComponentType<PanelProps>
  }>
  onInit?: (ctx: PluginContext) => void | (() => void)
  middleware?: MiddlewareFn
}

Commands

Plugins can register commands that appear in help and tab completion alongside built-in commands.

plugin-commands.tsx
const myPlugin: TerminalPlugin = {
  name: "my-plugin",
  commands: [
    {
      name: "ping",
      description: "Pong!",
      execute: () => ({
        output: [[{ text: "pong", color: "main" }]],
      }),
    },
  ],
}

<Terminal plugins={[myPlugin]} />

Middleware

Middleware wraps command execution. Call next() to continue the chain, or return directly to short-circuit.

middleware.tsx
const loggingPlugin: TerminalPlugin = {
  name: "logger",
  middleware: (input, next) => {
    console.log(`[terminal] ${input}`)
    return next()
  },
}

Panels

Plugins can register panel components that open as overlays or split views. Open a panel by returning panel in a command result.

panels.tsx
const panelPlugin: TerminalPlugin = {
  name: "my-panel",
  panels: [
    {
      id: "info-panel",
      component: ({ onClose }) => (
        <div>
          <h2>Info Panel</h2>
          <button onClick={onClose}>Close</button>
        </div>
      ),
    },
  ],
  commands: [
    {
      name: "info",
      description: "Open info panel",
      execute: () => ({
        output: [],
        panel: { id: "info-panel", position: "split-right" },
      }),
    },
  ],
}

Panel positions: "overlay", "split-right", "split-bottom".

Status Bar

Plugins can contribute items to the status bar at the bottom of the terminal.

status-bar.tsx
const statusPlugin: TerminalPlugin = {
  name: "status",
  statusBarItems: [
    { type: "cwd" },
    { type: "info", text: "v1.0.0" },
    {
      type: "shortcut",
      key: "Ctrl+P",
      label: "Palette",
      command: "help",
    },
  ],
}

Plugin Context

The onInit callback receives a PluginContext for interacting with the terminal. Return a cleanup function to run on unmount.

types.ts
interface PluginContext {
  execute: (command: string) => Promise<void>
  registerCommand: (command: Command) => void
  getHistory: () => HistoryEntry[]
  getCwd: () => string
}
0