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, register workers, manage teams, and change organization settings.

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. It 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. See Connect a worker.

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, it lives under ~/.rivets/worktrees/<id>.

Conversation

A chat inside a task. A task can hold several conversations, 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 ch_.

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, your message interrupts the current turn and is delivered straight away. You can choose to queue messages 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 and conversation

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.

Assistant

A conversational front end to Rivets. You ask it for things in plain language, and it creates and watches tasks for you. It is not a coding agent; the tasks it starts are. See Assistant.

Channel

An external place where you can talk to the assistant. Slack is available today. Microsoft Teams is next. See Slack.

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. With Auto, Rivets prefers the worker bundled in your Mac app, then workers closest to you on the network, then balances 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, and runs the repository’s setup script if one is checked in.
4. The agent works. The worker starts Claude Code or Codex in the worktree 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. Any member with access can 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.