Core concepts

toowl borrows an owl-and-aviary metaphor, so a handful of terms come up again and again across these docs. This page defines them once so the rest reads clearly. Skim it now, or come back whenever a word looks unfamiliar.

The vocabulary

toowl

The product. The name stands for Terminal yOu Will Love and is pronounced /tuːl/ — exactly like the word "tool". The owl is the mascot. It is a GPU-accelerated terminal emulator written in Rust.

The Perch

The sidebar. Toggle it with Ctrl+Shift+B on every platform — macOS, Linux, and Windows alike — because plain Ctrl+B is left free for tmux and the toowl TUI. The Perch is where your Feathers live.

Feathers

toowl's plugins and extensions. A Feather runs either in-process or as a subprocess, is capability-gated for safety, and supports hot-start and hot-stop — enable or disable one and it applies with no restart. Built-in Feathers include Claude, Nest (a file browser), MCP Hub, and Scout (web search).

The Claude Feather

The built-in Claude Code integration: a live session list, a crash-recovery banner when a session goes down, and command-palette integration. It ships in the free build.

The Aviary

The Feather registry. Use it to install Feathers and — soon — to publish signed ones of your own.

Workspace

A named, daemon-backed window — for example toowl up pm2. Closing the window detaches it; reopening reattaches. The sessions inside keep running in the daemon the whole time.

toowld

The daemon, also called the roost. One runs per host and owns your workspaces, sessions, and PTYs. Clients attach to it rather than owning the processes themselves.

Session

A running PTY — a shell or any long-lived process — owned by toowld. A session survives client disconnects, and a persistent session can even outlive a daemon restart.

Transport

The trait a client uses to reach a daemon. It can be a Unix socket (local), SSH-stdio (remote), or WebSocket / WSS (LAN, cloud, or browser).

Remote machine

Another host's toowld that you connect to. Its workspaces look identical to your local ones, just marked with an @host badge. You configure remotes in ~/.config/toowl/remotes.toml.

Two clients, one binary

The same toowl binary is a GPU desktop app when there is a display and a tmux-style crossterm TUI over SSH. It auto-detects which one to be, so you never pick.

FlyTo

The unified fuzzy navigator for directories, files, git branches, and bookmarks — one prompt to jump anywhere. See FlyTo for the full tour.