delta

Files (56)

• SKILL.md
• openai.yaml · agents/
• blog-beyond-pass-rate.md · resources/auto/
• blog-escaping-the-tyranny-of-worktrees.md · resources/auto/
• blog-future-of-version-control.md · resources/auto/
• blog-planning-together-in-delta.md · resources/auto/
• blog-please-stop-sending-me-google-docs.md · resources/auto/
• blog-tagged-agents.md · resources/auto/
• blog-tagged-ai.md · resources/auto/
• blog-tagged-collaboration.md · resources/auto/
• blog-tagged-crdt.md · resources/auto/
• blog-tagged-delta.md · resources/auto/
• blog-tagged-deltadb.md · resources/auto/
• blog-tagged-evals.md · resources/auto/
• blog-tagged-git.md · resources/auto/
• blog-tagged-product-vision.md · resources/auto/
• blog-tagged-the-diff.md · resources/auto/
• blog-the-diff-2026-09.md · resources/auto/
• blog.md · resources/auto/
• delta-docs-llms.txt · resources/auto/
• deltadb.md · resources/auto/
• docs-account-authenticate.md · resources/auto/
• docs-account-plans-and-pricing.md · resources/auto/
• docs-agents-cloud-runners.md · resources/auto/
• docs-agents-comments.md · resources/auto/
• docs-agents-mcp.md · resources/auto/
• docs-agents-models-and-providers.md · resources/auto/
• docs-agents-review-and-sync.md · resources/auto/
• docs-agents-skills.md · resources/auto/
• docs-agents-subagents.md · resources/auto/
• docs-agents-terminals.md · resources/auto/
• docs-agents-threads.md · resources/auto/
• docs-collaboration-collaborate-thread.md · resources/auto/
• docs-collaboration-delta-on-the-web.md · resources/auto/
• docs-concepts-core-concepts.md · resources/auto/
• docs-concepts-delta-and-git.md · resources/auto/
• docs-concepts-worktrees.md · resources/auto/
• docs-configuration-keybindings.md · resources/auto/
• docs-configuration-project-setup.md · resources/auto/
• docs-configuration-settings.md · resources/auto/
• docs-delta-101.md · resources/auto/
• docs-getting-started-quick-start.md · resources/auto/
• docs-getting-started.md · resources/auto/
• docs-installation.md · resources/auto/
• docs-llms.txt · resources/auto/
• docs-privacy-and-security-agentic-safety.md · resources/auto/
• docs-privacy-and-security-data-storage.md · resources/auto/
• docs-privacy-and-security-privacy.md · resources/auto/
• docs-privacy-and-security-security.md · resources/auto/
• docs-troubleshooting.md · resources/auto/
• docs-whats-in-the-latest.md · resources/auto/
• download.md · resources/auto/
• llms.txt · resources/auto/
• overview-index.md · resources/auto/
• pricing.md · resources/auto/
• roadmap.md · resources/auto/

SKILL.md (first lines)

<!-- cspell:ignore deltadb subthread subthreads subagent subagents worktree worktrees Jujutsu colocated colocate linearithmic projectless xattr -->

# Delta and DeltaDB

Delta is a multiplayer environment for coding with AI agents built by Zed Industries. Underneath Delta sits **DeltaDB**, a distributed CRDT version control and synchronization layer that records thread conversations, inline comments, and file edits continuously as fine-grained deltas rather than waiting for manual Git commits.

## Progressive disclosure and reference resources

Use the vendored documentation in `resources/auto/` as the source of truth for release-specific behavior, UI paths, and edge cases:

- **Product reference (Delta 101):** See [resources/auto/docs-delta-101.md](resources/auto/docs-delta-101.md) for the release-scoped specification of all desktop and browser behaviors.
- **Core concepts:** See [resources/auto/docs-concepts-core-concepts.md](resources/auto/docs-concepts-core-concepts.md) for how threads, projects, Delta worktrees, and checkouts fit together.
- **DeltaDB and Git integration:** See [resources/auto/docs-concepts-delta-and-git.md](resources/auto/docs-concepts-delta-and-git.md) and [resources/auto/blog-future-of-version-control.md](resources/auto/blog-future-of-version-control.md) for CRDT internals, fragment indexes, Jujutsu support, and dual Git remotes.
- **Delta worktrees and checkouts:** See [resources/auto/docs-concepts-worktrees.md](resources/auto/docs-concepts-worktrees.md) and [resources/auto/blog-escaping-the-tyranny-of-worktrees.md](resources/auto/blog-escaping-the-tyranny-of-worktrees.md) for checkout lifecycle and branch isolation.
- **Project setup (`.agents/` and `.delta/`):** See [resources/auto/docs-configuration-project-setup.md](resources/auto/docs-configuration-project-setup.md) for `.agents/prepare`, `.agents/linked`, and `.delta/` overrides.
- **Reviewing and landing changes:** See [resources/auto/docs-agents-review-and-sync.md](resources/auto/docs-agents-review-and-sync.md) for diff comparisons, review subthreads, Land skills, and pushing to `local` or `origin`.
- **Skills, subagents, and MCP:** See [resources/auto/docs-agents-skills.md](resources/auto/docs-agents-skills.md), [resources/auto/docs-agents-subagents.md](resources/auto/docs-agents-subagents.md), and [resources/auto/docs-agents-mcp.md](resources/auto/docs-agents-mcp.md).
- **Settings, keybindings, and troubleshooting:** See [resources/auto/docs-configuration-settings.md](resources/auto/docs-configuration-settings.md), [resources/auto/docs-configuration-keybindings.md](resources/auto/docs-configuration-keybindings.md), and [resources/auto/docs-troubleshooting.md](resources/auto/docs-troubleshooting.md).
- **Data storage and privacy:** See [resources/auto/docs-privacy-and-security-data-storage.md](resources/auto/docs-privacy-and-security-data-storage.md) for Cloudflare storage topology, redaction, and retention rules.

---

## 1. Core architecture: threads, Delta worktrees, and DeltaDB

Delta separates durable conversation and edit history from temporary on-disk directories:

```mermaid
graph TD
    Thread[Thread: Conversation + Attributed Turns] -->|Attaches| Project[Project: Git Repo with Remote]
    Thread -->|Owns 1 per Project| DWT[Delta Worktree: Shared History in DeltaDB]
    DWT -->|Mounted on Desktop| Checkout[Managed Checkout: .delta/worktrees/...]
    Checkout -->|git push local| LocalRepo[User Primary Checkout on Disk]
    Checkout -->|git push origin| OriginRepo[Shared Upstream Remote: e.g. GitHub]
```

### Domain model

- **Thread**: The unit of work combining an agent conversation, participant comments, and one Delta worktree per attached project. Reverting a conversation to an earlier message (`Edit > Revert Conversation to Cursor`) rewinds both the transcript and the attached Delta worktrees together.
- **Project**: The top-level folder of a Git repository opened in Delta. Every attached project **must** have a configured Git remote (used by DeltaDB to identify the repository). If multiple remotes exist, one must be named `origin`.
- **Delta worktree**: The replicated file representation and continuous edit history for a project within a single thread, stored inside DeltaDB. Unlike a Git worktree, multiple Delta worktrees can work on the same branch name concurrently without colliding.
- **Checkout**: The physical directory on a desktop machine where Delta materializes a Delta worktree for terminal commands, builds, and editors. Managed checkouts live under `.delta/worktrees/` inside the connected local clone (or in Delta's app storage when joining a shared thread without a local clone) and are deleted automatically when the thread is archived.

### How DeltaDB CRDTs work

Where Git captures discrete commit snapshots, DeltaDB records a continuous causal stream of fine-grained deltas (file edits, file tree mutations, messages, and comments):

```rust
struct EditDelta {
    insert: String,
    at: Range<usize>,
    based_on: Version,
}

enum Version {
    Git(Sha1),
    Delta(Vec<DeltaId>),
}
```

1. **Causal graph anchoring**: Each delta identifies its parent version explicitly - either a base Git object (`Version::Git(Sha1)`) or one or more prior deltas (`Version::Delta(Vec<DeltaId>)`) when concurrent edits merge. No distributed wall-clock is required.
2. **Fragment index (B-tree)**: Each document stores its text alongside a B-tree fragment index mapping character ranges to the `DeltaId` (or base Git blob) that created them. When an out-of-date concurrent delta arrives referencing position `X` in version `V`, DeltaDB queries the fragment index for version `V` and resolves concurrent insertions at the same offset deterministically via actor ID tiebreaking.
3. **Structural sharing**: Because fragment index trees are immutable, each new version allocates only the spine nodes from the root to the modified leaf and shares all unchanged subtrees with prior versions. Memory and index maintenance scale as `O(N log N)` with edit count rather than quadratically.
4. **Character-level provenance**: Because every fragment records the delta that produced it, comments and review anchors bind to stable change identities rather than brittle line numbers, surviving across subsequent edits and rebases onto new Git commits.
5. **Cloudflare storage topology**: DeltaDB stores file contents, Git commits, history packs, and checkpoints in Cloudflare R2; active thread and Delta worktree synchronization deltas and account settings in SQLite-backed Cloudflare Durable Objects; and thread/repository/collaborator metadata in Cloudflare KV and D1.

---

## 2. Git integration and bringing changes back

Delta imports all Git-tracked files (even if later matched by `.gitignore`), uncommitted modifications to tracked files, and untracked files not ignored by `.gitignore`. Untracked ignored files (such as `.env` or build outputs) stay machine-local and are never recorded in DeltaDB.

### Checkout modes

Before sending the first message in a thread, the status bar's **Project Settings** control (`Cmd+Option+O` on macOS, `Ctrl+Alt+O` on Linux/Windows) selects where the thread works:

1. **Isolated Delta Worktree (default)**: Creates a managed checkout under `.delta/worktrees/` starting from the remote's default branch (or the branch marked via **Make default branch for Delta worktrees**). Safe for parallel agents.
2. **Existing Local Checkout**: Adopts your primary repository folder in place. Gives up isolation - edits appear directly in your working tree, and `.agents/prepare` is skipped.
3. **Existing Git Worktree**: Uses a linked Git worktree already created via `git worktree`.

### The two remotes in a managed checkout

Commits made by an agent inside a managed checkout land in that checkout's isolated Git repository, **not** in your primary project folder. To move committed work out of a managed checkout, use one of its two configured remotes:

- **`local` remote**: Points directly to your primary repository folder on the same machine. Pushing a branch to `local` transfers commits immediately without a round trip through GitHub:

  ```bash
  git push local <branch-name>
  ```

  If `<branch-name>` is currently checked out in your primary repository and its working tree is clean, pushing to `local` updates the working tree in place. If the working tree has uncommitted edits to tracked files, Git rejects the push.

- **Source remote (`origin`)**: Points to your shared upstream host (such as GitHub). Additional remotes (such as `upstream` alongside a fork) are preserved automatically:

  ```bash
  git push -u origin <branch-name>
  ```

### Jujutsu (`jj`) repositories

When opening a colocated Jujutsu repository (both `.git` and `.jj` present at the root) with `jj` installed on the machine, Delta runs `jj git init --colocate` in each managed checkout, fetches bookmarks through `local`, preserves the Jujutsu operation log across archive/mount cycles, and copies identity, signing, and `trunk()` settings.

---

## 3. Preparing a repository for Delta (`.agents/` and `.delta/`)

Because managed checkouts are created on every new thread and removed on archive, repository setup must be automated and fast.

| Purpose                 | Shared Path (multi-tool)         | Delta-Specific Override             | Behavior                                                                             |
| :---------------------- | :------------------------------- | :---------------------------------- | :----------------------------------------------------------------------------------- |
| Checkout setup script   | `.agents/prepare`                | `.delta/prepare`                    | Executable script run from checkout root on mount before agent starts.               |
| Symlinked ignored files | `.agents/linked`                 | `.delta/linked`                     | Line-separated list of `.gitignore`d repo-relative paths symlinked across checkouts. |
| Cloud Runner setup      | `.agents/setup`                  | `.delta/setup`                      | Setup script for Cloud Runner environments (staff-gated in v0.20.1).                 |
| Project skills          | `.agents/skills/<name>/SKILL.md` | `.delta/skills/<name>/SKILL.md`     | Reusable agent workflows; `.delta/skills/` overrides matching frontmatter `name`.    |
| Custom thread emoji     | N/A                              | `.delta/emoji/<shortcode>.png\|svg` | Committed PNG/SVG files exposed as `:shortcode:` in messages and comments.           |

### Writing `.agents/prepare`

1. Create `.agents/prepare` (or `.delta/prepare` to override exclusively for Delta) at the repository root and mark it executable (`chmod +x .agents/prepare`).
2. Use POSIX shell syntax (`#!/bin/sh`), even on Windows where Delta executes it via Git Bash.

From MAHDTech/agent-skills, MIT.

More from MAHDTech/agent-skills