Skip to content

Extension guides

Panels and settings

Panels hold project information beside the transcript. Settings sections configure the extension, while the Pi half remains responsible for reading and writing durable state.

Context panels

A panel appears in the project context pane beside NativePi's Git surfaces. It is the roomiest contribution slot and the right place for information the reader consults rather than reads inline.

export default defineRenderer({
  apiVersion: 1,
  protocol: schemaProtocol,
  panels: [
    {
      id: "database-schema",
      title: "Database schema",
      render: (context) => (
        <SchemaTree projectPath={context.project.path} channel={context.channel} />
      ),
    },
  ],
});

Panels render for a new chat as well as a saved session. Use project state without assuming session.file exists. Keep frequent actions near the information they affect, but avoid turning a panel into a second application shell.

Settings sections

A section appears under Settings → General. NativePi draws the heading and optional description; the renderer supplies the controls.

export default defineRenderer({
  apiVersion: 1,
  protocol: settingsProtocol,
  settings: [
    {
      id: "query-settings",
      heading: "Query settings",
      description: "Choose how this package runs database queries.",
      render: (context) => <QuerySettings context={context} />,
    },
  ],
});

Persist through the Pi host

Renderer storage would create settings that exist only in NativePi and disappear from the extension in Pi's terminal UI. Instead, define protocol methods that read and update the extension's settings in the Pi process.

export const settingsProtocol = defineProtocol({
  methods: {
    getSettings: { result: settingsSchema },
    updateSettings: {
      params: settingsSchema.partial(),
      result: settingsSchema,
    },
  },
  events: {
    settingsChanged: settingsSchema,
  },
});

Settings controls

The shared UI exports complete settings rows for common values: SettingsActionRow, SettingsSwitchRow, SettingsSelectRow, SettingsTextRow, and SettingsSliderRow. Use them before assembling custom field layouts.

See Shared UI settings rows for their props.