Jujutsu for Agents

Core Concepts

Working copy is a commit. Every file edit auto-snapshots into @. No staging area.

Change IDs persist. Always reference Change IDs (e.g., zsowkzkt), not commit hashes. IDs survive rebases.

Conflicts don't halt. jj records conflicts in commits; fix them later.

Quick Reference

Task	Command
Check state	jj status --no-pager
Name current work	jj describe -m "message"
Seal and start new	jj new
Jump to commit	jj edit <change_id>
Move file to parent	jj squash --into @- <file>
Create bookmark	jj bookmark create <name> -r @
Push bookmark	jj git push --bookmark <name>
List conflicts	jj resolve --list
Undo last operation	jj undo
Find by description	jj log -r 'description("text")' --no-graph -T 'change_id "\n"'
Format code	jj fix
Quick lint check	jj quality
Full verify + push	jj secure-push
Post-merge sync	jj git fetch && jj rebase -s <next> -d main

Workflow Patterns

Basic Loop

# 1. Edit files (auto-snapshots)
# 2. Name the work
jj describe -m "feat: add feature"
# 3. Seal and continue
jj new

Edit Mid-Stack

# Find and jump to target
jj edit <change_id>
# Make edits (auto-snapshots)
# Return to tip
jj edit <tip_id>
# Verify no conflicts
jj log -r '::@' --template 'change_id " " conflict "\n"'

Post-Merge Sync (after GitHub merges)

jj has no git pull --rebase equivalent. After a PR is merged on GitHub:

# 1. Fetch the merged commit
jj git fetch

# 2. Rebase remaining work onto new main
jj rebase -s <oldest-unmerged-change-id> -d main

Important: Always use gh pr merge --rebase (not --squash). With rebase-merge, jj recognizes the commit is on main. Squash-merge creates a new hash, leaving orphaned "zombie" commits.

Forbidden Commands

• jj split — requires TUI, use construction method
• jj resolve — requires TUI, parse and rewrite conflict markers manually

Quality Gates

This project uses jj fix for auto-formatting and custom aliases for verification.

Philosophy

• Category A (formatters): Run jj fix anytime — auto-applies ruff, prettier, buf format
• Category B (verifiers): Run jj secure-push before pushing — runs all linters, type checkers, tests

Commands

Command	Purpose	Speed
jj fix	Format modified files (ruff, prettier, buf)	~5s
jj fix-all	Format entire repo	~30s
jj quality	Quick check: format + lint + type-check	~30s
jj secure-push	Full pipeline: format → lint → build → test → push	~5min

Workflow Integration

# While coding: format often
jj fix

# Before pushing: verify everything
jj secure-push --bookmark my-feature

# Quick sanity check (no tests)
jj quality

What Runs

jj fix: ruff-format, ruff-fix (isort/pyupgrade), prettier, buf format

jj secure-push: buf lint → pyright → eslint → prettier check → angular build → pytest → vitest → playwright → e2e → generated code check → push

Detailed Protocols

See references/workflows.md for:

• State verification protocols
• Non-interactive splitting techniques
• Post-merge sync workflow
• Conflict resolution steps
• Safety and recovery operations

See references/divergent-changes.md for:

• Identifying divergent changes (multiple commits with same change ID)
• Resolution strategies: abandon, give new ID, squash, or ignore
• Common causes and prevention