{
  "markdown": "<!-- mcp-name: io.github.blak0p/git-courer -->\n<!-- markdownlint-disable MD041 -->\n<img width=\"1259\" height=\"619\" alt=\"Gemini_Generated_Image_g9lcw7g9lc\" src=\"https://github.com/user-attachments/assets/2e9c0e64-b0de-4b83-9159-3a5906f9f3f4\" />\n\n<p align=\"center\">\n  <a href=\"https://github.com/blak0p/git-courer/releases/latest\">\n    <img src=\"https://img.shields.io/github/v/release/blak0p/git-courer?color=%2300BFFF&label=latest\" alt=\"Release\">\n  </a>\n  <a href=\"https://github.com/blak0p/git-courer/actions\">\n    <img src=\"https://img.shields.io/github/actions/workflow/status/blak0p/git-courer/test.yml?branch=main\" alt=\"Build\">\n  </a>\n  <a href=\"https://github.com/blak0p/git-courer/blob/main/LICENSE\">\n    <img src=\"https://img.shields.io/github/license/blak0p/git-courer\" alt=\"MIT License\">\n  </a>\n</p>\n\n> **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)\n\n| Doc | Description |\n| --- | --- |\n| [Web](https://blak0p.github.io/git-courer/) | Visit the official website |\n| [Roadmap](docs/roadmap.md) | What's coming next and the strategic vision |\n| [Architecture](docs/architecture.md) | Codebase structure, patterns, and how to add features |\n| [Troubleshooting](docs/troubleshooting.md) | Fix: Ollama not running, MCP not detected, permission errors |\n| [MCP Clients](docs/mcp-clients.md) | All 5 supported CLI agents, config formats, manual setup |\n| [Config Options](docs/config.md) | All `~/.config/git-courer/config.yaml` and `.git/git-courer/config.json` settings |\n| [Commands](docs/commands.md) | Complete reference for all 13 MCP tools |\n| [Contributing](docs/contributing.md) | Setup, running tests, and how to collaborate |\n\n---\n\n# git-courer\n\n**Git, but agents can't break it.**\n\nAn 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.\n\n13 tools. Structured JSON in, structured JSON out. No pagers, no text parsing, no guessing what the agent actually did to your repo.\n\n---\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/blak0p/git-courer/main/scripts/install.sh | sh\n```\n\n```go\ngo install github.com/blak0p/git-courer@latest\n```\n\n**Homebrew:**\n```bash\nbrew install blak0p/tap/git-courer\n```\n\n### Quick start\n\n```bash\ngit-courer mcp setup     # auto-configures your agent (OpenCode, Claude Code, Codex, pi, Antigravity)\n```\n\nRestart 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.\n\n### Diagnostics & lifecycle\n\n```bash\ngit-courer doctor              # read-only health report for every detected MCP client\ngit-courer hook-check \"git status\"   # classify a shell command (agent hook; never denies)\ngit-courer init                # TUI wizard to create/update project config\ngit-courer version --predict   # predict next release tag from conventional commits\ngit-courer remove              # remove project-level config (keeps the binary)\ngit-courer update              # self-update to the latest release + reconfigure MCP\n```\n\n`doctor` reports per client: config path, MCP configured, prompt block injected, hooks installed (`yes`/`no`/`partial`), and Claude inline hooks (Claude Code only).\n\n---\n\n## How an agent works with git-courer\n\n```\nAgent receives a task\n        ↓\nsession start → creates isolated worktree + branch\n        ↓\nAll MCP tools (diff, status, commit, branch...)\nautomatically redirect to that worktree\n        ↓\ncommit PREVIEW → Go parses AST + dependency graph\n                  classifies type (feat/fix/breaking...)\n        ↓\ncommit APPLY → two modes depending on config:\n\n  ┌─ WITH LLM ──────────────────────────────┐\n  │  Local LLM writes the WHY/WHAT message │\n  │  Go decides the type (agent can         │\n  │  override with type= if wrong)          │\n  └─────────────────────────────────────────┘\n\n  ┌─ WITHOUT LLM (toggle off) ─────────────┐\n  │  Perfect for modest laptops, no GPU    │\n  │  Agent writes the message directly     │\n  │  Preview, apply, and type override     │\n  │  still work                             │\n  └─────────────────────────────────────────┘\n\n        ↓\nSecurity checks → auto backup → commit\n        ↓\n\"✓ fix: refactor session finish workflow to stop automatic merging\n\n    WHY\n    The previous implementation automatically attempted to merge session\n    branches into the base branch, which forced a specific integration\n    strategy and required managing two different git repositories.\n\n    WHAT\n    * Removed automated merge logic and the dependency on a second Git\n      instance (mainGit) in the session handler and workflow.\n    * Updated cleanup to remove worktrees while leaving session branches\n      alive for manual integration.\n    * Switched to PreviewLight validation to prevent data loss from\n      uncommitted changes.\n    * Updated FinishResult to include BranchAlive status.\"\n\nsession finish → closes session + cleans up worktree\n```\n\n---\n\n## LLM Toggle\n\nModest 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.\n\n```yaml\nllm:\n  enabled: false\n```\n\nWithout LLM: commit with `message`, preview and type override work. Release is not available. Everything else (status, diff, branch, session, backup) works normally.\n\n---\n\n## Why it's different\n\n### 1. Commit type decided by Go, not the LLM\nAST analysis + deterministic rules. The LLM only writes the message. If the type is wrong, the agent overrides it with `type=`.\n\n### 2. Dependency graph\nBefore committing, it maps what your changes affect across the entire codebase. Real impact, not just \"you touched 3 files\".\n\n### 3. Isolated worktrees\nEach agent gets its own directory and branch. No stepping on each other. `session start` creates, `session finish` closes and cleans up.\n\n### 4. Commits as LLM context\nStructured summary with WHY/WHAT. Any LLM consumes it directly. Fewer tokens, fewer hallucinations.\n\n### 5. Automatic backup\nEvery write operation backs up before executing. One command undoes anything.\n\n### 6. Releases that survive squashes\nCommits are stored in `refs/courer/*`. Squash, rebase, force push — your changelog doesn't disappear.\n\n---\n\n## What a release looks like\n\n```\n❯ git-courer release\n\nTag? [v3.0.0]:\nAdd guidance for changelog generation? (y/N): n\n\n   📦 Release Preview\n\n  Tag: v3.0.0    Version Bump: major\n\n  --- Changelog ---\n  ...\n\nApply? (y/N/r/e):\n```\n\nThis is the changelog it writes:\n\n> **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.\n>\n> **Session Management and Isolation**\n> - 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.\n> - Integrated sessionGit wrapper into the MCP server for automatic directory redirection.\n>\n> **Developer Experience and Configuration**\n> - Refined golden rules, now prohibiting work in the repository root to enforce strict workspace isolation.\n> - Automatic injection of prompt rule blocks into client configuration files.\n> - Fixed TUI MCP setup bug where clients were not configured correctly.\n>\n> **System Robustness and Refactoring**\n> - Refactored agent instruction structure, removing unnecessary tool maps.\n> - Improved file cleanup using robust base names to prevent errors with complex paths.\n\n---\n\n## Workflows\n\n### Session\n`session start` → isolated worktree + branch. All MCP tools redirect there. `session finish` closes and cleans up. `session discard` throws it away.\n\n### Commit\n`PREVIEW` → review proposed commits. `APPLY` → executes them. Go splits files by dependency graph into atomic commits.\n\n### PR Review\n`pr-review` → tests + conflicts + diff stats + divergence. All in one call.\n\n### Release\n`git-courer release` → interactive. Pick the tag, guide the LLM, preview the changelog, confirm. Commits live in `refs/courer/*` — they survive squashes.\n\n### Undo\n`backup RESTORE` → undoes any operation.\n\n---\n\n## Tools (13)\n\n| Tool | Subcommands | What it does |\n| --- | --- | --- |\n| `status` | — | Full repo state: branch, changes, conflicts, stash, etc. |\n| `diff` | — | Diff with AST tags (`NEW_FUNC`, `MOD_SIG`, `DEPS`, `DEL`) |\n| `commit` | `PREVIEW` → `APPLY` | 3-phase LLM pipeline: preview, review, apply |\n| `branch` | `CREATE` / `SWITCH` / `DELETE` / `RENAME` / `LIST` | Branch management |\n| `stage` | `RM` / `RESTORE` / `CLEAN` | Staging area control |\n| `stash` | `SAVE` / `POP` / `SHOW` | Stash management |\n| `history` | `LOG` / `REFLOG` / `BLAME` | History inspection |\n| `sync` | `PUSH` / `PULL` / `FETCH` | Remote sync |\n| `pr-review` | — | Tests + conflicts + diff stats + divergence in one call |\n| `backup` | `RESTORE` / `LIST` | Undo amend/merge/rebase |\n| `rewrite` | `AMEND` / `REVERT` / `SOFT` / `HARD` | History rewriting |\n| `integrate` | `MERGE` / `UPDATE` / `PICK` / `CONTINUE` / `ABORT` | Branch integration |\n| `session` | `start` / `finish` / `status` / `select` / `discard` | Isolated worktree lifecycle |\n\nFull reference with examples: [docs/commands.md](docs/commands.md).\n\n---\n\n## Supported clients\n\n| Tool | Auto-configured |\n|------|----------------|\n| OpenCode | ✓ |\n| Claude Code | ✓ |\n| Codex | ✓ |\n| pi | ✓ |\n| Antigravity | ✓ |\n\n`git-courer mcp setup` configures all at once. Manual setup and config formats: [docs/mcp-clients.md](docs/mcp-clients.md).\n\n---\n\n## Hooks & golden rules\n\n`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.\n\n**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.\n\n**Hooks.** Clients that support shell hooks get entries wired to git-courer subcommands:\n\n| Event | Matcher | Command | Fires when |\n|-------|---------|---------|------------|\n| PreToolUse | `git *` | `git-courer hook-check` | Before any Bash `git ...` run |\n| SessionStart | — | `git-courer session-start-hook` | Agent session opens |\n| SubagentStart | — | `git-courer subagent-start-hook` | A sub-agent starts |\n| PreInvocation | — | `git-courer pre-invocation-hook` | Before each model call (Antigravity) |\n\n`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).\n\n**OpenCode policy.** For OpenCode (which has no shell hooks), `mcp setup` merges into `opencode.json`:\n- `permission.bash[\"git *\"] = \"ask\"` — OpenCode prompts the user before any `git` Bash command, so the agent is nudged toward the MCP tool.\n- `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.\n\nRun `git-courer doctor` to verify all of the above per client.\n\n---\n\n## FAQ\n\n**Who decides the commit type?**\nGo. The LLM only writes the message. The agent can override it.\n\n**Do I need a GPU or local LLM?**\nNo. Flip the toggle (`llm.enabled: false`) and it runs on any laptop. The agent writes messages directly.\n\n**Does my code leave my machine?**\nNo. Everything runs locally — git-courer, Ollama, your data.\n\n**What about release without an LLM?**\nNot available. Release needs an LLM for the changelog.\n\n**How do I mark a breaking change?**\n`feat!:` or `BREAKING CHANGE:` in the body. Go detects it automatically.\n",
  "bytes": 12391,
  "sha": "856562c17e2f17c04423837e3b061d9895e097b5147d52cf6f89157d68c3338e",
  "repo_slug": "alejandro-m-p/git-courer",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_alejandro_m_p_git_courer_ad00ffd7/readme"
}