Settings reference: options, defaults, and when they apply
Look up options by 1.3.3 settings section and understand saved values, installation defaults, scope, and experimental options.
Settings & helpHow to use this reference#
Click the account button at the bottom of the left navigation rail and choose Settings. The settings sidebar has four groups, and this page follows the same order:
| Group | Sections |
|---|---|
| App settings | General, Notifications, Appearance, Session organization, Keyboard shortcuts, Voice |
| AI and connections | Personalization, Tools, AI services, Claude Code, Browser, Secrets and hosts, Network proxy |
| Coding | Worktrees |
| Account and data | Account and license, Claude subscription usage, Activity, System permissions, Privacy, Storage, Archived sessions |
Your displayed value takes precedence. Upgrades generally preserve existing choices. The tables distinguish new-install defaults from fallback values used when a saved configuration is missing a field. For worked examples, see settings and data.
General: language, new sessions, and input#
| Group → option | How to choose | Effect and scope |
|---|---|---|
| Interface and window → Language | Choose the interface language | Not a universal response-language switch |
| Interface and window → Always on Top | Keep results visible while using other apps | Applies to the window immediately |
| New session defaults → Default Permission Mode | Default permissions, Auto mode, or Full access; see permissions | New-session default; existing sessions keep their own choice |
| Editor → Plain text editor | Keep links and references as editable text while composing | Off by default; applies immediately to all inputs |
| Editor → Show context window usage | Turn off if you do not want the context indicator in the input | On by default |
| Editor → Send shortcut | Enter or ⌘/Ctrl+Enter | Enter by default; Shift+Enter always inserts a new line |
| Editor → Follow-up behavior | While a reply is running, queue messages or steer the current reply | Queue by default; the shortcut in the description performs the other action |
| External applications → Default open tool | Choose a detected editor or terminal, or Remember last used | Controls the external-editor entry's main action; the entry itself is enabled in Appearance → Conversation display |
| Background activity → Keep running in background | Prevent sleep while a schedule, channel message, or session runs | Uses more power; normal power saving resumes afterward; macOS lid-close sleep is not covered |
| Updates → Check for Updates | Inspect version and available updates | Download and install, restart to update, or download manually as offered |
Notifications now have their own section, and display controls live in Appearance.
Installation defaults and saved choices
| Option | Fresh-install baseline | Missing-value fallback in older configurations |
|---|---|---|
| Theme / language | Light / Chinese | Existing choice or environment initialization |
| Permissions | Full access | Default permissions, or a compatible existing full-access configuration |
| Notification types | In-app off, desktop on | If an earlier version explicitly turned desktop notifications off, desktop stays off for every type |
| Automatic AI naming | Off | Off without an explicit naming policy; saved choices remain in effect |
| AI browser control | Off | Existing enabled settings remain enabled |
| Keep running in background | On | Off |
| Memory daily budget | $10 | $1 when a budget was never set |
Notifications: types, sounds, and system delivery#
| Option | What it covers | Default and notes |
|---|---|---|
| Notification types → Needs your confirmation | Claude asks a question, wants a tool approved, or has a plan for you to review | Desktop on, Ding sound |
| Notification types → Secret authorization | The AI wants to use, change, or read a saved secret, or connect to a new server | Desktop on, its own Rise sound |
| Notification types → Task completed | A conversation finishes its turn and is waiting for you | Desktop on, Chime sound |
| Task completed → When to notify | In background only, or Always | By default you are notified only when that conversation is not visible, including while Onevium shows another conversation |
| Notification types → Background tasks and subagents | A background task, subagent, or teammate finishes, fails, or stops, or Claude recalls a memory | Desktop on, Pop sound |
| Notification types → Errors and failures | A turn ends with an error, or a worktree cannot be created or restored | Desktop on, Alert sound |
| In-app / Desktop / sound per type | Check each channel; choose No sound to mute; the speaker button previews the sound | Saves immediately; Desktop is unavailable where the system cannot deliver notifications |
| Desktop notifications → System permission | Send test notification, Open system settings, and setup tips | On macOS the first test notification raises the permission prompt |
Figure 1: the five notification types and their sounds, with the 1.3.2 settings groups on the left. Isolated demonstration of the real notification settings component showing fresh-install defaults; no notification was sent and no system setting changed.
If desktop notifications do not appear, check system notification settings and Do Not Disturb or Focus, then System permissions. For the conversation lists in the Dock menu and menu bar hub, see menu bar hub.
Appearance: theme, sidebar, and conversation display#
Appearance has four tabs. Choices save automatically and apply to all conversations. If saving fails, the last saved appearance is restored and Retry is available.
Theme and typography
| Option | How to choose | Effect and scope |
|---|---|---|
| Light / Dark / System | Fix the brightness or follow the operating system | Applies across the workspace |
| Workspace palette | Neutral, Warm paper, Codex style, GitHub style, Notion style, Claude style, Catppuccin, or Nord | Eight palettes, each with light and dark colors; changing palette also selects its matching link color |
| Link and focus color | Palette default, Blue, Teal, Plum, or Warm brown | Colors conversation links and keyboard focus outlines |
| Visual contrast | Standard or Higher contrast | Makes muted text and boundaries more distinct |
| Interface / Message / Code font | Choose each separately | Separate fonts for interface text, conversation text, and code blocks |
| Chat / code text size | 12–16px / 10–16px | Adjusted separately with a live preview |
| Message weight | Regular or Medium | Headings and bold retain emphasis; code weight is unchanged |
The built-in terminal and code editor follow the workspace colors; this does not configure an external editor. Restore color and font defaults resets only these choices and keeps reading density and the Light/Dark/System selection.
Sidebar and session list
| Option | How to use it | What to verify |
|---|---|---|
| Layout preset and individual positions | Start from a preset, then place markers, channel/schedule icons, and activity status left or right of the title | Check the preview and an existing conversation |
| Sidebar text size | Adjust navigation, project names, and session titles | Message and code sizes remain independent |
| Initial default width | Enter at least 260 px | A manually dragged width stays remembered; double-click the sidebar edge to use the default again |
| Channel conversation titles | Show or hide sender and group/contact names separately | With both enabled, the sender comes first |
| Navigation entries | Toggle entries and drag to reorder | Hidden entries remain under Explore; New session stays first |
Conversation display
| Option | How to choose | Effect and scope |
|---|---|---|
| Reading density | Compact, Standard, or Relaxed | Adjusts spacing and line height across conversations; Restore spacing default resets only density |
| Message Navigator | Return to earlier messages in long chats | On by default; hover at the chat's right edge |
| Audio visualization | Animate conversation ticks with microphone and system sound | Needs Microphone and Screen and system audio permissions; analyzed locally, never recorded or uploaded |
| File change cards | Show per-turn file change cards and the live summary | Hiding them keeps recorded changes and restoration available |
| Toolbar entries → External editor entry / Commit entry | Show the top-right buttons to open the project or commit | Hidden by default; Review can still commit |
Completed turns collapse their process into a summary; click it to inspect tool steps. Collapsing changes display only.
Motion and performance
| Option | How to choose | Effect and scope |
|---|---|---|
| Reduce visual effects | First adjustment for flicker or stutter | Reduces decorative animation immediately |
| Disable hardware acceleration | Try if reducing effects does not help | Requires restart; may reduce smoothness |
Session organization: naming rules and labels#
This section has Naming rules and Labels tabs. To create labels, apply conversation markers, and filter by label, see Conversation organization. Naming rules save automatically; new or edited labels require Save label.
AI naming is opt-in: under Naming rules, enable Automatically update conversation titles, choose the naming model, and inspect the prompt. Enabling it does not rename old conversations immediately, and manual titles remain protected. Existing saved policies are retained; a missing policy defaults to off. Manual Generate with AI remains a separate action.
Keyboard shortcuts: edit, resolve conflicts, and global commands#
- Search for a command, select its row, and press a combination.
- A valid, conflict-free combination saves directly; Escape cancels recording.
- Transfer resolves a conflict by removing that binding from the previous command.
- Clear a binding, restore one default, or confirm a reset of all bindings.
Commands have global, chat, file-panel, browser, and other scopes. Some entries, such as double-Escape stop and Shift+Tab Plan switching, are fixed references.
System commands that work from any app—Open quick access, Open secrets quick window, Open verification codes, Open password generator, and Show or hide Onevium—have no default binding, so they never take a key another app already uses. ⌥⌘K (secrets quick window) and ⌥⌘T (verification codes), the 1.3.1 defaults, are no longer bound by default starting with 1.3.2; bind your own here if you want them. Capture active window defaults to the double-Command gesture, which requires Accessibility permission; a normal key combination does not. See menu bar hub for how the quick-access commands are used.
Voice: recognition, polish, and history#
| Control | How to configure it | How to verify |
|---|---|---|
| Recognition models | Download a suitable language model, then make it current | Verify with a short recording |
| AI transcript polish | Enable for homophone and punctuation cleanup | On by default; sends text to the model provider |
| Polish model | Choose a working model | Defaults to a low-cost role |
| Enable voice input | Off hides the microphone and disables its shortcut | Check the composer; on by default |
| Microphone selection | Authorize access, then choose system default or a detected device | Verify the selected device with a recording |
| History and recordings folder | Inspect records and local audio | Check the latest record and open its audio file |
| Copy transcript / Download recording / Delete recording | Use the actions on a history record | Paste or open the export to check; confirm the target before deleting |
Local recognition and AI polish are separate stages. There is no visible recording-retention-days setting. See voice dictation.
Correction preferences and vocabulary
Open Voice → Correction preferences → Manage. Write a short rule such as “Keep product names in English and preserve numbers,” then click Save preferences. Industry templates fill editable instructions; review them before saving. Closing the dialog does not save.
Under My words, add a correct spelling and optional common misspellings, then save the word. Learned words come from clear edits made before sending and are extracted by a later AI correction, with no extra model request at send time; one edit does not guarantee a learned word. Clearing learned words also removes pending examples while keeping manual words and instructions.
Personalization and the memory space#
| Group → control | Purpose and when to change it | Default, scope, and effect |
|---|---|---|
| Personalization (master switch) | Controls user rules, memory, and tool assessment | On by default |
| User Rules → Enable user rules | Stable preferences and habits | Off by default; up to 4,000 characters; autosaved; user scope |
| Memories → Use memory | Extract and use durable information from conversations | On by default; not a switch for saving all chat history |
| Memories → Extraction frequency | High: each turn; balanced: every 3; economy: every 5; or off | Balanced by default; off stops new extraction, not recall |
| Memories → Deep extraction | Include reasoning, alternatives, and tradeoffs | Off by default; adds extraction usage |
| Memories → Extraction language | Language of new memories | Follows interface by default; does not translate existing items |
| Memories → Excluded projects | Projects that should not create new memories | All included by default; exclusion does not delete existing items |
| Recall and upkeep → Recall threshold | Strict, balanced, relaxed | Strict for fresh installs; balanced fallback for older configurations |
| Recall and upkeep → Cross-project search | Retrieve relevant memories from other projects | Off by default; not blanket cross-project injection |
| Recall and upkeep → Context length | Compact, balanced, detailed | Balanced by default; memory volume, not the model window |
| Recall and upkeep → Auto-organise frequency | Daily, weekly, off | Daily by default |
| Background AI model and budget → Tool Assessment, Background AI model | Model shared by memory extraction and tool assessment | Must be callable |
| Background AI model and budget → Budget used / Budget Limit | Today's usage and the daily cap for automatic extraction | Counted at actual cost; $10 for fresh installs, $1 for early installs that never set one; not a total chat budget |
| Memory space | Browse, search, correct, disable, or forget memories, and inspect sources, links, and usage | Opened from Personalization; the sidebar keeps Personalization highlighted |
See memory and recaps for the full workflow. @Memory initiates work on Claude Code rule or memory files; it does not save a database memory to the memory space. Daily Briefing is retired; see the separately installed Daily review Skill.
Tools: built-in capability groups#
| Group | Purpose | Default or behavior |
|---|---|---|
| Schedules | Manage automations | Opt-in; enable in Settings → Tools or through the relevant capability card |
| Charts and interactive content | Create visual artifacts | On by default |
| Browser Preview | Browser tools | On by default; also requires AI browser control in Browser |
| Sessions and titles | Work across conversations, child sessions, teams, and title organization | Opt-in; enable in Settings → Tools or through the relevant capability card |
| Recap (work activity) | Generate work recaps | Opt-in; enable in Settings → Tools or through the relevant capability card |
| Image creation | Generate and edit images | On by default; an image service must be configured |
| Services (managed processes) | Manage services | On by default |
| Channels (manage bots) | Let the assistant manage channel configuration | Off by default; not the switch for connected bots |
| Secrets and hosts | Use secrets and SSH by reference | Off by default; turned on in Secrets and hosts |
| Turn Continuity / Channel Messaging | Automatically supplied runtime tools | Informational rows, not switches |
An opt-in group with no saved setting is off; already enabled choices are retained. Disabling a group prevents further calls, and newly enabled tools are available with the next message. Switches do not undo completed actions or delete existing conversations, schedules, or recap data.
AI services: model connections#
Add or adjust providers, models, and connection configuration here. Confirm the endpoint, credentials, and model, then send a short message; saving does not prove a working model. See providers and custom providers for the fields.
Open the provider's model configuration and expand Default reasoning effort to choose a starting level for models with multiple levels. Each choice saves immediately for that provider and model and seeds new conversations; existing conversations keep their own effort.
For an Anthropic-compatible relay, declare 1M support under the provider editor → Advanced Options → Endpoint supports 1M context, and enable the global 1M Context Window in Claude Code. Native OpenAI Responses, Chat Completions, and Gemini connections use Manage models → Advanced → Confirm 1M support for this model. Follow 1M context window.
Claude Code: shared CLI configuration and advanced options#
| Group → control | Purpose | Saving, scope, or limitation |
|---|---|---|
| Reasoning and context → Extended Thinking | Adjust extended reasoning on supported models | Saves immediately; model support varies |
| Reasoning and context → 1M Context Window | Enable long context according to connection and per-model support | Experimental; account and model eligibility still apply |
| Reasoning and context → Auto-compact timing | Default, or 50%–95% in 5% steps; 70% is marked recommended | The description shows the compaction point for 200K and 1M contexts; it can only compact earlier than the default; stored as an environment variable in ~/.claude/settings.json, so claude in the terminal follows it too |
| Experimental collaboration → Agent Teams | Enable experimental CLI teams | Separate from Onevium's @Team workflow |
| Experimental collaboration → Teammate Mode | auto, in-process, and platform-dependent tmux/iterm2 | Shown when teams are enabled; affects Claude in a terminal only |
| Permissions → Permission Rules | Edit CLI permission JSON | Valid JSON plus Save; a different layer from the session selector |
| Advanced → Environment Variables | Change variables passed to Claude | Edit JSON, save, and confirm; retain unrelated fields |
| Advanced → Edit Raw JSON | Edit the whole configuration | Format, review, and save; a settings file that cannot be parsed is not overwritten |
Compacting earlier sends fewer tokens per turn but drops detail sooner; start with the recommended value and adjust from long-task results. An unchecked CLI boolean does not describe every model's underlying defaults. Configuration can contain credentials; remove them before sharing screenshots.
Browser: control, identities, and site data#
| Control | Purpose | Operation and limitation |
|---|---|---|
| AI browser control | Enable AI browser tools | Off for fresh installs; existing enabled settings remain; off does not clear site data |
| Browser to control | Built-in, External, or Auto | Built-in uses the browser inside Onevium; External controls your Chrome through the Claude in Chrome extension; Auto currently works the same as Built-in |
| External Chrome connection | Extension and connection status for external Chrome | Shown only when External is selected |
| Built-in browser settings → Default viewport | Preset dimensions for new tabs | Existing tabs can override from the toolbar menu |
| Identities → New identity / Import from a browser… | Create an identity with its own cookies, sign-ins, and network | A new identity starts empty; importing does not guarantee a site stays signed in |
| Identities → Network for this identity | Browser default, Follow system proxy, Direct, or a route | Routes are managed in Network proxy; open pages may switch on their next load |
| Identities → Make app default | Used when a conversation has not chosen an identity yet | New tabs remember the identity per conversation |
| Identities → Delete identity… | Delete the identity with its sign-ins, cookies, and saved passwords | Cannot be undone; wait if one of its tabs is running an action |
| Passwords | Logins imported from your other browsers | Encrypted with this machine's credential storage; credentials the AI uses in commands belong in Secrets and hosts |
| Browsing data → Clear browsing data | Delete cookies, cache, and site data shared by all browser tabs | Affects shared login state |
Temporary identities are created in the browser and erased when their last tab closes; they are not listed in settings. See the browser guide.
Secrets and hosts#
Manage server, database, API, and cloud account credentials that the AI can use by reference; AI use is off by default. The quick-access row at the top opens the quick window. See Secrets and SSH for item types, SSH, import, and authorization.
Network proxy: routes, app proxy, and browser default network#
In-app hints also call this page “Settings → Network”. It has three parts:
| Part → control | What to enter or choose | Effect and check |
|---|---|---|
| App proxy → Mode | Off, App Only, or Global | Covers model requests, image generation, and commands started in a new terminal; running programs, SSH, and external MCP servers are not moved. Off connects directly (a VPN on the computer still applies) |
| App proxy → Route | Choose a saved route, then Test | Shows “Saved · applied to Onevium's requests” and the exit check; with several routes, the proxy turns on only after you choose one |
| App proxy → System Proxy Status | Applied or Not Applied in Global mode | Global writes the route into the system proxy and restores your previous setting when you switch back |
| App proxy → Extra Direct Addresses (Optional) | Comma-separated domains or hosts | Local and private addresses already connect directly |
| App proxy → Check Browser Exit IP | Opens a check page in your default browser in Global mode | Verifies the system browser's exit separately |
| Browser default network → Browser default | Follow system proxy, Direct, Same as app proxy, or a route | Applies only to identities set to Browser default; Follow system proxy reads system settings and never changes them |
| Routes → Add route… | Name, protocol (HTTP/HTTPS/SOCKS5), address, port, optional username and password | Paste socks5://user:password@host:1080 to fill every field; saving a route does not turn it on |
| Routes → Edit… / Test / Delete | Use each route's “⋯” menu | A new address applies immediately wherever the route is used; replace the app proxy's route before deleting it |
Figure 2: ① status and exit check for the app proxy's route, ② a saved route's protocol, address, test result, and usage count. Isolated demonstration of the real 1.3.2 network proxy component; addresses use example domains, and the exit IP and test result are simulated. No system proxy was changed and no test was actually run.
Test scope: a test reaches an IP-check service through the route and records the exit IP, location, latency, and time that service saw. It prefers the built-in browser's network stack; otherwise it runs as an app network test and is labeled that way. It does not test Anthropic or a custom model endpoint and does not validate a model account; other sites may see a different exit.
Deleting a route used by identities or the browser default asks what they use instead: keep them disconnected until you choose, switch them to follow the default, or replace it with another route. Windows cannot store proxy credentials in system settings, and GNOME's SOCKS system proxy has no credential fields; Onevium's own requests still authenticate, while other apps may prompt separately or connect without credentials.
When you upgrade from 1.3.1 or earlier, a complete old proxy becomes a route named “host:port”; an old proxy that was on but missing a host or port is treated as off.
Worktrees#
Manage the isolated Git checkouts Onevium creates for conversations and each project's local environments, which tell Onevium how to set up a worktree. See Worktrees; you can also reach worktree cleanup from Storage → Manage worktrees.
Account and license: account and devices#
Inspect email, license status/type, start and expiry dates, and remaining days. Replacement is controlled by account eligibility. When offered, enter the new activation code, submit, then verify the updated status and dates.
The device list shows name, platform, version, and recent activity. It has no delete-device action. Signing out does not clear local conversations.
Claude subscription usage: subscription limits#
This section shows the official Claude subscription account, limit windows, and behavior analysis, with refresh or retry. Relevant limits require a Pro/Max subscription login. API keys and third-party providers may not supply this data.
Temporarily unavailable does not mean zero quota. Read local token and cost statistics in Activity separately from these subscription limits.
Activity: local usage and cost observations#
| Control | What it shows | Useful approach |
|---|---|---|
| Token activity | A yearly heatmap of daily tokens or messages, with streaks, daily peak, and longest turn | Click a day to focus the views below on it |
| Overview / Models / Sessions / Images | Totals and trend, usage by model and connection, sessions by usage, image generation attempts | Click a model or session for details |
| Time range | Today, Yesterday, 7/30/90 days, with previous and next period; 7 days by default | Narrow the range to investigate a spike |
| Connection and model filters | All connections / All models, or one of each | Identify which connection contributes usage |
| Daily usage | Tokens, Output only, or Usage records | Compare like with like |
| Cost reference and cache hit rate | Service-reported charges and current-price estimates | Unknown prices stay unpriced; not a paid invoice |
Estimated cost, cache savings, and an official invoice are different.
System permissions: status and recovery#
Each permission—Microphone, Camera, Screen and system audio, Accessibility, Automation, Files and folders, Notifications—shows its purpose and system status: Allowed by the system, Not allowed by the system, Restricted by system policy, Not requested yet, or Check in system settings. Actions include Request permission, Open system settings, and a link to the related feature; Check permissions again refreshes the status. Opening the page does not request access.
On macOS, Already enabled, but still not working? explains recovery: fully quit and reopen from Applications; if access is still denied, turn the permission off and on in System Settings, or remove the old entry and add the current app. On Windows, microphone access also depends on allowing desktop apps to use it; on Linux it depends on your desktop environment's privacy, audio, and notification settings. See settings and data for the steps.
Privacy: diagnostics and cleanup#
SDK event telemetry log is off by default. Enable it for a specific investigation, reproduce the issue, then disable it. Review session metadata before sharing logs.
Clear Local Data deletes the database and companion files, media, uploads, and images. It does not delete backups in db-backups or upgrade-backups, and it is not a way to clear CLI configuration, project files, browser identities, or voice recordings. See settings and data for locations and cleanup distinctions.
Local storage does not mean offline processing; data destinations still depend on the services you use.
Storage: usage, cleanup, and database backups#
| Control | Purpose | Notes |
|---|---|---|
| This device | Total Onevium usage by database and conversations, attachments, images and media, worktrees, previews, database backups, logs, and other data | Sizes are estimates; Refresh rescans; Storage locations shows the real folders |
| Clean up old conversations → Review | Review conversations and their sub-conversations before moving them to the trash | Restore or permanently delete trash in Archived sessions |
| Manage worktrees | Opens Worktrees | Choose how many old worktrees to keep |
| Clear rebuildable previews → Review cleanup | Delete cached image previews | Original images, attachments, and logs are kept |
| Database backups → Back up now | Create a consistent snapshot | Works while you use Onevium; manual backups are not limited by the copies-to-keep setting |
| Database backups → Automatic database backup | Every day or every week, backup time, and automatic copies to keep (1–100) | Off by default; when enabled it starts at every day, 03:00, keeping 7; click Save schedule; a missed backup runs at the next launch |
| Backup history / Backup location | Download a backup or see its folder | db-backups in the data directory by default |
The Storage page never deletes an active database or compacts it automatically; deleted records may leave reusable space inside the database.
Archived sessions: restore or permanently delete#
Use search, project, and date filters to find a conversation. Preview it before restoring or deleting. After restoration, check the content in its project. Bulk actions are supported; Delete all applies to the filtered results.
Permanent deletion removes the selected conversations and messages and cannot be undone. Practice with a demo conversation rather than real history.
If an option is missing#
- Check the applicable version at the top of this page and whether the relevant feature is enabled. Account and license appears only in builds that require sign-in.
- Platform-specific options appear only where supported; inspect the settings on the device where you will run the task.
- CLI Agent Teams and the 1M context option remain experimental and depend on model, account, or platform support even when a control is visible.
- After upgrading from 1.3.1: an incomplete old proxy is treated as off, ⌥⌘K/⌥⌘T are no longer bound by default, memory calls count their actual cost, and 1.3.1 cannot read the upgraded data.
- After changing a setting, verify it with the relevant message, notification, browser action, or recording.
Next steps#
Return to settings and data for common adjustments, use permissions to choose execution controls, or follow workflow tips.