pi-extension-settings-tui

Declarative, mouse-capable TUI settings dialog and hardened layered JSON persistence library for Pi extensions over @earendil-works/pi-tui.

Packages

Package details

extension

Install pi-extension-settings-tui from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:pi-extension-settings-tui
Package
pi-extension-settings-tui
Version
0.6.0
Published
Nov 21, 2026
Downloads
1,296/mo · 1,296/wk
Author
championswimmer
License
MIT
Types
extension
Size
825.9 KB
Dependencies
0 dependencies · 2 peers

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-extension-settings-tui

npm version npm downloads license

A declarative settings dialog and layered JSON persistence library for Pi extensions, built on @earendil-works/pi-tui. Define your schema once to get a themed TUI overlay, fullscreen mouse support, hardened Global/Project overrides, and automatic RPC/headless fallback.

  • Declarative schema + strict TS inference — defineSettings and field.* builders infer exact literal union types via typeof schema.Type.
  • Single-overlay TUI + fullscreen mouse — tabs, searchable pickers, collapsible multi-select checklists, first-class Pi model + thinking level picker (Scoped/All + fuzzy search), inline editors, and custom sub-routes with native SGR mouse clicks and wheel scrolling.
  • Global & Project layered overrides — stores only diffs from defaults, shows provenance dots (●), and supports custom file names, path resolvers, or Pi session storage.
  • Hardened atomic I/O — 0o600 temp-file writes with fsync, symlink refusal, 64 KiB cap, secret-key rejection, and optimistic concurrency checks.
  • Automatic RPC & headless fallback — builds a ctx.ui.select/input menu in RPC mode and returns resolved settings cleanly in print/json mode.
  • Zero runtime dependencies — pure ESM for Node >=22.

Preview

Interactive settings dialog demo

Supports fullscreen mouse clicks and wheel scrolling across tabs, searchable pickers, collapsible multi-select checklists, and Global/Project provenance dots (●).

Settings Dialog Multi-Select Checklist
Settings dialog screenshot Multi-select checklist screenshot

Install

npm install pi-extension-settings-tui

@earendil-works/pi-coding-agent (>=1.5.0) and @earendil-works/pi-tui are optional peer dependencies — already provided inside Pi, and not required for the standalone /schema or /store subpaths.

Quickstart

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { defineSettings, field, openSettingsDialog } from "pi-extension-settings-tui";

const schema = defineSettings({
  id: "my-extension",
  title: "My Extension Settings",
  settingsFile: "my-extension.json",
  tabs: [{ id: "general", label: "General" }],
  fields: {
    enabled: field.boolean({ tab: "general", label: "Enable extension", default: true }),
    mode: field.enum({
      tab: "general",
      label: "Mode",
      default: "balanced",
      options: [
        { value: "off", label: "Off" },
        { value: "balanced", label: "Balanced" },
        { value: "strict", label: "Strict" },
      ],
    }),
    maxRetries: field.integer({ tab: "general", label: "Max retries", default: 2, min: 0, max: 10 }),
  },
});

export type MySettings = typeof schema.Type;

export default function (pi: ExtensionAPI) {
  pi.registerCommand("my-settings", {
    description: "Open My Extension settings",
    handler: async (_args, ctx) => {
      await openSettingsDialog(ctx, { schema });
    },
  });
}

With settingsFile: "my-extension.json", settings automatically mirror to ~/.pi/agent/my-extension.json (Global) and <cwd>/.pi/my-extension.json (Project).

Documentation

Guide Covers
Getting Started Full walkthrough, reading settings at startup, trying the demo extension
Field Types & Custom Sub-Routes boolean, enum, multiSelect, string, number, integer, model, custom
Storage, Scopes & Security Custom file names/paths, Global vs Project layers, session storage, hardening
TUI, Fullscreen Mouse & RPC Fallback Keyboard/mouse controls, subpath exports, non-TUI fallback
Demo Extension Runnable Pi extension showcasing every field type

License

MIT © 2026 Arnav Gupta