{"slug": "i-built-a-local-first-llm-code-reviewer-in-go-here-s-the-entire-pipeline", "title": "I built a local-first LLM code reviewer in Go. Here's the entire pipeline.", "summary": "A developer built CommitBrief, a local-first CLI tool that runs an LLM code review on git diffs before committing. The tool supports providers like Claude, GPT, Gemini, or local Ollama models, and ensures no data leaves the machine unless explicitly chosen. Key engineering includes a hybrid git diff acquisition, multi-layer diff filtering, and a pre-send guard to prevent leaking sensitive files.", "body_md": "**CommitBrief is a local-first CLI that runs an LLM review over your git diff before a teammate — or your future self — sees it.** There's no server and no telemetry; the diff leaves your machine only for the provider *you* chose, and with a local model like Ollama it never leaves at all.\n\nThe interesting engineering isn't \"call an LLM.\" It's everything that has to happen *around* that call so the review stays cheap, safe, and reproducible. Here's the whole path from `commitbrief --staged`\n\nto the findings on your screen.\n\n**TL;DR**\n\n`git diff`\n\nrange) with the provider you pick: Claude, GPT, Gemini, or a fully local Ollama model.**Key facts**\n\n`commitbrief commit`\n\n, and even that only runs one `git commit`\n\nof already-staged changes — it never edits a file.`brew install CommitBrief/tap/commitbrief`\n\n, `scoop install commitbrief`\n\n, or `go install github.com/CommitBrief/commitbrief/cmd/commitbrief@latest`\n\n.Every review walks one linear pipeline. Here it is at altitude before we zoom in:\n\n| Stage | What happens | Why it's here |\n|---|---|---|\n| 1. Resolve context | Walk up for `.git` , merge config (built-in < global < repo), apply env + flags |\nOne deterministic config per run |\n| 2. Load rules |\n`./COMMITBRIEF.md` or the embedded default; validate the output template first |\nFail on a broken template before spending a token |\n| 3. Acquire diff | Hybrid go-git + `exec git` fallback |\nWorktree state is git's, not a reimplementation's |\n| 4. Parse + filter | Three ignore layers, then an optional allowlist | Don't pay to review lock files |\n| 5. Pre-send guard | Refuse to leak `.commitbrief/**` ; scan for secrets |\nThe diff is about to leave the machine |\n| 6. Build prompt | Four XML blocks + an immutability guard | Structured and injection-resistant |\n| 7. Cache lookup | SHA-256 of the exact inputs | A re-run is a disk read, not a bill |\n| 8. Cost preflight | Estimate tokens, warn over a threshold | No surprise spend |\n| 9. Provider call | Structured JSON, or verbatim text for CLI providers | The actual review |\n| 10. Render + gate | Cards / JSON / Markdown, then `--fail-on`\n|\nHuman output or a CI exit code |\n\nFive of these carry most of the weight. Let's take them in order.\n\nYou'd think reading a diff is trivial. It is — until you need staged-vs-unstaged, a worktree comparison, and `git diff main...feature`\n\nto all behave *exactly* like git, on Windows too.\n\nCommitBrief runs a hybrid: a primary `go-git`\n\nimplementation with a `git`\n\nCLI fallback (ADR-0002). Range operations that go-git models cleanly — commit-vs-first-parent, merge-base range diffs, branch diffs — stay in-process. Staged, unstaged, and arbitrary `git diff <args>`\n\npassthrough shell out to `git`\n\nwith `--no-color --no-ext-diff`\n\nfor stable parsing. The CLI stays the source of truth for index and worktree state; reimplementing that plumbing is exactly the kind of subtle drift you don't want under a review tool.\n\n```\ncommitbrief --staged                 # the index\ncommitbrief --unstaged               # the working tree\ncommitbrief diff main...feature      # args forwarded verbatim to git diff\n```\n\nA diff is mostly signal *and* a pile of things no reviewer should read. Filtering is three composed layers (ADR-0006):\n\n`vendor/**`\n\n, `node_modules/**`\n\n, generated code, build artifacts, binaries, IDE/OS noise, and `.commitbrief/cache/**`\n\n.`.commitbriefignore`\n\n`!pattern`\n\nline can re-include something a built-in dropped.`COMMITBRIEF.md`\n\n(\"don't flag generated mocks\"), applied by the model itself.After the ignore layers, `--file`\n\n/ `--dir`\n\napply a narrower allowlist. If nothing survives, the run exits `0`\n\nhaving spent nothing — an empty diff is a success, not an error.\n\nStage 5 is the one I care about most, because it sits on the boundary where your code is about to leave the machine.\n\nTwo checks run before the provider call. First, a guard refuses to quietly ship your own config: if any path in the diff starts with `.commitbrief/`\n\n, it prompts, and auto-aborts when there's no TTY. Second, a secret scanner runs over **added lines only** against eight built-in patterns — AWS access keys, GitHub/GitLab tokens, Anthropic/OpenAI keys, JWTs, Stripe live keys, PEM private keys — and you can add your own through `guard.secret_patterns`\n\n.\n\nOne detail I'm proud of: a match records only `{Line, Patterns}`\n\n— never the matched substring. The scanner that exists to stop a leak can't itself become one through a log line, stderr, or a cache file.\n\nThe bypass policy is deliberate, too. `--allow-secrets`\n\nskips the scan; `--yes`\n\ndoes **not**. Auto-confirming prompts in a pipeline should never silently approve shipping a credential to a third party.\n\nReviewing the same diff twice should be free. The cache key is a SHA-256 over the exact inputs that could change the answer:\n\n```\nsha256( diff \"::\" systemPrompt \"::\" provider \":\" model \":\" lang \":\" schemaVersion [\":ctx\"] [\":mode:\"+mode] )\n```\n\nEvery input earns its place. The fully-assembled system prompt is in the key, so editing `COMMITBRIEF.md`\n\ninvalidates stale reviews. The schema version is in the key, so bumping the output contract invalidates everything at once. `--with-context`\n\nand the commit-message mode each get a suffix so they never collide with a plain review. Entries are written atomically — temp file, `0600`\n\n, then rename — to `.commitbrief/cache/<key>.json`\n\n: one file per response, no index.\n\nThe payoff lands at stage 8. Cost preflight estimates input tokens with a conservative `(len+3)/4`\n\nheuristic, clamps expected output to `[200, 1500]`\n\ntokens, multiplies by a per-model price table, and prompts only when the estimate clears your `cost.warn_threshold_usd`\n\n(default `$0.50`\n\n). A cache hit skips preflight entirely — re-running a review on an unchanged diff costs one disk read.\n\nFor API providers, CommitBrief asks for structured findings and parses them into a fixed contract — `severity`\n\n, `file`\n\n, `line`\n\n, `title`\n\n, `description`\n\n, `suggestion`\n\n— emitted as JSON schema v1. If the model returns something unparseable, it retries once; if it's still bad, it degrades to rendering the raw text as Markdown and prints a warning instead of crashing. CLI-backed providers (`claude-cli`\n\n, `gemini-cli`\n\n, `codex-cli`\n\n) run as read-only subprocesses and stream their text verbatim.\n\nOutput is Cards by default, or:\n\n```\ncommitbrief --json --fail-on=high       # CI gate: exit 1 on any high+ finding\ncommitbrief diff main...feature --markdown -o review.md\n```\n\nExit codes stay simple: `0`\n\nfor success — including a clean review or a `--fail-on`\n\nthreshold that wasn't breached — and `1`\n\nfor any error or a breached gate.\n\nIt's the zeroth reviewer, not a replacement for a human one. It catches the obvious-but-easy-to-miss class: injection, missing nil checks, swallowed errors, a guard clause that's now unreachable. It does not catch intent-level design problems, and it won't tell you whether the feature should exist. That conversation stays with your reviewer.\n\nI won't assert quality at you, either. There's a reproducible eval harness scoring real output against a known-answer corpus — run it yourself:\n\n```\nCOMMITBRIEF_EVAL_PROVIDER=<name> make eval-live\n```\n\nIf you want a second pair of eyes on your diff before anyone else gets one — locally, with the provider you already trust — that's the whole point:\n\n```\ncommitbrief setup     # pick a provider, paste a key, ping it\ncommitbrief init      # optional: write project-specific rules\ngit add .\ncommitbrief --staged\n```\n\nRepo and install instructions: **github.com/CommitBrief/commitbrief**.\n\n*This is part 1 of **Building CommitBrief**. Next: how one Go interface fans out to 10 LLMs across three transport classes — native APIs, OpenAI-compatible endpoints, and subprocess-backed CLIs.*", "url": "https://wpnews.pro/news/i-built-a-local-first-llm-code-reviewer-in-go-here-s-the-entire-pipeline", "canonical_source": "https://dev.to/muhammetsafak/i-built-a-local-first-llm-code-reviewer-in-go-heres-the-entire-pipeline-11g", "published_at": "2026-06-24 04:40:00+00:00", "updated_at": "2026-06-24 04:43:18.546661+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "ai-tools", "generative-ai", "ai-agents"], "entities": ["CommitBrief", "Ollama", "Claude", "GPT", "Gemini", "go-git"], "alternates": {"html": "https://wpnews.pro/news/i-built-a-local-first-llm-code-reviewer-in-go-here-s-the-entire-pipeline", "markdown": "https://wpnews.pro/news/i-built-a-local-first-llm-code-reviewer-in-go-here-s-the-entire-pipeline.md", "text": "https://wpnews.pro/news/i-built-a-local-first-llm-code-reviewer-in-go-here-s-the-entire-pipeline.txt", "jsonld": "https://wpnews.pro/news/i-built-a-local-first-llm-code-reviewer-in-go-here-s-the-entire-pipeline.jsonld"}}