Saffronv1.0.0
Get started
Get started

AI providers and sign-in

Saffron needs an AI agent only to record a scenario the first time and to heal it when your app changes. Every other run replays at zero tokens and needs no AI at all. The agent runs on an AI subscription you already pay for: Claude by default, or Codex, Google AI (through Antigravity) or Cursor. This page shows how to choose one, how each one signs in, and what saffron login does for each.

At a glance

provider Subscription Saffron runs it through Set up once Status
claude (default) Claude Pro or Max, or an API key the Claude Agent SDK, bundled with Saffron a Claude Code login verified
codex ChatGPT Plus or Pro OpenAI's @openai/codex-sdk install the SDK, then npx @openai/codex login verified (macOS and Linux)
antigravity Google AI Pro or Ultra Google's Antigravity CLI, agy install agy, sign in, then npx saffron login antigravity verified, experimental
cursor Cursor Pro or Business Cursor's @cursor/sdk install the SDK, then npx saffron login cursor not yet verified live

Choose one in saffron.config.json:

{ "provider": "codex" }

or for a single run:

npx saffron run --provider antigravity

Each provider runs through its vendor's official client, on the login that client keeps on your machine, the way the Claude provider runs Claude Code through the Claude Agent SDK. Saffron never reads or copies those logins.

saffron login: check and set up

npx saffron login              # the provider in saffron.config.json
npx saffron login antigravity  # or name one

It tells you whether the provider can record and heal on this machine, and lists what is missing if not. It exits 0 when all is set (Codex: ready to record and heal.) and 1 with the list otherwise. For two providers it also does the one-time setup:

  • saffron login cursor opens Cursor's sign-in in your browser.
  • saffron login antigravity allows Saffron's tools in agy's settings.

Run it again whenever you like: it leaves anything already set up as it is. saffron run shows the same list as a note before a run that may need the agent. Replay-only runs (--no-agent) never need a provider.

Claude (the default)

Runs through the Claude Agent SDK, which ships with Saffron and runs Claude Code on your login.

Sign in, one of:

  • Log in to Claude Code on this machine: install it (npm install -g @anthropic-ai/claude-code), run claude, then /login with your Claude Pro or Max account.
  • Or set ANTHROPIC_API_KEY=sk-ant-... (console.anthropic.com, API keys). Bedrock and Vertex work through Claude Code's own environment variables.

Check with npx saffron login claude.

Good to know. On a subscription the report shows your 5-hour plan window before and after the run, and prices the run at API rates for comparison. Saffron keeps your claude.ai connectors (Gmail, Figma and the like) out of its sessions: they would add hundreds of tool definitions to every model call.

Codex (ChatGPT Plus or Pro)

Runs through OpenAI's Codex SDK, which runs the Codex CLI on your ChatGPT login. macOS and Linux only for now.

Set up:

  1. npm install --save-dev @openai/codex-sdk. It brings the Codex CLI with it (about 300 MB), so only projects that use Codex install it.
  2. npx @openai/codex login, and sign in with ChatGPT. Use the full name: npx codex alone runs an unrelated npm package when OpenAI's is not installed in the project. If you already use Codex on this machine, you are signed in; a login kept in the keyring works too.
  3. npx saffron login codex to check.

In a session Saffron runs Codex without your ~/.codex/config.toml: your own MCP servers, plugins, hooks and model defaults stay out, and only its login settings are kept. It saves no session files, and the agent can use only Saffron's browser and recording tools. To do this Saffron keeps a two-line wrapper script in ~/.cache/saffron/.

Models are Codex's own, for example "model": "gpt-5.5"; unset, Codex picks its default.

Sign out with npx @openai/codex logout.

Limits. Your ChatGPT plan's usage limits apply: when you reach one, the scenario fails with Codex's message and the time it resets. On Windows the provider refuses to start, because it cannot keep your own Codex config out of the session there.

Antigravity (Google AI Pro or Ultra)

Runs through Google's Antigravity CLI, agy, headless, on its own login. Gemini CLI stopped serving Google AI Pro and Ultra accounts in June 2026, which is why the Google provider uses Antigravity.

Experimental, with a risk to know about. Google's Antigravity terms forbid reaching Antigravity through third-party tools with your login. Saffron only runs Google's own agy binary, headless, the way Google's headless documentation describes, but no statement from Google covers a tool doing that on your behalf. Use this provider knowing that risk to your Google account.

Set up:

  1. Install agy: curl -fsSL https://antigravity.google/cli/install.sh | bash. It lands in ~/.local/bin/agy.

  2. Run agy once and sign in with your Google AI Pro or Ultra account.

  3. npx saffron login antigravity. It checks that agy is installed and signed in (by listing your models, which costs no quota), then adds two rules to ~/.gemini/antigravity-cli/settings.json:

    "permissions": { "allow": ["mcp(saffron_browser/*)", "mcp(saffron_tools/*)"] }

    Headless agy cannot ask you for permission, so without these rules it refuses every call to Saffron's tools. They allow Saffron's two tool servers and nothing else. The rules are global to agy: a repository whose own .agents/mcp_config.json names a server saffron_browser or saffron_tools would run its tools without a prompt in your own agy sessions too, so treat those two names as reserved. The rest of the file stays as it was; a file that is not valid JSON is left alone and reported instead. Until the rules are in, recording and healing refuse to start and tell you to run this.

In a session Saffron works in a throwaway folder: an agent carrying Saffron's instructions, Saffron's two tool servers, and a hook that allows only calls to those servers and reading their tool descriptions. Shell, files, web search, agy's own browser and any MCP server of yours are denied. agy's own permissions are the second fence, and agy runs terminal commands in its sandbox besides.

Models are agy's, listed by agy models: for example "model": "gemini-3.8-flash-high" or "gemini-3.1-pro-high". Unset, agy picks its default.

Undo by removing the two rules from ~/.gemini/antigravity-cli/settings.json.

Good to know. agy still starts your own global MCP servers in each session (their tools are denied to the agent), and each Saffron session appears in agy's conversation history. agy has no ephemeral mode: it keeps every conversation, and the prompt it received, under ~/.gemini/antigravity-cli/. That prompt holds the resolved values of the {env:VAR} secrets a scenario uses, so on a shared machine clear that history after recording, or record with Claude or Codex, which keep nothing.

Cursor (Pro or Business)

Runs through Cursor's SDK: the agent loop runs on Cursor's servers under your plan, and the tools run on your machine. It needs Node.js 22.13 or newer. Not yet verified with a live recording.

Set up:

  1. npm install --save-dev @cursor/sdk.
  2. npx saffron login cursor. Cursor's SDK does not use the Cursor app's login, so this opens a sign-in page in your browser once. It stores a key for your account in ~/.cursor/sdk/auth.json (valid for 90 days by default), and runs bill your Cursor plan. A CURSOR_API_KEY in the environment works instead.
  3. Run npx saffron login cursor again to check: it says when you are already signed in.

In a session the agent can use only Saffron's tools, your own Cursor rules and MCP settings are left out, and the agent's records go to a throwaway folder.

Models are Cursor's, for example "model": "composer-2.5" or "auto"; unset, auto.

Sign out by deleting ~/.cursor/sdk/auth.json and revoking the key in your Cursor dashboard.

What every provider shares

  • The same recordings. The agent reaches the browser and Saffron's tools through Saffron, which records every call the same way whatever the provider. A recording made with Codex replays at zero tokens and heals like one made with Claude, and every recording is proof-replayed before you review it.
  • Only Saffron's tools. No provider's agent may run shell commands, edit files or search the web. Playwright's browser_run_code_unsafe, which would run code on your machine, is hidden from all of them; browser_evaluate, which runs inside the page, stays. The tools that remain are checked call by call: navigation opens web pages only (http(s) and about:blank, no file:, view-source: or data: URLs), uploads take files inside the project and never dotfiles such as .env, and the filename option, which would make a snapshot or a response body overwrite a project file, is dropped. Any file the vendor's tools produce lands in a temp folder. So are the tools a recording cannot replay (going back, reloading, resizing, dropping files, and what PLAYWRIGHT_MCP_CAPS adds), whatever your environment turns on.
  • Models belong to the provider. model and healModel take the configured provider's model names. A run switched with --provider uses that provider's defaults, and says so, unless --model names one.
  • Cost. Claude reports a price. Codex, Antigravity and Cursor report tokens only, so the report says "cost not reported by the provider" rather than showing $0.

Troubleshooting

You see Do this
note: the Codex agent is not set up here before a run Run npx saffron login codex and follow its list.
Antigravity cannot start here: Saffron's tools allowed in agy, once: npx saffron login antigravity Run that command once.
agy could not list your models Run agy and sign in again.
Codex: You've hit your usage limit ... Wait for the reset time in the message, or record with another provider, for example --provider claude.
Cursor: ... Invalid User API Key. Sign in once with: npx saffron login cursor Run it: the key is missing or has expired.
the cursor provider needs Node.js 22.13 or newer Upgrade Node, or use another provider.
the codex provider is not available on Windows yet Record on macOS or Linux, or use another provider.
note: model and healModel in saffron.config.json name Claude models; this Codex run uses its default models Expected with --provider. Pass --model to choose one.