@@ -0,0 +1,169 @@
1+# Conveyor
2+
3+Conveyor turns what you say into code. You write a ticket, and a Claude Code agent works it alone in its own virtual machine, then hands the work back for review. The app you do this in is made of widgets that Conveyor builds the same way. Hold Ctrl, click any part of the app, and say what it should become.
4+
5+<video src="docs/demo.mp4" width="700" autoplay loop muted playsinline></video>
6+
7+[Watch the demo (10 s)](docs/demo.mp4). One sentence on an empty canvas becomes a working focus timer. The agent's build took about 2 minutes, sped up here.
8+
9+## How it works
10+
11+Conveyor has two halves: a daemon and an app.
12+
13+- **`conveyord`, the daemon,** keeps your projects and tickets as plain files in `~/.local/share/conveyor`. It moves each ready ticket into a fresh QEMU VM, starts a headless Claude Code agent there, and collects what the agent reports.
14+- **The app** shows your projects, boards, tickets, and code. Every part of it is a widget from your **widget library**, a Rust crate in its own git repo. The app loads each new build of the library while it runs, with no restart.
15+
16+An agent never runs on your machine. It works on a copy of your repo inside its VM, and it reports to the daemon with these commands:
17+
18+| Command | What the agent means by it |
19+|---|---|
20+| `conveyor decide` | I made a choice the ticket left open, and here is why. |
21+| `conveyor deviate` | Doing this well needs something outside the ticket. Here is what I did. |
22+| `conveyor block` | I need something only you can give, such as a key or an account. |
23+| `conveyor note` | Progress worth showing you. |
24+| `conveyor done` | Finished and committed. |
25+
26+These show up in the ticket's conversation, so you read a ticket's reasoning instead of its raw log.
27+
28+
29+
30+### Tickets land on your branch
31+
32+A ticket starts from the branch you have checked out. Its work is kept in `refs/conveyor/t-<id>`, a git ref that `git branch`, `git push --all`, and clones never see. When you move the ticket to **Done**, Conveyor merges it into your checked-out branch under the ticket's title. From there you open your own pull request, and nothing in it mentions Conveyor.
33+
34+### Ctrl+click changes the app
35+
36+Hold Ctrl and the app outlines the widget under the pointer, with its name and the element you point at.
37+
38+
39+
40+Click, and a prompt opens for that widget. Ask for a change to it, or for a new widget in that spot. Your words become a ticket on the `widgets` project, and an agent builds it in a VM like any other ticket.
41+
42+
43+
44+When the build passes, it goes on trial. The app loads it at once, and you try it out. Then hover the belt in the title bar and click **Keep** to merge the build into your library, or **Discard** to drop it. If a build breaks the app, start it with `--safe` to keep or discard builds without loading any widgets.
45+
46+## Get started
47+
48+You need:
49+
50+- Linux with KVM, or a Mac with Apple silicon.
51+- QEMU, `git`, `ssh`, and Python 3.
52+- Rust through `rustup`. The repo pins the toolchain in `rust-toolchain.toml`, and `rustup` installs it on the first build.
53+- Claude Code, logged in on this machine. Each agent gets a copy of your login.
54+- About 10 GB of disk for the base VM image, and 8 GB of free memory for each ticket that runs at once.
55+
56+Run every command from the repo's root.
57+
58+1. Build the daemon:
59+
60+ ```sh
61+ cargo build --release -p conveyor
62+ ```
63+
64+1. On a Mac, build the CLI that runs inside each VM. Run the `rustup` line once, and `cargo guest` after every daemon build:
65+
66+ ```sh
67+ rustup target add aarch64-unknown-linux-musl
68+ cargo guest
69+ ```
70+
71+1. Bake the base image that every ticket's VM starts from. The bake downloads Debian 13, installs the build tools and Claude Code, and warms a cargo cache. It takes about 6 minutes:
72+
73+ ```sh
74+ tools/bake.py bake
75+ ```
76+
77+1. Start the daemon, and leave it running:
78+
79+ ```sh
80+ ./target/release/conveyor daemon
81+ ```
82+
83+ On its first start, the daemon creates your widget library from `templates/library`.
84+
85+1. Build and open the app:
86+
87+ ```sh
88+ cargo app && ./target/app/release/conveyor-app
89+ ```
90+
91+ Build the app only with `cargo app`. The app and your widgets must share one standard library, so the alias links them dynamically.
92+
93+The app opens on an empty canvas. Click **+** in the taskbar to add a project, then write your first ticket.
94+
95+## Work a ticket
96+
97+1. Add a project: a git repo, or an empty folder that Conveyor turns into one. Use **+** in the taskbar, or the CLI:
98+
99+ ```sh
100+ ./target/release/conveyor project pomodoro ~/code/pomodoro
101+ ```
102+
103+1. Open the project's board (Ctrl+O, then **Board**) and write a ticket under **draft**. Say what should happen, and attach files if they help.
104+1. Move the ticket to **ready**. The daemon starts it as soon as the project has a free slot. Each project runs one ticket at a time unless you raise its slots.
105+1. Watch the belt in the title bar. It moves while any ticket runs, and hovering it lists them.
106+1. When the ticket reaches **review**, read its conversation and its diff, or click **Explore in editor** to browse its files.
107+1. Move it to **Done** to merge it into your checked-out branch. To ask for changes, click **Back to draft**, edit the ticket, and click **Ready**. The agent continues from its earlier work.
108+
109+A ticket moves through these states:
110+
111+| State | Meaning |
112+|---|---|
113+| `draft` | Being written. Nothing runs. |
114+| `ready` | Waiting for a free slot. |
115+| `running` | An agent is working it in a VM. |
116+| `review` | The agent called `done`. The work waits for you. |
117+| `parked` | The agent called `block`. Read its reason, change the ticket, and move it to ready. |
118+| `failed` | The run ended without `done`. Move it to ready to try again. |
119+| `done` | Merged. |
120+
121+Every new project starts with a draft called **Dev notes**. Move it to ready, and an agent adds a small script to your web app's dev build. With that script loaded, a Ctrl+click in your own running app files a ticket here, the same way it does in Conveyor.
122+
123+## Reference
124+
125+### CLI
126+
127+| Command | What it does |
128+|---|---|
129+| `conveyor daemon` | Runs `conveyord`. |
130+| `conveyor project SLUG PATH [SLOTS]` | Adds a project. |
131+| `conveyor ticket SLUG TITLE [BODY]` | Adds a ticket, ready to run. |
132+| `conveyor ls` | Lists every ticket. Works without the daemon. |
133+| `conveyor retry SLUG ID [NOTE]` | Runs a ticket again. The note shows in its conversation. |
134+| `conveyor call JSON` | Sends one request to the daemon, as the app does. `crates/conveyor/src/server.rs` lists the requests. |
135+
136+### Where things live
137+
138+All state is plain files under `~/.local/share/conveyor`:
139+
140+| Path | Contents |
141+|---|---|
142+| `projects/<slug>/project.json` | The project's path and its slots. |
143+| `projects/<slug>/tickets/<id>/ticket.md` | The ticket: its title and state in front matter, then its text. |
144+| `projects/<slug>/tickets/<id>/events.jsonl` | The ticket's conversation. |
145+| `projects/<slug>/tickets/<id>/stream.jsonl` | The agent's raw output. |
146+| `library/` | Your widget library, a git repo. |
147+| `trial/` | The library plus every build on trial. The app is built from here. |
148+| `secrets/` | Keys you add in the keychain widget. Agents get them as environment variables. |
149+| `images/base.qcow2` | The base VM image. |
150+| `app/` | The app's layout and settings. |
151+
152+### Repo layout
153+
154+| Path | Contents |
155+|---|---|
156+| `crates/conveyor` | The daemon, its CLI, and the commands an agent runs in its VM. |
157+| `crates/conveyor-app` | The app, built as a dynamic library so widget builds load into it. |
158+| `crates/conveyor-widgets` | Builds your widget library for the app. |
159+| `templates/library` | The template every widget library starts from. `api.rs` is the contract between the app and your widgets. |
160+| `tools/bake.py` | Bakes the base VM image. |
161+
162+## Develop Conveyor
163+
164+| Task | Command |
165+|---|---|
166+| Fast tests | `cargo test --release -p conveyor -- --skip trial` |
167+| Trial test, which builds the real app against a throwaway library | `cargo test --release -p conveyor trial -- --nocapture` |
168+
169+[CLAUDE.md](CLAUDE.md) has the rules for working on Conveyor itself, for people and agents alike.