---
title: Settings (opening it, and getting where you were going)
---

# Open settings

## What it is

### What it is

**Settings** is the central place to change how Omniscio behaves — accounts, channels (Gmail/SMS/Slack/etc.), notifications, sessions, keybindings, appearance, voice, and dozens of other knobs. There is no separate "preferences" window; settings open inside the same Omniscio window as your sessions.

There are four ways to open settings, and all four render the **same** Settings UI:

1. The **gear icon** on the right side of the toolbar (top of the window).
2. The **Settings** entry in the **Omniscio** group at the bottom of the projects sidebar — this is a "virtual project," meaning it lives in the same column as your real projects but its content is the Settings UI rather than a session list.
3. The **tools menu on the mobile tab bar** (a grid icon ▦, on small viewports) — it opens a **header menu** (a dropdown of header tools), and **Settings** is one of its rows. (It is deliberately not a gear — a gear made the menu look identical to the old Settings button.)
4. The **accounts menu on the mobile tab bar** (the scale icon ⚖ at the right end) — its **Settings** row opens Settings, and **Manage Accounts** opens it straight at the Accounts section.

On a phone, either menu's Settings row works from any screen: it closes a full-screen page such as Recipes first, and the phone's Back gesture then returns to the hubs list.

The **first time you open Settings in an app session it lands on the Home page** — a pinned overview at the top of the section list with a large search box, popular-setting tiles, your recently-changed settings, a "Changed from default" list with one-click Reset, and browse-all cards for every group (see [settings-home.md](settings-home.md)). Reopening Settings later in the same app session returns to whatever section you last visited, and a deep link (a toast's "open settings" button, a right-click → setting, a search hit) always goes straight to its target — Home never hijacks those.

Beyond Home you'll see a **section list** on the left (Accounts, Appearance, System, Notifications, Sessions, Keyboard Shortcuts, Connected Tools, channels like Gmail/SMS/Slack, etc.) and the chosen section's content on the right. A **search box** lets you type to find a specific setting by name — it sits at the top of the sidebar on every section, and moves into the Home page's hero while Home is active (same search, same results, just front-and-center). Clicking a result jumps to its section and scrolls to the exact toggle. You can also type a **category name** (e.g. "Performance", "Appearance") to surface that whole category as a top result; selecting it opens that section. Results are ordered by how on-target the match is: a **section (category) name** match comes first, then a **setting whose name** matches, then matches found only in a setting's keywords or description — and a close typo of a name still counts as a name match, so a misspelling doesn't sink the setting you meant. Inside the search results you can navigate with the keyboard: **ArrowDown** / **ArrowUp** move the highlighted result, **Enter** opens the highlighted one, and the highlight wraps from the last back to the first.

There are **four** ways to leave Settings, and they all return you to whatever you were looking at before you opened Settings (a specific session, an inbox view, the Recipes pane, etc.):

1. The **× button** in the top-right of the Settings sidebar (top-right of the mobile section header on mobile).
2. The **Esc** key while Settings is focused and you're not typing into an input/textarea or inside an open dialog/menu.
3. The **gear icon** in the desktop toolbar — clicking it again toggles Settings closed. (On mobile the tools-menu icon opens the header menu rather than toggling Settings, so leave Settings via the × button, **Esc**, or by tapping another tab.)
4. Clicking any project in the projects sidebar, or any other Omniscio sidebar entry (Inbox, Recipes, Tools, etc.).

Settings is non-destructive — closing it keeps your changes; Omniscio saves on every toggle. There's nothing to "save" or "apply" — most changes are live. A few (like **Error Reporting** and **GPU acceleration**) require a restart, and Settings tells you when that's the case.

## Where to find it

The **gear icon at the top-right of the window** on desktop; the same Settings surface is reachable from the mobile navigation and from a session's own menus. The gear glows while you are inside Settings.

## How it behaves

### How to use it

1. **To open via the gear icon (desktop default).** Look at the top-right of the window for a small gear (`Settings` icon). Click it. The view switches to Settings; the gear glows in the accent color while you're inside Settings. Click the gear again to **toggle Settings closed** (returns you to whatever you were viewing before), or use the **× button** in the Settings sidebar's top-right, **Esc**, or any project in the sidebar to leave.
2. **To open via the Omniscio sidebar entry.** Scroll the **Projects sidebar** (leftmost column) to the bottom. There's a group labeled **Omniscio** containing built-in views like Inbox, Recipes, Tools, and **Settings** (gear icon). Click **Settings** to switch to the Settings view. This entry is a "virtual project" — same UI, same data, just a different way in.
3. **To open via the mobile tab bar.** On a phone or narrow window, the tab bar shows Inbox, Projects, and a **tools menu** (a grid icon ▦, not a gear). Tap it to open the **header menu** — a dropdown of the phone-appropriate header tools (Recipes, Bookmarks, Super Prompts, Focus Mode, Help, Mind Map/Whiteboard when enabled, Mute, Feedback, …) — then tap **Settings**.
4. **Pick a section.** The Settings sidebar lists every section: **Accounts** (Claude logins / API keys), **Appearance** (theme, accent color, sidebar density, branch-in-header toggle), **System** (default projects folder, global hotkey, data retention, error reporting, launch on startup), **Notifications** (sounds, silence, mobile push), **Sessions** (Submit key, post-send navigation, draft behavior), **Keyboard Shortcuts** (rebind every keyboard shortcut), **Connected Tools** (install/check Claude Code + helper CLIs), **Voice**, **Workflow**, **Automations**, **Recipes**, **Plugins**, and channel-specific sections for Gmail / SMS / Slack / GitHub / RSS / Webhooks / Calendar / Drive / Sheets / Email Inbound. Click a section to load its content.
5. **Search instead of scrolling.** The search box at the top of the Settings sidebar accepts free text — type "submit" and you'll get **Submit key** under Sessions; type "tray" and you'll get nothing (that one isn't surfaced); type "branch" and you'll get **Show current git branch in header** under Appearance. Click the result — or press **Enter** while it's highlighted (use **ArrowDown** / **ArrowUp** to change the highlight) — to jump to the section and the matching control.
6. **Two open Settings views are independent.** If you open the gear icon while you're already inside the Omniscio → Settings entry (or vice versa), you have two `<Settings />` instances. Each one tracks its own active section and search query — picking a section in one does not change the other. The underlying settings store stays consistent, so any toggle you flip is reflected everywhere immediately.
7. **A few deep-link entry points only work via the gear icon.** Some flows (the "Run Tour" buttons inside Setup Wizards, automation pre-fill from a deep link) thread callbacks through `App.tsx` props that only reach the gear-icon entry. If a "Run Tour" button is inert, you opened Settings via the Omniscio sidebar — close it and use the gear icon instead. See [settings-virtual-project.md](settings-virtual-project.md) for the full v1 limitation list.

There is currently no default keyboard shortcut bound to "Open Settings." If you want one, open Settings → **Keyboard Shortcuts**, find an unbound keybinding for one of the existing actions, or change the **Global Hotkey** in **System** (which only restores the Omniscio window from the tray — it doesn't open Settings directly).

## For agents

### How it works

The gear icon is the `settings` toolbar item — defined in `src/renderer/src/features/toolbar/toolbar-items.ts` and rendered by `src/renderer/src/features/toolbar/ToolbarPinnedItem.tsx` `case 'settings'`. Its `onClick` calls the `onOpenSettings` prop, which `App.tsx` wires into `handleToolbarAction` `case 'settings'`: if the Settings virtual project is currently active, it calls `closeSettings()`; otherwise it calls `openSettingsFromToolbar()`. On mobile the trigger is in `src/renderer/src/components/ui/MobileTabBar.tsx` — a distinct tools/menu glyph (`LayoutGrid`), NOT the Settings gear (the gear made the menu look identical to the old direct-to-Settings button) — and opens the `src/renderer/src/components/ui/MobileHeaderMenu.tsx` dropdown (which surfaces the desktop header tools that are otherwise hidden on mobile); its **Settings** row calls `navigateToSettingsProject()` — the same Settings view. See `mobile-header-menu-contract.md`. Settings is a pinned-by-default toolbar item (see `DEFAULT_PINNED_TOOLBAR_ITEMS` in `src/renderer/src/features/toolbar/toolbar-items.ts`).

The **Close Settings** affordance lives in `src/renderer/src/features/settings/Settings.tsx`: an optional `onClose` prop, when provided, renders a top-right × button in the desktop sidebar, the mobile section header (next to the existing ← back-to-menu button), and the mobile main header. A `useEffect` binds `Esc` on `document` and calls `onClose()`, skipping when the focused element is an `<input>`/`<textarea>`/`contenteditable`, when `event.defaultPrevented` is true, or when the target is inside a `[role="dialog"]`/`[role="menu"]`/`[role="listbox"]` so open dialogs/menus get first crack at Esc.

`src/renderer/src/integrations/SettingsPanelAdapter.tsx` bridges the standalone `<Settings />` into the Dashboard integration registry and wires `onClose` to `closeSettings()` from `src/renderer/src/lib/close-settings.ts`. That helper is a 9-line wrapper around `toggleSettingsFromToolbar(() => undefined)` from `src/renderer/src/lib/toggle-settings-from-toolbar.ts` — the same helper the toolbar gear uses — so all three programmatic exits (X button, Esc, gear) share one navigate-away path. The helper reads the existing `previousPosition: { projectId, sessionId } | null` slice on `src/renderer/src/stores/session-store.ts` (already maintained for `Alt+Q` toggleInbox and other navigation toggles): if `previousPosition` is set, restore that project/session and re-stash the pre-toggle Settings position; if null (cold start, deep-link), fall back to `INBOX_ID`. No new state was added for this feature — exit re-uses the slice entry already pays for.

The Omniscio sidebar entry is registered as a virtual project named "Settings" with the sentinel `SETTINGS_PROJECT_ID` from `src/shared/types.ts`; registration happens at startup in `src/main/index.ts` via `ensureVirtualProject('Settings', SETTINGS_PROJECT_ID)`. The Dashboard renders a lazy-loaded `<Settings />` (via `LazySettingsView`) when the active project's id matches the sentinel — see the `isSettingsSelected` branch in `src/renderer/src/features/dashboard/Dashboard.tsx`. Both entry points mount the same `<Settings />` component from `src/renderer/src/features/settings/Settings.tsx`, which holds the section list, search index (`src/renderer/src/features/settings/settings-search-index.ts`), and the right-pane content router. The 50-section list lives in `VALID_SECTIONS` near the top of `Settings.tsx`.

## Related

### Related

- [settings-home.md](settings-home.md) — the Home landing page: popular tiles, recently changed, changed-from-default with Reset
- [settings-virtual-project.md](settings-virtual-project.md) — the architecture: why two entries exist, what doesn't reach the Omniscio entry yet
- [keyboard-shortcuts.md](keyboard-shortcuts.md) — every default shortcut and how to rebind it (Settings → Keyboard Shortcuts)
- [tray-and-window.md](tray-and-window.md) — closing the window vs hiding to tray, and the global hotkey that restores the window
- [add-a-claude-account.md](add-a-claude-account.md) — Settings → Accounts is where you add your first Claude login