Settings screen

zidane-ui/settings is the settings screen. SettingsShell draws a nav, a search and the open section of whatever sections you hand it. SettingsRowsPage draws a page of zidane's settings (General, Agent, Interface, Advanced) from the catalog, read and written through a SettingsHost. The previews run on a fixture host: a toggle writes it, and search lands on the row it finds.

Mount it#

import { createServerClient, createServerSettingsHost } from 'zidane-ui/adapters'
import { SettingsProvider, SettingsRowsPage, SettingsShell, type SettingsSection } from 'zidane-ui/settings'
import { layoutSearchEntries, SETTINGS_PAGES, type SettingsSectionsPage } from 'zidane-ui/settings/headless'

const client = createServerClient({ url: 'wss://box:4280', token })
const settings = createServerSettingsHost({ client })

const sections: SettingsSection[] = SETTINGS_PAGES.filter((page): page is SettingsSectionsPage => 'sections' in page).map(page => ({
  id: page.id,
  title: page.label,
  icon: page.icon,
  description: page.description,
  search: layoutSearchEntries(page, { server: true, actions: [] }),
  render: () => <SettingsRowsPage page={page} server />,
}))

export function Settings({ onClose }: { onClose: () => void }) {
  return (
    <SettingsProvider host={settings}>
      <SettingsShell sections={sections} onClose={onClose} />
    </SettingsProvider>
  )
}

AppHostProvider (zidane-ui/app) puts host.settings in a SettingsProvider for you.

Sections#

A section is { id, title, icon?, monogram?, group?, description?, keywords?, search?, keepMounted?, render }. The shell lists them in order. A section without an icon but with a monogram (an extension's name) shows that word's first letter, uppercase, in a small square the size of an icon.

• group names the section it sits under in the nav, indented. Without one it is a top-level entry.
• search lists the rows inside it. A result opens the section and highlights the row with data-setting-focus equal to its key. Without search the section is found by its title, description and keywords. extraSearch adds entries the section can't list up front.
• keepMounted keeps the body mounted after its first visit, so its async state survives switching away. Its header actions portal into the screen's header with SettingsPanelActions.
• render takes no arguments. The body reads useSettingsSection(): whether it is open, and select(id, focus) to open another section on a row.

layoutSections(pages, { server, actions, renderRows, renderPanel }) (zidane-ui/settings/headless) turns layout pages (SETTINGS_PAGES, visiblePages) into sections: nav entry, group, search entries, panels kept mounted, your body for each.

initialSection and initialFocus open the screen on a section and a row. renderFrame draws your own frame around the nav, search and body: the desktop app puts them in its full-window screen. The default SettingsFrame stacks its two columns below 640px.

The rows#

SettingsRowsPage draws each catalog key as a toggle or a choice. A toggle that needs another setting, a toggle another setting holds on, and a toggle a kill switch turns off (killSwitches) are inert and say why. What the kit can't draw, you supply: customRows (model pickers, agent defaults), renderRow (your own row for a key), rowExtra (after each row), spaces, notes and actions. A custom row you leave out is skipped, and a section left empty is not drawn. With server, the layout's localOnly parts are left out; add spacesOnServer when your app's spaces are the server's (the web app's are), so Spaces stays (layoutSearchEntries takes it too).

Without update, or while writable is false, every row is read-only and the page says so. A failed first read shows an error with a retry.

Preference sections#

Three sections hold what one device prefers, read from the areas that own it rather than from the settings host:

What a host or prop leaves out is hidden: no editorPrefs, no Editing or Diagnostics groups; no openIn, no Open in row. appearanceSettingsSection(props), editorSettingsSection(props) and keybindingsSettingsSection(props) wrap each one as a kept-mounted SettingsSection, with its title, icon, group and search entries from SETTINGS_PAGES.

import { appearanceSettingsSection, keybindingsSettingsSection, SettingsShell } from 'zidane-ui/settings'

<SettingsShell sections={[...sections, appearanceSettingsSection(), keybindingsSettingsSection()]} />

Their strings are their own labels (DEFAULT_APPEARANCE_SECTION_LABELS, DEFAULT_EDITOR_SECTION_LABELS, DEFAULT_KEYBINDINGS_SECTION_LABELS), overridden with LabelsProvider. The previews run on fixture hosts: what you change writes them.

Catalog sections#

These sections read the settings host's optional groups. A section whose group the host leaves out shows nothing to do, and an action the group leaves out hides its button.

paths (reveal, open) adds the Finder and editor buttons on rows. A list the section keeps on screen comes as a SettingsResource (get, subscribe, refresh): createSettingsResource(read) builds one over an async read. skillsSettingsSection(props), extensionsSettingsSection, pluginsSettingsSection, instructionsSettingsSection, environmentsSettingsSection, logsSettingsSection, performanceSettingsSection and hostCatalogSettingsSection return them as SettingsSections with the layout's title and icon.

createServerSettingsHost offers environments, instructions and hostCatalog (installs need the server's allowRemoteInstalls and the admin scope), and extensions over the server's catalog with the options and actions its folder declares (extensions.configSchema, extensions.actions, extensions.actionStatuses, extensions.runAction; create scaffolds in the server user's folder, or in a project inside the server's workspace roots, the only kind a session can then open in). With an admin token it offers logs over logs.list, followed with logs.watch while the section is open and released with logs.unwatch when it closes. zidane-server has no method for this device's skills and plugins on disk, installs by folder or opening a path, so a web app shows the server's catalogs (plugins too) with HostCatalogSection.

SettingsProvider takes the server's name as hostName when its host is a server's. Then the page descriptions, catalog rows and tutorials name the server instead of this computer. A layout page or row carries a serverDescription, where {host} stands for the name. describedOn(part, host) reads it, and layoutSections({ host }) and the descriptors that take a hostName use that function. SettingsTutorial plays tutorialOnServer(topic, host). A text that is true on both hosts reads the same.

tddpdfdocxskills/tddpdfSystem prompttddTest firstpdfRead PDFsAdd a rate limiterUsing tdd

How skills work

1. 1Pick skillsA skill is a folder with a SKILL.md file of instructions. zidane copies it to your skills folder.
2. 2The agent sees the listEach run starts with the name and the description of every skill.
3. 3It reads a skill when a task fitsThe agent then follows the full instructions of that skill.

Repository or package

Browse

Recommended sources

Matt PocockAnthony Fu's packAnthony FuCursor pstackAnthropic

No skills in .claude/skills or ~/.claude/skills.

hello/index.tsexport default defineExtension({ name: 'hello', setup(ctx) { ctx.registerCommand('standup')hello/standupdeployPanelProviderhelloproject-toolsNeeds trust

How extensions work

1. 1An extension is a TypeScript moduleIts folder sits in ~/.zidane/extensions, or in .zidane/extensions of a project. You can also install one from GitHub or npm.
2. 2It adds what you needIt can add commands, tools, side panels, badges or a model provider. Both apps load it at startup.
3. 3You choose what runsTurn each one on or off here. A project's extensions also need your trust.

No extensions in .zidane/extensions or ~/.zidane/extensions.

Looking for plugins…

System promptzidane rulesSYSTEM.md2.1kAGENTS.md640MCP servers320Skills410New run

How instructions work

1. 1zidane builds one system promptIt joins its own rules, your AGENTS.md files, the instructions of your MCP servers and the list of your skills.
2. 2A SYSTEM.md replaces its rulesYour own SYSTEM.md takes the place of the built-in prompt. Your AGENTS.md files still load.
3. 3Each run starts with itThis page shows each part, where it comes from and its size in tokens.

Loading environments…

level ≥

debugdebuginfoinfowarnwarnerrorerror

followClear view0 lines

Nothing logged yet. Extension warnings, MCP diagnostics and host debug lines appear here.

Measuring…

Performance

Measuring…

tddpdfdocxskills/tddpdfSystem prompttddTest firstpdfRead PDFsAdd a rate limiterUsing tdd

How skills work

1. 1Pick skillsA skill is a folder with a SKILL.md file of instructions. zidane copies it to your skills folder.
2. 2The agent sees the listEach run starts with the name and the description of every skill.
3. 3It reads a skill when a task fitsThe agent then follows the full instructions of that skill.

box doesn't take installs from this app. Install on the server.

Reading box's skills…

Accounts and MCP servers#

Two more groups feed Settings › Accounts and Settings › MCP servers. As above, a section whose group the host leaves out shows nothing to do, an action the group leaves out hides its control, and a connection that may not write (writable) shows no action.

providersSettingsSection(props), serverProvidersSettingsSection, mcpSettingsSection and enabledListSettingsSection return them as SettingsSections. A sign-in is the onboarding area's SignInFlow (state, submit, cancel), so an app that already signs in for its setup wizard reuses it.

createServerSettingsHost offers providers over auth.status (with each provider's configuration fields), auth.setApiKey, auth.configure, auth.remove (one credential or all: the sign-out), auth.setPreferred, auth.rename and auth.oauth.*. It offers mcp over catalog.mcps (each server's sign-in state, tools and last Test), mcp.test and mcp.upsert. mcp.upsert writes the user's or the folder's project config, with an Advanced OAuth secret. The mcp group also has mcp.remove, mcp.signOut, and the shared processes mcp.instances and mcp.restart. Writes need the admin scope. settingsMcpServerOf maps a catalog.mcps row to the section's server, as the desktop app's server host does. An MCP server's sign-in needs oauthCallbackUrl. It is the server's /zidane/oauth/callback at the origin through which the page reaches the server, where the browser comes back. A page cannot listen on a loopback port. zidane-server has no method for extension providers of a folder or removing a project's MCP server, so those controls stay hidden there.

Pick a host#

Read settings anywhere#

Put the host at the root and read it with useSettings(): { settings, setSetting, toggle }, the defaults until the host has read. The provider subscribes to document once and hands it down through context, so every reader re-renders off that one subscription. setSetting writes through update and drops a refused write; the document goes back to what the host holds.

import { SettingsProvider, useSettings } from 'zidane-ui/settings'

function ThinkingToggle() {
  const { settings, toggle } = useSettings()
  return <button type="button" aria-pressed={settings.showThinking} onClick={() => toggle('showThinking')}>Thinking</button>
}

<SettingsProvider host={settings}><App /></SettingsProvider>

Model rows#

Settings › Agent's rows that pick a model. The chat models come from the composer's catalog (ComposerHost.models, so put a ComposerHostProvider above), the rest from the host's optional models group:

AgentDefaultsRows edits the agent, model and effort new sessions start on (agentDefaultsOf(settings) reads them, agentDefaultsPatch(value) writes them in one update); with inherited it is a space's rows, falling back to those. SpacesDefaultsSection is Settings › General › Spaces with each space's rows. ConversationPresetsRow previews the transcript presets. ModelListPicker is the bare-id list the decision row and extension model options open.

Extension options, new extensions, Claude Code import#

ExtensionOptionsSection lists the options and action rows the enabled extensions declare, as an ExtensionsSection's children: values live on Settings.extensionConfig, an action runs on the host and its config patch is written in one update. useExtensionOptionsSearch(cwd) makes them search hits (SettingsShell's extraSearch). They read optional members of SettingsHost.extensions: configSchema, actions, actionStatuses, runAction.

CreateExtensionDialog scaffolds an extension (extensions.create) and hands the result to your onOpen (open an authoring session); a project extension stops on the trust notice first. ClaudeImportDialog imports ~/.claude (SettingsHost.claudeImport: detect, run). Both open on the modal layer (useModal) and render nothing when the host leaves their member out. createServerSettingsHost offers both over the server's own files (extensions.create, claudeImport.detect / claudeImport.run) to an admin token when the server takes installs (allowRemoteInstalls): a server scaffolds in its user's folder only, and the import lands on the server.

useClaudeImportAvailable() says whether to offer the import at all: true once claudeImport.detect finds a Claude Code setup on the host, false before and without claudeImport (the desktop app and the web app both hide the action otherwise, as the TUI does).

import { ClaudeImportDialog, useClaudeImportAvailable } from 'zidane-ui/settings'

const available = useClaudeImportAvailable()
const actions = available
  ? [{ id: 'claude-import', label: 'Import from Claude Code', icon: 'i-ph-download-simple', onSelect: () => modal.open(<ClaudeImportDialog cwd={cwd} onClose={modal.close} />) }]
  : []

Parts#

Every string comes from the labels (DEFAULT_SETTINGS_LABELS). The catalog's row copy is data: reword it by handing the shell your own sections.

Test your host#

import {
  describeSettingsAccountsContract,
  describeSettingsClaudeImportContract,
  describeSettingsExtensionOptionsContract,
  describeSettingsHostContract,
  describeSettingsModelsContract,
  describeSettingsSectionsContract,
} from 'zidane-ui/settings/testing/contract'

describeSettingsHostContract('my host', backend => makeHarness(backend), ['update', 'writable'])
// The catalog groups: the host is built over the arrays the suite hands it.
describeSettingsSectionsContract('my host', backend => makeSectionsHarness(backend), ['environments', 'hostCatalog'])
// Accounts and MCP servers: the host holds the providers and servers the suite hands it.
describeSettingsAccountsContract('my host', backend => makeAccountsHarness(backend), ['providers', 'providers.setApiKey', 'mcp'])
// The model rows, the extension options, the Claude Code import: each lists the members the host offers.
describeSettingsModelsContract('my host', backend => makeModelsHarness(backend), ['decisionModels', 'test', 'testDecision'])
describeSettingsExtensionOptionsContract('my host', backend => makeOptionsHarness(backend), [])
describeSettingsClaudeImportContract('my host', backend => makeImportHarness(backend), false)