Jj

---
name: jj
description: >-
  Drives jujutsu (jj) version control on the user's behalf so they don't have to
  memorize commands. Use for single-agent feature work (the default), whenever the
  user mentions jujutsu/jj, when undo-safety or a clean rewritable history matters,
  or when starting/finishing a change in a jj-managed repo. For MULTI-agent parallel
  work use git worktrees (or jj workspaces) instead — see "jj vs worktrees" below.
---

# jj (jujutsu)

The user adopts the convention: **jj for single-agent work, worktrees for
multi-agent work.** They do NOT want to memorize jj commands — you drive jj
correctly on their behalf. Repos are **colocated** (jj on top of git), so `git`
and `gh` still work and GitHub/PRs are unchanged.

## Preflight (every session in a jj repo)

1. `command -v jj` — if missing, say so and fall back to plain git. Install:
   `cargo install --locked jj-cli` or `brew install jj` (mention, don't auto-run).
2. Detect a repo: `jj root` succeeds inside one. If a git repo isn't yet jj-managed
   and the user wants jj, run `jj git init --colocate` (keeps `.git`, adds jj on
   top; `--colocate` is the default in recent versions but pass it explicitly).

## Mental model (so you operate it correctly)

- **The working copy IS a commit**, addressed as `@`. There's no staging area and
  no "dirty tree" — every edit is auto-committed into `@` on the next `jj` command.
- **Changes are anonymous and rewritable.** A change keeps a stable change-ID even
  as you amend it. You freely edit history; jj records each rewrite (undoable).
- **Bookmarks ≈ git branches** — named pointers you attach to a change to push to
  GitHub. They do NOT auto-advance with `@`; you move/set them when ready to push.
- `@-` means "the parent of the working copy" (i.e. the change you just finished).

## The commands you'll actually use

| Goal | Command |
|------|---------|
| See state | `jj status` (alias `jj st`) |
| See history | `jj log` |
| Start a new change | `jj new` (fresh empty change on top of `@`) |
| Start off main | `jj new main` |
| Set/refine the message | `jj describe -m "feat: ..."` (describes `@`) |
| Finish change + start next | `jj commit -m "..."` (= describe `@` then `jj new`) |
| Move edits into parent | `jj squash` (or `jj squash -i` for hunks) |
| Edit an earlier change | `jj edit <change-id>` then make edits |
| Undo last operation | `jj undo` (or `jj op log` → `jj op restore <id>`) |
| Pull from remote | `jj git fetch` |
| Rebase onto updated main | `jj rebase -d main` (confirm the flag with `jj rebase --help` — destination flag naming has varied by version) |

Typical single-agent flow:
```
jj new main                      # start work
# ...edit files (auto-committed into @)...
jj describe -m "feat: add X"     # give @ a message
# ...keep editing; @ keeps updating...
```

## Pushing to GitHub (colocated repo)

A change needs a **bookmark** before it can be pushed as a branch:
```
jj bookmark create my-feature -r @     # name the current change
jj git push --bookmark my-feature      # push (force-pushes safely if rewritten)
```
Or let jj auto-name and push in one step:
```
jj git push -c @                       # -c/--change generates a bookmark + pushes
```
After pushing, open the PR with the existing tooling: `gh pr create`. To update an
existing branch after more edits, move the bookmark then push:
```
jj bookmark move my-feature --to @
jj git push --bookmark my-feature
```
The user's gh-bootstrap / branch-hygiene system still applies — squash-merge +
delete-on-merge are unchanged because the remote is plain git.

## jj vs worktrees (when to use which)

- **Single agent, one task at a time → jj.** Default. Anonymous changes + `jj undo`
  give cheap experimentation and a clean rewritable history.
- **Multiple agents in parallel → git worktrees** (the user's established habit,
  managed by their existing worktree/branch-hygiene tooling). Keep using those.
- **jj's own equivalent of worktrees is `jj workspace`** — multiple working copies
  backed by one repo, each with its own `@`. Use it when staying inside jj for
  parallel checkouts:
  ```
  jj workspace add ../repo-feature-x          # new working copy at that path
  jj workspace add --name fx ../repo-fx        # explicit name
  jj workspace list
  jj workspace forget <name>                   # then rm -rf the dir
  jj workspace update-stale                     # if another workspace moved a shared change
  ```
  Map of habits: `git worktree add` → `jj workspace add`; `git worktree remove` →
  `jj workspace forget` + delete the directory.

## Gotchas

- **Bookmarks don't follow `@`.** After more commits you must `jj bookmark move
  --to @` before pushing, or the remote branch lags behind.
- **No staging area.** Don't reach for `git add` / `git commit -p`; use `jj squash`
  / `jj squash -i` to shape what goes into a change.
- **Don't mix raw `git commit` with jj in the same repo.** Reading via git is fine;
  let jj own the commits. jj auto-syncs on each command, but manual git commits can
  surprise it (`jj` will import them as a new change).
- **`@` is never empty for long** — running almost any `jj` command snapshots the
  working copy first, so "uncommitted changes" effectively don't exist.
- **`update-stale`**: if a workspace shows a stale working copy, run
  `jj workspace update-stale` rather than fighting it.
- **Conflicts are first-class** — jj records conflicts in a commit instead of
  blocking. Resolve in the working copy, then `jj squash`/continue; nothing aborts.
- **Version drift**: exact flags (`rebase -d`, `--colocate` default) vary by jj
  version. When unsure, `jj <cmd> --help` is authoritative.