hunk

A cross-platform Git diff viewer and Codex orchestrator built with gpui + gpui-component.

License

Hunk is licensed under the GNU General Public License v3.0 or later. See LICENSE.

Why?

Nobody writes code anymore, people just review code. So we need the best diff viewer possible so that vibe engineers can review code and tell AI what to fix. Hunk is also has full codex integration so you can use Codex inside of Hunk instead of codex-cli or any other desktop app.

What it includes

• Uses a native Git backend built on gix with narrow git2 fallbacks for unsupported write flows
• Managed Git worktrees with per-worktree branch publishing
• File tree for changed files
• Side-by-side diff viewer with per-line styling and line numbers
• Review compare mode for base branch <-> workspace target and custom branch/worktree pairs
• AI drafts and threads scoped to the selected project checkout or worktree
• Resizable split panes (tree + diff)
• Light/Dark mode toggle
• Refresh action
• anyhow-based error handling
• tracing + tracing-subscriber logging

Workspace Layout

• crates/hunk-domain: config/state/db/diff/markdown domain logic
• crates/hunk-git: Git backend for repo discovery, diffing, branches, commits, push, and sync
• crates/hunk-text: rope-backed text model, positions/ranges, transactions, and undo/redo primitives
• crates/hunk-language: Tree-sitter language registry, syntax highlighting, preview highlighting, folds, and language-intelligence seams
• crates/hunk-editor: headless editor state, selections, display rows, folds, overlays, and editor commands
• crates/hunk-desktop: GPUI desktop app binary
• crates/hunk-codex: Codex Websocket Server handling logic

Requirements

• macOS
• Xcode + command line tools
• Metal toolchain for GPUI shader compilation

Run Dev Locally

Preferred local entry points:

just start-mac

just start-linux

just start-windows

Those helpers resolve CARGO_TARGET_DIR correctly, apply the macOS SDK wrapper when needed, and stage the bundled Windows Codex runtime automatically.

If you want the raw macOS cargo command, use:

CARGO_TARGET_DIR="$(./scripts/resolve_cargo_target_dir.sh)" \
  ./scripts/run_with_macos_sdk_env.sh cargo run -p hunk-desktop

Launch from anywhere, then use File > Open Project... (or Cmd/Ctrl+Shift+O) to choose a Git repository.

The app still launches from Terminal in local dev, so macOS may present it like a terminal-launched app.

Worktrees

Hunk treats the primary checkout and each linked Git worktree as separate workspace targets.

• Create and switch worktrees from the Git tab.
• Managed worktrees live under ~/.hunkdiff/worktrees/<repo-key>/worktree-N.
• The Files and Git tabs follow the currently active workspace target.
• The Review tab defaults to comparing the active workspace target against the repo base branch, but you can also compare custom branch/worktree pairs.
• The AI tab can start a new thread in the primary checkout with Cmd/Ctrl+N or in a worktree-targeted draft with Cmd/Ctrl+Shift+N.

Validate Workspace

On macOS:

CARGO_TARGET_DIR="$(./scripts/resolve_cargo_target_dir.sh)" \
  ./scripts/run_with_macos_sdk_env.sh cargo build --workspace
CARGO_TARGET_DIR="$(./scripts/resolve_cargo_target_dir.sh)" \
  ./scripts/run_with_macos_sdk_env.sh cargo test --workspace
CARGO_TARGET_DIR="$(./scripts/resolve_cargo_target_dir.sh)" \
  ./scripts/run_with_macos_sdk_env.sh cargo clippy --workspace --all-targets -- -D warnings

On Linux and Windows, run the same Cargo commands with CARGO_TARGET_DIR resolved through scripts/resolve_cargo_target_dir.sh or the just recipes so builds land in target-shared.

Example:

CARGO_TARGET_DIR="$(./scripts/resolve_cargo_target_dir.sh)" cargo test --workspace

For Production builds

cargo install cargo-packager
just bundle
open "$(./scripts/resolve_cargo_target_dir.sh)/packager/Hunk.app"

Cross-platform binary build helpers:

./scripts/build_linux.sh
./scripts/build_windows.sh

Optional flags:

• --target <triple> to override the default target triple (must match the script platform).
• --debug to build debug artifacts.
• --no-stage-runtime to skip copying the bundled Codex runtime into the target output tree.

Release packaging helpers:

./scripts/package_macos_release.sh
./scripts/package_linux_release.sh
pwsh ./scripts/package_windows_release.ps1

These produce:

• macOS ARM64: Hunk-<version>-macos-arm64.dmg, signed/notarized when Apple secrets are configured
• Linux x86_64: Hunk-<version>-linux-x86_64.AppImage, fallback Hunk-<version>-linux-x86_64.tar.gz, hunk-desktop_<version>-1_amd64.deb, and hunk-desktop-<rpm-version>-1.x86_64.rpm
• Windows x86_64: Hunk-<version>-windows-x86_64.msi

Linux release packaging is custom and does not use cargo packager. On Ubuntu hosts you can either enter nix develop to get the packaging toolchain from the flake, or install host deps with just install-linux-packaging-deps-ubuntu, then use:

just package-linux-release
just package-linux-deb-release
just package-linux-rpm-release
just smoke-test-linux-deb
just smoke-test-linux-rpm

The Debian smoke test installs the package in an Ubuntu container. The RPM smoke test installs it in a Fedora container.

Prepare Bundled Codex Runtime

Hunk embeds a native codex runtime and launches app-server mode with: codex app-server --listen ws://127.0.0.1:<port>.

Expected embedded runtime paths:

• assets/codex-runtime/macos/codex
• assets/codex-runtime/linux/codex
• assets/codex-runtime/windows/codex.cmd
• assets/codex-runtime/windows/codex.exe

Runtime layout details also live in assets/codex-runtime/README.md.

Download the pinned Codex release binary

The pinned Codex baseline is tracked in docs/AI_CODEX_SPEC.md.

./scripts/download_codex_runtime_unix.sh macos

Platform-specific download helpers:

• macOS ARM64: ./scripts/download_codex_runtime_unix.sh macos
• Linux x86_64: ./scripts/download_codex_runtime_unix.sh linux
• Windows x86_64: pwsh ./scripts/download_codex_runtime_windows.ps1

The Windows helper stages both assets/codex-runtime/windows/codex.exe and the bundled launcher assets/codex-runtime/windows/codex.cmd.

These pull the pinned release assets directly from the Codex GitHub release for the tag in crates/hunk-desktop/Cargo.toml:

• macOS ARM64: codex-aarch64-apple-darwin.tar.gz
• Linux x86_64: codex-x86_64-unknown-linux-musl.tar.gz
• Windows x86_64: codex-x86_64-pc-windows-msvc.exe.zip

If you already have a local native binary you want to use for macOS instead, you can still override the source path: ./scripts/install_codex_runtime_macos.sh /absolute/path/to/codex

Validate + stage + bundle (macOS local workflow)

Download and stage the pinned macOS runtime:

./scripts/install_codex_runtime_macos.sh
./scripts/validate_codex_runtime_bundle.sh --strict --platform macos
./scripts/stage_codex_runtime_macos.sh
CARGO_TARGET_DIR="$(./scripts/resolve_cargo_target_dir.sh)" \
  ./scripts/run_with_macos_sdk_env.sh cargo test -p hunk-codex --test real_runtime_smoke -- --ignored
just bundle

GitHub Actions Release Flow

• .github/workflows/pr-build.yml stays as the main PR CI workflow.
• .github/workflows/release.yml builds DMG/MSI/AppImage/DEB/RPM artifacts and publishes them to a GitHub Release when you push a v* tag.

The release workflows no longer bundle the old Helix runtime. The editor now uses the curated Tree-sitter language set compiled into hunk-language.

Syntax Highlighting

The Files editor, file preview, and markdown fenced-code highlighting now use the shared Tree-sitter language registry in crates/hunk-language.

Built-in languages/config formats:

• Rust
• JavaScript
• TypeScript
• TSX
• Bash / shell
• Python
• PowerShell
• JSON
• YAML
• Go
• HTML
• CSS
• TOML
• Java
• Kotlin
• C
• C++
• C#
• SQL
• Markdown
• Dockerfile
• Nix
• Terraform / HCL
• Swift

Apple signing/notarization secrets used by the workflows:

• APPLE_CERTIFICATE_P12_BASE64
• APPLE_CERTIFICATE_PASSWORD
• APPLE_SIGNING_IDENTITY
• APPLE_NOTARY_API_KEY_BASE64
• APPLE_NOTARY_KEY_ID
• APPLE_NOTARY_ISSUER

Windows signing is not configured in this repo yet. The current release workflow produces an unsigned MSI until you add a paid Windows signing solution.

Large Diff Stress Fixture

Generate a synthetic Git repository with a very large working-copy diff:

./scripts/create_large_diff_repo.sh --lines 25000 --files 1 --force

The script prints the generated repo path and total diff size. Open that folder in Hunk to stress scrolling/render performance and watch the FPS badge in the toolbar.

Generate code-like diffs instead of plain text (txt, js, or ts):

./scripts/create_large_diff_repo.sh --lines 25000 --files 20 --lang ts --force
./scripts/create_large_diff_repo.sh --lines 25000 --files 20 --lang js --force

To spread the same total load across multiple files:

./scripts/create_large_diff_repo.sh --lines 6000 --files 4 --force

Automated Perf Harness

Run the repeatable large-diff perf harness with threshold gating:

./scripts/run_perf_harness.sh

Run without threshold gating (metrics only):

./scripts/run_perf_harness.sh --no-gate

Protocol and metric definitions are documented in PERFORMANCE_BENCHMARK.md. The harness script currently targets Unix-like shells (bash).

Config

Hunk reads config from ~/.hunkdiff/config.toml. Keyboard shortcuts are configured in the [keyboard_shortcuts] table:

[keyboard_shortcuts]
toggle_sidebar_tree = ["cmd-b", "ctrl-b"]
open_project = ["cmd-shift-o", "ctrl-shift-o"]
save_current_file = ["cmd-s", "ctrl-s"]
open_settings = ["cmd-,", "ctrl-,"]
quit_app = ["cmd-q"]

Use an empty list to disable a shortcut action:

[keyboard_shortcuts]
quit_app = []

Icons

Generate git-diff icon variants and rebuild the bundle:

./scripts/generate_diff_icons.py
./scripts/build_macos_icon.sh
./scripts/build_windows_icon.sh
just bundle

Generated assets:

• assets/icons/hunk-icon-default.png (default/full color)
• assets/icons/hunk-icon-dark.png (dark appearance variant)
• assets/icons/hunk-icon-mono.png (monochrome/tint-friendly variant)

Current packaging uses Hunk.icns, Hunk.ico, and hunk_new.png through cargo-packager.

Hot Reload (Bacon)

Install bacon once:

cargo install bacon

Start hot reload (default job is run):

bacon

Useful jobs:

bacon check
bacon test
bacon clippy

Keybindings in bacon UI:

• r -> run
• c -> check
• t -> test
• l -> clippy