Introduction

Isolate is a workspace isolation tool built on top of JJ (Jujutsu) version control. It provides clean, isolated workspaces for AI agents working in parallel.

The Problem

Running 8-12 agents in parallel is chaos:

• Lost code — changes overwritten, gone forever
• Duplicate work — the same feature re-implemented 3-4x
• Bead stealing — agents claiming work already in progress
• Detached HEAD — constantly stuck in broken states
• Broken main — always blocked, always broken

The Solution

Workspace isolation. Each agent gets their own isolated JJ workspace. No shared state to corrupt, no coordination needed between agents.

Architecture

┌─────────────────────────────────────────────────────────┐
│  Development Phase (Isolate)                            │
│  - Agent spawns workspace                              │
│  - Agent works on feature                              │
│  - Agent runs isolate sync as main advances            │
│  - Feature validated                                   │
└─────────────────────── Hand off ────────────────────────┘
                                  ↓
┌─────────────────────────────────────────────────────────┐
│  Queue/Stacking Phase (External Tool)                  │
│  - Gets feature from Isolate                          │
│  - Handles queue, stacking, final rebase              │
│  - Merges to main                                      │
└─────────────────────────────────────────────────────────┘

Why JJ?

JJ is fundamentally better for multi-agent workflows:

• Lock-free concurrency — agents don’t corrupt each other’s work
• Operation log — undo ANY operation, recover from mistakes
• Anonymous commits — no branch name pollution at 8-12 agents
• First-class conflicts — no blocking on merges

Git Worktrees work at 1-3 agents. They break at 4+. We know because we lived it.

Quick Start

# Check where you are
isolate whereami

# Start work on a feature
isolate work feature-123

# Sync with main as it advances
isolate sync

# Complete work when done
isolate done

Requirements

• JJ (Jujutsu) must be installed
• Install via: cargo install jj-cli or brew install jj

CLI Commands

Complete reference for Isolate CLI commands.

Core Commands

These are the commands you need 90% of the time:

Session Management

Object Commands

Task (Beads)

isolate task list              # List all tasks
isolate task show <id>         # Show task details
isolate task claim <id>        # Claim a task
isolate task yield <id>        # Yield a task
isolate task start <id>        # Start work on a task
isolate task done <id>         # Complete a task

Session

isolate session list           # List all sessions
isolate session add <name>     # Create new session
isolate session remove <name>  # Remove a session
isolate session spawn <bead>   # Spawn session for agent work
isolate session sync           # Sync with remote

Status

isolate status show            # Show current status
isolate status whereami       # Show current location
isolate status whoami         # Show current identity
isolate status context        # Show context information

Config

isolate config list            # List configuration values
isolate config get <key>      # Get a config value
isolate config set <key> <value>  # Set a config value
isolate config schema         # Show configuration schema

Doctor

isolate doctor check           # Run diagnostics
isolate doctor fix            # Fix detected issues
isolate doctor integrity      # Check system integrity
isolate doctor clean          # Clean up invalid sessions

Additional Commands

Common Flags

Aliases

Quick Reference

Start Working

isolate whereami           # Check you're on main
isolate work feature-123   # Start work

While Working

isolate sync              # Sync with main
isolate context           # Check status

Finish Work

isolate done              # Complete and merge
isolate abort             # Abort and cleanup

Exit Codes

• 0: Success
• 1: Validation error (user input)
• 2: Not found
• 3: System error
• 4: External command error
• 5: Lock contention

Development Workflow

Isolate is designed for the development phase of multi-agent workflows.

The Workflow

┌─────────────────────────────────────────────────────────┐
│  1. SPAWN                                              │
│  isolate spawn <bead-id>                               │
│  - Agent claims a bead                                  │
│  - JJ workspace created                                │
│  - Agent begins work                                   │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│  2. DEVELOP                                            │
│  - Agent makes changes                                 │
│  - Runs tests locally                                  │
│  - Commits with jj describe                            │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│  3. SYNC (as needed)                                  │
│  isolate sync                                           │
│  - Fetches latest from main                            │
│  - Auto-rebases onto new main                          │
│  - Handles conflicts if any                            │
└─────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────┐
│  4. DONE                                               │
│  isolate done                                           │
│  - Feature complete                                     │
│  - Ready to hand off to queue/stacking tool            │
└─────────────────────────────────────────────────────────┘

Agent Workflow Example

Start Work

# Check you're on main
isolate whereami
# Output: "main"

# Start work on a feature
isolate work feature-abc123
# Output: "workspace:feature-abc123 created"

While Working

# Make changes to code...

# Sync with main if it has advanced
isolate sync

# Check status
isolate context

Complete Work

# Feature is done and validated
isolate done

# Hand off to queue/stacking tool
# (external process)

When to Sync

Run isolate sync when:

1. Main has advanced — other agents have merged features
2. Before completing — ensure your work is rebased onto latest
3. On conflicts — resolve and continue

Handling Conflicts

If isolate sync produces conflicts:

# Check what conflicts exist
jj status
jj diff

# Resolve conflicts manually
vim <conflicted-file>

# Commit the resolution
jj describe -m "resolve: merge conflicts"

# Continue working

Aborting

If something goes wrong:

# Preview what will happen
isolate abort --dry-run

# Abort and cleanup
isolate abort

Architecture: Dev vs Queue

Isolate handles development phase only:

The handoff happens after isolate done.

Why This Architecture

Isolate’s job: Workspace isolation during development

• Spawns isolated workspaces per agent
• Handles sync + auto-rebase while working
• Provides orientation (whereami, context)

External tool’s job: Queue management and final integration

• Receives completed features
• Handles stacking, final rebase
• Merges to main

This separation keeps Isolate focused and simple.

Why JJ?

Isolate uses JJ (Jujutsu) because it’s fundamentally better for multi-agent workflows.

The Problem with Git at Scale

Running 8-12 agents in parallel with Git:

• Detached HEAD — constant broken states at 4+ agents
• Branch pollution — 8-12 branches to manage
• Lost code — changes overwritten
• No undo — destructive operations are permanent
• Blocking merges — conflicts block until resolved

Git Worktrees work at 1-3 agents. They break at 4+.

Why JJ Works

Key Benefits for Multi-Agent

1. Lock-Free Concurrency

Multiple agents can run jj commands in parallel without repo corruption.

# Agent 1 and Agent 2 run simultaneously:
# Agent 1
jj describe -m "feat: part one"

# Agent 2
jj describe -m "feat: part two"

# Later, both sync without corruption
jj git fetch --all-remotes

2. Operation Log

Every operation is logged. You can undo anything.

# See operation history
jj op log

# Undo the last operation
jj undo

# Undo a specific operation
jj undo <operation-id>

3. Anonymous Workspaces

No branch names required.

# Create workspace - no branch name needed
jj workspace add feature-123

# Work normally
jj describe -m "feat: something"

# Push - bookmarks created automatically
jj git push

4. First-Class Conflicts

Conflicts can be committed and resolved later. No blocking.

# Sync - conflicts recorded, not blocking
jj git fetch --all-remotes

# Check for conflicts
jj status

# Resolve when ready
vim conflicted_file.rs
jj describe -m "resolve: merge conflict"

Why Not Git Worktrees?

Why Not File Locking?

File locking treats symptoms, not causes:

• Doesn’t prevent duplicate work
• Doesn’t prevent logical conflicts
• Doesn’t help when things go wrong
• Doesn’t scale

We tried Agentail/MCP. It didn’t work.

Summary

JJ enables:

• Running 8-12 agents in parallel
• Safe auto-rebase on sync
• Recovery from any mistake via operation log
• Clean workspaces without branch pollution

Git at that scale:

• Constant broken states
• Lost code
• Merge conflicts
• No recovery

That’s why Isolate is built on JJ.

Troubleshooting

Common issues and how to resolve them.

Workspace Issues

“Session not found”

# List available sessions
isolate list

# Check where you are
isolate whereami

“Workspace already exists”

# Use --idempotent to succeed if already exists
isolate work feature-123 --idempotent

“Detached HEAD”

This shouldn’t happen with JJ, but if it does:

# Check current state
jj status

# See the current commit
jj log -r @

# Create a new change if needed
jj new

Sync Issues

“Sync failed”

# Try again with verbose output
isolate sync --verbose

# Check for conflicts
jj status
jj diff

Conflicts during sync

# See what conflicts exist
jj status

# Resolve manually
vim <conflicted-file>

# Commit the resolution
jj describe -m "resolve: merge conflicts"

JJ Issues

“jj: command not found”

Install JJ:

# Via cargo
cargo install jj-cli

# Via Homebrew
brew install jj

“Cannot lock”

# Check what's locking
jj log

# Force unlock if needed (rare)
# JJ handles this automatically

Exit Codes

Getting Help

# Check isolate version
isolate --version

# Get help for a command
isolate <command> --help

# Check context
isolate context

Common Patterns

Start Fresh

isolate whereami                    # Should return "main"
isolate work feature-auth --idempotent

Continue Existing Work

isolate whereami                    # Returns "workspace:feature-auth"
# Already in workspace, continue working

Abandon and Start Over

isolate abort --dry-run             # Preview
isolate abort                       # Execute
isolate work feature-auth-v2        # Start fresh

Prevention

1. Run isolate sync regularly — Don’t let main get too far ahead
2. Use --idempotent when retrying — Prevents “already exists” errors
3. Check isolate whereami before operations — Know where you are
4. Use isolate context for full status — See everything at once