xonecas.io
8447
Co

conveyor / files

conveyor / CLAUDE.md

4.4 KB
1# Conveyor
2
3Conveyor turns what the user says into code. `conveyord` keeps projects and tickets as plain files, and works each ready ticket with a headless Claude Code agent inside its own QEMU VM. The app's whole UI is the user's widget library. The user holds Ctrl, clicks a widget, and says what it should become, and those words become a ticket on the library.
4
5## Layout
6
7- `crates/conveyor`: one binary for the daemon (`conveyor daemon`), its CLI, and the verbs an agent runs inside its VM (`note`, `decide`, `deviate`, `block`, `place`, `done`).
8- `crates/conveyor-app`: the app. It's a dylib, so new widget builds load into the running process.
9- `crates/conveyor-widgets`: the user's library (`~/.local/share/conveyor/library`, or `$CONVEYOR_LIBRARY`), built as a dylib the app loads. Before the library exists, it builds the template.
10- `templates/library`: the template every library starts from, and is kept in step with. See [The template ships to every user](#the-template-ships-to-every-user).
11- `tools/bake.py`: bakes the base VM image that every ticket's VM overlays.
12
13Every source file opens with a `//!` comment that says what it does. `crates/conveyor/src/server.rs` lists the daemon's socket ops.
14
15## Commands
16
17Run them from the repo's root.
18
19| Task | Command |
20|---|---|
21| Run the daemon | `cargo build --release -p conveyor && ./target/release/conveyor daemon` |
22| Run the app | `cargo app && ./target/app/release/conveyor-app` (`--safe` opens safe mode) |
23| Fast tests | `cargo test --release -p conveyor -- --skip trial` |
24| Trial test | `cargo test --release -p conveyor trial -- --nocapture` |
25| Bake the base image | Delete `~/.local/share/conveyor/images/base.qcow2`, then run `tools/bake.py bake` (about 6 minutes). |
26| Guest CLI, on macOS | Run `rustup target add aarch64-unknown-linux-musl` once, then `cargo guest` after every daemon build. |
27
28Build the app only with `cargo app` (`.cargo/config.toml`). The app and the widget builds must share one std and one Rune, so the alias links them dynamically, in their own target dir. A plain `cargo build` builds only the daemon.
29
30The trial test builds the real app against a throwaway library, so its first run takes minutes. It runs with its own `HOME` under `target/trial-test`.
31
32## Leave the user's state alone
33
34- `~/.local/share/conveyor` holds the user's real projects, tickets, library, secrets, and base image. Conveyor is in daily use. Don't delete or rewrite anything there.
35- A daemon start marks every running ticket failed and stops its VM. Don't restart a daemon you didn't start.
36
37## The template ships to every user
38
39`templates/library` isn't sample code. On every start, the daemon copies the files listed in `OWNED` (`crates/conveyor/src/library.rs`) into the user's library and commits them.
40
41- `api.rs` is the contract with every widget the user has. The app compiles it in, and so does the preview. A changed signature breaks the user's widgets.
42- `CLAUDE.md` is the prompt every widget agent reads, and `AGENTS.md` links to it. It costs context on every widget ticket, so keep it to what an agent can't learn from `api.rs`.
43- `widgets/` is the starter kit for a new library. Changing it doesn't change an existing library.
44
45`crates/conveyor/src/rules.md` and `crates/conveyor/src/devnotes.md` are prompts too. Every agent gets `rules.md` in its system prompt. `devnotes.md` is the draft ticket a new project starts with.
46
47## Keep the base image in step
48
49Each ticket's VM starts from the base image's warm cargo cache. Rebake when any of these change, or every ticket rebuilds Rune (38 s instead of 12 s):
50
51- `templates/library/preview/Cargo.toml`
52- `templates/library/Cargo.lock`
53- the bake's package list in `tools/bake.py`
54
55Rune is pinned to one git rev in `Cargo.toml` and in `templates/library/preview/Cargo.toml`. The Rust toolchain is pinned in both `rust-toolchain.toml` files. Change each pair together.
56
57## Conventions
58
59- The dependencies are serde, serde_json, and Rune. Use std and the system's programs (`git`, `ssh`, `qemu`, `curl`) before a crate. Ask before you add one.
60- Keep state in plain files (JSON, JSONL, Markdown, and TSV), read with serde.
61- Conveyor runs on Linux with KVM and on macOS with HVF. Code that touches processes, linking, or QEMU must work on both.
62- Write a commit's subject as one present-tense sentence that says what changed for the user, such as "Done merges a code ticket's branch into main, as Keep does for widgets".