Projects and spaces

Almost everything in Astra is a project or a space.

Term	What it is	Relationship
Project	A git repo on your machine.	Has many spaces.
Space	One conversation with an agent.	Belongs to exactly one project.
Tab	A surface inside a space — a chat, a terminal, a browser, a simulator, a design canvas.	A space has one or more.
Home branch	The project’s main line, e.g. main.	Where worktree branches start from and merge back into.

Projects

A project is just a folder Astra knows about. Adding one records its path and its home branch, gives it a color for the sidebar, and stores a few per-project settings — a setup command, a teardown command, files to seed into new copies, and an optional run command for the simulator. Nothing is copied or uploaded; the repo stays where it is.

You can have as many projects as you like, and the sidebar can group spaces by project when you’re working across several.

Spaces

A space is a conversation, and it’s also the unit of work in the sidebar. Each one carries a title and a one-line summary (generated from your first message, if you leave auto-naming on), an unread marker when an agent finishes while you’re elsewhere, and a status.

Statuses are the sidebar’s organizing axis:

• In progress — the agent is running. Spaces move here on their own.
• Inbox — the agent has finished and it’s your turn. Spaces land here on their own too.
• In review and Backlog — placed by hand, for work that’s waiting on someone or parked for later.

You can group the sidebar by status or by project, and pin the spaces you keep coming back to so they sit above the groups either way.

Where a space runs

This is the one real choice you make when creating a space, and it has consequences all the way through:

• Local (the default) — the space works in the project folder, on whatever branch you have checked out. No setup, no waiting, and changes land straight in your files. Every local space in a project shares that one folder, so they see each other’s work.
• Worktree — the space gets its own copy of the repo on its own branch, provisioned in the background. Your folder stays untouched until you merge.

The difference is isolation, not capability: both run the same agents with the same tools. The kind isn’t stored as a flag — it’s simply where the space’s files are — and it can’t be changed after the fact. If you start local and want isolation, fork the space to a worktree (see Running agents in parallel).

Worktree spaces get a branch icon in the sidebar and, optionally, a second line showing the branch name. They’re also the only spaces with a pull-request control; a local space is on your branch, so there’s nothing for Astra to open a PR from.

Tasks

Separate from spaces, Astra keeps a lightweight list of tasks per project — plain tickets with a title, a description, and a status (backlog, todo, in progress, done). They’re hand-managed and carry no agent state. A task is intent; a space is execution. Press ⌘⇧T for the list, ⌘⇧C for a new one.