Skip to content

Hello, SASE: Your First 15 Minutes Orchestrating Coding Agents

SASE (pronounced "sassy" — yes, really) is a coordination layer that sits above coding-agent CLIs like Claude Code, Codex, or Gemini. This post is the practical on-ramp: by the end you'll have installed sase, launched an agent, found the resulting ChangeSpec in ACE, 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.

If you'd rather read about why a system like this exists before touching it, the companion essay Why Coding Agents Need Orchestration makes that argument. This post does the opposite: run first, name the parts afterward.

Step 1 — Install (≈90 seconds)

SASE needs Python 3.12+, uv, and just. With those in place:

uv venv .venv
source .venv/bin/activate
just install
sase --help

If sase --help prints a wall of subcommands, you're in. The first install can stretch past 90 seconds when uv has to fetch wheels — that's normal, not a hang. The just install step pulls in the Python CLI plus the Rust core extension (sase_core_rs) that some of the hot paths call into. If anything looks off, sase core health is the canonical sanity check and the development guide covers the usual fix-ups.

What you just did. Dropped the sase CLI and its Rust core extension into an editable virtualenv.

Step 2 — Launch your first agent (≈3 minutes, plus model time)

Pick a tiny, safe task — anything that produces a visible diff without needing the network. A docstring is a friendly first choice; the exact wording doesn't matter, so use whatever feels natural:

sase run "add a one-line docstring to the most recently edited Python function in this repo"

sase run doesn't touch your working tree. It allocates an isolated workspace — a sibling clone of the repo named sase_<N> — and runs the agent in there. That isolation is what lets you fire off several agents at once without them elbowing each other, and what lets a failed run be retried without scorching your real checkout.

The launched agent gets its own durable record on disk: prompt, reply transcript, artifacts directory, status. You'll poke at it in the next step. (If the run takes longer than you expected, that's the model thinking, not SASE napping.)

What you just did. Dispatched a coding-agent run inside an ephemeral workspace, tracked as a SASE agent record with its own artifacts directory. The full CLI reference lists every flag you'll ever want.

Step 3 — Open ACE and find the result (≈3 minutes)

ACE is the TUI control surface. Open it:

sase ace

ACE has three tabs:

  • CLs — every ChangeSpec on this project. Your agent's commit should be sitting here as a new ChangeSpec, complete with a name, status, commits drawer, and diff. A ChangeSpec is SASE's durable record of one CL/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.
  • Agents — live and recent agent records. Find the run you just launched: prompt, reply transcript, workspace path, status, retry chain.
  • 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 durable ChangeSpec and a persistent agent artifact, both visible in ACE, with AXE handling lifecycle work in the background.

Step 4 — Reuse the prompt as an XPrompt (≈3 minutes)

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/docstring.md in your project root:

Add a one-line docstring to the most recently edited Python function in this repo. Keep the wording terse; do not change
behavior.

Now the same agent run is one tag:

sase run "#docstring"

That is the smallest XPrompt shape — a single Markdown file becomes a reusable prompt part. 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 5 — Plan bigger work with SDD and Beads (≈3 minutes)

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 (recap)

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 sase_<N> clones of the repo so agents can work in parallel without touching your checkout.
  • ChangeSpecs — durable CL/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, Gemini CLI, Codex, Qwen Code, OpenCode for agents; bare git and GitHub for version control.

Series Navigation

This is a hands-on companion to the Agentic Software Engineering series. Read the launch essay next for the motivation behind the system you just ran.