Introduction

Raven 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. Raven 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 Raven at.
Workspace	One conversation with an agent, inside a project.

A workspace 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 workspace in a project shares that one folder. Or you can create it as a worktree workspace, which gets its own copy of the repo on its own branch, so it can’t touch anything you’re doing.

Worktree workspaces 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 workspace

A workspace isn’t only a chat. Its tabs are conversations — several if you want, all against the same checkout — and beside them sits a panel of surfaces: the workspace’s files, its changes as a diff, the project’s context library, a design board, a browser, an iOS simulator, and a terminal. Pin the ones you use; the rest are one shortcut away. See Tabs and the right panel.

Because a worktree workspace owns a branch, it also owns the end of the job: open a pull request from the workspace’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. Raven’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 board is a canvas where the agent builds mockups as React frames — real interfaces you can open and click through, not pictures of one. Ask for a screen, get variants side by side, open one in preview 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.
• Integrations — connect GitHub, Linear, Sentry, PostHog, and 1Password.
• Projects and workspaces — the core model, in full.
• Worktree workspaces — how isolation actually works.
• Running agents in parallel — the workflow the rest of it is for.
• Tabs and the right panel — chats in the middle, surfaces on the right.
• Context library — teach agents your project once.
• Design boards — mockups as React frames.
• Raven on your iPhone — keep up with your workspaces from your phone (beta).