Documentation
Overview
toowl is a GPU-accelerated terminal with the Claude Feather built in. Start here.
toowl (pronounced /tuːl/, like "tool") is a cross-platform terminal emulator written in Rust. It renders through wgpu, ships with six flagship themes, and includes the Claude Feather — first-class Claude Code integration on the Perch from day one.
New here? Install with one command, then open the Perch.
$ curl -fsSL https://toowl.dev/install.sh | sh Vocabulary
| Term | Meaning |
|---|---|
| the Perch | Left sidebar where Feathers render. Toggle with Cmd+B on macOS, Ctrl+Shift+B on Linux. |
| Feather | An extension (plugin). In-process or subprocess, capability-gated, hot-installable. |
| Claude Feather | First-party Feather for Claude Code — session list, crash recovery, palette commands. |
| the Aviary | Feather registry — feather-install.sh, verify, publish. |
For the full vocabulary, see Core concepts.
Get started
- Installation Install toowl on macOS or Linux and open your first session.
- Quickstart Five minutes from install to splits, the Perch, the palette, and your first workspace.
- Core concepts The vocabulary — Perch, Feathers, the Aviary, workspaces, toowld, transports.
- Claude Feather Run Claude Code inside a GPU-accelerated terminal: session list, crash resume, and palette commands on the Perch.
- Grok Feather Run Grok Build TUI inside toowl: session list, groka preference, crash resume, and one-click CLI install.
Using toowl
- Features Tabs, splits, GPU rendering, reflow, search, and everything that ships today.
- Layouts Horizontal and vertical tab strips — chrome, scrolling, previews, dragging, and keybindings.
- Keybindings Default shortcuts on Linux and macOS, plus how to rebind.
- FlyTo Unified fuzzy navigator for directories, files, git branches, and bookmarks.
- Configuration config.toml reference — appearance, scrollback, keybindings, plugins.
- Themes 16 palette-true built-in themes, live-reloaded, plus how to write your own.
- Workspaces Daemon-backed named windows — open, detach, and reattach with one command.
- TUI client Run toowl on headless servers and over SSH with tmux-style keybindings.
- Remote machines Connect to remote toowld daemons over SSH or WebSocket from any client.
- Browser access Open a toowld session in any browser over a scoped, expiring URL — with optional built-in TLS.
- Persistent sessions Keep terminal sessions alive across toowld restarts — crash, OOM-kill, or redeploy.
- Command timeline A centered overlay of the commands run in the focused pane — durations, exit status, and jump-to-command.
- Session recording Record the focused pane to an asciinema cast v2 .cast file, replayable across the asciinema ecosystem.
- Toowl MCP Let Grok, Claude Code, and Cursor spawn sessions, type into them, and read the screen.
Feathers
- Feathers The Perch, the Claude Feather, and how to build your own extensions.
- Feather authoring Build a subprocess or in-process Feather plugin.
- MCP Hub Connect Model Context Protocol servers through the MCP Hub Feather.
- Nest Cwd file browser in the Perch.
- Scout SearXNG web search from the Perch.
- the Aviary Install and publish Feathers from the registry.
- Wire protocol JSON-RPC reference for subprocess Feathers.
Under the hood
- Architecture 37 crates, the frame loop, the daemon model, and the Transport trait.
- Performance Cold-start targets, deferred init, and how we benchmark launch speed.
- How toowl compares toowl vs iTerm2, Kitty, WezTerm, Ghostty, and Alacritty — daemon workspaces, remote TUI, Claude.
- FAQ & troubleshooting Common questions and fixes — daemon, remotes, fonts, PATH, and more.
Support
- Installation — Linux and macOS today, Windows coming soon
- [email protected] — questions, bugs and feature requests