Installation

macOS

Tidebreak requires macOS 13 Ventura or later. Computer use needs macOS 14.

Download the disk image and drag Tidebreak to Applications.

Releases ship one universal build for Apple Silicon and Intel Macs. An Apple-Silicon-only compatibility asset is also attached to the GitHub release, but the universal disk image is the normal download.

The macOS app is signed and notarized, so it opens without a Gatekeeper override. Each download has a .sha256 sidecar on the same release if you want to check it:

shasum -a 256 -c Tidebreak-macos-universal.dmg.sha256

Installed release builds keep themselves current. They check for a newer signed release in the background and ask before restarting.

Windows

The NSIS installers are not yet Authenticode-signed, so Windows SmartScreen may warn on first run. Each release includes a .sha256 sidecar for independent download verification.

Linux

Choose the portable AppImage or the Debian package for your architecture.

Linux packages are built on Ubuntu 22.04. Use Ubuntu 22.04, Debian 12, or a newer distribution with a compatible glibc baseline. The Debian package declares its WebKitGTK 4.1, GTK 3, and system-tray runtime dependencies; the AppImage bundles application dependencies but still needs a compatible host glibc.

Make the AppImage executable before launching it:

chmod +x Tidebreak-linux-x86_64.AppImage
./Tidebreak-linux-x86_64.AppImage

Each Linux download has a .sha256 sidecar. Verify the file you chose before installing or launching it:

sha256sum -c Tidebreak-linux-x86_64.AppImage.sha256
# or
sha256sum -c Tidebreak-linux-x86_64.deb.sha256

Windows and Linux packages run the desktop chat, files, connected-folder, provider, remote-sandbox, and code-mode surfaces. Code mode uses the same digest-verified managed Node runtime and pinned coding harnesses as macOS, with PowerShell commands on Windows and POSIX shell commands on Linux. Native local execution, managed LibreOffice installation, and computer use remain unavailable on both Windows and Linux. Release builds check the signed updater feed in the background and ask before restarting into a newer package. Linux updates preserve the installed format: AppImage installs receive AppImage updates and Debian installs receive .deb updates.

Build from source

You need the Rust toolchain pinned in rust-toolchain.toml (rustup picks it up automatically), pnpm, and the Tauri CLI. Local voice transcription runs in a separately published tidebreak-whisper helper the desktop downloads on first use, so building the desktop app does not require CMake.

cargo install tauri-cli --version "^2"

Then, from a clone of the repository:

scripts/dev.sh

That installs the UI dependencies and opens the app window. Arguments are forwarded to cargo tauri dev.

On Linux you also need the platform WebView dependencies (WebKitGTK); see the Tauri prerequisites.

Where your data lives

Tidebreak owns one application data directory, created on first launch:

Platform	Path
macOS	`~/Library/Application Support/io.brightwave.tidebreak`
Windows	`%APPDATA%\io.brightwave.tidebreak`
Linux	`~/.local/share/io.brightwave.tidebreak`

Inside it:

Item	What it holds
`tidebreak.db`	The SQLite database: chats, messages, turns, event history, document metadata, and canonical text
`tidebreak-schema.json`	Which schema pin this profile holds
`orphaned-code-worktrees.json`	Code worktrees a reset left on disk
`blobs/`	The original bytes of every document you attached
`backups/`	A copy of the database from before each of the last two updates that changed it, and any profile Tidebreak could not open
`logs/`	`tidebreak.log` and the structured diagnostics log
`listen.json`	Loopback URL and bearer for `--attach` while the server is running
`tools/`	On-demand installs: whisper helper, Node, LibreOffice, coding engines
`tidebreak.lock`	Proof that one process owns this directory

Code worktrees live outside that directory, by default under ~/Tidebreak/workspaces. You can change the root in settings; existing workspaces stay where they are.

Settings → Data and privacy shows this directory and how much disk each part of it uses. From there you can open it in your file manager, back it up as one .tar.gz, export your conversations as Markdown or JSON, reset your settings, or delete everything. The page also lists what Tidebreak sends off your computer, and how to turn each one off. The CLI does the backup and the export too: see tidebreak data.

Provider API keys are not in the application data directory. They go to your OS credential store — Login Keychain on macOS, Credential Manager on Windows, or Secret Service on Linux — under the service name tidebreak. A separate CLI profile, named with TIDEBREAK_DATA_DIR, keeps its keys under a service of its own, tidebreak.profile.<id>.

Desktop upgrades from v0.61.0 onward keep this data. Tidebreak upgrades the database in place and saves a copy in backups/ before an update changes it. A profile from v0.60.0 or earlier moves into backups/ instead, and Tidebreak starts a fresh one. To restore a copy, see Troubleshooting. Include this directory in your own backups, like any other data you cannot lose.

Uninstall

Delete the app, then the data Tidebreak left behind. The application data directory holds backups/, so copy out any backup you want to keep first.

To remove the data and your keys in one step, use Delete all data in Settings → Data and privacy before you delete the app. It asks you to type delete all data, then asks once more in a system dialog. It stops every agent, deletes the application data, cache, and log directories, the code browser's website data, and this installation's keychain items, and quits. The tidebreak command line works on the app's data and keys unless TIDEBREAK_DATA_DIR names another folder, so its default profile goes too. A profile in another folder keeps its data. It keeps its keys only after tidebreak rehome-secrets has copied them into the profile's own keychain entry. Until then they are in the app's entry, and Delete all data removes them too. To keep them, run this for each such profile first:

TIDEBREAK_DATA_DIR=/path/to/profile tidebreak rehome-secrets

Delete all data leaves the worktrees in ~/Tidebreak and your repositories alone. Worktrees from before version 0.59 live inside the data directory, and the system dialog says so when it finds any.

On macOS:

Drag /Applications/Tidebreak.app to the Trash.
Delete ~/Library/Application Support/io.brightwave.tidebreak.
Delete ~/Tidebreak/workspaces if you used code mode and do not need those worktrees.
Remove keychain items for the service tidebreak, and for any tidebreak.profile.<id> services a separate CLI profile created. In Keychain Access, search for tidebreak: that finds both kinds. security find-generic-password -s tidebreak matches the exact service name, so it finds only the app's item.

On Windows, remove the app from Settings → Apps, then delete %APPDATA%\io.brightwave.tidebreak and any worktrees you created. Credentials live in Credential Manager under tidebreak.

On Linux, remove the AppImage or Debian package, then delete ~/.local/share/io.brightwave.tidebreak and any worktrees. Credentials live in Secret Service under tidebreak.

A debug build uses io.brightwave.tidebreak.dev instead of io.brightwave.tidebreak. Do not delete a release profile if you only meant to wipe a development run.

Running it headless

The same server the desktop app embeds can run on its own:

ANTHROPIC_API_KEY=sk-... cargo run -p tidebreak-cli -- serve

It prints a loopback URL and a per-launch bearer token. With TIDEBREAK_DATA_DIR unset, it serves the app's own data (a debug build like this one serves the dev app's), so it runs only while that app is closed. See Running headless for which data each command uses and for the other commands.