# How Paperclip Integrates with Git for Worktree Execution

> Discover how Paperclip integrates with Git for worktree execution. Learn how it isolates agent runs in temporary checkouts for code isolation, deterministic execution, and safe cleanup.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: how-to-guide
- Published: 2026-08-14

---

**Paperclip isolates every agent run in its own Git worktree, creating temporary checkouts under `.paperclip/worktrees/` to guarantee code isolation, deterministic execution, and safe cleanup.**

Paperclip's Git worktree integration provides a containerized execution environment without containers. By leveraging Git's native worktree feature, the platform spins up lightweight, ephemeral code snapshots for each agent run while keeping the main repository untouched. This architecture enables parallel execution with strong isolation guarantees.

## How Git Worktree Execution Works in Paperclip

The worktree lifecycle follows three distinct phases orchestrated by the **adapter-utils** package: creation, execution, and cleanup.

### Worktree Creation

When a task starts, `GitWorktree.create(workspaceId, repoUrl, ref)` performs the following operations:

1. Clones the target repository using `git clone --no-checkout`
2. Adds a new worktree for the given `workspaceId` with `git worktree add`
3. Checks out the exact `ref` (branch, tag, or commit SHA) required for the run

The `workspaceId` is typically the run's UUID, ensuring unique paths. By checking out a specific ref rather than a floating branch, Paperclip guarantees every execution runs against an identical code snapshot.

```typescript
import { GitWorktree } from '@paperclip/adapter-utils';

const workspaceId = 'run-9f2c1a7b';
const repoUrl = 'https://github.com/acme/project';
const ref = 'v1.4.2';   // branch, tag, or commit SHA

await GitWorktree.create(workspaceId, repoUrl, ref);
// Worktree created at .paperclip/worktrees/run-9f2c1a7b

```

### Execution Environment

Server-side services launch the agent process with the worktree path as its **current working directory** (`cwd`). This simple but powerful mechanism ensures:

- All file-system operations occur within the isolated checkout
- Import resolution and module loading use the worktree's code
- Build processes and dependency installations remain contained

```typescript
import { exec } from 'child_process';
import { getWorktreePath } from '@paperclip/adapter-utils';

const cwd = getWorktreePath(workspaceId);
exec('npm run start', { cwd }, (err, stdout, stderr) => {
  if (err) {
    console.error('Agent failed:', err);
    return;
  }
  console.log('Agent output:', stdout);
});

```

### Cleanup and Resource Reclamation

After run completion, `GitWorktree.remove(workspaceId)` executes:

```typescript
await GitWorktree.remove(workspaceId);

```

This triggers `git worktree remove` followed by directory deletion, ensuring no stale checkouts consume disk space or retain sensitive code.

## Architectural Benefits of Git Worktree Integration

| Benefit | Implementation |
|---------|---------------|
| **Isolation** | Each run receives a dedicated worktree; filesystem changes never leak between executions |
| **Determinism** | Precise ref checkout guarantees identical code versions across runs |
| **Scalability** | Multiple worktrees coexist under `.paperclip/worktrees/`, enabling parallel agent execution |
| **Safety** | Original repository remains read-only; worktrees are lightweight, disposable checkouts |
| **Transparency** | Worktree paths are user-visible in the UI, with full file browsing capabilities |

## UI Integration for Git Worktrees

The Paperclip interface exposes worktree functionality through two primary touchpoints.

### Workspace Strategy Selection

The **Agent Management** panel allows users to select the `"Git worktree"` `workspaceStrategy`. This is implemented in [`ui/components/WorkspaceSelector.tsx`](https://github.com/paperclipai/paperclip/blob/main/ui/components/WorkspaceSelector.tsx), which renders the strategy dropdown and persists user selection.

### File Viewer Integration

The **File Viewer** component reads files from the worktree provider using `provider: "git_worktree"`. This enables users to browse the exact code snapshot their agent is executing against, with paths resolved relative to the worktree root.

## Key Implementation Files

| File | Responsibility |
|------|---------------|
| [`packages/adapter-utils/src/gitWorktree.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/adapter-utils/src/gitWorktree.ts) | Core abstraction wrapping `git clone`, `git worktree add`, and `git worktree remove` commands |
| [`server/services/workspaceService.ts`](https://github.com/paperclipai/paperclip/blob/main/server/services/workspaceService.ts) | Server-side orchestration of worktree creation, execution context setup, and cleanup scheduling |
| [`ui/components/WorkspaceSelector.tsx`](https://github.com/paperclipai/paperclip/blob/main/ui/components/WorkspaceSelector.tsx) | User interface for selecting Git worktree as the execution strategy |
| [`ui/storybook/stories/agent-management.stories.tsx`](https://github.com/paperclipai/paperclip/blob/main/ui/storybook/stories/agent-management.stories.tsx) | UI documentation demonstrating worktree strategy selection |
| [`ui/storybook/stories/file-viewer.stories.tsx`](https://github.com/paperclipai/paperclip/blob/main/ui/storybook/stories/file-viewer.stories.tsx) | File browsing example using the `git_worktree` provider |

## Summary

- **Git worktrees provide process-level isolation** without container overhead, with each run executing in a dedicated checkout at `.paperclip/worktrees/`
- **Three-phase lifecycle**: `GitWorktree.create()` establishes the environment, execution services use `getWorktreePath()` for the working directory, and `GitWorktree.remove()` cleans up
- **Deterministic execution** through exact ref checkout, preventing "works on my machine" inconsistencies
- **Full-stack integration** spans the `adapter-utils` package, server-side workspace services, and React UI components

## Frequently Asked Questions

### What is a Git worktree and why does Paperclip use it?

A Git worktree is a linked copy of a repository that shares the same `.git` object store but maintains an independent working directory. Paperclip uses worktrees because they provide lightweight, fast-to-create isolation without the overhead of full clones or container runtimes. Each worktree consumes minimal disk space while guaranteeing that file changes in one execution cannot affect another.

### How does Paperclip ensure the correct code version runs?

Paperclip enforces determinism through precise ref checkout. The `GitWorktree.create()` method accepts a `ref` parameter that can be a branch name, tag, or commit SHA. The implementation checks out exactly that ref, so every run against the same workspace ID and ref executes against bit-identical code. This is critical for reproducible agent behavior and debugging.

### What happens if a worktree cleanup fails?

The `GitWorktree.remove()` method in [`packages/adapter-utils/src/gitWorktree.ts`](https://github.com/paperclipai/paperclip/blob/main/packages/adapter-utils/src/gitWorktree.ts) executes `git worktree remove` followed by recursive directory deletion. If the removal fails—due to file locks, permissions, or running processes—the error propagates to the calling service. Production deployments typically schedule retry cleanup tasks or mark worktrees for garbage collection, though the source repository in `.paperclip/worktrees/` remains safe to delete manually without affecting other runs.

### Can multiple agent runs execute in parallel using worktrees?

Yes. Because each worktree has a unique `workspaceId`-based path, an unlimited number of worktrees can coexist simultaneously. The [`workspaceService.ts`](https://github.com/paperclipai/paperclip/blob/main/workspaceService.ts) server implementation creates independent worktrees for concurrent runs without blocking. The only constraints are available disk space and system process limits, not Git or Paperclip architecture.