# diffing

> Local-first CLI for reviewing, navigating, and discussing git diffs with AI.
> Version 0.16.1. MIT. Loopback-only by default.

Site: https://ahmedragab20.github.io/diffing/
Package: https://www.npmjs.com/package/diffing
Repo: https://github.com/ahmedragab20/diffing

## Docs

- [Documentation](https://ahmedragab20.github.io/diffing/docs/): Start here for the full documentation index — getting started, concepts, guides, and reference.
- [Getting started](https://ahmedragab20.github.io/diffing/docs/getting-started/): Install with npm, run the setup wizard, then launch diffing inside a git repo to open the review UI.
- [Overview](https://ahmedragab20.github.io/diffing/docs/concepts/overview/): diffing is a local-first git diff review tool for humans and AI agents with web UI, TUI, plan review, and MCP.
- [Architecture](https://ahmedragab20.github.io/diffing/docs/concepts/architecture/): diffing runs a loopback Hono server, discovers sessions via per-repo lockfiles, and auto-detects TTY vs terminal patch output.
- [Sessions](https://ahmedragab20.github.io/diffing/docs/concepts/sessions/): Multiple web/TUI/PR reviews can run concurrently; server.json points agent tools at the active session.
- [Storage & security](https://ahmedragab20.github.io/diffing/docs/concepts/storage/): Per-repo data under ~/.diffing/, settings under ~/.config/diffing/, loopback bind by default with path-traversal protection.
- [Code review](https://ahmedragab20.github.io/diffing/docs/guides/code-review/): Open a review, leave inline comments with severity, send to agent, and resolve threads as work lands.
- [Plan review](https://ahmedragab20.github.io/diffing/docs/guides/plan-review/): Agents submit plans, humans verdict approved/changes-requested/rejected, then agents obey the decision.
- [Agent handoff](https://ahmedragab20.github.io/diffing/docs/guides/agent-handoff/): Default is async park after sharing the URL; use await only for live reviews; timeout means park not retry-forever.
- [GitHub PR review](https://ahmedragab20.github.io/diffing/docs/guides/github-pr/): Open a PR session with diffing gh pr or --gh-pr; use bounded inspect and gh_* tools; mutate GitHub only with explicit authorization.
- [Terminal UI (TUI)](https://ahmedragab20.github.io/diffing/docs/guides/tui/): diffing view is the read-only browser; --tui is full review. Experimental — web remains the supported production path.
- [Search](https://ahmedragab20.github.io/diffing/docs/guides/search/): Four scopes via fff — files, text, symbols, all — with frecency ranking and graceful degradation.
- [Setup & MCP](https://ahmedragab20.github.io/diffing/docs/guides/setup-and-mcp/): Run diffing setup for doctor, skills, and MCP JSON; write IDE configs only with explicit flags.
- [CLI reference](https://ahmedragab20.github.io/diffing/docs/reference/cli/): diffing is a git-diff drop-in with review server flags plus agent, plan, sessions, gh, and inspect subcommands.
- [MCP tools](https://ahmedragab20.github.io/diffing/docs/reference/mcp/): Session, bounded diff inspect, comments, plan review, and GitHub PR tools over stdio MCP.
- [HTTP API](https://ahmedragab20.github.io/diffing/docs/reference/http-api/): Review await/send, comments CRUD, plans, progress, live SSE, search, and attachments on the local server.
- [Comments XML](https://ahmedragab20.github.io/diffing/docs/reference/comments-xml/): Structured XML with instructions, optional general-comment, file groups, severity, and replies for await-review payloads.
- [Keyboard shortcuts](https://ahmedragab20.github.io/diffing/docs/reference/keyboard/): j/k scrolling, g sequences for theme and files, m for split/unified, plan-page zen and edit keys.
- [Settings](https://ahmedragab20.github.io/diffing/docs/reference/settings/): Global settings live in ~/.config/diffing/settings.json including defaultMode, theme, and diff presentation.
- [Exit codes](https://ahmedragab20.github.io/diffing/docs/reference/exit-codes/): 0 ok, 2 await timeout, 3 no server, 4 not found, 5 usage — timeout is a park signal.
- [Gridline](https://ahmedragab20.github.io/diffing/docs/design/gridline/): Flat surfaces, mono type, one-pixel rules, semantic color roles — hierarchy from alignment and density, not glass or glow.
- [Themes](https://ahmedragab20.github.io/diffing/docs/design/themes/): 52 themes with default rose-pine; open the picker with g t.

## Optional

- [Full documentation corpus](https://ahmedragab20.github.io/diffing/llms-full.txt): concatenated guides and reference for bulk ingest
- [GitHub README](https://github.com/ahmedragab20/diffing#readme)

## Agent quick facts

- Install: `npm install -g diffing`
- Start review: `diffing` (web default) or `diffing --tui`
- MCP: `diffing mcp` — 37 tools
- Themes: 52; default rose-pine; picker key `g t` (plain `t` is tab size)
- Await timeout exit 2 = park, do not silent-loop
- Plans: submit → park → obey verdict (approved / changes-requested / rejected)
- Storage: ~/.diffing/<repo>-<hash>/ ; settings ~/.config/diffing/settings.json
- Never write agent scratch into the consumer working tree