Settings
Every settings section, what it controls, and where its choices are saved.
Open Settings at the foot of the sidebar's rail, or choose Settings in the command palette (⌘K). The sidebar then lists the sections, under Back to app. With the sidebar hidden, the section's title at the top of the page is a menu of every section.
Most choices save as soon as you make them, and the page shows Saving… and then Saved. If a save fails, the page says Could not save. Your change is still here. and offers Retry save.
Usage
Cost and Tokens show recorded activity for this OpenOrc installation. Filter by agent and choose the past 24 hours, 7 days, 30 days, or 90 days. The chart shows the trend; the table breaks it down by model or day. Costs are API estimates, including on subscription plans. Codex estimates use recorded tokens and published model prices, including cached-input discounts and recorded Fast mode; other agents supply their own estimates. Unknown prices stay unavailable.
Limits lists your enabled agents and Claude accounts, named such as Claude · Work. Codex, Claude Code, and signed-in Antigravity accounts report allowances; other agents link to their provider's usage page. An Anthropic API card joins them when you choose or save an Anthropic API key under Memory & models. The usage ring on the sidebar's rail shows the same numbers for the account your next message would use.
| Part | What it shows or does |
|---|---|
| Status | Usage reported, Limit reached, Stale report, Disconnected, Metrics unavailable, or Refresh failed. |
| Limits | Each limit the provider reports, as the percentage left, with its reset time. |
| Refresh button | Asks for a new report. OpenOrc also asks again when you come back from the provider's page. |
| Open usage | Opens the provider's usage page in your browser. The Anthropic API report has Open Console instead. |
| Details | Turns the card over to show where the report came from, when it arrived, how many runs this device has made with the agent, and any resets the account has. |
| Resets | For Codex, how many resets your account has. Use reset asks you to confirm, then spends one. |
fx reports AI Gateway balances and budgets, or Codex and Grok plan allowances, through its native usage commands. A balance without a defined budget shows an amount instead of a percentage. Custom fx connections use their provider's dashboard.
OpenCode, Oh My Pi, and Pi bill their configured model providers. Their account limits stay on those providers' dashboards. Cursor links to its own dashboard; Antigravity API-key usage links to Google AI Studio.
Connections
Connections lists the coding agents, your Claude accounts, and the GitHub tools OpenOrc found on this computer. Refresh connections checks each agent again, so it picks up an agent you just installed or signed in to.
Coding agents
Enable the agents you want to use. Enabled agents appear in model pickers and can start work. Turning one off keeps its conversation history but removes it from choices for new work. Add agents lists the others; choose Enable to bring one back. See all eight supported agents.
| Part | What it shows or does |
|---|---|
| Status | Connected, Not logged in, Not installed, Fails to start (found, but its version check failed), or Connection check failed. |
| Version | The installed version and how it was installed. Installation location shows the path. |
| Sign-in hint | For an agent that is installed but signed out: Connect in a terminal shows its own sign-in command. Agents that accept API keys also use keys from their native configuration or launch environment. |
| Install button | For an agent that is not installed, its install button opens that agent's setup guide. |
| Check for updates | Looks for newer agent versions now. Update all installs supported updates for enabled agents, and each row has its own button, such as Update Claude. A broken installation shows a reinstall button when its package manager can repair it, such as Reinstall Codex. When OpenOrc can't update an agent itself, the row links to instructions instead. |
| Check for agent updates automatically | On by default. Checks every six hours while OpenOrc is open, asking npm, Homebrew, or the agent's official release service for public version numbers. Nothing installs until you press a button. |
Agents keep working during an update. Each conversation moves to the new version on its next message. Stop on an agent's row ends the update that is running.
All eight agents support in-app updates through recognized installers. This includes Oh My Pi's stable Homebrew tap, Pi's npm installation, and the native installers for Cursor, Antigravity, and fx. OpenOrc keeps the installation's package manager and release channel. Pinned or custom installations show an explanation when an update needs to be done in a terminal.
Claude accounts
Each Claude account has a row with its name, email, status, and buttons such as Make default, Sign in again, and Disable. Your existing Claude Code login is listed as Existing CLI login. To add one, type a name and click Add account and sign in. The default account is the one new threads start with. Refresh accounts checks each sign-in again. See Use several Claude accounts.
GitHub
| Setting | What it does |
|---|---|
| GitHub CLI | Shows whether gh is installed. OpenOrc needs it to create and browse pull requests. Without it, pushing still works, and OpenOrc opens GitHub's compare page instead of creating the pull request. |
| Reviewer app | Set up creates a GitHub App on your account, so reviews you post from OpenOrc appear as a bot instead of as you. Then Choose repositories picks where it can review. |
| Let it approve | Off by default. Lets the app approve pull requests. Its approval can count toward required reviews, including on your own pull requests. |
Remove forgets the reviewer app and its key on this computer. The app stays on GitHub until you delete it there.
Cloud
Cloud connects the Vercel or Agent37 account that cloud threads and the cloud brain run on, and the sign-ins agents use there. See Cloud threads.
| Setting | What it does |
|---|---|
| Sign-ins for the cloud | Each sign-in the cloud can use, ready or how it gets ready. Bring them brings the missing ones, and asks before it copies a key from this computer. |
| Vercel | Connects an access token, then the Team that sandboxes run in, the Sandbox size, and the Sandbox region. Disconnect forgets the token. |
| Agent37 | Connects an API key, then the Instance size for new cloud threads. Disconnect forgets the key. |
| New cloud threads | With both services connected, Run on picks where new cloud threads go. |
| Claude accounts | A token for each Claude account to sign in with in sandboxes. Create token runs claude setup-token with that account's sign-in, and Paste token takes one you made. |
| Codex | Codex's sign-in for sandboxes. Sign in with ChatGPT makes one separate from this computer's login, or Use an API key. |
| OpenCode | Provider keys for OpenCode and Oh My Pi in sandboxes. Add a key adds one. |
| Cloud brain | Once a service is connected, sets up the cloud brain, pairs phones with it, chooses its projects and sign-ins, moves it to the other service, and removes it. This month shows what it cost. |
| Carry working threads on in the cloud, under When this Mac sleeps | Off by default. While it is on, a worktree thread's turn carries on in a sandbox when this computer goes to sleep. |
| Sandboxes | Every sandbox OpenOrc made, whether it is awake, its size, and what it has cost on Vercel. Remove deletes one. |
| Check | Run check tries everything a cloud thread needs in a throwaway sandbox, then deletes it. |
Slack
Slack connects a Slack bot to this computer, so you can mention it in a channel and an agent here replies. Connect Slack picks the kind of connection: Personal bot · no server needed or Shared relay · advanced. The setup steps are on Slack.
| Setting | What it does |
|---|---|
| Bot token, App token | The two tokens from your Slack app, starting with xoxb- and xapp-. Leave a saved token blank to keep it. |
| Your Slack member ID | Only requests and approvals from this Slack member control your computer. |
| Workspace entrypoint | The folder where Slack requests look for projects, besides your imported projects. It is also where Workspace threads work unless you pick another folder. Choose folder changes it. |
| Default coding agent, Default model | What new Slack conversations use. Codex is the default agent. Leave the model blank for the agent's default; you can ask for another model in Slack. |
| Mode | Applies to every Slack turn, including existing threads. A stricter mode set on a conversation always wins. The default is the level that asks before changes: Review everything, which Codex calls Review changes. |
Connect and check saves these and connects. While Slack is connected, the fields are locked; Disconnect Slack unlocks them. The shared relay has the same defaults under This computer, plus a relay address and a device key from the person who hosts it.
Phone
Phone lets the OpenOrc iPhone app reach this computer. See Phone app.
| Setting | What it does |
|---|---|
| Allow paired phones | Off by default. While it is on, this computer listens for paired phones on your local network and tailnet. Addresses lists where, marked Same network or Tailscale. |
| Pair a phone | Shows a pairing code to scan with the phone, valid for five minutes. Copy link copies the same code as a link. |
| Paired phones | Each phone with Connected or when it was last seen. Remove unpairs it. |
| Apple push key, under Notifications | The key this computer signs phone notifications with. Phones get notifications only from a computer that has one. |
Skills
Skills lists the skills each agent can use in a project. It only reads them; nothing here changes or runs a skill.
- Project chooses which project's skills you see. Each agent also has personal and plugin skills that apply in every project.
- The agent buttons switch between your enabled agents and show how many skills each one has.
- Skills are grouped as Project skills, Your skills, Plugin skills, and Built-in skills. Open one to see its location.
- Search skills filters by name, description, or path. Refresh skills reads the folders again.
Use $name for Codex or fx, /name for Claude Code, Cursor, or Antigravity, and /skill:name for Pi or Oh My Pi. OpenCode loads skills with its own skill tool, so ask it to use one by name. See Skills.
Devices
Devices sets up iOS simulators and Android emulators in the side panel. See Simulators and emulators.
| Setting | What it does | Default |
|---|---|---|
| Device support | Installs and starts the tools that run devices in the Device tab. When something is missing, such as Node.js 22.12 or Xcode, the switch says what. Turning it off stops the tools and leaves running devices on. | Off |
| Agents can use devices | Lets agents list, open, and drive devices. | On |
| Installed tools | The installed version of each tool, and the version it updates to. |
Appearance
| Setting | What it does | Default |
|---|---|---|
| Color appearance | System, Light, or Dark. | System |
| Accent colors | A ready-made set (Rose & sage, Ocean, Plum & amber, Graphite), or your own colors for Actions, Navigation, and Content. | Palette default |
| Palette | The colors of the whole workspace. Every palette has a light and a dark version. | OpenOrc |
| Font | The typeface across the app: Immaculate Gothic, Inter, Geist, or System. Code stays monospaced. | Immaculate Gothic |
| Code font | The monospace typeface for code blocks, diffs, and terminals: JetBrains Mono, Geist Mono, or System monospace. A preview shows your choice, independently of the interface font. | JetBrains Mono |
| Transparent surroundings | Lets the desktop show through the sidebar and outer rails, blurred. Needs macOS, or Windows 11 22H2 or later. | Off |
| Transparency | How much of the desktop shows through, from 0 to 100%. | 35% |
| Fine-tune individual colors | Changes any single color of the palette you picked. Reset all undoes your changes. | No changes |
Light and dark keep separate color choices. The command palette also has Theme: light, Theme: dark, and Theme: system.
General
| Setting | What it does | Default |
|---|---|---|
| Desktop notifications | Notifies you when a thread finishes, asks a question, needs an approval, or fails while you are looking at something else. | On |
| Notification sound | Plays a sound with each desktop notification. | Off |
| Check for updates automatically | Checks for a new OpenOrc release shortly after launch and every six hours, then shows a notice. Nothing downloads until you choose to. With it off, use the update button above Settings on the sidebar's rail, orCheck for updates… in the OpenOrc menu on macOS or the Help menu on Windows. Linux releases don't update themselves. | On |
| New thread workspace | Where new threads work: Local checkout or Isolated worktree. A task created in a conversation uses that conversation's workspace instead. | Local checkout |
| Close idle processes after | How long an agent process may wait between turns before OpenOrc closes it: Keep running, 5, 10, or 30 minutes, or 1 hour. The session resumes with your next message. | 10 minutes |
| Your Claude Code MCP servers | Lets Claude Code connect the MCP servers from your own Claude Code configuration. They load only in Autonomous; the other modes connect only OpenOrc's tools. A slow server can miss the first message. | On |
Memory & models
This section turns project memory on or off and chooses the small models OpenOrc uses in the background. See Project memory.
| Setting | What it does | Default |
|---|---|---|
| OpenOrc memory | Lets agents save and recall knowledge across conversations, in every project. Turning it off keeps saved memories for you to review. | Off |
| Provider, under Learn from completed runs | Which model summarizes a finished run into memories: Automatic · per agent uses the agent that did the work; Codex subscription or Claude Code subscription summarizes every run; Anthropic API key bills a key you enter; Off · no background learning runs no extra model. | Automatic · per agent |
| Model | Shown when you choose a subscription or the API key. Default names the model OpenOrc picks for it. | Default |
| Harness, under Text generation | Which agent names new threads and explains code. Automatic · per conversation uses a small model from the conversation's own agent; choosing an available harness uses it every time; Off · use opening message keeps the first line of your message and turns explanations off. | Automatic · per conversation |
| Model, under Text generation | Shown when you choose a harness. Use low-cost default goes back to its small model; a larger one can cost more. | Low-cost default |
Background text generation supports Codex, Claude Code, OpenCode, and Oh My Pi. In Automatic, other agents keep the opening message as the thread title and cannot explain code. Choose a supported harness to enable those features for every conversation.
Learning is paused while OpenOrc memory is off. With memory on and the provider set to Off, agents can still save memories themselves.
Data
Data shows the path of the Data folder, where OpenOrc keeps its database, memories, and worktrees, and how much space the worktrees take, with Clean up… to remove the ones you no longer need (see Remove a worktree). Below it, How your data is used summarizes where requests go: memory search runs on this device, each agent's requests go to its own provider, and background models use the same agent unless you chose another under Memory & models. Data and storage lists everything in the folder.
Where settings are saved
| Settings | Saved in |
|---|---|
| General (except updates), Memory & models (except the API key), automatic agent update checks, the reviewer app and Let it approve, the Workspace entrypoint, Claude accounts, phone access and paired phones, Devices | The settings table of openorc.sqlite, in the data folder |
| Cloud connections and choices, including Carry working threads on in the cloud | cloud-credentials.enc, encrypted |
| Sign-ins for the cloud, and the cloud brain's key | claude-cloud-tokens.enc, codex-cloud-login.enc, opencode-cloud-keys.enc, and cloud-brain.enc, encrypted |
| Check for updates automatically | updates.json in the data folder, because the main process reads it before the core starts |
| Slack tokens and Slack settings | slack-secrets.enc, encrypted |
| The Anthropic API key | memory-extraction-key.enc, encrypted |
| The reviewer app's private key | github-reviewer-app.enc, encrypted |
| This computer's key for phone connections | remote-access-key.enc, encrypted |
| The Apple push key | apns-key.enc, encrypted |
| Appearance | The app window's local storage, under keys such as openorc.theme and openorc.palette. The palette and colors are also copied to the settings table, so a paired phone uses the same look. |
The encrypted files use your system's protected storage: the macOS Keychain, Windows DPAPI, or the Secret Service or KWallet on Linux. Settings show whether a token or key is saved, never its value.
Source: apps/desktop/src/renderer/src/views/Settings.tsx and settings-*.tsx, packages/core/src/services/settings.ts, apps/desktop/src/main/protected-secrets.ts, update-preferences.ts
Next steps
Checked against OpenOrc's source on November 9, 2026.