git-courer

問題とバグ：@blak0p/git-courer/issues · ディスカッション：@blak0p/git-courer/discussions

ドキュメント	説明
ウェブサイト	公式ウェブサイトを見る
ロードマップ	今後の予定と戦略的ビジョン
アーキテクチャ	コードベースの構造、パターン、機能の追加方法
トラブルシューティング	Ollama が起動しない、MCP が検出されない、権限エラーを解決
MCP クライアント	サポート対象の 5 つの CLI エージェント、設定形式、手動セットアップ
設定オプション	~/.config/git-courer/config.yaml と .git/git-courer/config.json のすべての設定
コマンド	13 個すべての MCP ツールの完全なリファレンス
コントリビューション	セットアップ、テストの実行、コラボレーションの方法

---

git-courer

Git を、エージェントが壊せないように。

AI エージェントに Git の全機能を安全に操作できるインターフェースを提供する MCP サーバーです。コミットだけでなく、ステータス、差分、ブランチ、スタッシュ、履歴、同期まで、あらゆる操作をカバーします。変更を加える操作はすべて、自動的にバックアップされます。Bash を経由することはないため、知らないうちに git reset --hard が実行されることもありません。

13 個のツール。構造化 JSON を入力し、構造化 JSON を出力します。ページャーもテキスト解析も不要で、エージェントがリポジトリに対して実際に行ったことを推測する必要もありません。

---

インストール

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)

エージェントを再起動し、任意のリポジトリで status を実行するよう指示してください。生の git status 出力ではなく構造化 JSON が返ってくれば、接続できています。

診断とライフサイクル

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 のみ）を報告します。

---

エージェントによる 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 のない控えめなノート PC をお使いですか？切り替えると、git-courer は LLM なしで完全に動作します。エージェントがメッセージを直接作成し、種類の判定は引き続き Go が行います。

llm:
  enabled: false

LLM なしの場合、message を指定したコミット、プレビュー、種類の上書きが利用できます。リリースは利用できません。それ以外（ステータス、差分、ブランチ、セッション、バックアップ）は通常どおり動作します。

---

ほかとの違い

1. コミットの種類は LLM ではなく Go が判定

AST 解析と決定論的なルールを使用します。LLM が作成するのはメッセージだけです。種類が間違っている場合は、エージェントが type= で上書きします。

2. 依存関係グラフ

コミットの前に、コードベース全体にわたって変更の影響を受ける箇所をマッピングします。実際の影響を把握でき、「3 ファイルを変更した」だけにとどまりません。

3. 分離されたワークツリー

各エージェントに専用のディレクトリとブランチが割り当てられます。互いの作業に干渉しません。session start で作成し、session finish で終了してクリーンアップします。

4. LLM のコンテキストとしてのコミット

WHY／WHAT を含む構造化された要約です。どの LLM もそのまま利用できます。トークンも幻覚も減らせます。

5. 自動バックアップ

書き込み操作の前に、必ずバックアップを作成します。どの操作も 1 つのコマンドで取り消せます。

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 を利用した高度なセッション管理システムを導入し、並列ワークフローを可能にするとともに、エージェント実行ルールの堅牢性を向上させます。

セッション管理と分離

• エージェント同士の干渉を防ぐため、git worktrees を利用した分離セッションを実装しました。スラッグ化された識別子による一覧表示、選択、自動クリーンアップを含む、ライフサイクル全体に対応しています。
• MCP サーバーに sessionGit ラッパーを統合し、ディレクトリの自動リダイレクトに対応しました。

開発者エクスペリエンスと設定

• ゴールデンルールを見直し、厳格なワークスペース分離を徹底するため、リポジトリのルートでの作業を禁止しました。
• クライアント設定ファイルにプロンプトルールブロックを自動挿入します。
• クライアントが正しく設定されない TUI MCP のセットアップのバグを修正しました。

システムの堅牢性とリファクタリング

• エージェントの指示構造をリファクタリングし、不要なツールマップを削除しました。
• 堅牢なベース名を使用してファイルのクリーンアップを改善し、複雑なパスでのエラーを防ぎます。

---

ワークフロー

セッション

session start → 分離された worktree とブランチを作成します。すべての MCP ツールはそこにリダイレクトされます。session finish で終了してクリーンアップします。session discard で破棄します。

コミット

PREVIEW → 提案されたコミットを確認します。APPLY → 実行します。Go は依存関係グラフに基づいてファイルを分割し、アトミックなコミットを作成します。

PR レビュー

pr-review → テスト、競合、差分統計、分岐状況をまとめて確認します。1 回の呼び出しで完了します。

リリース

git-courer release → 対話形式で進めます。タグを選択し、LLM に指示して、変更履歴をプレビューし、確定します。コミットは refs/courer/* に保存されるため、スカッシュ後も保持されます。

元に戻す

backup RESTORE → どの操作も元に戻せます。

---

ツール（13）

ツール	サブコマンド	機能
status	—	リポジトリの全状態：ブランチ、変更、競合、スタッシュなど
diff	—	AST タグ（NEW_FUNC、MOD_SIG、DEPS、DEL）付きの差分
commit	PREVIEW → APPLY	3 段階の LLM パイプライン：プレビュー、レビュー、適用
branch	CREATE / SWITCH / DELETE / RENAME / LIST	ブランチ管理
stage	RM / RESTORE / CLEAN	ステージングエリアの操作
stash	SAVE / POP / SHOW	スタッシュ管理
history	LOG / REFLOG / BLAME	履歴の確認
sync	PUSH / PULL / FETCH	リモートとの同期
pr-review	—	テスト、競合、差分統計、分岐状況を 1 回の呼び出しで確認
backup	RESTORE / LIST	amend／merge／rebase を元に戻します
rewrite	AMEND / REVERT / SOFT / HARD	履歴の書き換え
integrate	MERGE / UPDATE / PICK / CONTINUE / ABORT	ブランチの統合
session	start / finish / status / select / discard	分離 worktree のライフサイクル管理

使用例付きの完全なリファレンス：docs/commands.md。

---

対応クライアント

ツール	自動設定
OpenCode	✓
Claude Code	✓
Codex	✓
pi	✓
Antigravity	✓

git-courer mcp setup ですべてを一括設定できます。手動セットアップと設定形式については、docs/mcp-clients.md を参照してください。

---

フックと基本ルール

mcp setup は MCP サーバーを登録するだけでなく、ガードレールも追加し、エージェントが生の Bash ではなく git-courer 経由で git 操作を行うようにします。

基本ルールの注入。 / ブロックが各クライアントの指示ファイル（OpenCode の場合は AGENTS.md、Claude Code の場合は CLAUDE.md、Antigravity の場合は GEMINI.md）に注入され、最新の状態に保たれます。このブロックには基本ルールが記載されています。変更を加える前に status を確認すること、PR の前に diff と review を実行すること、必ず最初に session start を実行することです。

フック。 シェルフックに対応するクライアントでは、git-courer のサブコマンドにフックが設定されます。

イベント	マッチャー	コマンド	実行タイミング
PreToolUse	git *	git-courer hook-check	Bash の git ... を実行する前
SessionStart	—	git-courer session-start-hook	エージェントのセッション開始時
SubagentStart	—	git-courer subagent-start-hook	サブエージェントの開始時
PreInvocation	—	git-courer pre-invocation-hook	各モデル呼び出しの前（Antigravity）

hook-check はコマンドを分類し、対応する git-courer MCP ツールを提案する additionalContext を出力します。拒否することはありません。セッション／サブエージェント／呼び出し前の各フックは、基本ルールを additionalContext として注入します。Claude Code は settings.json 内のインラインフック（PreInvocation の代わりに UserPromptSubmit）を使用します。Codex は個別の hooks.json を使用します。Antigravity は run_command マッチャーと 2 つのイベントのみを含む個別の hooks.json を使用します。詳細なリファレンスは docs/hooks.md をご覧ください。

OpenCode のポリシー。 シェルフックがない OpenCode の場合、mcp setup は opencode.json に次の内容をマージします。

• permission.bash["git *"] = "ask" — OpenCode は git の Bash コマンドを実行する前にユーザーに確認するため、エージェントは MCP ツールを使うよう促されます。
• instructions 配列には AGENTS.md のパスが含まれます（以前の GIT_COURER.md の項目は削除されます）。マージは冪等です。変更前に .bak バックアップが作成されます。

git-courer doctor を実行すると、上記の設定をクライアントごとに確認できます。

---

FAQ

コミットの種類は誰が決めますか？ Go です。LLM はメッセージのみを作成します。エージェントが上書きすることもできます。

GPU やローカル LLM は必要ですか？ いいえ。切り替え設定（llm.enabled: false）をオフにすると、どのノート PC でも動作します。エージェントがメッセージを直接作成します。

コードはマシンの外に送信されますか？ いいえ。git-courer、Ollama、データはすべてローカルで動作します。

LLM なしでリリースできますか？ できません。変更履歴の作成に LLM が必要です。

破壊的変更はどのように示しますか？ 本文に feat!: または BREAKING CHANGE: を記載します。Go が自動的に検出します。