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.

Starting from scratch

A subprocess Feather is any executable that speaks this protocol on stdin/stdout — Python, Node, Go, Rust, a shell script, whatever you like. The minimum is a directory in ~/.config/toowl/plugins/ containing the manifest TOML above plus your executable. Handle initialize, reply with your manifest, then answer render; everything else is optional.

See also Authoring Feathers and the Aviary.