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.
You open a PR. Ten minutes later a bot comments: 17 findings, 3 blockers, “please address the items below.” The comment has been made, the team Slack got a notification, your teammates are now seeing you as the person with the bad code. Nobody has even started the actual review yet.
It’s that situation I designed CommitBrief to avoid by making it a CLI instead of a GitHub App. This post is not a feature comparison — feature-matrix arguments are the kind everyone wins and nobody learns from. What I want to argue is more fundamental: when the tool fires, and who fires it.
Trigger ownership
A GitHub App’s trigger is fixed: PR opened, push happened, comment written. That trigger isn’t in your control. The App is a sensor wired into a specific point of your workflow; when you reach that point, it goes off.
A CLI’s trigger is you. commitbrief --staged runs when you type it. It doesn’t run when you don’t. That difference looks small but its behavioral consequences are not.
First: the App takes away your “I’m not ready yet” right. You can open a PR in draft mode and keep the branch protected — the App still writes the comment. With the CLI there’s no such problem: if you didn’t run it, it didn’t run.
Second: the App’s output lives in social space. The comment sits in a GitHub thread, visible to everyone. The CLI’s output lives in your terminal. When a junior gets 15 findings on their first PR, the App-shaped version of that experience is public; the CLI-shaped version is private. Same information, very different social weight.
Third: the App’s findings carry a “must do” energy because everyone can see them. The CLI’s findings carry a “worth thinking about” energy because the only audience is you. That psychological difference shapes a junior’s whole relationship with the tool.
Latency
The typical App flow: PR opens, App fires, comment lands in 30–90 seconds. That’s technically fast but semantically late. By the time the PR is open you may have moved on to the next feature; when the finding arrives you have to pay the context-switch tax to get back.
The CLI flow: git add, type commitbrief, 5–8 seconds for the answer. Context is still in your head. The finding lands as “I had thought about this and skipped it,” not as “I wrote that lambda a week ago, why did I do it that way?”
This difference isn’t measured in minutes; it’s measured in your mental mode. The same finding is instructive when you’re in writing mode and annoying when you’re heads-down on something else.
Lock-in
GitHub Apps usually bind to one provider. CommitBrief works with six (Anthropic, OpenAI, Gemini, Ollama, plus the claude-cli and gemini-cli subprocess wrappers that reuse your existing Claude Code or Gemini CLI subscription) and you can change which one for any single run with --provider or the --cli shorthand. On the App side, getting that freedom means installing multiple Apps or accepting whatever providers the App vendor supports.
A subtler lock-in: prompt ownership. The App’s system prompt belongs to the vendor. If you have a complaint, you write to their support. With CommitBrief, COMMITBRIEF.md and OUTPUT.md live inside your repo — you can open them and edit them whenever, without asking anyone.
The freedom isn’t free: you have to write COMMITBRIEF.md. The App says “works out of the box”; the CLI says “works better when you configure it.” The previous post lays out the anatomy of that rules file — start there if you haven’t.
Don’t fall into the feature-matrix trap
The classic mistake when picking a code review tool is to build a feature matrix. “X has streaming, Y doesn’t. X has markdown output, Y has JSON too…” That list goes nowhere because every tool eventually adds every feature. The real choice isn’t in the features; it’s in the philosophy.
When you pick a GitHub App, you’re picking: the tool fires when the system is ready, not when you are. It runs in a social space. Provider and prompt belong to the vendor.
When you pick a CLI, you’re picking: the tool fires when you decide. It runs in your private space. Provider and prompt belong to you.
Which one fits depends on your team’s maturity, the project’s nature, the privacy demands of your sector. A large, distributed, junior-heavy team might experience the App’s social pressure as a feature — everyone reads the bot, nobody takes it personally. A small, senior-heavy, fast-iterating team usually finds the CLI’s silence more productive.
One concrete piece of advice, regardless of which you pick: write down the reason in a paragraph. “We chose the bot because X” or “we chose the CLI because Y.” That paragraph will remind both your team and your future self what you weighed at decision time.
As the manifesto put it, CommitBrief’s position is the zeroth reviewer. A CLI sits naturally in that position; a GitHub App usually lands in the second-reviewer slot. The difference between those two positions isn’t only timing — it’s the social arena and the freedom you keep over your own tools.