openclaw/extensions/diffs

@openclaw/diffs

Read-only diff viewer plugin for OpenClaw agents.

Install

openclaw plugins install @openclaw/diffs

Installation and updates apply automatically when the local Gateway is running. If it is stopped, changes take effect the next time it starts.

It gives agents one tool, diffs, that can:

• render a gateway-hosted diff viewer
• render the same diff to a file (PNG or PDF)
• accept either arbitrary before and after text or a unified patch

What Agents Get

The tool can return:

• details.changed: false when before/after inputs are identical and no artifact was rendered; true for rendered results
• details.viewerUrl: a gateway URL that can be opened in the operator's browser
• details.filePath: a local rendered artifact path when file rendering is requested
• details.fileFormat: the rendered file format (png or pdf)
• details.artifactId and details.expiresAt: artifact identity and TTL metadata
• details.context: available routing metadata such as agentId, sessionId, messageChannel, and agentAccountId

When the plugin is enabled, it also ships a companion skill from skills/ and prepends stable tool-usage guidance into system-prompt space via before_prompt_build. The hook uses prependSystemContext, so the guidance stays out of user-prompt space while still being available every turn.

This means an agent can:

• call diffs with mode=view, then return details.viewerUrl for the operator to open
• call diffs with mode=file, then send the file through the normal message tool using path or filePath
• call diffs with mode=both when it wants both outputs

Tool Inputs

Before and after:

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

Patch:

{
  "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 Deprecated alias: image behaves like file and is still accepted for backward compatibility.
• layout: unified or split
• theme: light or dark (default: dark)
• fileFormat: png or pdf (default: png)
• fileQuality: standard, hq, or print
• fileScale: device scale override (1-4)
• fileMaxWidth: max width override in CSS pixels (640-2400)
• expandUnchanged: expand unchanged sections (per-call option only, not a plugin default key)
• path: display name for before and after input
• lang: language hint for before/after input; unknown values fall back to plain text
• Default syntax highlighting covers common source, config, and documentation languages. Install diffs-language-pack for the extended language catalog.
• title: explicit viewer title
• ttlSeconds: artifact lifetime for viewer and standalone file outputs
• baseUrl: override the gateway base URL used in the returned viewer link (origin or origin+base path only; no query/hash)
• viewerBaseUrl plugin config: persistent fallback used when a tool call omits baseUrl

Input safety limits:

• before and after: max 512 KiB each
• patch: max 2 MiB
• patch rendering cap: max 128 files / 120,000 lines

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",
            ttlSeconds: 21600,
          },
        },
      },
    },
  },
}

Explicit tool parameters still win over these defaults.

Docs

• https://docs.openclaw.ai/tools/diffs

Package

• Plugin id: diffs
• Package: @openclaw/diffs
• Minimum OpenClaw host: 2026.4.30

Security options:

• security.allowRemoteViewer (default false): allows non-loopback access to /plugins/diffs/view/... token URLs
• viewerBaseUrl (optional): persistent viewer-link origin/path fallback for shareable URLs
• defaults.ttlSeconds (default 1800, max 21600): default artifact lifetime for viewer and standalone file outputs

Example:

{
  plugins: {
    entries: {
      diffs: {
        enabled: true,
        config: {
          viewerBaseUrl: "https://gateway.example.com/openclaw",
        },
      },
    },
  },
}

Example Agent Prompts

Open in the browser:

Use the `diffs` tool in `view` mode for this before and after content, then return the viewer URL.

Path: docs/example.md

Before:
# Hello

This is version one.

After:
# Hello

This is version two.

Render a file (PNG or PDF):

Use the `diffs` tool in `file` mode for this before and after input. After it returns `details.filePath`, use the `message` tool with `path` or `filePath` to send me the rendered diff file.

Path: README.md

Before:
OpenClaw supports plugins.

After:
OpenClaw supports plugins and hosted diff views.

Do both:

Use the `diffs` tool in `both` mode for this diff. Return the viewer URL and then send the rendered file by passing `details.filePath` to the `message` tool.

Path: src/demo.ts

Before:
const status = "old";

After:
const status = "new";

Patch input:

Use the `diffs` tool with this unified patch in `view` mode. Return its viewer URL.

diff --git a/src/example.ts b/src/example.ts
--- a/src/example.ts
+++ b/src/example.ts
@@ -1,3 +1,3 @@
 export function add(a: number, b: number) {
-  return a + b;
+  return a + b + 1;
 }

Notes

• Multi-file patches start with a changed-files summary card: totals, per-file +N/-N stats, change badges, and anchor links.
• Rendered PNG/PDF files keep the per-file header counts but omit the interactive view toggles.
• The viewer is hosted locally through the gateway under /plugins/diffs/....
• Viewer HTML and metadata are ephemeral SQLite plugin blobs. The URL token is returned to the caller while SQLite stores only its SHA-256 hash.
• Rendered PNG/PDF files remain temporary materializations in $TMPDIR/openclaw-diffs because delivery APIs require a file path. No JSON metadata sidecars are written or imported.
• Default viewer URLs use gateway.publicOrigin when configured, then the existing bind-aware Gateway fallback. Plugin viewerBaseUrl and per-call baseUrl take precedence.
• If gateway.trustedProxies includes loopback for a same-host proxy (for example Tailscale Serve), raw 127.0.0.1 viewer requests without forwarded client-IP headers fail closed by design.
• In that topology, prefer mode=file / mode=both for attachments, or intentionally enable remote viewers and set plugin viewerBaseUrl (or pass a proxy/public baseUrl) when you need a shareable viewer URL.
• Remote viewer misses are throttled to reduce token-guess abuse.
• PNG or PDF rendering requires a Chromium-compatible browser. Set browser.executablePath if auto-detection is not enough.
• If your delivery channel compresses images heavily (for example Telegram or WhatsApp), prefer fileFormat: "pdf" to preserve readability.
• N unmodified lines rows may not always include expand controls for patch input, because many patch hunks do not carry full expandable context data.
• Diff rendering is powered by Diffs.