Start here
Your first task
The core ideas, then one task from an empty chat to a merged pull request.
Windows uses Ctrl in place of ⌘.
Core ideas
- Task: one piece of work with its own chat, agent, folder and branch. Many can run at once. A task can have subtasks that share its folder and branches.
- Worktree: each repository you attach gets its own copy of the code for the task, on a new branch. Your own checkout is never touched. See Tasks, worktrees and branches.
- Agent and model: picking a model beside Send picks the agent that runs it. A started chat stays with its agent; model and effort can change from the next message.
- Board and Code:
⌘1shows your plan (Inbox, Today, This week, Backlog).⌘2shows the task's chat with Preview, Changes, Checks, All files, Terminal and Simulator beside it.
1. Start a task
Click New task in the sidebar, or press ⌘N. An empty chat opens.
2. Attach a repository
In the chat header, click Add repository and pick one. To add another:
- Add a local folder… for a repository on your computer.
- Clone from GitHub or a URL… with
owner/nameor any git URL.
Attach several, or none.
3. Pick an agent and send
Choose a model in the picker beside Send, describe what you want, and send. Your first message names the task and its branch, such as alex/feat/add-dark-mode. Change the first part with branchPrefix in config.
4. Watch and answer
The work streams into the chat. When the agent needs you, the task gets a dot in the task list and the chat shows a permission card or a question. A plan opens in the Plan tab.
5. Review
Open Changes. Tick files as you review them, ask about a line, or revert a change. Not happy? Say so in the chat. See Review changes.
6. Ship and finish
Ask the agent to open a pull request, or click Open PR once every file is reviewed. Merge it from the chat header. When every pull request is merged, click Done. The task moves to the Plan as completed, and Clear completed archives it.