Development Setup¶

Roost has two active development surfaces:

1. The Rust workspace at crates/ — roost-ipc, roost-engine, roost-ui-model, roost-vt, roost-osc, roost-url, roost-agent, roost-cli, roost-iced (the Linux UI), and roost-session (the opt-in headless host-session daemon).
2. The Swift package at mac/ — the macOS UI, Roost.app.

Both link the same vendored libghostty-vt static archive built from third_party/ghostty/.

Prerequisites¶

There are no GTK packages to install — roost-iced is GTK-free, and CI enforces that with a dependency-boundary check (make check-iced). See Installation for the per-platform package commands and the runtime library set the iced UI needs.

Initial build¶

git clone https://github.com/charliek/roost.git
cd roost
mise install                 # Rust + Zig
make setup                   # + builds libghostty-vt (idempotent on cache hit)
make build                   # cargo build the workspace (iced UI + roostctl)
make bundle                  # macOS: assemble mac/build/Roost.app (debug)

third_party/ghostty/build.sh (what make setup runs) is the only step that needs Zig. After it finishes, normal Rust + Swift workflows work without invoking Zig again.

Iteration¶

make with no target lists everything.

Profiles and sockets¶

Each UI resolves a bundle profile that owns its socket, state, lock, and log paths, so the Mac app, a packaged Linux install, and a dev iced build never collide. ROOST_BUNDLE_PROFILE (mac | linux | iced) overrides the compiled-in default.

Without XDG_RUNTIME_DIR, Linux falls back to /tmp/roost-<uid> and /tmp/roost-iced-<uid> respectively (and /tmp/roost-session-<uid> for a session; a debug-build session uses /tmp/roost-session-dev-<uid>). Select a live UI with roostctl --target mac|linux|iced — session is deliberately not a --target value; drive it with roostctl session start|stop|status, and reach a running session with any other op only via an explicit roostctl --socket <path> (see cli.md). The full table — state, locks, logs, and the macOS dev paths for the linux profile — is in Paths & Environment.

Each UI writes a log file and tees to stdout. The iced UI logs to $XDG_STATE_HOME/roost/roost.log when it resolves the linux profile and .../roost-iced/roost.log in a dev build; roostctl --help and ipc.md document the wire surface.

Tests¶

Rust tests live next to the code they exercise. Major coverage:

Mac tests are under mac/Tests/RoostTests/; they cover the workspace state machine, PTY supervisor lifecycle, IPC server framing, single-instance flock, renderer, OSC scanner, key encoder, drag/drop math, and tab pill state machine. They run in headless swift test (no NSWindow required for any covered surface).

Above the unit tier sit the functional E2E suite and the visual + real-input harnesses:

make e2e-iced         # functional E2E against the iced UI (reuses a running one)
make e2e-mac          # functional E2E against Roost.app
make e2e-iced-ci      # CI parity: ROOST_TEST_MODE=1 + --roost-fresh. DESTRUCTIVE.
make e2e-mac-ci       # same, for the Mac app. DESTRUCTIVE.

See Test automation for the layer map, the test-mode IPC ops, the harness flags, and the CI lanes.

Documentation site¶

Markdown sources live in docs/. Zensical builds them through uv:

make docs                # static site under site-build/ (`zensical build --strict`)
make docs-serve          # live-reload server at http://127.0.0.1:7070

uv sync --locked --group docs runs automatically; no global Python install needed beyond the uv binary. zensical serve --strict is unsupported — verify with make docs.

The docs are not part of make check or the ci-success gate; they have their own workflows. Run make docs for any commit touching docs/, zensical.toml, pyproject.toml, uv.lock, CHANGELOG.md, or either docs workflow.

The voice for new docs: professional + direct (no marketing), tables for option lists, code blocks with language hints, admonitions only for important notes/warnings, copy-pasteable examples, one topic per page.

Bumping the pinned Ghostty SHA¶

libghostty-vt's API is documented as unstable. Bumps land in their own commit:

1. Edit third_party/ghostty/build.sh — update GHOSTTY_SHA.
2. make ghostty-force to rebuild from the new SHA.
3. Fix any FFI breakage in crates/roost-vt. The C symbols are listed in src/lib_vt.zig of the Ghostty source.
4. Re-run make test.
5. Commit with the SHA + date in the message.

Zig 0.15.x linked host artifacts as arm64-macos, which Apple's macOS 26+ SDK no longer exposed; third_party/ghostty/build.sh carried a maybe_arm64_sdk_shim helper to work around it. Zig 0.16.0 (the pinned toolchain as of the 2026-08-26 ghostty main-tip bump) resolves the system SDK correctly on its own, so the shim was deleted. If a future bump regresses this, restore the sdk_has_plain_arm64/maybe_arm64_sdk_shim block from git history (see b6c46f7).

Code conventions¶

The full set is in CLAUDE.md at the repo root. Highlights:

• Concrete types until duplication forces an interface — no premature Manager / Coordinator abstractions.
• Errors are returned, not logged-and-swallowed. Log at the boundary that handles them.
• Default to no comments. Add one when the why is non-obvious (a hidden constraint, a workaround, a tricky invariant).
• UI calls happen on the main thread. On Linux that is the winit event-loop thread, reached from update; background work arrives through the single engine feed. On macOS it is @MainActor / DispatchQueue.main.
• The JSON IPC schema is the durable boundary — change crates/roost-ipc/src/messages.rs, update vectors under tests/ipc-vectors/, and bump the Swift mirror in mac/Sources/Roost/IPCMessages.swift in the same commit.