Build Aura from Source

Clone the repo, build the binary, and get set up to ship your first patch.

Aura is open source under the Apache 2.0 license. The canonical repository lives at github.com/Naridon-Inc/aura. Building from source is the right path when you want to run an unreleased commit, test a pull request locally, target a platform without a prebuilt binary, or contribute a patch. This guide covers the toolchain requirements, the build itself, local install of your freshly built binary, and the mechanics of opening your first pull request.

If you just want a working aura binary, use the macOS, Linux, or Windows installers instead. Building from source is slower and has more moving parts.

Prerequisites

• Rust 1.80 or newer. Aura uses features from the 2024 edition and several stabilizations landed in 1.80. Check with rustc --version.
• A C compiler (cc or clang) and make. Tree-sitter grammars compile native shared objects as part of the build.
• git 2.30+.
• pkg-config and OpenSSL development headers if you are on Linux. libssl-dev on Debian/Ubuntu, openssl-devel on Fedora/RHEL.
• Roughly 4 GB of free disk for the full debug build, 1.5 GB for a release build and its target cache.
• 4 GB of RAM minimum, 8 GB comfortable. The release build is CPU-bound and benefits from all cores.

Install Rust with rustup if you do not already have it:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustup default stable
rustup component add rustfmt clippy

On Debian/Ubuntu, install the system dependencies:

sudo apt install -y build-essential pkg-config libssl-dev git

On Fedora/RHEL:

sudo dnf install -y gcc openssl-devel pkgconf-pkg-config git

On macOS, the Xcode Command Line Tools provide everything you need:

xcode-select --install

Clone and build

git clone https://github.com/Naridon-Inc/aura.git
cd aura

The repository is a Cargo workspace. The top-level Cargo.toml lists several crates:

• aura-cli — the aura binary.
• aura-core — the semantic engine, AST parsing, snapshot store.
• aura-merge — the semantic merge algorithm.
• aura-mothership — the P2P team hub daemon.
• aura-mcp — the Model Context Protocol server Aura agents speak.

A full release build produces a single binary:

cargo build --release

Expect 3 to 8 minutes on a modern laptop for the first build. Subsequent incremental builds are a few seconds. The resulting binary lives at target/release/aura.

For a faster developer loop, use the debug profile:

cargo build
./target/debug/aura --version

Debug builds are noticeably slower at runtime but build in seconds after the first compile.

Running the test suite

Before sending any patch upstream, run the suite:

cargo test --workspace

The tests cover the core semantic engine, the merge algorithm, the hook scripts, and a set of end-to-end scenarios that spawn temporary repos. Some tests require git on PATH; CI catches the rest.

Lint:

cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check

The project treats clippy warnings as errors in CI. Run them locally before pushing.

Installing your build

Copy the binary to any directory on your PATH. The simplest pattern:

cargo install --path aura-cli

This places aura at ~/.cargo/bin/aura. Ensure ~/.cargo/bin is on your PATH — rustup adds it by default.

For a system-wide install on Linux:

sudo install -m 0755 target/release/aura /usr/local/bin/aura

Verify:

aura --version
# aura 0.14.1 (dev build, commit abcdef0)

The (dev build, ...) suffix distinguishes a locally-built binary from a signed release. When you report bugs, include that suffix so maintainers know you are on a custom build.

Contributing your first patch

The Aura codebase is organized to make small contributions approachable. A first patch typically touches one file, adds a test, and updates a small surface of the CLI. Good starter areas:

• Shell completions — missing tab-completion for a subcommand.
• Error messages — making an existing error more actionable.
• Documentation — the docs/ tree in the repo mirrors the website.
• Doctor checks — extending aura doctor with a new environment assertion.

Workflow

1. Fork the repo on GitHub.
2. Clone your fork, add the upstream remote:

git clone git@github.com:<your-user>/aura.git
cd aura
git remote add upstream https://github.com/Naridon-Inc/aura.git

3. Create a feature branch off main:

git checkout -b fix/doctor-inotify-check

4. Make the change. Run tests, clippy, and fmt locally. Importantly, since you are working on an Aura repo, log your intent:

cargo build --release
./target/release/aura init
./target/release/aura log-intent "Added aura doctor check for inotify watch limit"

The repo's own pre-commit hook runs against your changes and verifies that the intent you logged matches the AST-level diff. This is the same mechanism you will use in your own projects — dogfooding is mandatory.

5. Commit and push:

git add .
git commit -m "doctor: check inotify watch limit on Linux"
git push origin fix/doctor-inotify-check

6. Open a pull request against Naridon-Inc/aura:main. The PR template asks for:

• A one-line summary.
• A link to a related issue if one exists.
• The aura log-intent message you recorded.
• Test coverage notes.

CI will run the full test matrix (Linux, macOS, Windows) plus clippy and fmt. A green CI is a prerequisite for review.

Coding conventions

• Module layout follows aura-<crate>/src/<module>.rs. One module per file; flat is better than deeply nested.
• Error handling uses anyhow::Result in binaries and thiserror-derived typed errors in libraries. Do not unwrap() outside of tests.
• Logging uses tracing. Prefer structured fields over interpolated strings.
• Formatting is whatever cargo fmt produces. Do not fight it.
• Unsafe is allowed only with justification in a comment.

Architecture orientation

A few pointers for reading the codebase:

• The AST parse-and-hash pipeline starts in aura-core/src/parse.rs. Each language has a tree-sitter grammar wired in aura-core/src/lang/.
• The snapshot store is aura-core/src/snapshot/. It is content-addressed and lives in .aura/snapshots/ in every tracked repo.
• The semantic diff is aura-core/src/diff.rs. This is the heart of the system.
• The CLI's subcommand routing is aura-cli/src/main.rs; each subcommand has a module under aura-cli/src/commands/.
• The MCP server lives in aura-mcp/. The 29+ tools exposed to AI agents — aura_status, aura_log_intent, etc. — are registered in aura-mcp/src/tools/.

For any patch larger than ~200 lines, open an issue or a draft PR before writing the code. The project has a small core team and they are happy to discuss design up front.

Cross-compiling

To build for a different target from your development machine:

rustup target add aarch64-unknown-linux-gnu
cargo build --release --target aarch64-unknown-linux-gnu

For cross-compiling C code (the tree-sitter grammars), you may need the appropriate cross-compiler toolchain. On Ubuntu for aarch64:

sudo apt install gcc-aarch64-linux-gnu
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc \
  cargo build --release --target aarch64-unknown-linux-gnu

The release pipeline uses cross (github.com/cross-rs/cross) for cross-builds. It produces reproducible binaries inside container images. If your development platform differs from your target, cross is usually easier than wrestling linker flags.

Keeping your fork current

git fetch upstream
git checkout main
git merge --ff-only upstream/main
git push origin main

For topic branches:

git checkout fix/doctor-inotify-check
git rebase upstream/main

Aura itself handles the rebase carefully — semantic identity of functions survives across rebases, so any intent logs you recorded remain valid. That is the same guarantee you get in your own repos. See CLAUDE.md integration for how this behavior is exposed to AI agents working on your branches.

Next steps

• Initialize your first repository with your freshly built binary.
• Write your first intent-logged commit.
• Troubleshooting install issues — applicable to source builds too.

If your build fails, the most common causes are: an old Rust toolchain (run rustup update), a missing C compiler, or missing OpenSSL headers on Linux. Open an issue on the GitHub repo with your rustc --version output and the full error log.