git-courer

<!-- 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

| Doc | Description | | --- | --- | | Web | Visit the official website | | Roadmap | What's coming next and the strategic vision | | Architecture | Codebase structure, patterns, and how to add features | | Troubleshooting | Fix: Ollama not running, MCP not detected, permission errors | | MCP Clients | All 5 supported CLI agents, config formats, manual setup | | Config Options | All ~/.config/git-courer/config.yaml and .git/git-courer/config.json settings | | Commands | Complete reference for all 13 MCP tools | | Contributing | Setup, running tests, and how to collaborate |

---

git-courer

Git, but agents can't break it.

An MCP server that gives AI agents a full, safe interface to Git — not just commits, the whole surface: status, diff, branch, stash, history, sync. Every mutation backs itself up automatically. Nothing routes through Bash, so there's no git reset --hard happening behind your back.

13 tools. Structured JSON in, structured JSON out. No pagers, no text parsing, no guessing what the agent actually did to your repo.

---

Install

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

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

Homebrew: ``bash brew install blak0p/tap/git-courer ``

Quick start

git-courer mcp setup     # auto-configures your agent (OpenCode, Claude Code, Codex, pi, Antigravity)

Restart your agent, then ask it to run status on any repo. If it comes back with structured JSON instead of raw git status output, you're connected.

Diagnostics & lifecycle

git-courer doctor              # read-only health report for every detected MCP client
git-courer hook-check "git status"   # classify a shell command (agent hook; never denies)
git-courer init                # TUI wizard to create/update project config
git-courer version --predict   # predict next release tag from conventional commits
git-courer remove              # remove project-level config (keeps the binary)
git-courer update              # self-update to the latest release + reconfigure MCP

doctor reports per client: config path, MCP configured, prompt block injected, hooks installed (yes/no/partial), and Claude inline hooks (Claude Code only).

---

How an agent works with git-courer

Agent receives a task
        ↓
session start → creates isolated worktree + branch
        ↓
All MCP tools (diff, status, commit, branch...)
automatically redirect to that worktree
        ↓
commit PREVIEW → Go parses AST + dependency graph
                  classifies type (feat/fix/breaking...)
        ↓
commit APPLY → two modes depending on config:

  ┌─ WITH LLM ──────────────────────────────┐
  │  Local LLM writes the WHY/WHAT message │
  │  Go decides the type (agent can         │
  │  override with type= if wrong)          │
  └─────────────────────────────────────────┘

  ┌─ WITHOUT LLM (toggle off) ─────────────┐
  │  Perfect for modest laptops, no GPU    │
  │  Agent writes the message directly     │
  │  Preview, apply, and type override     │
  │  still work                             │
  └─────────────────────────────────────────┘

        ↓
Security checks → auto backup → commit
        ↓
"✓ fix: refactor session finish workflow to stop automatic merging

    WHY
    The previous implementation automatically attempted to merge session
    branches into the base branch, which forced a specific integration
    strategy and required managing two different git repositories.

    WHAT
    * Removed automated merge logic and the dependency on a second Git
      instance (mainGit) in the session handler and workflow.
    * Updated cleanup to remove worktrees while leaving session branches
      alive for manual integration.
    * Switched to PreviewLight validation to prevent data loss from
      uncommitted changes.
    * Updated FinishResult to include BranchAlive status."

session finish → closes session + cleans up worktree

---

LLM Toggle

Modest laptop with no GPU? Flip the toggle and git-courer runs fully without an LLM. The agent writes messages directly, Go still decides the type.

llm:
  enabled: false

Without LLM: commit with message, preview and type override work. Release is not available. Everything else (status, diff, branch, session, backup) works normally.

---

Why it's different

1. Commit type decided by Go, not the LLM

AST analysis + deterministic rules. The LLM only writes the message. If the type is wrong, the agent overrides it with type=.

2. Dependency graph

Before committing, it maps what your changes affect across the entire codebase. Real impact, not just "you touched 3 files".

3. Isolated worktrees

Each agent gets its own directory and branch. No stepping on each other. session start creates, session finish closes and cleans up.

4. Commits as LLM context

Structured summary with WHY/WHAT. Any LLM consumes it directly. Fewer tokens, fewer hallucinations.

5. Automatic backup

Every write operation backs up before executing. One command undoes anything.

6. Releases that survive squashes

Commits are stored in refs/courer/*. Squash, rebase, force push — your changelog doesn't disappear.

---

What a release looks like

❯ git-courer release

Tag? [v3.0.0]:
Add guidance for changelog generation? (y/N): n

   📦 Release Preview

  Tag: v3.0.0    Version Bump: major

  --- Changelog ---
  ...

Apply? (y/N/r/e):

This is the changelog it writes:

v2.8.0 — This update introduces an advanced session management system using git worktrees to enable parallel workflows and improves the robustness of agent execution rules. Session Management and Isolation - Implemented isolated sessions using git worktrees to prevent agents from interfering with each other; includes full lifecycle with listing, selection, and automatic cleanup via slugified identifiers. - Integrated sessionGit wrapper into the MCP server for automatic directory redirection. Developer Experience and Configuration - Refined golden rules, now prohibiting work in the repository root to enforce strict workspace isolation. - Automatic injection of prompt rule blocks into client configuration files. - Fixed TUI MCP setup bug where clients were not configured correctly. System Robustness and Refactoring - Refactored agent instruction structure, removing unnecessary tool maps. - Improved file cleanup using robust base names to prevent errors with complex paths.

---

Workflows

Session

session start → isolated worktree + branch. All MCP tools redirect there. session finish closes and cleans up. session discard throws it away.

Commit

PREVIEW → review proposed commits. APPLY → executes them. Go splits files by dependency graph into atomic commits.

PR Review

pr-review → tests + conflicts + diff stats + divergence. All in one call.

Release

git-courer release → interactive. Pick the tag, guide the LLM, preview the changelog, confirm. Commits live in refs/courer/* — they survive squashes.

Undo

backup RESTORE → undoes any operation.

---

Tools (13)

| Tool | Subcommands | What it does | | --- | --- | --- | | status | — | Full repo state: branch, changes, conflicts, stash, etc. | | diff | — | Diff with AST tags (NEW_FUNC, MOD_SIG, DEPS, DEL) | | commit | PREVIEW → APPLY | 3-phase LLM pipeline: preview, review, apply | | branch | CREATE / SWITCH / DELETE / RENAME / LIST | Branch management | | stage | RM / RESTORE / CLEAN | Staging area control | | stash | SAVE / POP / SHOW | Stash management | | history | LOG / REFLOG / BLAME | History inspection | | sync | PUSH / PULL / FETCH | Remote sync | | pr-review | — | Tests + conflicts + diff stats + divergence in one call | | backup | RESTORE / LIST | Undo amend/merge/rebase | | rewrite | AMEND / REVERT / SOFT / HARD | History rewriting | | integrate | MERGE / UPDATE / PICK / CONTINUE / ABORT | Branch integration | | session | start / finish / status / select / discard | Isolated worktree lifecycle |

Full reference with examples: docs/commands.md.

---

Supported clients

| Tool | Auto-configured | |------|----------------| | OpenCode | ✓ | | Claude Code | ✓ | | Codex | ✓ | | pi | ✓ | | Antigravity | ✓ |

git-courer mcp setup configures all at once. Manual setup and config formats: docs/mcp-clients.md.

---

Hooks & golden rules

mcp setup does more than register the MCP server — it also injects guardrails so agents route git operations through git-courer instead of raw Bash.

Golden rules injection. A <!-- git-courer start --> / <!-- git-courer end --> block is injected (and kept up to date) in each client's instructions file (AGENTS.md for OpenCode, CLAUDE.md for Claude Code, GEMINI.md for Antigravity). The block encodes the golden rules: check status before mutating, run diff + review before a PR, always session start first.

Hooks. Clients that support shell hooks get entries wired to git-courer subcommands:

| Event | Matcher | Command | Fires when | |-------|---------|---------|------------| | PreToolUse | git * | git-courer hook-check | Before any Bash git ... run | | SessionStart | — | git-courer session-start-hook | Agent session opens | | SubagentStart | — | git-courer subagent-start-hook | A sub-agent starts | | PreInvocation | — | git-courer pre-invocation-hook | Before each model call (Antigravity) |

hook-check classifies the command and emits additionalContext suggesting the matching git-courer MCP tool — it never denies. The session/subagent/pre-invocation hooks inject the golden rules as additionalContext. Claude Code uses inline settings.json hooks (UserPromptSubmit instead of PreInvocation); Codex uses a separate hooks.json; Antigravity uses a separate hooks.json with a run_command matcher and only 2 events. Full reference: docs/hooks.md.

OpenCode policy. For OpenCode (which has no shell hooks), mcp setup merges into opencode.json:

• permission.bash["git *"] = "ask" — OpenCode prompts the user before any git Bash command, so the agent is nudged toward the MCP tool.
• instructions array includes the AGENTS.md path (legacy GIT_COURER.md entries are removed). The merge is idempotent; a .bak backup is written before any change.

Run git-courer doctor to verify all of the above per client.

---

FAQ

Who decides the commit type? Go. The LLM only writes the message. The agent can override it.

Do I need a GPU or local LLM? No. Flip the toggle (llm.enabled: false) and it runs on any laptop. The agent writes messages directly.

Does my code leave my machine? No. Everything runs locally — git-courer, Ollama, your data.

What about release without an LLM? Not available. Release needs an LLM for the changelog.

How do I mark a breaking change? feat!: or BREAKING CHANGE: in the body. Go detects it automatically.