Skip to main content

Settings and maintenance

Saggar's defaults favor a quiet, recoverable workspace. Settings lets you change how it looks, what earns your attention, how long terminal state stays on disk, and which integrations may edit files outside the app.

Finding a setting

Open Settings with ⌘,. Its sidebar is searchable, including words that do not appear in a pane title: “hooks” finds Providers, “scrollback” finds Sessions, and “split pane” finds Interface. The panes are grouped as App, Workspace, Agents, and Access.

Appearance

A theme family pairs a light and dark palette with a window material. Saggar can follow macOS automatically or stay on either appearance. The ceramic families may add a photographic texture and slow palette-colored light drift; turn Show image backgrounds off to keep the same palette on a plain surface. Custom mode lets you choose the light and dark palettes independently.

App text and terminal text have separate sizes. The app control scales Saggar's menu, cards, panes, and palette; macOS still draws standard controls and menus at the system size. Terminal settings choose any installed fixed-width font, set a separate point size, and decide whether the terminal canvas follows the app's appearance or stays dark for tools whose dim colors assume a dark background.

Open Appearance settings

Use Option as Meta

Interface

Monitor settings choose the default card size, whether new monitors start collapsed, and whether idle monitors fade until hovered or needed. The discreet project menu does the same for the left side of the main window. Quick runs may start tucked into their project row.

Monitors follow their project. Quick runs and split panes do too by default: leave a project and they hide, then return when you come back. Interface settings can keep either one visible across project changes when your workflow needs a fixed companion.

Notifications, sound, and watch patterns

Notification Center banners, command-completion notices, menu reordering, program-raised notifications, sounds, and trackpad feedback each have their own controls. Each sound can be changed or previewed, and sound effects can be limited to the time Saggar is in the background.

Programs inside a terminal can raise titled notifications through OSC 99 or OSC 777, including over SSH and from containers. Urgent messages make the session need you. Watch patterns add your own plain-text or regular-expression cues to the same vocabulary, which is useful for log tails and test watchers. The optional away summary collects what finished, failed, waited, or stayed dirty while you were gone into one card when you return.

Projects and sessions

Projects settings choose the default editor, control smart collapsing, and manage the folders Saggar scans for Git repositories. Scanning walks a few levels beneath each root and stores the list in ~/.saggar/config.json.

Session presets

A session preset is a saved way to start a session you use everywhere. Presets have their own Session presets pane. Give one a readable name, then choose what opens it: your shell, or one of your configured agents and models. A shell preset's opening task is the full command, including the flags you otherwise type from memory; an agent preset can also set reasoning effort, custom context, and an opening task. Saggar adds it to the ＋ Session menu and the command palette for every project.

The Sessions settings pane with a Claude command being saved and a lazygit session preset enabled

Opening a shell preset creates a normal shell in the current project, then types the saved command at its prompt. Your aliases, shell functions, PATH, and startup files still apply. Turn a definition off to hide it from launch menus without deleting it.

Useful definitions include:

  • an agent with your usual model and flags, such as claude --model opus --verbose;

  • a terminal UI you reach for in many repositories, such as lazygit, or a local dashboard such as docker compose top;

  • a familiar shell setup, such as tmux new-session -A -s work.

Keep project-specific dev servers, test watchers, and startup sets in project commands. Those definitions belong to the repository and travel with it; session presets belong to you and are available everywhere.

Sessions settings enable OSC 133 shell integration for exact command boundaries and exit codes, choose the live scrollback depth, and control paste, close, and quit warnings. A timed tidy can close sessions that have gone quiet, but it protects waiting prompts, live commands and processes, failures, and every session currently shown in a pane, monitor, or separate window.

Open Sessions settings

Keep 10,000 lines of scrollback

Scrollback restoration stores snapshots under ~/.saggar/scrollback. Turning it off deletes those snapshots. Project Activity retention is separate and can keep closed sessions by count or age. See Projects and sessions for how restored and closed sessions appear.

SSH targets

SSH settings save remote machines you use repeatedly. Saggar connects through macOS's OpenSSH client and opens a named tmux session on the remote machine. Closing Saggar or losing the connection leaves work in that tmux session running. Authentication, host keys, and proxies stay in OpenSSH rather than Saggar.

You can add a target by hand or import a named host from ~/.ssh/config. Test the connection before opening it. The test distinguishes an unknown host key, missing authentication, an unreachable machine, and a machine without tmux.

Example: rent a DigitalOcean development machine

  1. Create an Ubuntu Droplet in the nearest region. A shared-CPU machine with 2 GB RAM is enough for light terminal work; choose 4 GB for coding agents and builds. Check

    DigitalOcean's current prices

    rather than relying on a price quoted here.

  2. Select SSH-key authentication when creating it. If you don't have a key yet, create one on your Mac with ssh-keygen -t ed25519, then add the contents of ~/.ssh/id_ed25519.pub to the Droplet.

  3. Connect once from Terminal, verify the host fingerprint shown by DigitalOcean, and install the basic tools:

    ssh root@YOUR_IP
    apt update
    apt install -y tmux git curl build-essential

  4. Give the machine a stable local name in ~/.ssh/config:

    Host saggar-dev
        HostName YOUR_IP
        User root
        IdentityFile ~/.ssh/id_ed25519

  5. Check that ssh saggar-dev works, then import saggar-dev in SSH settings and select Test connection.

Create a non-root user before treating the machine as permanent. DigitalOcean charges for a Droplet until you destroy it; powering it off doesn't stop billing. A Linux machine works for web, backend, and general agent work, but it can't build or test macOS apps.

Open SSH settings

Agents and supervision

In Providers, each provider is one collapsed card: Claude Code, Codex, Antigravity CLI, Pi, OpenCode, and GitHub Copilot CLI. The switch beside a card's name adds that provider to the launch menus. Expand the card to see whether its CLI is installed and install it if not, choose models, install or remove its hooks, and install or remove the Saggar skill. Installation always names the external config or skill file it will change.

Models work two ways. Claude Code, Codex, and Antigravity CLI use Saggar's own catalog, and More models reveals the older or less suitable rows the catalog hides. Pi and OpenCode report their own model lists, so Choose models asks the CLI (pi --list-models or opencode models) and lets you pick which of the reported models get their own row in the new-session menu.

Open Provider settings

A provider whose handshake reports context, and confirms a compaction afterwards, can also compact itself while you are gone. Claude Code and Codex both do, and the Compact idle chats while you're away switch appears inside each of their cards. It is one setting wherever you flip it. Turn it on and after 59 minutes away Saggar compacts each idle chat whose context is at least half full, once. A chat that is working or waiting on you is never interrupted, and anything compacted is named in the away summary.

Supervision settings choose which providers start supervised and show every destructive-command category automatic approval refuses. Built-in protections can be disabled individually, and your own plain-text or regular-expression rules can hold additional commands for review. See Agents for the provider contracts and the safety model.

Open Supervision settings

Automation holds the defaults behind work Saggar starts on its own. Each scheduled job and each hook keeps its own controls in its project's tab; these settings apply to all of them. Catch up missed runs is on by default: a job whose minute passed while the Mac was asleep or Saggar was closed fires once when it is back. Turn it off and the missed run is skipped, and the job waits for its next scheduled minute. Pause automatic launches holds every failure that an Investigate or Fix automatically hook would have acted on in the project's Activity tab, with a note saying why, until you turn it off; you can still investigate by hand. Investigate with picks the agent a hook opens. It defaults to the last agent you launched, and a chosen provider you later switch off falls back to that.

Open Automation settings

CLI

Install the Saggar command and choose what it can do from this page. Workspace changes ask first by default. You can allow them after a cancelable 10-second countdown or immediately. Completed changes always show their source.

Let agents approve their own prompts controls whether an agent may run saggar approve inside its own terminal. It is off until you turn it on, and destructive approvals stop for you either way.

Command line

Installs saggar under ~/.local/bin and updates the profile for your configured login shell. saggar . then adds or focuses the enclosing repository.

Open CLI settings

General maintenance

Open General settings
Launch at login
Registers the packaged app with macOS. Development builds cannot.
Welcome
Runs the first-launch tour again without resetting the app.
Diagnostics

Reveals or exports app details, logs, and crash stacks. The bundle excludes terminal input and output, commands, account data, and tokens. Automatic crash sharing is on by default and sends only coarse Mac details and sanitized crash stacks. It never sends file paths, environment variables, screenshots, traces, or profiles.

Reset

Restores every preference to its default without removing the account, pairings, projects, sessions, history, watch patterns, or custom approval rules.

Updates

Saggar checks its small release manifest at most once a day and stays silent when the installed version is current or a background check fails. When a release is available, a banner offers the right path for the installation: a visible Homebrew upgrade in a monitor, or the download page for a direct install. Check for updates… in the app menu runs the same check immediately and reports success or failure.

Language

Saggar follows the language order in macOS. The app is localized in English, French, German, Spanish, Simplified Chinese, and Traditional Cantonese. Use System Settings ▸ General ▸ Language & Region ▸ Applications when Saggar should use a different supported language from the rest of the Mac.

Account and remote access

The Marginal Utility account pane signs the Mac in or out and opens account management in the browser. Remote control settings choose whether the Mac dials the relay, control the idle-sleep hold, approve pairing requests, revoke devices, and show recent remote actions. The remote-control documentation covers those security-sensitive controls in full.

Open Account settings

Open Remote control settings

Settings sync is on the account pane and off until you turn it on. With it on, this Mac's appearance, interface, notification, sound, session, and account-feature preferences follow your account, so a second Mac signed into the same account wears the same setup. Each preference carries the moment it was chosen and the most recent choice wins, per preference rather than per Mac, so two Macs that each changed something different both keep their change. A Mac that has just joined adopts what the account already holds rather than overwriting it. The document lives on Marginal Utility's relay, so this needs an active Saggar remote subscription.

What describes one machine stays on it: the default IDE, which providers are installed and enabled, shell integration, automatic approval and its per-provider defaults, remote access, keeping the Mac awake, phone alert forwarding, and crash sharing. Nothing secret is eligible either — tokens, device grants, project paths, and window state are not preferences and never leave. The preferences that do sync are stored on Marginal Utility's relay for your other Macs to read, so turn sync off if you would rather they stayed on this one.

The account pane also holds the two cloud AI features. Session summaries send the last part of a transcript to Marginal Utility's AI service when you ask for one; smart session naming sends verbose agent prompts automatically and is off until you turn it on. Both scrub obvious secrets on the Mac before anything is sent. See Cloud AI features for what leaves the Mac.