Susan

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

A run of the ask workflow asks its question and stops. You answer in the dashboard, and a second run picks up from your answer.

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

  1. Install the suite

    One command pulls the images and starts the dashboard and the operator on your computer.

  2. Hand over the work

    Start a run from the dashboard, on an item (a unit of work of one of your projects).

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

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

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

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

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

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

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

github.com/gplanchat/awf-workflow-openspec-tdd

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.

Try it on your workstation