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