domux: Instructions file for Claude Code

Repository guidelines for domux V2

Rust workspace, five crates under crates/:

• domux-term: the Emulator trait and GhosttyEmulator, its one implementation. There is no second emulator and no cargo feature to select. Read docs/decisions/0001-terminal-emulator.md and docs/decisions/0002-ghostty-source-acquisition.md before touching this crate.
• domux-core: pure model, layout, keymap, config, protocol and state types, and the theme model: roles, colour values, chains of themes and the readability guards. No IO, no tokio, no ratatui, no process spawning. Every rule here has a unit test.
• domux-server: the core task, panes, rendering, socket, persistence. src/testing.rs is the harness every interface test uses.
• domux-client: the thin client: raw mode, capabilities, keys out, frames in, clipboard, the attach batch that asks the terminal for its colours, the desktop check and the Omarchy watch.
• domux: the domux binary. One file per API namespace under src/cli/.

The M0 pane spike is gone. M1 lifted its PTY, input and render code into domux-server and deleted crates/m0-spike; docs/milestones/m1.md records what M1 shipped.

Build and test

• cargo build --workspace fetches two pinned inputs on the first build and caches both under ~/.cache/domux: the Ghostty source, cloned at the commit in vendor/ghostty-pin.toml, and the Zig that builds it, from vendor/zig-pin.toml. DOMUX_GHOSTTY_SOURCE_DIR and DOMUX_ZIG point at local copies.
• A cold build can fail while Zig fetches Ghostty's dependencies: deps.files.ghostty.org returns TlsInitializationFailed intermittently on some networks. The fetch pass already runs with -j1; rerun the build. Decision 0002 records the details.
• crates/domux-term/scripts/bump-ghostty.sh <commit> is the only thing that edits vendor/ghostty-pin.toml. It regenerates the bindings and runs the suite.
• cargo test --workspace runs everything. Interface tests live in crates/domux-server/tests/ and assert on frames: a failing test prints the screen as |...| rows with a styles list.
• cargo clippy --workspace --all-targets -- -D warnings and cargo fmt --all --check must pass before a commit. CI runs cargo fmt --all --check, cargo build --workspace --locked, cargo clippy --workspace --all-targets -- -D warnings and cargo test --workspace --locked, in that order.
• UPDATE_GOLDEN=1 cargo test -p domux-term --test golden rewrites the golden files. Read the diff against the fixture's intent before committing it: a golden that changed because the emulator changed is the point, and one that changed because a test was loosened is a defect being recorded as correct.
• crates/domux-term/scripts/ghostty-src.sh prints the Ghostty tree the build resolved. build.rs exports the same path as DOMUX_GHOSTTY_SRC, and tests/header_fingerprint.rs and tests/zig_pin.rs read it, so the bindings are always checked against the headers that were actually compiled.
• cargo run -p domux -- api schema prints the control API schema.
• The shell half has its own suites, all POSIX sh: sh tests/license/run.sh, sh tests/release/run.sh and sh tests/install/run.sh (and the same under TEST_SHELL=bash). shellcheck -s sh install.sh scripts/release/*.sh scripts/dev/*.sh tests/lib/assert.sh tests/license/run.sh tests/release/run.sh tests/install/run.sh tests/install/fakebin/* must pass too, the same list .github/workflows/ci.yml gives it: leave out tests/lib/assert.sh and shellcheck exits 1 on the files that source it. CI runs all of it on macOS and Ubuntu.
• The Neovim plugin has its own suite: nvim --headless -l tests/nvim/run.lua, with Neovim 0.10 or later. It needs no build. It serves a fake control API, and tests/nvim/requests.jsonl, which a domux-core test parses, keeps that fake honest. CI runs it on macOS and Ubuntu against Neovim 0.10.4 and 0.11.6.
• cargo about generate --fail -o /dev/null about.hbs checks that every compiled crate's license is in about.toml. Install it with cargo install cargo-about --version 0.9.2 --locked --features cli; without --features cli nothing is installed.
• Releases: a v* tag runs .github/workflows/release.yml, which builds four archives with scripts/release/build-archive.sh, smoke-tests each on its own platform, verifies SHA256SUMS, and publishes the GitHub release with the CHANGELOG.md section for that version. The tag must equal [workspace.package].version. Versions stay low: the releases start at 0.1.0, and the next one is the next patch unless the author asks for another. A CHANGELOG.md section opens with a one-line summary, which domux.dev shows beside the newest version. gh workflow run release.yml -f version=<x.y.z> runs everything except the publish. Read docs/decisions/0039, 0048 and docs/milestones/m5.md before changing any of it.
• site/ is domux.dev. .github/workflows/pages.yml publishes it with install.sh at /install.sh on every push to main that changes either, so the install command is curl -fsSL https://domux.dev/install.sh | sh. The page is one HTML file with no build step. Decision 0047 records why.
• Run domux only in its own Ghostty tab, never inside tmux. ~/bin/domux points at target/release/domux. V1, the Go version, is the v1 branch and is never built or run from here.
• scripts/dev/deploy.sh runs the latest build without ending a pane: it fast-forwards the checkout (--no-pull builds it as it is), builds release, links ~/.local/bin/domux and ~/bin/domux to the build, and runs domux server upgrade. It is safe to run from inside a pane.