GitFrame

Understand code in its exact Git context.

GitFrame is a terminal workspace for reviewing Git changes, browsing source, and exploring history.

“Frame” is the Git context that gives code its meaning: the repository, worktree, file path, current state, commits, and comparison basis. GitFrame preserves that frame so you always know exactly what you are viewing or changing.

gitframe-demo.mp4

Highlights

• Switch repositories and branches.
• Navigate with Vim-style keys.
• Review unified or side-by-side diffs. (Changes, History, Compare)
• Stage, commit, and sync changes. (Changes)
• View full source files and explore the repository. (Repository)
• Inspect commits and their changed files. (History)
• Compare branches using merge-base. (Compare)

Four working views

GitFrame separates current changes, repository browsing, commit history, and branch comparison into four working views.

Key	View	Focus
1	Changes	Working tree and index
2	Repository	Repository source
3	History	Commits and commit ranges
4	Compare	Current HEAD and selected Base branch

Installation

GitFrame can be installed with Homebrew or mise, or built from source. Homebrew and mise use prebuilt binaries from GitHub Releases, so no Zig compiler is required for those methods.

Requirements

The prebuilt binaries support the following platforms:

Platform	Requirements
macOS	macOS 15 or newer on Apple Silicon
Linux	x86_64, kernel 5.15 or newer, glibc 2.35 or newer

GitFrame runs in an interactive terminal and requires Git 2.45.1 or newer on your PATH. Check the installed version with git --version. Homebrew installs Git as a dependency; install Git separately when using mise or building from source. For Git updates and startup failures, see requirements troubleshooting.

Homebrew

With Homebrew installed, run:

brew install hiroaqii/tap/gitframe

On Apple Silicon, use native ARM Homebrew.

To update GitFrame:

brew update
brew upgrade hiroaqii/tap/gitframe

mise

With mise installed and activated in your shell, run:

mise use -g github:hiroaqii/gitframe@latest

This makes GitFrame available globally in shells using mise. To update:

mise upgrade github:hiroaqii/gitframe

By default, mise waits 24 hours before selecting a newly published release with @latest. See mise's minimum release age setting for details.

From source

See the guide's source build instructions to build GitFrame with Zig and install the binary.

Check the installation

Check that GitFrame is available:

gitframe --version
gitframe --help

Getting started

Run GitFrame inside a Git worktree to review staged and unstaged changes:

gitframe

In the main views, press ? for help or q to quit. Run gitframe --help to see the available command-line options.

See the guide for usage, configuration, troubleshooting, and development instructions.

Design boundaries

GitFrame is intentionally scoped and does not aim to provide:

• a full text editor or IDE;
• a replacement for every Git command;
• an interactive rebase or commit-graph workbench;
• a provider-specific Git hosting client or web interface;
• native Windows support.

Architecture

GitFrame is written in Zig and built on:

• Chasen for the terminal runtime and effect boundary;
• Chasen UI for reusable TUI components;
• flow-syntax for optional syntax highlighting.