Saggar links

A Saggar link proposes one action to the Mac app. The app shows its source and the complete request, then waits for the user to confirm. Opening a link never changes settings, creates a session, runs a prompt, or writes a skill by itself.

The canonical shape is:

https://saggar.marginalutility.dev/open/v1/{action}?{parameters}

v1 supports five actions:

Action	Parameters	Result after confirmation
navigate	Optional pane	Opens Saggar, or a Settings pane.
settings	One or more supported setting keys	Shows and applies an exact before-and-after diff.
session	name, command	Adds an enabled session preset.
prompt	prompt, provider, model, optional title	Opens an agent session and runs the visible prompt.
skill	id, provider	Installs a skill shipped inside this Saggar build for one provider.

Parameters

pane names a Settings pane: general, appearance, interface, notifications, sound, keyboard, projects, presets, terminals, ssh, providers, turbo, automation, cli, account, or remoteControl. Without pane, navigate opens Saggar.

Supported setting keys are appFontScale, optionAsMetaKey, terminalFontSize, and terminalScrollback. Each value is checked against the setting's allowed range when the change is applied, and a value outside it fails with a message naming the setting. Links can't change remote access, accounts, credentials, grants, or secrets.

prompt opens an agent session only when model is in the Mac's own catalog for that provider. Otherwise the confirmed action fails with a message that the model isn't available in this build. provider is a provider name such as claude or codex.

Add a button to a docs page

Import the shared component, then pass typed parameters:

import SaggarLink from '@site/src/components/SaggarLink';

<SaggarLink
  action="session"
  parameters={{name: 'Review', command: 'codex'}}
>
  Add the Review session
</SaggarLink>

Open Provider settings

Use a button label that names the action. Don't use a generic “Confirm” or “Continue” label.

Trust and limits

Universal links delivered from the public Saggar site appear as official. The browser fallback is saggar://open/v1/{action}?{parameters}. It always appears as unverified, and the confirmation shows its source parameter, if any, as the unverified origin, even when it claims to come from the public site. Both paths require the same native confirmation.

The parser rejects unknown actions, unsupported versions, duplicate parameters, oversized URLs, any query parameter the action doesn't take (other than source), and any settings key that isn't a supported setting.

Field	Limit
Whole URL	8,192 bytes
prompt	4,000 bytes
command	1,000 bytes
name, model, title	120 bytes each
id (skill)	80 bytes
provider	40 bytes

Links can't contain arbitrary skill files or direct shell-execution actions.