sagaflow 0.3.0

Temporal-backed workflow runtime for Claude Code skills

sagaflow

Run durable agent workflows that outlive your session.

The problem

Multi-agent skills for code review, debugging, and research spawn parallel subagents and thread their output back together through ad-hoc file-based state machines. When the session crashes — or a subagent wedges silently for hours — that state fragments, retries are brittle prose inside markdown, and there's no visibility into what's still in flight. Rolling a durable execution layer per skill duplicates a lot of work that Temporal already solves.

Quick start

pip install sagaflow
temporal server start-dev &
export ANTHROPIC_API_KEY=sk-ant-...
sagaflow launch hello-world --name alice --await
# → hello, alice

A DONE entry also lands in ~/.sagaflow/INBOX.md and fires a desktop notification. Kill your terminal mid-run and re-launch: the workflow resumes from the last completed activity.

Install

pip install sagaflow

Requirements:

• Python 3.11+
• Temporal CLI running locally: brew install temporal && temporal server start-dev
• An Anthropic API key: export ANTHROPIC_API_KEY=sk-ant-...

Optional: set ANTHROPIC_BASE_URL to route through any Anthropic-compatible proxy (Bedrock, a local model gateway, etc.).

Usage

Launch and wait for the result

sagaflow launch hello-world --name alice --await

Fire and forget; check the inbox later

sagaflow launch hello-world --name alice
sagaflow inbox
# [2026-04-22 14:33:22] hello-world-20260422-143322 DONE hello-world  hello, alice
sagaflow dismiss hello-world-20260422-143322

Diagnose a broken setup

sagaflow doctor
# [OK] temporal
# [OK] transport
# [WARN] worker: no worker polling; will auto-spawn on launch
# [OK] hook

How it works

sagaflow launch <skill> --await
        │
        ▼
preflight → auto-install SessionStart hook
         → auto-spawn worker daemon if none running
         → submit workflow to Temporal (localhost:7233)
         │
         ▼
worker daemon polls task queue "sagaflow"
         runs @workflow.defn → executes activities:
           • write_artifact     (file I/O)
           • spawn_subagent     (Anthropic SDK or `claude -p`)
           • emit_finding       (INBOX + desktop notify)
         │
         ▼
4-layer result-surfacing safety net:
  1. --await completion → caller prints
  2. ~/.sagaflow/INBOX.md (append-only)
  3. SessionStart hook → next Claude Code session surfaces unread
  4. desktop notification (osascript / notify-send)

If the worker crashes mid-run, the next sagaflow launch auto-spawns a fresh one and Temporal resumes from the last completed activity.

Built-in skills

sagaflow ships with 11 skills. Each is a Python package under skills/ that plugs into the runtime via register(registry):

Skill	What it does
hello-world	Framework smoke test — greets a name and emits a finding
deep-qa	Multi-round QA of docs, code, research, or skills with parallel critics and synthesis
deep-debug	Hypothesis-driven debugging: generate → judge → synthesize root-cause report
deep-research	WHO/WHAT/HOW/WHERE/WHEN/WHY dimension expansion with per-direction findings
deep-design	Draft spec → critique × N → redesign → final spec.md
deep-plan	Planner → Architect → Critic consensus loop with ADR output
proposal-reviewer	Claim extraction + 4-dimension critique + fact-check + assembly
team	Plan → PRD → N parallel workers → verify → fix loop
autopilot	Expand → plan → exec → qa → validate (3 judges) → completion report
loop-until-done	PRD + falsifiability judge + per-criterion verify loop until all pass
flaky-test-diagnoser	Multi-run N × → hypothesis generation → judge → report

All skills use the same transport layer (Anthropic SDK or claude -p subprocess) and the same 4-layer result-surfacing (INBOX → SessionStart hook → desktop notify → --await return).

Writing a new skill

See docs/SKILL-TEMPLATE.md. The minimal skill is skills/hello_world/ (~100 lines), which exercises every framework surface without importing anything skill-specific from the framework core.

Development

git clone https://github.com/npow/sagaflow
cd sagaflow
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

ruff check sagaflow tests skills
mypy sagaflow
pytest

# Opt-in end-to-end tests (require live Temporal + real Anthropic access)
SAGAFLOW_E2E=1 pytest

License

MIT