Creating tasks
A task is one workspace on a worker (a branch and its checkout) plus the conversations that happen in it. You create one from the New task dialog on web, Mac, iPhone, or iPad, and Rivets handles the branch, worktree, and first agent run.
Open the New task dialog
Choose New task in the sidebar or on Home. On web and Mac, you can also press ⌘N. Each project in the sidebar has its own +, which opens the dialog with that repository already chosen and the cursor in the prompt.
You can also create tasks from the command palette (⌘K) on Mac, or on web while you are on Home. Tasks can also come from a Linear issue, over MCP, on a schedule with Automations, and on iPhone and iPad from the share sheet.
The dialog has two tabs. Task starts a task. Repository connects a new repository. On web, only owners see the Repository tab.
Fill it in
Repository
Pick the repository to work in. You only see repositories your teams grant you, and owners see every repository. If the list is empty, ask an organization owner to add you to a team with repository access.
Prompt
Describe what you want the agent to do. Be as specific as you would be with a colleague: the goal, the constraints, and how to tell it is done.
Attachments
On web and Mac, drag files onto the prompt or paste them. You can also use the attach button. On iPhone and iPad, the attach button offers Photo Library and Files. After a drop, the cursor moves into the prompt so you can keep typing.
A message can carry up to 8 files of up to 10 MB each. PNG, JPEG, WebP, and GIF images go to the agent as images. Other files, including screen recordings and other videos (.mov, .mp4, .m4v, .webm), are saved in the worktree for the agent to read. If the agent you picked does not accept images, the dialog asks you to remove them or pick another agent.
On Mac, you can drag a screen recording straight from the screenshot thumbnail into the prompt. That drag moves the recording rather than copying it, so if Rivets cannot attach it, for example because it is over the size limit, the tray says where the original was kept.
Start from
By default, a task branches from the repository’s default branch. To pick something else, open the start control. On web it reads from followed by the default branch, for example from main. On Mac, iPhone, and iPad it reads Start from…. It opens Choose where to start:
| Tab | What the task starts from |
|---|---|
| Pull requests | The branch of an open pull request. Pull requests from forks cannot be checked out. Requires the GitHub App. |
| Branches | Any other existing branch in the repository. |
| Linear issues (Linear in the Mac and iOS apps) | A Linear issue. The task is linked to the issue, and the prompt can be left empty to work on the issue as written. Search by title, ID, or description, and narrow the list with the filters under the search. Requires the Linear integration. |
The Linear list opens on open issues. Filter it by Status, Team, Assignee, Project, Priority, and Labels. Choices within one filter widen the list, and each filter you add narrows it. Picking a status replaces the default of open issues, so you can include done or canceled ones. Reset filters goes back to open issues only.
Choose Start from followed by your choice, for example Start from #123 or Start from ENG-12. To go back to the default branch, choose the × beside the start control. Changing the repository also clears it.
A task started from a Linear issue shares its Team discussion with the issue. You can also link a task to an issue after it is created. See Linear.
Agent, model, and options
The controls under the prompt set how the agent runs:
- Agent and model. Claude Code or Codex, and one of the models the worker offers. Preselected from your agent defaults.
- Reasoning effort. How long the model thinks before acting. Click it to step through the levels.
- Fast mode. Shown when the selected agent and model support it.
- Plan mode. Asks the agent to plan before making changes. Shown when the agent supports it.
- Worker cluster (Run on). Auto picks the best available worker. Choosing a cluster pins the task to it. See Clusters and routing.
On iPhone, these controls open as touch-sized sheets. Fast mode and plan mode share one button, which shows a bolt, a checklist, or both when a mode is on. Tap it to open Modes and switch either one.
See Agents and models for what each option does.
If something would stop the task from starting, the dialog says so and offers a fix, for example No workers connected with Add worker, or No agents ready.
Create
Choose Create, or press Return. If you set Send with to ⌘ Return under Settings › General › Keyboard, Return adds a new line instead.
Drafts
An unsent prompt is kept on the device you wrote it on, for each organization, and comes back the next time you open the dialog. A dialog opened from a project’s + brings back only a draft written for that project. New task in the sidebar or on Home brings back any draft, along with its repository. Attachments are not kept with a draft.
Share from other apps
On iPhone and iPad, you can send images to an agent from any app’s share sheet. Choose Rivets, then:
- Type what the agent should do with the images. A prompt is required.
- If you belong to more than one organization, choose one.
- Under Send to, pick a repository under New task in, or an existing task under Add to a task.
- Choose Send.
Rivets opens and sends it. A new task runs on your agent defaults. Adding to a task sends the message to its current chat. You can share up to 8 images at a time. Text and links are not supported. You need to be signed in to the Rivets app first. The share sheet remembers the last place you sent to in each organization.
What happens next
Rivets creates the task immediately and shows Setting up workspace while the worker gets ready. The task starts with a placeholder name taken from the first line of your prompt. A task started from a Linear issue or a pull request takes its title instead.
While the worker fetches the repository, your agent writes a short title and a branch name. A task started on an existing branch keeps that branch’s name and only gets a new title. A title from a Linear issue or a pull request is kept, and only the branch name is generated. The worker then creates the worktree, copies in the machine’s workspace files, starts the agent, and runs the repository’s setup script alongside it if there is one. The agent is told to wait for setup to finish before relying on it.
Naming uses your own agent on its smallest model, so it runs on your subscription, and it never delays task creation. If the agent is slow or unavailable, the placeholder name and branch stay. You can change how tasks are named with the Task naming prompt. See Custom prompts.
Better titles from the conversation
When a prompt is too vague to name well, such as “fix this” or a bare link, the agent says so while naming. Rivets then names the task again from its conversation once the first run finishes. Only those tasks are re-titled, so a task that got a good name keeps it.
To ask for a new title at any time, choose Regenerate title from the task’s sidebar row, its row on Home, the task’s menu, or the command palette. On Mac it is also in the menu bar. The new title comes from your messages and the agent’s answers so far. If the current title already fits, Rivets keeps it and says so.
A name you gave the task yourself always wins: automatic re-titling never replaces it. The first chat’s title follows the task’s title.
Work in a task
More conversations
A task can hold several conversations, each in its own tab, all working in the same checkout. Choose + (New tab) in the tab strip and pick Chat, or press ⌘T. The same menu has Review changes, Terminal, and Browser. On web, Browser opens a new browser tab. On Mac, iPhone, and iPad it opens inside Rivets.
On iPhone, tapping a task opens its chat directly when it has one chat, or exactly one that is running, queued, or awaiting approval. Otherwise you see the task’s overview first.
Rename
Choose Rename from a task’s sidebar row or its row on Home, or Rename task from the command palette. On web and Mac, you can also double-click the task name in the header. Rename a conversation with Rename chat in its tab menu.
Discard changes
In the Changes tab, you can undo uncommitted changes to one file from its menu or its diff. The action depends on the file:
| File | Action |
|---|---|
| Modified | Discard changes returns it to the last commit. This cannot be undone. |
| New | Delete file removes it from the worktree. This cannot be undone. |
| Deleted | Restore file brings it back from the last commit. |
| Renamed | Undo rename moves it back to its old path. |
Archive and restore
When the agent has finished, choose Archive task in the task header, or Archive from its row in the sidebar or on Home. On iPhone and iPad it is in the task’s actions menu. Archived tasks can be restored for 7 days: choose Restore on the notice that appears, or on Home switch to Showing archived and choose Restore.
By default, Rivets also archives a task when its pull request is merged. See Pull requests and merging.
Archiving frees the worker straight away. It stops the task’s run scripts and dev servers, closes its terminals and idle agent processes, withdraws its previews, and runs the repository’s archive script if one is defined. The checkout stays on disk. Restoring the task runs its setup script again, attributed to whoever restored it. See The .rivets directory.
Home
Home lists active tasks across your repositories. On web, Mac, and iPad, you can:
- Search tasks, or filter to one project.
- Switch between Showing archived and Hiding archived.
- Rename, regenerate the title of, archive, or copy the branch name of a task from its row menu.
On iPhone, Home groups tasks by repository, with archived tasks in their own Archived section.
Home also shows your workers’ subscription usage. See Clusters and routing.
Repository settings
Open a repository’s settings from its project in the sidebar: choose the gear that appears when you hover over it, or right-click it and choose Settings…. On iPhone, choose Settings… in the repository’s ⋯ menu.
Project order
Drag projects in the sidebar to reorder them, or use Move up and Move down in a project’s menu. The order is yours alone, for each organization: it syncs across web, Mac, iPhone, and iPad, and a teammate’s order never changes yours. You can reorder on web, Mac, and iPad.