convez.ai
AgenteAutomaçãoAvançado
DannyGoodall

Claude Code JJ

DannyGoodall/claude-code-jj

Orquestração paralela de agentes com jj workspaces e proteção de specs

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent para orquestração multi-agentes em fluxos de trabalho paralelos usando Jujutsu (jj) como VCS. Integra GitHub, OpenSpec e Linear com isolamento seguro de tarefas, validação de especificações e reconciliação automática sem bloqueios de merge.

Instalação

$npx convez-ai DannyGoodall/claude-code-jj

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
1
Contribuidores
1

Casos de uso

  • Paralelizar alterações de código em múltiplos agentes sem conflitos
  • Integrar especificações OpenSpec com validação pré e pós-voo
  • Automatizar stacks de PRs no GitHub com landing CI-gated
  • Gerenciar workflows complexos entre GitHub, Linear e OpenSpec

Veredito

Ferramenta sofisticada para equipes que precisam de orquestração multi-agente segura. Exige domínio de jj e entendimento profundo de workflows distribuídos, mas elimina classes inteiras de problemas de merge e sincronização.

README

A tradução para o português deste README ainda está na fila.

claude-code-jj

claude-code-jj is a quality-of-life plugin family for Claude Code that smooths everyday work across GitHub, OpenSpec, and Linear — with concurrent multi-agent orchestration powering it underneath. A standout is the OpenSpec integration: it parallelizes a change by splitting its tasks across multiple agents while protecting the specification itself — disjoint task-group ownership so agents never clobber each other's work, plus spec-validation discipline at both ends (a pre-flight health check before work starts and a verify gate before anything lands).

It all runs on Jujutsu (jj) workspaces, whose lock-free, conflict-tolerant model is what makes the parallelism safe: each agent works in its own workspace (physical file isolation), commits are auto-snapshotted so nothing is lost to a crash, and integration never halts because jj conflicts are first-class objects rather than a blocked merge.

This is the jj successor to a Graphite/git-worktree orchestration.

Documentation:

  • JJ_OVERVIEW.md — new to jj? Start here: the working-copy-as-commit model, colocated jj-on-git, and how jj workspaces differ from git worktrees.
  • MANUAL.md — operating the plugins: the orchestrator/worker contract, workspace lifecycle, /jj-delegate, the fan-out, /jj-fleet, /jj-pr, /jj-openspec, the Linear binding, the hooks, and a gotchas/troubleshooting table.
  • DESIGN.md — the design rationale (ADR): why jj over GitButler (shared-tree write race) and over git worktrees (restack-while-checked-out hazard).
  • ROADMAP.md — the proposed-but-not-yet-built features (OpenSpec proposals under openspec/changes/).
  • docs/case-studies/linkstack-walkthrough.md — learn by example. One beginner ("Sam") builds one tiny web app and, step by step, uses every feature of all four plugins — each with what you type in Claude and the jj/gh/Linear commands it abstracts. Start here if you'd rather see the tools in action than read reference docs.

Plugins

PluginWhat it adds
jj-concurrentThe core. Skills: jj-delegate (orchestrator/worker lifecycle), jj-fleet (one at-a-glance status view of all in-flight workers), jj-pr (push a bookmark + create/update its GitHub PR — the "submit" jj lacks), jj-stacked-pr (one based PR per bookmark from a stitched stack), jj-land (land a PR stack bottom-up, CI-gated, retargeting each base to trunk), jj-absorb (amend-after-review: distribute scattered hunks into their downstack commits), jj-checkpoint / jj-rewind (record a named op-log save point before a risky step, then roll back to it), jj-preview (stand up a throwaway dev environment from any commit/bookmark, then tear it down). Plus the jj-workspace-worker agent, a snapshot hook (jj util snapshot after every edit — closes jj's crash-before-snapshot gap), and a guard hook (blocks raw mutating git, interactive jj, and rm on the .jj/.git stores; also enforces the orchestrator-only rule — a worker may not run jj bookmark/jj git push). Workflow-agnostic.
jj-concurrent-openspecjj-openspec skill — backgrounds an OpenSpec verb (apply / propose / new / ff / relay) in its own jj workspace, mapping verb → shape → reconcile tail. apply can fan out across a change's separable tasks.md groups, run a multi-change pipeline over a set of changes (concurrent siblings → independent landings or a stitched stack), and runs /opsx:verify as a gate that auto-archives on green; relay chains author → human go/no-go → apply in one command; a pre-flight health check validates artifacts before dispatch. Enable only in OpenSpec repos.
jj-concurrent-linearjj-linear skill — Linear binding over the orchestrator, two halves meeting on the agent-plan manifest: at dispatch, auto-create an umbrella issue + one sub-issue per worker and thread their IDs into the manifest; at reconcile, map each worker's report to its sub-issue (in-progress → done / blocker comment), post a four-section umbrella summary, and raise a human-gate sub-issue on a manual signal. Separate, separately-enabled binding; enable only in Linear-tracked repos (requires a configured Linear MCP server).
jj-lifecycleSolo jj→GitHub lifecycle, decoupled from concurrency and OpenSpec so it installs on its own. Skill: jj-release — cut a GitHub release for the repo at a commit, relay-shaped (prepare → human go/no-go gate → publish): a CI gate read off the target commit's checks, a SemVer bump auto-proposed from conventional commits and always confirmed (asks outright on a first release), release notes generated from commits/PRs and editable in conversation, tag-only vMAJOR.MINOR.PATCH versioning (no manifest is touched), a 0.x → --prerelease policy, and an optional opaque artifacts hook. The tag is created server-side via gh release create --target, sidestepping jj's missing tag creation and the guard hook; refuses to overwrite an existing release.

This marketplace does not vendor a jj command reference — it depends on the excellent read-only jj-vcs@toolbox (schpet), installed unmodified, for the worker's jj vocabulary and agent-hang rules.

Prerequisites

# jj itself, colocated with git so GitHub/PRs still work
brew install jj                       # or your platform's package
cd your-repo && jj git init --colocate

# the jj reference layer (worker vocabulary) — unmodified upstream
claude plugin marketplace add schpet/toolbox
claude plugin install jj-vcs@toolbox

# GitHub CLI — required only if you use /jj-pr (push + open/update a PR)
brew install gh && gh auth login   # or your platform's package

gh (authenticated) is a prerequisite for the /jj-pr push-and-PR step and the reconcile tails that call it. Everything else — /jj-delegate, /jj-fleet, the fan-out, local jj — works without it.

Install

# 1. register the marketplace (GitHub, or a local clone path)
claude plugin marketplace add DannyGoodall/claude-code-jj   # or /path/to/claude-code-jj

# 2. refresh it — also how you pick up new plugin versions later
claude plugin marketplace update claude-code-jj

# 3. install the plugins you want (each is independent)
claude plugin install jj-concurrent@claude-code-jj             # orchestration core + GitHub reconcile tail
claude plugin install jj-lifecycle@claude-code-jj              # /jj-release — standalone, no concurrency needed
claude plugin install jj-concurrent-openspec@claude-code-jj    # only for OpenSpec repos
claude plugin install jj-concurrent-linear@claude-code-jj      # only for Linear-tracked repos

Restart Claude Code after installing. Newly installed skills and the hooks (snapshot + guard) only take effect in sessions started after install — an already-running session won't see them, even for a brand-new plugin. (/jj-release in jj-lifecycle ships no hooks, so for that plugin the restart only registers the skill.)

Quick start

# one worker, one workspace, one change
you:    /jj-delegate "add a rate limiter to the api client" feat/rate-limit
claude: plan: workload, bookmark feat/rate-limit, workspace ../wt-rate-limit,
        base <trunk>. Proceed?
you:    yes
claude: [jj workspace add -r … · bookmark create · dispatch jj-workspace-worker
         (background)] → terminal returns to you; worker edits + shapes commits
         in its workspace; reports JSON.
        [reconcile: verify · jj git push -b feat/rate-limit · jj workspace forget]

# apply an OpenSpec change on its own workspace (add "fan out" to split it across task groups)
you:    /jj-openspec apply timetabling-strand-location-grouping

# while workers run: one status view of the whole fleet
you:    /jj-fleet

# submit a finished bookmark — push + open/update its GitHub PR
you:    /jj-pr feat/rate-limit

Validation

Every functional claim has been exercised end-to-end against real jj 0.42 in colocated mode. Summary of what was run and what it proved:

AreaWhat was validatedResult
jj substrateworkspace add -r @ carries in-flight inputs; snapshot hook captures an edit against live jj; cross-workspace visibility; integration never halts (rebase with a real conflict → exit 0, first-class conflict object); stale detection + jj workspace update-stale recovery6/6
Single-worker loopa real background jj-workspace-worker provisioned → worked → reported (~28s), contract-abiding (jj only, no bookmarks/push); snapshot hook fired — a discrete snapshot working copy op appears in jj evolog between the worker's edits and its describe (the crash-gap protection); integrated via an orchestrator-owned bookmark✓
Concurrent multi-workertwo background workers dispatched in parallel on sibling workspaces (~16–17s, overlapping); physical isolation proven — each workspace held only its own file, no clobber; both integrated into one stack✓
Same-file concurrent conflicttwo workers edited the same line of one file (1.1.0 vs 2.0.0) in separate workspaces; isolation held (no race); rebase exited 0 and recorded a first-class conflict; resolved by editing markers + snapshot (never jj resolve) — the exact scenario a shared-working-tree model cannot do safely✓
Colocated jj-on-gitjj reads the full git history and jj @- == git HEAD; the colocated commit→bookmark→jj git push flow works (one-time jj bookmark track main --remote=origin after init)✓
cwd-aware guardenforces inside a jj repo / fails open outside; a leading cd <dir> is parsed so cd <non-jj> && git … is judged from the right directory6/6
/jj-openspec relaypropose (authoring) drafts the change artifacts in a workspace; the apply worker bases on the proposal revision (seed-intent — no seed commit); apply (implementing) writes the code + ticks tasks.md✓

Untested by choice: a real jj hang (intermittent by nature — resume-in-place is ready for it, since a stalled worker's edits are already snapshotted).

Status

jj-concurrent v0.7.1 · jj-concurrent-openspec v0.2.0 · jj-concurrent-linear v0.3.0 — functionally validated, documented, and self-hosting (the plugin is now OpenSpec-managed and its features ship via its own jj workers).

The v0.1.x evaluation arc (substrate, single/concurrent workers, same-file conflict, colocated jj-on-git, the cwd-aware guard, the /jj-openspec relay) and v0.2.0 (/jj-fleet, /jj-pr, the OpenSpec apply fan-out, the jj-concurrent-linear binding) are complete — see the Validation table above.

v0.3.0 adds four features, applied concurrently by the plugin's own workers and reconciled in one stack (see the fan-out case study):

  • /jj-stacked-pr — derive the parent chain from a stitched jj stack and open/update one PR per bookmark, each based on its parent (true stacked PRs).
  • /jj-absorb — amend-after-review: preview placement (by jj absorb --dry-run where available, else an op-log jj op show -p review + one-command jj op restore undo), distribute scattered working-copy hunks into their downstack commits, report where each landed.
  • /jj-checkpoint + /jj-rewind — record a named op-log save point before a risky integration, then roll the whole repo back to it via jj op restore.
  • Guard role enforcement — the guard hook now blocks jj bookmark/jj git push from a worker workspace (the orchestrator-only rule, previously contract-only), while still allowing them in the orchestrator's primary workspace.

v0.4.0 adds /jj-land — land a stack of GitHub PRs bottom-up, CI-gated, retargeting each child PR's base to trunk before merge and tidying merged bookmarks/stale workspaces. It directly closes the stacked-merge hazard that once orphaned upper PRs onto deleted feature branches. (Shipped alongside three new roadmap proposals authored in the same four-worker fan-out — see ROADMAP.md.)

v0.5.0 adds multi-orchestrator support (multi-orchestrator-namespacing): per-session agent-plan manifests (.jj-agent-plan.<session>.json), per-orchestrator workspace/bookmark prefixes, a /jj-fleet that unions all sessions, and a stale-state startup sweep — so more than one orchestrator can run in a single repo without clobbering the manifest or colliding on names. It was implemented via the first within-a-change fan-out: three workers each took a separable task group of the one change (session-id+manifest / naming+cleanup / fleet-union) and were reconciled into one branch.

v0.5.1 (jj-land-colocated-cleanup) fixes /jj-land under colocated jj: judge merge success by PR state (not the gh pr merge exit code, which fails on jj's detached git HEAD), drop --delete-branch, and explicitly delete each merged PR's remote branch in cleanup so no stragglers remain — found and fixed while landing the archive stack (#11–#14).

v0.6.0 — the workspace & dev-environment batch (3-worker fan-out, landed via the fixed /jj-land): /jj-preview <rev> (stand up a throwaway dev environment from any commit/bookmark, then tear it down), worktree-include provisioning (seed a worker's gitignored files from the .worktreeinclude / .claude/settings.json declaration instead of ad-hoc cp), and optional sparse partitions (jj workspace add --sparse-patterns so a worker's tree materialises only its lane — hard file-ownership).

v0.6.1 (jj-land-stack-restack) completes the /jj-land family: it waits for mergeability (not just CI) before each merge, defaults to --merge for multi-PR stacks, and restacks+repushes the tail after a rewriting merge — so a stack whose PRs share a file lands without cascade-conflicts. (Found while landing #16–#19, which needed a manual restack; now encoded in the skill.) It was then validated: the next batch — jj-concurrent-linear v0.2.0 below — was landed as a real 2-PR shared-file stack with the fixed /jj-land, which merged cleanly (no cascade) and left zero remote stragglers.

The guard enforces the universal safety floor (no raw mutating git, no interactive jj, no rm on the VCS store) inside jj repos for both roles, with cwd-aware repo detection, plus the worker bookmark/push restriction above.

jj-concurrent-openspec v0.2.0 — four features applied concurrently by a second four-worker fan-out, all converging on one file (jj-openspec/SKILL.md) and reconciled through a deliberate 4-way merge (case study): the relay verb (author → human go/no-go → apply in one command), /opsx:verify as a gate that auto-archives on green, a pre-flight health check of change artifacts, and a multi-change pipeline (apply over a set of changes as concurrent siblings → independent landings or a stitched stack).

jj-concurrent-linear v0.2.0 — the binding grew a dispatch half: linear-dispatch-issue-creation (auto-create the umbrella + per-worker sub-issues at dispatch, thread their IDs into the manifest) and jj-linear-reconcile-summary (a four-section umbrella summary + a human-gate sub-issue at reconcile). Landed as the shared-file 2-PR stack that validated /jj-land's stack-restack fix.

v0.7.0 — the jj-native stack & history batch, two new orchestrator skills: /jj-pr-fixup <pr> (read an open PR's review comments, fix them in a workspace based on the PR head, absorb each fix into the commit it belongs to via /jj-absorb, and re-push — the amend-after-review loop end-to-end) and /jj-keep-current (detect trunk moved, fetch + rebase the stack, re-check CI, and gate landing behind a green required-checks signal so a stale-but-green PR never lands).

jj-concurrent-linear v0.3.0 — the binding's inbound half, closing the board↔fan-out loop: /jj-from-linear <issue> (one command from a triaged ready-for-agent issue to a dispatched jj-delegate worker, with the bookmark and PR/change back-link derived deterministically from the issue) and /jj-burndown (drain a board's ready-for-agent issues as a bounded sliding-window stream of concurrent jj workers, updating each issue as its worker lands — the board becomes a work queue with jj as the engine).

v0.7.0 and linear v0.3.0 shipped together: all four remaining roadmap proposals applied in one 4-worker fan-out. Because each change added its own new skill file, the four worker branches were fully disjoint — reconciled by the orchestrator into a clean 3-PR stack (jj-concurrent skills / linear skills / docs) and landed via /jj-land with no cascade.

v0.7.1 (jj-absorb-no-dry-run-fallback) makes /jj-absorb — and, by composition, /jj-pr-fixup — run on a jj that ships jj absorb without --dry-run (e.g. 0.42, the current toolchain). The skill detects --dry-run support: where it exists, the preview-first path is unchanged; where it doesn't, it captures the pre-absorb op, runs jj absorb, reviews the placement via jj op show -p, and surfaces a one-command jj op restore undo — equivalent see-then-undo safety via the operation log. This unblocked the jj-pr-fixup live exercise on jj 0.42.

What's next is captured as OpenSpec proposals — see ROADMAP.md. Deliberately deferred (see DESIGN.md "Open questions"): smarter guard matching (it currently matches git/jj mentions in a command string, and git -C <dir> slips past — the worker contract is the primary line, the guard a backstop).

Ver o original no GitHub

Bom para

Relacionados