How Paperclip Integrates with Git for Worktree Execution

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.

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

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:

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, 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	Core abstraction wrapping git clone, git worktree add, and git worktree remove commands
server/services/workspaceService.ts	Server-side orchestration of worktree creation, execution context setup, and cleanup scheduling
ui/components/WorkspaceSelector.tsx	User interface for selecting Git worktree as the execution strategy
ui/storybook/stories/agent-management.stories.tsx	UI documentation demonstrating worktree strategy selection
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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}