AGENTS.md

1## Building
2 
3UTM **cannot** build without prebuilt native dependencies (QEMU, SPICE, …) staged
4into `sysroot-*` directories at the repo root. Get them from the project's GitHub
5Actions `Sysroot-*` artifacts — don't build them manually unless you're modifying a
6dependency (it's slow and fragile). Then build with `./scripts/build_utm.sh` and
7sign/package with `./scripts/package*.sh`. Setup, platform/arch names, schemes, and
8signing: `Documentation/iOSDevelopment.md`.
9 
10## Architecture
11 
12Layered: platform-independent backend (`Services/`, `Configuration/`) + SwiftUI
13frontend (`Platform/`). Full picture: `Documentation/Architecture.md`. Load-bearing
14gotchas:
15 
16- **Two VM backends** behind the `UTMVirtualMachine` protocol — `UTMQemuVirtualMachine`
17  (QEMU, via the QEMUKit/CocoaSpice packages) and `UTMAppleVirtualMachine`
18  (Virtualization.framework, macOS-only). Most backend code branches on which.
19- **Config is the serialization format** — parallel `Codable` trees
20  `UTMQemuConfiguration` and `UTMAppleConfiguration` (PLIST in the `.utm` bundle).
21  Add new fields there; don't extend the `Configuration/Legacy/` readers.
22- **macOS runs QEMU out-of-process** (XPC: `QEMUHelper`→`QEMULauncher`); host files
23  reach it only through a security-scoped-bookmark dance — respect it for anything
24  touching disk images, shared dirs, or file handles. **iOS runs QEMU in-thread and
25  can launch it only once per process** — this constrains start/stop logic.
26- **UTM SE** (`iOS-SE` scheme, `*-tci` sysroots) is gated by the `WITH_QEMU_TCI`
27  compile flag — grep for it before changing anything that differs between editions.
28 
29## Generated files — never hand-edit
30 
31Edit the generator and regenerate, not the output: `Configuration/QEMUConstantGenerated.swift`
32(`scripts/const-gen.py`), `Scripting/UTMScripting.swift` (`scripts/bridge-gen.sh`
33from `UTM.sdef`), and QAPI/QMP wrappers (produced by the dependency build).
34Third-party patches live in `patches/`.
35 
36## Conventions
37 
38**`CONTRIBUTING.md` is the source of truth** for style, concurrency, design, and
39compatibility rules; `/utm-review` audits the diff against it. Two rules an agent
40must apply unprompted — they override default behavior and are easy to violate:
41 
42- **AI attribution:** every AI-assisted commit **must** carry an
43  `Assisted-by: AGENT:MODEL` trailer (e.g. `Assisted-by: Claude:claude-opus-4-8`) —
44  add it explicitly **even if your agent doesn't normally inject attribution
45  trailers**; the absence of a default trailer is not an excuse to omit it. Never
46  add `Co-authored-by` or session links (strip any a tool adds). Commit titles are
47  `component: short description` explaining *why*.
48- **Scope:** one feature/fix per PR; don't touch, refactor, or reformat unrelated
49  files; route new logging through `UTMLogging`/`logging` at `debug` level.
50 
51## Contribution workflows
52 
53Before opening or updating a PR, run **`/utm-review`** then **`/utm-submit`** —
54canonical instructions in `.agents/skills/{utm-review,utm-submit}/SKILL.md` (thin
55shims in `.claude/commands/` and `.opencode/command/`). If your agent doesn't
56auto-load them, read and follow those `SKILL.md` files directly.
57