Skip to content
OpenWaggle

Settings reference

Every setting in the Settings window, with its values and default.

This page lists every setting in the Settings window, section by section, in the order the sidebar lists them. To open Settings, click the gear icon in the sidebar. For what each section is for and the changes people make most, see Settings.

Settings apply to the whole app unless the table says otherwise. A section with a project picker shows one project at a time. Picking a project there does not switch your conversation to it.

General

SettingValuesDefaultWhat it does
Open web links inSystem browser, OpenWaggleSystem browserWhere web links open. Terminal links and detected local ports use it too.
Automatic compaction threshold1 to 100 %80 %Compacts before the next model request once context reaches this share of the model’s window.
Pi sessionsAsk, OpenWaggle, pi (per project)AskWhat happens when you send in a session the pi CLI used last. Kept in your app settings, not in the project.
CodemodeOn, offOn, or your Pi defaultToolsLets the agent write a short script that calls several tools in one step.
Keep prompt caches warmOff, While working, Between runsWhile working, or your Pi cacheWarmingWhen Pi resends the conversation so the provider keeps it cached.
Update channelStable, Beta, AlphaThe build’s own channelWhich releases the app and openwaggle update install. Choosing Alpha asks you to confirm.
Share anonymous usage statistics and error reportsOn, offOn in released buildsSends anonymous usage statistics and error reports. Off deletes statistics not yet sent.

Automatic compaction also runs by 400,000 tokens at the latest, whatever the percentage.

Version shows the installed version. Latest version shows the update status, with Check now and, once an update has downloaded, Restart to update.

Until you choose a channel, a Stable build follows Stable, an Alpha or Beta build follows its own channel, and a release candidate follows Beta.

Until you change Codemode or Keep prompt caches warm here, each follows your own Pi setting in ~/.pi/agent/settings.json when you have set it, and the default above otherwise. Once you choose here, your OpenWaggle choice wins. OpenWaggle never writes either value to Pi’s files.

Pi valueLabel
offOff
streamingWhile working
idleBetween runs

The usage statistics switch is off and locked in a Dev build, during an automated test launch, and when DO_NOT_TRACK, PI_TELEMETRY or CI turns statistics off. See Usage statistics and error reports.

Browser

SettingValuesDefaultWhat it does
Let agents open and drive the preview browserOn, offOnOff withholds the browser tools and their instructions from agents. Your own browser panel still works.
New preview tabs useAny browser profileDefaultThe profile a new preview tab opens with. You can change it per tab.
ViewportFill available space, or a device sizeFill available spaceThe device size of a new tab.
Zoom25 % to 500 %100 %The page zoom of a new tab.
AppearanceSystem, Light, DarkSystemThe color scheme pages see in their media queries.
Recording30 FPS, 60 FPS30 FPSFrames per second for preview recordings.
Show agent-opened previewsOn, offOnShows a floating preview when an agent opens one without saying where.

The zoom steps are 25, 33, 50, 67, 75, 80, 90, 100, 110, 125, 150, 175, 200, 250, 300, 400 and 500 %.

Profiles lists the built-in Default and Incognito profiles and the ones you add. Default and your own profiles keep logins and site data. OpenWaggle clears Incognito when it quits. You can add up to 24 profiles, each with a name of up to 48 characters. Import from copies cookies from a browser installed on your computer into a profile. See Browser preview.

Project actions

This section has a project picker. It lists the project’s saved actions and the Workspace preparation setup and cleanup for worktrees OpenWaggle creates. OpenWaggle saves a new action for Just me unless you choose Everyone working on this project, which saves it in .openwaggle/actions.json. See Project actions.

Shortcuts

Lists every keyboard command and project action shortcut, with search, Add binding and Reset defaults. The Panels group holds a shortcut for each right panel view. For the default keys and how bindings combine, see Keyboard shortcuts.

Appearance

SettingValuesDefaultWhat it does
Color and syntaxA theme for each of Light, Dark, High Contrast Light and High Contrast DarkLight+, Dark+, GitHub Light High Contrast, GitHub Dark High ContrastCode colors in the editor, Markdown, diffs, search and data views.
Terminal colorsA color for Background, Foreground, Cursor, Selection and ScrollbarThe active syntax theme’s colorsTerminal-only colors. Reset to theme removes your changes.
Interface fontA font from the list, or a CSS font stackSystem UINavigation and controls.
Documents fontA font from the list, or a CSS font stackSystem UIChat and Markdown.
Code fontA font from the list, or a CSS font stackSystem monospaceCode.
Terminal fontA font from the list, or a CSS font stackFollows the Code fontThe built-in terminal.
Interface scale85 to 125 %, in steps of 5100 %The size of the whole interface.
Document text12 to 22 px14 pxChat and Markdown text size.
Code text10 to 24 px12 pxCode text size.
Document spacing120 to 200 %, in steps of 5150 %Line height of chat and Markdown text.
Code line height14 to 36 px, and at least 2 px more than the code text20 pxLine height of code.
Terminal text10 to 24 px14 pxTerminal text size.
Code ligaturesOn, offOffUses programming ligatures when the font has them.
Terminal follows Code fontOn, offOnKeeps the terminal font the same as the Code font.
When the panel is closedKeep rail visible, Hide railKeep rail visibleWhether the panel rail stays on the right edge while the right panel is closed.
Diff layoutUnified, Side by sideUnifiedOne column, or old and new side by side.
Wrap long linesOn, offOffWraps long diff lines instead of scrolling sideways.
Reduce motionOn, offOff, following the operating systemOn always keeps animation to a minimum.

Import in Color and syntax adds VS Code JSON or JSONC themes, TextMate themes and grammars, VS Code extensions, and OpenWaggle theme packages. Reset in Typography puts every font and size back to its default. A custom font stack can be up to 240 characters. Diff layout and Wrap long lines also change from the diff panel’s own controls. Appearance choices apply in every project. OpenWaggle does not read them from project files.

Waggle Mode

SettingValuesDefaultWhat it does
PresetA built-in or saved presetNone loadedLoads two agents and their settings. Save Changes and New Custom Preset save to a presets file.
Agent A, Agent BA name, a model and a role description eachNamed Agent A and Agent B, using the session’s modelThe two agents that take turns.
Stop whenConsensus, ManualConsensusWhether the agents stop once they agree, or only when you stop them.
Max turns4 to 208The most turns before Waggle stops.

See Waggle.

Extensions

Lists your OpenWaggle and Pi extension packages, with controls to review, enable, update, disable and remove them. See Extensions.

Skills

Has a project picker. Lists the skills found in the project’s .openwaggle/skills and .agents/skills folders, with a switch to turn each one off for that project. See Skills.

Agents

SettingValuesDefaultWhat it does
Agent-created WorkersOn, offOnLets agents start worker sessions to share a task.
Workers per parent1 or more4The most runs active at once by one parent session’s direct workers.
Active Workers1 or more16The most worker runs active at once across the app, in every Hive, counting sessions agents launch, create or fork and runs agents start in your sessions.

Both limits apply to agents’ work only. Your runs in sessions you made never count toward them, and a message you send, a new session and a reply to a Queen are never refused because of them. OpenWaggle refuses a new worker run that would pass either limit, with an error the agent can retry. It does not queue the run. A run OpenWaggle starts for a parent whose workers reported is the exception and is retried when another run ends, as the Hive reference describes. Saved sessions, queued follow-ups, searches, waits and exports do not count toward the limits. A project’s .openwaggle/settings.json can set its own Agent-created Workers and Workers per parent, and the file wins.

Saved project overrides appears only when an older version saved per-project values. Clear saved value removes one. It does not change a project file.

Below the limits, pick a project to read its agent definitions and turn each one on or off for new sessions. See Agent definitions.

Scheduled tasks

Lists scheduled tasks for All projects or one project. See Scheduled tasks.

Permissions

SettingValuesDefaultWhat it does
Default access modeYOLO (Full Access), Ask for ApprovalYOLO (Full Access)The access mode of every project and session that has not chosen its own.
Selected projectUse default, YOLO (Full Access), Ask for ApprovalUse defaultThe access mode of the project chosen in the picker. Saved in the project’s .openwaggle/settings.json.
Saved approvalsA list, with Revoke on eachEmptyThe approvals you kept with Always allow for the selected project.

In .openwaggle/settings.json, the modes are yolo and ask-for-approval. See Approvals and permissions.

MCP

Lists your MCP servers with controls to add, turn off, sign in to and inspect them, and to choose how the agent reaches their tools. See MCP connections.

Worktrees

SettingValuesDefaultWhat it does
New Sessions run inCurrent checkout, A new worktreeCurrent checkoutWhere a new session works. You can change it before the session’s first message.
Remove worktrees of archived Sessions automaticallyOn, offOffRemoves a worktree once every session in it has been archived long enough.
After archiving for7, 14, 30, 60 or 90 days30 daysHow long every session in a worktree must stay archived before OpenWaggle removes it.

The rest of the section lists the worktrees of every project in three groups, Safe to remove, Needs a decision and In use, with the space each would free. See App settings.

Archived items

Lists archived sessions and branches, with Search, filters for Project, Archived date and Type, and Sort. You can restore or open each item, and delete archived sessions for good. You can select up to 1,000 matches at once. See App settings.

Connections

SettingValuesDefaultWhat it does
API Key ProvidersA key per provider, with Test, Save and ClearNoneSaves a provider’s API key through Pi.
OAuth ProvidersA switch per providerOffSigns in to a provider in your browser.
Source controlHosts, each with a provider and accountsNoneWhich hosts use GitHub or GitLab, through the gh and glab CLIs. Add host… adds one.
Open pull and merge requests inOpenWaggle, Provider websiteOpenWaggleWhere a click on a pull or merge request opens. Cmd or Ctrl-click opens the other one.
Available ModelsA checkbox per modelNoneWhich models appear in the model selector.
Provider RestrictionsPer provider: Inherited, Allowed, Blocked; scopes with an “only” toggleAll providers allowedWhich providers each project’s sessions may use. The app-wide scope covers every project; a folder scope covers every project inside it. See Per-project configuration.
Title modelAutomatic, Off, or any enabled modelAutomaticWhich model writes session titles.

A key test sends one short prompt and gives up after 15 seconds. See API keys and Browser sign-in. For source control hosts and accounts, see Pull and merge requests.

Title model choiceWhat happens
AutomaticThe cheapest available model from each session’s own provider and model family writes its title, with the same sign-in and region.
A modelThat model writes every title.
OffOpenWaggle generates no titles. Sessions keep their opening message as the title, and Regenerate title is hidden.

When you pick a model, each session’s opening message and each worker’s task go to that model’s provider, and so does up to about 8,000 characters of the conversation when a title is refined or regenerated. If the model fails, OpenWaggle tries the session’s own model.

Titles use the models of each session’s project, so a provider or virtual model that a project’s Pi extension adds can write titles for that project’s sessions.