gitwarren-app

<img src="src/renderer/src/assets/logo.png" alt="" width="112" height="112" />

# GitWarren

**[gitwarren.com](https://gitwarren.com)** — the official site, with downloads for
macOS, Windows and Linux. On macOS there is also a Homebrew cask:

```bash
brew install --cask klarluft/tap/gitwarren
```

There is a command line too, which serves the same review UI in a browser
instead of an Electron window — for a machine that will not have the app on it,
or one with no screen at all:

```bash
brew install klarluft/tap/gitwarren-cli               # macOS and Linux, brings its own Node
curl -fsSL https://gitwarren.com/install.sh | sh      # macOS and Linux, no Homebrew needed
npx gitwarren serve                                   # anywhere Node 22.14+ is, including Windows
```

Then `gitwarren serve --open`. See
[The `gitwarren` command line](#the-gitwarren-command-line).

If you arrive from a coding agent, start there instead. The plugin brings the
MCP server and a note that teaches the agent when to open a review and how to
answer your comments:

```bash
/plugin marketplace add klarluft/gitwarren-app       # Claude Code, then:
/plugin install gitwarren@gitwarren
gemini extensions install https://github.com/klarluft/gitwarren-app
npx skills add klarluft/gitwarren-app                 # the note alone, for any agent
```

Cursor, Codex, VS Code and Kiro read the same repository from their plugin
screens. See [Installing it as a plugin](#installing-it-as-a-plugin).

Code review for your own git repositories, on your own machines. Your machines,
your agents, no one else's server — and no account.

It runs as a desktop app on macOS, Windows and Linux, or as a command that
serves the same review UI into a browser tab. Same renderer either way; the
shell is the only thing that differs. A machine with no screen at all — a VPS, a
WSL distro, a box an agent works on — runs the headless half and is reviewed
from somewhere else.

Reviews live on the machine the code is on, and stay there. GitWarren reaches
your other machines over SSH, over `wsl.exe`, or over your own tailnet, and
nothing is replicated, relayed or stored anywhere but the computers you already
own. See [Your other machines](#your-other-machines).

Built for the moment a coding agent — Claude Code, Codex, or anything else that
edits files on your disk — has just finished, and its work is sitting in your
worktree uncommitted. Read that diff here, on your own machine, before it
becomes a commit.

<a href="https://gitwarren.com"><img src="docs/review-uncommitted.png" alt="A GitWarren review: the files-changed tab with staged, unstaged and untracked work folded into the diff, and the amber uncommitted badge in the branch header" width="800" /></a>

Tell GitWarren which local git repositories you care about, then open **reviews**
against them — a review is a comparison of two refs, presented the way a pull
request is, with *conversation*, *commits* and *files changed* tabs.

The part that makes it worth having: a review can include work that has not been
committed. If the branch you are reviewing is checked out in a worktree,
GitWarren finds that worktree — wherever it is — and folds its staged, unstaged
and untracked changes into the diff. You can review a change before it is a
commit, which is exactly when review is most useful.

Nothing is cached: every branch name, commit and diff on screen is read from git
at the moment it is shown.

Local AI agents get the same capabilities through an MCP server over stdio, and
a plugin puts it into Claude Code, Codex, Cursor, VS Code and Gemini CLI in one
line — see [Agent access (MCP)](#agent-access-mcp).

---

## Contents

- [Stack](#stack)
- [Architecture](#architecture)
- [Reviews](#reviews)
- [Navigating a large diff](#navigating-a-large-diff)
- [Development setup](#development-setup)
- [Project layout](#project-layout)
- [Data storage](#data-storage)
- [Database migrations](#database-migrations)
- [Agent access (MCP)](#agent-access-mcp)
- [The `gitwarren` command line](#the-gitwarren-command-line)
- [Your other machines](#your-other-machines)
- [Linking the user back into the app](#linking-the-user-back-into-the-app)
- [Images in comments](#images-in-comments)
- [Release process](#release-process)
- [Auto-update](#auto-update)
- [Code signing and notarization](#code-signing-and-notarization)
- [Social preview](#social-preview)
- [Known limitations](#known-limitations)
- [Contributing](#contributing)
- [License](#license)

---

## Stack

| Concern | Choice |
| --- | --- |
| Shell | Electron 44 + TypeScript |
| UI | React 19, Tailwind CSS v4, shadcn/ui-style components on **Base UI** (`@base-ui/react`) |
| Data fetching | SWR (client-side only, no SSR) |
| Storage | SQLite via `better-sqlite3`, Drizzle ORM, generated migration files |
| Validation | zod, shared between UI forms, IPC and MCP tools |
| Agent interface | `@modelcontextprotocol/sdk` over stdio |
| Packaging | electron-builder + electron-updater |

> **Why Electron and not `deno desktop`?** Silent auto-update has to work on
> Windows, and that is the requirement `deno desktop` could not meet. Everything
> in the packaging setup below exists to serve it.

> **Base UI, not Radix.** The components in `src/renderer/src/components/ui`
> follow shadcn/ui conventions (CVA variants, `cn()` merging, the same prop
> shapes) but are built on Base UI primitives. They were written for this
> project rather than pulled from the shadcn registry, because the registry's
> default output targets Radix.

---

## Architecture

The single most important rule in this codebase:

> **The UI and the MCP server both call one shared service layer. Neither one
> contains any repository or review logic of its own.**

```
   ┌────────────────────────────┐         ┌───────────────────────────────┐
   │  Renderer (Chromium)       │         │  MCP server (its own process) │
   │  React + SWR               │         │  stdio JSON-RPC               │
   │                            │         │                               │
   │  window.gitwarren.*        │         │  repository + review tools    │
   └────────────┬───────────────┘         └───────────────┬───────────────┘
                │ contextBridge                           │
                │ ipcRenderer.invoke                       │ direct import
   ┌────────────▼───────────────┐                         │
   │  Main process              │                         │
   │  src/main/ipc.ts           │                         │
   │  (thin delegation only)    │                         │
   └────────────┬───────────────┘                         │
                │                                          │
                └──────────────┬───────────────────────────┘
                               ▼
              ┌──────────────────────────────────────┐
              │  src/core/services/                  │
              │  repositories.ts · reviews.ts        │
              │  validation · path resolution ·      │
              │  duplicate rules · error semantics   │
              └───────┬───────────────────┬──────────┘
                      ▼                   ▼
            ┌──────────────────┐  ┌──────────────────┐
            │ SQLite (WAL)     │  │ git (subprocess) │
            │ durable facts    │  │ live state only  │
            └──────────────────┘  └──────────────────┘
```

The two surfaces are not identical in *reach*: the review service's
`commits` and `diff` reads are wired to the UI only, because an agent can read
the repository with git directly. The rule is that neither surface implements
logic of its own, not that every function must be exposed to both.

Three properties fall out of this shape:

**No drift between surfaces.** `src/main/ipc.ts` is a set of one-line
delegations, and each MCP tool is a thin wrapper. The service re-parses its own
input with the zod schema from `src/shared/schemas.ts` rather than trusting the
caller, so a rule added there applies to the UI, the IPC layer and the agent
tools simultaneously. It is not possible for an agent to write something the UI
would have rejected.

**Two processes, one database.** The GUI and the MCP server are separate OS
processes sharing one SQLite file. Hence WAL journalling and a busy timeout (see
`src/core/db/client.ts`). Changes made by an agent show up in the UI on the next
refresh; the window revalidates when it regains focus.

**`src/core` never imports `electron`.** That is what lets the MCP process reuse
it. It also means the application-data directory is computed by the same
platform-aware function in both processes (`src/core/paths.ts`) rather than one
using Electron's `app.getPath('userData')` and the other guessing.

### Why IPC and not a local HTTP server

The renderer reaches the main process over Electron's context bridge, not over
`fetch` to `127.0.0.1`. A local HTTP server would add a port to allocate and
discover, a listening socket other software on the machine could talk to, and a
startup ordering problem — in exchange for nothing this app needs. SWR is used
exactly as it would be with HTTP; only the fetcher differs.

There is no authentication anywhere. This is a local, single-user app; the MCP
transport is a pipe owned by the agent the user launched, and there is no
network surface to authenticate.

### Error handling across the boundary

Errors cannot cross `ipcRenderer.invoke` intact — Electron stringifies them and
the type is lost. Every handler returns an `IpcResult<T>` envelope instead, and
the preload script rebuilds a real `AppError` on the renderer side. That is what
lets a form show *"This folder is not inside a git repository"* underneath the
path input rather than a generic banner. The MCP tools map the same errors to
`CODE: message` tool errors so agents can branch on the code.

### Attribution

Comments carry an author; nothing else does. The rule that makes it trustworthy
is that **the author is an argument to the service, never a field