Brood is a new workspace project for a persistent, graphical developer environment.
The core idea is a local virtual workspace containing isolated sessions. A session server owns durable state and hosted applications; an independent presentation client opens the native viewport. The client is not a remote framebuffer viewer. It imports individual pane surfaces and owns recursive layout, composition, interaction, and presentation-local plugins.
Brood should feel like a native editor while behaving more like a rich tmux session:
- managed apps and session state survive presentation window close/reopen
- editor, browser, terminal, agent, git, and app panes share one pane model
- browser and Wayland app surfaces are composited as first-class panes
- built-in apps can be WASM-backed plugins whose SDK components emit bounded canvas draw packets
brood: CLI entrypoint that starts the presentation client.brood-client: WGPU presentation process that connects to the session server.brood-sessiond: authoritative local session server.bmux: tmux-shaped control interface backed by Brood sessions and first-party terminals.- pane producers: browser pane client, terminal pane client, hosted Wayland app surfaces, and future native panes.
- plugins/WASM apps: built-in or user applications that use addressed actors, private shared-memory workers, completion-based I/O, WASI resources, optional sync policy lanes, canvas draw packets, native text services, and a future advanced-graphics escape hatch.
This repository contains a split session-server and presentation-client proof of concept.
The current PoC can:
- expose a nested Wayland compositor socket
- launch and map hosted Wayland apps
- open an independent Winit/WGPU presentation client and render nested Wayland clients
- forward keyboard, pointer, button, and axis input
- close the presentation client while hosted Wayland apps keep running
- reconnect a new presentation client to the surviving session
- compose client-local plugin panes and managed panes through recursive layout leases
- report frame cadence, input-to-frame latency, client commits, frame callbacks, dmabuf state, and explicit-sync state
- run async core-WASM behavior harnesses through
brood run --test-harness
Graphical behavior tests start a headless server and a real external
brood-client, then drive and capture that client through a headless Wayland
compositor. The backend is never used as an outer presentation container.
Run the project through the Nix development shell:
nix develop --command cargo runBy default the CLI starts brood-client. The client connects to the default
session server, starts brood-sessiond when necessary, performs a protocol
handshake, and then opens its WGPU presentation window.
The session service is always usable without a presentation client. Service
managers and backend development invoke brood-sessiond; exact command
options remain defined by the CLI parser.
The repo includes flake.nix, and checked-in development workflows should prefer it for builds and tests. Its default package is the Brood app; heavier development environments are exposed through explicit full outputs.
Start the one-line development workflow from Nix:
nix run github:ElSargo/brood#dev-workflowThis clones a writable checkout under ~/.cache, installs the packaged WASM
example artifacts used by the normal config, starts a normal Brood session
from the Nix-built binary, and opens a terminal in that checkout. See
Develop With Nix.
For the larger toolbox with Docker, Go, Firefox, and smoke tools:
nix run github:ElSargo/brood#dev-workflow-fullFor exact runtime, validation, and control commands, see the CLI reference pointers.
Current acceptance uses the external presentation client rather than the old
daemon smoke matrix. Run the focused layout and session-switcher workloads
through the Nix shell, or use nix run .#software-e2e-capture for retained
client-composed frames and reconnect evidence. See
Testing for the supported paths.
The session server uses Smithay and Wasmtime. The presentation client uses WGPU,
and shared CLI/DBus types live in brood-cli. Local transport carries
per-window frames and bounded input/configuration lanes; viewport placement
never crosses that boundary.
The docs are organized as a wiki-style knowledge base.
- Knowledge Base Index
- Overview
- Architecture
- Runtime
- Testing
- Configuration
- Extension Host
- Design Targets
- Implementation Progress
- Design Frictions
- CLI Reference Pointers
- Decision Records
Historical design notes and older prototypes live under docs/archive/.
Active, unaccepted design explorations live under docs/experiments/.