How to uninstall Wave Terminal on Mac

Wave Terminal keeps your settings, SSH connections and encrypted secrets in ~/.config/waveterm, and its workspaces and tabs in ~/Library/Application Support/waveterm. Copy the first folder before you remove anything if you want your setup back later. Your shell history, dotfiles and projects are not part of Wave and stay where they are. This guide covers the app downloaded from waveterm.dev (it installs as Wave.app) and the Homebrew cask wave.

Save your setup first

Wave's configuration docs put every settings file in ~/.config/waveterm: settings.json, connections.json with the SSH and WSL connections you added in Wave, plus themes, presets and widgets. Installs from before v0.9.0 used ~/.waveterm/config instead. Copy whichever folder you have to a place outside it.

Secrets you stored in Wave are kept encrypted in the Wave configuration directory, and the key that unlocks them sits in your macOS Keychain. A copy of the folder alone may not bring those secrets back on another Mac, so note down any password you only kept in Wave. Hosts in ~/.ssh/config belong to your SSH setup, not to Wave, and are not touched by removing the app.

Quit Wave and remove the app

  1. Quit Wave from the Wave menu. The app runs a background server, wavesrv, next to its windows.
  2. Search Activity Monitor for Wave and check that Wave, its Helper processes and wavesrv have exited; in the test they all ended when the app quit.
  3. Move Wave from Finder's Applications folder to the Trash.

The recorded tests found no login item or launch agent from Wave, so there is nothing to turn off in Login Items & Extensions.

If Wave installed its helper wsh on remote machines, it lives at ~/.waveterm/bin/wsh on each remote host, as Wave's connection docs describe. Removing the app on this Mac does not reach those machines; delete that folder on a host only if you no longer connect to it with Wave.

Where Wave keeps its data

Open each path with Shift + Command + G in Finder and skip the ones that do not exist.

Location What it holds What to do
~/.config/waveterm Settings, connections, themes, widgets and the encrypted secrets file Back up first; keep it for a reinstall
~/Library/Application Support/waveterm Wave's data directory with its local database of workspaces and tabs, according to Wave's source code Remove only if you do not need your layout back
~/Library/Application Support/Wave Browser-engine caches of the Electron shell, seen on the test Mac Safe to remove after quitting
~/Library/Caches/waveterm An empty cache folder the app created on first launch in the test Safe to remove
~/Library/Preferences/dev.commandline.waveterm.plist App preferences Remove for a clean start
~/.waveterm Configuration home of installs before v0.9.0; the only path in the Homebrew zap list Check it before removing; newer installs may not have it

The two Application Support folders and the cache folder are local observations from the test Mac, not paths Wave documents.

Check the result

Run these read-only commands after the app is in the Trash:

pgrep -il wave
ls -d ~/.config/waveterm "$HOME/Library/Application Support/waveterm" ~/.waveterm
  • No output from pgrep means no Wave process is running. A listed wavesrv or Wave Helper line means part of the app is still open; quit it before touching its data. Other programs with "wave" in their name can also match, so read the names.
  • ls prints each folder that still exists and reports "No such file or directory" for the rest. A surviving ~/.config/waveterm is expected if you kept your settings. A permission error is a different result; look into it before assuming the folder is gone.

If you installed it with Homebrew

The wave cask's zap list holds a single path, ~/.waveterm, the configuration home of old installs. Running brew uninstall --cask --zap wave yourself moves that folder to the Trash, whatever you selected in Mole, and leaves ~/.config/waveterm and both Application Support folders in place. To keep everything, leave the zap step out:

brew uninstall --cask wave

Mole adds --zap only when every path on the zap list sits inside ~/Library, none of them touches a row you left unchecked, and no other installed app claims them. ~/.waveterm is outside ~/Library, so Mole removes a Homebrew install of Wave without --zap and handles the rows you ticked itself.

What Mole lists

For Wave from waveterm.dev:

  • ~/.config/waveterm, ~/Library/Application Support/waveterm and ~/Library/Caches/waveterm are listed but not selected, so your settings and workspaces stay unless you tick them.
  • ~/Library/Application Support/Wave is listed but not selected. The Chromium cache folders inside it, such as Cache, Code Cache and GPUCache, are separate rows selected by default.
  • The logs folder inside ~/Library/Application Support/waveterm, the dev.commandline.waveterm preferences file, the recent-documents list and the temporary caches filed under the bundle ID are selected by default.
  • ~/.waveterm and anything wsh installed on remote hosts are not listed.

What this test covered

On September 19, 2026, Wave was copied from the official disk image into Applications, opened, and uninstalled with a Preview build of Mole 1.15; there was no Homebrew receipt. On September 26, 2026, it was installed again from the same official download, opened once without adding connections or secrets, and removed with a development build of Mole with every row ticked. Mole's Status view showed Wave as one row of 8 processes, about 443 MB, with wavesrv folded in. All 15 items went to the Trash, no process or startup item was left, and only the empty ~/Library/Caches/waveterm stayed, because Mole did not list it then. SSH connections, secrets, remote wsh installs and the Homebrew cask were not tested.