With jj-musubi, you use jj normally after joining a hive, the group of copies of one project. Their daemons exchange history through the hub.
Pick up on another machine
By default, jj creates a snapshot of your working directory for almost every command you run. My
shell prompt includes a call to jj status, so my shell creates a snapshot of my working copy
every time I run any command interactively.
So for me, there’s no effort needed to snapshot and send one machine’s work. jj-musubi syncs it
in the background and it shows up on other machines in moments. If you want to do this
explicitly, you can simply run jj status followed by musubi sync (which will probably have
run automatically on your behalf before you finish typing the explicit command).
The examples hand off from a laptop to a devbox; use the workspace names from musubi status.
If jj reports a stale working copy, update it
before continuing.
On your laptop, save your edits:
jj status musubi sync # for convenience, not necessary musubi statusThe
musubi syncandmusubi statuscommands are not usually necessary. Here, they’re simply ways for you to verify that that jj-musubi is doing its job.When you look at the output of those commands, check for a recent successful sync and
the hub has all its work.In the devbox’s repo, check that the laptop’s recorded change has been received:
musubi sync # also for convenience, not necessary musubi status jj log jj diff -r laptop/default@As before,
musubi syncandmusubi statusare just eyeball verification tools. I never run these commands in the normal course of events.On your devbox, you can now check out the changes that were most recently snapshotted on your laptop:
jj new laptop/default@ # a new change on top of the laptop'sThis checks out a child of the laptop’s change without moving the laptop’s checkout.
Record saves automatically
Edits sync after jj records them. To record each save, install watchman and enable its jj trigger:
jj config set --user fsmonitor.backend watchman
jj config set --user fsmonitor.watchman.register-snapshot-trigger true
Coding agents
Give each agent a workspace with jj workspace add so agents don’t share files. Their work
appears on every machine as devbox/default@ or laptop/agent-2@. Review it from any machine:
jj log -r 'working_copies()' # what every agent on every machine is working on
jj diff -r devbox/default@ # review one agent's change
Pick up an agent’s work as you would another machine’s.
Use musubi status to check syncing before starting.
Copies stay in the hive until removed. For a temporary devbox, use musubi join --lease 6h
or musubi clone <hive> <dir> --lease 6h to forget it after six hours without a local operation.
The jj-musubi skill helps agents choose a stable base,
avoid disrupting other machines, and handle stale copies and sync failures.
Link it into your agent’s skills directory, replacing ~/src/jj-musubi with your clone’s path:
ln -s ~/src/jj-musubi/skills/jj-musubi ~/.claude/skills/jj-musubi # Claude Code
ln -s ~/src/jj-musubi/skills/jj-musubi ~/.codex/skills/jj-musubi # Codex
See what other machines are doing
Workspace names in jj log show recorded work; unsnapshotted edits stay on their machine.
jj op log shows each machine’s operations with the workspace that made them, such as
laptop/default.
musubi status reports this copy’s last known sync and working copies without contacting the
hub or recording edits. It exits 0 even when reporting a problem. For all-machine reports,
logs and unattended checks, see Monitor syncing.
When another machine rewrites your working copy
A rebase or squash on another machine can make your working copy stale. The next jj command
stops and says so:
Error: The working copy is stale (not updated since operation dc4042ec91bd).
Hint: Run `jj workspace update-stale` to update it.
See https://docs.jj-vcs.dev/latest/working-copy/#stale-working-copy for more information.
jj workspace update-stale snapshots unrecorded edits before updating the files. Your
working-copy change may become divergent and need resolving.
To let jj commands update stale files automatically, set:
jj config set --user snapshot.auto-update-stale true
Then even jj log can change files under a build or editor. Set it on each machine where
you want that behavior.
Undo across machines
jj undo refuses to undo another machine’s operation, as it does another workspace’s:
Error: Refusing to undo operation bf73e005993e because it was performed in workspace laptop/default
Hint: Use `--allow-cross-workspace` to undo it anyway, or use `jj op revert` to revert a specific operation
Pass --allow-cross-workspace to undo it anyway. To revert one of this machine’s operations
after others have arrived, use its id:
jj op log # find the operation
jj op revert <id>
Undos, reverts and restores replicate like any other operation. jj op restore also puts
every machine’s working copy back where it was, so other machines’ working copies may become
stale.
When machines change the same thing
Resolve a bookmark conflict or divergent change on any machine; the resolution syncs to the others:
- A bookmark moved to different commits on two machines is conflicted everywhere, shown as
main??. Move it once, anywhere, withjj bookmark set main -r <rev>. - A change rewritten on two machines becomes divergent everywhere. Keep one version with
jj abandon <commit-id>, or combine them withjj converge. - A commit abandoned on one machine while another builds on it is rebased onto its parent, once.
In a colocated repo, sync updates the Git branches for resolved bookmarks moved by a merge. A conflicted bookmark leaves each machine’s branch where it is until you resolve it.
Fetch and push
jj git fetch on one machine updates every copy’s remote bookmarks and .git remote-tracking
refs. A jj git push shows as pushed everywhere.
Remote definitions stay local. Copies without remotes, or with unused matching remotes, still
receive Git results and share work. musubi clone adds none; it checks inherited global config,
including conditional includes for the new path, before creating the destination. To fetch or
push from another copy, configure a remote there:
jj git remote add origin https://github.com/you/app.git
A hive binds each remote name to its fetch and push destinations for its lifetime. musubi join
checks them even with --hive or when rejoining. A copy may omit a remote; a different repo
or push destination needs an unused remote name or another hive. Equivalent URL forms agree.
Renaming or removing a remote renames or removes shared bookmarks such as main@origin, but
leaves other machines’ remote definitions alone. Coordinate before anyone fetches or pushes.
Join checks destinations at that time; it cannot inspect offline config or prevent later edits.
After changing a remote URL, run musubi join again to register it; the destination must
still match. See configuration and
remote-name refusals
if joining is refused.
Configure each machine
jj config stays local, including trunk(), immutable_heads(), git.private-commits, aliases
and signing settings. Clone uses the destination’s trunk(); its one-time defaults are chosen
during setup. See the configuration
reference for config scope and reload behavior.
Set protections on every machine that needs them. immutable_heads() cannot prevent rewrites
elsewhere. git.private-commits limits that copy’s Git pushes, not what jj-musubi shares.
Abandoning operations
jj op abandon removes operations from every machine’s log, including offline members when
they return. Remaining operations keep their repo state, but descendants get new ids:
ids saved from jj op log no longer work. jj-musubi logs this as
musubi: pass on jj op abandon.
An offline member can return and take the abandon. If all remaining members took an abandon
while a copy was forgotten or out of the hive, that copy cannot sync again. The same can
happen to a copy away before its first musubi join or musubi clone sync finished: after a
day without contact, or an hour after a hub restart. It reports “this repository’s history
no longer matches the hive’s”; follow the new-copy recovery
steps.
A command already running when the abandon arrives, such as jj git fetch, still syncs its
work. If another command merges it before jj-musubi sees it, bookmarks changed by the first
command can conflict. Set them again with jj bookmark set, as after jj op abandon on one
machine.
A command finishing on an old operation can also repeat a rebase, leaving identical divergent
changes. Compare them with jj log -r '<first> | <second>' and
jj diff --from <first> --to <second>. Only abandon an unused leaf: check
jj log -r '<unwanted-commit>::' for descendants, and check bookmarks, tags and working copies.
jj abandon rebases descendants onto the parents and removes bookmarks; it does not move
them to the equivalent copy. Keep versions used by other work or references.