JayJay User Guide

Open a Repository #

• Open a repository with Cmd+O, the app menu, the Dock recent-repositories menu, or the CLI launcher: jayjay /path/to/repo.
• Open the current terminal directory with jayjay . after installing the bundled CLI launcher.
• The Repository List separates persistent Pinned repositories from shell-local Recent Repositories. Use the pin button to keep a repository in the list; clearing Recent does not remove pins. Pins are shared between the SwiftUI and GPUI shells.
• Click the repository title in an open window to switch repositories. The menu activates an already-open repository without duplicating its window, opens a closed pinned repository in a new window, or returns to the full Repository List.
• Closing the last repository window returns to the Repository List automatically.
• If you open a folder that is not a jj repository, JayJay shows an onboarding view with a jj git init path.
• JayJay watches the repository and working tree, then refreshes when jj operations or file edits change the repo.

Main Window #

• The left graph shows jj changes as a DAG with lanes for forks, merges, bookmarks, tags, conflicts, divergent changes, and working-copy state. Each row shows bookmark and tag chips, the author avatar, a relative timestamp, and the shortest unique change-id prefix highlighted.
• The detail header shows the selected change, description, author, status, bookmarks, PR state, and available actions. The change-id and commit-id are shown with their shortest unique prefix in bold.
• The file column lists changed files in flat or tree form and shows review status, conflicts, renames, and file-level actions.
• The diff pane shows the selected file with unified or side-by-side layout, syntax highlighting, word-level changes, collapsed context, and rich previews for supported formats.
• The status bar surfaces repository state, selected bookmark PR links/checks, and useful workspace context.

Navigate History #

• Click a change to inspect it.
• Use j/k, arrow keys, or Ctrl+N/Ctrl+P to move through the graph and file lists.
• Use Load More to fetch older history without expanding the whole repo at once.
• Use revset chips for common views: all changes, mine, bookmarks, trunk, conflicts, and heads. Type a custom revset — including aliases from your jj config — when the presets are too broad.
• Use the context menu to reveal related changes, open file history, start comparisons, or run change operations.
• Drag a change row to preview and confirm a rebase from the graph.
• Drag a bookmark chip onto another change to move the bookmark there, or drag the working-copy @ chip to move the working copy (jj edit). Dropping on the same change is a no-op; backward moves are allowed and undoable from the operation log. Press Return to confirm or Esc to cancel mid-drag.
• Divergent changes are marked in the graph so they are visible before you pick a resolution.

Review Diffs #

• Review your working copy like a pull request: step through the changed files and press Space to tick each one off with its review checkbox. Hide reviewed files to focus on what's left.
• Toggle between unified and side-by-side diffs, and browse changed files as a flat list or a tree.
• Use Cmd+F to search within the current diff.
• Review state is local to your machine and survives app restarts. Marks invalidate when a file's old or new content changes, but survive rebases that keep the same bytes.
• Image files render as images where possible; SVG files can be viewed as source or rendered output.
• Supported rich previews include Markdown, SVG, HTML, notebooks, CSV/TSV tables, SARIF reports, and binary property lists. Text-backed files stay raw by default so diff review still works; click the rich preview icon to switch to the rendered view. Working-copy HTML files render inline in a sandboxed preview (scripts don't run); an external-open icon next to it still launches the file in the default app, so linked CSS and images work normally there too. Binary property lists open as XML with a banner, while plain XML property lists stay raw.
• Renames, collapsed context, and ignore-whitespace behavior are reflected in the diff view. In either diff layout, use Show 10 or Show all on an unmodified-lines row to reveal nearby context without leaving the file. Copying diff text excludes gutter line numbers.

Review Notes #

• Leave line-anchored feedback while reviewing the working copy: right-click a changed line's gutter and choose Add Review Note. The editor shows a short diff excerpt around the anchored line; save with Cmd+Return.
• Saved notes render inline in the unified diff as an orange-outlined bubble directly below the annotated line, with an orange dot in the gutter's note column. Click the dot — or right-click the line again — to Edit, Resolve, or Delete the note.
• Files with active notes show an orange note count in the file list, and the header note badge filters the list to noted files.
• Notes anchor to the line's content. If the file changes underneath, the note turns stale and moves to a banner above the diff, together with orphaned notes whose anchor disappeared. Resolving a note keeps a dimmed gutter dot as a record.
• Notes are local to your machine, shared across app windows and the jayjay CLI, and survive rebases of the change. They render in unified view; side-by-side shows the file's note count with a one-click Show in Unified.
• Built for agent loops: review an AI agent's changes (or your own), leave notes on the lines that need work, then have the agent read them with jayjay review notes --repo . --format json and resolve each with jayjay review resolve-note <id> --repo . once addressed.
• Agents can annotate too: jayjay review add-note --repo . --file <path> --line <n> -m "note" anchors a note to a changed line, and it appears in the diff view like any other note — a cleaner channel for review commentary than source-code comments.

Compare Changes #

• Shift-click two graph revisions to compare them. When both have bookmarks, JayJay uses bookmark names in the compare banner.
• Use the compare direction control to switch the diff direction.
• Bookmark diff is useful for PR-style review: compare the main bookmark or fork point against a feature bookmark.
• Interdiff mode uses the same unified and side-by-side renderers, but hides working-copy review controls because the comparison is not a file-review session.
• Diff divergent changes: right-click a change marked divergent and choose Compare Divergent Versions to interdiff the two commits that share its change-id — so you can see which one is safer to abandon.

Edit Diffs & Split Work #

• Diff edit mode lets you select files, hunks, or line ranges from the working copy or another mutable change.
• Each file card shows its +/− line counts and collapses in place. Large diffs start collapsed so the file list stays scannable, and Expand All / Collapse All (Cmd+Option+E / Cmd+Option+C) toggle every file at once.
• The whole view is keyboard-driven: j / k or ↑ / ↓ move focus between file cards, ← / → collapse or expand the focused card, Return toggles it, and Space selects its changed lines.
• Selected edits can become a child change, a parallel change, or be moved into the working copy. Working-copy edits can be discarded at selected line granularity.
• Batch split can use reviewed files as the selection model. Split supports a parallel option when the selected edits should become a sibling instead of a child.
• Topology-aware destinations preserve the intended jj graph shape when moving edits.

Change Operations #

• Edit a change description directly, or use the commit box to describe and commit the working copy.
• Generate commit messages with the AI provider chain: Codex CLI, Claude CLI, then Apple Intelligence when available.
• Create new changes, edit an existing change, squash into a parent, abandon, duplicate, merge, absorb into ancestors, and back out changes.
• Restore, ignore, or untrack working-copy files from file actions where applicable, and move selected files from any change into the working copy.
• Use Undo to inspect the jj operation log and roll back recent operations. JayJay shows lightweight toasts for completed actions and keeps the rest of the window usable when possible.

Bookmarks, Git & Pull Requests #

• Use the Bookmark Manager (Cmd+Shift+B) to inspect bookmark stats, filter bookmarks, reveal their changes, copy names, diff them, and resolve conflicts.
• Each bookmark shows its remote sync state per tracked remote: a green check when it matches the remote, or ahead / behind / diverged when the local bookmark and the remote ref point at different commits — hover to see where the remote sits. (The synthetic colocated @git remote is omitted as noise.)
• Deleted bookmarks are hidden by default; toggle Show deleted to see them, then use Forget (clean up) to remove a leftover bookmark — including its colocated @git branch.
• Use bookmark actions to create, rename, track, move forward, delete, and push bookmarks, or drag a bookmark chip in the DAG to move it onto any change.
• After moving a remote-tracking bookmark by drag, a one-click Push affordance appears in the sidebar so you can publish the move (it never pushes automatically).
• Push and fetch Git remotes from JayJay; push can auto-track a bookmark when needed.
• Right-click a bookmark in the DAG or Bookmark Manager to open a GitHub, GitLab, or Codeberg pull/merge request. If a matching PR or MR already exists, JayJay opens it; otherwise it opens the provider's compose page.
• The status bar can show the selected bookmark's PR/MR link and CI check status via the GitHub gh CLI, the GitLab REST API, or Codeberg's Forgejo API. Private GitLab projects use a GITLAB_TOKEN environment variable.
• Remote repository URLs can be opened in the browser, including git@... URLs converted to HTTPS.

Workspaces #

• Create a new jj workspace from the Repository menu (New Workspace…) or the command palette: pick a destination folder and name, and JayJay runs jj workspace add so you get a second working copy backed by the same repository.
• Switch between workspaces from the command palette — each one opens in its own window pointed at that working copy.
• The sidebar lists the repository's workspaces and marks the current one; forget a stale workspace from there once its working copy is gone.

Stacked Pull Requests #

Turn a linear stack of changes into one PR (GitHub) or MR (GitLab) per change, each targeting the one below it.

• Right-click the tip change in the DAG and choose Create / Update Stacked PRs. Whatever change you click becomes the top of the stack; everything from just above trunk() up to it is included.
• The preview shows one row per change — bottom-first targeting your default branch (main), each higher one targeting the bookmark below it. Each row's branch name is editable (pencil → edit → Done); when Apple Intelligence is available, Generate bookmarks suggests names from the commit messages. Existing bookmarks are reused unchanged.
• Submit pushes every bookmark at once, then creates or updates the PRs/MRs with their dependent bases. Done opens the top PR for a linked GitHub stack, always opens the highest submitted GitLab MR, and opens each submitted PR if GitHub native linking falls back. Re-running is idempotent — bookmarks anchor on the change-id, so it updates the same PRs/MRs and stack instead of duplicating.
• GitHub native stacks: JayJay uses the standard gh api command; no extension is required. If GitHub Stacked PRs is not enabled for the repository or rejects the chain, the dependent PRs remain usable and the result explains that native linking was skipped.
• GitLab stacks: GitLab detects the dependent MR chain automatically and shows a stack navigator in each MR; no separate linking request is required.
• Merging: for ordinary GitHub PR chains and GitLab MRs, merge bottom-up (the one targeting main first). After each merge, run jj git fetch and Create / Update Stacked PRs again to retarget the remaining layers. If GitHub has linked the PRs into a native stack, use GitHub's stack controls; merging a PR also merges every unmerged layer below it, then GitHub rebases and retargets the remainder.
• JayJay requires an authenticated gh CLI (GitHub) or glab CLI (GitLab). The forge is taken from the repo's origin remote; Codeberg is not yet supported.

Conflict Resolution #

• Conflicted changes and files are marked in the graph and file list.
• The conflict bar offers one-click Use Ours and Use Theirs actions when the file can be resolved that way.
• Resolve in Editor opens jj resolve --tool with your configured merge editor, such as VS Code or Zed.
• JayJay refreshes after resolution so the graph and file list reflect the new repo state.

Inspection Tools #

• File Annotate shows blame information with a syntax-highlighted gutter and lets you navigate to the responsible change.
• File History lists revisions that modified the selected file.
• Change Evolution shows prior versions of a rewritten change with operation labels such as snapshot, describe, rebase, squash, and split. Entries can be compared against the current version.
• Right-click an evolution entry to copy its commit id or a jj restore recovery command.

Command Palette #

• Open the command palette with Cmd+Shift+P and search built-in actions by name.
• Type help <topic>, such as help split or help stacked pr, to find local feature help from the bundled guide index.
• Type jj <args> or ! <args> to run raw jj commands inline. Output appears inside the palette and can be copied.
• Command history is available during the session, so repeated jj commands are easy to recall.

Tools & Settings #

• Configure appearance, diff behavior, editor, terminal, jj settings, and app metadata in Settings. JayJay checks for jj availability and detects supported AI providers.
• Anonymous build and OS statistics are enabled by default and can be disabled in Settings. No repository, file, or command data is sent, and rotating identifiers cannot link an installation across months.
• Pick a font family and adjust zoom with Cmd++, Cmd+-, and Cmd+0.
• Open files in external editors such as VS Code, VSCodium, Cursor, Zed, Xcode, or Vim. Cursor launches with --classic so it opens in editor mode rather than its agent window.
• Open terminals such as Terminal.app, iTerm2, or Ghostty at the repository path.
• Commit avatars can come from GitHub or Gravatar. Multi-window mode keeps one window per repository and deduplicates URL-scheme launches.
• Choose Help > Send Feedback to email us. The Help menu also opens the bundled JayJay Help Book, the full web user guide, jj documentation, and issue reporting.

GPUI Shell Alpha #

• Build and run it from source with just gpui or just gpui /path/to/repo.
• GPUI's current parity target is Linux. Its macOS build is for development and is not expected to duplicate every SwiftUI integration; the released macOS app remains SwiftUI.
• Current GPUI coverage includes graph browsing, diffs, file history, annotate, evolog, file review, review notes, bookmark manager, filesystem refresh, command palette, raw jj commands, searchable help topics that open this guide, native appearance tracking, SVG previews, rendered Markdown previews, HTML external open, diff text selection/copy, file multi-select in the file column, workspace windows, and a Linux jayjay command-line install in Settings > Tools.
• Early write coverage includes editing descriptions, saving the working-copy description with the Describe button, committing from the commit box, AI-generated commit messages via the codex or claude CLIs, splitting or committing selected files into a new change, batch file actions on the selection (restore to parent, delete from disk, ignore & untrack, mark reviewed), creating and forgetting workspaces, abandoning selected working-copy lines from the diff gutter, and a dedicated multi-file Diff Edit view with per-file cards, per-file line stats and collapse/expand with auto-collapse for large diffs, keep-only-selected Done, move to working copy, new child, and new parallel destinations.
• Remaining GPUI work is tracked in the roadmap.

Keyboard Shortcuts #