io.github.Alejandro-M-P/git-courer
Full git MCP server for LLM agents — 17 tools, AST annotator, auto-backups, real plumbing.
Open source Open in the app JSON README (API)
About
Full git MCP server for LLM agents — 17 tools, AST annotator, auto-backups, real plumbing.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- alejandro-m-p
- Origin
- official
- Category
- ferramentas
- Transport
- desconhecido
- Version
- 2.0.4
- Stars
- 43
- Forks
- 4
- Open pull requests
- 7
- Last push
- 2026-08-21T19:23:47Z
- Repository state
- ativo
- Language
- Go
- License
- MIT
- Added
- 2026-08-29 03:01:41
- Updated
- 2026-08-29 03:01:41
- Origin id
io.github.Alejandro-M-P/git-courer
README
<!-- 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](https://github.com/blak0p/git-courer/issues) · **Discussions**: [@blak0p/git-courer/discussions](https://github.com/blak0p/git-courer/discussions)
| Doc | Description |
| --- | --- |
| [Web](https://blak0p.github.io/git-courer/) | Visit the official website |
| [Roadmap](docs/roadmap.md) | What's coming next and the strategic vision |
| [Architecture](docs/architecture.md) | Codebase structure, patterns, and how to add features |
| [Troubleshooting](docs/troubleshooting.md) | Fix: Ollama not running, MCP not detected, permission errors |
| [MCP Clients](docs/mcp-clients.md) | All 5 supported CLI agents, config formats, manual setup |
| [Config Options](docs/config.md) | All `~/.config/git-courer/config.yaml` and `.git/git-courer/config.json` settings |
| [Commands](docs/commands.md) | Complete reference for all 13 MCP tools |
| [Contributing](docs/contributing.md) | 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
```bash
curl -fsSL https://raw.githubusercontent.com/blak0p/git-courer/main/scripts/install.sh | sh
```
```go
go install github.com/blak0p/git-courer@latest
```
**Homebrew:**
```bash
brew install blak0p/tap/git-courer
```
### Quick start
```bash
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
```bash
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.
```yaml
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](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](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](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.