This document instructs Claude Code to use `jj` (Jujutsu) instead of `git` for version control operations. jj is a Git-compatible VCS that provides a simpler mental model and powerful history editing.
Use jj (Jujutsu) instead of git for version control. jj is Git-compatible
with a simpler model and powerful history editing.
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.
@ is your current working copy commit.| Git | jj |
| --- | --- |
| branch | bookmark |
| HEAD | @ (working copy) |
| checkout | edit / new |
| stash | not needed — just jj new |
| commit --amend | just edit @, changes auto-apply |
| Action | Command |
| --- | --- |
| Status | jj st |
| Log | jj log (jj log -r 'all()' for everything) |
| Diff working copy / a commit | jj diff --git / jj diff --git -r <rev> |
| Show a commit | jj show <rev> |
| Describe @ | jj desc -m "feat: …" |
| New commit on @ / on a rev | jj new [-m "…"] / jj new <rev> |
| Edit an existing commit | jj edit <rev> (descendants auto-rebase) |
| Squash into parent | jj squash -m "…" (-r <rev> for a specific one) |
| Squash paths across commits | jj squash --from <src> --into <dst> <paths> |
| Restore paths from a rev | jj restore --from <rev> <paths> |
| Split by file | jj split <path>... (--parallel for siblings) |
| Absorb into ancestors | jj absorb (see caveat below) |
| Rebase | jj rebase -d <dest> (-r one, -s +descendants, -b branch) |
| Bookmarks | jj bookmark create\|set\|delete <n> · jj bookmark track <n>@origin |
| Fetch / push | jj git fetch / jj git push -b <n> |
| Conflicts / undo | jj log -r 'conflicts()' / jj op undo |
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>.
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.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.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.LLMs can't drive TUIs, so always use non-interactive forms:
-m "…" to describe, squash, commit, new.
jj split takes -m "first" -m "second" for both halves.--from/--into
and --from <rev> <paths> forms above.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):
jj new -m "next thing" between steps; you never
need split.jj new; edit @ to part A's state; jj squash --from <original> --into @ <paths>; the original now holds only part B.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"
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer