Development

Rust checks

Run the full Rust test suite:

cargo test --quiet

For CLI behavior changes, also inspect help output:

cargo run --quiet --bin zodex -- --help
cargo run --quiet --bin zodex -- sprite --help
cargo run --quiet --bin zodex -- proxy --help
cargo run --quiet --bin zodex -- github --help
cargo run --quiet --bin zodex-agent -- --help
cargo run --quiet --bin zodex-agent -- github publish-pr --help

The tests cover binary manifests, CLI behavior, GitHub App scripts, install behavior, Sprite scripts, zodex-agent forwarding, MCP tool registration, session handling, redaction, patch application, and mode-first product contracts.

Liveboard checks

Liveboard is an isolated frontend app under apps/liveboard. On macOS its production assets are embedded into the zodex binary by build.rs; Linux/Sprite builds do not require frontend tooling.

For visual development against the real currently running Local runtime, use the attached dev server:

cd apps/liveboard
bun run dev:live

The launcher builds a repo-local Zodex viewer once, starts zodex local watch --no-open against the active Local observer, and runs Vite with HMR. Vite proxies Liveboard API, SSE, and preference requests through that temporary same-origin capability host, so the observability bearer remains outside browser JavaScript. It does not restart or replace the running Local runtime.

cd apps/liveboard
bun install --frozen-lockfile
bunx playwright install chromium webkit
bun run typecheck
bun run test
bun run test:browser
bun run test:browser:webkit
bun run build

Do not commit apps/liveboard/node_modules/ or apps/liveboard/dist/.

For an embed-required macOS validation, build the frontend first and then run Cargo with:

ZODEX_LIVEBOARD_EMBED_REQUIRED=1 cargo test

CI does this only on the native macOS lane. Release builds likewise install Bun/build Liveboard only for the Apple target; Linux/Sprite release targets stay independent of the frontend toolchain.

Docs site checks

Run:

cd docs
bun install
bun run check
bun run build

Do not commit generated Astro output:

.astro/
dist/
node_modules/

These paths are ignored.

Docs content rules

Keep docs tied to actual zodex behavior:

• mention the real binaries: zodex, zodex-agent, git-remote-zodex, zodexd, zodex-prd
• distinguish operator-machine commands from Sprite-side commands
• keep the read/write access model explicit
• explain when a command needs an active grant
• keep MCP as the supported remote coding transport; do not reintroduce deleted legacy transports
• update command examples when Clap arguments change
• when Local observability routes, response fields, filters, SSE event types, discovery fields, API/presentation versions, or recovery semantics change, update Local observability API in the same change
• when Liveboard/TUI controls, board behavior, presentation, or recovery UX changes, update Watch and Liveboard in the same change

Repository scripts

Useful scripts include:

scripts/install.sh
scripts/mint-gh-app-installation-token.sh
scripts/protect-main-branch.sh
scripts/github_actions_fail_fast.py

Run script-specific tests when changing them:

cargo test --quiet --test install_script
cargo test --quiet --test github_app_scripts

Release awareness

The crate version is defined in Cargo.toml. The repository uses tagged releases.

When a release changes CLI arguments, binary names, setup behavior, service layout, Liveboard assets, or public observer contracts, update the docs site in the same change.