@zigai/pi-settings-ui

Schema-driven TUI editor for Pi extension settings.

Packages

Package details

extension

Install @zigai/pi-settings-ui from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@zigai/pi-settings-ui
Package
@zigai/pi-settings-ui
Version
1.1.0
Published
Oct 11, 2026
Downloads
227/mo · 203/wk
Author
zigai
License
MIT
Types
extension
Size
240.1 KB
Dependencies
2 dependencies · 5 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

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

README

Pi Settings UI

Edit extension-owned Pi settings through a schema-driven terminal interface. The editor discovers the generated schemas installed by @zigai/pi-extension-settings and turns them into validated, reusable controls.

  • Pi's regular settings selector as the first tab, followed by one tab per extension.
  • A compact active-tab header and searchable Ctrl+P switcher that scale to large extension sets.
  • Global and trusted-project scopes for extension-owned settings.
  • Native toggles, searchable choices, sliders, path completion, color previews, text, and number controls plus nested editors for lists, records, maps, and unions.
  • Humanized, grouped labels with aligned values, descriptions, constraints, and override state.
  • Atomic, conflict-checked saves that leave malformed settings untouched.

Pi 0.84 renderer mode and fullscreen scrollbar changes are saved from the Pi tab and take effect in the next Pi session. Pi does not currently expose live renderer switching to extensions.

Install

pi install npm:@zigai/pi-settings-ui

Schema controls

Extension schemas may use the optional x-control JSON Schema keyword to state presentation intent that ordinary types and constraints cannot express. With TypeBox, pass it as a quoted schema option:

Type.String({ "x-control": "textarea" });
Type.String({ "x-control": "path" });
Type.Integer({ minimum: 1, maximum: 20, "x-control": "slider" });
Type.String({ "x-control": "combobox", examples: ["accent", "warning"] });
x-control Compatible schema TUI behavior
text string Single-line inline input.
textarea string Pi's multiline editor.
switch boolean Boolean toggle.
segmented primitive choices Compact choice changed with Left and Right.
select primitive choices Searchable choice picker.
slider number or integer Compact range bar; Left and Right step by multipleOf or the numeric default, while Enter accepts an exact value.
numeric number or integer Single-line numeric input.
color string Single-line color input with a live swatch for hexadecimal colors.
path string Single-line path input; Tab completes files and directories relative to Pi's working directory or ~.
combobox string or string-only union Searchable suggestions from string examples or finite string branches, plus a custom schema-validated value.
json-editor any schema Full validated JSON editor instead of a shape-derived control.

Configuration

Global settings are stored in ~/.pi/agent/extension-settings/pi-settings-ui.json.

Option Type Default Description
projectOverrides boolean true Let trusted projects have their own extension settings. 
{
  "$schema": "./schemas/pi-settings-ui.schema.json",
  "projectOverrides": true
}

Development

just --justfile ../../Justfile setup
npm run build --prefix ../..
just coverage

License

MIT