Concepts

Rivets has a small set of building blocks. This page defines each one and then walks through what happens when you create a task.

People and access

Organization

The top-level account for your company or team. An organization is created from a license, has a fixed number of seats, and holds your repositories, workers, and tasks. Every member is either an Owner or a Member. Owners connect repositories, manage members and teams, and change organization settings. See Licenses and seats.

You can belong to more than one organization. In the Mac app, each window shows one organization, so you can keep two side by side.

Team

A group of members with a repository grant. A team grants either a selected set of repositories or Everything, which includes repositories connected later. A member’s access is the union of all their teams’ grants. Owners always have access to every repository. See Teams and permissions.

Repository

A codebase Rivets can work on. Most repositories are connected through the Rivets GitHub App, which enables pull requests, checks, and merging. Credential-free and file:// remotes can also be added. See GitHub.

Machines

Worker

A machine that runs agents. A worker is either the rivets CLI daemon on macOS, Linux, or Windows, or the worker bundled with the Mac app. The Mac app runs a separate worker for each organization you have open in a window, while Rivets is open. A worker connects outbound to Rivets over a secure WebSocket, receives jobs, runs Claude Code or Codex inside git worktrees, and streams events back. It never listens on a port. Each worker belongs to the member who registered it, who chooses who else can run work on it. See Connect a worker and Worker access.

Cluster

A named pool of workers. Every worker belongs to one cluster. When you create a task you either let Rivets route it automatically or pin it to a cluster. A pinned task never falls back to a worker outside that cluster. See Clusters and routing.

Work

Task

The unit of work in Rivets. A task is one workspace (a branch and its checkout on a worker) plus the conversations that happen in it. Task IDs start with wt_.

Workspace and worktree

A task’s checkout on the worker. Each worker keeps one clone per repository and cuts a separate git worktree from it for every task, so tasks never share a working directory. “Workspace” is the word the apps use. On disk, a CLI worker keeps it under ~/.rivets/worktrees/<task-id>, and the Mac app’s worker under ~/.rivets/desktop/<worker-id>/worktrees/<task-id>.

A fresh worktree has only what git tracks. Gitignored files a task needs from the machine, such as a .env file, are workspace files: each worker keeps its own copy and puts them into every new worktree. Manage them from a repository’s settings. See The .rivets directory.

Conversation

A thread of messages with an agent inside a task. The apps call it a chat. A task can hold several, each shown as a tab, all working in the same checkout. A conversation is an append-only, ordered log of events, which is why every client sees the same transcript and can resume after a disconnect. Conversation IDs start with chat_.

Job

One agent run inside a conversation. Sending a prompt starts a job. Follow-up messages either steer the running job or start the next one.

Steering

Sending a message to an agent while it works. By default, the message reaches the agent without waiting for the turn to end: Claude Code reads it at its next step and keeps going, and Codex stops its current turn to read it. You can choose to queue messages until the turn finishes instead. Every message records who sent it. See Steering and multiplayer.

Handoff

Continuing a conversation somewhere else. A handoff starts a new, linked conversation, optionally on the other agent, with a bounded copy of the transcript. If a task’s worker goes offline, Rivets can also move the task to another worker, carrying its file changes with it. See Agents and models.

Snapshot

The git status and diffs a worker uploads after every tool call that may have changed files. Snapshots drive the live Changes view, so everyone watching sees edits as they happen.

Automation

A saved prompt that runs on a schedule across one or more repositories. Each run creates an ordinary task that you can open, steer, and merge. See Automations.

How a task runs

1. You create a task. You choose a repository, write a prompt, and optionally pick a start point, agent, model, and cluster.
2. Rivets routes it. Rivets only considers online workers you may use, whose owner can also access the repository. With Auto, it prefers the Mac app’s own worker when you create the task there, then workers with free capacity, then workers closest to you on the network, and spreads the rest by load. With a cluster pin, only that cluster is considered.
3. The worker prepares the workspace. It fetches the repository, names the task and its branch using your agent, creates the worktree, copies in its workspace files, and starts the repository’s setup script if one is checked in.
4. The agent works. The worker starts Claude Code or Codex in the worktree, alongside setup, and streams normalized events to Rivets. Every client subscribed to the conversation receives them in order.
5. Changes stream back. After each tool call that may have written files, the worker uploads a snapshot. The Changes view updates for everyone.
6. People steer. Anyone with access to the repository can watch. Anyone the worker is shared with can also send messages, queue follow-ups, open terminals, or start another conversation in the same task.
7. You publish. From the Checks tab you create the pull request, follow checks and reviews, resolve conflicts, and merge. After the merge, Rivets archives the task by default.

If the worker loses its connection mid-turn, it keeps unsent events in a durable queue and delivers them when it reconnects, so the turn is not lost.