diff --git a/diffr/README.md b/diffr/README.md index 0cceb6434..15bc46625 100644 --- a/diffr/README.md +++ b/diffr/README.md @@ -1,30 +1,31 @@ # diffr -> diffr is experimental and still in alpha. +> diffr is still experimental. Read the [blog post](https://dev.fast/blog/diffr/) for more info about why we built it! -diffr is a Rust-based structural diffing (AST-aware) library with a WASM plugin system. It also has an: +At its core, diffr is a Rust-based structural diffing (AST-aware) library with a WASM plugin system. The plugin system allows you to do things like collapse noisy unit tests, or summarize long code blocks in pseudocode. It also ships with a variety of clients: -1. Interactive TUI with AST-aware code folding +1. An interactive TUI with AST-aware code folding. + ![Long changes summarized as pseudocode in the diffr TUI](docs/images/tui-pseudocode.gif) - ![AST-aware code folding in the diffr TUI](docs/images/folding.gif) +2. Diffr is also available natively in claude code as a mod via `/diffr`. You can view and comment on diffs without switching tabs: -2. Sane defaults for AI coding - - Summarize long changes as pseudocode - - Collapse tests and docs + ![Claude Code Mod](docs/images/claude-code-mod.gif) - ![Long changes summarized as pseudocode in the diffr TUI](docs/images/pseudocode.gif) +3. It's also available as a fun, client-side only website! See [diffs.fast](https://diffs.fast). All of the computation (WASM plugins, code folding, summarization) happens exclusively on your device. In this configuration, `diffr` runs in WASM and streams results back to the frontend. -3. [WASM-based plugin system](docs/plugin.md) + ![diffr website](docs/images/website.gif) -4. Diffr is also available natively in many coding agents as a native plugin via `/diffr`. You can view and comment on diffs without switching tabs: +4. [WASM-based plugin system](docs/plugin.md). You can customize your view of diffs by vibe coding plugins and dynamically collapse portions that you find to be low-signal: -// TODO(smenon): gif of claude code plugin + ![claude code vibe-coding experience with diffr](docs/images/claude-code-plugin.gif) -Currently, we support a plugin for Claude Code. + And we're working on interactive views which are deeply integrated with the Whiteboard app: + + ![Gif - user collapsing diffr plugins via vibe-coding](docs/images/plugin.gif) ## Usage -`diffr` accepts the exact same arguments that `git diff` does. +`diffr` accepts the exact same arguments that `git diff` does when invoked on the command line: ```sh diffr # index versus working tree @@ -32,6 +33,8 @@ diffr --cached # staged changes diffr main...HEAD -- src/ # merge-base comparison ``` +When installed as a Claude Code mod, you can invoke it via `/diffr`. Claude also has a tool it can use to invoke a diffs view to show you file(s) as well. + ## Installation ### Install Script (Preferred) @@ -42,6 +45,8 @@ Run the script below + follow its setup instructions: curl -fsSL https://install.dev.fast/diffr | sh ``` +This will also guide you through the setup instructions for the Claude Code integration. + ### Alternative Methods: You can use homebrew (Apple Silicon macOS, Intel macOS, and x64/ARM64 Linux): @@ -62,6 +67,20 @@ cargo install diffr-cli --locked Windows x64: download `diffr--.tar.gz` from [Whiteboard Releases](https://github.com/devdotfast/whiteboard/releases) and extract it with `tar -xzf`, or use `cargo binstall`. +## Configuration + +`diffr`'s config page is accessible via `diffr config`. Your agent can also customize it for you; just ask it to do so (there are instructions for your agent under `diffr --help`). + +To set up pseudocode summarization (or any other customization), you can: + +1. Run `diffr config init` to get onboarded to diffr. +2. Alternatively, run `diffr config` to get dropped to the settings page. + - Run diffr config + - Search for 'summarization' + - Enable in the dropdown + - Pick a provider and model, and add its API key unless GEMINI_API_KEY, OPENAI_API_KEY or ANTHROPIC_API_KEY is already in your environment +3. Through `Cmd + P > Settings` in the Whiteboard app. + ## History diffr is sourced heavily from two other great open-source projects: @@ -72,29 +91,18 @@ diffr is sourced heavily from two other great open-source projects: We forked these projects because of the following 3 technical reasons: 1. AST-based fold matching: we didn't want just structural diffing; with the power of tree-sitter queries, you can also match AST *folds* across new/old files and get a more intuitive review experience: -// TODO(cld/sid): need a gif here. 2. Plugin System: We started to review lightweight diffs but realized that every language, team, and developer was different. We're striving towards the ideal where you can customize your own review - for example, filter to only files and types which are important to you. - By default, we have plugins set up that collapse unit tests, and summarize long code blocks in pseudocode. 3. TUI affordance - for small diffs it's too heavyweight to have a full review app, or even github. We kept things in Typescript for the MVP here; this will be rewritten in pure Rust. We hope in the future that we can find some way to upstream some / all of these features. Obviously everyone works differently and this is quite an opinionated stance on things, so we imagine this may take time. -## Known Limitations - -1. Semantic diff summarization calls Gemini, OpenAI (or any OpenAI-compatible server, such as Ollama, via `endpoint`), or Anthropic. Onboarding guides you on getting it set up (via script or `diffr config init`). but otherwise: - a. Through the TUI: - - Run `diffr config` - - Search for 'summarization' - - Enable in the dropdown - - Pick a provider and model, and add its API key unless `GEMINI_API_KEY`, `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` is already in your environment - b. Through `Cmd + P > Settings` in the [Whiteboard app](../). -2. The plugin API is a bit awkward and will be simplified radically in the coming releases. ### Plugin API `diffr` has a powerful, wasm-based plugin API which customizes how it presents changed files. For more details, read the [docs](./docs/plugin.md). -TODO: move this probably to the plugins dir?? and update the reference. probably sjould just be a README.md? +> Note: The plugin API is a bit awkward and will be simplified radically in the coming releases. It is still not stable! ## License diff --git a/diffr/docs/images/claude-code-mod.gif b/diffr/docs/images/claude-code-mod.gif new file mode 100644 index 000000000..b08c91269 Binary files /dev/null and b/diffr/docs/images/claude-code-mod.gif differ diff --git a/diffr/docs/images/claude-code-plugin.gif b/diffr/docs/images/claude-code-plugin.gif new file mode 100644 index 000000000..e56559880 Binary files /dev/null and b/diffr/docs/images/claude-code-plugin.gif differ diff --git a/diffr/docs/images/plugin.gif b/diffr/docs/images/plugin.gif new file mode 100644 index 000000000..1fd7efb52 Binary files /dev/null and b/diffr/docs/images/plugin.gif differ diff --git a/diffr/docs/images/tui-pseudocode.gif b/diffr/docs/images/tui-pseudocode.gif new file mode 100644 index 000000000..a6e24d47b Binary files /dev/null and b/diffr/docs/images/tui-pseudocode.gif differ diff --git a/diffr/docs/images/website.gif b/diffr/docs/images/website.gif new file mode 100644 index 000000000..c922ad78a Binary files /dev/null and b/diffr/docs/images/website.gif differ