sase (pronounced "sassy") orchestrates coding agents into tracked, repeatable engineering workflows. It gives agent runs a durable operating layer: isolated workspaces, reusable prompts, scheduling, status, review state, and commit flow.

Full documentation: sase.sh.

Prerequisites:

• Python 3.12+
• uv
• One authenticated coding-agent CLI: Claude Code, Codex, Gemini CLI, Qwen Code, or OpenCode

SASE orchestrates an existing provider CLI; it does not replace that provider's install or authentication flow. Install SASE from PyPI, then run sase doctor as the readiness gate before launching your first agent:

uv tool install sase --python 3.12
sase version
sase doctor

After sase doctor reports a usable provider, try a read-only run from the repository or directory you want the agent to inspect:

sase run "#cd:$(pwd) summarize what this repository does; do not change files"
sase agents status

If sase doctor reports a missing provider executable or authentication gap, install and authenticate one of the supported CLIs, then run sase doctor again.

For the guided beginner path, follow the 15-minute quickstart.

Coding agents are useful one run at a time. Real engineering work needs coordination:

• Schedule, monitor, resume, and archive background agent runs.
• Keep prompts and multi-step workflows reusable instead of trapped in shell history.
• Track each unit of work with status, metadata, comments, mentors, and review state.
• Allocate and manage isolated workspaces for parallel work.
• Keep commit, PR, notification, and artifact flow tied back to the original work.

The goal is not to replace coding agents. The goal is to make agent-driven software engineering dependable.

• ACE - The interactive TUI for ChangeSpecs, live agents, notifications, automation, comments, and review.
• AXE - The background automation daemon for scheduled work, chop scripts, hooks, mentors, and workflow runs.
• XPrompt - Prompt templates and YAML workflows with reference expansion, typed inputs, output-variable handoffs, and workflow visualization.
• ChangeSpecs - Tracked CL/PR-sized units of work with lifecycle state, commits, comments, mentors, and metadata.
• Memory - Agent instruction memory loaded through AGENTS.md, keyword-triggered long-term context, audited agent reads, and human-reviewed write proposals.
• SDD and Beads - Spec-driven planning artifacts plus git-portable issue tracking for epics, phases, and dependencies.
• Commit finalizer - A provider-neutral post-invocation check that asks SASE-launched agents to commit dirty enforced workspaces, treats static singleton siblings as advisory, and auto-commits exact SDD status closeouts.
• Plugins - Provider boundaries for agents, VCS operations, workspaces, notifications, and external integrations.
• Editor integration - An xprompt LSP and JSON helper bridge for completions, snippets, hover, diagnostics, and jump-to-definition in companion editors.

sase doctor -v           # readable install, config, project, provider, and state report
sase version             # inspect the exact SASE packages loaded by this environment
sase ace                  # open the interactive control surface; press ,p for project lifecycle management
sase run "<prompt>"       # launch an agent or workflow
sase agents status        # inspect running agents
sase plan                 # review pending, approved, and inferred rejected plan proposals
sase bead onboard         # see the bead issue-tracking quick start
sase workspace list       # inspect numbered workspaces for the current project

When asking for help, attach sase doctor -v for a readable report or sase doctor -j when a machine-readable support artifact is easier to share.

SASE-launched agents use sase memory read ... -r/--reason ... and sase memory write ... when they need audited long-term memory access. Those commands require agent identity in the environment, so a normal human shell should start with sase memory list, sase memory review --list, and sase memory log.

SASE keeps durable state outside any one chat session:

• Rust core - Ported parsing, launch, notification, agent-scan, cleanup, and bead operations are served by the required sase_core_rs extension. Run sase core health before first use and after dependency changes.
• Project lifecycle - ProjectSpec metadata can mark a project active or inactive. Missing PROJECT_STATE is treated as active. Default launch pickers, ChangeSpec searches, project-local xprompt catalogs, broad mobile helper catalogs, and known-project VCS refs such as #gh:sase only use active projects. Use sase project list --state all, sase project show <project>, and sase project activate <project> when revisiting inactive work. Legacy on-disk archived and closed ProjectSpecs are read as inactive. In ACE, press ,p to manage lifecycle state, edit ProjectSpecs, mark projects for bulk lifecycle actions, or delete an obsolete SASE project directory. Deleting from that panel removes ~/.sase/projects/<project>/, not the workspace checkout.
• Numbered workspaces - Parallel agents run in numbered project checkouts. Workspace #0 is the primary checkout, #1 through #9 are reserved, and new claims allocate from #10 upward.
• Workspace roots - By default, numbered checkouts live under the platform state directory in a project-keyed managed root. Set workspace.root: adjacent to keep the legacy <primary>_<num>/ sibling layout, or use an absolute path for a custom managed-root base; sase workspace list, path, repair, cleanup, and migrate inspect and maintain that view. Normal sase run launches prepare their own workspaces; use sase workspace open 10 when you want to prepare a specific checkout for an external shell, editor, or debugging session.
• Prompt authoring surface - ACE's prompt input combines prompt history, snippets, Ctrl+T completion for directives, xprompts, slash skills, paths, and recent file references, plus a Ctrl+R recursive fuzzy file finder. Relative path lookup is prompt-aware: a resolvable #cd reference wins. When no #cd reference is present, registered workspace-provider refs and known-project refs such as #git:sase or #gh:sase-org/sase can root completion in that project checkout. If no prompt workspace ref resolves, ACE uses the TUI process directory.
• Provider retries - The LLM provider layer can retry matching provider errors, preserve the workspace across retries, and fall back to another model when configured. Claude adds built-in matching for context-limit, socket-close, and Claude CLI API-error output; per-provider retry counts, waits, and fallback policy live under llm_provider.retry.
• Configured sibling repos - Project and user config can expose related repositories to launched agents as workspace-matched directories. SASE records those paths in environment variables and agent metadata so cross-repo work uses the same numbered workspace as the main checkout, while singleton repos such as chezmoi can opt out with workspace.strategy: none.
• Named-agent handoffs - %name gives a producer a stable identity, and %wait starts consumers only after dependencies complete. A producer can publish small non-secret strings with sase var set KEY=VALUE before it exits; waited consumers load those values at startup as Jinja namespaces for prompt or workflow rendering, and ACE shows them in the producer's OUTPUT VARIABLES metadata panel.
• Plan approval pipeline - Planning agents submit Markdown plans with sase plan propose. ACE, notifications, and sase plan all read the same pending approval state; sase plan approve [id] -k <kind> writes the same response protocol as the TUI. Approval kinds decide whether the runner starts a coder without committing an SDD plan, commits the plan as a tale/epic/legend before the follow-up, or records the approved plan in SDD and stops there.
• Commit finalization - After a successful provider invocation inside a SASE-launched agent session, the provider-neutral finalizer checks the main workspace and configured Git sibling workspace directories for uncommitted changes. Static siblings (workspace.strategy: none) are reported as advisory work that the agent may commit when it made those changes, but they do not fail the run if they remain dirty. If the only enforced change is one tracked SDD markdown file under sdd/tales/, sdd/epics/, sdd/legends/, or sdd/myths/ whose leading front matter changes exactly from status: wip to status: done, SASE commits that closeout directly. Other dirty enforced workspaces trigger bounded follow-up invocations that tell the same agent to use the configured commit skill; if enforced workspaces are still dirty after the configured pass limit, the agent run fails with a clear artifact trail.
• Durable artifacts - Agent metadata, chats, notifications, prompt history, source-linked episode evidence, dismissed-agent bundles, saved agent groups, ChangeSpecs, SDD files, and beads are stored in predictable project/user directories so ACE, AXE, CLI commands, and external integrations can share state. Long-term memory reads and write proposals are also project-scoped and audited so agents can discover context without silently changing canonical memory files. ACE uses a persistent artifact index for its normal Agents-tab "visible inbox" - active plus recent completed, non-hidden rows - so startup does not scan all history. Use sase agents index status for a lightweight health check, verify to compare the index with source artifacts, and gc to rebuild the index and dismissed projection.

The full documentation lives at sase.sh. Start with:

• ACE TUI (local)
• Initialization (local)
• Memory (local)
• Episodes (local)
• AXE Automation (local)
• Spec-Driven Development (local)
• XPrompts (local)
• ChangeSpecs (local)
• ProjectSpec and project lifecycle (local)
• Beads (local)
• Workflows (local)
• Workspaces (local)
• Mentors (local)
• Commit Workflows (local)
• Plugins (local)
• LLM Providers (local)
• VCS Providers (local)
• Integration APIs (local)
• Notifications (local)
• Editor Integration (local)
• Agent Attachments (local)
• Mobile Gateway (local)
• Mobile MVP Runbook (local)
• Performance Runbook (local)
• Telemetry (local)
• Agent Revival Log (local)
• Rust Backend (local)
• CLI Reference (local)
• Configuration (local)
• Query Language (local)
• Architecture (local)
• Development (local)

The docs/ directory is a MkDocs Material site configured by mkdocs.yml. Run just docs-check for the strict docs build and just docs-pdf-check for the handbook PDF validation.

Requirements:

• Python 3.12+
• uv
• just

git clone https://github.com/sase-org/sase
cd sase
uv venv .venv
source .venv/bin/activate
just install
sase core health
sase ace

just install installs SASE in editable mode with development dependencies. When a sibling ../sase-core checkout is present and cargo is available, it also builds and installs the local sase_core_rs extension.

just install       # Install with dev deps
just fmt           # Auto-format code
just lint          # Run ruff, mypy, pyvision, keep-sorted, and SDD validation
just test          # Fast parallel test run, including PNG visual snapshots
just test-slow     # Slow pytest subset only
just test-visual   # ACE PNG visual regression snapshots only
just test-terminal-smoke  # Optional real-terminal ACE smoke test
just test-cov      # Parallel test run with coverage + 50% gate, including visual snapshots
just check         # All checks: formatting, lint, SDD validation, and tests
sase validate      # Validation: init --check plus sdd validate
just test-tox      # Test across Python 3.12, 3.13, 3.14
just clean         # Remove build artifacts
just build         # Build wheel + sdist

just test, just test-slow, just test-visual, and just test-cov size the pytest-xdist worker pool from local CPU count, capped at 16. Set SASE_PYTEST_WORKERS=<N> to override that value. Default test runs exclude slow and terminal-smoke tests but include the PNG visual snapshot suite. Use just test-visual for focused ACE PNG visual regression work, and accept intentional PNG golden changes with --sase-update-visual-snapshots only after inspecting .pytest_cache/sase-visual/.

Ported sase.core operations are served by the required Rust extension sase_core_rs, distributed as the sase-core-rs package. Normal installs pull a prebuilt wheel; source installs build from a sibling ../sase-core checkout when present. There is no pure-Python fallback for ported operations, so sase core health is the canonical install check.

sase builds on Boris Cherny's practical demonstration of parallel agentic development with multiple checkouts and tmux sessions. sase keeps that core insight - one developer supervising several agents - and adds structured workspaces, ChangeSpecs, XPrompts, SDD artifacts, ACE, and AXE around it.

The expanded acknowledgements live in docs/acknowledgements.md.

sase bead is influenced by Steve Yegge's beads, especially the idea that agents need a structured, persistent, dependency-aware memory layer rather than ad hoc TODO files. sase adapts that idea with SQLite, JSONL export, plan tiers, and multi-workspace aggregation.

The project name and direction were also influenced by Agentic Software Engineering: Foundational Pillars and a Research Roadmap, and XPrompt workflows were influenced by PDL: A Declarative Prompt Programming Language.