grut

command module

v0.0.4 Latest Latest Go to latest Published: Mar 23, 2026 License: MIT Imports: 4 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/jongio/grut

Links

Open Source Insights

README ¶

A reactive terminal UI for Git and GitHub where every panel talks to every other panel.

grüt Explorer layout with file tree, git info, and syntax-highlighted preview

Why grut?

Files, Git, GitHub, and preview — all in one terminal, all aware of each other. Pick a branch and the file tree, commits, and preview update. Pick a file and commits filter to its history. Pick a PR and three panels reconfigure at once. No switching tools, no refreshing.

Features

Reactive Panels

Context-Aware — Panels react to your selections. Select a branch, file, worktree, remote, stash, or PR and every other panel updates to match.
Commit-Files Mode — Enter on a commit shows only that commit's changed files in the tree. Escape restores.
PR Triple-Sync — Select a PR and file tree, commits, and preview all update simultaneously.
Git Filter — g toggles the file tree to git-changed files only. Preview switches to diff mode automatically.

Files

File Explorer — Navigate your project with git status markers, Nerd Font icons, create/rename/delete
Fuzzy Finder — / for instant file search
Syntax Highlighting — 100+ languages via Chroma
Preview — Adapts to show file content, issue/PR bodies, workflow details, or diffs depending on selection

Git

Status & Staging — Stage, unstage, discard with single keystrokes. Partial staging for individual hunks and lines.
Branches, Worktrees, Stash, Tags, Remotes, Reflog — Each as a dedicated tab with full CRUD operations.
Diff — Inline and side-by-side modes with hunk navigation.
Log — Commit graph with ASCII visualization.
Merge, Rebase, Blame, Bisect, Undo/Redo — Complete git workflow without leaving the terminal.

GitHub

Issues, Pull Requests, Actions, Workflows, Releases — Each as a tab with filters and preview integration.
Merge PRs — Merge pull requests with merge commit, squash, or rebase strategies and optional branch cleanup.
Workflow Dispatch — Trigger CI/CD workflows with parameters from the TUI.

AI Chat

Built-in chat powered by GitHub Copilot — read/write files, run git commands, search code, interact with issues and PRs.
AI-powered commit messages, conflict resolution, code review, and PR descriptions.
Collapsed, expanded, and full-screen overlay modes.

Interface

Themes — Default, Catppuccin, Tokyo Night, Gruvbox, plus custom TOML themes.
Session Persistence — Saves and restores layout on restart.
Self-Update — grut update upgrades in-place.

See the Roadmap for what's coming next.

Screenshots

AI Chat

Git Info

Git Diff

Inline diff view with syntax-highlighted additions and deletions

Git Branches

Branch management panel with local and remote branches

Git Log

Fuzzy Finder

Fuzzy file finder overlay for quick navigation

File Explorer & Preview

File explorer with syntax-highlighted preview

Themes

Default

Catppuccin

Tokyo Night

Gruvbox

Installation

Shell script (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/jongio/grut/main/install.sh | sh

To install a specific version:

curl -fsSL https://raw.githubusercontent.com/jongio/grut/main/install.sh | sh -s -- v0.1.0

PowerShell script (Windows)

irm https://raw.githubusercontent.com/jongio/grut/main/install.ps1 | iex

To install a specific version:

$v="v0.1.0"; irm https://raw.githubusercontent.com/jongio/grut/main/install.ps1 | iex

Go Install

go install github.com/jongio/grut@latest

Binary Download

Download from GitHub Releases.

Updating

grut update  # Downloads and installs the latest release

Quick Start

grut              # Launch file explorer in current directory
grut /path/to/dir # Open specific directory
grut update       # Update grut to the latest release
grut version      # Print the version

CLI Flags

Flag	Description
`--help`, `-h`	Show usage information
`--version`, `-v`	Print the version and exit
`--demo`	Launch with a demo project to explore grut
`--no-ai`	Disable AI features for this session

A background update check runs on every launch and notifies you when a new version is available.

Nerd Font Icons

grüt displays file-type icons using Nerd Font glyphs. For the best experience, install a Nerd Font (e.g. 0xProto, FiraCode, JetBrainsMono) and configure your terminal to use it.

When icon_mode is set to "auto" (the default), grüt detects known nerd-font-capable terminals (WezTerm, kitty, Alacritty, iTerm, Ghostty, Windows Terminal, etc.) and enables icons automatically. You can also force it:

# ~/.config/grut/config.toml
[file_tree]
icon_mode = "nerd"   # always use nerd font icons
# icon_mode = "ascii" # always use plain ASCII

Or set the environment variable GRUT_NERD_FONT=1 to enable nerd icons in any terminal.

Keybindings

See docs/keybindings.md for the complete reference.

Key	Action
`j` / `k`	Navigate up/down
`h` / `l`	Collapse/expand
`Enter`	Open/select
`1`–`5`	Focus panel (File Tree, Git Info, GitHub, Commits, Preview)
`/`	Fuzzy finder
`?`	Help overlay
`R`	Refresh all data + preview
`F`	Fetch all remotes
`P`	Push
`s`	Stage file
`x`	Delete / cancel
`g`	Toggle git filter

Configuration

Config file: ~/.config/grut/config.toml (Linux/macOS) or %APPDATA%\grut\config.toml (Windows)

See docs/configuration.md for all options.

Building from Source

git clone https://github.com/jongio/grut.git
cd grut
go build -o grut .
./grut

Or with Mage:

mage build

Development

grut uses Mage for development workflows:

mage install    # Run tests, build bin/grut-dev, add to PATH (default target)
mage test       # Run all unit tests
mage preflight  # Pre-commit checks: fmt, tidy, vet, build, test, vulncheck
mage vet        # Run go vet
mage lint       # Run golangci-lint (falls back to go vet)
mage fmt        # Format all Go source files
mage clean      # Remove bin/ directory

You can also use standard Go commands directly:

go build ./...   # Build all packages
go test ./...    # Run all tests
go vet ./...     # Vet all packages

Tech Stack

Go 1.26 + Bubble Tea v2 (TUI) + Lipgloss v2 (styling) + Bubbles v2 (widgets)
Chroma v2 (syntax highlighting) + Glamour (markdown rendering)
fsnotify (filesystem watching) + mimetype (file type detection)
TOML configuration via go-toml/v2
Cobra CLI framework

License

MIT

Documentation ¶

There is no documentation for this package.

Source Files ¶

View all Source files

main.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
contrib-notes command Command contrib-notes extracts contributor information from git history and outputs formatted text for changelogs, release notes, or CONTRIBUTORS.md.	Command contrib-notes extracts contributor information from git history and outputs formatted text for changelogs, release notes, or CONTRIBUTORS.md.
internal
actions Package actions defines the action registry for configurable double-click actions.	Package actions defines the action registry for configurable double-click actions.
ai Package ai defines the provider interface and shared types for the AI subsystem.	Package ai defines the provider interface and shared types for the AI subsystem.
ai/middleware Package middleware provides AIGitClient, a transparent wrapper around git.GitClient that intercepts operations with AI enhancements while delegating all other methods to the inner client.	Package middleware provides AIGitClient, a transparent wrapper around git.GitClient that intercepts operations with AI enhancements while delegating all other methods to the inner client.
ai/ops Package ops implements AI-powered git operations that compose the core provider and context types from the ai package.	Package ops implements AI-powered git operations that compose the core provider and context types from the ai package.
bookmarks Package bookmarks manages persistent directory bookmarks for the grut TUI.	Package bookmarks manages persistent directory bookmarks for the grut TUI.
chat Package chat implements the conversational AI chat box, including tool definitions that the model can invoke to interact with the repository.	Package chat implements the conversational AI chat box, including tool definitions that the model can invoke to interact with the repository.
config Package config handles application configuration for grut.	Package config handles application configuration for grut.
context Package context provides context-building utilities for AI chat workflows.	Package context provides context-building utilities for AI chat workflows.
contributors Package contributors extracts, deduplicates, and formats contributor information from git history for use in changelogs, release notes, and the CONTRIBUTORS.md hall of fame.	Package contributors extracts, deduplicates, and formats contributor information from git history for use in changelogs, release notes, and the CONTRIBUTORS.md hall of fame.
crashlog Package crashlog captures, stores, and formats crash reports for grut.	Package crashlog captures, stores, and formats crash reports for grut.
demo
extension Package extension implements grut's plugin system.	Package extension implements grut's plugin system.
extension/runtime Package runtime provides sandboxed execution environments for grut extensions.	Package runtime provides sandboxed execution environments for grut extensions.
git Package git wraps the git CLI to provide typed, safe access to git operations.	Package git wraps the git CLI to provide typed, safe access to git operations.
github
keymap Package keymap provides a configurable key-dispatch system for grut.	Package keymap provides a configurable key-dispatch system for grut.
layout Package layout implements the layout engine for grut's TUI.	Package layout implements the layout engine for grut's TUI.
markdown Package markdown provides shared markdown-to-terminal rendering used by both the preview pane and the chat panel.	Package markdown provides shared markdown-to-terminal rendering used by both the preview pane and the chat panel.
mcp Package mcp provides MCP (Model Context Protocol) server functionality.	Package mcp provides MCP (Model Context Protocol) server functionality.
notify Package notify provides a notification system for the grut TUI.	Package notify provides a notification system for the grut TUI.
panels Package panels defines shared message types used for inter-panel communication.	Package panels defines shared message types used for inter-panel communication.
panels/agents Package agents implements the Agent Monitor panel for grut.	Package agents implements the Agent Monitor panel for grut.
panels/aiconflict Package aiconflict implements a three-way diff panel with AI-powered conflict resolution suggestions.	Package aiconflict implements a three-way diff panel with AI-powered conflict resolution suggestions.
panels/bookmarks Package bookmarks implements the bookmarks overlay panel for grut.	Package bookmarks implements the bookmarks overlay panel for grut.
panels/branches Package branches implements the branch management panel for grut.	Package branches implements the branch management panel for grut.
panels/commits Package commits implements the commits panel for grut.	Package commits implements the commits panel for grut.
panels/conflicts Package conflicts implements the conflict resolution panel for grut.	Package conflicts implements the conflict resolution panel for grut.
panels/context Package context implements the context builder panel for grut.	Package context implements the context builder panel for grut.
panels/extensions Package extensions implements the extension management panel for grut.	Package extensions implements the extension management panel for grut.
panels/filetree Package filetree implements the file explorer panel for grut.	Package filetree implements the file explorer panel for grut.
panels/fuzzyfinder Package fuzzyfinder implements a fuzzy search overlay for grut.	Package fuzzyfinder implements a fuzzy search overlay for grut.
panels/gitdiff Package gitdiff implements the diff viewer panel for the grut TUI.	Package gitdiff implements the diff viewer panel for the grut TUI.
panels/gitinfo Package gitinfo implements a combined panel that displays branches, worktrees, and remotes as switchable tabs within a single panel.	Package gitinfo implements a combined panel that displays branches, worktrees, and remotes as switchable tabs within a single panel.
panels/gitlog Package gitlog implements the git log panel for grut.	Package gitlog implements the git log panel for grut.
panels/gitstatus Package gitstatus implements the Git Status panel for grut.	Package gitstatus implements the Git Status panel for grut.
panels/help Package help implements the help overlay panel for grut.	Package help implements the help overlay panel for grut.
panels/preview Package preview implements the file preview panel for the grut TUI.	Package preview implements the file preview panel for the grut TUI.
panels/review Package review implements the diff review panel for grut.	Package review implements the diff review panel for grut.
panels/settings Package settings implements the settings overlay panel for grut.	Package settings implements the settings overlay panel for grut.
panels/stash Package stash implements the stash management and cherry-pick panel for grut.	Package stash implements the stash management and cherry-pick panel for grut.
panels/terminal Package terminal implements the embedded terminal panel for grut.	Package terminal implements the embedded terminal panel for grut.
panels/welcome Package welcome implements the first-run welcome overlay panel for grut.	Package welcome implements the first-run welcome overlay panel for grut.
panels/worktrees Package worktrees implements the worktree management panel for grut.	Package worktrees implements the worktree management panel for grut.
rightclick Package rightclick provides a shared helper for building context menu commands from the action registry and user configuration.	Package rightclick provides a shared helper for building context menu commands from the action registry and user configuration.
session Package session manages persistent session state for grut.	Package session manages persistent session state for grut.
shortcuts Package shortcuts provides AI-powered git workflow shortcut definitions and an execution engine.	Package shortcuts provides AI-powered git workflow shortcut definitions and an execution engine.
terminal Package terminal provides a pipe-based terminal backend for grut.	Package terminal provides a pipe-based terminal backend for grut.
theme Package theme provides the color theme system for grut.	Package theme provides the color theme system for grut.
tui Package tui implements the terminal user interface for grut using Bubble Tea v2, Lip Gloss v2, and Bubbles v2.	Package tui implements the terminal user interface for grut using Bubble Tea v2, Lip Gloss v2, and Bubbles v2.
update Package update implements background version checking and self-updating for the grut CLI.	Package update implements background version checking and self-updating for the grut CLI.