Skip to main content

Data Distribution Service (DDS)

DDS is Yazi's built-in pub-sub messaging layer. It allows multiple Yazi processes to communicate in real time — enabling coordinated state, cross-instance commands, and event-driven plugins.

How It Works​

Every Yazi instance can act as a publisher, subscriber, or both. Messages flow through an internal broker without requiring an external server.

 ┌─────────┐   publish    ┌──────────┐   notify    ┌─────────┐
 │ Instance A │ ─────────► │   DDS    │ ─────────► │ Instance B │
 │ (publisher)│            │  Broker  │            │ (subscriber)│
 └───────────┘             └──────────┘            └────────────┘

Static vs. Dynamic Messages​

TypeDescriptionUse Case
StaticPre-defined message kinds declared in package.tomlReliable subscriptions, compile-time checks
DynamicAd-hoc messages sent at runtime without prior declarationOne-off commands, debugging, scripts

Common Use Cases​

  • Sync working directory across multiple Yazi instances (e.g., two terminals side-by-side)
  • Notify other instances when files are created, deleted, or renamed
  • Coordinate plugins running in separate Yazi processes
  • Remote control — send navigation commands from a script or another tool

Sending Messages​

# Static publish
ya pub "refresh" '{"path": "/data"}'

# Dynamic publish
ya pub "custom:reload-config" '{}'

Subscribing in a Plugin​

In your plugin's package.toml:

[dds]
subscribe = ["refresh", "file-changed"]

Then handle events in your plugin code:

-- plugin.lua
local dds = require("dds")

dds.subscribe("refresh", function(msg)
	-- msg.body contains the JSON payload
	app.emit("refresh", msg.body.path)
end)
tip

Use dynamic messages (prefix with a namespace like custom:) to avoid naming collisions between plugins.

See Also​