Lifecycle and storage

Plugins can explicitly subscribe to active-terminal lifecycle events beside commands. Use commands: [] for an event-only plugin.

export default definePlugin({
  commands: [],
  events: {
    "terminal.ready"({ context }) {
      context.toasts.info("Terminal ready");
    },
    "tab.activated"({ event, context }) {
      console.log(event.previousTabIndex, context.activeTab?.index);
    },
    "workingDirectory.changed"({ event }) {
      console.log(event.previousWorkingDirectory, event.workingDirectory);
    },
    "command.finished"({ event }) {
      console.log(event.command, event.exitCode, event.durationMs);
    },
  },
} satisfies TermyPlugin);

Handlers receive the same read-only context as commands. They can emit toasts or return the same actions.

terminal.ready runs once after the plugin catalog is ready. The remaining events track the active terminal tab, working directory, and completed command. Native shell integration provides command exit codes and measured durations; tmux command completion is inferred, so unavailable fields are omitted instead of guessed.

Events remain ordered within one plugin. Separate plugins may handle them concurrently under the normal execution timeout.

Store JSON values

Use the asynchronous storage API for small persistent values:

const todos = await context.storage.get<Todo[]>("todos") ?? [];
await context.storage.set("todos", todos);
await context.storage.delete("todos");
await context.storage.clear();

Each plugin can store up to 512 JSON values totaling 1 MiB. Storage is plain local JSON; use a declared secret setting for credentials.

Store larger files

context.paths.dataDirectory is for larger persistent files, while context.paths.cacheDirectory is for disposable data. Plugins may use Bun or Node-compatible file APIs to read and write these paths.

Both locations are isolated per plugin, live outside the content-hashed source tree, and survive reloads and updates. Uninstalling a plugin removes its storage, data, and cache. Disabling it keeps them.

Use Native UI to turn stored data into a small native tool, or review the security model before handling sensitive data.