@luan.sh/pi-xsettings  

@luan.sh/pi-xsettings is a settings host for Pi extensions. It adds the /xsettings editor to Pi's interactive TUI, persists Pi and extension settings in one xsettings.toml file, exposes a UI-free SDK (@luan.sh/pi-xsettings/sdk) that other extensions use to declare typed settings, and binds keys from keybindings.json to actions that extensions register through pi-libactions.

Preview

Watch the demo.

Install

pi install npm:@luan.sh/pi-xsettings

Optional companion: pi install npm:@luan.sh/pi-panels. When a side-panel host is present, /xsettings opens as a "Settings" tab beside the session; without it, the editor opens as a fullscreen overlay.

Use

In the TUI, run /xsettings. Outside the TUI (print, RPC, and other non-interactive modes) the command only prints a warning.

The left sidebar lists eight pages: UI, Editor, UX, Animations, Terminal, Behavior, Interaction, and Tools, with each page's sections underneath. Extension settings appear under the label the extension registered. The search field at the top filters settings across every page. / focuses search; Tab (or the key bound to xsettings.cursor.toggle) toggles focus between sidebar and content. In the sidebar, arrows or j/k move and Enter opens the highlighted destination. In the content, h/l or left/right change pages, Enter edits the selected setting, and Backspace restores its default.

Every confirmed edit is written to xsettings.toml immediately. Settings marked live (the theme and all @luan.sh/pi-libtui settings) apply to the running TUI at once. Other settings need a reload: when the editor was opened from /xsettings, Pi reloads after you close it; otherwise it tells you to run /reload.

xsettings.toml

The file lives in Pi's agent directory, normally ~/.pi/agent/xsettings.toml. If it does not exist, the host creates it with a single comment line.

Values are stored under four fixed category tables: appearance, behavior, interaction, and tools. Inside a category, Pi's own settings are keyed pi.<key> and extension settings <namespace>.<key>:

[appearance]
pi.theme = "tokyo-night"
pi-libtui.iconPack = "nerd-fonts"
pi-xsettings.presentation = "fullscreen"

[interaction]
pi.steeringMode = "one-at-a-time"

[tools]
pi.defaultTools = []

Unknown keys and other top-level tables are kept but not shown in the editor. Writes go to a temporary file followed by a rename; a symlinked path has its target written rather than the link. Comments and layout are not preserved. An omitted pi.defaultTools means "use Pi's default tools"; pi.defaultTools = [] disables every built-in tool.

Recognized Pi settings (theme, compaction, retry, transport, message delivery, enabled models, default tools, and the other pi.* keys shown in the editor) are mirrored into settings.json in the same directory, because Pi reads that file before extensions load. Keep bootstrap values such as packages, trust, telemetry, provider, and model configuration in settings.json directly.

Settings owned by this package

Both namespaces below are registered with createSettings and edited via /xsettings; when a value is absent or invalid the default applies. Namespace @luan.sh/pi-xsettings (label "Xsettings") has one key, presentation, default side-panel (or fullscreen); side-panel falls back to fullscreen when no panel host is present.

Namespace @luan.sh/pi-libtui (label "TUI", all applied live):

| Key | Default | | --- | --- | | iconPack | unicode (nerd-fonts, unicode, emoji) | | activityIndicator / activityMessage | spinner / phase | | textEffect / textEffectScope / pulseEffect | off / message / off | | statusPresentation | standard | | animationSpeed | normal (slow, relaxed, normal, fast, very-fast) | | animationSmoothness | balanced (economy, balanced, smooth, ultra) | | thinking*, working*, tool* (Indicator, Message, TextEffect, PulseEffect, Presentation) | inherit (use the General value) | | powerline / powerlineButtons / softCursor | false | | insertionCursor / navigationCursor / selectionCursor | virtual |

Actions and keybindings

Actions registered by this package: xsettings.toggle (open the editor, same as /xsettings), xsettings.cursor.toggle (toggle sidebar/content focus inside the editor, replacing Tab), and xsettings.effort.decrease / xsettings.effort.increase (step through the current model's supported thinking levels, stopping at either end).

None of them has a default key. Bind them in keybindings.json in Pi's agent directory, normally ~/.pi/agent/keybindings.json. Each property is an action ID; each value is a key ID string or an array of key ID strings:

{
  "xsettings.toggle": "ctrl+,",
  "xsettings.cursor.toggle": "ctrl+t",
  "xsettings.effort.decrease": ["alt+,"],
  "xsettings.effort.increase": ["alt+."]
}

The file is read once when extensions load, so reload Pi after editing it. Invalid JSON, an invalid key ID, or an unbound action installs no shortcut; the action stays available through its command or UI. This package is also the global shortcut host: for every action any installed extension registers through @luan.sh/pi-libactions, it calls Pi's registerShortcut() with the keys configured for that action ID. Other extensions' READMEs list their action IDs.

SDK for extension authors

Import the UI-free SDK, not the extension entry point:

import { createSettings } from "@luan.sh/pi-xsettings/sdk";

const settings = createSettings({
  namespace: "pi-example",
  label: "Example",
  definitions: {
    enabled: {
      label: "Enabled",
      description: "Enable the example feature.",
      category: "behavior",
      type: "boolean",
      default: true,
    },
    mode: {
      label: "Mode",
      description: "How the feature runs.",
      category: "behavior",
      type: "enum",
      default: "safe",
      options: [{ value: "safe", label: "Safe", description: "" }, { value: "fast", label: "Fast", description: "" }],
    },
  },
});

const unregister = settings.register((values) => { /* values.enabled, values.mode */ });

createSettings() returns defaults (compiled defaults), get() (a clone of the current values), and register(onValues) (returns a disposer). Types are boolean, string, enum, multi-enum (with ordered), string-list (helper stringListSetting(), with minItems), and schema-checked list (helper listSetting(schema, definition) with a TypeBox schema and a declarative item definition). Enum options may carry a @luan.sh/pi-libtui color, or point at another setting's list via { source: "setting", setting, field }.

Each definition names a category (its TOML table). Optional page places it on one of the eight pages without changing the TOML path (default: the page matching the category, appearance on UI); section sets the heading (default: the registration label); apply is "live" or "reload" (default "reload", overridable per registration); preview selects an animation preview kind. Invalid stored values fall back to the default, enum values resolve to a valid option, and multi-enum values drop stale choices.

Registration works before the host loads or when it is absent: values arrive when the host publishes them, and without a host the extension keeps its defaults. Add @luan.sh/pi-xsettings to your package's dependencies; do not create a separate settings file or settings screen.

Layout

| Responsibility | File | | --- | --- | | Pi command, actions, side-panel tab, lifecycle | src/extension.ts | | UI-free SDK | src/sdk.ts | | Cross-extension registry protocol | src/protocol/settings.ts | | xsettings.toml load, set, unset, atomic write | src/config/store.ts | | Pi setting definitions and settings.json mirror | src/config/pi-settings.ts | | @luan.sh/pi-libtui and @luan.sh/pi-xsettings definitions | src/config/tui-settings.ts, src/config/presentation.ts | | Value resolution, publication, reload decision | src/runtime/settings.ts, src/runtime/apply.ts | | Keybinding bridge and effort actions | src/runtime/actions.ts, src/runtime/effort.ts | | Editor session, fields, list editors, screen | src/ui/ |

Develop

Source: https://github.com/luan/agents, directory harnesses/pi/agent/packages/pi-xsettings. Run bun run typecheck and bun test test in that directory.