# mdiff
A terminal UI for reviewing git diffs and providing feedback to coding agents. Built for developers running multiple agents across worktrees who need a fast way to review changes, annotate code, and send structured feedback back.
## Features
- **Split and unified diff views** — side-by-side or interleaved, toggle with `Tab`
- **Syntax highlighting** — tree-sitter powered, supports Rust, TypeScript, JavaScript, Python, Go, Ruby, JSON, TOML, YAML, CSS, HTML, and Bash
- **Inline annotations** — select diff lines in visual mode and attach review comments that persist across sessions
- **Prompt templating** — annotations and diff context are rendered into a structured prompt you can copy to clipboard (`y`) and paste into any agent session, or send directly to a configured agent (`Ctrl+A`)
- **Worktree browser** — browse and switch between git worktrees with automatic detection of active coding agents (Claude Code, Codex, OpenCode, Gemini)
- **Git operations** — stage, unstage, restore files, and commit without leaving the TUI
- **Runtime target switching** — change the comparison ref (branch, tag, commit) at runtime with `t`
- **Fuzzy file search** — quickly filter the file list with `/`
- **Whitespace toggle** — hide whitespace-only changes with `w`
## Installation
**Homebrew**
```
brew install mutinyhq/tap/mdiff
```
**Cargo**
```
cargo install mutiny-diff
```
**GitHub Releases**
Pre-built binaries for macOS (Intel & Apple Silicon) and Linux (x86_64 & ARM) are available on the [releases page](https://github.com/mutinyhq/mdiff/releases).
## Usage
```bash
# Review what an agent changed on this worktree
mdiff
# Compare against main to see the full branch diff
mdiff main
# Diff against a specific commit
mdiff abc1234
# Browse worktrees to check on multiple agents
mdiff --wt
# Start in unified view, ignoring whitespace
mdiff --unified -w
```
## Workflow
mdiff fits into a workflow where you have multiple coding agents working in parallel across git worktrees. You review their output, leave feedback as annotations, and send that feedback back — either by copying a templated prompt into an existing agent session or by launching an agent directly.
1. Open `mdiff` (or `mdiff --wt` to start in the worktree browser)
2. Browse worktrees to see which agents are active and switch to one to review
3. Navigate the diff, press `v` to select lines, and press `i` to annotate with your feedback
4. Repeat across files — annotations persist per comparison target across sessions
5. When ready to send feedback:
- Press `y` to copy the rendered prompt (diff context + annotations) to your clipboard, then paste it into your existing agent session
- Or press `Ctrl+A` to launch a configured agent directly with the prompt
6. Press `p` to preview the prompt before sending
## Keybindings
Press `?` to show all keybindings in the HUD. The essentials:
### Navigation
| `j` / `↓` | Next item / scroll down |
| `k` / `↑` | Previous item / scroll up |
| `g` | Jump to top |
| `G` | Jump to bottom |
| `]` | Jump to next hunk |
| `[` | Jump to previous hunk |
| `h` / `←` | Focus file navigator |
| `l` / `→` / `Enter` | Focus diff view |
| `/` | Search files (or current file in diff view) |
| `Ctrl+F` | Search across all diff content |
| `n` / `N` | Next/previous search match (in global search) |
| `Tab` | Toggle split/unified view |
| `PageUp` / `PageDown` | Scroll page |
### Annotations & Prompts
| `v` | Enter visual mode (select lines) |
| `i` | Add comment on selection |
| `a` | Open annotation menu on current line |
| `d` | Delete annotation on selection |
| `Ctrl+]` / `Ctrl+[` | Jump to next/previous annotation |
| `y` | Copy rendered prompt to clipboard |
| `p` | Toggle prompt preview |
| `Ctrl+A` | Open agent selector |
### Git Operations
| `s` | Stage file |
| `u` | Unstage file |
| `r` | Restore file |
| `c` | Open commit dialog |
| `t` | Change comparison target |
| `R` | Refresh diff |
### General
| `q` | Quit |
| `Ctrl+C` / `Ctrl+D` | Quit (press the same combo twice, from any modal) |
| `w` | Toggle whitespace |
| `o` | Toggle agent outputs tab |
| `Ctrl+W` | Toggle worktree browser |
| `?` | Show/hide all keybindings |
### Worktree Browser
| `j` / `↓` | Next worktree |
| `k` / `↑` | Previous worktree |
| `Enter` | Select worktree |
| `r` | Refresh list |
| `f` | Freeze worktree (stage all + auto-commit) |
| `Esc` | Back to diff view |
## Agent Configuration
Configure agents in `~/.config/mdiff/config.toml`:
```toml
[[agents]]
name = "claude"
command = "claude --model {model} --print '{rendered_prompt}'"
models = ["sonnet", "opus"]
[[agents]]
name = "codex"
command = "codex --model {model} --prompt '{rendered_prompt}'"
models = ["o3-mini", "o4-mini"]
```
The `{rendered_prompt}` placeholder is replaced with the templated prompt containing the diff context, selected code, and your annotations. The `{model}` placeholder is replaced with the model you select.
## CLI Reference
| `<TARGET>` | Branch, commit, or ref to diff against (default: HEAD) |
| `--wt` | Open worktree browser directly |
| `-w`, `--ignore-ws` | Ignore whitespace changes |
| `--unified` | Start in unified view instead of split |
## License
MIT