saturday.ai

::docs :: getting started

your first session

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

cd into a folder and run saturn. That folder is the working folder: the file tools read and write there, shell commands run there, and its SATURN.md loads every turn. Launched from ~, your home folder is the working folder. You get a prompt (»). Anything starting with / is a command, and everything else is a turn for the agent.

» what's on my calendar tomorrow, and is anything in mail waiting on me?
» summarize report.pdf and list the decisions in it
» remind me to call the dentist tomorrow at 9
» remember that I prefer concise answers

::what you see

  • –The rail shows each tool call as it runs, with a one-line preview of its result, the gate decisions, and, on a multi-step task, the agent's checklist.
  • –The status bar is pinned to the bottom. It shows posture only when it deviates from the safe default (⚠ GATE OFF, a loosened tier, ⛓ AIRGAP), then progress (thinking 3s while the model reasons, iteration, tool count, elapsed time, tok/s), the context-fill meter, an egress count once the ledger has an entry, GPU and memory use, and the keys esc pause · ctrl-c cancel.
  • –The answer streams as it's written. When the turn gathered anything, it ends with a numbered Sources list. A one-line receipt follows with tokens and timing, plus a trust segment whenever something left the machine or faced the gate.
  • –The gate stops the turn when a call wants to change or send something, and shows you the exact diff, command, or message. Bare Enter rejects.

A fact you state in your own words ("remember that I prefer concise answers") is kept without a gate, and the answer ends with remembered #N: …. /memory remove N undoes it. Once a web page, an email, a file, or an attachment has entered the conversation, every later fact asks first, until /clear.

::keys

keydoes
Esc on an empty linepause at the agent's next pass: Enter continues, typed text steers, q aborts. While the model is thinking, it stops the thought and the pass answers without it
type text, then Escsteer the running turn with that correction, without restarting it
type text, then Enterqueue it as your next message (the queue depth shows in the status bar)
Ctrl+Ccancel the turn
Shift+Tabat the prompt: cycle the approval tier (read_only → side_effecting → destructive)
Shift+Enter / Ctrl+J / \ then Enterinsert a newline in the prompt
Tabcomplete /commands and @paths

A large paste collapses into a [paste #N +L lines] chip that is sent in full. Put the cursor on a chip and press Ctrl+E to expand it for editing.

::in a message

@file

attach a file's contents (PDF, Word, and Excel are read as text), with tab completion. @"path with spaces" works.

@clipboard

attach what's on the clipboard. Saturn never reads the clipboard unless you type this.

!command

run a shell command yourself, without the agent. The output prints and is attached to your next message, so !git diff followed by "summarize that" works.

::first things to try

  1. 01/help lists every command, grouped by theme. Every command takes --help.
  2. 02/policy shows your trust posture: what runs without asking, and what can leave the machine.
  3. 03/tools shows the toolkits: Saturn's tools in groups (files, web, mail, calendar, messages, …). /tools off messages turns one off so the model never sees it.
  4. 04/init surveys the working folder and drafts SATURN.md, standing instructions loaded every turn.
  5. 05/trace, after a turn, shows the full drill-down of what just happened.
  6. 06/skills create weekly-review writes a template to ~/.saturn/skills/weekly-review/SKILL.md. Fill in the steps, then type /weekly-review to run it. Every action it leads to still asks as usual.

note

The file tools can't reach outside the working folder on their own. Ask about a file elsewhere and Saturn suggests /add-dir <folder>, which makes that folder reachable for the session. /rm-dir takes it away again.