Metadata-Version: 2.4
Name: sase
Version: 0.1.5
Summary: Structured Agentic Software Engineering
Project-URL: Homepage, https://sase.sh/
Project-URL: Documentation, https://sase.sh/
Project-URL: Repository, https://github.com/sase-org/sase
Project-URL: Issues, https://github.com/sase-org/sase/issues
Author: Bryan Bugyi
Maintainer: Bryan Bugyi
License-Expression: MIT
Keywords: agentic software engineering,automation,coding agents,developer tools,workflow orchestration
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Version Control
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: jinja2
Requires-Dist: jsonschema
Requires-Dist: langchain-core
Requires-Dist: pillow
Requires-Dist: plotext
Requires-Dist: pluggy
Requires-Dist: prometheus-client
Requires-Dist: pyinstrument
Requires-Dist: pyyaml
Requires-Dist: rich
Requires-Dist: sase-core-rs<0.2.0,>=0.1.1
Requires-Dist: schedule
Requires-Dist: textual[syntax]>=0.45.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: hypothesis; extra == 'dev'
Requires-Dist: inline-snapshot; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-mock; extra == 'dev'
Requires-Dist: pytest-xdist; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: tox; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material<10,>=9.7; extra == 'docs'
Requires-Dist: mkdocs-rss-plugin<2,>=1.18; extra == 'docs'
Provides-Extra: docs-pdf
Requires-Dist: mkdocs-exporter<7,>=6.2; extra == 'docs-pdf'
Requires-Dist: mkdocs-material<10,>=9.7; extra == 'docs-pdf'
Requires-Dist: mkdocs-rss-plugin<2,>=1.18; extra == 'docs-pdf'
Requires-Dist: pypdf<7,>=5; extra == 'docs-pdf'
Provides-Extra: terminal-smoke
Requires-Dist: pexpect<5,>=4.9; extra == 'terminal-smoke'
Requires-Dist: pyte<1,>=0.8; extra == 'terminal-smoke'
Provides-Extra: visual
Requires-Dist: cairosvg<3,>=2.7; extra == 'visual'
Description-Content-Type: text/markdown

# sase - Structured Agentic Software Engineering

[![Docs](https://img.shields.io/badge/docs-sase.sh-3b82f6?logo=readthedocs&logoColor=white)](https://sase.sh/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![mypy](https://img.shields.io/badge/type_checker-mypy-blue.svg)](https://mypy-lang.org/)
[![pytest](https://img.shields.io/badge/tests-pytest-blue.svg)](https://docs.pytest.org/)
[![tox](https://img.shields.io/badge/ci-tox-yellow.svg)](https://tox.wiki/)

**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](https://sase.sh/).**

## Quick start

Prerequisites:

- Python 3.12+
- [uv](https://docs.astral.sh/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:

```bash
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:

```bash
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](https://sase.sh/blog/posts/hello-sase-your-first-15-minutes/).

## 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](https://docs.anthropic.com/en/docs/claude-code) | **Supported** |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli)     | **Supported** |
| [Codex](https://github.com/openai/codex)                      | **Supported** |
| [Qwen Code](https://github.com/QwenLM/qwen-code)              | **Supported** |
| [OpenCode](https://opencode.ai/)                              | **Supported** |

<img src="docs/images/sase_overview.png" alt="Overview of SASE coordinating parallel coding agents, isolated workspaces, and durable workflow state" width="800">

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

## Common commands

```bash
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 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`.

## 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 `,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.
- **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.

## Keep reading

The full documentation lives at **[sase.sh](https://sase.sh/)**. Start with:

- [ACE TUI](https://sase.sh/ace/) ([local](docs/ace.md))
- [Initialization](https://sase.sh/init/) ([local](docs/init.md))
- [Memory](https://sase.sh/memory/) ([local](docs/memory.md))
- [Episodes](https://sase.sh/episodes/) ([local](docs/episodes.md))
- [AXE Automation](https://sase.sh/axe/) ([local](docs/axe.md))
- [Spec-Driven Development](https://sase.sh/sdd/) ([local](docs/sdd.md))
- [XPrompts](https://sase.sh/xprompt/) ([local](docs/xprompt.md))
- [ChangeSpecs](https://sase.sh/change_spec/) ([local](docs/change_spec.md))
- [ProjectSpec and project lifecycle](https://sase.sh/project_spec/) ([local](docs/project_spec.md))
- [Beads](https://sase.sh/beads/) ([local](docs/beads.md))
- [Workflows](https://sase.sh/workflow_spec/) ([local](docs/workflow_spec.md))
- [Workspaces](https://sase.sh/workspace/) ([local](docs/workspace.md))
- [Mentors](https://sase.sh/mentors/) ([local](docs/mentors.md))
- [Commit Workflows](https://sase.sh/commit_workflows/) ([local](docs/commit_workflows.md))
- [Plugins](https://sase.sh/plugins/) ([local](docs/plugins.md))
- [LLM Providers](https://sase.sh/llms/) ([local](docs/llms.md))
- [VCS Providers](https://sase.sh/vcs/) ([local](docs/vcs.md))
- [Integration APIs](https://sase.sh/integrations/) ([local](docs/integrations.md))
- [Notifications](https://sase.sh/notifications/) ([local](docs/notifications.md))
- [Editor Integration](https://sase.sh/editor/) ([local](docs/editor.md))
- [Agent Attachments](https://sase.sh/agent_images/) ([local](docs/agent_images.md))
- [Mobile Gateway](https://sase.sh/mobile_gateway/) ([local](docs/mobile_gateway.md))
- [Mobile MVP Runbook](https://sase.sh/mobile_mvp_runbook/) ([local](docs/mobile_mvp_runbook.md))
- [Performance Runbook](https://sase.sh/perf_runbook/) ([local](docs/perf_runbook.md))
- [Telemetry](https://sase.sh/telemetry/) ([local](docs/telemetry.md))
- [Agent Revival Log](https://sase.sh/troubleshooting/agent-revival/) ([local](docs/troubleshooting/agent-revival.md))
- [Rust Backend](https://sase.sh/rust_backend/) ([local](docs/rust_backend.md))
- [CLI Reference](https://sase.sh/cli/) ([local](docs/cli.md))
- [Configuration](https://sase.sh/configuration/) ([local](docs/configuration.md))
- [Query Language](https://sase.sh/query_language/) ([local](docs/query_language.md))
- [Architecture](https://sase.sh/architecture/) ([local](docs/architecture.md))
- [Development](https://sase.sh/development/) ([local](docs/development.md))

The `docs/` directory is a MkDocs Material site configured by [mkdocs.yml](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](https://docs.astral.sh/uv/)
- [just](https://github.com/casey/just)

```bash
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

```bash
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`](docs/rust_backend.md),
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](docs/acknowledgements.md).

`sase bead` is influenced by Steve Yegge's [beads](https://github.com/steveyegge/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](https://arxiv.org/abs/2509.06216), and
XPrompt workflows were influenced by [PDL: A Declarative Prompt Programming Language](https://arxiv.org/abs/2410.19135).
