Development setup

Prerequisites

Rust through rustup. rust-toolchain.toml pins the compiler; rustup installs it on the first Cargo run.
uv for packaging scripts. It uses the Python version in .python-version.
macOS: the Xcode command line tools and CMake (xcode-select --install, brew install cmake).
Ubuntu 24.04 or Debian 13: sudo bash scripts/setup-linux.sh. Other distributions need the equivalent of the GPUI and Wry dependencies.

Install the agent CLIs you want to test against and make sure they are on Aether’s PATH.

Everyday commands

cargo run --locked -p aether
cargo test --locked --workspace -- --skip hackernews::client
cargo fmt --all -- --check

The Makefile wraps the common ones:

Target	Does
`make run`	Run a debug build.
`make build`	Build without running.
`make test`	Workspace tests, skipping the `hackernews::client` tests that flake on macOS.
`make lint`	`cargo clippy` on every target.
`make fmt` / `make fmt-check`	Format, or check formatting.
`make test-packaging`	Python tests for the packaging scripts.
`make package`	Build the installer for this OS into `dist/`.
`make app`	Build `dist/Aether.app` (macOS).
`make install`	Build the app and copy it to `/Applications` (macOS).
`make pacman`	Build an Arch package from `PKGBUILD`.

Configure providers in the app’s settings. Development builds can also read a local .env.

Conventions

Unit tests live beside, not inside, the source. Tests for crates/<crate>/src/<path>.rs go in crates/<crate>/tests/unit/<path>.rs. The source file ends with:

#[cfg(test)]
#[path = "<path relative to this file's folder>"]
mod tests;

and the test file starts with use super::*; for private access. Use one test file per source file and split it when the source splits. tests/*.rs is for real integration tests. Never add tests/unit/main.rs; Cargo would build it as a single test binary.

Words. The codebase uses a fixed vocabulary: Project (not workspace or repo), Session cwd (not working dir), Provider, Driver, Update. The glossary pages use the same terms.

Commits follow Conventional Commits with a crate scope, for example feat(git): add worktree remove with branch delete or fix(driver): pass the prompt to agy -p.

Design docs. Larger changes start as a spec in docs/superpowers/specs/ and a plan in docs/superpowers/plans/. Decisions that should outlive a feature go in docs/adr/.

Before you send a change

make fmt-check lint test

CI runs formatting, tests and the packaging checks on macOS and Linux, then builds the packages.