jj-skipper

jj-skipper

Makes jj (Jujutsu) the native VCS for AI coding agents.

jj-skipper provides a single source of truth for jj knowledge, guard logic, and workflow automation that works with both Claude Code and OpenAI Codex — without duplicating content or maintaining parallel configurations.

The name "skipper" represents how the agent steers the repo through tumultuous waters using jj. It also harkens to jj's ability to "skip" unbookmarked changes in the git commit history.

How It Works

Repos use colocated mode (jj git init --colocate) so both .jj/ and .git/ exist. This preserves compatibility with tools that expect .git/ (Codex worktrees, VSCode, gh CLI). Agents use jj for all writes; git reads work naturally.

Guard Layer

• Claude Code: PreToolUse hook intercepts Bash commands and blocks git before execution, suggesting the jj equivalent.
• Codex: execpolicy rule with decision = "forbidden" blocks all git commands.
• Escape hatch: Prefix with :;git for git-only operations (submodule, lfs).

Knowledge Layer

• jj-guide skill: Loaded automatically for any VCS operation. Covers mental model, workflows, bookmark rules, revsets, filesets, and common pitfalls.
• git-to-jj reference: Complete command mapping from git to jj equivalents.

Automation Layer (Claude Code)

• WorktreeCreate hook: Bridges jj workspace add + .envrc for $GIT_DIR, so gh CLI works in secondary workspaces.
• /jj-workspace: Create an isolated workspace and bookmark for parallel agent work.
• /jj-commit-push-pr: Commit, push bookmark, and open a PR on GitHub.
• jj-doctor: Sub-agent for debugging lost commits, stale bookmarks, conflicts, and other VCS tangles.

Prerequisites

• jj, jq (required)
• direnv (recommended — enables automatic $GIT_DIR in worktrees; fallback: source .envrc)

Installation

Claude Code (plugin)

# From marketplace (when published):
/plugin marketplace add plasticbeachllc/jj-skipper

# Or local install for development:
/plugin install /path/to/jj-skipper/claude-code

Codex

git clone https://github.com/plasticbeachllc/jj-skipper.git
./jj-skipper/codex/install.sh

Warning: The Codex execpolicy rule blocks git commands globally across all sessions. For repos still using plain git, remove the rule: rm ~/.codex/rules/jj-skipper.rules

Per-project instructions

Add to your project's CLAUDE.md or AGENTS.md:

## Version Control

This project uses jj (Jujutsu) exclusively. The repo is colocated (.jj/ and .git/ both
exist). All VCS writes use jj. Git reads work naturally.

**Multi-agent model: one bookmark per agent/feature.**

Before doing any work, create a bookmark:
  jj new main -m "feat: description"
  jj bookmark create <feature-name> -r @

After committing, the content is at @- (parent). @ is always an empty working copy.

To push:
  jj git push -b <feature-name>

To sync after a PR merges on GitHub:
  jj git fetch
  jj bookmark set main -r main@origin

Claude Code handles workspace creation automatically via the WorktreeCreate hook.
If gh CLI doesn't work in a worktree, run `direnv allow` or `source .envrc`.

Use the jj-guide skill for full reference. Use /jj-commit-push-pr to ship code.
If VCS state gets tangled, invoke jj-doctor.

Repository Structure

jj-skipper/
├── shared/                          # Platform-agnostic content
│   ├── skills/
│   │   ├── jj-guide/              # Core jj knowledge (both platforms)
│   │   │   ├── SKILL.md
│   │   │   └── references/git-to-jj.md
│   │   ├── jj-commit-push-pr/     # Ship code skill
│   │   │   └── SKILL.md
│   │   └── jj-workspace/          # Workspace creation skill
│   │       └── SKILL.md
│
├── claude-code/                     # Claude Code adapter
│   ├── .claude-plugin/plugin.json
│   ├── hooks/hooks.json            # PreToolUse + Worktree hooks
│   ├── scripts/                    # Worktree bridge scripts
│   ├── skills/                     # Real directories (plugin cache compatible)
│   │   ├── jj-guide/
│   │   ├── jj-commit-push-pr/
│   │   └── jj-workspace/
│   └── agents/jj-doctor.md        # VCS debugger sub-agent
│
├── codex/                           # Codex adapter
│   ├── skills/                     # Symlinks → ../../shared/skills/*
│   │   ├── jj-guide
│   │   ├── jj-commit-push-pr
│   │   └── jj-workspace
│   ├── rules/jj-skipper.rules     # execpolicy guard
│   ├── agents/AGENTS.md
│   └── install.sh
│
├── LICENSE.md
├── README.md
└── CHANGELOG.md

Shared skills are the single source of truth. Claude Code uses real copies for plugin cache compatibility. Codex symlinks to shared skills (install.sh falls back to copy if needed). Claude Code scripts (guard, worktree hooks) are self-contained — no cross-directory references that break in the plugin cache.

Multi-Agent Parallel Workflows