Issues & Bugs: @blak0p/git-courer/issues · Discussions: @blak0p/git-courer/discussions
| Doc | Description |
|---|---|
| Architecture | Codebase structure, patterns, and how to add features |
| Troubleshooting | Fix: Ollama not running, MCP not detected, permission errors |
| MCP Clients | All 14 supported clients, config formats, manual setup |
| Config Options | All ~/.config/git-courer/config.yaml and .git-courer/config.json settings |
| Commands | Complete reference for all 22 MCP tools |
| Models Guide | Tested models, token usage, and which one to pick |
| Contributing | Setup, running tests, and how to collaborate |
go install github.com/blak0p/git-courer@latestcurl -fsSL https://raw.githubusercontent.com/blak0p/git-courer/main/scripts/install.sh | shThat's it. It installs the binary and auto-configures every AI tool it detects on your machine.
Requirements: Git · llm local
Homebrew (macOS / Linux):
brew install blak0p/tap/git-courerWindows
# Windows (PowerShell)
irm https://github.com/blak0p/git-courer/releases/latest/download/git-courer_windows_amd64.tar.gz | tar -xz -o git-courer.exe
.\git-courer.exe setupManual install:
# macOS / Linux
curl -fsSL https://github.com/blak0p/git-courer/releases/latest/download/git-courer_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m).tar.gz | tar -xz -C /usr/local/bin git-courer
chmod +x /usr/local/bin/git-courer
git-courer setupThe only MCP git server that understands your code before it commits.
Most tools wrap git diff | llm "write a commit". git-courer does something different: it parses your AST, builds a dependency graph, classifies the change type in Go without touching the LLM, and only calls the model to write the human-readable message.
One staged area = one commit. Always.
git-courer uses go-enry and go-tree-sitter to parse your AST and apply deterministic rules — new public function, modified signature, deleted symbol, breaking change. The LLM writes the message, not the decision.
Before committing, git-courer builds a graph of what your staged files affect across the codebase. Real scope, not just which files were touched.
Go and the local LLM handle everything they can. Your cloud LLM receives structured commit context — WHY + WHAT — instead of raw code.
A git-courer commit is a compressed, structured summary any LLM can consume directly. Better input, fewer tokens, fewer hallucinations.
Every write operation creates a backup before executing. One command undoes anything.
Why install one tool for commits, another for releases, another for PR checks? git-courer covers the full cycle:
Read: status, diff, history, blame, pr-review
Write: commit, amend, revert, stage, reset, stash
Branch: branch, merge, rebase, cherry-pick, tag
Utility: sync, backup, undo, remotes, config
All returning structured JSON. No pager hangs, no text parsing, no extra tools.
Preview the change → review proposed commits → apply. git-courer splits your staged files into atomic commits by dependency graph automatically.
Call pr-review — a pre-PR gate that runs in one shot:
- Tests — runs
test_commandfrom.git-courer/config.json(e.g.go test ./...) - Conflicts — detects merge conflicts with the target branch and returns AST-annotated hunks (
[NEW_FUNC],[MOD_SIG ⚠BREAKING]) - Diff stats — files changed, additions, deletions
- Divergence — ahead/behind count, mergeable status
If it's not green, you don't merge. Set test_command via git-config SET_TEST_COMMAND or edit .git-courer/config.json directly.
Run git-courer release. The CLI reads commits from .git-courer/commits.json (captured during each git-commit APPLY on this branch) and groups them by the areas defined in .git-courer/config.json. If the branch store is empty, it falls back to git log since the last tag. Go calculates the version bump; the local LLM writes the human-readable changelog per area.
Every destructive operation has an automatic backup. One command restores the previous state.
You: "commit my changes"
↓
AI delegates to git-courer (via MCP)
↓
Go reads AST + dependency graph → classifies type deterministically
↓
Local LLM writes the human-readable message from the annotated diff
↓
Security scan (5 layers) → auto-backup → commit
↓
"✓ feat(auth): add OAuth2 token refresh"
For the full list of tools: docs/commands.md
For workflow details: docs/workflows.md
| Tool | Auto-configured |
|---|---|
| Claude Code | ✓ |
| Cursor | ✓ |
| Windsurf | ✓ |
| OpenCode | ✓ |
| Cline | ✓ |
| Roo Code | ✓ |
| VS Code | ✓ |
| Claude Desktop | ✓ macOS/Win only |
| Continue | ✓ |
| Zed | ✓ |
| Codex | ✓ |
| Gemini CLI | ✓ |
| pi | ✓ |
| Antigravity | ✓ |
Run git-courer mcp setup to configure all detected tools at once, or git-courer mcp setup <client> for a specific one.
Run git-courer with no arguments to launch the interactive installer:
The TUI walks you through 4 steps:
- MCP Configuration — select which AI tools to configure (auto-detects installed clients)
- General Settings — configure your LLM backend, model, and project context
- Review — preview your config before saving
- Finish — config saved to
~/.config/git-courer/config.yaml
You can also update the binary or uninstall directly from the menu. Navigation: j/k or arrow keys, esc to go back.
git-courer runs as an interactive TUI when launched without arguments. It also provides MCP server and management commands:
| Command | Description |
|---|---|
git-courer |
Launch interactive TUI (requires terminal) |
git-courer mcp |
Run MCP server |
git-courer mcp setup |
Configure all detected AI tools |
git-courer mcp setup <client> |
Configure a specific tool (e.g. cursor) |
git-courer release |
Automated semver releases and changelogs (CLI only) |
git-courer remove |
Remove git-courer from the current project |
git-courer uninstall |
Uninstall the binary globally |
git-courer update |
Update to the latest version |
git-courer version |
Show current version |
For the 22 MCP tools and their arguments, see docs/commands.md.
git-courer uses two config levels:
Global (~/.config/git-courer/config.yaml) — personal settings: LLM backend, model.
Per-project (.git-courer/config.json) — committable, shared with team. Stores description, areas, test_command, excluded. Better results = edit this file per project.
All options: docs/config.md
When you call git-commit PREVIEW, the server may return immediately (FAST) or start a background job (SLOW). In the SLOW case:
- PREVIEW returns
{status:"processing", job_id} - The agent must call
git-commit STATUSwith thatjob_idto poll - When STATUS returns
{status:"done"}, the plan is ready - Then call
git-commit APPLYwith the samejob_id
The agent continues working — it does NOT block waiting for the job.
Every successful commit via git-commit APPLY is captured to .git-courer/commits.json (branch-scoped under .git-courer/branches/<branch>/commits.json). When you later run git-courer release, the CLI reads those captured commits — grouped by the areas defined in .git-courer/config.json — to generate the changelog. No re-parsing git log.
Why this matters: Git history is frequently rewritten — PR squashes, rebases, force-pushes — destroying the real commit narrative. The CommitStore preserves every commit message as it was written, independently of what happens on the remote. Your release changelog survives git log being flattened into a single squashed commit. This is local documentation that outlives git history rewriting.
Having issues? Check docs/troubleshooting.md for:
- Ollama not running / model not configured
- MCP not detected by your AI tool
- Permission errors during install
- Secrets detected in commits (false positives)
MCP config file locations: docs/mcp-clients.md
Who decides the commit type? Go, via AST analysis. The LLM only writes the human-readable message.
Do I need Ollama? You need some LLM backend. Ollama is the recommended default, but git-courer works with any OpenAI-compatible server: LM Studio, vLLM, LocalAI, or a custom endpoint. Without a configured backend, all AI operations (commits, releases, branch names, security auditor) fail. Basic git reads (status, diff, log) still work.
Is my code sent anywhere? No. Everything runs on your machine — git-courer, Ollama, your data.
Who decides the version number in a release?
Go, not Ollama. Version is calculated from commit types (feat: → minor, feat!: → major). Ollama only writes the human changelog.
My tool isn't listed. Open an issue: @blak0p/git-courer/issues. If it supports MCP, adding it is usually a few lines.
How do I mark a breaking change?
Use ! after the commit type (feat!:) or include BREAKING CHANGE: in the body. git-courer picks this up automatically for version bumping and changelog generation.
Want to collaborate? Here's everything you need:
Read docs/architecture.md for:
- Directory structure and tech stack
- Hexagonal architecture patterns
- Key packages and their responsibilities
- How to add a new feature
- Testing approach
Found a bug? Open an issue: @blak0p/git-courer/issues
Include:
- Your OS and git-courer version (
git-courer version) - AI tool you're using (Claude Code, Cursor, etc.)
- Steps to reproduce
- Relevant logs or error messages
- Read the docs: Start with docs/architecture.md and CONTRIBUTING.md
- Pick an issue: Check @blak0p/git-courer/issues for
good first issuelabels - Discuss: Use @blak0p/git-courer/discussions for questions or feature ideas
- Submit PR: Follow conventional commits (
feat:,fix:,chore:)
If your AI tool supports MCP but isn't listed, adding it is usually 5 lines of code in internal/installer/mcp_config.go. See docs/mcp-clients.md for the format.