docs.

introduction

What Saturn is, the two guarantees it is built around, and how one turn runs through the loop.

installation

The one-line installer, pipx/uv, and installing from source, plus the environment knobs the installer honors.

your first session

The working folder, the prompt, the rail and status bar, and the keys that matter during a turn.

the loop & steering

How a turn runs: passes, thinking and /think, the plan checklist, pausing and steering with Esc, ask_user, and the bounds that end every turn with an answer.

the approval gate

Risk tiers, the y/N/s/a/e prompt, what the prompt shows, how long an approval lives, the tools that always ask, the shell and Shortcuts allowlists, and /policy.

the trust stack

The egress ledger and air-gap, untracked processes, the URL hold, prompt-injection quarantine, terminal escapes, control files, invented recipients, the trust receipt, and secrets.

answers you can check

What an answer carries: the Sources list and /trace source, the incidents note, and how declined, failed, and capped work is reported.

tools

All 47 built-in tools and their risk tiers, the toolkits you can turn off, and what each tool does: files, shell, web, knowledge, memory and skills, the loop's own tools, and the macOS apps.

your mac

Notes, Calendar, Mail, Contacts, Reminders, Messages, Shortcuts, the browser tab, and Finder, plus the macOS permission dialogs and Full Disk Access.

mcp servers

Connect any Model Context Protocol server from config.yaml. Its tools face the same gate as everything else and never set their own risk tier.

workspace, memory & documents

The working folder and /add-dir, SATURN.md standing instructions, hooks, layered memory (what you tell it, the first-run questions, and the review queue), the local knowledge base, /undo, and sessions.

skills

Your own procedures, written once in markdown and run by typing their name. Saturn can draft one for you, and it always asks before it saves.

observability & replay

/trace: the drill-down of any recorded run, why it chose what it did, exactly what the model was sent, exports, and offline replay.

headless & the cli

saturn -p and -q for scripts and pipes, --json, --export, --yolo, --replay, and what the gate does when no human is present.

slash commands

Every command. /help lists them all by theme, and every command takes --help.

configuration & models

config.yaml: the four model tiers, /models, runtime and trust knobs, the memory, web, RAG, MCP, toolkits, and shell sections, and which settings persist.