Blog
Releases, design notes, and short reads on local-first developer tooling.
/blog/rss.xml`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.
Three flags into one subcommand: the `commitbrief diff` collapse and what it taught me about CLI surface area.
v0.9.0 retired --commit, --branch, and --pull-request in favour of a single 'diff' subcommand that pass-throughs to git diff. A note on why reinventing what git already does is the wrong shape.
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.
v1.0 is an API freeze: what `schema: v1` actually promises.
v1.0 isn't just a number. CLI flag surface, JSON schema v1, and the COMMITBRIEF.md / OUTPUT.md formats are under strict semver from here on. Here's what that buys you, and what it stops me from doing.
Why a CLI, not a GitHub App.
On trigger ownership when picking a code review tool. The design thinking behind CommitBrief as a CLI — and when that's the wrong choice.
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.
LLM code review doesn't replace human review. It multiplies it.
The position paper that ships with v1.0 — what an LLM catches, what it doesn't, and why a human reviewer's job changes shape rather than disappearing.