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, OpenCode, Meta's Muse Code, or xAI's Grok Build. 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, handed one durable artifact to another run, 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, OpenCode, Meta's Muse Code, or xAI's Grok Build. 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.

Also worth doing now: sase completion install writes a <TAB>-completion script for your shell (zsh, bash, or fish) and verifies it actually loads. See Shell Completion for details.

Step 2 — Check Provider Readiness

SASE orchestrates a supported provider CLI and still relies on the provider's own authentication flow. Inventory the supported CLIs, then run the read-only doctor before the first agent launch:

sase agent-cli
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. SASE can install most built-in providers itself: every npm-packaged CLI (Claude Code, Codex CLI, OpenCode, Qwen Code, Grok Build) via npm install -g <package>, and Muse Code from its install script. Use sase agent-cli install <name> --dry-run to inspect the plan — the exact command and target, plus the downloaded script's URL and digest for Muse — then sase agent-cli install <name> to confirm and run it. The Antigravity CLI uses the install command in the provider guide. Installing & Authenticating Agent Providers has the per-provider install and auth commands plus the complete provider/model selection options; the LLM provider reference covers how SASE integrates each provider once it is ready.

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. Use one launch form: the normal form when SASE can auto-detect an installed provider CLI, or the explicit form when Muse Code or Grok Build is your provider. SASE never auto-detects muse or grok from PATH because both are generic executable names; this is about default provider selection. Select either explicitly with a provider/model directive. Both can still be reached automatically through whichever shipped size aliases currently target them (see the generated shipped size-alias defaults); override llm_provider.model_aliases.builtin.<size> to change that. Alias routing checks for an available grok executable but does not verify its identity, so resolve any Grok identity warning from sase doctor before launching:

# Auto-detected providers:
sase run "+home summarize this workspace's layout; do not change files"
# Muse Code:
sase run "%model:muse/muse-spark-1.3 +home summarize this workspace's layout; do not change files"
# Grok Build:
sase run "%model:grok/grok-4.7 +home summarize this workspace's layout; do not change files"
# Then, while it is still running:
sase agent list

The +home project tag 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. Default sase agent list shows running agents only. After the run finishes, use sase agent list -a (recent DONE/FAILED, capped at 50 most-recent per project) or open sase's TUI Agents tab to find the completed record.

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 sase's TUI And Find The Result

sase's TUI is the TUI control surface. Open it:

sase tui

sase's TUI has three top-level tabs:

  • Agents — live and recent agent records. Find the run you just launched: prompt, reply transcript, workspace path, status, retry chain.
  • Artifacts — views for stitches, Patches, beads, configured document providers such as Plans and Research, and captured files. The Patches view contains every Patch on the project. A Patch 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 Patch guide goes deeper when you're curious. This first read-only run should not have created one. Normal commits appear in the Artifacts Stitch pane (◉); the #pr workflow creates a Patch for a pull request.
  • Services — machine services, scheduled jobs, hooks waiting to complete, mentor launches, and error digests. This includes every configured service proc and nests scheduled work below scheduler. sase's TUI starts the active controller unless you pass --no-service.

The Step 3 prompt is kept in prompt history when it is at least five words long. sase prompt list shows it. Project tags are expanded before they are stored, so the +home tag in that launch is stored as #git:home.

In sase's TUI, that history shares the Prompts overlay with saved and discarded drafts. From the Agents, Artifacts, or Services tab, press Space to open the prompt input. When every launch so far used home, Space opens a blank home prompt. If any other project has been launched, Space prefills the most recent of those workspace prefixes; press Ctrl+U (the cursor is already at the end of the line) to clear it. Then press Ctrl+K. That shortcut works only while the prompt is a single line, and it opens the overlay on History without a project filter when the input is blank. Enter launches the highlighted prompt as stored. Tab loads it into the prompt input for editing. Esc closes the overlay.

Pressing , then . does not reopen this home launch. #git:home is the default workspace prefix, and sase does not keep it on the list of recently launched workspace prefixes that ,. reads. With nothing else on that list, sase warns No previously launched VCS macro and stays on the current tab. After you have launched some other project, ,. opens History from a main tab (not from inside a text field) and rewrites the workspace prefix of a prompt you submit or edit to that most recent non-home prefix.

Stash holds drafts saved with Ctrl+S from a non-empty prompt pane. Ctrl+S on an empty prompt opens Stash instead of saving. Trash holds drafts you discarded from Stash, not launched prompts. Restoring a Trash row puts it back in Stash and does not launch it. A copy is archived when a draft permanently leaves Stash or Trash, or when an existing Stash row is updated in place. Recover that copy with sase prompt stash-archive. [ and ] cycle the two top-level tabs, Stash and History. Trash is a view of the Stash tab, not a third tab: press t or select the 🗑️ chip to open it. From Trash, t or Esc returns to the Stash list. [ or ] from Trash opens History, and the bracket that comes back restores Trash. Esc on the Stash list or on History closes the overlay. See Prompts Overlay.

The colored project: +<project> chip at the right of each tab's status row is the current project — the project you most recently launched an agent on (or promoted with sase project set-current). After the +home run above, that chip is +home. First-open Artifacts filters seed from it; they do not lock you into that project. Press ? for help and q to quit.

What you just did. Observed one sase run produce a persistent agent artifact visible in sase's TUI, with the scheduler 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 \
  "+home create or update notes.md with one short note about SASE workspaces. Then run: sase artifact create -p notes.md -l 'Workspace note'"
sase agent list -a

Now the agent has permission to edit notes.md in its isolated numbered workspace. The example prompt does not include #commit. After the agent submits its final declaration, SASE's default host finalizer commits completed changes with create_commit and pushes them. A normal commit creates a stitch record. Creating a pull request with #pr creates a Patch.

On the Agents tab, the selected run lists its commits under SASE CONTEXT / ARTIFACTS / Commits, grouped by repository. That list is not the diff. Open the full message and diff from Artifacts: the Stitch pane (◉, key 2) is the default view, and Enter on a row opens that commit.

Workspace isolation separates concurrent edits, but the normal commit also pushes to the project's remote. For home, that remote is SASE's local bare repository. A later home run prepares a numbered workspace and syncs it from that bare origin (git fetch, then rebase onto the default branch), so it sees the pushed commit. The primary checkout is a separate tree.

Use #propose when you want a saved diff for review instead of a commit and push. #propose writes ~/.sase/diffs/<name>-<timestamp>.diff, then resets and cleans the workspace (git reset --hard and git clean -fd), so the uncommitted notes.md is not left in the workspace. See Commit Workflows.

Wait until that run finishes before continuing. Default sase agent list shows running agents only, so the row disappears from the default list when the run ends. Watch it on sase's TUI Agents tab, or poll sase agent list -a until that row's status is DONE or FAILED. -a still includes running agents; you are waiting for the status to change, not for the row to appear. The second instruction registers a durable snapshot while leaving the tracked notes.md in the workspace.

For your own repositories, target an existing managed project with its short project tag: sase run "+home list the files in this repo" is the same launch as sase run "#git:home list the files in this repo", and a GitHub project named sase can be targeted as +sase without remembering its provider. Use #git:<name> to create 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. In sase's TUI prompt editor, type + to pick a project from a menu. 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 — Hand Off Existing Work With Artifact References

An agent handoff is more reliable when it names the exact prior artifact instead of describing it loosely. List the explicit files SASE indexed for home:

sase artifact list --project home --explicit --limit 10

The Workspace note row's REF column contains a durable file reference such as file:explicit:0123456789abcdef01234567. The table truncates that column in narrower terminals, so widen the terminal or print the full ref field with sase artifact list --project home --explicit -q 'Workspace note' --json. Copy the exact value from your output and inspect it without launching an agent:

sase artifact show file:explicit:0123456789abcdef01234567

Then add @ when the same reference appears inside a prompt:

sase run "+home read @file:explicit:0123456789abcdef01234567 and summarize it"

Replace the sample reference with one from your own REF column. This leading-@ distinction is intentional: sase artifact show, path, and open accept the bare logical reference, while launch prompts use @kind:payload so SASE can find and expand references embedded in ordinary prose. sase artifact list inventories the persistent artifact-file index, not every kind of artifact reference. Rows with file:explicit: were registered with sase artifact create; file:default: rows are media that SASE persisted automatically while finalizing successful runs.

Artifact references cover more than indexed files:

Prompt form What it identifies
@file:<source>:<digest> Indexed file; source is explicit or default
@file:<absolute-path> One file below a configured allow-listed root
@<document-kind>:<path> One document in a configured sidecar, such as plan: or research:
@bead:<id> One published bead page in the current project
@agent:<global-name> One published agent page in the current project
@patch:<name> One Patch
@stitch:<repo>@<sha> One repository revision

Use @plan:<path> for the built-in plans sidecar. @commit: remains an alias for @stitch:; the old #ref/<kind> renderer syntax has been retired.

sase's TUI can supply these without memorizing the grammar. Type @ in the prompt bar for the grouped reference menu, or press % on an Artifacts entry to open Copy as…. The editor LSP completes canonical @stitch: payloads from local git checkouts, excluding SDD sidecar repositories. sase's TUI prompt bar currently lists both canonical and compatibility kinds, but its repository-history picker is still attached to @commit:; that alias and @stitch: resolve identically at launch. sase's TUI also lists @patch: without enumerating Patch names, so use % on the Patch or type its name. Choose Reference in new agent prompt to open a prompt pre-filled with the entry's project and prompt-ready @ reference; choose Copy artifact reference when you only want the reference on the clipboard.

At launch, each known artifact reference expands to portable semantic prose rather than an @-prefixed filesystem path. @plan:202608/foobar.md becomes the 202608/foobar.md file in the plans sidecar repo; @research: uses the same sidecar-pointer shape; @file: names the captured or materialized file; @bead: / @agent: / @patch: name the object in its project; @stitch: names the full SHA in its repository. Authored citations stay @<kind>:<argument>. A historical @bug: reference becomes issue #<number> in the <project> project (<url>). A malformed or missing known non-pointer reference stops the launch with a diagnostic instead of silently giving the agent bad context. Inline-code and fenced-code examples stay literal.

See the sase artifact command reference for inspection, path, viewer, and repair commands. The Artifact References page documents canonical forms, project context, compatibility aliases, and allow-listed files. The prompt preprocessing reference explains expansion order and literal regions.

What you just did. Passed one durable output from a completed run to a new agent without depending on chat history or a recycled workspace path.

Step 7 — Reuse The Prompt As A Macro

A one-off prompt is fine once. The second time you find yourself reaching for it, wrap it as an Macro so you're not retyping the same paragraph forever. Create sase/macros/til.md at the project root 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 Macro 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. Macros 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 Macros 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 Macro, the smallest unit of repeatable agent work in SASE.

Step 8 — 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 two (admittedly whimsical) names: ordinary plans are tales, and executable multi-phase plans are epics. Either 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 ready task beads whose blockers are closed
sase bead show <bead-id>  # inspects one bead in detail

For a self-contained follow-up that does not need an epic, agents first run /sase_new_task; when it is genuinely new, create a standalone task bead with sase bead create --type 'task(bug)' --title "Follow up" --size small -w "Independent follow-up that does not belong on the current epic" -f location=src/foo.py -f repro='fails on retry', move it to ready with sase bead update <task-id> --status ready when it is ready for triage, and launch it with sase bead work <task-id>. AXE also turns stored ready tasks into notification gates where a reviewer can launch or close them.

Approving a structured epic plan files its epic and phase beads, wires their dependencies, and automatically invokes the same path as sase bead work <epic-id> --yes. Before it spawns anything, that path sets the epic's internal launch-readiness marker, assigns every remaining phase bead to its deterministic worker, assigns the epic to the land worker, and commits the complete launch checkpoint. Unless the launch uses --no-push, the existing-epic path also runs managed store synchronization before dispatch; a remote-backed detached bead store must actually publish the checkpoint. It then launches one agent per remaining phase plus the final land agent. Dependency waits require both the blocking agent to finish successfully and its bead to close; the land agent waits for every phase bead. You can still run sase bead work <epic-id> manually to retry remaining work.

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:

  • sase's TUI — the TUI control surface for Patches, agents, notifications, and automation.
  • Current project — the project SASE treats as working context: in practice, the one you most recently launched an agent on (or promoted with sase project set-current / the c key on the Admin Center's Projects tab). sase project current prints it. The working directory never sets it, and there may be none.
  • Scheduler and Service Host — background automation. 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.
  • Patches — durable PR-sized review records: status lifecycle, commits, hooks, comments, mentors.
  • Artifact references — durable @kind:payload locators that put files, documents, chats, beads, agents, commits, and bugs into a launch prompt. Resolve them with sase artifact show, path, or open; complete, copy, or hand them off from sase's TUI.
  • Beads — dependency-aware, git-portable plan, phase, and standalone task work units. A note can attach a content-addressed snapshot of a file with @<path>, or with sase bead attach. When it reaches a shared store, other machines can fetch it; local-only snapshots stay on the originating machine. See Attachments.
  • Memory Webs / Glossary — per-project definitions of the terms your team keeps reusing, authored as strand files under sase/memory/glossary/. Agents fetch one on demand with sase memory read glossary:<term> -r "<why>" instead of carrying every definition in memory (-r is required — a read is never printed unless it is recorded). In sase's TUI, both shortcuts are prompt-bar keys: from a prompt pane in NORMAL mode, K previews the term under the cursor and gG opens the browse-and-edit Memory panel seeded on it. gT opens the Snippets panel.
  • Macros — reusable prompt templates and YAML workflows with typed inputs and multi-agent fan-out. See also workflow specs.
  • SDD — Spec-Driven Development. Plans and epics as first-class artifacts on disk.
  • Procs — durable records for background operations such as a sync, an accept, or a detached task launch. Every proc runs under its own supervisor and outlives the client that submitted it; a session is attribution only, and historical tui and detached rows stay readable. Inspect them with sase proc list / sase proc show, or on the Admin Center's Procs tab.
  • Monitors — agent-session members used to hand off a slow command (just check-full, a CI wait, a deploy) at the end of an agent turn. A detached supervisor runs the command, and an optional follow-up agent turn returns under the same agent session; the session keeps its one runner slot for the monitor and then the follow-up. SASE reports explicitly if that follow-up cannot inherit the monitor's workspace.
  • Plugins and providers — model and VCS providers behind a common boundary: Claude Code, Antigravity CLI (agy), Codex, Qwen Code, OpenCode, Muse Code, Grok Build for agents; bare git and GitHub for version control.