Projects and workspaces

Almost everything in Raven is a project or a workspace.

Term	What it is	Relationship
Project	A git repo on your machine.	Has many workspaces.
Workspace	One conversation with an agent, plus its tabs and panel.	Belongs to exactly one project.
Tab	A chat inside a workspace — one agent conversation.	A workspace has one or more, up to ten.
Surface	A pane in the workspace’s right panel: files, changes, context, design, browser, simulator, terminal.	One shows at a time, per tab.
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 Raven knows about. Adding one records its path and its home branch, gives it an icon and a color for the sidebar, and stores a few per-project settings: what a fresh worktree needs (a setup command, files to carry in, a teardown command), the Run button’s command, the simulator’s, which surfaces are pinned, and any Linear, Sentry, or PostHog connections. Nothing is copied or uploaded; the repo stays where it is.

You can have as many projects as you like. The sidebar groups workspaces by status or by project — View options › Group by — and each project’s header folds on its caret and has a menu: New workspace here, Change icon…, and Remove project.

Workspaces

A workspace 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. Hover a row for a card with its title, summary, project, branch, and folder.

Statuses are the sidebar’s organizing axis:

• In progress — the agent is running. Workspaces move here on their own.
• Inbox — the agent has finished and it’s your turn. Workspaces land here on their own too.
• In review and Backlog — placed by hand, with Move to in a workspace’s right-click menu, for work that’s waiting on someone or parked for later. In review is for worktree workspaces, whose branch can be waiting on a pull request.

Pin the workspaces you keep coming back to and they sit above the groups either way. Drag pinned workspaces into the order you want, or drag any workspace onto the Pinned section to pin it. The right-click menu also has Rename, Regenerate title (rewrites the title and summary from what the conversation actually covered), Mark as unread, Archive, and Delete.

When several agents finish at once, the Next unread pill above the composer, or ⌘⇧U, steps you to the next tab or workspace that needs you, then through your pinned workspaces (the pill reads Next pinned once nothing is unread).

Where a workspace runs

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

• Local (the default) — the workspace works in the project folder, on the branch you pick. No setup, no waiting, and changes land straight in your files. Every local workspace in a project shares that one folder, so they see each other’s work.
• Worktree — the workspace gets its own copy of the repo on its own branch, provisioned in the background. Your folder stays untouched until you merge. A worktree needs a commit to start from, so in a repo with nothing committed yet the option is disabled and says so.

The New Workspace page (⌘N) carries the choice as a row of pills above the chat composer: the project, Local / Worktree, and the branch — on a branch for a local workspace, which checks it out in your folder, or from a branch for a worktree workspace — with a pin toggle at the row’s end (⌘⇧P) so the workspace starts out pinned. The page is a view of its own, like Designs: it stays until you pick a workspace or another view, and Raven reopens on it after a relaunch. The dialog (⌘⇧N) carries the same row over whatever you’re looking at, plus Start in background in the send button’s menu. The first time either opens, Raven explains the two options; Change default… takes you to Settings › Chats › New workspaces run, and the add-project dialog asks the same question for a project’s first workspace.

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 workspace’s files are — and it can’t be changed after the fact. If you start local and want isolation, fork the workspace to a worktree (see Running agents in parallel).

Worktree workspaces get a branch icon in the sidebar and, if you turn on Settings › Appearance › Left sidebar › Workspace detail line, a second line with the branch name. With Ahead / behind counts in the same section (on by default), each worktree row also shows commits ahead of and behind the home branch, until the branch is merged. Worktree workspaces are the only ones with a pull-request control; a local workspace is on your branch, so there’s nothing for Raven to open a PR from.

The workspace header

Above the tabs, the workspace’s chip opens a small menu: Reveal in Finder, Open on GitHub, and Project settings. Beside it sit the Run button (see Project setup) and, on worktree workspaces, the pull-request control. A worktree workspace also shows its worktree’s name there — hover it for the folder’s path and the bird’s one line of lore.

The branch readout

The branch a workspace is on sits in a quiet row under the composer, and it’s live: a worktree workspace follows whatever branch its checkout has, so switch, create, or rename a branch from the terminal and the sidebar, the readout, and the pull-request control all follow. Hover the readout for the current branch and the folder it’s in. Click it to switch: a local workspace lists every local branch, a worktree workspace the branches it has been on, minus any branch held by another checkout. The switch is a plain git switch, and it’s refused while an agent is working there. A detached HEAD shows as detached at and can’t be switched from here.

Work in Linear

Connect a Linear team in the project’s settings to look up, create, and update issues from chat — /linear create an issue to add keyboard navigation to the search menu files the work in Linear and shows it as a card. A single-issue card can also start a workspace for that issue directly. See Integrations for setup.