Jujutsu (jj) Usage Guide for Claude Code

Use jj (Jujutsu) instead of git for version control. jj is Git-compatible with a simpler model and powerful history editing.

Delegate noisy work to a subagent

For multi-step VCS work — history cleanup, rebase, conflict resolution, splitting commits — spawn a subagent (Sonnet) to do it and return a one-line summary. This keeps verbose jj log/diff/op log output and this reference out of the parent's context, saving tokens. Tell the subagent exactly what changed and what the end state should be.

Do NOT delegate trivial one-shots (jj describe -m … && jj git push) — spawn overhead exceeds the saving. Run those inline.

Mental model

• No staging area — every change is part of the working copy commit.
• Working copy is a commit — @ is your current working copy commit.
• Bookmarks, not branches — commits are anonymous; name a bookmark only to push.
• Conflicts are values — they don't block operations; resolve them later.
• Automatic rebasing — descendants rebase automatically when you edit history.

Command reference

Workflow

Atomic commits by construction. The cheapest path is to create commits as you go, not to split afterward. Start work with a description in place and run jj new between logical steps:

jj new main -m "refactor: extract auth helper"   # start from main
# ...edit...
jj new -m "feat: use helper in login flow"
# ...edit...

Adjust later with jj describe -m "…"; merge two commits with jj squash -m "…".

Before push:

jj log -r 'conflicts()'          # 1. no conflicts
jj st                            # 2. clean status
jj git fetch && jj rebase -d main # 3. onto latest main
jj log -r '::@ ~ ::main'         # 4. review your changes
jj bookmark create <n> && jj git push -b <n>  # 5. push

Update a PR after review: jj edit <commit>, make changes (descendants auto-rebase), jj new <tip> to return to the tip, jj git push -b <n>.

Bookmark naming: feat/user-dashboard, fix/issue-123-auth-bug, claude/<feature>-<session-id>.

Judgment notes

• jj absorb only moves hunks into ancestor commits that already touch the

same lines. It won't create commits; split mixed unrelated changes in @ first.

• Recovery: jj op log shows every operation; jj op undo reverts the last,

jj op restore <id> jumps to a known-good state. Nothing is ever truly lost.

• Colocate with git: jj git init --colocate shares the .git dir, so `jj

git fetch/push` keep both in sync and git commands still work for edge cases.

Avoiding interactive editors

LLMs can't drive TUIs, so always use non-interactive forms:

• Inline messages — pass -m "…" to describe, squash, commit, new.

jj split takes -m "first" -m "second" for both halves.

• Squash / restore specific paths without an editor — the --from/--into

and --from <rev> <paths> forms above.

• Split by file — jj split <path>... opens no editor when boundaries align

with files. Prefer it over the hunk-level TUI.

Hunk-level split within one file (no file boundary to use):

1. Split before you mess up — jj new -m "next thing" between steps; you never

need split.

1. Compose — jj new; edit @ to part A's state; `jj squash --from <original>

--into @ <paths>`; the original now holds only part B.

1. Patch round-trip (last resort, scriptable):

`` jj diff -r <rev> --git > /tmp/full.patch # hand-split into partial/rest jj restore -r <rev> && jj new -r <rev>- git apply /tmp/partial.patch && jj commit -m "part A" git apply /tmp/rest.patch && jj commit -m "part B" ``