Install Tide
With Homebrew:
brew install ultradotdev/tap/tideOr use the shell installer:
curl -fsSL https://ultra.dev/tide/install.sh | shcurl -fsSL https://ultra.dev/tide/uninstall.sh | shRemoves a script installation. Your settings, sessions and history are kept.
This documentation follows v0.10.0. Install with Homebrew or the shell installer. No compiler or build tools are needed. The shell installer downloads a prebuilt executable and adds a managed launcher at ~/.local/bin/tide; Homebrew manages its own installation.
Requirements
Tide runs on macOS and Linux. You need a supported terminal, plus Homebrew for the brew command or curl for the shell installer.
Prebuilt targets require macOS 14+ or Linux with glibc 2.35+ (Ubuntu 22.04+), on ARM64 or x64. WSL support is deferred. A true-color terminal and a Nerd Font give the best display; tui.iconStyle: "ascii" provides a plain-text icon fallback.
Your first project
From your project's directory, run:
tide .Tide opens the current folder as your workspace.
If tide is not on PATH yet, check your Homebrew shell setup. For a shell installation, run ~/.local/bin/tide . and add ~/.local/bin to your shell's PATH.
- Use Ctrl+P to find a file and Ctrl+S to save.
- Open the command palette with Ctrl+K while editing. From a shell or agent tab, use Ctrl+T or F1.
- Split right with Ctrl+\, or down with Ctrl+Shift+\. Use pane menus to move tabs between panes.
- Press F6 to cycle regions and F7 / F8 to move between main panes.
- Use Ctrl+Shift+A to add a tab. Choose a file, terminal, SQL editor, or installed coding agent.
Some terminals cannot transmit Ctrl+Shift or Cmd combinations. The shortcut reference includes alternatives and context-specific bindings.
Find your workflow
Manage your installation
Updates and rollback
For a Homebrew installation:
brew upgrade ultradotdev/tap/tideFor a shell installation, run the shell install command again to update. The previous active payload is retained for rollback, and activation checks installation ownership and payload integrity.
To return to the previous shell-installed release:
curl -fsSL https://ultra.dev/tide/install.sh | sh -s -- --rollbackUninstall
Remove a Homebrew installation with:
brew uninstall ultradotdev/tap/tideFor a shell installation:
tide --uninstallThis keeps your settings, sessions, credentials, and history. To remove Tide's user data too, use tide --uninstall --purge instead and confirm the prompt. Project .tide directories and providers' own session stores remain. These flags apply to the shell-managed launcher; use Homebrew to remove a brew installation.
Configuration and storage
Open Settings from the palette. Tide loads embedded defaults, then your settings.jsonc. Keybindings live alongside it in keybindings.jsonc.
| Root | Location | Contents |
|---|---|---|
| config | ${XDG_CONFIG_HOME:-~/.config}/tide/ | Settings, keybindings, themes and saved connections |
| data | ${XDG_DATA_HOME:-~/.local/share}/tide/ | Encrypted secrets and database history |
| state | ${XDG_STATE_HOME:-~/.local/state}/tide/ | Sessions, recovery and logs |
| cache | ${XDG_CACHE_HOME:-~/.cache}/tide/ | Rebuildable application data |
| workspace | <workspace>/.tide/ | Project-scoped database connection records |
XDG overrides must be absolute paths. Font family and size are controlled by your terminal application.
{
"workbench.colorTheme": "ultra-dusk",
"editor.tabSize": 2,
"editor.wordWrap": "on",
"editor.minimap.enabled": true,
"tui.sidebar.location": "left",
"tui.terminal.scrollback": 1000
}Supported settings and defaults
| Setting | Default |
|---|---|
ai.autoStartCli | true |
ai.cli.defaultProvider | "claude-code" |
ai.cli.workspaceAliases | [] |
editor.autoIndent | "full" |
editor.diagnostics.curlyUnderline | true |
editor.insertSpaces | true |
editor.lineNumbers | "on" |
editor.minimap.enabled | true |
editor.tabSize | 2 |
editor.undoHistoryLimit | 1000 |
editor.wordWrap | "on" |
editor.wordWrapColumn | 80 |
files.exclude | {"**/.DS_Store":true,"**/.git":true,"**/node_modules":true} |
files.watchFiles | "onFocus" |
git.inlineDiff.contextLines | 3 |
git.inlineDiff.maxHeight | 15 |
lsp.completionDebounceMs | 250 |
lsp.diagnostics.enabled | true |
lsp.diagnostics.showInGutter | true |
lsp.diagnostics.underlineErrors | true |
lsp.enabled | true |
lsp.hover.enabled | true |
lsp.signatureHelp.display | "popup" |
lsp.signatureHelp.enabled | true |
lsp.triggerCharacters | ".:/<@(" |
session.autoSave | true |
session.autoSaveInterval | 30000 |
session.databaseQueryHistory | true |
session.restoreOnStartup | true |
terminal.shell | "" |
tui.agentsSidebar.visible | true |
tui.agentsSidebar.width | 36 |
tui.diffViewer.autoRefresh | true |
tui.diffViewer.editMode | "stage-modified" |
tui.diffViewer.showDiagnostics | true |
tui.filePicker.maxFiles | 10000 |
tui.fileTree.showGitStatus | true |
tui.iconStyle | "nerd" |
tui.mainRegion.minimumWidth | 56 |
tui.outline.autoFollow | true |
tui.outline.collapsedOnStartup | true |
tui.sidebar.location | "left" |
tui.sidebar.visible | true |
tui.sidebar.width | 36 |
tui.tabBar.scrollAmount | 1 |
tui.terminal.height | 10 |
tui.terminal.scrollback | 1000 |
tui.timeline.collapsedOnStartup | true |
tui.timeline.commitCount | 50 |
tui.timeline.mode | "file" |
workbench.colorTheme | "ultra-dusk" |
Moving from an earlier implementation
Back up your configuration, data, and state roots before switching. Rust can read historical TypeScript sessions, but writes its own snapshots. Settings and themes are reused where supported; preserved settings do not necessarily enable a current feature.
If you are developing Tide or managing a source build, see the developer installation instructions.
Check your setup
tide --version
tide --check-catalogs
tide --check-terminal
tide --check-lsp
tide --check-ai-cliMissing agent or language-server features usually mean the executable is absent from PATH. Install and authenticate provider CLIs separately, then restart Tide after changing PATH.
Use tide --debug for debug logging. To investigate session restoration, start with tide --no-session .; keep your original state intact.
If a sidebar disappears in a small terminal, increase the window size. Tide preserves the requested layout while collapsing regions that no longer fit.