<!-- mcp-name: io.github.blak0p/git-courer --> <!-- markdownlint-disable MD041 --> <img width="1259" height="619" alt="Gemini_Generated_Image_g9lcw7g9lc" src="https://github.com/user-attachments/assets/2e9c0e64-b0de-4b83-9159-3a5906f9f3f4" />

<p align="center"> <a href="https://github.com/blak0p/git-courer/releases/latest"> <img src="https://img.shields.io/github/v/release/blak0p/git-courer?color=%2300BFFF&label=latest" alt="Release"> </a> <a href="https://github.com/blak0p/git-courer/actions"> <img src="https://img.shields.io/github/actions/workflow/status/blak0p/git-courer/test.yml?branch=main" alt="Build"> </a> <a href="https://github.com/blak0p/git-courer/blob/main/LICENSE"> <img src="https://img.shields.io/github/license/blak0p/git-courer" alt="MIT License"> </a> </p>

Issues & Bugs: @blak0p/git-courer/issues · Discussions: @blak0p/git-courer/discussions

Quick Links

Install

go install github.com/blak0p/git-courer@latest

curl -fsSL https://raw.githubusercontent.com/blak0p/git-courer/main/scripts/install.sh | sh

That's it. It installs the binary and auto-configures every AI tool it detects on your machine.

Requirements: Git · llm local

Homebrew (macOS / Linux):

brew install blak0p/tap/git-courer

Windows

# Windows (PowerShell)
irm https://github.com/blak0p/git-courer/releases/latest/download/git-courer_windows_amd64.tar.gz | tar -xz -o git-courer.exe
.\git-courer.exe setup

Manual install:

# macOS / Linux
curl -fsSL https://github.com/blak0p/git-courer/releases/latest/download/git-courer_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m).tar.gz | tar -xz -C /usr/local/bin git-courer
chmod +x /usr/local/bin/git-courer
git-courer setup

git-courer

The only MCP git server that understands your code before it commits.

Most tools wrap git diff | llm "write a commit". git-courer does something different: it parses your AST, builds a dependency graph, classifies the change type in Go without touching the LLM, an[...]

One staged area = one commit. Always.

Why it's different

1. Commit type determined in Go, not by the LLM

git-courer uses go-enry and go-tree-sitter to parse your AST and apply deterministic rules — new public function, modified signature, deleted symbol, breaking change. The LLM writes the message,[...]

2. Dependency graph

Before committing, git-courer builds a graph of what your staged files affect across the codebase. Real scope, not just which files were touched.

3. Local + cloud working together

Go and the local LLM handle everything they can. Your cloud LLM receives structured commit context — WHY + WHAT — instead of raw code.

4. Commits as LLM context

A git-courer commit is a compressed, structured summary any LLM can consume directly. Better input, fewer tokens, fewer hallucinations.

5. Automatic backup on every mutation

Every write operation creates a backup before executing. One command undoes anything.

6. The complete git pack — one server, nothing else needed

Why install one tool for commits, another for releases, another for PR checks? git-courer covers the full cycle:

Read: status, diff, history, blame, pr-review Write: commit, amend, revert, stage, reset, stash Branch: branch, merge, rebase, cherry-pick, tag Utility: sync, backup, undo, remotes, config

All returning structured JSON. No pager hangs, no text parsing, no extra tools.

Workflows

Commit

Preview the change → review proposed commits → apply. git-courer splits your staged files into atomic commits by dependency graph automatically.

Before any PR or merge

Call pr-review — a pre-PR gate that runs in one shot:

1. Tests — runs test_command from .git/git-courer/config.json (e.g. go test ./...)
2. Conflicts — detects merge conflicts with the target branch and returns AST-annotated hunks ([NEW_FUNC], [MOD_SIG ⚠BREAKING])
3. Diff stats — files changed, additions, deletions
4. Divergence — ahead/behind count, mergeable status

If it's not green, you don't merge. Set test_command via git-config SET_TEST_COMMAND or edit .git/git-courer/config.json directly.

Release (CLI)

Run git-courer release. The CLI reads commits from .git/git-courer/branches/ (captured during each git-commit APPLY on this branch) and also from refs/courer/* — per-branch commit blobs that survive squash merges and deleted branches

Undo

Every destructive operation has an automatic backup. One command restores the previous state.

How it works

You: "commit my changes"
        ↓
AI delegates to git-courer (via MCP)
        ↓
Go reads AST + dependency graph → classifies type deterministically
        ↓
Local LLM writes the human-readable message from the annotated diff
        ↓
Security scan (5 layers) → auto-backup → commit
        ↓
"✓ feat(auth): add OAuth2 token refresh"

For the full list of tools: docs/commands.md For workflow details: docs/workflows.md

Supported Tools

Run git-courer mcp setup to configure all detected tools at once, or git-courer mcp setup <client> for a specific one.

Interactive TUI

Run git-courer with no arguments to launch the interactive installer:

Interactive TUI

The TUI walks you through 4 steps:

1. MCP Configuration — select which AI tools to configure (auto-detects installed clients)
2. General Settings — configure your LLM backend, model, and project context
3. Review — preview your config before saving
4. Finish — config saved to ~/.config/git-courer/config.yaml

You can also update the binary or uninstall directly from the menu. Navigation: j/k or arrow keys, esc to go back.

Commands

git-courer runs as an interactive TUI when launched without arguments. It also provides MCP server and management commands:

MCP Tools

For the 22 MCP tools and their arguments, see [docs/commands.md](docs/commands.md).

Configuration

git-courer uses two config levels:

Global (~/.config/git-courer/config.yaml) — personal settings: LLM backend, model.

Per-project (.git/git-courer/config.json) — committable, shared with team. Stores description, areas, test_command, excluded. Better results = edit this file per project.

All options: [docs/config.md](docs/config.md)

Background Jobs

When you call git-commit PREVIEW, the server may return immediately (FAST) or start a background job (SLOW). In the SLOW case:

1. PREVIEW returns {status:"processing", job_id}
2. The agent must call git-commit STATUS with that job_id to poll
3. When STATUS returns {status:"done"}, the plan is ready
4. Then call git-commit APPLY with the same job_id

The agent continues working — it does NOT block waiting for the job.

Every successful commit via git-commit APPLY is captured to .git/git-courer/branches/<branch>/commits.json and a refs/courer/<branch> blob is created. When you later run git-courer release, it reads commits from both the local store and the refs — so squash-merged PRs still produce accurate changelogs

Why this matters: Git history is frequently rewritten — PR squashes, rebases, force-pushes — destroying the real commit narrative. The CommitStore preserves every commit message as it was[...]

Troubleshooting

Having issues? Check [docs/troubleshooting.md](docs/troubleshooting.md) for:

• Ollama not running / model not configured
• MCP not detected by your AI tool
• Permission errors during install
• Secrets detected in commits (false positives)

MCP config file locations: [docs/mcp-clients.md](docs/mcp-clients.md)

FAQ

Who decides the commit type? Go, via AST analysis. The LLM only writes the human-readable message.

Do I need Ollama? You need some LLM backend. Ollama is the recommended default, but git-courer works with any OpenAI-compatible server: LM Studio, vLLM, LocalAI, or a custom endpoint. Without a configured backen[...]

Is my code sent anywhere? No. Everything runs on your machine — git-courer, Ollama, your data.

Who decides the version number in a release? Go, not Ollama. Version is calculated from commit types (feat: → minor, feat!: → major). Ollama only writes the human changelog.

My tool isn't listed. Open an issue: @blak0p/git-courer/issues. If it supports MCP, adding it is usually a few lines.

How do I mark a breaking change? Use ! after the commit type (feat!:) or include BREAKING CHANGE: in the body. git-courer picks this up automatically for version bumping and changelog generation.

Used by

<!-- Using git-courer? Share your setup → Discussions and I'll add you here. -->

Running it? Drop your setup in Discussions — I'll add you to this table.

Contributing

Want to collaborate? Here's everything you need:

Architecture & Codebase

Read [docs/architecture.md](docs/architecture.md) for:

• Directory structure and tech stack
• Hexagonal architecture patterns
• Key packages and their responsibilities
• How to add a new feature
• Testing approach

Reporting Bugs

Found a bug? Open an issue: [@blak0p/git-courer/issues](https://github.com/blak0p/git-courer/issues)

Include:

• Your OS and git-courer version (git-courer version)
• AI tool you're using (Claude Code, Cursor, etc.)
• Steps to reproduce
• Relevant logs or error messages

How to Collaborate

1. Read the docs: Start with docs/architecture.md and CONTRIBUTING.md
2. Pick an issue: Check @blak0p/git-courer/issues for good first issue labels
3. Discuss: Use @blak0p/git-courer/discussions for questions or feature ideas
4. Submit PR: Follow conventional commits (feat:, fix:, chore:)

Adding a New MCP Client

If your AI tool supports MCP but isn't listed, adding it is usually 5 lines of code in internal/installer/mcp_config.go. See docs/mcp-clients.md for the format.