---

Inside a Jujutsu workspace the agent stops reaching for Git and uses jj instead — and it is told why, rather than just being blocked.

• Refuses Git where it would mislead. git status in a colocated repo reports a different state than jj status. The guard catches that and hands back the command to run instead.
• A tiered jj tool surface — 28 tools by default, with core (14) and minimal (5) for smaller prompts — so the model can read and write history without shelling out and parsing output.
• Teaches the model what jj is: no staging area, @ is always a commit, change IDs survive rewrites.
• A settings panel, on the plugin's own page.

The plugin is invisible outside a Jujutsu workspace, unless you turn on Force Jujutsu (then it refuses jj there and names the init command). In a plain Git repo it otherwise does nothing at all.

Install

Install from the harness Plugins page, or:

dsh plugin install dsh-jujutsu

Then open Plugins → Jujutsu to configure it. It works out of the box; the defaults are chosen to be safe.

Requirements

jj	Required. 0.46.0 or newer. brew install jj
jj-hunk	Optional. Adds hunk-level split/squash. Without it those two tools report unavailable rather than failing. cargo install --git https://github.com/laulauland/jj-hunk --tag v0.5.1 jj-hunk
Node	24 or newer

What it does

Refuses Git, and says what to run instead

The refusal is translated, not templated: the guard parses the command you actually typed and hands back the exact jj command it maps to.

You run	What happens
git log --oneline -6	Refused: git log --oneline -6. Run: jj log -r ::@ --limit 6 --no-graph
git diff HEAD~1	Refused: git diff HEAD~1. Run: jj diff --from @-
git push origin main	Refused: git push origin main. Run: jj git push --remote origin --bookmark main
git status	Refused: git status. Run: jj status
git add src/a.ts	Refused with the reason instead of a command: there is no staging area to add to
git status --porcelain	The catalogue wording — flags that change the command are never silently dropped
git rebase -i	Refused — it needs a terminal. Suggests jj rebase, jj squash, jj absorb
rm -rf .git	Refused, and explains that jj's commit objects live there
jj status, jj log, …	Run normally
echo "git commit"	Runs — it never touched Git

Three rules make the translation safe to paste: Git revisions are rewritten into revsets (HEAD~2 → @--, because HEAD is not a jj revset), anything that does not map exactly falls back to the catalogue wording rather than a half-translated command, and every argument is shell-quoted.

Reads and writes are configured separately. A user who is happy to let the model look with Git has not thereby agreed to let it write.

The jj tools

The default full surface is 28 tools; the settings page can select core (14) or minimal (5). Every one returns structured JSON, never prose, and revisions are addressed by change ID, which survives a rewrite — a commit ID does not.

Group	Tools	What it does
Read	jj_status, jj_log, jj_diff, jj_show, jj_file, jj_evolog, jj_op_log	Working copy, history, one revision, files at a revision, evolution
Author	jj_new, jj_commit, jj_describe, jj_edit, jj_squash, jj_bookmark	Start, commit, split, reword, resume, fold, name
Hunks	jj_hunk_list, jj_hunk_apply	Select and apply individual hunks
History / recovery	jj_history, jj_op, jj_op_restore, jj_repair	Rebase, duplicate, revert, abandon, restore, undo, converge
Workspaces / verify	jj_workspace, jj_test	One workspace per agent; isolated test, run, bisect
Publish / hygiene	jj_publish, jj_fix, jj_sparse	Push/fetch/tags (gated), format the stack, sparse patterns
Coordination	jj_coordinate, jj_group, jj_doctor, jj_sign	Plan/merge/squash agent groups; readiness report; signing

Reads pass --ignore-working-copy, so a history read never snapshots another agent's half-written files. jj_status({snapshot:true}) is the explicit checkpoint and the only read that writes.

Teaches the model

The model is told, in its system prompt, that version control here is Jujutsu and what that implies. The rule is withheld where it would be false: in a plain Git repo, or in a directory with no repository at all.

In a directory with no version control, the plugin says so — so the agent can offer to initialise one, suggesting jj git init (colocated, so Git tooling still works).

Plain Git repositories can be adopted, deliberately. Turn on Use Jujutsu in Git repos and the first session in a Git repo that has no .jj runs jj git init --colocate: the history is imported and the agent gets jj, while Git tooling keeps working because .git is untouched. It is refused outright for repositories jj cannot represent — LFS (where jj would commit raw bytes over the pointer), sparse checkouts, shallow clones, linked worktrees, and a Git operation in progress. Submodules are not a blocker: jj records the gitlink and leaves the submodule to Git, so you can keep using jj in the superproject. See docs/37.

Depth is deferred rather than paid for. The rule and the workspace state ride the system prompt because they must be in force before the model's first Git command; the manual — the working-copy model, the Git→jj verb map, what each tool returns — is registered as a jujutsu runtime skill, so its cost is one catalog line until the model actually needs it. Turn it off with Offer the jj manual. Why the split is drawn there, and why the manual is not an MCP server, is docs/36.

Configuration

Open Plugins → Jujutsu. Most settings are on that page:

Setting	Default	What it changes
Guard	on	Off leaves the guard mounted but inert — useful to see what it would have caught
Read-only Git	ask	What to do with git status, git log, …
Writing Git	ask	What to do with git commit, git push, …
Remember approvals	on	Stop re-asking about a verb you already approved, for this session
Mention missing version control	on	Tell the model when a directory has no repository
Prefer Jujutsu	on	Suggest jj git init rather than git init
Explain Jujutsu in the prompt	on	Off means the guard still refuses Git but the model is not told why
Offer the jj manual	on	Ship the jj manual as an on-demand skill
Use Jujutsu in Git repos	off	Adopt a plain Git repo by creating .jj beside .git
Force Jujutsu	off	Refuse jj outside a workspace, naming jj git init --colocate
Tool surface	full	full, core (14 tools), or minimal (5 tools)
Publishing	ask	jj_publish push: ask (dry-run preview), deny, or allow
Workspace ownership	advise	off, advise, or enforce when a tool targets another workspace's @
Default grouping	merge	What jj_coordinate suggests: merge or stack

Advanced: where the binaries are found

Three settings are not on the page, because only an unusual install needs them and showing them would ask everyone else to decide about them. Set them in the profile's config instead — they are ordinary Config fields:

Setting	Default	What it changes
jjPath	jj	Set when jj is not on PATH, or to pin a specific build
jjHunkPath	jj-hunk	Same, for jj-hunk
hunkInstall	ask	What to do when jj-hunk is missing: ask, never, or auto
verifyCloneDirs	["node_modules"]	Directories jj_test copy-on-write clones into its ephemeral workspace
agentBookmarkPrefix	agent/	Bookmark prefix recording workspace ownership; empty disables
workspaceRoot	..	Directory jj_workspace add uses when no path is passed

Turning it off for one project

Drop a .dsh-jujutsu.json in the project root:

{ "enabled": false }

The nearest marker walking up from the working directory wins, so you can disable a monorepo and re-enable one vendored jj repo inside it with {"enabled": true}. The same file takes the two opt-ins per project — {"adopt": true} / {"adopt": false} for adoption and {"forceJj": true} / {"forceJj": false} for forcing Jujutsu — and {"enabled": false} vetoes both.

The file is yours to place — add it to .gitignore if the switch should stay local, or commit it to share the behaviour with your team. A malformed marker is ignored rather than obeyed, so a typo cannot silently disable the guard.

Troubleshooting

"Refused" when I wanted Git. That is the plugin working. Set Read-only Git or Writing Git to allow, or add a .dsh-jujutsu.json with {"enabled": false} for that project.

Nothing happens at all. The plugin only acts inside a Jujutsu workspace — a directory with a .jj directory, in it or any parent. Check with jj status; if that says "There is no jj repo in '.'", the plugin is correctly inactive. jj git init creates one (colocated by default). If you want the plugin to take over such a directory anyway, turn on Force Jujutsu: jj commands are then refused with the initialisation command instead of failing on their own.

The hunk tools say unavailable. jj-hunk is not installed or not on PATH. Set jj-hunk executable to an absolute path, or install it:

cargo install --git https://github.com/laulauland/jj-hunk --tag v0.5.1 jj-hunk

Do not run cargo install jj-hunk. The published crate is the same project but two minor versions behind, and its CLI is different — it rejects the query interface these tools use. Installing from crates.io gives you a jj-hunk that fails on every call with unexpected argument '--query' found, which is a confusing way to learn this. The pinned git install above is what the plugin is tested against.

jj new or jj commit is refused. The plugin refuses commit-creating commands when jj has no identity configured, because jj would create a commit with an empty author that cannot be pushed:

jj config set --user user.name "Your Name"
jj config set --user user.email "you@example.com"

Commands that preserve an author — jj describe, jj squash — are not affected.

For developers

The rest of this file is about building and verifying the plugin itself.

Build and test

pnpm run build           # tsc -> lib/   then   vp pack -> lib/client.js
pnpm run ci              # vp check, build, suite, package checks — the whole gate
pnpm run package-check   # just the tarball and release-wiring checks

lib/ is not optional and not committed. The published entry is emitted JavaScript, because Node refuses to strip types for files under node_modules (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING). That is why the plugin works from a link: install and would not work from a tarball: a link resolves to the working tree, where stripping is allowed.

Two artifacts, built two ways, because they are loaded two ways:

lib/index.js	the host half. tsc -p tsconfig.build.json, ESM, with rewriteRelativeImportExtensions so the ./foo.ts specifiers the source uses become ./foo.js
lib/client.js	the browser half. vp pack from src/client/panel.ts, CommonJS wrapped in window.__ModuleLoader__.load

The client half cannot be plain tsc output: the web client does not import a bundle, it evaluates one as a script and hands the factory a require. That wrapper is the bundler's banner/footer in vite.config.ts. The route serves ${package}/client.js and accepts only /^client\..*\.js$/, so scripts/name-client-bundle.ts renames what vp pack emits as client.cjs.

Releases do not go through a local pnpm publish. The registry entry is created by CI through npm's OIDC trusted publishing, so there is no token to hold and provenance is automatic; a hand-published version would be the one release with no provenance and no tag check. Three ways to trigger it, and the one-time setup each needs, are in CONTRIBUTING.md.

npm publish --dry-run   # what a publish would upload, from the working tree

Layout

src/	The host half — guard, tools, prompt, detection. See src/README.md.
src/client/	The panel, built to lib/client.js by vp pack. Harness primitives only.
locale/	Display name and one-liner, per language.
SPEC.md	The build specification.
docs/	40 documents: verified contracts, measurements, decisions.
research/digest.md	The durable record of the conversation that seeded the design.

What is verified, and how

Every claim about the harness was read from the 0.2.0-rc.2 source with line citations (docs/11); every claim about jj was measured against the installed 0.46.0 (docs/13). Both documents record what the sweeps did not find, and what remains open.

The guard, the jj tools, the prompt injection and the panel have all been observed working in a live session. 383 tests, pnpm run ci green.

Where this came from

The design conversation happened in a Google AI Mode thread, shared as a public link, and was scraped through an anti-bot proxy. The transcript is not kept verbatim — it carried a personal share link and a private conversation. It was distilled into research/digest.md and the raw scrape deleted. The digest is safe to publish; the thread was not.

License

MIT — see LICENSE.