Introduction

Astra is a macOS app that runs coding agents on the repos already on your machine. It is not a hosted service and not an editor plugin: the agents run locally, against your real checkouts, using your own Claude or Codex account.

The problem it solves is a narrow one. Running one agent in a terminal works fine. Running four means four checkouts, four branches, and a lot of bookkeeping to stop them overwriting each other. Astra makes that bookkeeping the app’s job.

The model in thirty seconds

Two nouns carry almost everything:

Term	What it is
Project	A git repo on your machine — the folder you point Astra at.
Space	One conversation with an agent, inside a project.

A space runs in one of two places. By default it runs in your project folder, on whatever branch you have checked out — the same as running an agent in your terminal, and every local space in a project shares that one folder. Or you can create it as a worktree space, which gets its own copy of the repo on its own branch, so it can’t touch anything you’re doing.

Worktree spaces are what makes running several agents at once safe. Each one is a real git worktree on disk, isolated from the others and from your own checkout, with its own branch you can review and merge like any other.

What’s in a space

A space isn’t only a chat. It holds tabs, and a tab can be a conversation with an agent, a terminal, a browser, an iOS simulator, or a design canvas. Alongside them sits a panel with the space’s files, its uncommitted changes as a diff, and its context docs — plus a terminal drawer that’s always one keystroke away.

Because a worktree space owns a branch, it also owns the end of the job: open a pull request from the space’s header, watch checks, and merge, without leaving the app.

Giving agents context

An agent that has to rediscover your architecture every conversation keeps making the same wrong guesses. Astra’s context library is a folder of Markdown committed in your repo — conventions, domain vocabulary, the reasoning the code can’t explain. Mark a doc Always and it’s loaded at the start of every conversation in the project; leave it on mention and it’s there when you @ it.

Because the library is committed, it’s shared: everyone on the team, and every agent they run, starts from the same understanding of the project.

Designing, not just building

Not all the work is code. A design space is a canvas where the agent builds mockups as live React frames — real running interfaces you can click through, not pictures. Ask for a screen, get variants side by side, open one in interact mode and actually use it, then tell the agent what’s wrong.

Frames are fenced off from your application code, so exploring five directions costs nothing and changes nothing. Turning one into a real implementation is a separate, explicit job.

Where to go next

• Install and sign in — get the app running and connect your agent accounts.
• Projects and spaces — the core model, in full.
• Worktree spaces — how isolation actually works.
• Running agents in parallel — the workflow the rest of it is for.
• Context library — teach agents your project once.
• Design spaces — mockups as live frames.