Skip to main content

​
Clone Plugin

The clone plugin provides workspace isolation by creating full git clones of your repository. Each agent session gets a completely independent copy, ideal for experiments that require maximum isolation.

​
Overview

Unlike worktrees which share the git object database, the clone plugin creates full repository copies for each session. This provides complete independence at the cost of more disk space and slower creation.
Use the clone plugin when you need complete isolation between workspaces, such as testing destructive operations or maintaining fully independent git histories.

​
Configuration

Configure the clone plugin in your agent-orchestrator.yaml: 
plugins:
  workspace:
    name: clone
    config:
      cloneDir: ~/my-clones  # Optional: defaults to ~/.ao-clones

​
Configuration Options

​
cloneDir
string
default:"~/.ao-clones"
Base directory where clones will be created. Path supports ~ expansion for home directory.Clones are organized as: {cloneDir}/{projectId}/{sessionId}/

​
How It Works

  1. Get Remote URL: Retrieves the origin remote URL from the source repository
  2. Clone with Reference: Uses git clone --reference to speed up cloning by sharing objects with the source repo
  3. Create Branch: Checks out the default branch and creates a new feature branch
  4. Post-Create Hooks: Runs custom setup commands after clone creation

​
Usage Example

plugins:
  workspace:
    name: clone
    config:
      cloneDir: ~/workspace/clones

projects:
  - id: my-app
    path: ~/repos/my-app
    repo: owner/my-app
    defaultBranch: main
    postCreate:
      - pnpm install
      - pnpm build

​
Requirements

The clone plugin requires:
  • Git 2.0 or later
  • Network access to the remote repository (or a local source repo)
  • Write access to the clone base directory
  • Sufficient disk space (each clone is a full repository copy)

​
Path Segment Safety

Project IDs and session IDs must contain only safe characters: a-z, A-Z, 0-9, _, - This prevents directory traversal attacks and ensures filesystem compatibility.

​
Features

​
Workspace Lifecycle

Create
  • Retrieves remote URL from source repository
  • Clones with --reference flag for faster cloning (shares objects with source)
  • Clones the default branch initially
  • Creates and checks out the feature branch
  • Runs post-create hooks
  • Cleans up partial clones on failure
Destroy
  • Recursively deletes the clone directory
  • Uses rmSync with { recursive: true, force: true }
List
  • Lists all clones for a project by reading directory contents
  • Queries each clone for its current branch using git branch --show-current
  • Skips corrupted clones with a warning message
Exists
  • Checks if clone path exists and is a valid git working tree
  • Uses git rev-parse --is-inside-work-tree
  • Has a 30-second timeout
Restore
  • Recreates a workspace after it was destroyed or corrupted
  • Clones fresh from remote
  • Checks out the feature branch (creates if needed)
  • Cleans up on failure

​
Clone with Reference

The --reference flag creates a clone that borrows objects from the source repository, significantly speeding up the clone operation and saving disk space initially.
git clone --reference ~/repos/my-app --branch main origin-url clone-path
This creates a clone that shares the git object database with the source repository, but maintains an independent working directory and ref history.

​
Post-Create Hooks

Run custom commands after clone creation: 
projects:
  - id: my-app
    path: ~/repos/my-app
    postCreate:
      - npm ci              # Clean install dependencies
      - npm run build       # Build the project
      - cp .env.example .env # Setup environment
Post-create commands run with full shell privileges. Only use commands from trusted configuration.

​
Troubleshooting

The plugin fails early if the destination path already exists to avoid accidentally deleting a pre-existing workspace.Solution: Destroy the existing workspace first:
ao destroy session-id
The clone plugin requires network access to the remote repository.If cloning from a local source, ensure the origin remote is accessible:
cd ~/repos/my-app
git remote get-url origin
For offline work, consider using the worktree plugin instead.
If the feature branch exists on remote but checkout fails, the plugin:
  1. Tries to checkout the existing branch
  2. Falls back to creating a new branch with -b
  3. Cleans up the orphaned clone on failure
Check that the branch name is valid and not protected.
If a clone directory exists but isn’t a valid git repository, the list command logs a warning and skips it:
[workspace-clone] Skipping "session-123": not a valid git repo (error message)
Solution: Manually remove corrupted clones:
rm -rf ~/.ao-clones/my-app/session-123
Each clone is a full repository copy. For multiple sessions, this can consume significant disk space.Solutions:
  • Use the worktree plugin instead (shares git objects)
  • Clean up old clones regularly
  • Use git gc to compress repository objects
  • Increase available disk space

​
Advanced Configuration

​
Clone Directory Structure

Clones are organized by project and session: 
~/.ao-clones/
  my-app/
    session-123/  # Full clone for session-123
    session-456/  # Full clone for session-456
  another-app/
    session-789/
Each directory is a complete, independent git repository.

​
Comparison with Worktree Plugin

FeatureCloneWorktree
Disk usageHigh (full copy)Low (shared objects)
Creation speedSlowerFast
IndependenceFully independentShared git database
Use caseIsolated experimentsParallel branches
Offline supportLimited (needs remote)Better (uses local refs)

​
When to Use Clone vs Worktree

Use Clone when:
  • You need complete isolation between sessions
  • Testing destructive git operations
  • Working with different git configurations per session
  • Maintaining independent git histories
Use Worktree when:
  • Working on multiple branches in parallel
  • Disk space is limited
  • Faster workspace creation is needed
  • Shared git object database is acceptable

​
Performance Considerations

​
Clone Speed

The --reference flag significantly speeds up cloning:
  • Without reference: Full object transfer (~1-2 minutes for large repos)
  • With reference: Only new objects copied (~5-10 seconds)

​
Disk Usage

Example for a typical Node.js project:
  • Source repository: 500 MB
  • Clone without reference: 500 MB per clone
  • Clone with reference: 50-100 MB per clone (initially)
  • Worktree: 10-20 MB per worktree
Over time, clones with --reference will grow as they create their own objects for new commits.

​
Security Considerations

  • Path segments are validated to prevent directory traversal
  • Existing workspace paths are protected (won’t overwrite)
  • Post-create commands run with shell privileges (trusted config only)
  • Remote URLs are retrieved from the source repo (not user input)

​
Source Code

Source: packages/plugins/workspace-clone/src/index.ts

Build docs developers (and LLMs) love

Get started for freeTalk to us