Feathers

Feathers are toowl's extension system. They render in the Perch (left sidebar), respond to palette commands, and can spawn panes or show banners — all without restarting the terminal.

The Perch opens at 480 logical px and drags between 280 and 640 px by its inner edge. It sits on the left by default; with the tab bar on the left it moves right so the two never share a gutter (perch_side in config).

Switching Feathers

One Feather owns the Perch at a time. Under the header sits a chip per enabled Feather — click one to switch. The strip only appears when more than one Feather is enabled, since a switcher with nothing to switch to would just cost a row. Chips are sized to their names and wrap onto further rows rather than shrinking to fit, so a long name stays readable.

From the keyboard, bind cycle_feather_next / cycle_feather_prev, or set_active_feather:N to jump straight to one.

The Claude Feather

Ships built in via toowl-plugin-agent — AgentPlugin::from_builtin("claude"), the same type that drives Grok and Codex. Bring your own claude binary; the Feather handles the rest.

• Session list — every Claude Code conversation in the active pane's cwd, labeled by title or last user prompt.
• Live badge — running sessions show live; the list updates via filesystem watch on ~/.claude/projects/.
• One-click resume — click a row to spawn or focus a Claude session in the current directory.
• Crash recovery — unexpected exit shows a [R] Resume / [X] Dismiss banner with one-key restart.
• Palette integration — Claude commands appear alongside terminal actions in Cmd+Shift+P.

Subprocess Feathers

Drop a Feather in ~/.config/toowl/plugins/<id>/ with a plugin.toml manifest and a binary. The host speaks newline-delimited JSON-RPC over stdio. Capabilities are declared in the manifest and enforced on every host API call.

# ~/.config/toowl/plugins/my-feather/plugin.toml
id = "my-feather"
name = "My Feather"
version = "0.1.0"
program = "./my-feather"
capabilities = ["pane_spawn", "notify"]

Enable / disable

[plugins.my-feather]
enabled = true

Changes hot-reload. Toggle Feathers in Settings, the hamburger Feathers… manager, or config.toml.

Developer env vars

Build your own

Read the wire protocol and the Aviary for install and publish workflows. In-process Feathers implement toowl_plugin::Plugin directly; out-of-process Feathers use JSON-RPC.