nicknisi/diffdad

Última atividade de origem registrada: 7 de julho de 2026 às 20:35

Catálogo do SkillsMP atualizado: 5 de novembro de 2026 às 19:57

skills coletadas: 1

Estrelas no GitHub: 23
Forks no GitHub: 4

Instalar com um assistente de IA

Copie este prompt para o assistente de IA que você usa.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/nicknisi/diffdad.

README do repositório

Arquivo de origem do README: README.md

Ler o README original

Expandir README completo

<p align="center"> <img src="packages/web/public/diff-dad-mark.svg" width="120" height="120" alt="Diff Dad" /> </p> <h1 align="center">Diff Dad</h1> <p align="center"> GitHub PRs as narrated stories.<br/> <code>dad 139</code> turns a file-by-file diff into a semantic walkthrough with AI-generated chapters, reviewer concerns, a recap tab, inline comments, and live sync. </p> ## Install ### Homebrew ```sh brew install nicknisi/formulae/dad ``` Or, equivalently: ```sh brew tap nicknisi/formulae brew install dad ``` ### From source ```sh git clone https://github.com/nicknisi/diffdad && cd diffdad bun install && bun run build bun link ``` Requires [Bun](https://bun.sh) when building from source. The Homebrew install is a standalone binary — no runtime needed. ## Usage ```sh dad <pr> # Open a PR as a narrated review dad review <pr> # Same as above (explicit subcommand) dad config # Print a link to the in-app settings page (opens it if the daemon is up) dad cache clear # Clear cached narratives dad daemon # Start the per-machine review command center dad --version # Print version ``` Flags (can go in any position): ```sh --with=claude|codex|pi # Force a specific local AI CLI --no-cache # Regenerate narrative even if cached --no-open # Don't auto-open the browser --port=3000 # Use a specific port ``` PR argument formats: ``` https://github.com/owner/repo/pull/123 owner/repo#123 139 # bare number — infers repo from git remote ``` The CLI fetches the PR diff, generates a semantic narrative, and opens a local web UI in your browser. The review view starts with verdict, reading plan, and concerns; the Recap tab lazily generates an orientation brief for in-flight work. ## Command Center (daemon) `dad daemon` runs a long-lived, per-machine review hub: one cross-repo queue of everything waiting on you, served at a stable local URL (`http://localhost:4319`) and grouped by status — **needs you**, **in flight**, **cleared**. ```sh dad daemon # Start the command center dad daemon status # Is it running? dad daemon install # Run it under launchd — survives terminal close, restarts at login dad daemon uninstall # Remove the launchd agent ``` With a GitHub token configured (see [GitHub Token](#github-token)), the daemon polls every 60 seconds for open PRs where you're a requested reviewer or assignee and mints a queue unit for each. Open a review request on GitHub and it shows up here. - **Lazy narration** — a unit's walkthrough is generated the first time you open it, not on poll, so PRs you never click cost nothing. - **Review from the drill-in** — a queue row only opens the PR; you approve or request changes from inside the review, which posts a **real GitHub review**. There is no queue-level verdict. A PR you've reviewed stays out of the queue until its author pushes past the commit you reviewed. - **Re-read (⟳)** — from a PR's review, re-fetch its live head SHA and regenerate the walkthrough from scratch, bypassing the cache — for when the author has pushed since you last looked. - **Refresh (↻)** — the header button runs a poll on demand instead of waiting for the next tick; a "checked … ago" caption shows how fresh the queue is, and a toast reports what changed. - **Self-cleaning queue** — every poll reconciles against GitHub: closed or merged PRs drop immediately; PRs no longer requested of you drop after two consecutive polls without them. - **Repo filter** — a sidebar facets the queue by repo with per-repo "needs you" counts (a native dropdown on narrow screens), so a busy inbox stays scannable. - **Errors, not spinners** — if narration fails, the review shows an explicit panel with a Retry button (and the raw diff below) instead of spinning forever. ## How It Works Instead of reviewing files one by one, Diff Dad groups code changes into **chapters** by semantic behavior. An AI reads the entire diff and produces a reading order — setup first, then core changes, then wiring, then edge cases — with prose explaining what each group does and why. ### AI Provider Diff Dad picks a provider in this order: 1. `--with=<cli>` flag (forces a local CLI) 2. Provider configured on the settings page 3. **API key env vars** — `ANTHROPIC_API_KEY`, then `OPENAI_API_KEY`, auto-route through the matching API when no provider is configured 4. `claude -p` (Claude Code CLI), `codex`, then `pi` — uses your existing subscriptions, no API key needed, but significantly slower due to harness overhead Open the settings page (`/settings` in the command center, or the Settings view in a PR review) to choose between: - **Anthropic API** — requires `ANTHROPIC_API_KEY` (recommended) - **OpenAI** — requires OpenAI API key - **Ollama** — local models, no key needed - **Claude CLI / Codex CLI / pi CLI** — uses your existing subscription, no API key ```sh dad --with=claude owner/repo#123 # force the Claude CLI even if a key is set ``` Set `DIFFDAD_DEBUG_AI=1` (also accepts `true`) to print one stderr summary per AI call — provider, model, why the stream stopped, token usage, and a tally of stream part types. Use it to spot model-behavior surprises, like thinking burning the token budget (a `reasoning` count next to `finishReason=length` and `textChars=0`). ### GitHub Token Diff Dad needs a GitHub token to fetch PR data and post comments. It checks, in order: 1. `DIFFDAD_GITHUB_TOKEN` environment variable 2. `gh auth token` (GitHub CLI) 3. Token saved on the settings page ### Caching Narratives and recaps are cached at `~/.cache/diffdad/`, keyed by the PR and its head commit — same commit = instant reload. Use `--no-cache` to regenerate, or `dad cache clear` to wipe the cache. The daemon's review queue is durable state, not a cache, so it lives in the app-data dir instead: `~/Library/Application Support/diffdad` on macOS, else `$XDG_DATA_HOME/diffdad` or `~/.local/share/diffdad`. `dad cache clear` never touches it. ## Features ### Reviewer Surface Before the chapters, Diff Dad surfaces what a reviewer needs first: - **TL;DR + verdict** — one-line summary plus a `safe` / `caution` / `risky` call - **Reading plan** — an ordered list of where to start and what to look at next, with one-click jumps to the relevant chapter - **Concerns** — Socratic questions about likely defect classes (logic, state, timing, validation, security, test gaps, API contracts, error handling) with citations to the diff Per-file risk is computed from churn, criticality keywords (`auth`, `migration`, `payment`, …), inbound import refs, and test-gap heuristics, then fed to the LLM as hints so the reading plan is risk-ordered. Concerns can be dismissed, restored, jumped to in the diff, or turned directly into a GitHub comment / draft review comment. ### Recap Tab For drive-by help or returning to a stale PR, the Recap tab answers “what is going on here?” instead of “what might be wrong?” It gathers PR body text, linked issues, commits, force-push events, review threads, CI status, and latest reviews, then summarizes: - **Goal** — the PR’s intended outcome - **State of play** — done, WIP, and not started - **Decisions & alternatives** — cited choices and direction changes - **Blockers** — failing checks, unanswered review questions, TODOs, or thrash - **Mental model** — core files, touchpoints, and a small ASCII sketch - **How to help** — concrete ways a teammate can unblock the work Recaps are generated on demand and cached separately from review narratives. ### Semantic Chapters The AI groups hunks across files by behavior, not by filename. Each chapter has a title, a **why-it-matters** block, and narrative prose explaining the change. Chapters can reference the same hunk when it's relevant to multiple behaviors. ### Inline Comments Review comments from GitHub appear inline next to the relevant code lines, including existing multi-line ranges. Comments you post from Diff Dad sync back to GitHub as real review comments, with support for added lines, removed lines, replies, and shift-click multi-line selections. Bot comments (Greptile, CodeRabbit, etc.) are clustered into collapsible groups with replies. ### Live Sync An SSE connection streams narrative generation progress, partial narratives from API providers, recap completion, and GitHub updates. New comments, CI status changes, and check runs appear in real time. Comments you post are broadcast instantly via the server — no waiting for the next poll. ### Story Controls - **Density** — toggle narration between terse (1 sentence), normal, and verbose per chapter - **Re-narrate** — rewrite a chapter's narration through a different lens (security, performance, API consumer) - **Ask AI** — ask a question about a specific chapter's code changes - **Mark reviewed** — track your progress through the PR, persisted across page reloads ### Review Submission Submit reviews directly from the UI — Comment, Approve, or Request Changes. Inline comments are posted to GitHub along with your summary, and the submit dialog can draft or polish that summary with AI using reviewed chapters, draft comments, and raised concerns as context. ### Keyboard Shortcuts | Key | Action | | --------- | ------------------------------------- | | `j` / `k` | Next / previous chapter | | `r` | Toggle reviewed on current chapter | | `c` | Open comment composer on hovered line | | `s` | Open / close submit review dialog | | `?` | Show shortcuts help | | `Esc` | Close open panels | ### Display Options Configurable on the settings page: - **Story structure** — chapters (cards), linear (continuous flow), outline (collapsed) - **Layout** — TOC sidebar or full-width linear - **Density** — comfortable or compact - **Narration density** — terse, normal, or verbose default ## Architecture Monorepo with three packages: ``` packages/cli/ Bun CLI + Hono server packages/web/ React + Vite reviewer UI packages/site/ Astro marketing site ``` The CLI fetches the PR, generates the narrative, starts a local Hono server, and opens the browser. The frontend is a static Vite build served by the Hono server. All GitHub API calls go through the CLI server — the frontend never talks to GitHub directly. ### Tech Stack - **Runtime:** Bun - **Server:** Hono - **Frontend:** React 19, Vite, Zustand, Tailwind CSS v4 - **Site:** Astro - **AI:** Vercel AI SDK (multi-provider) or local CLIs (`claude`, `codex`, `pi`) - **Syntax highlighting:** Shiki (github-light/dark themes) - **Markdown:** Custom renderer with DOMPurify sanitization ## Development ```sh bun install bun run dev # Start Vite dev server (frontend only) bun run build # Build frontend bun run build:bin # Build standalone binary bun run test # Run tests bun run typecheck # Type-check CLI, web, and site bun run eval # Run narrative eval fixtures ``` To test end-to-end, build the frontend first, then run the CLI: ```sh bun run build cd packages/cli && bun run src/cli.ts review owner/repo#123 ``` ## License MIT

Carregando o README do repositório…

Skills neste repositório

Desenvolvedores de software

1 categorias ocupacionais · 100% classificado

skill

ocupação

descrição

atualizado

verify

Desenvolvedores de software

How to launch and drive Diff Dad for runtime verification — daemon on a scratch port, config/test-connection API, and the single-PR server.

Idioma do texto original: inglês

2026-07-07

Mostrando 1 de 1 skills coletadas.