https://github.com/jongio/grut
A terminal file explorer with full Git and GitHub integration, AI chat, and reactive panels that stay in sync as you navigate.
https://github.com/jongio/grut
cli copilot developer-tools dprun dx-idea file-explorer git git-client github terminal terminal-ui tui
Last synced: about 2 hours ago
JSON representation
A terminal file explorer with full Git and GitHub integration, AI chat, and reactive panels that stay in sync as you navigate.
- Host: GitHub
- URL: https://github.com/jongio/grut
- Owner: jongio
- License: mit
- Created: 2026-03-10T04:26:50.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-07-03T19:55:26.000Z (4 days ago)
- Last Synced: 2026-07-03T21:27:22.347Z (4 days ago)
- Topics: cli, copilot, developer-tools, dprun, dx-idea, file-explorer, git, git-client, github, terminal, terminal-ui, tui
- Language: Go
- Homepage: https://jongio.github.io/grut/
- Size: 27 MB
- Stars: 40
- Watchers: 0
- Forks: 2
- Open Issues: 46
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
[](https://github.com/jongio/grut/actions/workflows/ci.yml)
[](https://goreportcard.com/report/github.com/jongio/grut)
[](https://pkg.go.dev/github.com/jongio/grut)
[](LICENSE)
[](go.mod)
[](#)
A reactive terminal UI for Git and GitHub where every panel talks to every other panel.
## 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` cycles through three modes: all files → git-changed → branch diff. 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. Press `f` to toggle between file-on-disk and contextual diff view. Click and drag to select text, `y` to copy.
- **Inline Editor** — Press `e` in the preview panel to edit files directly. `Ctrl+S` saves, `Escape` discards.
### 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](ROADMAP.md) for what's coming next.
Screenshots
### AI Chat
### Git Info
### Git Diff
### Git Branches
### Git Log
### Fuzzy Finder
### File Explorer & Preview
Themes
### Default
### Catppuccin
### Tokyo Night
### Gruvbox
## Installation
### Shell script (Linux / macOS)
```bash
curl -fsSL https://raw.githubusercontent.com/jongio/grut/main/install.sh | sh
```
To install a specific version:
```bash
curl -fsSL https://raw.githubusercontent.com/jongio/grut/main/install.sh | sh -s -- v0.1.0
```
### PowerShell script (Windows)
```powershell
irm https://raw.githubusercontent.com/jongio/grut/main/install.ps1 | iex
```
To install a specific version:
```powershell
$v="v0.1.0"; irm https://raw.githubusercontent.com/jongio/grut/main/install.ps1 | iex
```
### Go Install
```bash
go install github.com/jongio/grut@latest
```
### Binary Download
Download from [GitHub Releases](https://github.com/jongio/grut/releases).
### Updating
```bash
grut update # Downloads and installs the latest release
```
## Quick Start
```bash
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 |
| `--cpu-profile FILE` | Write CPU profile to FILE (dev/debug) |
| `--mem-profile FILE` | Write memory profile to FILE (dev/debug) |
| `--pprof PORT` | Start pprof server on localhost:PORT (dev/debug) |
| `--reset-welcome` | Reset first-run state so the welcome screen shows on next launch |
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](https://www.nerdfonts.com/) 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:
```toml
# ~/.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](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` | Cycle filter: all → git changed → branch diff |
| `e` | Edit file inline (in preview panel) |
## Configuration
Config file: `~/.config/grut/config.toml` (Linux/macOS) or `%APPDATA%\grut\config.toml` (Windows)
See [docs/configuration.md](docs/configuration.md) for all options.
## Building from Source
```bash
git clone https://github.com/jongio/grut.git
cd grut
go build -o grut .
./grut
```
Or with Mage:
```bash
mage build
```
## Development
grut uses [Mage](https://magefile.org/) for development workflows:
```bash
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:
```bash
go build ./... # Build all packages
go test ./... # Run all tests
go vet ./... # Vet all packages
```
## Tech Stack
- **Go 1.26.3** + **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