> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.
# Clone Plugin
> Workspace plugin that creates fully independent git clones for complete isolation
# 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`:
```yaml theme={null}
plugins:
workspace:
name: clone
config:
cloneDir: ~/my-clones # Optional: defaults to ~/.ao-clones
```
### Configuration Options
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
```yaml theme={null}
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.
```bash theme={null}
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:
```yaml theme={null}
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:
```bash theme={null}
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:
```bash theme={null}
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:
```bash theme={null}
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
| Feature | Clone | Worktree |
| - | - | - |
| Disk usage | High (full copy) | Low (shared objects) |
| Creation speed | Slower | Fast |
| Independence | Fully independent | Shared git database |
| Use case | Isolated experiments | Parallel branches |
| Offline support | Limited (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`
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.