Your AI software factory, on the machines you choose
Hand your changes to development agents and keep the decisions in your hands. Susan starts each workflow in its own container, follows every run (one execution of a workflow) in one dashboard, and stops to ask a person of your team when a choice comes up. It runs on your own computer today, and soon on the homelab your team shares.
Try it on your workstationor on your homelab
AI software factory · Open source under Apache 2.0
One agent in a terminal is not a factory
One agent in your terminal
- It stops as soon as you close the terminal or your laptop goes to sleep.
- Its question waits in a window nobody is looking at.
- Afterwards, nobody can tell what it did or what it cost in tokens.
The same work in Susan
- Each run lives in its own container, independent of your terminal.
- Its question appears in the “Waiting for you” view, and the run resumes as soon as you answer.
- Every run keeps its outcome and the tokens it used, model by model.
What your team gains
A production line for your changes
Hand over OpenSpec changes (a written proposal, design and task list). The factory workflows apply several in parallel, one git worktree each, write the test before the code of every task, then merge them one at a time and run your end to end test.
Every run in one place
The dashboard lists the runs of all your projects with their state: queued, running, completed, failed, cancelled or lost.
Questions reach a person
When a run needs a decision, it asks and stops. Your answer starts a new run that picks up from there.
One container per run
Each run works apart from the others: a Docker container on a workstation, a pod with mutual TLS and a network policy on a cluster.
How it works
Install the suite
One command pulls the images and starts the dashboard and the operator on your computer.
Hand over the work
Start a run from the dashboard, on an item (a unit of work of one of your projects).
Decide and review
Answer the questions waiting for you. The run resumes, and you review what it produced.
The recommended way to work: openspec-tdd
openspec-tdd takes each change along a short, checked path. You write it down before anyone codes it, fresh eyes review it, a person accepts it, and the code is built test first. The run image ships its AWF workflows, and its /flow commands drive them from Claude Code.
Explore the idea
Think it through with the code at hand. Elephant Goldfish Model (EGM) reviewers, fresh agents who hold none of your context, challenge it, and the agreed direction becomes a brief.
Propose the change
An agent drafts the OpenSpec change (proposal, design, specs and tasks) in its own git worktree. Gates check its scope, strict validation, spec deltas and Definition of Done before the commit.
Review with fresh eyes
Seven EGM reviewers, each with read-only tools, read the change. Their Blockers come to you, and you settle each finding before the next step.
Accept it yourself
Your acceptance is recorded with your name, the date and a fingerprint of the Definition of Done, and the change merges into main without being pushed. No agent takes part.
Build it test first
Each slice of code goes through RED (a failing test), GREEN (the code that makes it pass) and a review, in the worktree of the change. Several changes can run in parallel.
Archive what is done
Once every task is checked, the deltas join the main specs, the Definition of Done runs again, and the change is archived.
Only you can waive a gate, with a reason, for 30 days at most. Read openspec-tdd on GitHub
Ready from the first run
The run image ships two packs of AWF workflows, so your first run can already apply a change.
openspec-tdd
The recommended way of working described above: from the OpenSpec proposal to the code, with an EGM review of the design and a test before each piece of code.
factory
Applies several OpenSpec changes in parallel, one git worktree per change, merges them one at a time and writes a JSON report.
One suite for every team
Start alone on your computer, then share a homelab with your team. Both setups run the same dashboard, the same operator and the same workflows; only the engine that starts each run changes.
What stays with you
- Your repositories
- On your Git forge
- Your secrets and the run logs
- On the machines that run Susan
- Prompts and the code excerpts an agent reads
- Sent to the provider of the AI model you configure, when it is a cloud model
Questions
What do I need to try it?
Docker with Compose v2, curl, and port 8090 free on 127.0.0.1. A forge is optional: connect a Forgejo or Gitea forge to follow pull requests.
Does Susan include an AI model?
No. The workflows call the agent and the model you configure. With a cloud model, the prompts and the code excerpts the agent reads go to that model’s provider.
Does it work with my language?
The factory workflows run the test commands you write in .awf/factory.json. Any language whose test runner writes a JUnit report fits.
What happens when my computer restarts?
Docker starts the dashboard and the operator again. Runs, the dashboard database and the keys are kept in Docker volumes. A run whose container disappeared ends as lost.
How do I remove it?
In the .susan folder of your home directory, run docker compose down -v, then delete the folder. Runs still in progress keep their containers: remove them first.
Can my whole team use it?
On a workstation, the dashboard listens on 127.0.0.1 only. The homelab setup, a MicroK8s cluster shared by a team, is coming soon.
What if we outgrow a homelab?
Susan covers one workstation and a homelab of a few machines. Beyond that, a managed platform from a cloud provider fits better.
Is the dashboard in English?
Not yet: the dashboard interface is in French today. This site is in English and French.
Is it free?
Yes. Susan is released under the Apache License 2.0. It runs workflows with AWF, a separate project published under its own license.
Can someone operate it for us?
Yes, in France. See Operated for you.
Start your AI software factory today
Free and open source. Start on your own computer, and bring your team in when it is ready.