Jujutsu Workspace — Agent Workspace Isolation

Agents use jj workspace to safely work in parallel within Jujutsu (jj) repositories. jj workspace eliminates branch binding, shares an operation log, and has immutable Change IDs for life — making it more suitable for agent operations than git worktree.

Triggers

• Agent needs to work in parallel within a jj-managed repository
• Agent needs stable commit references (unchanged across rebases)
• Migrating from git worktree to jj workspace
• Multiple agents share the same repository and need independent workspaces
• User mentions "jj workspace", "jj working copy", "Change ID"

Requirements

• jj >= 0.35.0 (recommended) — 0.6.0+ usable, 0.35+ includes per-workspace config and colocated conversion
• Verify: jj --version
• Git-compatible backend (automatic): jj manipulates Git objects via the Gitoxide library

Core Concepts

Lifecycle

1. Initialization (first-time jj usage)

# Initialize on top of an existing git repo (colocated = .jj/ + .git/ coexist)
jj git init --colocate

# Or pure jj repository
jj git init

2. Create Workspace

# Agent recommended pattern: name by task ID
jj workspace add --name "task-${TASK_ID}" "<path>"

# Create based on a specified revision
jj workspace add --name "feature-x" --revision main "@path"

# Specify sparse patterns
jj workspace add --name "sparse-ws" --sparse-patterns copy <path>

3. Use Workspace

cd <workspace-path>
# Create a new change
jj new -m "Implement feature"
# Edit files...
# Describe the change
jj describe -m "Complete feature implementation"
# Check status
jj st

4. List & Status

jj workspace list              # All workspaces
jj workspace root              # Root path of current workspace
jj workspace root --name <n>   # Root path of specified workspace

5. Stale Recovery

# When another workspace has modified the current workspace's working-copy
jj workspace update-stale
# Auto-snapshots current changes → updates to new commit → creates recovery commit (if needed)

6. Cleanup

# Forget workspace (repo stops tracking, files remain)
jj workspace forget <name>

# Delete disk files
rm -rf <workspace-path>

Recommended Patterns for Agents

Per-Task Workspace

TASK_ID="t_8894c1db"
WS_PATH="./workspace-${TASK_ID}"

# Create
jj workspace add --name "task-${TASK_ID}" "$WS_PATH"
cd "$WS_PATH"

# Work
jj new -m "Task ${TASK_ID}: research"
# ... edit ...
jj describe -m "Task ${TASK_ID}: complete"

# Clean up after completion
jj workspace forget "task-${TASK_ID}"
rm -rf "$WS_PATH"

Multi-Agent Parallel Pattern

# Agent 1: create workspace + independent work
jj workspace add --name agent-1 ./workspace-agent-1
cd ./workspace-agent-1
jj new -m "Agent 1 task"
# ... work ...

# Agent 2: create another workspace (parallel, no lock contention)
jj workspace add --name agent-2 ./workspace-agent-2
cd ./workspace-agent-2
jj new -m "Agent 2 task"
# ... work ...

# Agent 1 needs to sync Agent 2's changes
jj workspace update-stale  # Non-destructive sync

# Cross-workspace reference (Change ID unchanged)
jj edit <change-id-from-agent-2>

Migrating from Git Worktree

# Old way (git worktree)
git worktree add ../task-1 -b wt/task-1

# New way (jj workspace)
jj git init --colocate                    # One-time initialization
jj workspace add --name task-1 ../task-1  # Subsequent usage

Concurrency Safety

Cross-Workspace References

# Stable reference via Change ID (unchanged across rebases)
jj edit <change-id>        # Switch to specified change
jj new <change-id>         # Create new change based on specified change
jj diff --from <id1> --to <id2>  # Compare two changes

# View working-copy of all workspaces
jj log -r 'working_copies()'

Pitfalls

1. Stale Working Copy

Symptom: Command reports "working copy is stale" when run. Cause: Another workspace modified the current workspace's working-copy commit. Solution: jj workspace update-stale (non-destructive, automatically preserves uncommitted changes).

2. Colocated Mode Caveats

Symptom: jj and git commands behave differently in the same directory. Cause: In colocated mode, .jj/ and .git/ coexist; Git is unaware of jj's change model. Solution: Use jj commands for change operations (jj new, jj describe), use git commands only for push/pull.

3. Change ID Reference Lifecycle

Symptom: After jj workspace forget, Change ID still exists in the operation log. Cause: forget only removes workspace tracking, does not delete the commit. Solution: To fully delete, use jj abandon <change-id>.

4. Workspace Disk Leakage

Symptom: Abandoned workspace directories accumulate (100 MB–2 GB+ each). Solution: Implement a two-phase cleanup: jj workspace forget <name> && rm -rf <path>.

5. Empty Commit Causes @ Drift

Symptom: After jj commit, @ moves to (empty) state. Cause: jj's auto-snapshot has already captured all changes before the commit. Solution: jj bookmark set main -r <parent> --allow-backwards.

Quick Reference

Sources

• jj official documentation: https://docs.jj-vcs.dev/latest/working-copy/
• jj GitHub: https://github.com/jj-vcs/jj
• jj FAQ: https://docs.jj-vcs.dev/latest/faq/
• jj vs. Git comparison: https://docs.jj-vcs.dev/latest/git-comparison/