Writing a plugin

A sidecar is any executable — Rust, Python, a shell script — that reads one JSON object per line on stdin and writes one per line on stdout. Wire v1 is frozen. Start from plugins/echo/ in the Gray repo, a copy-paste reference.

Host → plugin

Plugin → host

A plugin can call back into the host: host/run runs a prompt, host/say prints into the transcript, host/background starts background work, and host/ask asks the user.

{"id": "q1", "method": "host/ask",
 "params": {"questions": [{"id": "color", "header": "Color",
   "question": "Which color?",
   "options": [{"label": "Red", "description": "warm"}]}],
  "blocking": true}}

On a terminal the question renders as an inline modal; with piped stdin it reads one line per question; headless, it resolves empty at once. Empty and timed-out answers deny, so approval plugins fail closed.

Timeouts

• —Ordinary calls time out after 30 s, so a hung plugin can never hang Gray.
• —Plugins that ask the user claim protocol 1.1 in their manifest and get 330 s on tool/call and tool/before; their own ask should time out at 300 s.
• —Provider plugins claim protocol 1.2.

Check it

$gray plugin check ./my-plugin

Boots the plugin exactly as gray.yml would and drives the failure modes: empty-name manifests, hung calls, concurrent calls routed by id, graceful shutdown. One line per check, nonzero exit on failure. Publish to the registry at /plugins/submit.