Everything you need to use sAI.

Before you start

• A Mac — sAI 0.2.0 supports macOS. Windows and Linux are not supported yet.
• Python 3.14 — check with python3 --version. Get it from python.org if needed.
• A license — free during the preview. Request access; each license works on one computer.
• An OpenRouter API key — required. Create one at openrouter.ai/keys. Optional free-tier keys add capacity: Groq, Google Gemini, NVIDIA.

Install and activate

1. Download the package from the home page and install it: python3 -m pip install sai-0.2.0-py3-none-any.whl Tip: install it in its own environment first with python3 -m venv ~/.sai-env && source ~/.sai-env/bin/activate.
2. Get your laptop code and send it with the access form: python3 -m sai_guard machine-id
3. When your approval email arrives, run this and paste the email (all of it is fine): python3 -m sai_guard activate You'll see ✓ License installed.
4. Check it works: sai --version

Your first session

1. Open Terminal and go to a project folder: cd ~/my-project
2. Run sai. The very first time, it asks for your API keys — paste them when asked (input is hidden).
3. The first time in a folder, sAI asks whether you trust it. That folder becomes the workspace: agents can read everything in it, and change files or run commands only with your approval. They can't reach outside it.
4. Type what you want in plain English and press Enter:

❯ why does the login test fail?
  ⎿  jev → Debugger
⏺ Bash(python3 -m pytest tests/test_login.py -q)   ⎿  1 failed
⏺ Read(app/auth.py)                              ⎿  Read 84 lines
⏺ Debugger
  The test expects a 401 but login() returns 403 for a wrong password…
  models: Jev → gpt-oss-20b (groq, free) · Debugger → nemotron-3-super (free) ×3

Each ⏺ line is a step: a tool the agent used, then its result. The last line under every answer shows which AI models produced it, and whether they were free.

Talking to sAI

You can say "don't edit anything" or "just explain" and sAI will only investigate and report.

The agents

You don't need to pick one — sAI routes each request automatically. Big tasks go to several agents in turn (for example Planner → Coder → Reviewer). /agents lists them.

Approvals and safety

• File changes show a colored diff first and ask Allow? [y/N/a] — y yes, N no, a yes to all edits for this session.
• Risky commands (deleting files, sudo, git push, installing from the internet into a shell…) always ask first.
• "No" means no. When you decline, the agent stops and tells you what it was trying to do. It won't look for another way around.
• Sandbox. Commands that agents run can only write inside your project, can't read private files in your home folder (like SSH keys or documents), and can only reach package registries and GitHub online. If a command needs more, the agent asks you first. /sandbox shows the status; /sandbox allow example.com permits a website.
• Undo. /undo rolls back the file changes from the last request. Repeat it to go further back.
• Fewer prompts. /permissions edits auto applies edits without asking; /permissions allow pytest lets a command run without asking. /permissions shows your rules.

Commands

From the shell: sai --version, sai login, sai logout groq, sai -c (continue last conversation), sai -r (pick one).

Models and cost

• sAI uses free models first — from OpenRouter, Groq, Google and NVIDIA, depending on the keys you added — and switches to a paid model only when free ones are busy or fail. You'll see a short note when that happens.
• Every answer ends with a models line saying exactly which models were used, and whether they were free.
• OpenRouter limits free models to about 50 requests a day per account; adding free Groq, Gemini and NVIDIA keys gives sAI more free capacity.
• Paid usage is charged by the provider to your own key. Watch it with /cost and cap it with /budget.
• Free model providers may log what you send them. Avoid free keys for code you can't share with third parties.

Your API keys

• Stored encrypted in your Mac's Keychain — never in your project folder, so they can't end up in git.
• Change them any time: sai login (or /login inside sAI). Each key is checked with its provider before it's saved.
• Remove one: sai logout groq.
• Environment variables such as OPENROUTER_API_KEY override saved keys — handy for scripts.
• Never paste API keys into a request.

Sessions and project memory

• Conversations are saved per folder. Continue the last one with sai -c, or pick with sai -r / /resume.
• Long conversations are summarized automatically so sAI keeps working; /compact does it on demand.
• SAI.md in your project holds standing instructions. Create it with /init and edit it freely.

Your own commands

Save prompts you use often as Markdown files: in .sai/commands/ inside a project, or ~/.sai/commands/ for all projects. A file review.md becomes /review. Write $ARGUMENTS where the text after the command should go:

# .sai/commands/explain.md
Explain $ARGUMENTS to a new team member: what it does, how it fits in, and what to watch out for.

Then: /explain app/auth.py

Using sAI from scripts

Run one request without the interactive screen — the answer goes to the output, progress to the error stream:

sai -p "summarize what this repo does"
cat error.log | sai -p "why is this failing?"
sai -p "add docstrings to utils.py" --accept-edits
sai -p "list the TODOs" --output-format json

Nobody is there to approve, so commands that need approval are declined and reported. --accept-edits allows file edits.

Tips for great results

• Be specific. "Fix the date parsing in reports/export.py so it accepts 2026-10-04" beats "fix the bug".
• Point at files with @file when you know where the problem is.
• Paste the error. A stack trace or log line saves the agent a lot of searching.
• Say the limits. "Only change the tests", "don't add dependencies", "just explain".
• Run /init once per project so every agent knows its conventions.
• Use /council for questions where you want a second opinion.
• Commit often — and use /undo if a change isn't what you wanted.

Troubleshooting

Still stuck? Use the form and describe the problem in the last box.