Documentation

Feather wire protocol

JSON-RPC v1 reference for subprocess Feathers.

Subprocess Feathers communicate with toowl over newline-delimited JSON. Each line is one envelope.

Handshake

Host sends Hello { protocol: 1 }.
Feather replies HelloOk { protocol: 1 }.
Host sends Manifest; feather returns full PluginManifest.
Host sends BuildSidebar { ctx } on each Perch frame; feather returns optional View tree.
Host sends OnEvent notifications (fire-and-forget) for clicks, palette actions, ticks.

Envelope shapes

{"kind":"req","id":1,"body":{"method":"hello","params":{"protocol":1}}}
{"kind":"resp","id":1,"body":{"result":"hello_ok","value":{"protocol":1}}}
{"kind":"event","body":{"event":"shutdown","params":{}}}

Host → feather methods

Method	Purpose
`hello`	Protocol version negotiation
`manifest`	Fetch manifest (capabilities, id, name)
`build_sidebar`	Build Perch `View` tree

Feather → host reverse calls

Method	Capability required
`host_spawn_pane`	`pane_spawn`
`host_inject_pane`	`pane_inject`
`host_open_url`	`network`
`host_http_get`	`network`
`host_show_banner` / `host_dismiss_banner`	`notify`
`host_read_file`	`fs_read`
`host_watch_path`	`fs_watch`
`host_state_get` / `host_state_set`	(always allowed)

Manifest on disk

id = "my-feather"
name = "My Feather"
version = "0.1.0"
program = "./my-feather"
capabilities = ["pane_spawn", "notify"]

The subprocess sends its authoritative manifest over the wire at handshake; the TOML file controls spawn only.

Starters

bash scripts/feather-new.sh my-feather python
bash scripts/feather-new.sh my-feather node

Rust authors should copy crates/toowl-plugin-subprocess/src/bin/demo_plugin.rs or build the demo binary.

See also Authoring Feathers and the Aviary.