# Git Courer

> Full git MCP server for LLM agents — 17 tools, AST annotator, auto-backups, real plumbing.

- **Type:** MCP server
- **Install:** `agentstack add mcp-alejandro-m-p-git-courer`
- **Verified:** Pending review
- **Seller:** [blak0p](https://agentstack.voostack.com/s/blak0p)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 2.0.0
- **License:** MIT
- **Upstream author:** [blak0p](https://github.com/blak0p)
- **Source:** https://github.com/blak0p/git-courer

## Install

```sh
agentstack add mcp-alejandro-m-p-git-courer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

> **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.

---

## 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).

---

## 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.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [blak0p](https://github.com/blak0p)
- **Source:** [blak0p/git-courer](https://github.com/blak0p/git-courer)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v2.0.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **2.0.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-alejandro-m-p-git-courer
- Seller: https://agentstack.voostack.com/s/blak0p
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.