sase 0.7.0

Structured Agentic Software Engineering

sase - Structured Agentic Software Engineering

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.

Quick start

Prerequisites:

• Python 3.12+
• uv
• One authenticated coding-agent CLI: Claude Code, Codex, Antigravity CLI (agy), 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 agent list

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.

Why sase

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.

Works with your agents

Agent	Status
Claude Code	Supported
Antigravity CLI (agy)	Supported
Codex	Supported
Qwen Code	Supported
OpenCode	Supported

Core pieces

• 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 with short-term notes inlined directly into a generated AGENTS.md (and provider files such as CLAUDE.md kept as full copies of it), 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 linked repos 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.

Common commands

sase init -c             # check initialization drift without writing files
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 # for the Admin Center (Config / Logs / Projects / Tasks / Updates / XPrompts)
sase run "<prompt>"       # launch an agent or workflow
sase agent list          # inspect running agents
sase plan                 # review pending proposals, approvals, and inferred rejected archive rows
sase bead onboard         # see the bead issue-tracking quick start
sase plugin list         # browse built-in/community plugins and update indicators
sase update -n           # preview a SASE core + installed-plugin update
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.

Operational model

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 # and switch to the Projects tab of the SASE Admin Center to manage lifecycle state, edit ProjectSpecs, mark projects for bulk lifecycle actions, or delete an obsolete SASE project directory. Deleting from that tab removes ~/.sase/projects/<project>/, not the workspace checkout.
• Update workflow - ACE caches latest-version checks by default, shows startup and top-bar update signals when SASE or installed plugins are behind, and uses the Admin Center Updates tab for review. That tab shows SASE core/plugin versions, optional incoming commit previews, and dry-run confirmation modals; press u for full sase update or U for the highlighted plugin when that row has an update available. Successful changed updates from ACE restart ACE and axe, and self-updates can show a one-shot post-update confirmation toast.
• 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 -r "<reason>" 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. Typing + at the absolute start of the prompt, or #+ at a token boundary, opens a project/ChangeSpec picker for active launchable projects and active PR-sized ChangeSpecs; accepting a row inserts the canonical VCS workspace tag such as #gh:sase. If no prompt workspace ref resolves, ACE uses the TUI process directory. When ACE loads a prompt with literal top-level --- multi-agent separators, it renders a stack of prompt panes so each agent segment can be edited, reordered, launched individually, or submitted together in top-to-bottom order. In prompt NORMAL mode, use g- to add panes, gj/gk to focus panes, and gJ/gK to reorder them. Prompt-level frontmatter is edited from the Frontmatter Panel with g=, the active pane can be stashed with Ctrl+S, all non-empty panes can be bundled into one stash row with gs, the current stack can overwrite a pinned stash with gS, and the current stack can be saved as a reusable xprompt with gx; open the unified stashed-prompt picker with Ctrl+G p from the prompt bar or @ from the main ACE tabs. Ctrl+P moves through recent workspace prefixes toward older entries and Ctrl+N toward newer entries; both pass through a no-prefix stop. Use %wait when one segment must wait for another to finish.
• 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 linked repos - Project and user config can expose related repositories to launched agents as workspace-matched directories via the linked_repos key (the legacy sibling_repos key still works as a deprecated alias). 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. ACE uses that metadata for live context: dirty suffix-strategy linked repos can appear in a non-terminal agent's DELTAS section, and linked workspaces opened inside the agent with sase workspace open -p <linked_repo> -r "<reason>" <workspace_num> appear in the SASE CONTEXT WORKSPACES lane and the t tmux chooser. In that command, -p/--project names the configured linked repo's backing project record.
• 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> and sase plan reject [id] write 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. A no-feedback rejection writes the response first, then attempts to kill and dismiss the matching planner row when it can be found.
• Commit finalization - After a successful provider invocation inside a SASE-launched agent session, the provider-neutral finalizer checks the main workspace and enforces only configured numbered Git linked-repo workspaces opened during the run with sase workspace open -p .... Static linked repos (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, 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 agent index status for a lightweight health check, verify to compare the index with source artifacts, and gc to rebuild the index and dismissed projection.

Keep reading

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

• ACE TUI (local)
• Initialization (local)
• Memory (local)
• AXE Automation (local)
• Spec-Driven Development (local)
• XPrompts (local)
• Prompt History (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.

Development

Install from source

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.

Verification

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/.

Required Rust core

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.

Acknowledgements

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.

License

sase is licensed under the MIT License. See LICENSE.