jj-octo
v0.13.3
Published
A jj subcommand for GitHub that supports stacked pull requests and works in Claude Code cloud sessions
Readme
jj-octo
A jj subcommand for GitHub that supports stacked pull requests and works in Claude Code cloud sessions.
[!WARNING]
jj-octois in early development, and its commands may change. So far it is largely vibe coded.
Usage
jj gh --help documents every command, setting and environment variable, and jj gh <command> --help each command's flags.
Install
Each GitHub release has a standalone jj-octo for macOS on Apple silicon and Linux on x64 and arm64. Alternatively, run the npm package with Bun. Either way, jj must be on PATH.
With mise, add it to one repository's mise.toml:
[tools]
"github:kkom/jj-octo" = "X.Y.Z"Or to every repository:
mise use --global github:kkom/[email protected]Then run jj-octo init once in each checkout. It makes the checkout a jj repository colocated with git, makes GitHub's default branch trunk(), and sets the jj gh alias.
In Claude Code cloud sessions
A Claude Code cloud session runs in an Anthropic-hosted environment, or in your organization's self-hosted environment. Each needs its own setup. jj gh --help describes each setting and environment variable named below.
The session's GitHub proxy can append a "Generated by Claude Code" footer to each pull request body that it creates or edits. In a cloud session, jj gh submit leaves the footer out when it compares a pull request's body with its change's description, so it doesn't write the footer into the change. jj-octo.ignore-claude-code-footer overrides that.
In an Anthropic-hosted environment
There, the GitHub proxy carries all GitHub traffic, and rejects GraphQL requests. jj-octo uses GitHub's REST API, so it works there with its default settings, while gh pr and other tools that depend on GraphQL fail. REST can't mark a draft ready for review, so there jj gh publish and jj gh submit --publish use the proxy's own route for it, and GraphQL elsewhere.
In a self-hosted environment
A self-hosted runner started with --use-anthropic-git-proxy sends git through the Anthropic git proxy, which adds the GitHub credentials of the session's creator. The session then holds no GitHub token. There, have jj-octo use the same proxy:
jj config set --repo jj-octo.github-auth git-proxyDevelopment
bun install
bun run check # format, lint, types, tests and build
bun run fix # regenerated GraphQL types, then format and lint fixescodegen.ts types the GraphQL documents in src against GitHub's published schema, into src/clients/github/graphql/. The generated code is checked in, bun run check fails where it is out of date, and the bundle holds only each document's text.
To release, run bun run release:patch, release:minor or release:major in a pull request, which raises version in package.json. Once it is merged and the checks pass on main, the same workflow publishes that version to npm, and as a GitHub release with the executables.
The workflow publishes the version from the last commit of the push. So merge a release pull request with nothing above it: in a stack, run jj gh merge -r on the release change, then merge the pull requests above it. Until the release is merged, the CI check fails on each pull request above it. main requires CI to pass, so GitHub doesn't merge those pull requests with the release.
