CommitBrief
The project
Posts published under the project name rather than a personal byline: release notes, design decisions recorded as they were made, and walkthroughs of how a shipped feature actually behaves. CommitBrief is an open-source CLI under GPL-3.0-or-later, maintained by Muhammet Şafak. Everything documented in these posts is verifiable against the source.
16 posts
When the model won't return valid JSON: a recovery ladder, not a blind retry.
Prompt-only models break the JSON contract in three predictable ways — fenced JSON, prose, and truncation. How CommitBrief v1.13.0 recovers each one with fence salvage, a failure-mode-specific repair prompt, and a graceful degrade.
Multi-provider as an architecture decision: why locking to one LLM is a reliability problem.
Anthropic, OpenAI, Gemini, Ollama, claude-cli, gemini-cli — the provider abstraction in v1.0 and the manual-switch posture that keeps single-provider outages from breaking your workflow.
Onboarding through review rules: nobody reads CONTRIBUTING.md, but everyone reads their PR feedback.
A `COMMITBRIEF.md` your team has actually written becomes the most effective onboarding document for new hires — because it shows up where they're already paying attention.
Blocking vs. nitpicking: shaping review tone with `OUTPUT.md`.
Encoding team norms into the review output. Severity scales, finding format, what gets surfaced and what gets quietly suppressed.
Signal from noise: the three-layer filter that keeps reviews readable.
Built-in defaults, `.commitbriefignore`, and `COMMITBRIEF.md` semantic filtering — how they compose, last-wins semantics, and how negative patterns revert a default.
Your diff should never leave your machine: the Ollama path for air-gapped repos.
How CommitBrief runs LLM code review with zero network egress. For SOC2-restricted repos, defense work, fintech and healthcare codebases — and an honest look at the quality trade-off.
v1.13 → v1.15: replacing inference with evidence
Three releases that look unrelated — a JSON parser change, one config key, four new commands — and the single direction underneath them: every claim CommitBrief makes should be something it can show you, and the ones that don't need a model shouldn't call one.
`commitbrief compress`: an LLM rewriting another LLM's system prompt — and the discipline that keeps it safe.
Three compression levels, atomic apply, automatic backup, and the rule that refuses to shrink your rules file if the result isn't actually smaller.
`commitbrief doctor`: the diagnostic I wish more CLIs shipped.
Eight checks against the resolved environment, plus a per-provider connection ping — what doctor inspects, why warnings are non-blocking by design, and the CI pattern that gates merges on a clean health check.
How a single JSON schema survives four very different LLM providers.
Anthropic tools mode, OpenAI strict response_format, Gemini ResponseSchema, Ollama format:json — four mechanisms, one contract. How CommitBrief's findings schema v1 stays stable across them, and the retry-once-then-degrade fallback for when it doesn't.
Subprocess providers: reusing a subscription you're already paying for.
How claude-cli and gemini-cli wrap a host CLI as a subprocess instead of calling an API, what they give up to do that, and why stdin transport matters when the diff gets large.
Hooks that survive Tower, GitHub Desktop, and JetBrains.
Why git hooks installed from the command line silently fail when you commit from a GUI client — and the absolute-path embedding trick that makes commitbrief install-hook just work everywhere.
`--fail-on`: turning an LLM review into a CI gate without locking yourself in.
How severity-based exit codes work, why graceful degrade deliberately skips the gate, and what 'fail at critical or worse' actually means inside your pipeline.
Three guards before any token is spent.
The secret scanner, the cost preflight, and the .commitbrief/ guard — three pre-send checks that fire before CommitBrief talks to a provider, and why --yes deliberately doesn't bypass two of them anymore.
Anatomy of a `COMMITBRIEF.md`: turning team tribal knowledge into a system prompt.
What a good rules file looks like, what doesn't belong in it, and why the LLM's effectiveness as a zeroth reviewer depends on the file being written well.
Review before the push: why the strongest review window is right before `git commit -m`.
Why CommitBrief defaults to --staged scope. Reviewing a change that hasn't entered history yet is always cheaper than patching it with a force-push.