Your first run

This walkthrough takes about fifteen minutes. Examples use the label demo and <path> placeholders; they do not use real names.

A real run starts your configured Claude Code, which uses your account and plan. The sample task is small. Intake, when you use it, starts with grill.

1. Make a sample repoCopy Anchor Link

Create a folder demo-app with one shell script and a test, then commit it. These commands only need git and a shell.

mkdir demo-app
cat > demo-app/hello.sh <<'EOF'
#!/bin/sh
echo hello
EOF
cat > demo-app/hello_test.sh <<'EOF'
#!/bin/sh
set -eu
got=$(sh hello.sh)
test "$got" = "hello"
EOF
chmod +x demo-app/hello.sh demo-app/hello_test.sh
git -C demo-app init -b main
git -C demo-app add hello.sh hello_test.sh
git -C demo-app -c user.name=demo -c user.email=demo@localhost commit -m "Initial commit"
( cd demo-app && sh hello_test.sh )

<path> in the next step is this demo-app folder.

2. Run kusaw up --openCopy Anchor Link

kusaw up --open

kusaw up --open starts the supervisor with serve and ui and opens the Dashboard; kusaw status shows them.

3. Create the factory from the DashboardCopy Anchor Link

With no factories yet, the Dashboard opens the "New factory" dialog by itself. If you close it, the "No factories yet" page has a "Create a factory" button that opens it again, and the sidebar button "New factory" works too.

The "New factory" dialog has fields "Name" and "Folder for kusaw.yaml", a "Repos" legend, placeholders "label" and "path", a "+ Add another repo" button, and the submit button "Create factory" (shows "Creating…" while saving).

Set Name to demo, point a repo label app at <path>, and create the factory. The Dashboard then opens the new factory's Runs page.

4. Add hello.md as a task from the DashboardCopy Anchor Link

A task is a short Markdown file: a title, what to change, and a ## Verification section with the test command. Save this as hello.md:

cat > hello.md <<'EOF'
---
id: demo-hello
title: Print hello, world
repos: [app]
---

## Goal

Make `hello.sh` print `hello, world`.

## Scope

The hello script and its test.

## Acceptance criteria

- [ ] `sh hello.sh` prints `hello, world`.

## Verification

- `sh hello_test.sh`

## Out of scope

Other files.
EOF

From the Dashboard, use "Add task". Tabs: "From a spec file" and "Start intake". Field: "Spec file on this computer". Buttons: "Check spec", "Cancel". Intake fields: "Idea", "Repo (optional)".

Select the file on the "From a spec file" tab and submit with "Add task".

Or from the CLI: kusaw add hello.md --factory demo.

5. Watch itCopy Anchor Link

kusaw status --factory demo

The same run is on the run page in the Dashboard.

6. Review and approveCopy Anchor Link

If the pipeline has a gate, the run waits at waiting_for_human. Approve it with kusaw approve <run> or the Dashboard button. The default pipeline has no gate, so a first run does not stop for approval.

7. Stop the factoryCopy Anchor Link

Stop with kusaw down.

When the run has finished, what success looks like is how to read the result.

Using only the CLICopy Anchor Link

kusaw new demo --repo app=<path>
kusaw validate --factory demo

kusaw new writes kusaw.yaml and registers the factory. kusaw validate --factory demo checks that config.

kusaw serve --factory demo

kusaw ui --open --factory demo

kusaw serve is the worker. kusaw ui --open is the Dashboard at 127.0.0.1. Leave serve running while you add the task.

To keep both running in the background instead, use kusaw up --factory demo (add --open to open the Dashboard). It starts serve and ui under a supervisor and restarts them if they crash. kusaw down stops them. kusaw logs serve -f follows the serve log, and kusaw service install starts kusaw up at sign-in (systemd, launchd, or Task Scheduler).

cat > hello.md <<'EOF'
---
id: demo-hello
title: Print hello, world
repos: [app]
---

## Goal

Make `hello.sh` print `hello, world`.

## Scope

The hello script and its test.

## Acceptance criteria

- [ ] `sh hello.sh` prints `hello, world`.

## Verification

- `sh hello_test.sh`

## Out of scope

Other files.
EOF
kusaw add hello.md --factory demo

kusaw add checks the spec and queues a run.

kusaw status --factory demo

The same run is on the run page in the Dashboard.