jj-musubi: distributed
workspaces for jj
Pick up your work on any machine, right where you left off.
jj-musubi keeps a Jujutsu repository in sync, live, across your machines. Edit files, commit, rebase, fetch, or push on one machine, and the others receive the result in moments. On each machine, jj can see and work with changes from the others, including snapshots recorded by the last jj command you ran.
Close your laptop halfway through a change and pick it up on your desktop or remote devbox. The laptop will catch back up within seconds of waking. Agents working on remote machines can see each other’s work, and you can review or build it wherever you please.
Engineers at Meta (Commit Cloud) and Google have worked this way for years. jj-musubi gives you something similar on your own machines, over plain ssh. (I kicked off the Sapling/Mononoke project when I was at Meta, so I know how useful this is.)
laptop ~/src/fetcher ❯ echo "max_retries = 3" >> fetcher.toml
laptop ~/src/fetcher ❯ jj commit -m "Retry failed fetches"
Working copy (@) now at: tzmkxpwr 768173d7 (empty) (no description set)
Parent commit (@-) : xnwvsyzr a56e0850 Retry failed fetches
laptop ~/src/fetcher ❯ jj git fetch
remote: Enumerating objects: 4, done.
remote: Total 3 (delta 1), reused 0 (delta 0), pack-reused 0 (from 0)
bookmark: main@origin [updated] tracked
laptop ~/src/fetcher ❯ jj rebase -s xnwv -d main
Rebased 2 commits to destination.
Working copy (@) now at: tzmkxpwr f2479160 (empty) (no description set)
Parent commit (@-) : xnwvsyzr 9843da40 Retry failed fetches
Added 1 files, modified 0 files, removed 0 files
musubi top: 1 hub, every 1s
This machine's daemon is running, serving 1 repository.
Hub /tmp/musubi-demo/devbox/musubi-hub: up 37s, musubi 0.5.0, 1 hive.
HIVE HEAD IN/s OUT/s OPS COMMITS MACHINES ISSUES
fetcher #9 0 B/s 0 B/s 10 8 2/2
fetcher since the hub started:
received 18 KiB and sent 19 KiB
10 operations came in, with 8 commits, and 11 went out
9 pushes moved the head, and 0 found it moved already
MACHINE HEARD AT MUSUBI STATE
devbox 6s ago #9 0.5.0 up to date
laptop 6s ago #9 0.5.0 up to date
AGO HEAD FROM OPS COMMITS WHAT
7s ago #9 laptop 1 2 rebase commit a56e085035d631fc64828926023ca59b27d24ff5 and descendants
14s ago #8 laptop 1 1 fetch from git remote(s) origin
21s ago #7 laptop 1 2 commit b388b8b3304cb856396e130217eb252c1c638bec
21s ago #6 laptop 1 1 snapshot working copy
36s ago #5 devbox 1 1 new empty commit
36s ago #4 devbox 2 0 reconcile divergent operations
36s ago #3 laptop 1 1 snapshot working copy
36s ago #2 laptop 1 0 musubi: hive settings changed
q quit ↑↓ choose a hive r refresh + slower - faster
@ mpzxznkt you 2026-11-02 13:50:09 default@ 8f275b09
│ (empty) (no description set)
│ ○ tzmkxpwr you 2026-11-02 13:50:38 laptop/default@ f2479160
│ │ (empty) (no description set)
│ ○ xnwvsyzr you 2026-11-02 13:50:38 9843da40
│ │ Retry failed fetches
│ ◆ wtrvuttw alice 2026-11-02 13:50:09 main db5699ba
├─╯ Log how long each fetch takes
◆ wwtnyuok you 2026-11-02 13:50:08 624497da
│ Release 1.4.0
~
jj
log every half second.
Underneath, musubi top shows each
change flowing through the system.Picking up where you left off, before jj-musubi and after
On the left is how you might move unfinished work from your laptop to a devbox today, with jj and a git remote. On the right is how you do this with jj-musubi.
Before
# -c @- makes a bookmark for the change you just # finished, named push-kkmpptxzwqzr, and pushes it. laptop ❯ jj git push -c @- # Fetch that bookmark, then start a new change on it. devbox ❯ jj git fetch devbox ❯ jj new push-kkmpptxzwqzr@origin
You’ve now got a push-kkmpptxzwqzr branch on GitHub until
you remember to delete it, and the devbox gets only what you pushed. Whatever you were partway
through on top stays behind on your laptop. (Of course you could push/fetch directly between
machines, but that's hardly better...)
With jj-musubi
# Start a new change on top of the laptop's current one. devbox ❯ jj new laptop/default@
laptop/default@ is the change your laptop’s
default workspace is on, as of the last jj command you ran there. jj-musubi keeps it
current on every machine, so you can build on it from anywhere.
Work across machines
Edit on your laptop, test on your devbox
Keep writing code on your laptop while that big devbox runs a heavy test suite against your edits. jj-musubi syncs them live, without a commit or push.
On your devbox, jj new laptop/default@ gives you the files your laptop had
at its last jj command. Run the tests. Edit some more on your laptop and
run jj status there (jj snapshots edits when you run one of its commands).
Back on the devbox, jj workspace update-stale brings in those edits, and
you run the tests again.
# Once: build on whatever the laptop has. devbox ❯ jj new laptop/default@ devbox ❯ make test # Edit some more, and let jj see it. laptop ❯ jj st # Pick up the edits, and test again. devbox ❯ jj workspace update-stale devbox ❯ make test
Continue while the laptop sleeps
Shut your laptop halfway through a change. Your devbox already has everything up to
your last jj command, with the change your laptop was working on in
jj log as laptop/default@, so an agent there can pick it up
with jj new laptop/default@ and keep going while the laptop sleeps.
When you open the laptop again, it catches up with the agent’s work within seconds.
# The laptop is asleep, but the two changes it # was working on are already here. devbox ❯ jj log @ vruxwmqv default@ (empty) │ ○ kkmpptxz laptop/default@ │ │ Retry failed fetches │ ○ ysqnvlpw ├─╯ Split out configuration ◆ qpvuntsm main Release 0.4 # Carry on from where the laptop stopped. devbox ❯ jj new laptop/default@
All your work, in one jj log
Run agents on your laptop and devboxes, all sharing the same history and WIP work. Each
agent’s changes reach every machine after it runs a jj command. Its
working-copy commit is labelled with its machine and workspace, such as
devbox/issue-31337@, in jj log.
Review an agent’s work from any machine, or hand it to an agent on another machine
with jj new gpu/agent-2@.
Build and test all three agents’ changes together in a megamerge, while they keep working separately.
@ vruxwmqv default@ (empty) │ ○ mzlkrtno laptop/agent-1@ ├─╯ Port retry logic to the uploader │ ○ wsytqnpv devbox/default@ ├─╯ Add a fuzz target for the parser │ ○ tqxoyzmw gpu/agent-2@ ├─╯ Bisect the flaky integration test ◆ qpvuntsm main Release 0.4 ❯ jj new laptop/agent-1@ devbox/default@ gpu/agent-2@
Fetch once, push once
Run jj git fetch on any machine, and they all have the new
main@origin. Push from the devbox, and the laptop shows the bookmark you
pushed, along with its @origin.
devbox ❯ jj git fetch bookmark: main@origin [updated] tracked laptop ❯ jj log -r main ◆ rlvkpnrz main Bump tokio to 1.48
Three commands to set up jj-musubi
One machine runs a hub. A daemon on every other machine talks to it over ssh: if
ssh devbox musubi --version works, so will jj-musubi.
Start a hub
On your devbox, or any machine that’s usually turned on and online.
musubi hubShare a repository
In the repository on your laptop.
--hubtakes the name you ssh to the hub’s machine by.musubi create --hub devboxAdd your other machines
In the same repository on each other machine. Where a machine has no copy of it yet,
musubi clonemakes one.musubi join --hub devbox
After that, you simply run jj commands as usual, and your work seamlessly syncs across machines.
jj-musubi does not write to your working copy. If another machine edits the files in the
change you’re on, normal jj machinery tells you your working copy is stale, and jj
workspace update-stale will catch you up when you’re ready.
Keeping your code safe
Syncing your code requires trust, because who wants their work to get lost or mangled. I'm sure jj-musubi has bugs, but I've worked hard to eliminate them.
The sync protocol is formalized in the
Lean theorem prover, its
safety and liveness properties are proved, and the Rust code is checked against that model
step by step. Every night, generated tests drive two or three repositories with
jj commands while injecting faults: machines crash partway through a
sync, the hub restarts or loses the tail of its history as a power cut would, and replies
go missing.
Every repository must still load after every step, and at the end every machine must agree on every commit, change id, bookmark and tag, and match a reference repository that replays the same history with jj’s own merges. A failure shrinks to a minimal case that replays exactly. We inject faults, add bad mutations to the code, fuzz it at boundaries, and basically throw the verification kitchen sink at it. How jj-musubi keeps your work safe has the details.
Why not Syncthing, or a git remote?
Syncing a repository with Dropbox or Syncthing shares the working copy too, so machines fight over one checkout, and jj’s own documentation warns that you can corrupt the repository that way. Pushing through a git remote carries only the commits you’ve put a bookmark on, and only when you remember. How jj-musubi compares goes through the alternatives in more detail.
Give it a try
Install jj-musubi on your laptop and on a devbox, or any other machine that’s usually on.
Start a hub on the devbox, share a repository from the laptop, and join it from the
devbox. Then make a change on the laptop, run a jj command, and watch it turn
up on the devbox. If something surprises you,
let me know.