Galley 0.1.0 — an integrated review environment (IRE)

Review a git diff in the browser, then hand a structured review back to your
coding agent. CLI with working / staged / file / pr modes and an await →
comment → reload event loop; a browser desk (Alpine + @pierre/diffs) with
guided review, per-line comment threads, per-change accept/reject, file
sign-off, and keyboard-first navigation; an installable skill + agents
snippet; CI and tagged-release (OIDC publish) workflows.

Author: ymansurozer

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: corepack enable
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm check
+      - run: pnpm build
+      - run: pnpm test
+      - run: pnpm smoke

.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write # OIDC trusted publishing + npm provenance
+  contents: write # create the GitHub Release
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: corepack enable
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          registry-url: "https://registry.npmjs.org"
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm check
+      - run: pnpm build
+      - run: pnpm test
+      - run: pnpm smoke
+      # OIDC trusted publishing (tokenless) requires npm >= 11.5.1
+      - run: npm install -g npm@latest
+      - run: npm publish --provenance --access public
+      - run: npx changelogen@latest github release --token "$GITHUB_TOKEN"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,10 @@
+.prd/
+prototypes/
+node_modules/
+dist/
+.pi/
+*.log
+.DS_Store
+
+# Playwright MCP test artifacts (screenshots/snapshots)
+.playwright-mcp/

.oxfmtrc.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "ignorePatterns": ["src/ui/index.html", "src/ui/icon-data.ts"]
+}

.oxlintrc.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "ignorePatterns": ["src/ui/icon-data.ts"]
+}

AGENTS.md

@@ -0,0 +1,27 @@
+# Agent Instructions
+
+## Reviewing with Galley
+
+When the user should review a plan, a PR, or code changes you've made, hand it to **Galley** — a living browser review desk.
+
+- **Changes you made** → `galley --session <task-id> &` (working tree; `--diff staged` for staged only).
+- **A markdown plan / single artifact** → `galley file <path> &`.
+- **A branch / PR** → `galley pr <ref> &`.
+
+Then loop: `galley await --session <task-id>` blocks for the next event and prints a tagged JSON envelope.
+- `{"kind":"question",…}` → answer **now** with `galley comment --path … --line … --side … --body "…"` at the question's location.
+- `{"kind":"review","result":{…}}` → act on `result`: revert **rejected**, make **requestedChanges**, leave **accepted** alone, leave **approvedFiles** (signed off as-is) untouched, don't touch **stagedFiles** unless a change requires it. (Editing an approved file invalidates its approval → it needs re-review next round.)
+
+After editing code, run `galley reload --session <task-id>` so your edits show in the open tab, then `galley await` again for the next round. The desk stays open across rounds — don't reopen it.
+
+Full reference (modes, options, exit semantics, `ReviewResult`): **`skills/galley/SKILL.md`**.
+
+## Commits & releases
+
+- Commits follow **Conventional Commits** (`feat:`, `fix:`, `perf:`, `refactor:`, `docs:`,
+  `chore:`, …). `changelogen` groups them into the changelog and infers the semver bump, so the
+  prefix matters — use `feat:` for user-facing additions and `fix:` for bug fixes.
+- Releases are cut by the maintainer with `pnpm release`: it runs lint + typecheck + tests +
+  build + smoke, then `changelogen --release --push` bumps the version, writes `CHANGELOG.md`,
+  tags `vX.Y.Z`, and pushes. The pushed tag triggers the `release` workflow, which publishes to
+  npm with provenance via OIDC. Do not run `npm publish` by hand.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yusuf Mansur Özer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,85 @@
+<div align="center">
+
+<img src="assets/logo.svg" alt="Galley" width="84" />
+
+# Galley
+
+**An integrated review environment (IRE) for code you didn't write by hand.**
+
+[![CI](https://github.com/ymansurozer/galley/actions/workflows/ci.yml/badge.svg)](https://github.com/ymansurozer/galley/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@ymansurozer/galley.svg)](https://www.npmjs.com/package/@ymansurozer/galley) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+<img src="assets/screenshot.png" alt="Galley — a guided review: pending changes with accept/reject, a question waiting on the agent, and a change request" width="80%" />
+
+</div>
+
+<br>
+
+Code editors and IDEs were built for a coding-first world. Their diff view is fine for a quick glance, but not for working through a big change or going back and forth with the agent that wrote it.
+
+Galley is my attempt at a real review surface: you review, hit **Send to Agent**, and your agent acts on your decisions and replies in place.
+
+I'm not saying this is *the* review surface. I built it in a week and I'm still figuring out the shape. But this is what I think it should be.
+
+> The name comes from the *galley proof*: in printing, the rough proof pulled for proofreading and corrections before a text goes to press. You mark it up, then it ships. Same idea, for code.
+
+## Principles
+
+Galley is opinionated about exactly one thing: the review surface. It's a protocol and an interface, nothing more. How you review, and what you review with, stays yours.
+
+- **No model runs here.** Galley doesn't call an LLM or orchestrate one. It renders the diff, validates the structured input it's given, and hands a result back.
+- **Your agent, not ours.** The contract is plain JSON over stdout and a localhost server, with no assumption about who's on the other end: Claude Code, Cursor, Codex, a shell script. The guided review, the answers to your questions, the code changes themselves are all *your* agent's work. Galley just gives it somewhere to land.
+- **Local and private.** The server binds to localhost on a random port. No telemetry. Your browser may fetch a web font; switch to system fonts and even that stops.
+- **It won't touch your repo unless you ask.** Galley never edits your tracked files.
+
+## Features
+
+- **A beautiful and functional diff view** built on `@pierre/diffs`.
+- **Per-line comment threads.** Comment on any line. Ask a question and your agent answers live in the thread; leave a change request and it rides to the handoff.
+- **Per-change accept/reject.** Accept or reject individual changes, or sign off a whole file.
+- **A tight handoff loop.** Hit **Send to Agent** and your agent gets a structured review. It makes the edits, re-diffs into the same tab, and replies in place.
+- **Guided review.** Your agent can attach a guide: an overview, the files in a sensible order, a per-file summary and category, and the risky ones flagged.
+- **Four review modes.** The working tree, the staged diff, a single file (tracked or not, like a plan, PRD, or issue), or a branch against its merge-base.
+- **Keyboard-first.** Intuitive navigation: move by file, line, or change, and accept, reject, comment, or approve without touching the mouse.
+- **Customize** diff layout, intra-line, hunk separators, wrapping, code-highlight theme, and fonts.
+
+## Getting started
+
+1. **Install the CLI** (needs **Node 20+** and **git**):
+
+   ```bash
+   npm install -g @ymansurozer/galley        # global, for any repo
+   # or: npm install -D @ymansurozer/galley   # per-project
+   ```
+
+2. **Teach your agent to drive it.** Install the skill for on-demand use:
+
+   ```bash
+   npx skills add ymansurozer/galley
+   ```
+
+   Or paste the [snippet](./skills/galley/agents-snippet.md) into your agent's `AGENTS.md` / `CLAUDE.md` to always review via Galley.
+
+3. **Start a review:**
+
+   ```bash
+   galley                       # review the working-tree diff
+   galley --diff staged         # review the staged diff
+   galley file path/to/plan.md  # review a single file or artifact (e.g. a generated plan)
+   galley pr feature-branch     # review a branch's commits vs its merge-base
+   ```
+
+   Galley opens in your browser and stays open. You review and click **Send to Agent**; the agent attaches, acts on each send, and replies in the same tab. More flags (`--repo`, `--path`, `--port`, `--no-open`, `--guide`, …) are documented in the skill.
+
+## Roadmap
+
+Immediate to-dos, in rough priority order.
+
+- [ ] **Anchor repair instead of stale-flagging**: when re-diffing on `reload`, try to re-anchor each guide entry to its nearest surviving section/line before declaring the guide stale, so a guide degrades gracefully across rounds (the agent edits between rounds, Galley's hot path) instead of invalidating wholesale on any drift. Keep clean "vanished → stale" semantics for anchors that genuinely no longer resolve.
+- [ ] **Command palette**: add a discoverable Cmd/Ctrl+Shift+P palette for common review actions: file filter, find in diffs, next/previous file or change, accept/reject/request change, approve file, toggle layout/settings/sidebar, open in editor, reload, and Send to Agent. Keep keyboard shortcuts as the fast path, but make every major action searchable.
+- [ ] **Commit/range/branch review modes**: expand beyond working/staged/file/PR branch reviews with `galley commit <ref>`, `galley range <base>..<head>` / `<base>...<head>`, and `galley branch <base>` so Galley can review historical or comparison diffs without requiring a dirty working tree.
+- [ ] **Open file in editor**: add a configurable editor command and UI/shortcut action to open the selected file at the current line from the review desk. Support placeholders like `{repo}`, `{file}`, and `{line}` and keep it safe for repo-relative paths.
+- [ ] **Lazy diff/content loading + large/binary-file guards**: today every changed file's full contents are read and shipped up front; the only large-file handling is client-side render deferral. Move the guard to the data layer: classify each file by byte size and ship lightweight patch data first, hydrating full contents, highlighting, and rendered markdown on demand when a file is opened. Per-file `loadState` (`ready | deferred | too-large | binary | error`) with two byte tiers — an *eager* limit (~1 MiB, loaded up front) and a *manual* limit (~2 MiB, deferred until opened); over that is `too-large` (skipped with a summary + explicit load-anyway action), plus an image byte cap. Add **binary detection** (NUL-byte scan) so binaries are skipped rather than read as UTF-8 and handed to @pierre.
+
+## License
+
+[MIT](./LICENSE) © Yusuf Mansur Özer