@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. Actions with an isActive predicate consume their configured keys only while active; otherwise Pi handles those keys normally.

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. Reopening restores the last page, setting, search, and pane focus, including after reloads in the same Pi process. The first open starts on the UI page. Outside the TUI (print, RPC, and other non-interactive modes), the command only prints a warning.

Configured defaultTools form the session's tool baseline. Startup, resume, reload, and branch navigation automatically enable that selection while keeping other active tools. Historical tool declarations cannot remove configured tools. Pi's explicit tool allowlists and exclusions still limit the available tools. Changes take effect on the next turn without rewriting history.

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.

Global edits are written to xsettings.toml immediately. Settings marked this session are saved in the active session branch and restored on resume; they do not change other sessions or the global file. 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.

The mouse wheel scrolls the column under the pointer: the category sidebar or the settings content. Reaching either end keeps scrolling inside Settings; it does not move the conversation behind the pane.

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. Startup display supports Pi 1.0's full, header-only, and hidden startup modes, preserving pi.quietStartup as false, "header", or true. 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.

Pi 0.87.1 settings include Cache warming (off, streaming, idle) and Compaction → Per-model budgets. Cache warming follows Pi's streaming default and uses Pi's provider eligibility and cost checks; idle warming remains opt-in. Budget rows select an exact provider/model and override response reserve or recent tokens; Use global setting leaves that field inherited. Native settings.json stores the same rows as compaction.modelOverrides, keyed by model ID. Import and export preserve these values and reject malformed budgets before writing.

Recognized Pi settings (theme, compaction, retry, transport, message delivery, enabled models, default tools, and the other pi.* keys shown in the editor) are synchronized with settings.json, which Pi reads before extensions load. Edits through Pi's /settings, model controls, or the JSON file are imported into TOML; edits through /xsettings or TOML are exported to JSON. Bootstrap values such as packages, trust, telemetry, provider, and model configuration stay in settings.json directly. Project-local settings retain Pi's normal override behavior and are not imported into global TOML.

Reconciliation runs at startup, before editor saves, on file changes, and at shutdown. A per-setting baseline lives under ~/.cache/pi-xsettings/, keyed by the resolved TOML and JSON paths, outside the managed configuration tree. Deleting that state starts reconciliation without history. With no baseline, values present in only one file are copied to the other; differing values present in both files are left untouched. Later, edits to different settings merge, including removals. When both sides change the same setting differently, xsettings keeps both values and reports a conflict. Select the desired value in /xsettings or make both files agree to resolve it. Unrelated settings continue to sync.

Sync uses the same settings-file lock as Pi, rereads both files under that lock, and preserves managed symlinks. It watches parent directories so atomic file replacement stays visible. Saved Pi settings still require /reload where Pi does not support live changes; synchronization does not force running sessions to reload. Invalid files are reported and left untouched until repaired.

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	auto (auto, nerd-fonts, unicode, emoji)
activityIndicator / activityMessage	braille-wave / phase
textEffect / textEffectScope / pulseEffect	sweep / message / off
statusPresentation	standard
animationSpeed	relaxed (slow, relaxed, normal, fast, very-fast)
animationSmoothness	balanced (economy, balanced, smooth, ultra)
thinkingIndicator / thinkingTextEffect / thinkingPulseEffect	braille-pulse / glow / pulse
workingIndicator / workingTextEffect / workingPulseEffect	braille-scanline / rainbow-glow / color
Other thinking*, working*, tool* values	inherit (use the General value)
powerline / powerlineButtons / softCursor	false
userMessageBubbles	true (right-aligned user messages; UI → TUI)
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. Declare scope: "session" and apply: "live" for a setting saved with the current session. Read those values with settings.get(ctx.sessionManager.getSessionId()); get() returns global values and compiled defaults.

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	src/config/pi-settings.ts
@luan.sh/pi-libtui and @luan.sh/pi-xsettings definitions	src/config/tui-settings.ts, src/config/presentation.ts
Pi settings reconciliation and file watching	src/config/pi-settings-sync.ts, src/runtime/settings-watch.ts
Configured tool baseline across session lifecycle	src/runtime/tool-selection.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.