toowl

Documentation

Getting started

Install toowl, open your first window, and meet the Perch.

Install

Pick the path that matches your machine. All three land the same toowl binary.

$ curl -fsSL https://toowl.dev/install.sh | sh

Detects your OS + arch, downloads the matching binary from GitHub Releases, verifies the SHA256, installs to ~/.toowl/bin/toowl. ~5 seconds on a fresh machine.

$ brew install 1martianway/tap/toowl

Installs from toowl's Homebrew tap. Auto-updates via brew upgrade. Use this if you already manage tools with brew.

One-line script

$ curl -fsSL https://toowl.dev/install.sh | sh

First launch

  1. Open a window. Run toowl from your terminal, or launch Toowl.app on macOS.
  2. Open the Perch. Press Ctrl+Shift+B (all platforms). The Claude Feather lists Claude Code sessions for the active pane's cwd.
  3. Open the palette. Cmd+Shift+P / Ctrl+Shift+P — fuzzy search over actions and Feather commands.
  4. Tweak config. Optional — toowl runs on sensible defaults with no config file at all. The installer drops an annotated ~/.config/toowl/config.toml.example covering every option; copy it to config.toml and edit, or just open Settings (Ctrl+, / Cmd+,). Full reference on the Configuration page. Edits hot-reload in ~150ms.

System dependencies

Ubuntu / Debian:

sudo apt install -y libwayland-dev libxkbcommon-dev libfontconfig-dev libgl-dev pkg-config

The macOS build ships with its platform integration built in — nothing to install.

Upgrade

Curl installs (~/.local/bin by default): toowl checks for new releases on startup (configurable in Settings or [updates] in config). When a newer build is downloaded, open About from the hamburger menu and choose Install + restart.

Homebrew: brew upgrade toowl.