Install and sign in

Astra is a signed macOS app that updates itself. Download it, drag it to Applications, and open it.

Astra is in private beta and downloads aren’t public yet. Request access and we’ll send you a build. Everything below describes the app as it ships today.

Sign in to Astra

The first launch asks you to sign in. Astra opens your browser, you authenticate there, and the browser hands the session back to the app. The session is stored encrypted on your Mac using the system keychain, and it’s checked locally after that — so signing in once is enough, and the app keeps working offline.

Connect an agent

Astra runs Claude Code and Codex. You don’t have to install either one: the command-line binaries ship inside the app. What Astra needs is your account.

Open Settings › Connections and log in to whichever agents you want to use. Each login runs in a small terminal inside the settings pane — the same login flow the CLI would show you — and Astra reports the connection as live once the binary is present and the account is signed in.

A few things worth knowing:

• The check is local. Astra reads the CLI’s own stored credentials; it doesn’t make a network call or spend a turn to find out.
• Because it’s local, a revoked token can still read as connected until a real run fails. If a chat suddenly says you’re not logged in, re-check the connection here.
• The two agents are independent. Checking Codex never touches Claude, and you can use one without connecting the other.

Connect GitHub

Pull requests are optional, but if you want them, connect GitHub from the same Connections pane. Astra uses GitHub’s device flow — it shows you a code, you approve it in the browser — and stores the resulting token encrypted in your keychain.

Without a GitHub connection, everything else still works; spaces just show “Connect GitHub to open PRs” where the pull-request control would be.

Add a project

Point Astra at a git repo on your machine. You can add an existing folder, clone one from GitHub, or start a brand-new repo from scratch.

When you add a project, Astra looks at it and prefills two things it can determine for certain:

• A setup command, from the lockfile it finds — pnpm-lock.yaml becomes pnpm install, package-lock.json becomes npm install, and so on.
• A seed list, from gitignored .env* files at the repo root — files a fresh copy of the repo would otherwise be missing.

Both are suggestions you can edit or clear. Astra doesn’t guess beyond that; it won’t infer or run scripts it wasn’t told about. See Project setup for what these do.

Your first space

Create a space, type what you want, and send. That’s the whole loop.

The space starts local by default: it works directly in your project folder, on your current branch, and changes land in your files as the agent makes them. When you want the agent working somewhere it can’t disturb you, create the space as a worktree instead — see Worktree spaces.

Updates

Astra checks for updates on its own and offers to install them. Settings › Updates shows your current version and lets you check on demand, or opt into beta builds if you’d rather see changes early.