Contributing

Athas uses Tauri, React, TypeScript and Rust. Start with a focused issue or reproducible bug and check existing issues before starting overlapping work.

Requirements

Git, Rust through rustup, Node.js 24.19.0 and Bun 1.3.14 for the current repository.
macOS: Xcode Command Line Tools (xcode-select --install).
Windows: Visual Studio Build Tools with Desktop development with C++ and WebView2.
Linux: your distribution's native compiler, GTK, WebKitGTK 4.1 and Tauri dependencies.

The repository's package.json, setup scripts and AGENTS.md are authoritative if requirements change between releases. Linux builds use the system WebKitGTK runtime; CEF setup is no longer required.

Clone and run

bash

git clone https://github.com/athasdev/athas.git
cd athas
bun setup
bun dev

bun setup installs dependencies and checks platform requirements. On supported Linux distributions it offers the appropriate native dependencies. Read its output before installing system packages. If your environment is already prepared, bun install installs JS dependencies.

Find the right code

Concern	Location
Frontend feature	`src/features/<feature>/`
Shared UI primitives	`src/ui/`
Shared hooks and helpers	`src/hooks/`, `src/utils/`
Integration and theme implementation	`src/extensions/`
Rust feature logic	`crates/<feature>/`
Desktop wiring	`src-tauri/`
Public documentation	`athasdev/www`, under `src/content/docs/`

Read AGENTS.md before making changes. Follow nearby patterns, reuse existing controls, and keep a feature's components, services, stores and tests together.

Validate a change

bash

bun check
bun typecheck
bunx vp test run

Run the relevant tests while iterating. For Rust changes, also run bun check:rust; a focused cargo test -p <crate> <test-name> can help during development. Verify visible changes in the app with both themes and keyboard navigation where applicable.

Build Linux packages

Run native package builds on Linux after installing its build dependencies:

bash

bun build:linux:deb
bun build:linux:rpm
bun build:linux:appimage

The repository also provides bun build:linux:tarball for the portable tarball. See the current package scripts for output locations and prerequisites.

Submit a contribution

Keep each commit focused, explain the problem and resulting behavior, and include a concise test plan. Add screenshots for visible changes.

Read the Contributor License and Feedback Agreement and agree to it by checking the box in the pull request. Athas is licensed under AGPL-3.0 and is also distributed under other terms, such as through the Mac App Store or in commercial editions. The agreement gives Athas the rights to include your contribution in both, and you keep the copyright in your work. Pull requests without the agreement checked can't be merged.

For documentation changes in the website repository, follow its own AGENTS.md and use Vite+ with Node 24.19.0. Desktop and website validation commands are different.

Documentation contributions

Report an inaccurate guide through its Suggest an edit link. Include the affected version and source behavior so the correction can be verified. Documentation for LLMs describes the generated Markdown exports.

Report a problem Get help Docs for LLMs