JJ for Agentic Workflows

JJ (Jujutsu) enables multiple AI agents to work on the same Git repository simultaneously using isolated workspaces. Each agent gets its own working copy while sharing the underlying repository. Change IDs are stable identifiers that survive rewrites, making them ideal for agent coordination.

Initialize JJ

jj git init --colocate

The --colocate flag keeps JJ and Git in sync. Git remains in detached HEAD state (normal for JJ).

Agent Workspaces

Create isolated workspaces for agents (each needs its own directory):

jj workspace add ../agent-1 --name agent-1
jj workspace add ../agent-2 --name agent-2

Layout:

parent/
├── myproject/
├── agent-1/
└── agent-2/

Core Workflow

Start a Task

jj git fetch
jj new main -m "implementing feature X"

Complete Work

Option A - Finalize and prepare for next task:

jj commit -m "feat: add login validation"

Completed work is now @-. Report change ID:

jj log -r @- --no-graph -T 'change_id ++ "\n"'

Option B - Describe only (work stays in @):

jj describe -m "feat: add login validation"
jj log -r @ --no-graph -T 'change_id ++ "\n"'

Start Fresh

jj new main -m "next task"

Build on Another Agent's Work

cd ../agent-2
jj new kxrymlpv -m "extending agent-1's work"
jj new 'agent-1@' -m "extending agent-1's work"

Check jj status for conflicts after jj new.

Conflict Resolution

JJ handles conflicts gracefully without blocking work.

jj status

Output shows "(conflict)" for conflicted files. Resolve with:

jj resolve

Or manually edit files and let JJ auto-detect resolution. Conflicts can be committed and resolved later.

Monitor Agents

jj log -r 'working_copies()'
jj log -r kxrymlpv
jj diff -r kxrymlpv

Create a PR

Prepare Changes

jj git fetch
jj rebase -s <change-id> -d main@origin
jj squash

Push with Bookmark

Use format: username/TICKET-ID

jj git push --named "aferguson/ACCOUNT-1234" --allow-new
jj bookmark track aferguson/ACCOUNT-1234

Or explicit two-step:

jj bookmark create aferguson/ACCOUNT-1234 -r <change-id>
jj git push -b aferguson/ACCOUNT-1234 --allow-new

Update After Review

jj new aferguson/ACCOUNT-1234
jj squash
jj bookmark set aferguson/ACCOUNT-1234 -r @
jj git push

Recovery

JJ tracks every operation in an immutable log. Any operation can be undone.

jj undo

View operation history:

jj op log

Restore to any previous state:

jj op restore <operation-id>

This makes JJ safe for experimentation - rebases, squashes, and merges can always be reverted.

Additional Resources

For extended commands (rebasing strategies, squashing, merging, workspace management, revsets), see references/commands.md.