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.

$ cargo install --git https://github.com/1martianway/toowl toowl-app

Requires Rust 1.95+. Slow first build (~3 min compile), no pre-built binary needed. Use this if you want HEAD or are on an unsupported arch.

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 Cmd+B (macOS) or Ctrl+B (Linux/Windows). 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. Copy config.toml.example from the repo to ~/.config/toowl/config.toml. Edits hot-reload in ~150ms.

System dependencies

Ubuntu / Debian:

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

macOS and Windows desktop builds ship with platform integration built in. See plans/setup.md in the repo for contributor setup.

Upgrade

Curl installs (~/.toowl/bin): toowl checks GitHub 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. Cargo: cargo install toowl-app --force.

Developers on macOS can also re-run:

bash scripts/install.sh

That bumps the version, reinstalls, and re-bundles ~/Applications/Toowl.app.