Your first workspace
Add a project, describe a task and put an agent to work in a workspace of its own.
Add a project
A project is a git repository on your Mac. Add one from the File menu:
- Open Project… (⌘O) adds a repository that's already on your Mac.
- Open GitHub Project… (⇧⌘O) clones one of your GitHub repositories. Search your repos or paste a URL; it goes to the clone location under Settings → General.
- Quick Start… creates a new, empty repository.
The project appears in the sidebar. Before you start, it's worth giving it a setup script, so every workspace installs its dependencies by itself.
Create a workspace
Press ⌘N to open Create. Pick the project, and type what you want to work on, the way you'd say it to a colleague:
The recipe search ignores accents: "creme" doesn't find "Crème brûlée". Fix that and add a test.
Under the text you choose the agent and model, how hard it should think, and the permission mode. Press Return and Compagnion:
- fetches the newest commits from GitHub,
- creates a worktree on a new branch from the default branch,
- runs the project's setup script, and
- starts the agent with your message.
A small model gives the workspace a title and a branch name that says what the change does, such as vincent/fix-recipe-search. The prefix is your GitHub login; you can change it under Settings → Git.
You can also start from something that already exists: the GitHub menu at the top right of Create has tabs for PRs, Branches and Issues. And Create without starting an agent gives you just the worktree.
Follow along
The workspace shows up in the sidebar. The Compagnion mark next to it tells you what the agent is doing: it spins while the agent works, and turns around when the agent needs you, for example to approve a command. A sound plays when an agent is done or needs you.
Open the workspace to see the conversation: the agent's messages, the tools it used, and under every turn the files it changed. Send a follow-up any time; while the agent is busy it waits in line and goes in as soon as the turn ends.
Work in parallel
Create as many workspaces as you like, in the same project or in different ones. Each has its own worktree and branch, so agents never get in each other's way, and your own checkout of the project stays untouched.
When a workspace is done, open a pull request and merge it, then archive it.