openclaw/docs/tools/diffs.md

title, summary, description, read_when

title	summary	description	read_when
Diffs	Read-only diff viewer and file renderer for agents (optional plugin tool)	Use the optional Diffs plugin to render before and after text or unified patches as a gateway-hosted diff view, a file (PNG or PDF), or both.	You want agents to show code or markdown edits as diffs You want a canvas-ready viewer URL or a rendered diff file

Diffs

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

• arbitrary before and after text
• a unified patch

The tool can produce:

• a gateway-hosted viewer URL for canvas use
• a rendered file artifact (PNG or PDF) for message delivery
• both outputs together

Enable the plugin

{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
      },
    },
  },
}

What agents get back

• mode: "view" returns details.viewerUrl and details.viewerPath
• mode: "file" returns details.filePath
• mode: "both" returns the viewer details plus details.filePath
• file-producing modes also return details.fileFormat (png or pdf)

Typical agent patterns:

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

Tool inputs

Before and after input:

{
  "before": "# Hello\n\nOne",
  "after": "# Hello\n\nTwo",
  "path": "docs/example.md",
  "mode": "view"
}

Patch input:

{
  "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, file, or both
• layout: unified or split
• theme: light or dark
• fileFormat: png or pdf (default: png)
• fileQuality: standard, hq, or print (file mode only)
• fileScale: override file device scale factor (1-4)
• fileMaxWidth: override file max width in CSS pixels (640-2400)
• expandUnchanged: expand unchanged sections instead of collapsing them
• path: display name for before and 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 ~/.openclaw/openclaw.json:

{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
        config: {
          defaults: {
            fontFamily: "Fira Code",
            fontSize: 15,
            lineSpacing: 1.6,
            layout: "unified",
            showLineNumbers: true,
            diffIndicators: "bars",
            wordWrap: true,
            background: true,
            theme: "dark",
            fileFormat: "png",
            fileQuality: "standard",
            fileScale: 2,
            fileMaxWidth: 960,
            mode: "both",
          },
        },
      },
    },
  },
}

Supported defaults:

• fontFamily
• fontSize
• lineSpacing
• layout
• showLineNumbers
• diffIndicators
• wordWrap
• background
• theme
• fileFormat
• fileQuality
• fileScale
• fileMaxWidth
• mode

Explicit tool parameters override the plugin defaults.

Compatibility note: defaults.format is accepted as an alias for defaults.fileFormat.

Notes

• Viewer pages are hosted locally by the gateway under /plugins/diffs/....
• Viewer artifacts are ephemeral and stored locally.
• mode: "file" uses a faster file-only render path and does not create a viewer URL.
• File quality presets include hard pixel caps to prevent runaway renders on very large diffs.
• PNG or PDF rendering requires a Chromium-compatible browser. If auto-detection is not enough, set browser.executablePath.
• If your channel compresses images aggressively (for example Telegram or WhatsApp), prefer fileFormat: "pdf" to preserve diff readability.
• Diff rendering is powered by Diffs.

Related docs

• Tools overview
• Plugins
• Browser