whygit MCP server

whygit

<!-- mcp-name: io.github.Srikarmk/whygit -->

What just happened to my Git repository, and how do I fix it?

whygit looks at a Git repository and tells you, in plain English, what state it is in and which commands will get you out of it: a merge conflict, a rebase stopped halfway, a detached HEAD, a rejected push, a login GitHub won't accept, a 120 MB CSV that GitHub will refuse. Paste it an error message and it explains that too.

It is written for people meeting Git for the first time. Git's own messages are accurate but hard to read; whygit turns them into a short explanation and the exact fix.

It only ever reads your repository. It never runs the fixes it suggests, so you stay in control and learn the commands as you go.

There are two ways to use it, built on the same engine:

reliable diagnosis instead of guessing from git status.

• On the command line, with no AI tools involved: whygit.
• As an MCP server, so an assistant such as Claude Code, Claude Desktop or Cursor gets a

Install

whygit needs Python 3.10 or newer and Git. Pick one:

uv tool install whygit     # with uv (https://docs.astral.sh/uv/)
pipx install whygit        # with pipx
uvx whygit                 # run once without installing

This works the same on macOS, Windows and Linux.

Use it from the terminal

Run it inside your project folder:

whygit                    # what's wrong here, most urgent first
whygit status             # a plain summary: branch, upstream, what's changed
whygit explain "fatal: refusing to merge unrelated histories"
git push 2>&1 | whygit explain -

Options: --path (or -C) to look at another folder, --json for machine-readable output, --no-color to turn off colour. Colour is only used in a real terminal and never when NO_COLOR is set.

Exit codes: 0 nothing blocking, 1 something blocking was found, 2 bad usage (for example the folder does not exist), 3 explain did not recognise the message.

Example

$ whygit
whygit: /Users/sam/ds3500/hw2 (branch main)

[BLOCKING] Merge in progress with conflicts in 1 file
  Git tried to combine two lines of work, but both changed the same part of these
  files, so it stopped and is waiting for you to choose what the result should be.
  Nothing is lost while you decide.
  Conflicted files:
    - analysis.py  (both changed)
  How to fix:
    Finish the merge:
      1. Open each file and find the blocks between <<<<<<< and >>>>>>>. The part
         above ======= is one version, the part below is the other. Keep what you
         want, and delete the three marker lines.
      2. git add analysis.py
         Marks the files as resolved
      3. git commit --no-edit
         Records the merge and finishes it
    Or cancel the merge:
      1. git merge --abort
         Puts everything back the way it was before the merge started
  Learn more: https://git-scm.com/docs/git-merge#_how_to_resolve_conflicts

1 blocking. whygit never runs these commands for you; copy the ones you want.

Shortened. The full README is on GitHub.