> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openaeon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Diffs

> Use the optional Diffs plugin to render before/after text or unified patches as a gateway-hosted diff view or a PNG.

# Diffs

`diffs` is an **optional plugin tool** that renders a read-only diff from either:

* arbitrary `before` / `after` text
* a unified patch

The tool can produce:

* a gateway-hosted viewer URL for canvas use
* a PNG image for message delivery
* both outputs together

## Enable the plugin

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
      },
    },
  },
}
```

## What agents get back

* `mode: "view"` returns `details.viewerUrl` and `details.viewerPath`
* `mode: "image"` returns `details.imagePath` only
* `mode: "both"` returns the viewer details plus `details.imagePath`

Typical agent patterns:

* open `details.viewerUrl` in canvas with `canvas present`
* send `details.imagePath` with the `message` tool using `path` or `filePath`

## Tool inputs

Before/after input:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "before": "# Hello\n\nOne",
  "after": "# Hello\n\nTwo",
  "path": "docs/example.md",
  "mode": "view"
}
```

Patch input:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "patch": "diff --git a/src/example.ts b/src/example.ts\n--- a/src/example.ts\n+++ b/src/example.ts\n@@ -1 +1 @@\n-const x = 1;\n+const x = 2;\n",
  "mode": "both"
}
```

Useful options:

* `mode`: `view`, `image`, or `both`
* `layout`: `unified` or `split`
* `theme`: `light` or `dark`
* `expandUnchanged`: expand unchanged sections instead of collapsing them
* `path`: display name for before/after input
* `title`: explicit diff title
* `ttlSeconds`: viewer artifact lifetime
* `baseUrl`: override the gateway base URL used in the returned viewer link

## Plugin defaults

Set plugin-wide defaults in `~/.openaeon/openaeon.json`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
        config: {
          defaults: {
            fontFamily: "Fira Code",
            fontSize: 15,
            layout: "unified",
            wordWrap: true,
            background: true,
            theme: "dark",
            mode: "both",
          },
        },
      },
    },
  },
}
```

Supported defaults:

* `fontFamily`
* `fontSize`
* `layout`
* `wordWrap`
* `background`
* `theme`
* `mode`

Explicit tool parameters override the plugin defaults.

## Notes

* Viewer pages are hosted locally by the gateway under `/plugins/diffs/...`.
* Viewer artifacts are ephemeral and stored locally.
* `mode: "image"` uses a faster image-only render path and does not create a viewer URL.
* PNG rendering requires a Chromium-compatible browser. If auto-detection is not enough, set `browser.executablePath`.
* Diff rendering is powered by [Diffs](https://diffs.com).

## Related docs

* [Tools overview](/tools)
* [Plugins](/tools/plugin)
* [Browser](/tools/browser)