Skip to content

Getting Started: Your First 15 Minutes

SASE (pronounced "sassy" — yes, really) is a coordination layer that sits above coding-agent CLIs like Claude Code, Codex, Antigravity CLI (agy), Qwen Code, or OpenCode. This guide is the practical on-ramp: by the end you'll have installed sase, checked that a provider CLI is ready, launched a safe read-only agent run, found the resulting agent record, and picked up the vocabulary you'll keep bumping into in the rest of the docs. Plan on roughly fifteen minutes at a terminal, plus however long your favorite model takes to think.

Step 1 — Install SASE

SASE needs Python 3.12+, uv, and one authenticated coding-agent CLI such as Claude Code, Codex, Antigravity CLI (agy), Qwen Code, or OpenCode. With Python and uv in place:

uv tool install sase
sase version

If sase version prints the SASE package plus the sase-core-rs package, the CLI is installed. The first install can stretch past 90 seconds when uv has to fetch wheels; that's normal, not a hang.

What you just did. Installed the public sase CLI and its Rust core extension as a user tool, without cloning the repository or setting up a contributor environment.

Step 2 — Check Provider Readiness

SASE orchestrates an existing provider CLI; it does not replace that provider's own install or authentication flow. Run the read-only doctor before the first agent launch:

sase doctor

If the provider check reports a missing executable or an authentication gap, install and authenticate one provider CLI, then run sase doctor again. The LLM provider reference keeps the setup pointers in one place so this quickstart can stay focused.

What you just did. Verified that SASE can find a usable coding-agent provider before spending time on an agent run.

Step 3 — Launch A Safe First Agent

Start with a read-only task in SASE's managed home project:

sase run "#git:home summarize this workspace's layout; do not change files"
sase agent list

The #git:home prefix targets SASE's built-in home sandbox. On first use, SASE bootstraps that managed project with a bare git repository, a primary checkout, and generated SDD scaffolding, then launches the provider CLI in an isolated numbered workspace managed by SASE. Prompts with no workspace reference are normalized to #git:home automatically, so the bare form sase run "summarize this workspace's layout; do not change files" is equivalent. That isolation is what lets you fire off several agents at once without them colliding, and what lets a failed run be retried without touching your primary checkout.

The launched agent gets its own durable record on disk: prompt, reply transcript, artifacts directory, status, and workspace path. sase agent list gives you the first visible handle for that record while the model is thinking or after it finishes.

What you just did. Dispatched a read-only coding-agent run inside an explicit workspace, then looked up the resulting SASE agent record.

Step 4 — Open ACE And Find The Result

ACE is the TUI control surface. Open it:

sase ace

ACE has three tabs:

  • Agents — live and recent agent records. Find the run you just launched: prompt, reply transcript, workspace path, status, retry chain.
  • PRs — every ChangeSpec on this project. A ChangeSpec is SASE's durable record of one PR-sized unit of work; think of it as the long-lived sibling of a pull request that holds the description, parent, status (WIP → Draft → Ready → Mailed → Submitted), commits, hooks, comments, and mentor activity all in one place. The ChangeSpec guide goes deeper when you're curious. This first read-only run should not have created one yet; editable committed work is where ChangeSpecs appear.
  • Axe — the background daemon's view: scheduled jobs, hooks waiting to complete, mentor launches, error digests. ACE auto-starts AXE the first time it opens, so this tab is already ticking before you click it.

ACE TUI tabs

What you just did. Observed one sase run produce a persistent agent artifact visible in ACE, with AXE handling lifecycle work in the background.

Step 5 — Try One Tiny Edit

After you have seen the agent record, try a low-risk change:

sase run "#git:home create or update notes.md with one short note about SASE workspaces"
sase agent list

Now the agent has permission to make a visible diff in its isolated numbered workspace. Your own repositories and the home primary checkout stay untouched unless you explicitly bring changes back. When the agent commits its work, SASE's commit workflow records a ChangeSpec that you can review on ACE's PRs tab before landing or submitting anything.

For your own repositories, use #git:<name> to target a managed project or #git:<bare-repo-path> to register an existing bare repository. Provider plugins add other workspace references, such as #gh:<owner>/<repo> for GitHub. #cd:<path> also exists, but it runs directly in that directory with no numbered workspace or VCS lifecycle; use it only when you deliberately want an in-place run. The workspace guide has the full model.

What you just did. Moved from a read-only run to a small editable task after confirming where SASE records agent state.

Step 6 — Reuse The Prompt As An XPrompt

A one-off prompt is fine once. The second time you find yourself reaching for it, wrap it as an XPrompt so you're not retyping the same paragraph forever. Create xprompts/til.md in the directory where you run sase:

Append one Today-I-Learned entry to `til.md` about something useful in this workspace. Keep it to two sentences. If the
file does not exist, create it.

Now the same agent run is one tag:

sase run "#til"

That is the smallest XPrompt shape: a single Markdown file becomes a reusable prompt part. Because this prompt has no workspace reference, the same #git:home default kicks in at launch. XPrompts also support YAML files with typed inputs, multi-step workflows (prompt parts, Python, bash, parallel fan-out, approvals), and --- separators for multi-agent dispatch. The XPrompts guide covers the full surface, and the workflow spec reference documents the YAML form.

What you just did. Turned a one-off prompt into a reusable XPrompt, the smallest unit of repeatable agent work in SASE.

Step 7 — Plan Bigger Work With SDD And Beads

When a task is too big to hand to a single agent and hope, SASE asks you to write a plan first. Spec-Driven Development (SDD) keeps those plans as first-class artifacts on disk under three (admittedly whimsical) names: ordinary plans are tales, executable multi-phase plans are epics, and longer cross-cutting plans are legends. Any of them can be filed as a bead: a git-portable, issue-like work unit with status, dependencies, and an assignee.

The smallest useful loop:

sase bead onboard         # walks through the issue-tracking quick start
sase bead ready           # lists work whose blockers are closed
sase bead show <bead-id>  # inspects one bead in detail

Once an epic plan exists and its phase beads are filed, sase bead work <epic-id> builds a dependency schedule from the open phases, pre-claims each phase bead, launches one agent per phase in the right order, and runs a final land agent after the phases finish. That's the on-ramp from one-shot prompts to multi-agent execution with actual ordering. No more babysitting sase run calls in a shell loop.

What you just did. Stepped from one-shot prompts into Spec-Driven Development with Beads as dependency-aware work units.

The Component Map

The names you'll keep bumping into, in one place:

  • ACE — the TUI control surface for ChangeSpecs, agents, notifications, and automation.
  • AXE — the background automation daemon. Runs hooks, mentor launches, comment polling, dependency unblocking, error digests.
  • sase run — the entry point that launches an agent or workflow. See the CLI reference.
  • Workspaces — isolated numbered clones managed by SASE so agents can work in parallel without touching your primary checkout.
  • ChangeSpecs — durable PR-sized review records: status lifecycle, commits, hooks, comments, mentors.
  • Beads — dependency-aware, git-portable work units. Powers epic execution.
  • XPrompts — reusable prompt templates and YAML workflows with typed inputs and multi-agent fan-out. See also workflow specs.
  • SDD — Spec-Driven Development. Plans, epics, and legends as first-class artifacts on disk.
  • Plugins and providers — model and VCS providers behind a common boundary: Claude Code, Antigravity CLI (agy), Codex, Qwen Code, OpenCode for agents; bare git and GitHub for version control.