Installation

macOS

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

Download the disk image and drag Tidebreak to Applications.

Download for macOS

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.

A release built with an Apple Developer ID is signed and notarized, so it opens without a Gatekeeper override. A release built without one is ad-hoc signed and not notarized, and its release notes say so. macOS blocks such a build the first time you open it. To open it, choose Open Anyway in System Settings → Privacy & Security, or run this in Terminal:

xattr -dr com.apple.quarantine /Applications/Tidebreak.app

Each update carries a new ad-hoc signature, so macOS may ask you again to grant Accessibility and Screen Recording and to allow keychain access.

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

• Download for x86_64 Windows
• Download for ARM64 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.

• Download x86_64 AppImage
• Download x86_64 Debian package
• Download ARM64 AppImage
• Download ARM64 Debian package

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:

Inside it:

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 io.github.naingthet.tidebreak. A separate CLI profile, named with TIDEBREAK_DATA_DIR, keeps its keys under a service of its own, tidebreak.profile.<id>.

Moving from an earlier version

Versions before the app identity changed kept the same data under io.brightwave.tidebreak instead: in ~/Library/Application Support/io.brightwave.tidebreak, %APPDATA%\io.brightwave.tidebreak, or ~/.local/share/io.brightwave.tidebreak, with keys under the service tidebreak. The first time a newer Tidebreak opens, it moves that folder to the new location, along with the window's own storage and your keys, before it opens anything. It tells you once when it has.

• If an earlier Tidebreak is still running, the new one opens nothing and asks you to quit the other one first.
• The old folder's path becomes a link to the new folder, so anything that recorded the old path, such as a worktree from before version 0.59, still finds it.
• If both folders already hold data, Tidebreak uses the new one and leaves the old one as it is. Nothing is merged or overwritten.
• On macOS, the moved app asks again for Accessibility and Screen Recording, and macOS may ask whether Tidebreak can use your keychain. If you decline that, your keys stay in the tidebreak entry and you sign in again.

The tidebreak command line does the same move when it is the first to run. While an earlier Tidebreak is still running, it uses that app's folder as it is.

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:

1. Drag /Applications/Tidebreak.app to the Trash.
2. Delete ~/Library/Application Support/io.github.naingthet.tidebreak, and ~/Library/WebKit/io.github.naingthet.tidebreak, which holds the window's own storage.
3. Delete ~/Tidebreak/workspaces if you used code mode and do not need those worktrees.
4. Remove keychain items for the service io.github.naingthet.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 io.github.naingthet.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.github.naingthet.tidebreak, %LOCALAPPDATA%\io.github.naingthet.tidebreak, and any worktrees you created. Credentials live in Credential Manager under io.github.naingthet.tidebreak.

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

If an earlier version left a folder or a key under io.brightwave.tidebreak or tidebreak, delete those the same way. After a move, the old folder's path is only a link to the new one.

A debug build uses io.github.naingthet.tidebreak.dev instead of io.github.naingthet.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.