git-courer

问题与 Bug： @blak0p/git-courer/issues · 讨论： @blak0p/git-courer/discussions

文档	描述
Web	访问官方网站
路线图	后续计划与战略愿景
架构	代码库结构、模式以及如何添加功能
故障排查	解决 Ollama 未运行、未检测到 MCP、权限错误等问题
MCP 客户端	支持的全部 5 个 CLI Agent、配置格式和手动设置
配置选项	~/.config/git-courer/config.yaml 和 .git/git-courer/config.json 的全部设置
命令	13 个 MCP 工具的完整参考
参与贡献	环境设置、运行测试以及协作方式

---

git-courer

Git，但 Agent 无法破坏它。

一个 MCP 服务，为 AI Agent 提供完整、安全的 Git 操作界面——不只是提交，而是涵盖全部操作：状态、差异、分支、暂存、历史记录、同步。每次修改都会自动备份。所有操作都不会经过 Bash，因此不会有 git reset --hard 在你不知情的情况下发生。

13 个工具。输入结构化 JSON，输出结构化 JSON。没有分页器、没有文本解析，也不用猜测 Agent 实际对你的仓库做了什么。

---

安装

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

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

Homebrew：

brew install blak0p/tap/git-courer

快速开始

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

重启你的 Agent，然后让它在任意仓库中运行 status。如果返回的是结构化 JSON，而不是原始的 git status 输出，就说明已连接。

诊断与生命周期

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 会按客户端报告：配置路径、是否配置 MCP、是否注入提示词区块、是否安装钩子（yes/no/partial），以及 Claude 内联钩子（仅限 Claude Code）。

---

Agent 如何使用 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 开关

笔记本电脑配置一般且没有 GPU？切换开关后，git-courer 就能在完全不使用大模型的情况下运行。Agent 直接编写消息，Go 仍负责判定类型。

llm:
  enabled: false

不使用大模型时：可通过 message 提交，预览和类型覆盖也可用。发布功能不可用。其他所有功能（状态、差异、分支、会话、备份）均正常工作。

---

与众不同之处

1. 提交类型由 Go 决定，而非大模型

AST 分析加确定性规则。大模型只负责编写消息。如果类型不正确，Agent 可以通过 type= 覆盖。

2. 依赖关系图

提交前，它会绘制变更在整个代码库中的影响范围。提供真实影响分析，而不只是“你改了 3 个文件”。

3. 隔离的工作树

每个 Agent 都有自己的目录和分支，互不干扰。session start 会创建工作树，session finish 会关闭并清理。

4. 将提交作为大模型上下文

包含 WHY/WHAT 的结构化摘要。任何大模型都能直接使用。减少 token，减少幻觉。

5. 自动备份

每次写入操作都会在执行前备份。一条命令即可撤销任何操作。

6. 不受压缩提交影响的发布

提交会存储在 refs/courer/* 中。压缩提交、变基、强制推送——你的变更日志都不会消失。

---

发布内容示例

❯ 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):

这是它生成的更新日志：

v2.8.0 — 本次更新引入了一套使用 git worktrees 的高级会话管理系统，以支持并行工作流，并提升 Agent 执行规则的稳健性。

会话管理与隔离

• 使用 git worktrees 实现隔离会话，防止 Agent 相互干扰；包含完整生命周期管理，包括通过 slug 化标识符进行列出、选择和自动清理。
• 将 sessionGit 封装集成到 MCP 服务中，实现目录自动重定向。

开发者体验与配置

• 优化了黄金规则，现禁止在仓库根目录中工作，以强制执行严格的工作区隔离。
• 自动将提示词规则块注入客户端配置文件。
• 修复了 TUI MCP 设置错误，之前客户端未能正确配置。

系统稳健性与重构

• 重构 Agent 指令结构，移除了不必要的工具映射。
• 使用稳健的基本名称改进文件清理，避免复杂路径导致错误。

---

工作流

会话

session start → 创建隔离的工作树和分支。所有 MCP 工具都会重定向到该目录。session finish 会关闭并清理会话。session discard 会丢弃会话。

提交

PREVIEW → 审查拟议的提交。APPLY → 执行提交。Go 会根据依赖关系图拆分文件，生成原子提交。

PR 审查

pr-review → 测试 + 冲突 + 差异统计 + 分支偏离情况。一条调用即可完成。

发布

git-courer release → 交互式操作。选择标签，引导大模型，预览更新日志并确认。提交保存在 refs/courer/* 中，即使经过压缩合并也会保留。

撤销

backup RESTORE → 撤销任意操作。

---

工具（13）

工具	子命令	功能
status	—	完整的仓库状态：分支、更改、冲突、暂存等。
diff	—	带 AST 标签的差异（NEW_FUNC、MOD_SIG、DEPS、DEL）
commit	PREVIEW → APPLY	三阶段大模型流水线：预览、审查、应用
branch	CREATE / SWITCH / DELETE / RENAME / LIST	分支管理
stage	RM / RESTORE / CLEAN	暂存区控制
stash	SAVE / POP / SHOW	暂存管理
history	LOG / REFLOG / BLAME	历史记录检查
sync	PUSH / PULL / FETCH	远程同步
pr-review	—	一条调用即可完成测试 + 冲突 + 差异统计 + 分支偏离情况
backup	RESTORE / LIST	撤销 amend/merge/rebase
rewrite	AMEND / REVERT / SOFT / HARD	重写历史
integrate	MERGE / UPDATE / PICK / CONTINUE / ABORT	分支集成
session	start / finish / status / select / discard	隔离工作树生命周期管理

完整参考文档及示例：docs/commands.md。

---

支持的客户端

工具	自动配置
OpenCode	✓
Claude Code	✓
Codex	✓
pi	✓
Antigravity	✓

git-courer mcp setup 可一次性完成所有配置。手动设置和配置格式：docs/mcp-clients.md。

---

钩子与黄金规则

mcp setup 不仅会注册 MCP 服务，还会注入防护规则，让 Agent 通过 git-courer 而非原始 Bash 执行 git 操作。

注入黄金规则。 每个客户端的指令文件中都会注入（并保持最新）一个 / 区块（OpenCode 使用 AGENTS.md，Claude Code 使用 CLAUDE.md，Antigravity 使用 GEMINI.md）。该区块包含黄金规则：修改前检查 status，创建 PR 前运行 diff + review，并始终先运行 session start。

钩子。 支持 shell 钩子的客户端会配置 git-courer 子命令：

事件	匹配器	命令	触发时机
PreToolUse	git *	git-courer hook-check	运行任何 Bash git ... 命令之前
SessionStart	—	git-courer session-start-hook	Agent 会话开启时
SubagentStart	—	git-courer subagent-start-hook	子 Agent 启动时
PreInvocation	—	git-courer pre-invocation-hook	每次模型调用之前（Antigravity）

hook-check 会对命令进行分类，并通过 additionalContext 提示使用对应的 git-courer MCP 工具——它绝不会拒绝。会话／子 Agent／调用前钩子会通过 additionalContext 注入黄金规则。Claude Code 使用内联 settings.json 钩子（以 UserPromptSubmit 替代 PreInvocation）；Codex 使用单独的 hooks.json；Antigravity 使用单独的 hooks.json，其中包含 run_command 匹配器，且仅支持 2 个事件。完整参考：docs/hooks.md。

OpenCode 策略。 对于没有 shell 钩子的 OpenCode，mcp setup 会合并到 opencode.json 中：

• permission.bash["git *"] = "ask" — OpenCode 会在运行任何 git Bash 命令之前提示用户，从而引导 Agent 使用 MCP 工具。
• instructions 数组会包含 AGENTS.md 路径（会移除旧版 GIT_COURER.md 条目）。合并操作是幂等的；任何更改之前都会写入 .bak 备份。

运行 git-courer doctor，按客户端验证以上所有配置。

---

常见问题

谁来决定提交类型？ Go。LLM 只负责编写消息。Agent 可以覆盖该类型。

我需要 GPU 或本地 LLM 吗？ 不需要。关闭开关（llm.enabled: false），即可在任何笔记本电脑上运行。Agent 会直接编写消息。

我的代码会离开我的设备吗？ 不会。所有操作都在本地运行——git-courer、Ollama 和你的数据。

不使用 LLM 可以发布吗？ 不可以。发布需要 LLM 来生成变更日志。

如何标记重大变更？ 在正文中使用 feat!: 或 BREAKING CHANGE:。Go 会自动检测。