protocol.md

Protocol Reference

The current wire protocol version is 1.

Plugin Kinds

• logo_animation
• info_provider
• effect
• config_provider (extension protocol)

Logo Animation Request

{
  "version": 1,
  "kind": "logo_animation",
  "lines": ["line 1", "line 2"],
  "frames": [["frame 1"], ["frame 2"]],
  "args": {
    "fps": 12,
    "duration_ms": 1200,
    "loop": true,
    "style": "wave"
  }
}

Logo Animation Response

{
  "frames": [
    {
      "delay_ms": 80,
      "lines": ["rendered line 1", "rendered line 2"]
    }
  ]
}

Info Provider Request

{
  "version": 1,
  "kind": "info_provider",
  "args": {
    "username": "example",
    "max_lines": 5
  }
}

Info Provider Response

{
  "lines": [
    "line one",
    "line two"
  ]
}

Effect Request

The core renders the info lines and sends them to an effect binary (xfetch-effect-<name>); the effect returns per-frame states.

{
  "version": 1,
  "kind": "effect",
  "lines": ["\u001b[32m os: Arch \u001b[0m", "\u001b[32m cpu: 3.2 GHz \u001b[0m"],
  "args": {
    "style": "glitch",
    "duration_ms": 800,
    "fps": 30
  }
}

Effect Response

{
  "frames": [
    { "delay_ms": 33, "lines": ["@peo@f8i*xo&23#", "1qnx4w9@&k6c"] },
    { "delay_ms": 33, "lines": ["os: Arch", "cpu: 3.2 GHz"] }
  ]
}

The last frame should reach the final content. Effects must keep ANSI escape sequences intact while transforming the lines.

Config Provider Request (Extension)

{
  "version": 1,
  "kind": "config_provider",
  "config": { "show_colors": true, "modules": ["os", "cpu"] },
  "args": { "strategy": "random" }
}

Config Provider Response (Extension)

{
  "config": { "show_colors": false, "modules": ["cpu", "memory"] }
}

Compatibility

Protocol changes should be introduced in this repository first and then adopted by the core and official plugin repositories together.