gaze

Live-reloading terminal markdown previewer with diff highlighting.

Gaze watches markdown files for changes and re-renders them in the terminal. Changed sections are highlighted in the gutter. Built for the workflow where an AI agent edits a file and the rendered result updates live with visual diffs of what changed.

Features

Watching & Diffs

Gaze tracks every change to a file since the last baseline. Modified lines get gutter markers that accumulate until dismissed (d). Press D to open a unified diff view showing all accumulated changes with configurable context lines ([/]). Word-level highlighting (W) shows exactly which words changed within each line.

Three scroll modes control how the viewport responds to changes — smart auto-scrolls to the most recently changed section, fixed holds position, follow tracks the end of the file like tail -f. Cycle with s.

• Live reload via fsnotify — re-renders on every save
• Diff gutter highlights, accumulate until dismissed (d)
• Unified diff view (D) with context lines ([/]), full view (\)
• Word-level diff highlighting, toggle word/char mode (W)
• Scroll modes: smart, fixed, follow (s to cycle)
• Diff views for uncommitted and staged git changes (from git log)

Git Integration

Press l to open the git log for the current file. From there:

• Enter on a commit opens a unified diff showing what that commit changed
• v on a commit enters COMMIT mode — the file is frozen at that point in time, with blame-style gutter highlights showing which lines the commit touched
• s on a commit enters SINCE mode — sets that commit as the diff baseline. Gutter highlights then show everything that has changed from that historical point to the current file on disk
• d dismisses git mode, Esc closes the log

The git log also shows uncommitted and staged entries at the top when changes exist.

Navigation & Reading

Vim-style navigation with regex search and structural features.

• Scroll with j/k, Ctrl+D/Ctrl+U, PgUp/PgDn, g/G
• Regex search with highlight-all (/, n/N)
• Section folding (za toggle, zM fold all, zR unfold all)
• Table of contents overlay (t)
• Link following — Enter on a link opens relative .md files as tabs, URLs in browser
• Zen mode — centered, distraction-free reading (zz)
• File picker — browse and open files (o)

Multi-file & Display

Open multiple files as tabs. Each tab tracks its own diff state, scroll position, and fold state independently. Tab indicators in the status bar show which files have pending changes.

• Tabbed files (Tab/Shift+Tab to switch), tab dots: ● active, ◆ changed, ○ inactive
• 7 built-in themes including Catppuccin Mocha, Dracula, Nord, Tokyo Night (Ctrl+P to change)
• Inline images via Kitty graphics protocol (auto-detected)
• Mermaid diagrams rendered inline via mmdc
• Desktop notifications on file change (a to toggle)
• Position memory — scroll position remembered per file across sessions
• Mouse scrolling enabled by default, Shift+drag to select text

Installation

Go

go install git.jeremyk.net/jeremy/gaze/cmd/gaze@latest

Nix

nix run git+https://git.jeremyk.net/jeremy/gaze -- README.md

Or add to a flake:

inputs.gaze = {
  url = "git+https://git.jeremyk.net/jeremy/gaze.git";
  inputs.nixpkgs.follows = "nixpkgs";
};

Usage

gaze                   # all .md files in current directory
gaze README.md         # single file
gaze *.md              # multiple files (Tab/Shift+Tab to switch)
gaze -r ./docs         # recursive (respects .gitignore)
gaze --web README.md   # browser preview via go-grip

Flag	Description
-r, --recursive	Recursively find .md files (respects .gitignore)
--web	Browser preview via go-grip
-h, --help	Show usage help

Press ? inside gaze for context-aware keybinding help. Press ? again for a concepts guide explaining modes and workflows.

Configuration

All settings can be changed at runtime via the options menu (Ctrl+P) and saved to disk from there. Config file location: ~/.config/gaze/config.toml.

theme = "catppuccin-mocha"
render_width = 80
scroll_mode = "smart"
diff_context = 5

Every feature can be individually toggled under [features]. All default to enabled.

Available themes: catppuccin-mocha (default), dracula, nord, solarized-dark, tokyo-night, dark, light.

Status Bar

The status bar shows the filename, tab indicators, heading breadcrumb, active mode, wrap width, line position, and scroll percentage.

Mode indicators: 1/5 (search match position), ALERT (notifications on), DIFF:source (in diff view), COMMIT:hash (frozen at commit), SINCE:hash (historical baseline), CHANGED (diffs accumulated), ZEN (zen mode), and the scroll mode (SMART/FIXED/FOLLOW).

Building from Source

git clone https://git.jeremyk.net/jeremy/gaze.git
cd gaze
go build -o gaze ./cmd/gaze

Requires Go 1.24+. Optional: mmdc (mermaid-cli) for diagram rendering, Kitty terminal for inline images.

Contributing

See CONTRIBUTING.md for development setup, testing, and code style.

For architecture and design decisions, see docs/architecture.md and docs/decisions.md.

Acknowledgments

Built with Bubble Tea, Glamour, and Lipgloss from Charmbracelet. Diff computation via go-diff. Inline images via rasterm.

License

GPL-3.0 — see LICENSE.