FAQ & troubleshooting

Questions

Is toowl free?

Yes. toowl is open source under MIT OR Apache-2.0, and the free build includes the Claude Feather out of the box. A Pro build layers on a few extras through a Cargo feature flag — it is the same codebase and the same binary, not a fork and not a separate download.

Which platforms are supported?

macOS, Linux, and Windows. Prebuilt binaries currently ship for Linux (x86_64 and aarch64). On macOS and Windows you build from source today — via Homebrew or cargo — which still gets you the same fast, native client.

How do I install it?

See the Installation guide for full details and per-platform notes. The quickest path:

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

Do I need the daemon?

No — a plain local terminal needs nothing extra. The daemon, toowld, is what powers named workspaces, detach and reattach, persistent sessions, and remotes. It auto-starts on first use, so you only ever notice it when you reach for those features.

Where is my config?

Your settings live at ~/.config/toowl/config.toml — plain TOML, hot-reloaded in about 150ms with atomic writes, so saving never corrupts the file mid-read. Remote machine definitions live alongside it in ~/.config/toowl/remotes.toml.

Troubleshooting

"claude / gh / node not found" when launched from the macOS Dock

Apps launched from the Dock inherit a minimal PATH from launchd, so tools installed via Homebrew, nvm, or npm-global can be invisible. toowl runs Feather-spawned binaries under your login shell to restore your interactive PATH — just make sure the binary is on PATH in your ~/.zprofile or ~/.bash_profile.

A workspace or toowl up does nothing

Check that the daemon is healthy. It auto-starts on demand; on a server it can also run under a systemd --user unit. Re-running toowl up <name> simply reattaches to the existing workspace rather than creating a second one.

Remote attach fails

Confirm that plain SSH works to the host, or — for a WebSocket-backed remote — that the endpoint URL and bearer token in remotes.toml are correct. A bad token or unreachable host is the usual cause.

Missing glyphs or emoji on Linux

Install the Noto font set so symbol, emoji, and CJK fallback render correctly:

sudo apt install -y fonts-noto-core fonts-noto-color-emoji fonts-noto-cjk

Typing Chinese / Japanese / Korean on macOS

Not yet supported. The macOS window does not yet integrate with the system Input Method Kit, so IME composition (candidate windows for CJK) and dead-key sequences such as Option+e then e → é do not work there. ASCII input is unaffected, and Linux and the TUI client are not impacted. Full IME support is a fast-follow.

Ctrl+C does not copy

That is by design. Ctrl+C sends SIGINT to the running shell — the universal terminal convention for interrupting a command. To copy a selection, use Cmd+C on macOS or Ctrl+Shift+C on Linux and Windows.

Change theme or keybindings without restarting

Edit config.toml and your changes hot-reload almost instantly — no restart needed. For shortcuts you can also use the visual rebind UI from the command palette. See Themes and Keybindings for the full list of options.