FAQ & troubleshooting

Questions

Is toowl free?

Yes — the terminal is free to use, with the Claude Feather included. Toowl Pro is a paid tier layering on managed AI credits, team playbooks and shared sessions.

Is toowl open source?

Not yet — the binary is free to use, but the source isn't published. That may change; we'll say so here first.

Which platforms are supported?

Linux and macOS today — prebuilt Linux binaries for x86_64 and aarch64, and a universal macOS build. Windows is coming soon.

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, remotes, and Toowl MCP. It auto-starts on first use, so you only ever notice it when you reach for those features.

How do I let Grok or Claude use Toowl?

Point the host at toowl mcp. Full setup for Grok, Claude Code, Cursor, and Claude Desktop — plus the tool list and handshake fixes — is in Toowl MCP.

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.

Grok or Claude shows Toowl MCP as disconnected

The child process is exiting on startup. Confirm toowld --version works, then restart the agent. A missing daemon binary is the usual cause — see Toowl MCP troubleshooting.

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.

How do I put tabs on the left?

Settings → Tab layout, the hamburger Tab layout: Left item, or ⌘⌥V / Ctrl+Alt+V. The rail scrolls when there are many tabs; grab empty rail background to move the window. Details: Layouts.

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.