Skip to content
mrman

Getting Started

Requirements

Section titled “Requirements”
  • Go 1.26 or newer to build (go.mod declares go 1.26.11; a newer go downloads the pinned toolchain automatically).
  • git on PATH. Jujutsu repositories additionally need jj.
  • A terminal with full kitty keyboard protocol support gives the best experience — Ghostty is the reference. mrman works without it; a few chords fall back to aliases. See Terminal Setup.

Install

Section titled “Install”

Each release carries a tarball for Linux and macOS (amd64 and arm64), a zip for Windows, and a SHA256SUMS manifest. For example, on Linux amd64:

Terminal window
v=vX.Y.Z    # the release you want
base=https://github.com/infrashift/mrman/releases/download/$v
curl -fsSLO "$base/mrman_${v}_linux_amd64.tar.gz"
curl -fsSL "$base/SHA256SUMS" | grep "mrman_${v}_linux_amd64.tar.gz" | sha256sum -c -
tar -xzf "mrman_${v}_linux_amd64.tar.gz"
install "mrman_${v}_linux_amd64/mrman" ~/.local/bin/

Your first review

Section titled “Your first review”

  1. Make some changes in any git repository, then open them:

    Terminal window
    mrman -w

    -w goes straight to your working-tree diff. With no arguments at all, mrman opens the target selector instead so you can pick a commit range.

  2. Move around. j / k by line, } / { by file, ] / [ by hunk. Counts work everywhere: 5j, 3}, 42G. Enter or Space on a ⋯ expander pulls in the hidden context around a hunk.

  3. Comment. Put the cursor on a line and press c. Type. Enter saves.

    C comments on the whole file, v selects a range first, and <leader>c (;c) comments on the review as a whole.

    Tab cycles the comment type, shown in the box title (Add L60 comment [ISSUE]). Four ship by default — NOTE, ISSUE, SUGGESTION, PRAISE — starting on NOTE, then an untyped entry for comments that need no classifying. Define your own to replace them.

  4. Track what you have read. r marks the current file reviewed, R the current hunk. m / M jump between comments.

  5. Export it. With nothing selected, y copies the whole review as markdown to your clipboard. :clip does the same thing by name, and --stdout prints it instead.

  6. Quit. :q (which refuses if you have unsaved comments), :wq or ZZ to save and quit, :q! to discard.

Your review was saved to ~/.local/share/mrman/reviews on the way out. Reopen the same diff later and your comments and reviewed marks are still there.

Set your name

Section titled “Set your name”

Comments are stamped with an author, which is also how mrman tells your comments apart from an agent’s. Set it once:

~/.config/mrman/config.toml
username = "your-name"

While you are in there, the options people change first:

theme = "tokyo-night-storm"   # see the Themes reference for the full list
comment_vim = true            # modal editing in the comment box


[[comment_types]]             # optional: replaces the four built-ins
id = "blocker"
label = "BLOCKER"
definition = "must fix before merge"
color = "red"

Every option is documented in Configuration.

Review a merge request

Section titled “Review a merge request”

If your checkout has a remote on a supported forge, mrman can open pull requests directly:

Terminal window
mrman pr 125                    # by number, repo inferred from the checkout
mrman pr owner/repo#125         # addressed explicitly
mrman pr <MR URL>               # any supported forge
mrman                           # then Tab to the Merge Requests tab

The forge’s existing review threads render inline in the diff, read-only, and :submit posts your review back. Start with How MR Review Works, then your forge: GitHub · GitHub Enterprise · GitLab · Azure DevOps · Forgejo & Gitea ⚗️ · Codeberg ⚗️.

⚗️ marks a driver that is experimental — implemented and unit-tested, but not yet run against a live instance.

Next steps

Section titled “Next steps”