App settings

Find settings for models, permissions, appearance, browser previews, and project tools.

Click the gear icon in the sidebar to open Settings. For a first setup, connect a model in Connections, choose an access mode in Permissions, and leave the other settings alone until you need them.

Most settings apply across the app. Sections with a project picker let you inspect a particular project without switching your current conversation. Check the selected project before changing an override.

Active sections

Agents and permissions

Start with Settings > Permissions > Default access mode > Ask for Approval if you want to review protected actions. This is not a read-only mode. See Approvals and permissions before granting wider access.

Selected project sets a project-specific mode. Use default removes that override. Saved approvals lists permissions you kept for the selected project; Revoke stops their future use but does not undo completed work.

In Settings > Agents, Agent-created Workers allows agents to create other sessions to share a task. A Worker is another conversation with its own work and tool activity. See Hives and sessions before enabling parallel work.

• Workers per parent defaults to 4 active direct Worker runs per parent session.
• Active agent runs defaults to 16 across independent sessions and Hives.

A run is one period of agent work, not a saved conversation. Saved sessions, queued follow-ups, searches, waits, and exports do not consume these run slots. Reaching a limit rejects a new run with a retryable error rather than hiding it in a queue. You can raise the limits, but more simultaneous runs may strain your machine or provider quota.

Project configuration can override the project-specific controls. If an older version saved project overrides, Saved project overrides lets you inspect and clear them. Clearing a saved value does not remove an override in a project file.

Below the controls, select a project to read its agent definitions or enable and disable them for new sessions. There are no bundled roles or built-in definition editor. Edit the Markdown files in your project; see Agent definitions. Skills has its own project picker and browser.

General

Open web links in chooses whether links open in OpenWaggle or your external browser.

Context compaction controls when OpenWaggle reduces the older context sent to a model so a long conversation can continue. Automatic compaction threshold defaults to 80% of the model’s context capacity. It applies across models, projects, and sessions. The model’s capabilities determine whether this uses native compaction or a portable summary; there is no provider-specific switch.

About & Updates shows your installed version and update channel. Stable is the default. Beta also accepts release candidate and Stable releases; Alpha accepts Alpha, Beta, release candidate, and Stable releases. Entering Alpha requires confirmation. Changing the channel saves it and immediately checks for an eligible update, but never authorizes a downgrade.

Use Check now to check again. A downloaded update installs only when you choose Restart to update. OpenWaggle rechecks that it is still eligible for your channel before restarting; ordinary app exit does not install it. The app and openwaggle update share the channel setting.

After Restart to update, the update shows as installing while OpenWaggle stops its background Session Host and quits. It reopens on its own once the update is installed, usually within a few seconds; opening it yourself before then makes the install fail. On macOS an update cannot install while another OpenWaggle process is still running, such as openwaggle mcp serve used by another agent or openwaggle sessions wait in a terminal. If an update did not install, OpenWaggle says why once that update is ready to install again, shortly after it next opens; close the other process and choose Restart to update again.

Share anonymous usage statistics and error reports, below the update channel, is on by default in released builds. Turning it off stops both and deletes statistics that have not been sent yet. What is sent opens Usage statistics and error reports, which lists every field and the other ways to turn them off.

Command-line availability

The CLI ships with the app. Packaged macOS and Linux launches install or refresh ~/.local/bin/openwaggle; the Windows installer provides the command. Ensure the install directory is on your shell’s PATH.

General shows a read-only warning if the command is missing, outdated, blocked by another file, or not on PATH. There are no CLI installation controls here. OpenWaggle does not replace an unrelated file at the command path; resolve that conflict yourself. An exact legacy macOS link to the app still works, but rerun the installer if you move the app. From source, use pnpm cli:dev -- <command>.

Appearance

Use Settings > Appearance to adjust readability without changing your code:

• Choose syntax themes and accessibility profiles using the preview.
• Adjust terminal colors and typography.
• Set Diff layout to Unified or Side by side.
• Enable Wrap long lines to avoid horizontal scrolling in diffs.
• Enable Reduce motion to minimize animation instead of following the operating system’s preference.

Diff layout and line wrapping are shared with the diff panel’s own controls. These appearance choices apply across projects, not through a project settings file.

Browser

In Settings > Browser, use Let agents open and drive the preview browser to control agent access. Turning this off withholds browser tools from the agent. It is separate from where links open.

New preview tabs use selects a browser profile. Persistent profiles keep cookies and site data; Incognito uses memory only. Review what an imported login allows before giving an agent access to that profile.

Preview defaults include Viewport, Zoom, Appearance, Recording, and Show agent-opened previews. See Browser preview for using a preview during development and Security and privacy for its limits.

Project actions and shortcuts

Use Settings > Project actions to save commands such as tests and builds, or a dev server that keeps running. Choose a discovered project script or enter a custom command. New definitions are saved for Just me in that project by default; Everyone working on this project saves a shareable .openwaggle/actions.json file.

Launch actions from Project Actions on the right panel rail. They run in that session’s workspace, which may be a separate worktree. Inspect output, stop or restart a run, and open its ready preview from the Project Actions panel or Session Summary. A running action shows Stop, Restart and its output instead of starting another copy.

The separate Workspace preparation section configures setup and cleanup for preparation profiles. Enabled setup must finish before the first agent turn in a new managed worktree. Existing checkouts only run it when you choose Run setup. Shared preparation commands need local review and enablement. See Project actions for the full workflow.

Use Settings > Shortcuts for both app keyboard bindings and Project Action bindings. Add binding lets you choose either kind of command. Review overlap warnings when assigning a shortcut already used elsewhere.

Worktrees

Session environment mode sets the default for new sessions:

• Current checkout edits the project folder you opened. This is the shipped default.
• New worktree creates a separate Git checkout for the session.

You can choose a different mode before a session’s first message. See Git integration.

The Worktrees list includes every worktree of the opened repository, even ones created outside OpenWaggle. The main checkout is marked (main) and cannot be removed here. Use Refresh to reload the list or Remove on a linked worktree. Normal removal refuses uncommitted changes or locks.

If configured cleanup fails, the worktree stays in the list with its output and Retry cleanup controls. Delete anyway skips cleanup, which may leave external resources behind. Force remove also permits removal of dirty or locked worktrees and can discard uncommitted work. Preserve anything you need before using it.

Connections

Expand API Key Providers to save a key or OAuth Providers to sign in through a browser. Under Available Models, enable the models you want beside the message box. The selector shows models that are both enabled and available through their provider.

Title model chooses the model that writes session titles:

A provider that a project’s Pi extension adds is not available for titles. Sessions on such a model keep their opening message as the title unless you choose a specific Title model.

See Providers and models for the full setup.

MCP

MCP connects the agent to tools and services outside its built-in file and command tools. It starts globally off. In Settings > MCP, review each server’s definition and requested access before trusting or enabling it.

Activation can differ by session and project. Changes during agent work may remain pending until the turn finishes. Turning a server off does not prove a job already submitted to a remote service has stopped. See Model Context Protocol for setup, credentials, and cancellation limits.

Archived items

Restore archived sessions and conversation branches here, or permanently delete an archived session. Archived branches are hidden from normal sidebar navigation but remain marked in the full Session Tree. Deleting individual branches is not currently available.

Data storage

For repository-specific resources and advanced runtime options, see Per-project configuration.

OpenWaggle stores app settings and session records under its application-data directory. The active session database is session-host/session-host.sqlite. If an older database was migrated, use the explicit Session recovery commands to inspect or restore its recovery copy.

Other files have separate locations:

Credentials may also come from environment variables or custom provider configuration. Do not treat the session database as a complete backup of credentials or project files.

Managed worktrees live outside your project at ~/.openwaggle/worktrees/<repository>/<workspaceId>. New workspace branches use ow/session-<workspaceId>; sessions that share a workspace use the same checkout. Existing worktrees retain their recorded names. Check Session Summary > Environment for the actual path and branch rather than deriving them from a session ID.

Sidebar sort order, collapsed projects, and the Pinned section’s sort are remembered between launches. Pinned sessions and their dragged order are stored with app data. Text filters and state chips are not remembered, so an old filter does not keep hiding sessions.

Logs

The error display can open the logs directory when agent work fails. Review logs for secrets and private project details before sharing them.