gojo is a fullscreen TUI for jj (Jujutsu VCS), written in Go with Bubble Tea (Elm-architecture TUI framework) and Lip Gloss (styling). Diff syntax highlighting uses chroma.
main.go — entry point: tea.NewProgram(ui.NewModel()); Model.View
declaratively enables alt screen, focus reporting,
and all-motion mouse events; main also enables mode 2031
(CSI ? 2031 h) so dark/light scheme changes are reported
internal/
jj/
jj.go — Runner: runs jj CLI commands, parses log/status output;
conflict ops: Conflicts (resolve --list),
FetchConflictSides (throwaway probe merge tool steals
$left/$base/$right, leaves $output empty so jj aborts
— the conflict stays intact), Resolve (tool copies the
gojo-composed content into $output)
config.go — Config struct, repo-root discovery (ErrNoRepo sentinel
when no .jj dir; Config still carries JJPath so the
boot prompt can init), minimal TOML loader (incl. the
[keymap] / [tools.gojo.keymap] section → Config.Keymap,
and the top-level `theme` key → Config.Theme),
ConfigDir/ConfigPath/ThemesDir helpers, SaveTheme
(upserts `theme = "<id>"` into gojo.toml for the picker)
ai.go — AIDescribe: provider dispatch + OpenAI-compatible chat-completions client (net/http)
ai_codex.go — Codex CLI backend: saved login, ephemeral read-only exec,
prompt/diff on stdin, final-message file, 90s timeout
ui/
model.go — Bubble Tea Model: state, Update (msgs + keys), View, commands
keys.go — configurable keybindings: key contexts/actions, default
table, KeyMap (defaults + [keymap] overrides), resolve/
hk/hkN hint helpers, keyMsg synthesis for menu clicks
render.go — seg/renderSegs/clip/bgRow + the lipgloss style cache
(probe-once per style combo; bounded RWMutex map —
themes introduce new color combos at runtime),
blankRow cache, ASCII fast path for segTextWidth,
expandTabs (raw control chars never hit the terminal:
tabs render as tabStop=4 spaces everywhere)
styles.go — color palette vars (defaults = the compiled-in "gojo"
theme; rewritten at boot by applyTheme), spinner frames
themes.go — Theme + paletteDef (every color slot), resolve()
derivation recipe (tints mix toward bg, dark_* dim
accents, accent fallback chains), applyTheme
themes_builtin.go — compiled-in "gojo"/"terminal" themes, theme file
discovery (exe-relative share/gojo/themes →
/usr/{local,}/share → ./themes for dev →
~/.config/gojo/themes; user dir shadows by id),
minimal TOML theme parser
themepicker.go — theme picker view (key T): live preview on move,
⏎ applies + saves via jj.SaveTheme, esc restores
darkmode.go — follows OS dark/light scheme changes live: handles the
mode-2031 DSR (CSI ? 997 ; 1|2 n) parsed by
Ultraviolet, updates explicit UI background state,
re-applies the active theme, and
re-highlights chroma-cached content (open diff rows,
file-view blame)
logview.go — commit list rendering + variable-height scroll windowing
diff.go — git unified-diff parser + chroma highlighting → diffRow
(lexer + token-fg caches; LCS word diff with prefix/
suffix trim, flat matrix, cell-count budget)
diffpanel.go — diff viewer rendering (gutter, status, file/hunk/line rows);
current file header sticks below the title while scrolling,
with shared overlay geometry for rendering and mouse hits
merge3.go — 3-way merge on line slices: LCS line diff (prefix/suffix
trim + cell budget) → context/auto/conflict blocks;
composeResolved emits the file from per-block choices
conflictview.go — side-by-side conflict resolution view (key `c`):
left pane = side 1, right = side 2, per-hunk pick
l/r/b/u (or click the pane), [ ] file tabs, ⏎ applies
via jj resolve; rows cached per file, no wrapping
split.go — split mode + intermediate-file computation + jj split tool
helpview.go — keybinding reference + scroll
go.mod / go.sum — module `gojo`, deps: bubbletea, lipgloss, chroma, x/ansi
themes/*.toml — built-in color themes, one file per theme (~50:
[dark]/[light] palette sections + name/syntax keys).
Installed to <prefix>/share/gojo/themes by the flake
and by release packages; users override/add in
~/.config/gojo/themes (file-stem id shadows builtin).
flake.nix — nix flake: devShell (go, gopls, jujutsu),
buildGoModule package, `nix run .#bump` —
version bump app (major|minor|patch|X.Y.Z) wrapping
scripts/bump.go from the repo root
scripts/bump.go — version bumper: writes VERSION, refreshes the
flake vendorHash via `nix build .#default`
.goreleaser.yaml — release pipeline: tarballs, distro packages (nfpm:
archlinux pacman pkg + deb + rpm; one entry per
format so jujutsu is a hard dep on Arch, recommended
on deb, weak recommend on rpm), Windows ZIPs, and
Homebrew/Scoop manifest commit-back. Validates
VERSION == tag in a before hook.
VERSION — single source of truth for the version (flake + goreleaser read it)
.envrc — direnv: `use flake`
- Follow Semantic Versioning.
VERSIONremains the release version source of truth; feature work updates changelogs but does not bumpVERSION. - Every user-facing feature must add a concise entry under
## [Unreleased]in bothCHANGELOG.mdand../gojo-www/CHANGELOG.mdin the same change. - Use Keep a Changelog categories (
Added,Changed,Deprecated,Removed,Fixed,Security). Describe user-visible behavior, not implementation details or commit history. - Keep the two Unreleased sections synchronized. During a release, move those entries into the new version/date section in both files before tagging.
- The canonical editor schemas live in the website repository:
../gojo-www/public/schemas/gojo.jsonand../gojo-www/public/schemas/theme.json, served athttps://gojo.rocks/schemas/gojo.jsonand/schemas/theme.json. - Whenever config keys, aliases, types, defaults, keybinding contexts/actions,
theme metadata, or palette slots change, update the corresponding schema and
affected documentation in the same change. Source owners are
internal/jj/config.go,internal/jj/ai*.go,internal/ui/keys.go,internal/ui/themes.go, andinternal/ui/themes_builtin.go. - Model
[keymap]dotted keys as nested context/action objects in JSON Schema; document the unquotedlog.down = "j,down"syntax supported by gojo's parser. - Validate representative config and shipped theme TOML with Taplo after schema
changes, including rejected unknown keys and invalid values. Build the website
with
npm run buildfrom../gojo-wwwto verify the public assets are included.
- Go 1.24+ (build)
- gopls, go-tools (tooling)
- jj v0.44+ (jujutsu VCS, runtime dependency — gojo shells out to it; 0.44
stabilized
jj tag+ tag fetch/push, which gojo relies on) nix developdrops you into the shell; direnv auto-loads it.
nixpkgs has two packages named jj:
nixpkgs#jj= tidwall/jj — a JSON stream editor (NOT what we want)nixpkgs#jujutsu= jj-vcs/jj — the VCS (what we want)
The flake uses jujutsu. Always ensure the correct jj is first in PATH.
go run . # dev
go build -o gojo . && ./gojo
go test ./... # unit + integration tests (TestSmoke needs a jj repo)The TUI uses the alternate screen buffer. Tests drive the Model headlessly
by feeding messages to Update and asserting on View() (see
internal/ui/model_test.go) — no PTY required.
Runner.Log uses jj's template language. Key syntax:
- String concatenation:
++ - String literals:
"text"; newlines"\n"; marker byte"\x01" - Field access:
change_id.short(8),commit_id.short(8),author.email() - Conditionals:
if(condition, "yes", "no") - Joins:
bookmarks.join(",") - Date:
author.timestamp().local().format("%Y-%m-%d %H:%M")
A literal \x01 marker byte precedes both the data line and the body line, so
the graph prefix (everything before the marker) can be separated from the
fields. Fields are |-separated (13 total):
0: change_id.short(8) | 1: change_id.shortest() | 2: commit_id.short(8) |
3: commit_id.shortest() | 4: author.email() | 5: date | 6: working_copy (Y/N) |
7: immutable (Y/N) | 8: bookmarks (comma-separated) | 9: tags (comma-separated) |
10: conflict (Y/N) | 11: workspaces (comma-separated names) | 12: divergent (Y/N)
Lines without a marker byte are graph edge lines, attached to the preceding
commit during parsing (parseLog).
- Model (
ui.Model) holds all state: window size, log entries + cursor + offset, status, diff panel, help scroll, bookmark/git/remote modes, autocomplete, AI-loading set, spinner frame. - Update handles
tea.Msgs. UI-blocking work (running jj, HTTP) happens intea.Cmds that return result messages (refreshMsg,diffLoadedMsg,actionDoneMsg,aiDoneMsg,listLoadedMsg, …). Keyboard input is atea.KeyMsgdispatched per mode. Mouse wheel events are coalesced: the first step of a burst applies immediately, further steps accumulate and flush as one batch per 16 mswheelTickMsg— macOS trackpads emit wheel events far faster than the terminal can repaint during momentum scrolling, and per-event handling made the message queue back up (the app kept repainting stale scroll states after the fingers lifted). - View composes the screen as a slice of pre-styled, width-clipped lines (top bar, content, optional autocomplete line, status bar, help bar) joined to exactly the terminal height.
OpenTUI's <box>/<text>/StyledText are replaced by seg (a styled run)
plus renderSegs/plainRow/bgRow. Each segment carries its own background
so a filled row stays continuous across ANSI resets. clip truncates to width
with x/ansi (preserving escape codes).
d (jj describe) uses tea.ExecProcess to suspend the TUI, run
jj describe -r <rev> with the terminal attached for $EDITOR, then resume.
| View | Key | Description |
|---|---|---|
| Log | default | Commit list, 2 lines + graph edges per commit. Variable-height scroll windowing in logWindow. |
| Diff | enter |
Status summary + parsed/highlighted diff. Cursor moves (j/k, g/G) center the cursor in the viewport (clamped at the page ends); wheel/pgup·pgdn scroll only via diffScrollY without touching the chunk cursor. |
| Conflicts | c (log/diff) |
Side-by-side 3-way conflict resolution; per-hunk l/r/b/u or pane click, per-file ⏎ apply via jj resolve with a probe/apply merge tool. |
| Themes | T (log) |
Theme picker over all installed + user themes; live preview on move, ⏎ applies and upserts theme = "<id>" into ~/.config/gojo/gojo.toml, esc restores the previous theme. |
| Help | ? |
Keybinding reference, scrolled via helpScrollY. |
- Top bar —
◉ gojo+ repo path (2 lines, dark-purple bg) - Content area — log / diff / help (
height - 4 - autocomplete) - Autocomplete suggestions — only in bookmark input mode (1 line, optional)
- Status bar — mode menus, errors, messages, or file count (1 line)
- Help bar — global keybinding hints (1 line)
All keys route through KeyMap (keys.go): every handler resolves
tea.KeyMsg.String() through a context (global, log, diff, split,
conflict, input, menu, bookmark, tag, git, remote, …) to a named
action, then switches on the action. The default table in keys.go declares
each context's actions with their default keys.
Users override in ~/.config/gojo/gojo.toml (or [tools.gojo.keymap] in jj's
config.toml):
[keymap]
log.down = "j,down" # comma-separated alternates; replaces the whole binding
global.quit = "Q"
diff.absorb = "" # empty = unbindKey names follow tea.KeyMsg.String() ("enter", "esc", "tab", "up", "pgup",
"ctrl+u", single runes…); normalizeKeyName accepts friendly spellings
("space", "escape", "pgdn"…). When two actions in a context are bound to the
same key, the one declared first in the default table wins. Overrides apply at
boot (bootMsg → newKeyMap(cfg.Keymap)); the boot init/error screens read the
user keymap too since config loads before repo discovery.
Every UI hint (help bar, status-bar menus, view title bars, help view,
context menus) renders from the keymap via m.hk / m.hkN / m.hkRaw /
m.hkLast helpers, so rebinding is reflected everywhere. Synthetic dispatch
(context-menu clicks, shortcut-bar clicks → keyMsgFromName) also resolves
against the active bindings.
All jj operations go through Runner.run(args...), which executes jj in the
repo dir via os/exec, capturing stdout and surfacing stderr on error.
Operations: Log, Status, Diff (--git), DiffSummary, FileShow, Describe, New,
Edit, Abandon, Absorb, Undo, Redo, Bookmark{Create,Delete,Forget,List,Move,Rename,Set,
Track,Untrack}, Tag{List,Set,Delete}, GitFetch, GitPush, GitPushTags,
Remote{Add,List,Remove,Rename,SetURL}, AIDescribe. GitInitDir (not a Runner
method — no repo exists yet) wraps jj git init [--colocate] for the boot
prompt: outside any repo gojo asks "initialize here?" then "colocate with
git?", inits, and re-runs the boot.
Colors are themeable. styles.go initializes the palette vars to the
"gojo" default; at boot applyTheme rewrites them from the selected theme.
The picker (T in the log view) lists all themes, live-previews the one
under the cursor, and persists the choice with ⏎ (jj.SaveTheme upserts
theme = "<id>" into ~/.config/gojo/gojo.toml); esc restores the previous
theme. Picking terminal makes gojo follow the terminal's own ANSI scheme.
Theme sources (later shadows earlier by id):
- compiled-in:
gojo(default),terminal <exe>/themes(release archives, including Scoop)<exe>/../share/gojo/themes(nix store / /usr installs)/usr/local/share/gojo/themes,/usr/share/gojo/themes./themes(repo root, forgo run .dev)~/.config/gojo/themes(user custom; tagged "user" in the picker)
File format (one theme per file, id = file name stem, name = display
title, optional syntax/syntax_light set the chroma diff-highlighting
style). A theme lists [dark] and/or [light] sections with core slots
(background, element, text, text_muted, purple, blue, green, red, yellow,
cyan, orange, pink, teal, …); every omitted slot is derived deterministically
by resolve() (tints = accent mixed onto background; dark_* = dimmed
accent; magenta → purple, pink → magenta, teal → cyan chains):
name = "Dracula"
syntax = "dracula" # optional
[dark]
background = "#282a36"
element = "#44475a"
text = "#f8f8f2"
text_muted = "#6272a4"
purple = "#bd93f9"
blue = "#8be9fd"
green = "#50fa7b"
red = "#ff5555"
yellow = "#f1fa8c"
cyan = "#8be9fd"
orange = "#ffb86c"
pink = "#ff79c6"Values are "#rrggbb" hex or ANSI indices ("1"…"15" — the terminal
theme uses these to follow the terminal scheme). Empty/nil slots mean
"terminal default" once derivation is exhausted (mixing ANSI values yields
nil). See themes/ for the ~50 shipped themes.
| Name | Hex (dark) | Usage |
|---|---|---|
| purple | #9d7cd8 | Change IDs, highlights |
| element | #1c1c26 | Selection / top-bar background |
| blue | #5c9cf5 | Author names |
| green | #7fd88f | Bookmarks, additions |
| red | #e06c75 | Errors, deletions |
| yellow | #f5a742 | Working copy, cursor |
| magenta | #c487f0 | Change ID prefix, AI spinner |
| cyan | #56b6c2 | Bookmark mode, hunk headers |
| textMuted ("gray") | #787886 | Dates, commit IDs, help text |
| border ("darkGray") | #343440 | Separators |
| panel ("darkerGray") | #14141c | Status bar background |
| text ("white") | #e2e2ec | Subjects |
| orange / darkOrange | #f5a742 / #b08030 | Git mode |
| pink / darkPink | #ff7eb6 / #b85a90 | Remote mode |
| teal / darkTeal | #4db6ac / #2e7d72 | Tag mode |