Contributing
Atlas is open source. Where help goes furthest, how to build it, and how a change gets merged.
Atlas is developed in the open at github.com/tryatlas/atlas. Anyone can send a change, and you can talk one through on Discord before you start.
Contributors whose work keeps making a difference are invited into Atlas Contributors, the small group with the Atlas team that is on the way to maintaining Atlas.
The repository's CONTRIBUTING.md is the full guide. This page is the short version.
Where help goes furthest
Start with the labeled issues:
good first issue: small, well-scoped changes, mostly in the interface.help wanted: harder problems we'd welcome help on.
Issues also carry an area: label, so you can filter to the part of the app you know. Areas where outside help has gone furthest so far:
- Linux and Windows. Atlas runs on both, and the team works mostly on macOS. Testing and fixes there are always welcome:
platform: linux,platform: windows. - The workspace interface: navigation, tabs and discoverability (
area: workspace ui). - Agents and chat (
area: agents & chat). - The editor and the built-in browser (
area: editor,area: browser). - Themes. A new theme needs no Rust at all; see Authoring themes.
The larger items on the roadmap are being designed by the core team. If one of them interests you, talk to us before writing code.
Before you build
- Bug fixes and docs: go ahead and open a pull request.
- New features: open an issue first, or raise it in
#feature-requestson Discord. Most features cross the React interface, a Tauri command and a Rust crate, so agreeing the approach first saves a rewrite. - Design changes: share the proposal in the issue before implementing it.
- New dependencies need discussion first.
Set up
You need Bun and Rust (rustup installs the pinned version on first use), plus Xcode Command Line Tools on macOS. No API keys, .env file or account are needed to build.
git clone git@github.com:<you>/atlas.git
cd atlas
bun install
bun run dev:appbun run dev:app runs Atlas Dev, a separate profile with its own data, so it never touches an installed Atlas. For interface work, bun run dev runs the frontend in your browser against a fake backend, with no Rust at all.
CONTRIBUTING.md covers the rest: the two run modes in detail, the browser mock's scenarios, and the test commands.
Branches
Atlas is trunk-based: everything lands on main, and a release is a tag on main.
- Fork the repository and branch from
main. Name your branch<you>/<short-slug>, with the issue number first if there is one:alex/42-fix-sidebar-collapse. - Open the pull request against
main. - Title it as a Conventional Commit:
fix(terminal): keep the close button clickable while dragging. Pull requests are merged with a merge commit titled with the pull request title, and that commit decides the next version and the changelog. Your branch's commits land too: one in Conventional form is a changelog entry of its own. A check on the pull request holds the title to this shape.
Branches and releases explains the whole flow, with diagrams.
Before you open the pull request
bun run lint
bun run format:check
bun run typecheck
bun run test
bun run ci:local # what CI would run for your branchRun the app and use your change in a window. Tests cover logic, not whether it works on screen.
The pull request template asks What?, Why? and How?, and has a short checklist: the right target branch, a test for new behavior (a failing-then-passing test for a bug fix), and that you ran it.
Review
- Leave Allow edits from maintainers checked. We often push small fixes to your branch rather than send them back to you.
- Review happens on GitHub, in the pull request. Questions you'd rather talk through can go to Discord.
- An issue closes when its fix merges into
main(putFixes #Nin the pull request). Before starting on an issue that looks unclaimed, check the open pull requests. - Merged contributions ship in the next release, and contributors are credited in its release notes and in the changelog.
Code of conduct
Taking part is covered by the Code of Conduct.