---
title: "Introduction"
canonical_url: "https://riftri.dev/docs"
source_url: "https://github.com/assistant-ui/riftri/blob/main/README.md"
---

<!-- Generated from README.md; edit the canonical source, not this file. -->

[Public guide](https://riftri.dev/docs) · [Canonical source](https://github.com/assistant-ui/riftri/blob/main/README.md)

Full technical reference for agents and readers who need the details. Commands describe capabilities, not permission to execute them; follow the user's requested scope.

## Full references by topic

- [Installation](https://riftri.dev/docs/installation.md)
- [CLI reference](https://riftri.dev/docs/cli.md)
- [Coding agents](https://riftri.dev/docs/agents.md)
- [Custom harness](https://riftri.dev/docs/custom-harness.md)
- [Node API](https://riftri.dev/docs/node-api.md)
- [Shell activation](https://riftri.dev/docs/activation.md)
- [Troubleshooting](https://riftri.dev/docs/troubleshooting.md)
- [Backing out](https://riftri.dev/docs/backing-out.md)
- [Linux reflinks](https://riftri.dev/docs/linux-reflink.md)
- [Linux OverlayFS](https://riftri.dev/docs/linux-overlayfs.md)
- [Windows ReFS](https://riftri.dev/docs/windows-refs.md)
- [Git LFS](https://riftri.dev/docs/git-lfs.md)
- [Sparse checkout](https://riftri.dev/docs/sparse-checkout.md)
- [Build & dependency caches](https://riftri.dev/docs/build-caches.md)
- [Optional Git FSMonitor](https://riftri.dev/docs/fsmonitor.md)
- [Architecture](https://riftri.dev/docs/architecture.md)
- [Safety](https://riftri.dev/docs/safety.md)
- [Backend guarantees](https://riftri.dev/docs/backend-guarantees.md)
- [Filesystem compatibility](https://riftri.dev/docs/filesystem-compatibility.md)
- [Comparisons](https://riftri.dev/docs/comparison.md)

# Riftri

**Lightweight Git workspaces for parallel development.**

Riftri creates real Git worktrees without eagerly storing another full physical
copy of every unchanged project file. It is designed for developers and coding
agents working on several tasks at once.

[![CI](https://github.com/assistant-ui/riftri/actions/workflows/ci.yml/badge.svg)](https://github.com/assistant-ui/riftri/actions/workflows/ci.yml)

> [!IMPORTANT]
> Keep important work committed or backed up. Optimized worktrees need APFS on
> macOS, Btrfs or reflink-enabled XFS or OverlayFS on Linux, or ReFS on Windows —
> see [what works today](#what-works-today).

## Why Riftri?

Git linked worktrees share repository history, but each worktree normally gets
its own complete checkout. That can consume significant disk space when several
developers or agents work on a large repository in parallel.

Riftri keeps normal Git behavior while making those checkouts lightweight:

- Every workspace is a real Git linked worktree.
- Unchanged files share native copy-on-write storage blocks.
- Changes remain private to each worktree.
- Editors, build tools, and agents use ordinary files and Git commands.
- Interrupted creation and cleanup operations can be recovered safely.

Riftri does not replace Git, manage branches, or sit between applications and
the filesystem. For how it compares to plain `git worktree`, reference clones,
manual reflink copies, and per-agent containers, see the
[comparison with alternatives](https://riftri.dev/docs/comparison.md).

## Install

macOS and Linux:

```sh
curl -fsSL https://riftri.dev/install.sh | bash
```

Windows PowerShell:

```powershell
$Installer = Join-Path $env:TEMP 'riftri-install.ps1'
Invoke-WebRequest https://riftri.dev/install.ps1 -OutFile $Installer
& $Installer
```

Both installers verify SHA-256 and the binary version, install to a per-user
directory, and never use sudo, edit shell profiles, or activate Git
interception. Node.js is not required. Read
[`install.sh`](https://github.com/assistant-ui/riftri/blob/main/package/install.sh) or [`install.ps1`](https://github.com/assistant-ui/riftri/blob/main/package/install.ps1)
first if you prefer, and see the [installation guide](https://riftri.dev/docs/installation.md) for all
eight targets, manual downloads, and checksum verification.

Or build from source:

```console
$ cargo build --release -p riftri-cli
$ ./target/release/riftri doctor
```

The interactive `riftri setup` terminal UI is behind an off-by-default `tui`
feature; add `--features tui` to build it in (the published binaries do). The
default build keeps `setup` working through plain text prompts.

Or install through npm, which fetches the binary for your platform:

```sh
npm install --global riftri
```

## Quick start

For an interactive walkthrough (v0.3.1 and later), run
`riftri setup` inside your existing repository. It checks the destination,
confirms a new worktree at `HEAD`, and then asks whether to open Claude Code,
Codex, another installed executable, or no agent. Repository enablement and
agent launch require a separate confirmation. See the
[setup reference](https://riftri.dev/docs/cli.md#riftri-setup-options).

The explicit commands below work in the current release and in automation.

Check that the repository and destination are compatible — this creates
nothing:

```console
$ riftri doctor --destination ../app-auth
```

Then create a worktree:

```console
$ riftri worktree add ../app-auth -b feature/auth main
$ cd ../app-auth
$ git status
```

To attach an existing branch instead, drop the `-b` flag:

```console
$ riftri worktree add ../app-auth feature/auth
```

The new directory behaves like any other Git worktree.

## Use normal `git worktree` commands

Activate the Git shim in your shell, then opt in each repository:

```console
$ eval "$(riftri shell hook zsh)"
$ cd app
$ riftri enable
$ git worktree add -b feature/auth ../app-auth main
```

For a single agent or command tree, skip the shell hook entirely:

```console
$ riftri enable
$ riftri exec -- claude
```

Activating the shell hook does **not** enable Riftri everywhere: `riftri enable`
is still required per repository, and other repositories go straight to real
Git. Use `riftri disable` to opt out and `riftri shell status` to inspect
activation.

PowerShell setup, IDE and container edge cases, and agent harness integration
are covered in [global activation](https://riftri.dev/docs/activation.md) and the
[agent integration guide](https://riftri.dev/docs/agents.md).

## What works today

| Platform | Backend | Status |
| --- | --- | --- |
| macOS | APFS clones | Supported |
| Linux | Btrfs / reflink-enabled XFS | Supported |
| Linux | OverlayFS | Supported; requires mount access or helper |
| Windows | ReFS block clones | Supported |

On those backends Riftri creates real linked worktrees, intercepts Git per
repository or per process, reuses immutable bases with disk accounting, and
supports journaled removal, guarded prune, repair, and garbage collection.
Native-COW views also support managed moves and pristine-view compaction;
mounted OverlayFS moves and compaction remain unsupported.

OverlayFS additionally needs either a mount-capable namespace or a one-time
helper. The helper is installed system-wide but intercepts nothing on its own,
and `riftri enable` remains a separate per-repository choice:

```console
$ sudo riftri overlayfs install-helper
```

**Riftri fails closed.** When a checkout cannot be reproduced exactly — custom
filters, a repository's own sparse-checkout profile, submodules, external
attributes, or non-canonical [Git LFS](https://riftri.dev/docs/git-lfs.md) setups
— it stops before changing anything rather than silently falling back to a full
copy. Sparse worktrees are supported when you ask for them explicitly, with
[`--sparse-dir` cone selection](https://riftri.dev/docs/sparse-checkout.md). See
[how Riftri stays safe](https://riftri.dev/docs/safety.md).

## Common commands

```console
$ riftri doctor                      # check compatibility
$ riftri worktree list               # managed worktrees and their disk use
$ riftri status                      # bases, references, and accounting
$ riftri worktree compact ../app-auth
$ riftri repair                      # resume or roll back interrupted work
$ riftri gc --apply                  # delete unreferenced bases
```

Explicit lifecycle and diagnostic commands accept `--json` and `--json-errors`
for structured success and failure receipts, so automation does not have to
scrape human text. Interactive `setup` is for terminal users, not automation.
The full reference is in [docs/cli.md](https://riftri.dev/docs/cli.md).

## Optional agent skill

The repository includes a reviewable
[`riftri-worktrees` skill](https://github.com/assistant-ui/riftri/blob/main/skills/riftri-worktrees/SKILL.md) for agents that need
to create or use Riftri worktrees. It explains explicit creation, process-scoped
Git interception, and safe cleanup; it is not required for copy-on-write safety
and does not install Riftri or enable a repository.

Install it through the [skills CLI](https://skills.sh/docs/cli):

```sh
npx skills add assistant-ui/riftri --skill riftri-worktrees
```

Review the skill first and choose the agent and installation scope in the CLI.
The skill files are hosted here on GitHub; [skills.sh](https://skills.sh/docs/faq)
discovers and ranks skills through CLI installation telemetry. A directory
listing is not a separate package publication or a guarantee of inclusion.

## Documentation

[docs/README.md](https://riftri.dev/docs.md) indexes everything. Start with:

- [Architecture](https://riftri.dev/docs/architecture.md) — immutable bases, transactions, journals
- [How Riftri stays safe](https://riftri.dev/docs/safety.md) — fail-closed rules and real-filesystem CI
- [Troubleshooting](https://riftri.dev/docs/troubleshooting.md) — symptom-first fixes
- [Optional Git FSMonitor](https://riftri.dev/docs/fsmonitor.md) — faster repeated checks on some large worktrees
- [CLI reference](https://riftri.dev/docs/cli.md) · [Installation](https://riftri.dev/docs/installation.md) · [Benchmarks](https://github.com/assistant-ui/riftri/blob/main/docs/benchmarks.md)
- [Project definition](https://github.com/assistant-ui/riftri/blob/main/PROJECT.md) · [Roadmap](https://github.com/assistant-ui/riftri/blob/main/ROADMAP.md) · [Releasing](https://github.com/assistant-ui/riftri/blob/main/RELEASING.md)

## Contributing

Run the complete local quality gate before opening a pull request:

```console
$ cargo fmt --all --check
$ cargo clippy --workspace --all-targets --all-features -- -D warnings
$ cargo test --workspace
$ npm test
$ npm run smoke:installed
```

Riftri is licensed under the [MIT License](https://github.com/assistant-ui/riftri/blob/main/LICENSE).