xonecas.io
8447
Co

conveyor / files

conveyor / README.md

9.4 KB
1# Conveyor
2
3Conveyor 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
11Conveyor 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
16An 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
26These show up in the ticket's conversation, so you read a ticket's reasoning instead of its raw log.
27
28![A ticket in review: the request, the agent's decisions, and its reply, next to the board](docs/review.png)
29
30### Tickets land on your branch
31
32A 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
36Hold Ctrl and the app outlines the widget under the pointer, with its name and the element you point at.
37
38![Holding Ctrl outlines the board's review column](docs/inspect.png)
39
40Click, 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![Ctrl+click on the board opens a prompt for it](docs/ctrl-click.png)
43
44When 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### Ctrl+click your own web app
47
48Dev notes bring Ctrl+click to the web apps your projects build. The daemon serves a small script, `devnotes.js`, on `127.0.0.1:7717`. Load it in your app's dev build:
49
50```html
51<script src="http://127.0.0.1:7717/devnotes.js" data-project="pomodoro" async onerror="this.remove()"></script>
52```
53
54Hold Ctrl and the script outlines the element under the pointer. Click it, write what should change, and press Enter. The note becomes a ticket in the project that `data-project` names. The ticket carries the page's URL, the element's selector, text, and HTML, and the window size, so the agent can find the element in the source. Check **Ready?** to start the ticket at once, or leave it unchecked to file a draft. Your app never sees a click made while Ctrl is held.
55
56If your app uses Ctrl+click itself, set `data-key` on the tag to `alt`, `shift`, or `meta`.
57
58Only pages served from localhost can file notes, because every ticket runs an agent that holds your keys. When the daemon isn't running, `onerror` removes the tag and your app runs as usual.
59
60You don't have to add the tag yourself. Every new project starts with a draft called **Dev notes** that asks an agent to add it to the dev build only, and to prove that a production build leaves it out. Edit the draft to fit the project, then move it to ready.
61
62Dev notes are based on the click-to-note overlay from [claudeweaver](https://github.com/statico/claudeweaver), by statico, under the MIT license.
63
64## Get started
65
66You need:
67
68- Linux with KVM, or a Mac with Apple silicon.
69- QEMU, `git`, `ssh`, and Python 3.
70- Rust through `rustup`. The repo pins the toolchain in `rust-toolchain.toml`, and `rustup` installs it on the first build.
71- Claude Code, logged in on this machine. Each agent gets a copy of your login.
72- About 10 GB of disk for the base VM image, and 8 GB of free memory for each ticket that runs at once.
73
74Run every command from the repo's root.
75
761. Build the daemon:
77
78	```sh
79	cargo build --release -p conveyor
80	```
81
821. On a Mac, build the CLI that runs inside each VM. Run the `rustup` line once, and `cargo guest` after every daemon build:
83
84	```sh
85	rustup target add aarch64-unknown-linux-musl
86	cargo guest
87	```
88
891. 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:
90
91	```sh
92	tools/bake.py bake
93	```
94
951. Start the daemon, and leave it running:
96
97	```sh
98	./target/release/conveyor daemon
99	```
100
101	On its first start, the daemon creates your widget library from `templates/library`.
102
1031. Build and open the app:
104
105	```sh
106	cargo app && ./target/app/release/conveyor-app
107	```
108
109	Build the app only with `cargo app`. The app and your widgets must share one standard library, so the alias links them dynamically.
110
111The app opens on an empty canvas. Click **+** in the taskbar to add a project, then write your first ticket.
112
113## Work a ticket
114
1151. Add a project: a git repo, or an empty folder that Conveyor turns into one. Use **+** in the taskbar, or the CLI:
116
117	```sh
118	./target/release/conveyor project pomodoro ~/code/pomodoro
119	```
120
1211. 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.
1221. 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.
1231. Watch the belt in the title bar. It moves while any ticket runs, and hovering it lists them.
1241. When the ticket reaches **review**, read its conversation and its diff, or click **Explore in editor** to browse its files.
1251. 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.
126
127A ticket moves through these states:
128
129| State | Meaning |
130|---|---|
131| `draft` | Being written. Nothing runs. |
132| `ready` | Waiting for a free slot. |
133| `running` | An agent is working it in a VM. |
134| `review` | The agent called `done`. The work waits for you. |
135| `parked` | The agent called `block`. Read its reason, change the ticket, and move it to ready. |
136| `failed` | The run ended without `done`. Move it to ready to try again. |
137| `done` | Merged. |
138
139Every new project starts with a draft called **Dev notes**. Move it to ready to [Ctrl+click your own web app](#ctrlclick-your-own-web-app) and file tickets from it.
140
141## Reference
142
143### CLI
144
145| Command | What it does |
146|---|---|
147| `conveyor daemon` | Runs `conveyord`. |
148| `conveyor project SLUG PATH [SLOTS]` | Adds a project. |
149| `conveyor ticket SLUG TITLE [BODY]` | Adds a ticket, ready to run. |
150| `conveyor ls` | Lists every ticket. Works without the daemon. |
151| `conveyor retry SLUG ID [NOTE]` | Runs a ticket again. The note shows in its conversation. |
152| `conveyor call JSON` | Sends one request to the daemon, as the app does. `crates/conveyor/src/server.rs` lists the requests. |
153
154### Where things live
155
156All state is plain files under `~/.local/share/conveyor`:
157
158| Path | Contents |
159|---|---|
160| `projects/<slug>/project.json` | The project's path and its slots. |
161| `projects/<slug>/tickets/<id>/ticket.md` | The ticket: its title and state in front matter, then its text. |
162| `projects/<slug>/tickets/<id>/events.jsonl` | The ticket's conversation. |
163| `projects/<slug>/tickets/<id>/stream.jsonl` | The agent's raw output. |
164| `library/` | Your widget library, a git repo. |
165| `trial/` | The library plus every build on trial. The app is built from here. |
166| `secrets/` | Keys you add in the keychain widget. Agents get them as environment variables. |
167| `images/base.qcow2` | The base VM image. |
168| `app/` | The app's layout and settings. |
169
170### Repo layout
171
172| Path | Contents |
173|---|---|
174| `crates/conveyor` | The daemon, its CLI, and the commands an agent runs in its VM. |
175| `crates/conveyor-app` | The app, built as a dynamic library so widget builds load into it. |
176| `crates/conveyor-widgets` | Builds your widget library for the app. |
177| `templates/library` | The template every widget library starts from. `api.rs` is the contract between the app and your widgets. |
178| `tools/bake.py` | Bakes the base VM image. |
179
180## Develop Conveyor
181
182| Task | Command |
183|---|---|
184| Fast tests | `cargo test --release -p conveyor -- --skip trial` |
185| Trial test, which builds the real app against a throwaway library | `cargo test --release -p conveyor trial -- --nocapture` |
186
187[CLAUDE.md](CLAUDE.md) has the rules for working on Conveyor itself, for people and agents alike.