Ephemeral worktree isolation for Loop Engineering. Divert agent execution into an isolated git worktree, capture their changes as a reviewable `.patch` file, and instantly destroy the sandbox.

Unattended AI agents (loops) running directly in your main working tree can cause damage, overwrite untracked files, or make it incredibly tedious to untangle failed execution attempts.

`loop-sandbox` solves this by providing **ephemeral worktree isolation**:

1. It automatically creates an isolated git worktree for the agent to run in.

2. The agent runs its command, interacting with the codebase completely naturally.

3. When the command finishes, `loop-sandbox` automatically captures the agent's edits (including new untracked files) into a clean `.patch` file.

4. It nukes the worktree, keeping your main repo completely clean.

A human can then safely review the patch and apply it with one keystroke.

npm install -g @cobusgreyling/loop-sandbox

npx @cobusgreyling/loop-sandbox run -- <command>

| Command | Description |

|---------|-------------|

| `run [opts] -- <cmd>` | Run an agent command inside the isolated sandbox |

| `review` / `list` | List isolated patches ready for human review |

| Option | Description |

|--------|-------------|

| `--shell` | Spawns the command using `shell: true` (for bash -c, etc.) |

| `--base <branch>` | The base branch for the worktree (defaults to current HEAD) |

**Running a tool via an agent:**

npx @cobusgreyling/loop-sandbox run -- npx my-agent

**Running a shell command:**

npx @cobusgreyling/loop-sandbox run --shell -- bash -c "echo 'hello' > test.txt"

**Reviewing and applying patches:**

npx @cobusgreyling/loop-sandbox review

Under the hood, `loop-sandbox` leverages `@cobusgreyling/loop-worktree` and native `git worktree` primitives. It creates a temporary branch from your current HEAD, spawns your process with its `cwd` set to the isolated tree, runs `git diff --cached` to generate the patch, and uses `git worktree remove --force` to clean up.

#!/usr/bin/env node

export {};

#!/usr/bin/env node

import path from 'node:path';

import { runInSandbox, listPatches } from './sandbox.js';

async function main() {

const args = process.argv.slice(2);

if (args.length === 0 || args[0] === 'help' || args[0] === '--help') {

printHelp();

process.exit(0);

}

const command = args[0];

const root = process.cwd();

if (command === 'run') {

const runArgs = args.slice(1);

let targetCommandIndex = runArgs.findIndex(a => a === '--');

if (targetCommandIndex === -1) {

console.error('❌ Missing `--` separator before the command. Usage: loop-sandbox run [options] -- <command>');

process.exit(1);

}

const sandboxOptionsArgs = runArgs.slice(0, targetCommandIndex);

const targetCommandArgs = runArgs.slice(targetCommandIndex + 1);

if (targetCommandArgs.length === 0) {

console.error('❌ Missing command to run. Usage: loop-sandbox run [options] -- <command>');

process.exit(1);

}

let shell = false;

let base;

for (let i = 0; i < sandboxOptionsArgs.length; i++) {

const arg = sandboxOptionsArgs[i];

if (arg === '--shell') {

shell = true;

}

else if (arg === '--base') {

base = sandboxOptionsArgs[++i];

}

else {

console.error(`❌ Unknown option: ${arg}`);

process.exit(1);

}

}

const exe = targetCommandArgs[0];

const exeArgs = targetCommandArgs.slice(1);

try {

const result = await runInSandbox(root, exe, exeArgs, { shell, base });

if (result.hasChanges && result.patchFile) {

console.log('\n==================================================');

console.log(`🎉 Run completed. Changes isolated successfully!`);

console.log(`To review the changes, run:`);

console.log(` npx @cobusgreyling/loop-sandbox review`);

console.log(`\nTo apply the changes immediately, run:`);

console.log(` git apply ${path.relative(root, result.patchFile)}`);

console.log('==================================================\n');

}

else {

console.log(`\nℹ️ Run completed with exit code ${result.exitCode ?? 0}. No changes detected.`);

}

process.exit(result.exitCode ?? 0);

}

catch (err) {

console.error(`❌ sandbox error: ${err.message}`);

process.exit(1);

}

}

else if (command === 'review' || command === 'list') {

try {

const patches = await listPatches(root);

if (patches.length === 0) {

console.log('No sandbox patches found in .loop-sandbox/patches/');

return;

}

console.log('\n=== Loop Sandbox Patches ===\n');

for (const p of patches) {

const kb = (p.size / 1024).toFixed(1);

console.log(`📄 ${p.patchName} (${kb} KB)`);

console.log(` Apply: git apply ${path.relative(root, p.patchPath)}`);

}

console.log('');

}

catch (err) {

console.error(`❌ sandbox error: ${err.message}`);

process.exit(1);

}

}

else {

console.error(`❌ Unknown command: ${command}`);

printHelp();

process.exit(1);

}

function printHelp() {

console.log(`

main().catch((err) => {

console.error(err);

process.exit(1);

export interface SandboxOptions {

shell?: boolean;

base?: string;

export interface SandboxResult {

runId: string;

patchFile: string | null;

exitCode: number | null;

hasChanges: boolean;

export declare function runInSandbox(root: string, command: string, args: string[], options?: SandboxOptions): Promise<SandboxResult>;

export interface ReviewItem {

patchName: string;

patchPath: string;

size: number;

export declare function listPatches(root: string): Promise<ReviewItem[]>;

import { spawn, execFile } from 'node:child_process';

import { promisify } from 'node:util';

import { mkdir, writeFile, readdir, stat } from 'node:fs/promises';

import path from 'node:path';

import crypto from 'node:crypto';

import { createWorktree, isGitRepo, gc } from '@cobusgreyling/loop-worktree';

const runExec = promisify(execFile);

async function git(args, cwd) {

const { stdout } = await runExec('git', args, { cwd, maxBuffer: 50 * 1024 * 1024 });

return stdout.trim();

async function gitRaw(args, cwd) {

return new Promise((resolve, reject) => {

execFile('git', args, { cwd, encoding: 'buffer', maxBuffer: 50 * 1024 * 1024 }, (err, stdout) => {

if (err)

reject(err);

else

resolve(stdout);

});

});

export async function runInSandbox(root, command, args, options = {}) {

if (!(await isGitRepo(root))) {

throw new Error('loop-sandbox must be run inside a git repository.');

}

const runId = `sandbox-${crypto.randomBytes(4).toString('hex')}`;

// 1. Setup paths

const sandboxDir = path.join(root, '.loop-sandbox');

const patchesDir = path.join(sandboxDir, 'patches');

await mkdir(patchesDir, { recursive: true });

const baseBranch = options.base || await git(['rev-parse', '--abbrev-ref', 'HEAD'], root).catch(() => 'main');

console.log(`\n📦 Creating ephemeral worktree isolation: ${runId}`);

// 2. Create the worktree

const entry = await createWorktree({

root,

runId,

pattern: 'sandbox', // dummy pattern

base: baseBranch

});

const worktreeAbsPath = path.resolve(root, entry.path);

console.log(`🚀 Executing inside sandbox: ${command} ${args.join(' ')}`);

let exitCode = null;

let hasChanges = false;

let patchFilePath = null;

let extractionFailed = false;

// Signal handlers for graceful cleanup if user ctrl+c's during run

let isCleaningUp = false;

const cleanup = async () => {

if (isCleaningUp)

return;

isCleaningUp = true;

if (extractionFailed) {

console.log(`⚠️ Patch extraction failed. The worktree at ${worktreeAbsPath} and branch loop/${runId} were left on disk for manual recovery.`);

return;

}

console.log(`🧹 Cleaning up sandbox worktree...`);

try {

await git(['worktree', 'remove', '--force', worktreeAbsPath], root);

await git(['branch', '-D', `loop/${runId}`], root).catch(() => { });

await gc({ root, force: false });

}

catch (err) {

console.error(`❌ Failed to cleanup sandbox worktree. It may need manual removal:`, err);

process.exitCode = 1;

}

};

const sigHandler = () => {

cleanup().finally(() => process.exit(1));

};

process.on('SIGINT', sigHandler);

process.on('SIGTERM', sigHandler);

try {

// 3. Execute the user's command

try {

const child = spawn(command, args, {

cwd: worktreeAbsPath,

stdio: 'inherit',

shell: options.shell ?? false

});

exitCode = await new Promise((resolve) => {

child.on('close', (code) => resolve(code));

child.on('error', () => resolve(1));

});

}

catch (err) {

console.error(`❌ Execution failed inside sandbox:`, err);

exitCode = 1;

}

console.log(`\n🔍 Scanning sandbox for changes...`);

// 4. Extract diff as a patch

try {

await git(['add', '-A'], worktreeAbsPath);

const diffStat = await git(['diff', '--cached', '--stat'], worktreeAbsPath);

if (diffStat) {

hasChanges = true;

patchFilePath = path.join(patchesDir, `${runId}.patch`);

const diffOutput = await gitRaw(['diff', '--cached', '--binary'], worktreeAbsPath);

await writeFile(patchFilePath, diffOutput);

console.log(`✅ Sandbox changes captured to patch: ${patchFilePath}`);

}

else {

console.log(`ℹ️ No changes were made in the sandbox.`);

}

}

catch (err) {

console.error(`❌ Failed to extract patch from sandbox:`, err);

extractionFailed = true;

}

}

finally {

process.removeListener('SIGINT', sigHandler);

process.removeListener('SIGTERM', sigHandler);

await cleanup();

}

return {

runId,

patchFile: patchFilePath,

exitCode,

hasChanges

};

export async function listPatches(root) {

const patchesDir = path.join(root, '.loop-sandbox', 'patches');

try {

const files = await readdir(patchesDir, { withFileTypes: true });

const patches = [];

for (const f of files) {

if (f.isFile() && f.name.endsWith('.patch')) {

const patchPath = path.join(patchesDir, f.name);

const s = await stat(patchPath);

patches.push({

patchName: f.name,

patchPath,

size: s.size

});

}

}

return patches;

}

catch {

return [];

}