; <body> BEL` * Example (bash/zsh): `printf '\033]777;notify;Deploy;Success on prod\007'` Notes: * Works on macOS, Windows, and Linux where Warp is allowed to show notifications. * Newlines and semicolons should be avoided or escaped in payloads. * This feature is enabled by default in current releases of Warp. ## How to access it [Section titled “How to access it”](#how-to-access-it) ### Notifications [Section titled “Notifications”](#notifications) * Notifications are enabled by default and require system permissions to appear. * If you’ve turned Notifications off before, toggle it back on by going to **Settings** > **Features** > **Session**, or quickly toggle Notifications with the [Command Palette](/terminal/command-palette/). * Customize Notification triggers for long-running commands or password prompts by going to **Settings** > **Features** > **Notifications**. Note On macOS, you will want to **Allow** or **Accept** the request so that Warp can send you desktop notifications. If you accidentally denied it or would like to re-enable Notifications later, check the [troubleshooting guide below](/terminal/more-features/notifications/#troubleshooting-notifications). ## How it works [Section titled “How it works”](#how-it-works) [Notifications Demo](https://www.loom.com/embed/65967f43a7fa432b98cf3e94766a8e79) ## Troubleshooting Notifications [Section titled “Troubleshooting Notifications”](#troubleshooting-notifications) * macOS Warp requires two distinct notification settings to work. macOS system settings found in > **System Settings** > **Notifications & Focus** and Warp app settings found in **Settings** > **Features** > **Session** must both be enabled for Notifications to show.\ \ If you have Notifications enabled in the system and Warp, but you still aren’t receiving desktop notifications, try the following: * Make sure that you are navigated away from Warp when you expect to receive the notification. * Make sure the **Do Not Disturb** mode is turned off in > **System Settings** > **Notifications** > **Notifications & Focus** > **Focus**. * Go to > **System Settings** > **Notifications & Focus** > **Notifications** and select Warp in the list. Make sure either banner style or alert style notifications are selected, then quit and restart Warp. * To get the macOS notification prompt to show again for Warp, run `defaults delete dev.warp.Warp-Stable Notifications`, then restart Warp and toggle on the **Settings** > **Features** > **Receive desktop notifications from Warp**. * Once all of the above is done, please restart macOS to apply the changes and that should help with restoring notifications in Warp. * Windows Warp requires two distinct notification settings to work. Windows system settings found in **Settings** > **System** > **Notifications** > **Warp** and Warp app settings found in **Settings** > **Features** > **Session** must both be enabled for Notifications to show. If you have Notifications enabled in the system and Warp, but you still aren’t receiving desktop notifications, try the following: * Make sure that you are navigated away from Warp when you expect to receive the notification. * Make sure the **Do Not Disturb** mode or **Focus** is turned off. * Go to **System** > **Notifications** and select Warp in the list. Make sure notifications are turned on, then quit and restart Warp. * Linux Warp requires two distinct notification settings to work. Linux system settings found in **Settings** > **Notifications** > **Warp** and Warp app settings found in **Settings** > **Features** > **Session** must both be enabled for Notifications to show. If you have Notifications enabled in the system and Warp, but you still aren’t receiving desktop notifications, try the following: * Make sure that you are navigated away from Warp when you expect to receive the notification. * Make sure the **Do Not Disturb** mode (if your distribution supports it) is turned off. * Go to **Settings** > **Notifications** and select Warp in the list. Make sure notifications are turned on, then quit and restart Warp. Please [reach out to us](/support-and-community/troubleshooting-and-support/sending-us-feedback/#sending-warp-feedback) if you have any other issues. # Terminal quit warning > Warp's quit warning feature is a valuable precaution to prevent unintentional data loss or lost progress on long-running jobs. ## What is it [Section titled “What is it”](#what-is-it) The quit warning feature ensures that you receive a warning before quitting the app with a running process, allowing you to save your work and avoid any unintended data loss.\ If you quit the app or close a window containing a session with a running process, you’ll see the alert and need to confirm the action before proceeding. If you aren’t sure which processes you have running, there is also an option to show those processes. ## How to access it [Section titled “How to access it”](#how-to-access-it) * Open **Settings** > **Features** > **General**, there you can toggle the “Show warning before quitting”. * You can also toggle the quit warning feature in the [Command Palette](/terminal/command-palette/), by searching for \`Quit Warning’. * If enabled, when you try and close Warp you will see a pop-up window with a few options listed below: * Yes, quit, which will close all the Warps sessions and running processes. * Show running processes, which will bring up the [Session Navigation](/terminal/sessions/session-navigation/) panel with a filter for running processes. * Cancel, which will prevent Warp from closing. * Don’t ask again, which is a box you can check to disable the quit warning feature. ## How it Works [Section titled “How it Works”](#how-it-works) [Quit Warning Modal Demo](https://www.loom.com/embed/bacb9d1c1e3947dca8365e15231cfcd3) # Settings Sync > Keep your Warp settings consistent across devices and sessions with cloud-based sync. ## How to toggle settings sync [Section titled “How to toggle settings sync”](#how-to-toggle-settings-sync) * You can toggle Settings Sync within the **Settings** > **Account** pane * Through the [Command Palette](/terminal/command-palette/) by searching for “Settings Sync” ![Settings Sync in Account pane](/_astro/settings-sync-account.CXPtR0Zh_Z1dUiGF.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Settings Sync in Account pane. ![Settings Sync in Command Palette](/_astro/settings-sync-palette.IHlP0TEp_ZgCkRN.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Settings Sync in Command Palette. ## How settings sync works [Section titled “How settings sync works”](#how-settings-sync-works) **Settings Sync** works by syncing the state of most of your Warp settings to our cloud servers. When you log in to Warp on another device or through the browser with [Session Sharing](/knowledge-and-collaboration/session-sharing/), if you have Settings Sync enabled, most of your settings will be the same as they were when you were logged in before. That means your themes, most features, privacy settings, AI settings, **are all the same everywhere you use Warp**, saving you the time from having to set them up again. When you first enable Settings Sync, the settings from the computer you enabled it on becomes the default settings for all devices. This is true if you toggle Settings Sync off and on as well - the synced settings are always from **the last device you enabled Settings Sync on**, so toggling effectively causes all of your devices to have settings from the current logged in instance. Note Read more about privacy for cloud features in the [privacy overview](https://www.warp.dev/privacy/overview). ### Non-synced settings [Section titled “Non-synced settings”](#non-synced-settings) Not all settings are synced, however. Notably, Warp does not sync: * Custom keybindings (we may in the future). Although, you can set [custom keybinds with a file](/getting-started/keyboard-shortcuts/#custom-keyboard-shortcuts) * Custom themes (we may in the future) * Device specific settings (e.g. what editor you prefer using, startup shell) * Platform-specific settings are synced across devices on the same platform (e.g. your settings for how to interact with the Linux clipboard are synced across all Linux devices, but not on macOS, Windows, or Web). You can tell when a setting is not synced because it will have a special cloud strikethrough icon in the settings panel. ![Settings not synced](/_astro/settings-not-synced.DiTc6z_j_tV6fN.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Indicator showing settings are not synced. # Text selection > Use smart selection and rectangular (column) selection to quickly highlight text in Warp. ## Smart selection [Section titled “Smart selection”](#smart-selection) **Smart selection** goes beyond the typical double-click selection, which only highlights a single word. Instead, it uses semantic rules to treat common patterns (like URLs or file paths) as one unit, even when separated by punctuation or whitespace. ![Using smart selection to select a file path by double clicking.](/_astro/smart-selection.D6-9NXc1_Ze9MX3.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Using smart selection to select a file path by double clicking. Double-click on text in the input or blocklist. The following patterns are recognized: 1. URLs 2. File paths 3. Email addresses 4. IP addresses 5. Floating point numbers, including scientific notation. You can toggle smart selection on the **Settings** > **Features** > **Terminal** > **Double-click smart selection**. If disabled, you can instead manually select specific punctuation characters to be included within word boundaries. ## Rectangular selection [Section titled “Rectangular selection”](#rectangular-selection) **Rectangular selection** lets you highlight text in a clean vertical block (also called *column* or *box* selection). This is especially useful for copying command output, logs, or prefixed text without grabbing unwanted characters. ![Using rectangular selection to select by columns in the block output.](/_astro/rectangular-selection.Cl11DsbL_saXwb.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Using rectangular selection to select by columns in the block output. Hold the modifier keys while dragging your mouse: * macOS: `CMD-OPT` * Windows and Linux: `CTRL-ALT` # Warp URI Scheme > Warps URI scheme enables you to programmatically open new windows, tabs, or launch configurations with ease. ## How to use it [Section titled “How to use it”](#how-to-use-it) There are several ways to use the URI scheme: * Open new window `warp://action/new_window?path=<path_to_folder>` * Open new tab `warp://action/new_tab?path=<path_to_folder>` * Open Launch Configuration `warp://launch/<launch_configuration_path>` Note [Warp Preview](/support-and-community/community/warp-preview-and-alpha-program/) URI scheme begins with `warppreview://` ## How it works [Section titled “How it works”](#how-it-works) Example of Warp [URIs in use in Warp + Raycast Extension](https://github.com/raycast/extensions/blob/74521b70b62355004b0958393a64f9417b1ff3a6/extensions/warp/src/uri.ts). [Warp + Raycast Extension Demo made using URIs](https://twitter.com/i/status/1678432353461637121) # Working Directory > Set a default working directory for new Warp sessions, with options for home directory, previous session, custom path, or per-window/tab/pane configuration. ## What is it [Section titled “What is it”](#what-is-it) Warp’s working directory feature is designed to enhance your workflow by enabling you to set up a default directory for new sessions. This feature helps you save time and quickly access your preferred directories when starting new sessions. You have the flexibility to set up a working directory for all new sessions or customize it individually for Windows, Tabs, and Panes, based on your specific needs. ## How to access it [Section titled “How to access it”](#how-to-access-it) * Open **Settings** > **Features** > **Session** and go to “Working directory for new sessions”. * The drop-down for this feature provides several options discussed below: * Home Directory, is the default option for new sessions and opens new sessions in the currently logged-in users home folder `~/`. * Previous session’s directory, opens new sessions in your active sessions’ current directory. * Custom directory, opens new sessions in a file path you specify. * Advanced, allows you to select from the three options for new sessions in Windows, Tabs, and Panes. ## How to use it [Section titled “How to use it”](#how-to-use-it) [![](/assets/terminal/working-directory-demo.poster.jpg)](/assets/terminal/working-directory-demo.mp4) # Sessions overview > Navigate between sessions and automatically restore windows, tabs, and panes when you relaunch Warp. 1. [Session Navigation](/terminal/sessions/session-navigation/) enables you to easily navigate to any session in Warp. 2. [Session Restoration](/terminal/sessions/session-restoration/) automatically restores the window and tabs from your previous session. For tab layout configuration, see [Tab Configs](/terminal/windows/tab-configs/) and [Launch Configurations (Legacy)](/terminal/sessions/launch-configurations/) under [Windows and Tabs](/terminal/windows/). ## Session Navigation [Section titled “Session Navigation”](#session-navigation) [Session Navigation Demo](https://www.loom.com/embed/2147adc6749c4f4ea5da432eadda7995) ## Session Restoration [Section titled “Session Restoration”](#session-restoration) [![](/assets/terminal/sessions-block_restoration.poster.jpg)](/assets/terminal/sessions-block_restoration.mp4) # Launch Configurations (Legacy) > Launch Configurations (Legacy) let you save a configuration of windows, tabs, and panes. For new setups, use Tab Configs instead. Caution Launch Configurations have been replaced by [Tab Configs](/terminal/windows/tab-configs/). Existing Launch Configurations continue to work, but new features are not being added. For new setups, use [Tab Configs](/terminal/windows/tab-configs/). ## What is it [Section titled “What is it”](#what-is-it) With Launch configurations you can save in the app or by adding a yaml file. ## Creating a Launch Configuration [Section titled “Creating a Launch Configuration”](#creating-a-launch-configuration) ### From the UI [Section titled “From the UI”](#from-the-ui) 1. Set up the configuration of windows, tabs, and panes you would like to save. 2. Open the [Command Palette](/terminal/command-palette/), and type in `Save New Launch Configuration`. 3. Name the configuration file. The name field cannot be empty. 4. Click the Save configuration button. ### With a YAML File [Section titled “With a YAML File”](#with-a-yaml-file) * Launch Configurations files are generated when you create them with the UI and can also be created or modified manually. * Please see the below for [Launch Configuration YAML file locations, format, and examples](/terminal/sessions/launch-configurations/#launch-configuration-yaml-format). ## Using a Launch Configuration [Section titled “Using a Launch Configuration”](#using-a-launch-configuration) * macOS * From the [Command Palette](/terminal/command-palette/), enter `Launch Configuration` to open and select Launch Configuration. * Right-clicking the new Tab **+** button to open a menu and select saved Launch Configuration. * From the macOS menu bar, **File** > **Launch Configurations**, where you can search through and open your saved Launch Configuration. * Single-window launch configs can be launched into the active window from the launch configuration palette using `CMD-ENTER` on macOS. * Windows * From the [Command Palette](/terminal/command-palette/), enter `Launch Configuration` to open and select Launch Configuration. * Right-clicking the new Tab **+** button to open a menu and select saved Launch Configuration. * Single-window launch configs can be launched into the active window from the launch configuration palette using `CTRL-ENTER` on Linux. To open a WSL tab with a Launch Configuration, you must first set WSL as your default shell in Warp: * Go to **Settings** > **Features** > **Session** > **Startup shell for new sessions**. * Select your desired WSL distribution (e.g., Ubuntu) as the default shell. After this, any Launch Configuration you open will use WSL as the shell. * Linux * From the [Command Palette](/terminal/command-palette/), enter `Launch Configuration` to open and select Launch Configuration. * Right-clicking the new Tab **+** button to open a menu and select saved Launch Configuration. * Single-window launch configs can be launched into the active window from the launch configuration palette using `CTRL-ENTER` on Linux. Tip **Terminal Tip**\ You can open saved Launch Configurations via Alfred Workflow or [Raycast](/terminal/integrations-and-plugins/#raycast) Extension. Learn more [here](https://blog.joe.codes/open-warp-launch-configurations-from-raycast-and-alfred). Credit to [@joetannenbaum](https://twitter.com/joetannenbaum/status/1633538768866009115) ## How it works [Section titled “How it works”](#how-it-works) [Launch Configuration Demo](https://www.loom.com/embed/daa2a9e55c27458c8bbf722d90078880) ## Launch Configuration YAML Format [Section titled “Launch Configuration YAML Format”](#launch-configuration-yaml-format) All Launch Configuration yaml files are stored in the following location: * macOS ```bash $HOME/.warp/launch_configurations/ ``` * Windows ```powershell $env:APPDATA\warp\Warp\data\launch_configurations\ ``` * Linux ```bash ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/launch_configurations/ ``` Caution The `cwd:` value in the yaml code must contain an absolute path or `""`. Note that `~` or empty paths will result in the file not being visible on the list of options for Launch Configurations. ### Windows [Section titled “Windows”](#windows) Sample configuration that shows how windows are structured in launch configuration files. ```yaml # Warp Launch Configuration # # This configuration has two windows, # each with one tab in different starting directories. --- name: Example Windows windows: - tabs: - title: Documents layout: cwd: /Users/warp-user/Documents color: blue - tabs: - title: Warp User layout: cwd: /Users/warp-user color: green ``` ### Tabs [Section titled “Tabs”](#tabs) Here’s a sample configuration that shows how tabs are structured in launch configuration files. * Use the `title` field to set a custom tab name * Use the `color` field to set the tab color * We currently support using the terminal colors (ANSI colors): `Red | Green | Yellow | Blue | Magenta | Cyan` The actual color values will be automatically derived from your Warp theme ```yaml # Warp Launch Configuration # # This configuration has two tabs in the same window. --- name: Example Tabs windows: - tabs: - title: Documents layout: cwd: /Users/warp-user/Documents color: blue - title: Warp User layout: cwd: /Users/warp-user color: green ``` ### Panes [Section titled “Panes”](#panes) Launch Configurations support setting split panes in each tab. Note that Warp also supports nesting split panes in launch configuration files. ```yaml # Warp Launch Configuration # # This configuration is two windows, each with split panes. # The first window contains a vertically split tab with two panes. # The second window contains a horizontally split tab, # with a vertically split tab on the right. --- name: Example Panes windows: - tabs: - title: Downloads and Warp User layout: split_direction: vertical panes: - cwd: /Users/warp-user/Downloads - cwd: /Users/warp-user color: blue - tabs: - title: Desktop, Documents, and Warp User layout: split_direction: horizontal panes: - cwd: /Users/warp-user/Desktop - split_direction: vertical panes: - cwd: /Users/warp-user/Documents - cwd: /Users/warp-user color: green ``` ### Active and Focus [Section titled “Active and Focus”](#active-and-focus) Sample configuration that shows how a Window and Tab can be activated with a session in focus. * Use the `active_window_index` and `active_tab_index`fields to set your active Window and Tab. * Use the `is_focused` field to set which Pane is focused in each tab. Caution Note that when you use `- active_tab_index:` the `tabs:` field doesn’t need the `-` prefix, as this can cause syntax issues. ```yaml # Warp Launch Configuration # # This configurations has two tabs, with the second tab active. # Two vertical split panes in the first tab and the top pane focused. # Two horizontal split panes in the second tab and the right pane focused. --- name: Example Active and Focus active_window_index: 0 windows: - active_tab_index: 1 tabs: - title: Tab 1 layout: split_direction: vertical panes: - cwd: /Users/warp-user/Documents is_focused: true - cwd: /Users/warp-user/Documents/Projects - title: Tab 2 layout: split_direction: horizontal panes: - cwd: /Users/warp-user/Downloads - cwd: /Users/warp-user is_focused: true ``` ### Commands [Section titled “Commands”](#commands) Use the `commands` field to define a set of commands to run when a launch configuration in run. Caution You may need to use double quotes for commands with special characters. Commands in separate lines are chained together with `&&` when run, as such commands run after `ssh` commands may not execute. ```yaml # Warp Launch Configuration # # This configuration has two windows, # the first window executes two commands on start, # the second window has a split pane that executes a command on start. --- name: Example Commands windows: - tabs: - title: Documents layout: cwd: /Users/warp-user/Documents commands: - exec: ls - exec: code . color: blue - tabs: - title: Downloads layout: split_direction: vertical panes: - cwd: /Users/warp-user/Downloads commands: - exec: curl http://example.com -o my.file - exec: cp my.file my.file2 - cwd: /Users/warp-user commands: - exec: ssh user@remote.server.com color: green ``` # Session Navigation > Quickly navigate to any terminal session across Warp using the Session Navigation palette. ## How to access Session navigation [Section titled “How to access Session navigation”](#how-to-access-session-navigation) 1. Open the Session Navigation palette with the [Command Palette](/terminal/command-palette/), click on **session >\_** or type in “sessions:”. 2. Jump to a session by using your mouse or the `UP ↑`/`DOWN ↓` arrow keys and `ENTER`. 3. Refine the session results by searching for sessions by prompt, the currently running command, last run command, and command status (ex: “Running…”, “Completed 10 minutes ago”, “Empty Session”). Note Sessions are ordered by recency, so the most recently focused sessions show up first. The Session Navigation palette does not have **PS1** support and can only show Warp’s native prompt. ### CTRL-TAB behavior [Section titled “CTRL-TAB behavior”](#ctrl-tab-behavior) `CTRL-TAB` shortcut defaults to activate the previous / next [Tabs](/terminal/windows/tabs/). You can configure the shortcut to cycle the most recent session, including any [Split Panes](/terminal/windows/split-panes/), in **Settings** > **Features** > **Keys** > **Ctrl-Tab behavior** ## How session navigation works [Section titled “How session navigation works”](#how-session-navigation-works) [Session Navigation Demo](https://www.loom.com/embed/2147adc6749c4f4ea5da432eadda7995) # Session Restoration > Restore your windows, tabs, panes, and recent Blocks automatically when you relaunch Warp. ## What is it [Section titled “What is it”](#what-is-it) Session restoration allows you to quickly pick up where you left off in your previous terminal session. ## How to access Session Restoration [Section titled “How to access Session Restoration”](#how-to-access-session-restoration) * Session Restoration comes enabled by default in Warp. Note On Linux, opening windows at a specific position is not supported in Wayland. * You can disable Session Restoration by going to **Settings** > **Features**, then toggling off `Restore windows, tabs, and panes on startup`. Caution Toggling off Session Restoration will not clear the [SQLite database](/terminal/sessions/session-restoration/#session-restoration-database); however, Warp will stop recording new output. ## How session restoration works [Section titled “How session restoration works”](#how-session-restoration-works) [![](/assets/terminal/sessions-block_restoration.poster.jpg)](/assets/terminal/sessions-block_restoration.mp4) #### Session Restoration database [Section titled “Session Restoration database”](#session-restoration-database) Warp saves the data from your previous session’s windows, tabs, and panes to a SQLite database on your computer, and every time you quit the app, this data is overwritten by your latest session. You can open the database directly and inspect its full contents like so: * macOS ```bash sqlite3 "$HOME/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Stable/warp.sqlite" ``` * Windows ```powershell sqlite3 $env:LOCALAPPDATA\warp\Warp\data\warp.sqlite ``` * Linux ```bash sqlite3 "${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/warp.sqlite" ``` **How to clear the Session Restoration database** Sometimes, you may want to prevent a sensitive Block from being saved on your computer, or you may want to clear blocks from a machine entirely. Note This interferes with the running session’s ability to save content and may require you close Warp before running the database removal commands. Danger The following guidance is destructive and will delete any sessions and block history. There are two ways to do this: * macOS * Clear the blocks from your running Warp session with `CMD-K`. * Delete the SQLite file entirely with the following command: ```bash rm -f "$HOME/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Stable/warp.sqlite" ``` * Windows * Clear the blocks from your running Warp session with `CTRL-SHIFT-K`. * Delete the SQLite file entirely with the following command: ```powershell Remove-Item -Force $env:LOCALAPPDATA\warp\Warp\data\warp.sqlite ``` * Linux * Clear the blocks from your running Warp session with `CTRL-SHIFT-K`. * Delete the SQLite file entirely with the following command: ```bash rm -f "${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/warp.sqlite" ``` # Settings file > Configure Warp with a plain-text TOML settings file. Learn where it lives, how it works with the Settings panel, and see common configuration examples. Warp stores your preferences in a plain-text file called `settings.toml`. You can edit it directly in any text editor, check it into version control, or generate it with a script. Changes take effect immediately — no restart required. The settings file works alongside the graphical Settings panel. Changes you make in either place are reflected in the other. **Key features:** * **Hot-reload** — Warp watches `settings.toml` for changes and applies them instantly when you save the file. * **Error recovery** — If the file contains invalid TOML or an unrecognized value, Warp shows a warning banner and falls back to defaults for the affected settings. Fix the file and the banner clears automatically. * **Automatic migration** — When you upgrade to a version of Warp that includes the settings file, Warp automatically migrates your existing preferences into `settings.toml`. * **Bidirectional sync with Settings UI** — Changes in the Warp **Settings** panel (`⌘+,` on macOS, `Ctrl+,` on Linux/Windows) write to `settings.toml`, and hand-edits to the file are reflected in the panel. * **Agent-powered editing** — Ask Warp’s agent to change settings for you using natural language (for example, “increase my font size to 16”). The bundled `modify-settings` skill handles the file update automatically. ## Opening your settings file [Section titled “Opening your settings file”](#opening-your-settings-file) There are several ways to open `settings.toml`: * In the Warp app, go to **Settings** and click **Open settings file** at the bottom of the panel. * Open the file directly in any editor at the path listed below for your platform and Warp release channel. ## File location [Section titled “File location”](#file-location) Depending on your platform and Warp release channel, `settings.toml` is located at: * **macOS** * Stable — `~/.warp/settings.toml` * Preview — `~/.warp-preview/settings.toml` * **Linux** * Stable — `~/.config/warp-terminal/settings.toml` * Preview — `~/.config/warp-terminal-preview/settings.toml` * **Windows** * Stable — `%LOCALAPPDATA%\warp\Warp\config\settings.toml` * Preview — `%LOCALAPPDATA%\warp\WarpPreview\config\settings.toml` ## Settings file format [Section titled “Settings file format”](#settings-file-format) The file uses [TOML v1.1](https://toml.io/en/v1.1.0) syntax. Settings are organized into **sections** (TOML tables) that group related options — for example, `[appearance.text]` contains font settings and `[agents.profiles]` contains agent permission settings. Here is a minimal example showing the structure: ```toml # Appearance settings [appearance.text] font_name = "JetBrains Mono" font_size = 14.0 line_height_ratio = 1.3 [appearance.themes] theme = "dracula" # Terminal behavior [terminal.input] syntax_highlighting = true honor_ps1 = false # Agent permissions [agents.profiles] agent_mode_execute_readonly_commands = true ``` ### How sections map to TOML tables [Section titled “How sections map to TOML tables”](#how-sections-map-to-toml-tables) Each section in the settings file corresponds to a TOML table header in brackets. Subsections use dot-separated paths: * `[general]` — Top-level general settings like session restoration and tab placement * `[appearance]` — Visual settings, with subsections like `[appearance.text]`, `[appearance.themes]`, `[appearance.cursor]` * `[agents]` — Agent and AI settings, with subsections like `[agents.profiles]`, `[agents.warp_agent.input]` * `[terminal]` — Terminal behavior settings, with subsections like `[terminal.input]` For the complete list of every available setting, see [All settings reference](/terminal/settings/all-settings/). ## How settings are applied [Section titled “How settings are applied”](#how-settings-are-applied) ### Relationship between the Settings panel and the file [Section titled “Relationship between the Settings panel and the file”](#relationship-between-the-settings-panel-and-the-file) The Warp Settings panel (`⌘+,` on macOS, `Ctrl+,` on Linux/Windows) and `settings.toml` represent the same underlying configuration. Changing a toggle in the Settings panel writes the new value to `settings.toml`. Editing `settings.toml` by hand updates the Settings panel the next time it reads the file. ### Error banner [Section titled “Error banner”](#error-banner) When `settings.toml` has errors, Warp displays a dismissible warning banner at the top of the workspace. The banner includes an **Open settings file** button so you can jump directly to the file and fix the issue. Once you save a corrected file, the banner disappears automatically. ## Common configurations [Section titled “Common configurations”](#common-configurations) ### Change theme and font [Section titled “Change theme and font”](#change-theme-and-font) ```toml [appearance.themes] theme = "cyber_wave" [appearance.text] font_name = "Fira Code" font_size = 15.0 ligature_rendering_enabled = true font_weight = "normal" ``` ### Configure agent permissions [Section titled “Configure agent permissions”](#configure-agent-permissions) ```toml [agents.profiles] agent_mode_coding_permissions = "always_allow_reading" agent_mode_execute_readonly_commands = true agent_mode_command_execution_allowlist = [ "cat(\\s.*)?", "echo(\\s.*)?", "find .*", "grep(\\s.*)?", "ls(\\s.*)?", "which .*", ] ``` ### Enable Vim keybindings [Section titled “Enable Vim keybindings”](#enable-vim-keybindings) ```toml [text_editing] vim_mode_enabled = true vim_status_bar = true ``` ## Migrating from previous settings [Section titled “Migrating from previous settings”](#migrating-from-previous-settings) When you upgrade to a version of Warp that includes the settings file, Warp automatically migrates your existing preferences into `settings.toml`. No action is required — your customizations carry over and the file becomes the source of truth for all settings going forward. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### ”Your settings file contains an error” banner [Section titled “”Your settings file contains an error” banner”](#your-settings-file-contains-an-error-banner) This banner appears when `settings.toml` has invalid TOML syntax or an unrecognized value. Click **Open settings file** in the banner to open the file and look for: * **Missing quotes** — String values must be wrapped in double quotes: `font_name = "Hack"`, not `font_name = Hack`. * **Missing brackets** — Section headers require square brackets: `[appearance.text]`. * **Wrong value types** — Check that numbers are numbers (`font_size = 13.0`), booleans are `true`/`false`, and enum values are valid strings. ### Resetting to defaults [Section titled “Resetting to defaults”](#resetting-to-defaults) Delete `settings.toml` (or rename it) and restart Warp. Warp falls back to built-in defaults for all settings. The file is re-created the next time you change a setting through the Settings panel. ```bash # Uncomment the two lines that match your platform and Warp release # channel, then run them to back up and delete settings.toml. # Stable (macOS) # cp ~/.warp/settings.toml ~/.warp/settings.toml.bak # rm ~/.warp/settings.toml # Stable (Linux) # cp ~/.config/warp-terminal/settings.toml ~/.config/warp-terminal/settings.toml.bak # rm ~/.config/warp-terminal/settings.toml # Preview (macOS) # cp ~/.warp-preview/settings.toml ~/.warp-preview/settings.toml.bak # rm ~/.warp-preview/settings.toml # Preview (Linux) # cp ~/.config/warp-terminal-preview/settings.toml ~/.config/warp-terminal-preview/settings.toml.bak # rm ~/.config/warp-terminal-preview/settings.toml ``` ### Settings not applying [Section titled “Settings not applying”](#settings-not-applying) Confirm you’re editing the correct file for your platform and Warp release channel (see [File location](#file-location) above). If you run multiple [Warp release channels](/support-and-community/community/warp-preview-and-alpha-program/), each channel has its own settings directory. ## Related pages [Section titled “Related pages”](#related-pages) * [All settings reference](/terminal/settings/all-settings/) — Complete list of every available setting with descriptions, types, and defaults * [Customizing Warp](/getting-started/quickstart/customizing-warp/) — Overview of all customization options * [Custom themes](/terminal/appearance/custom-themes/) — Create and load custom YAML or Base16 themes * [Keyboard shortcuts](/getting-started/keyboard-shortcuts/) — Customize keybindings * [Settings Sync (Beta)](/terminal/more-features/settings-sync/) — Sync settings across machines # All settings reference > Complete reference for every setting available in Warp's settings.toml file, organized by section with descriptions, types, defaults, and examples. This page lists every setting you can configure in [`settings.toml`](/terminal/settings/) organized by TOML section. For an introduction to the settings file, how to open it, and common configuration examples, see [Settings file](/terminal/settings/). Settings are grouped into sections that correspond to TOML table headers (for example, `[appearance.text]`). Only include the settings you want to change — Warp uses built-in defaults for everything else. ## General [Section titled “General”](#general) Top-level settings that control Warp’s startup behavior, session management, and window-level preferences. **Section**: `[general]` * `default_session_mode` — The default mode for new terminal sessions. Type: string. Default: `"terminal"`. Options: `"terminal"`, `"agent"`, `"cloud_agent"`, `"tab_config"`, `"docker_sandbox"`. * `default_tab_config_path` — Path to the tab config used when `default_session_mode` is `"tab_config"`. Type: string. Default: `""`. * `link_tooltip` — Whether to show a tooltip when hovering over links. Type: boolean. Default: `true`. * `login_item` — Whether to launch Warp automatically when you log in. Type: boolean. Default: `true`. * `mouse_scroll_multiplier` — The scroll speed multiplier for mouse scroll events. Type: number. Default: `3.0`. * `new_tab_placement` — Where new tabs are placed in the tab bar. Type: string. Default: `"after_current_tab"`. Options: `"after_current_tab"`, `"after_all_tabs"`. * `quit_on_last_window_closed` — Whether to quit Warp when the last window is closed. Type: boolean. Default: `false`. * `restore_session` — Whether to restore the previous session when Warp starts up. Type: boolean. Default: `true`. * `should_confirm_close_session` — Whether to show a confirmation dialog when closing a session. Type: boolean. Default: `true`. * `show_changelog_after_update` — Whether the changelog is shown after an update. Type: boolean. Default: `true`. * `show_warning_before_quitting` — Whether to show a warning dialog before quitting Warp. Type: boolean. Default: `true`. * `snackbar_enabled` — Whether to show snackbar notifications. Type: boolean. Default: `true`. * `user_native_preference` — Whether to prefer the native desktop app or the web app. Type: string. Default: `"not_selected"`. Options: `"not_selected"`, `"web"`, `"desktop"`. ### Undo close [Section titled “Undo close”](#undo-close) **Section**: `[general.undo_close]` * `enabled` — Whether the undo close feature is enabled. Type: boolean. Default: `true`. * `grace_period` — How long (in seconds) after closing a tab you can still undo the close. Type: integer. Default: `60`. ## Appearance [Section titled “Appearance”](#appearance) Visual settings that control how Warp looks, including themes, fonts, cursor, tabs, window, and layout. **Section**: `[appearance]` * `spacing` — Controls the spacing between terminal blocks. Type: string. Default: `"normal"`. Options: `"normal"`, `"compact"`. ### Themes [Section titled “Themes”](#themes) **Section**: `[appearance.themes]` * `theme` — The color theme. Type: string. Default: `"dark"`. Options: `"adeberry"`, `"phenomenon"`, `"dark"`, `"dracula"`, `"fancy_dracula"`, `"cyber_wave"`, `"solar_flare"`, `"solarized_dark"`, `"willow_dream"`, `"light"`, `"dark_city"`, `"gruvbox_dark"`, `"red_rock"`, `"jelly_fish"`, `"leafy"`, `"koi"`, `"solarized_light"`, `"snowy"`, `"gruvbox_light"`, `"pink_city"`, `"marble"`, or a custom theme object. * `system_theme` — Whether to match the system light/dark theme. Type: boolean. Default: `false`. * `selected_system_themes` — The themes to use for system light and dark modes. Type: object. Default: `{ dark = "dark", light = "light" }`. To use a custom theme: ```toml [appearance.themes] theme = { custom = { name = "My Theme", path = "~/.warp/themes/my-theme.yaml" } } ``` ### Text [Section titled “Text”](#text) **Section**: `[appearance.text]` * `font_name` — The monospace font used in the terminal. Type: string. Default: `"Hack"`. * `font_size` — The size of the monospace font in the terminal. Type: number. Default: `13.0`. * `font_weight` — The weight of the monospace font. Type: string. Default: `"normal"`. Options: `"thin"`, `"extra_light"`, `"light"`, `"normal"`, `"medium"`, `"semibold"`, `"bold"`, `"extra_bold"`, `"black"`. * `line_height_ratio` — The line height ratio for terminal text. Type: number. Default: `1.2`. * `ligature_rendering_enabled` — Whether to render font ligatures in the terminal. Type: boolean. Default: `false`. * `ai_font_name` — The font used for AI-generated content. Type: string. Default: `"Hack"`. * `match_ai_font` — Whether the AI font automatically matches the terminal font. Type: boolean. Default: `false`. * `notebook_font_size` — The font size used in notebooks. Type: number. Default: `14.0`. * `match_notebook_to_monospace_font_size` — Whether the notebook font size matches the terminal font size. Type: boolean. Default: `true`. * `use_thin_strokes` — Whether to use thin font strokes on macOS. Type: string. Default: `"on_high_dpi_displays"`. Options: `"never"`, `"on_low_dpi_displays"`, `"on_high_dpi_displays"`, `"always"`. * `enforce_minimum_contrast` — Whether to enforce minimum contrast for text readability. Type: string. Default: `"only_named_colors"`. Options: `"never"`, `"only_named_colors"`, `"always"`. ### Cursor [Section titled “Cursor”](#cursor) **Section**: `[appearance.cursor]` * `cursor_display_type` — The visual style of the cursor. Type: string. Default: `"bar"`. Options: `"bar"`, `"block"`, `"underline"`. * `cursor_blink` — Whether the cursor blinks. Type: string. Default: `"enabled"`. Options: `"enabled"`, `"disabled"`. ### Blocks [Section titled “Blocks”](#blocks) **Section**: `[appearance.blocks]` * `show_block_dividers` — Whether to show dividers between terminal blocks. Type: boolean. Default: `true`. * `show_jump_to_bottom_of_block_button` — Whether to show the jump-to-bottom button in long command output. Type: boolean. Default: `true`. * `should_show_bootstrap_block` — Whether the bootstrap block is visible in the terminal. Type: boolean. Default: `false`. * `should_show_in_band_command_blocks` — Whether in-band command blocks are visible. Type: boolean. Default: `false`. * `should_show_ssh_block` — Whether the SSH connection block is visible. Type: boolean. Default: `false`. ### Tabs [Section titled “Tabs”](#tabs) **Section**: `[appearance.tabs]` * `workspace_decoration_visibility` — When workspace decorations such as the tab bar are visible. Type: string. Default: `"hide_fullscreen"`. Options: `"always_show"`, `"hide_fullscreen"`, `"on_hover"`. * `tab_close_button_position` — Position of the close button on tabs. Type: string. Default: `"right"`. Options: `"right"`, `"left"`. * `show_indicators_button` — Whether to show activity indicators on tabs. Type: boolean. Default: `true`. * `preserve_active_tab_color` — Whether to preserve the active tab’s color when switching tabs. Type: boolean. Default: `false`. * `header_toolbar_chip_selection` — Configuration for the header toolbar chips in the vertical tab panel header. Type: string or object. Default: `"default"`. ### Vertical tabs [Section titled “Vertical tabs”](#vertical-tabs) **Section**: `[appearance.vertical_tabs]` * `enabled` — Whether to display tabs vertically instead of horizontally. Type: boolean. Default: `false`. * `view_mode` — Display mode for the vertical tab bar. Type: string. Default: `"compact"`. Options: `"compact"`, `"expanded"`. * `primary_info` — The primary information displayed on vertical tabs. Type: string. Default: `"command"`. Options: `"command"`, `"working_directory"`, `"branch"`. * `compact_subtitle` — Subtitle shown on compact vertical tabs. Type: string. Default: `"branch"`. Options: `"branch"`, `"working_directory"`, `"command"`. * `display_granularity` — Granularity of rows displayed in the vertical tabs panel. Type: string. Default: `"panes"`. Options: `"panes"`, `"tabs"`. * `tab_item_mode` — Tab item display mode in vertical tabs. Type: string. Default: `"focused_session"`. Options: `"focused_session"`, `"summary"`. * `show_details_on_hover` — Whether to show a details sidecar when hovering over a vertical tab. Type: boolean. Default: `true`. * `show_diff_stats` — Whether to show diff stats on vertical tabs. Type: boolean. Default: `true`. * `show_pr_link` — Whether to show PR links on vertical tabs. Type: boolean. Default: `true`. * `use_latest_prompt_as_title` — Whether vertical tab names for agent conversations use the latest user prompt. Type: boolean. Default: `false`. ### Panes [Section titled “Panes”](#panes) **Section**: `[appearance.panes]` * `focus_pane_on_hover` — Whether panes are focused when hovered over. Type: boolean. Default: `false`. * `should_dim_inactive_panes` — Whether inactive panes are visually dimmed. Type: boolean. Default: `false`. ### Input position [Section titled “Input position”](#input-position) **Section**: `[appearance.input]` * `input_mode` — The position of the terminal input. Type: string. Default: `"pinned_to_bottom"`. Options: `"pinned_to_bottom"`, `"pinned_to_top"`, `"waterfall"`. ### Full-screen apps [Section titled “Full-screen apps”](#full-screen-apps) **Section**: `[appearance.full_screen_apps]` * `alt_screen_padding` — Controls padding around full-screen terminal applications. Type: string or object. Default: `{ custom = { uniform_padding = 0.0 } }`. ### Icon [Section titled “Icon”](#icon) **Section**: `[appearance.icon]` * `app_icon` — The app icon displayed in the dock. Type: string. Default: `"default"`. Options: `"default"`, `"aurora"`, `"classic1"`, `"classic2"`, `"classic3"`, `"comets"`, `"cow"`, `"glass_sky"`, `"glitch"`, `"glow"`, `"holographic"`, `"mono"`, `"neon"`, `"original"`, `"starburst"`, `"sticker"`, `"warp_one"`. ### Window [Section titled “Window”](#window) **Section**: `[appearance.window]` * `override_opacity` — The opacity of the window background, from 1 to 100 percent. Type: integer. Default: `100`. * `override_blur` — The blur radius applied to the window background. Type: integer. Default: `1`. * `override_blur_texture` — Whether to apply a blur texture to the window background. Type: boolean. Default: `false`. * `zoom_level` — The zoom level for the window, as a percentage. Type: integer. Default: `100`. * `open_windows_at_custom_size` — Whether to open new windows at a custom size instead of the default. Type: boolean. Default: `false`. * `new_windows_num_columns` — The number of columns for new windows when using a custom size. Type: integer. Default: `80`. * `new_windows_num_rows` — The number of rows for new windows when using a custom size. Type: integer. Default: `40`. * `left_panel_visibility_across_tabs` — Whether the left panel visibility is shared across all tabs. Type: boolean. Default: `true`. ## Terminal [Section titled “Terminal”](#terminal) Settings that control terminal behavior, input, and event handling. **Section**: `[terminal]` * `copy_on_select` — Whether text is automatically copied to the clipboard when selected. Type: boolean. Default: `true`. * `focus_reporting_enabled` — Whether to forward focus and blur events to full-screen terminal applications. Type: boolean. Default: `true`. * `mouse_reporting_enabled` — Whether to forward mouse events to full-screen terminal applications. Type: boolean. Default: `true`. * `scroll_reporting_enabled` — Whether to forward scroll events to full-screen terminal applications. Type: boolean. Default: `true`. * `maximum_grid_size` — The maximum number of rows in the terminal grid. Type: integer. Default: `50000`. * `use_audible_bell` — Whether to play an audible bell sound on terminal bell events. Type: boolean. Default: `false`. * `show_terminal_zero_state_block` — Whether to show the AI zero-state block in new terminal sessions. Type: boolean. Default: `true`. ### Input [Section titled “Input”](#input) **Section**: `[terminal.input]` * `syntax_highlighting` — Whether syntax highlighting is enabled in the terminal input. Type: boolean. Default: `true`. * `honor_ps1` — Whether to use your shell’s PS1 prompt instead of the Warp prompt. Type: boolean. Default: `false`. * `input_box_type_setting` — The terminal input style. Type: string. Default: `"classic"`. Options: `"universal"` (AI-first input), `"classic"` (Terminal-first input). * `alias_expansion_enabled` — Whether shell alias expansion is enabled in the input. Type: boolean. Default: `false`. * `command_corrections` — Whether command corrections are suggested for mistyped commands. Type: boolean. Default: `true`. * `error_underlining_enabled` — Whether command errors are underlined in the input. Type: boolean. Default: `true`. * `completions_open_while_typing` — Whether the completions menu opens automatically while typing. Type: boolean. Default: `false`. * `classic_completions_mode` — Whether classic completions mode is enabled. Type: boolean. Default: `false`. * `show_hint_text` — Whether hint text is shown in the terminal input. Type: boolean. Default: `true`. * `show_terminal_input_message_bar` — Whether the terminal input message bar is shown. Type: boolean. Default: `true`. * `enable_slash_commands_in_terminal` — Whether slash commands are available in the terminal input. Type: boolean. Default: `true`. * `at_context_menu_in_terminal_mode` — Whether the @ context menu is available in terminal mode. Type: boolean. Default: `true`. * `outline_codebase_symbols_for_at_context_menu` — Whether codebase symbols appear in the @ context menu. Type: boolean. Default: `true`. * `middle_click_paste_enabled` — Whether middle-click pastes from the clipboard. Type: boolean. Default: `true`. * `extra_meta_keys` — Controls which additional keys are treated as meta keys. Type: object. Default: `{ left_alt = false, right_alt = false }`. #### Autosuggestions [Section titled “Autosuggestions”](#autosuggestions) **Section**: `[terminal.input.autosuggestions]` * `enabled` — Whether command autosuggestions are shown. Type: boolean. Default: `true`. * `keybinding_hint` — Whether autosuggestion keybinding hints are displayed. Type: boolean. Default: `true`. * `show_ignore_button` — Whether the ignore button is shown for autosuggestions. Type: boolean. Default: `false`. ### Smart select [Section titled “Smart select”](#smart-select) **Section**: `[terminal.smart_select]` * `enabled` — Whether double-click smart selection is enabled for URLs, emails, file paths, and identifiers. Type: boolean. Default: `true`. * `word_char_allowlist` — Characters considered part of a word for double-click selection when smart select is disabled. Type: string. Default: `"-.~/\"`. ## Session [Section titled “Session”](#session) Settings that control shell selection and working directory behavior for new sessions. **Section**: `[session]` * `startup_shell_override` — The shell to use when Warp starts up. Type: string or null. Default: `null` (uses system default). * `new_session_shell_override` — The shell to use when opening a new session. Type: string, object, or null. Default: `null` (uses system default). Options: `"system_default"`, `{ executable = "/path/to/shell" }`, `{ custom = "command" }`. ### Working directory config [Section titled “Working directory config”](#working-directory-config) **Section**: `[session.working_directory_config]` * `advanced_mode` — Whether to use separate settings per session source. Type: boolean. Default: `false`. When `advanced_mode` is `false`, the `[session.working_directory_config.global]` table applies to all session sources. When `true`, you can configure each source independently. **Section**: `[session.working_directory_config.global]` (also `.split_pane`, `.new_tab`, `.new_window`) * `mode` — How the working directory is determined. Type: string. Default: `"previous_dir"`. Options: `"home_dir"`, `"previous_dir"`, `"custom_dir"`. * `custom_dir` — Custom directory path, used when mode is `"custom_dir"`. Type: string. Default: `""`. ```toml # Use a specific directory for split panes, previous directory for everything else [session.working_directory_config] advanced_mode = true [session.working_directory_config.global] mode = "previous_dir" custom_dir = "" [session.working_directory_config.split_pane] mode = "custom_dir" custom_dir = "~/projects" [session.working_directory_config.new_tab] mode = "previous_dir" custom_dir = "" [session.working_directory_config.new_window] mode = "home_dir" custom_dir = "" ``` ## Agents [Section titled “Agents”](#agents) Settings for Warp’s agents, including model behavior, permissions, knowledge, MCP servers, and voice input. **Section**: `[agents]` * `cloud_conversation_storage_enabled` — Whether conversations are stored in the cloud. Type: boolean. Default: `true`. ### Knowledge [Section titled “Knowledge”](#knowledge) **Section**: `[agents.knowledge]` * `rules_enabled` — Whether the agent uses your saved rules during requests. Type: boolean. Default: `true`. * `warp_drive_context_enabled` — Whether Warp Drive context is included in AI requests. Type: boolean. Default: `true`. ### MCP servers [Section titled “MCP servers”](#mcp-servers) **Section**: `[agents.mcp_servers]` * `file_based_mcp_enabled` — Whether global file-based MCP servers from third-party agents are automatically spawned. Warp-managed global MCP servers auto-spawn regardless of this setting, and project-scoped servers must be started manually. Type: boolean. Default: `false`. ### Profiles (permissions) [Section titled “Profiles (permissions)”](#profiles-permissions) **Section**: `[agents.profiles]` * `agent_mode_coding_permissions` — The file read permission level for the agent. Type: string. Default: `"always_ask_before_reading"`. Options: `"always_ask_before_reading"`, `"always_allow_reading"`, `"allow_reading_specific_files"`. * `agent_mode_coding_file_read_allowlist` — File paths the agent can read without asking for permission. Type: array of strings. Default: `[]`. * `agent_mode_execute_readonly_commands` — Whether the agent can auto-execute read-only commands without asking. Type: boolean. Default: `false`. * `agent_mode_command_execution_allowlist` — Commands the agent can execute without explicit permission (regex patterns). Type: array of strings. Default: `["cat(\\s.*)?", "echo(\\s.*)?", "find .*", "grep(\\s.*)?", "ls(\\s.*)?", "which .*"]`. * `agent_mode_command_execution_denylist` — Commands the agent must always ask before executing (regex patterns). Type: array of strings. Default: `["bash(\\s.*)?", "fish(\\s.*)?", "pwsh(\\s.*)?", "sh(\\s.*)?", "zsh(\\s.*)?", "curl(\\s.*)?", "eval(\\s.*)?", "exec(\\s.*)?", "source(\\s.*)?", "wget(\\s.*)?", "dig(\\s.*)?", "nslookup(\\s.*)?", "host(\\s.*)?", "ssh(\\s.*)?", "scp(\\s.*)?", "rsync(\\s.*)?", "telnet(\\s.*)?", "rm(\\s.*)?"]`. ### Warp Agent (AI features) [Section titled “Warp Agent (AI features)”](#warp-agent-ai-features) **Section**: `[agents.warp_agent]` * `is_any_ai_enabled` — Controls whether all AI features are enabled. Type: boolean. Default: `true`. #### Active AI [Section titled “Active AI”](#active-ai) **Section**: `[agents.warp_agent.active_ai]` * `enabled` — Controls whether proactive AI features like suggestions are enabled. Type: boolean. Default: `true`. * `code_suggestions_enabled` — Controls whether AI code suggestions are enabled. Type: boolean. Default: `true`. * `intelligent_autosuggestions_enabled` — Controls whether AI-powered intelligent autosuggestions are enabled. Type: boolean. Default: `true`. * `agent_mode_query_suggestions_enabled` — Controls whether prompt suggestions are shown in Agent Mode. Type: boolean. Default: `true`. * `shared_block_title_generation_enabled` — Controls whether titles are auto-generated when sharing blocks. Type: boolean. Default: `true`. #### Input [Section titled “Input”](#input-1) **Section**: `[agents.warp_agent.input]` * `ai_auto_detection_enabled` — Controls whether AI automatically detects natural language input. Type: boolean. Default: `true`. * `ai_command_denylist` — Commands to exclude from AI natural language autodetection. Type: string. Default: `""`. * `nld_in_terminal_enabled` — Controls whether natural language detection is enabled in the terminal input. Type: boolean. Default: `false`. * `show_model_selectors_in_prompt` — Whether to show AI model selectors in the input prompt. Type: boolean. Default: `true`. * `show_agent_tips` — Whether agent tips are displayed in the input. Type: boolean. Default: `true`. * `include_agent_commands_in_history` — Whether agent-executed commands are included in command history. Type: boolean. Default: `false`. * `agent_toolbar_chip_selection_setting` — Controls the layout of context chips in the Agent Mode toolbar. Type: string or object. Default: `"default"`. #### Other [Section titled “Other”](#other) **Section**: `[agents.warp_agent.other]` * `thinking_display_mode` — Controls how agent thinking traces are displayed after streaming. Type: string. Default: `"show_and_collapse"`. Options: `"show_and_collapse"`, `"always_show"`, `"never_show"`. * `open_conversation_layout_preference` — Whether to open agent conversations in a new tab or a split pane. Type: string. Default: `"new_tab"`. Options: `"new_tab"`, `"split_pane"`. * `show_conversation_history` — Whether conversation history appears in the tools panel. Type: boolean. Default: `true`. * `show_agent_notifications` — Whether agent notifications are shown. Type: boolean. Default: `true`. * `should_show_oz_updates_in_zero_state` — Whether the “What’s new” section is shown in the agent view. Type: boolean. Default: `true`. * `should_render_use_agent_toolbar_for_user_commands` — Whether to show the “Use Agent” footer for terminal commands. Type: boolean. Default: `true`. * `cloud_agent_computer_use_enabled` — Whether computer use is enabled for cloud agent conversations. Type: boolean. Default: `false`. ### Code review autogeneration [Section titled “Code review autogeneration”](#code-review-autogeneration) Controls AI-driven autogeneration in the code review dialogs. This setting currently lives under `[agents.oz.active_ai]` rather than alongside the other `[agents.warp_agent.active_ai]` settings. **Section**: `[agents.oz.active_ai]` * `git_operations_autogen_enabled` — Controls whether AI auto-generates commit messages and PR title and body in the code review dialogs. Type: boolean. Default: `true`. ### Third-party (CLI agents) [Section titled “Third-party (CLI agents)”](#third-party-cli-agents) **Section**: `[agents.third_party]` * `should_render_cli_agent_toolbar` — Whether to show the CLI agent footer for coding agent commands. Type: boolean. Default: `true`. * `auto_toggle_composer` — Whether CLI agent Rich Input automatically closes and reopens based on the agent’s blocked state. Type: boolean. Default: `true`. * `auto_open_composer_on_cli_agent_start` — Whether CLI agent Rich Input automatically opens when a CLI agent session starts. Type: boolean. Default: `false`. * `auto_dismiss_composer_after_submit` — Whether CLI agent Rich Input automatically closes after the user submits a prompt. Type: boolean. Default: `false`. * `cli_agent_toolbar_chip_selection_setting` — Controls the layout of context chips in the CLI Agent toolbar. Type: string or object. Default: `"default"`. * `cli_agent_toolbar_enabled_commands` — Maps custom toolbar command patterns to specific CLI agents. Type: object. Default: `{}`. ### Voice [Section titled “Voice”](#voice) **Section**: `[agents.voice]` * `voice_input_enabled` — Controls whether voice input is enabled for AI interactions. Type: boolean. Default: `true`. * `voice_input_toggle_key` — The key used to toggle voice input. Type: string. Default: `"none"`. Options: `"none"`, `"fn"`, `"alt_left"`, `"alt_right"`, `"control_left"`, `"control_right"`, `"super_left"`, `"super_right"`, `"shift_left"`, `"shift_right"`. ## Code [Section titled “Code”](#code) Settings for Warp’s built-in code editor, file handling, and codebase indexing. **Section**: `[code]` ### Editor [Section titled “Editor”](#editor) **Section**: `[code.editor]` * `open_file_editor` — The editor used to open files. Type: string or object. Default: `"system_default"`. Options: `"system_default"`, `"warp"`, `"env_editor"`, or an external editor object such as `{ external_editor = "v_s_code" }`. Supported external editors: VS Code (`v_s_code`), VS Code Insiders (`v_s_code_insiders`), PyCharm (`py_charm`), IntelliJ IDEA (`intelli_j`), CLion (`c_lion`), RustRover (`rust_rover`), Sublime Text 4 (`sublime4`), Zed (`zed`), Cursor (`cursor`), Windsurf (`windsurf`), and others. * `open_code_panels_file_editor` — The editor used to open files from code panels. Type: string or object. Default: `"warp"`. * `open_file_layout` — The layout used when opening files in the editor. Type: string. Default: `"split_pane"`. Options: `"split_pane"`, `"new_tab"`. * `prefer_markdown_viewer` — Whether to use the Markdown viewer when opening Markdown files. Type: boolean. Default: `true`. * `prefer_tabbed_editor_view` — Whether to prefer opening files in a tabbed editor view. Type: boolean. Default: `true`. * `show_code_review_button` — Whether to show the code review button on tabs. Type: boolean. Default: `true`. * `auto_open_code_review_pane_on_first_agent_change` — Whether to automatically open the code review pane when the agent makes its first change. Type: boolean. Default: `false`. * `show_code_review_diff_stats` — Whether to show lines added/removed counts on the code review button. Type: boolean. Default: `true`. * `show_project_explorer` — Whether the project explorer is shown in the tools panel. Type: boolean. Default: `true`. * `show_global_search` — Whether global file search is shown in the tools panel. Type: boolean. Default: `true`. * `use_warp_as_default_editor` — Whether Warp is used as the default code editor. Type: boolean. Default: `false`. ### Indexing [Section titled “Indexing”](#indexing) **Section**: `[code.indexing]` * `agent_mode_codebase_context` — Whether Codebase Context is provided to the agent. Type: boolean. Default: `true`. * `agent_mode_codebase_context_auto_indexing` — Whether automatic codebase indexing is enabled. Type: boolean. Default: `false`. ## Keys [Section titled “Keys”](#keys) Keyboard behavior settings. **Section**: `[keys]` * `ctrl_tab_behavior_setting` — Controls the behavior of `Ctrl+Tab`. Type: string. Default: `"activate_prev_next_tab"`. Options: `"activate_prev_next_tab"`, `"cycle_most_recent_session"`. ## Notifications [Section titled “Notifications”](#notifications) Settings that control desktop notification behavior. **Section**: `[notifications]` * `toast_duration_secs` — How long notification toasts are displayed, in seconds. Type: integer. Default: `8`. ### Preferences [Section titled “Preferences”](#preferences) **Section**: `[notifications.preferences]` * `mode` — Whether notifications are enabled, disabled, or not yet configured. Type: string. Default: `"unset"`. Options: `"unset"`, `"dismissed"`, `"enabled"`, `"disabled"`. * `is_long_running_enabled` — Whether to notify when a long-running command completes. Type: boolean. Default: `true`. * `long_running_threshold` — Threshold in seconds for long-running command notifications. Type: integer. Default: `30`. * `is_agent_task_completed_enabled` — Whether to notify when an agent task completes. Type: boolean. Default: `true`. * `is_needs_attention_enabled` — Whether to notify when a session needs attention. Type: boolean. Default: `true`. * `is_password_prompt_enabled` — Whether to notify when a password prompt is detected. Type: boolean. Default: `true`. * `play_notification_sound` — Whether to play a sound with notifications. Type: boolean. Default: `true`. ## Privacy [Section titled “Privacy”](#privacy) Settings that control telemetry, crash reporting, and secret redaction. **Section**: `[privacy]` * `telemetry_enabled` — Whether anonymous usage telemetry is collected. Type: boolean. Default: `true`. * `crash_reporting_enabled` — Whether crash reports are sent. Type: boolean. Default: `true`. * `custom_secret_regex_list` — Custom regex patterns for detecting and redacting secrets. Type: array of objects. Default: `[]`. Each item in `custom_secret_regex_list` has the format: ```toml [[privacy.custom_secret_regex_list]] pattern = "sk-[A-Za-z0-9]{48}" name = "OpenAI API key" ``` ### Secret redaction [Section titled “Secret redaction”](#secret-redaction) **Section**: `[privacy.secret_redaction]` * `enabled` — Whether secret redaction is enabled to detect and obscure secrets in terminal output. Type: boolean. Default: `false`. * `hide_secrets_in_block_list` — Whether to hide detected secrets in the block list using asterisks. Type: boolean. Default: `false`. * `secret_display_mode_setting` — Controls how detected secrets are visually displayed. Type: string. Default: `"strikethrough"`. Options: `"asterisks"`, `"strikethrough"`, `"always_show"`. ## System [Section titled “System”](#system) Low-level system and rendering settings. **Section**: `[system]` * `prefer_low_power_gpu` — Whether to prefer the integrated (low-power) GPU. Type: boolean. Default: `false`. * `preferred_graphics_backend` — The preferred graphics backend (Windows). Type: string or null. Default: `null`. Options: `"dx12"`, `"vulkan"`, `"gl"`, `"metal"`, `null`. * `linux_selection_clipboard` — Whether the Linux primary selection clipboard is used. Type: boolean. Default: `true`. ## Text editing [Section titled “Text editing”](#text-editing) Settings that control text editing behavior in the input editor. **Section**: `[text_editing]` * `vim_mode_enabled` — Whether Vim keybindings are enabled. Type: boolean. Default: `false`. * `vim_status_bar` — Whether the Vim status bar is displayed. Type: boolean. Default: `true`. * `vim_unnamed_system_clipboard` — Whether the Vim unnamed register uses the system clipboard. Type: boolean. Default: `false`. * `autocomplete_symbols` — Whether matching symbols like brackets and quotes are auto-completed. Type: boolean. Default: `true`. ## Warp Drive [Section titled “Warp Drive”](#warp-drive) Settings for Warp Drive (shared workflows, notebooks, and prompts). **Section**: `[warp_drive]` * `enabled` — Whether Warp Drive is enabled. Type: boolean. Default: `true`. * `sorting_choice` — The sort order for items in Warp Drive. Type: string. Default: `"by_object_type"`. Options: `"by_timestamp"`, `"alphabetical_descending"`, `"alphabetical_ascending"`, `"by_object_type"`. ## Warpify [Section titled “Warpify”](#warpify) Settings for Warp features in SSH sessions and subshells. ### SSH [Section titled “SSH”](#ssh) **Section**: `[warpify.ssh]` * `enable_ssh_warpification` — Whether to enable Warp features in SSH sessions. Type: boolean. Default: `true`. * `enable_legacy_ssh_wrapper` — Whether the legacy SSH wrapper is enabled for SSH sessions. Type: boolean. Default: `true`. * `use_ssh_tmux_wrapper` — Whether to use a tmux-based wrapper for SSH warpification. Type: boolean. Default: `false`. * `ssh_extension_install_mode` — Controls SSH extension installation behavior. Type: string. Default: `"always_ask"`. Options: `"always_ask"` (always prompt before installing), `"always_install"` (auto-install and connect without prompting), `"never_install"` (fall back to legacy warpification). * `ssh_hosts_denylist` — SSH hosts that should not trigger the warpification prompt. Type: array of strings. Default: `[]`. ### Subshells [Section titled “Subshells”](#subshells) **Section**: `[warpify.subshells]` * `added_subshell_commands` — Additional regex patterns for commands that should be recognized as subshells. Type: array of strings. Default: `[]`. * `subshell_commands_denylist` — Commands that should not trigger the subshell warpification prompt. Type: array of strings. Default: `[]`. ## Workflows [Section titled “Workflows”](#workflows) Settings for workflow behavior. **Section**: `[workflows]` * `show_global_workflows_in_universal_search` — Whether to show global workflows in universal search results. Type: boolean. Default: `false`. ## Accessibility [Section titled “Accessibility”](#accessibility) Settings for screen reader support. **Section**: `[accessibility]` * `accessibility_verbosity` — The verbosity level for screen reader announcements. Type: string. Default: `"verbose"`. Options: `"verbose"` (includes help string), `"concise"` (value only). ## Account [Section titled “Account”](#account) Settings related to your Warp account. **Section**: `[account]` * `is_settings_sync_enabled` — Whether settings are synced across devices via the cloud. Type: boolean. Default: `false`. ## Cloud platform [Section titled “Cloud platform”](#cloud-platform) Settings for third-party API key integration and cloud model configuration. ### Third-party API keys [Section titled “Third-party API keys”](#third-party-api-keys) **Section**: `[cloud_platform.third_party_api_keys]` * `aws_bedrock_credentials_enabled` — Whether Warp should use your local AWS credentials for Bedrock-enabled requests. Type: boolean. Default: `false`. * `aws_bedrock_profile` — The AWS profile name to use for Bedrock credentials. Type: string. Default: `"default"`. * `aws_bedrock_auto_login` — Whether to automatically run the AWS login command when Bedrock credentials expire. Type: boolean. Default: `false`. * `aws_bedrock_auth_refresh_command` — The command to run to refresh AWS credentials for Bedrock. Type: string. Default: `"aws login"`. * `can_use_warp_credits_with_byok` — Whether Warp credits can be used even when providing your own API key. Type: boolean. Default: `false`. ## Global hotkey [Section titled “Global hotkey”](#global-hotkey) Settings for the global activation hotkey and dedicated hotkey window (Quake Mode). ### Toggle all windows [Section titled “Toggle all windows”](#toggle-all-windows) **Section**: `[global_hotkey.toggle_all_windows]` * `enabled` — Whether the hotkey that toggles visibility of all windows is enabled. Mutually exclusive with `global_hotkey.dedicated_window.enabled`. Type: boolean. Default: `false`. * `keybinding` — The keybinding for the global activation hotkey. Format: modifiers and a key joined by `-`, for example `"cmd-shift-a"` or `"alt-enter"`. Type: string or null. Default: `null`. ### Dedicated window (Quake Mode) [Section titled “Dedicated window (Quake Mode)”](#dedicated-window-quake-mode) **Section**: `[global_hotkey.dedicated_window]` * `enabled` — Whether the dedicated hotkey window is enabled. Mutually exclusive with `global_hotkey.toggle_all_windows.enabled`. Type: boolean. Default: `false`. **Section**: `[global_hotkey.dedicated_window.settings]` * `active_pin_position` — Screen edge where the hotkey window is pinned. Type: string. Options: `"top"`, `"bottom"`, `"left"`, `"right"`. * `hide_window_when_unfocused` — Whether to hide the hotkey window when it loses focus. Type: boolean. * `keybinding` — Keyboard shortcut to toggle the hotkey window. Type: string or null. * `pin_screen` — Display to pin the hotkey window to. Type: string or object or null. Options: `"primary"`, `{ external = 1 }`, `null`. Window size percentages are configured per pin position: ```toml [global_hotkey.dedicated_window] enabled = true [global_hotkey.dedicated_window.settings] active_pin_position = "top" hide_window_when_unfocused = true keybinding = "ctrl-`" [global_hotkey.dedicated_window.settings.pin_position_to_size_percentages.top] width = 100 height = 30 [global_hotkey.dedicated_window.settings.pin_position_to_size_percentages.bottom] width = 100 height = 30 [global_hotkey.dedicated_window.settings.pin_position_to_size_percentages.left] width = 40 height = 100 [global_hotkey.dedicated_window.settings.pin_position_to_size_percentages.right] width = 40 height = 100 ``` # Warpify overview > Warp support for Warpifying, or enabling Warp's features, in local or remote sessions. 1. [Subshells](/terminal/warpify/subshells/), Warp supports enabling Warp features in subshells for bash, zsh, and fish. 2. [SSH](/terminal/warpify/ssh/), Warp’s SSH extension brings the file tree, reliable completions, and native code diffs to remote macOS and Linux hosts. Legacy tmux-based Warpification is still available for clients that don’t yet ship the extension. 3. [SSH Legacy](/terminal/warpify/ssh-legacy/), Warp supports a legacy wrapper that enables Warp features in remote (SSH) sessions. ## Subshells [Section titled “Subshells”](#subshells) [![](/assets/terminal/subshells-demo.poster.jpg)](/assets/terminal/subshells-demo.mp4) ## SSH [Section titled “SSH”](#ssh) [![](/assets/terminal/subshell-ssh-demo.poster.jpg)](/assets/terminal/subshell-ssh-demo.mp4) # SSH with Warp features > Use Warp's SSH extension on remote macOS and Linux hosts to get a real file tree, reliable completions, and native code edits over SSH. Warp’s **SSH extension** brings the local Warp experience to remote macOS and Linux hosts. After you opt in on first connect, you get a real file tree backed by the remote filesystem, more reliable completions over a single multiplexed SSH connection, and a coding agent that applies edits with Warp’s native diff tool instead of falling back to `sed`. [SSH extension demo](https://www.loom.com/embed/466d88a1968842c68f66a3b66b94f146) ## What you get over SSH [Section titled “What you get over SSH”](#what-you-get-over-ssh) Once the SSH extension is installed on a remote host, the following features work the same way they do locally: * **File tree (Project Explorer)** - The left panel reflects the remote project’s structure and updates as you `cd` between directories or change files. See [File Tree](/code/code-editor/file-tree/). * **Reliable completions and autosuggestions** - Generators run in parallel over a single multiplexed connection instead of opening a new SSH session per command, so completions stop hitting the remote host’s `MaxSessions` ceiling and stop occasionally injecting errors into your blocks. * **Native file reads and code diffs** - The Agent reads files and applies edits through Warp’s built-in diff tool. Code changes show up as inline diffs you can review and approve, instead of being applied via `sed` or other shell commands. See [Code diffs](/agent-platform/local-agents/code-diffs/). * **All core terminal features** - The input editor, blocks, command history, autosuggestions, and history search behave the same as in a local session. For a full breakdown of what works over SSH and what doesn’t, see [Feature support over SSH](/code/ssh-feature-support/). ![Warp prompting to Warpify a freshly-connected SSH session.](/_astro/warpify_ssh_prompt.BustqpFn_Z20DP5r.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ## Installing the SSH extension [Section titled “Installing the SSH extension”](#installing-the-ssh-extension) On the first SSH connection to a host that doesn’t already have the SSH extension installed, Warp shows an in-block prompt with two options: * **Install Warp’s SSH extension** - Recommended. Warp downloads the matching remote server extension for the remote OS and architecture, installs it under `~/.warp/remote-server` (or `~/.warp-preview/remote-server` on Preview builds), launches it, and completes the handshake. Subsequent connections to the same host skip the prompt and reuse the installed binary. * **Continue without installing** - Skip installing the extension for this connection. The session continues without the SSH extension, so file tree, native file reads, and native code diffs are unavailable until you install. You can reconnect and install at any time. Warp never installs anything on a remote host without your explicit consent, and the install only writes under `~/.warp*/`. Note The extension binary tracks your client’s release channel. Stable Warp installs the extension under `~/.warp/remote-server`, and Preview installs it under `~/.warp-preview/remote-server`, so both channels can coexist on the same remote host. ### Managing the install prompt [Section titled “Managing the install prompt”](#managing-the-install-prompt) In the Warp app, go to **Settings** > **Warpify** to control how the prompt behaves: * **Always ask** (default) - Show the install prompt the first time you connect to each host. * **Always install** - Skip the prompt and install the extension automatically when it’s missing. * **Never install** - Skip the prompt and connect to the host without installing the SSH extension. The same setting can also be changed inline from the install prompt by selecting **Don’t ask me this again** before clicking either button. The underlying TOML key is `warpify.ssh.ssh_extension_install_mode` - see [All settings reference](/terminal/settings/all-settings/#ssh) for the full list of SSH-related settings, including `ssh_hosts_denylist` for hosts you never want to engage Warpification on. ## Legacy: tmux-based Warpification [Section titled “Legacy: tmux-based Warpification”](#legacy-tmux-based-warpification) Caution Tmux-based Warpification is a legacy alternative to the SSH extension and is being deprecated. Use the SSH extension above whenever possible. Tmux-based Warpification remains available today for clients that don’t yet ship the SSH extension (for example, Windows clients). Tmux-based Warpification is an older approach to enabling Warp features in SSH sessions. It uses [`tmux`](#why-do-i-need-tmux-on-the-remote-machine) to multiplex commands over your SSH connection and provides Blocks, completions, the input editor, and history search. ### FAQs [Section titled “FAQs”](#faqs) #### Will Warpifying a remote SSH session make changes to the remote machine? [Section titled “Will Warpifying a remote SSH session make changes to the remote machine?”](#will-warpifying-a-remote-ssh-session-make-changes-to-the-remote-machine) Only with your explicit permission. The SSH extension installs the remote server extension under `~/.warp*/remote-server`. Legacy tmux-based Warpification installs [`tmux`](#why-do-i-need-tmux-on-the-remote-machine) (a popular open source terminal multiplexer) if it isn’t already present. Both flows show you exactly what they’re going to run, and you can always decline and continue using SSH without these features. #### Why do I need `tmux` on the remote machine? [Section titled “Why do I need tmux on the remote machine?”](#why-do-i-need-tmux-on-the-remote-machine) `tmux` is only required by the legacy tmux-based Warpification path; the SSH extension does not need it. [tmux](https://github.com/tmux/tmux/wiki) is a popular open source terminal multiplexer that lets you run multiple sessions within one SSH connection. It requires minimal permissions and is widely adopted (⭐ 35k+ on GitHub). The legacy path uses [tmux Control Mode](https://github.com/tmux/tmux/wiki/Control-Mode) to run ad-hoc background tasks like autocompleting a `cd` command or populating the contents of a custom prompt. The SSH extension supersedes this by speaking a length-delimited protocol over a single SSH connection. #### Can I SSH to remote machines that I don’t want to Warpify? [Section titled “Can I SSH to remote machines that I don’t want to Warpify?”](#can-i-ssh-to-remote-machines-that-i-dont-want-to-warpify) Yes. Cancel the prompt to continue without Warp features, or add the host to the denylist (**Settings** > **Warpify** > **SSH hosts denylist**) so you’re never prompted again. #### Do I have to manually Warpify every time? [Section titled “Do I have to manually Warpify every time?”](#do-i-have-to-manually-warpify-every-time) After you successfully Warpify an SSH connection manually, Warp provides a brief script you can run to append a marker at the end of your shell’s rcfile. This lets Warp know when your remote shell is ready to be Warpified. Place the snippet at the bottom of your rcfile for the best results. ![Setting up Auto-Warpify](/_astro/warpify_ssh_auto_script.X-APJAYD_25jCTB.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### What shells and operating systems are supported? [Section titled “What shells and operating systems are supported?”](#what-shells-and-operating-systems-are-supported) Warp supports macOS and most flavors of Linux as remote hosts on both the SSH extension and legacy tmux-based Warpification. Supported shells are `bash` and `zsh`. Windows remote hosts are not yet supported. #### What if Warp fails to detect my SSH session? [Section titled “What if Warp fails to detect my SSH session?”](#what-if-warp-fails-to-detect-my-ssh-session) If you’re in a remote SSH session and Warp didn’t detect it, you can manually Warpify by opening the [Command Palette](/terminal/command-palette/) and searching for “Warpify SSH Session”. #### What triggers SSH session detection for Warpification? [Section titled “What triggers SSH session detection for Warpification?”](#what-triggers-ssh-session-detection-for-warpification) With SSH session detection enabled, Warp watches for `ssh` commands whose arguments suggest an interactive session. If you’ve aliased `ssh` or are running it as part of a script, Warp won’t perform SSH session detection. Once Warp is confident you’ve successfully authenticated (by detecting `Last login:` or something resembling a basic prompt), it prompts you to Warpify the active SSH session. If SSH session detection doesn’t pick up your session, you can still [Warpify manually](#what-if-warp-fails-to-detect-my-ssh-session). # Legacy SSH wrapper > Legacy SSH wrapper that bootstraps Warp features on remote machines without tmux. Note If you are looking to troubleshoot the tmux SSH feature, see the [SSH](/terminal/warpify/ssh/). When you SSH into a remote box, you get all the features of Warp without any configuration on your part. The input editor, auto-completions, and history search work the same, regardless of machine. Caution [Limitations of SSH](https://github.com/warpdotdev/Warp/issues/578) (as of May 2024): * The SSH Wrapper only supports `bash` or `zsh` shells in remote sessions. * If you’re using a different shell, you’ll want to use `command ssh` directly (see below for more details). * For zsh, xxd is required to bootstrap warp. * For Windows, [Cygwin](https://www.cygwin.com/) is required to bootstrap the SSH Wrapper. * RemoteCommand causes the ssh wrapper to fail. * [Tmux is not currently supported.](https://github.com/warpdotdev/Warp/discussions/501) Note If you’re using zsh on the remote host, Warp creates a temp folder to act as the ZDOTDIR during the bootstrapping process and removes it when the shell is set up. ![SSH](/_astro/ssh-1.Ba7RzgnH_Z1ooVYW.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ## Implementation [Section titled “Implementation”](#implementation) We create a wrapper (around `/usr/bin/ssh`) to set up the shell for Warp’s feature set. We authenticate normally using `/usr/bin/ssh`, and bootstrap the remote shell to work with Warp Blocks and the Input Editor. You can opt out of this functionality by invoking `command ssh` directly. * Warp takes over the prompt which enables us to build a modern input editor. * Warp configures histcontrol to ignore commands with leading spaces. We do this so our bootstrapping code does not clutter the history. You can see the SSH wrapper by using `which warp_ssh_helper` in zsh, `type warp_ssh_helper` in bash. *Note:* The ssh wrapper is only *initialized* on your local machine. We don’t currently support bootstrapping nested ssh sessions. Note Warp [Completions](/terminal/command-completions/completions/) for ssh show entries in `~/.ssh/config` and `~/.ssh/known_hosts` ## Troubleshooting SSH [Section titled “Troubleshooting SSH”](#troubleshooting-ssh) ### channel 2: open failed: connect failed: open failed [Section titled “channel 2: open failed: connect failed: open failed”](#channel-2-open-failed-connect-failed-open-failed) If you’re seeing these errors, you may have some config on your server (usually in `/etc/ssh/sshd_config`) preventing Warp’s ControlMaster connection from working. In this state, completions that require information from your remote host won’t work and your history also won’t work. You should ensure that `MaxSessions` is either commented out or is at least `2`. Write access in `/etc/ssh/` typically requires sudo access. After any edits, you’d also need to restart the `sshd` daemon. ### SSH Wrapper fails [Section titled “SSH Wrapper fails”](#ssh-wrapper-fails) There are several [known issues with SSH Wrapper](https://github.com/warpdotdev/Warp/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-desc+label%3ABugs+label%3ASSH). As a workaround to the SSH Wrapper, you can add `command ssh` to your **Settings** > **Warpify** > **Subshells** > **Added commands**, then run `command ssh <user@server>` to connect to a remote session, this will attempt to enable Warp features as a [subshell](/terminal/warpify/subshells/). Note If the subshell workaround helps, we recommend you disable the SSH Wrapper in **Settings** > **Features** > **Session**. You’ll need to start a new session before a change is reflected or try invoking the SSH binary directly with `command ssh`. [![](/assets/terminal/subshell-ssh-demo.poster.jpg)](/assets/terminal/subshell-ssh-demo.mp4) # Warpify subshells > Warpify subshells in bash, zsh, and fish to get Warp features in nested sessions. ## What is a subshell? [Section titled “What is a subshell?”](#what-is-a-subshell) Within the context of Warp, a “subshell” is defined as any nested interactive shell session that’s spawned and running within the context of an existing, running shell. This can be a nested session running locally on your machine, a shell session running within a Docker container, or a remote server accessed through SSH. [See more on SSH Warpification](/terminal/warpify/ssh/). Note that Warp’s definition of a subshell differs from the more common definition of a Unix subshell, which typically refers to any shell process spawned as a child of the interactive shell. For example, in bash, a command wrapped in parentheses is executed in a subshell with its own PID and addressable memory space. ## How to Warpify the subshell [Section titled “How to Warpify the subshell”](#how-to-warpify-the-subshell) By default, Warp automatically recognizes the following commands as **subshell-compatible**: * bash, fish, zsh * docker exec * gcloud compute ssh * eb ssh * poetry shell When you run a command that’s subshell-compatible, Warp will prompt you and invite you to “Warpify” the subshell which makes all of the modern IDE features of Warp available in that subshell. The list of subshell-compatible commands is configurable in Subshell settings as described [below](/terminal/warpify/subshells/#configuring-subshell-compatible-commands). Note bash, zsh, or fish (3.6 or above) must be set as the default shell within containers and ssh sessions for the Warpification of the subshells to work. [![](/assets/terminal/subshells-demo.poster.jpg)](/assets/terminal/subshells-demo.mp4) ### Configuring subshell-compatible commands [Section titled “Configuring subshell-compatible commands”](#configuring-subshell-compatible-commands) To configure subshell-compatible commands, navigate to **Settings** > **Warpify** > **Subshells**. #### Adding compatible commands [Section titled “Adding compatible commands”](#adding-compatible-commands) You can add any command that spawns a bash, fish, or zsh subshell to ‘Added commands’ to make it eligible for “Warpification.” Furthermore, you can add regular expressions to the Added commands list. Any commands that match an added regex will be eligible for “Warpification.” #### Blocklisting commands [Section titled “Blocklisting commands”](#blocklisting-commands) Some types of subshells are not compatible, and you may also want to control Warp so it never invites you to “Warpify” the subshells for specific commands. When you add commands to the Blocklist, Warp will never invite you to “Warpify” subshells spawned by those commands. ### Automatically “Warpify” subshells [Section titled “Automatically “Warpify” subshells”](#automatically-warpify-subshells) To remember your preferences for a command and bypass the confirmation banner, you can manually paste the appropriate snippet to the end of the RC file corresponding to your subshell (bash, fish, or zsh). ```bash # For zsh subshells, add to ~/.zshrc. printf '\eP$f{"hook": "SourcedRcFileForWarp", "value": { "shell": "zsh"}}\x9c' # For bash subshells, add to ~/.bashrc or ~/.bash_profile. printf '\eP$f{"hook": "SourcedRcFileForWarp", "value": { "shell": "bash"}}\x9c' # For fish subshells, add to ~/.config/fish/config.fish. if status is-interactive printf '\eP$f{"hook": "SourcedRcFileForWarp", "value": { "shell": "fish"}}\x9c' end ``` Once added, Warp will automatically “Warpify” subsequent subshell sessions for the corresponding shell on the machine with the newly updated RC file. Under the hood, this snippet prints a Device Control String ([DCS](https://vt100.net/docs/vt510-rm/chapter4.html)) to be read by Warp, signaling that a subshell session has started and is ready to be “Warpified.” In turn, Warp executes a setup script in the session that enables the full suite of Warp features like blocks, completions, and the input editor. For this reason, it’s best to ensure the snippet is added to the end of the RC file, so Warp does not attempt to execute the setup script before the shell has finished sourcing your RC file. To disable automatic integration, remove the snippet from the corresponding RC file. If you encounter issues in subshell sessions where the RC file is sourced, [file a GitHub issue](https://github.com/warpdotdev/Warp/issues/new/choose). ## Background commands [Section titled “Background commands”](#background-commands) Warp runs background commands to power useful features like completions, syntax highlighting, and command corrections. For example, to provide completions for git checkout, Warp runs a background command that lists all git branches in the current repo. In local subshell sessions, these commands are run in forked shell processes, isolated from your interactive shell session. This is the same implementation used for any non-subshell session. In remote sessions, however, Warp takes a different approach – while a forked shell process is running on your local machine (where the Warp app is running), your remote session might be running on a server elsewhere. In these cases, Warp takes advantage of the session’s “idle time” – when no command is currently running – to run background commands directly in the session itself. These commands are executed in a non-interactive subshell process to prevent modifications to the session state (they cannot modify an environment variable, for instance). ### Show/hide background blocks [Section titled “Show/hide background blocks”](#showhide-background-blocks) By default, blocks for background commands are hidden. To show background command blocks, select ‘Show background blocks’ in the ‘Blocks’ menu of the macOS menu bar. ### Disable background commands in remote sessions [Section titled “Disable background commands in remote sessions”](#disable-background-commands-in-remote-sessions) We understand that some developers may want to disable background commands for certain or all environments. To disable background commands in remote subshell sessions, you can execute the following command in a top-level terminal session: * macOS Update the settings defaults located in `dev.warp.Warp-Stable` to include the following name-value pair: `"DisableInBandCommands": "true"`. ```bash defaults update dev.warp.Warp-Stable DisableInBandCommands true ``` * Windows Update the settings registry located at `HKCU:\Software\Warp.dev\Warp` to include the following name-value pair: `"DisableInBandCommands": "true"`. ```powershell Set-ItemProperty -Path "HKCU:\SOFTWARE\Warp.dev\Warp" -Name DisableInBandCommands -Value true ``` * Linux Update the settings file located at `~/.config/warp-terminal/user_preferences.json` to include the following name-value pair: `"DisableInBandCommands": "true"`. ```bash cd ~/.config/warp-terminal/ jq '.prefs += {"DisableInBandCommands": "true"}' user_preferences.json > tmp.json && mv tmp.json user_preferences.json ``` This will effectively disable tab completions, syntax highlighting, command corrections, and the git status prompt indicator in remote subshells. # Windows and tabs overview > Manage Warp windows, tabs, vertical tabs, split panes, and tab configurations with global hotkeys and reusable layouts. 1. [Tabs](/terminal/windows/tabs/) allow you to organize a window into multiple terminal sessions. 2. [Vertical Tabs](/terminal/windows/vertical-tabs/) replace the horizontal tab bar with a sidebar that shows rich metadata and drag-and-drop management for every tab and pane. 3. [Split Panes](/terminal/windows/split-panes/) allows you to divide a Tab into multiple rectangular *panes*, each of which is a unique terminal session. 4. [Tab Configs](/terminal/windows/tab-configs/) let you define reusable tab setups in a simple TOML file 5. [Global Hotkey](/terminal/windows/global-hotkey/) is a configurable shortcut that can show/hide a dedicated window or all windows on your chosen desktop regardless of whether the app is focused. 6. [Launch Configurations (Legacy)](/terminal/sessions/launch-configurations/) support saving a configuration of windows, tabs, and panes to open later. ## Tabs [Section titled “Tabs”](#tabs) [Tabs Demo](https://www.loom.com/embed/84d15cc7eb5a4a668bb86be9e827f261) ## Split Panes [Section titled “Split Panes”](#split-panes) [Split Panes Demo](https://www.loom.com/embed/c1104b51cab848a9bef6792ec4fd8421) ## Global Hotkey [Section titled “Global Hotkey”](#global-hotkey) [![](/assets/terminal/Dedicated-Window.poster.jpg)](/assets/terminal/Dedicated-Window.mp4) [![](/assets/terminal/Show-Hide-All-Windows.poster.jpg)](/assets/terminal/Show-Hide-All-Windows.mp4) # Configurable toolbar > Reorder, hide, and move panel toggle buttons between the left and right sides of Warp's header toolbar to match your workflow. The header toolbar holds the panel toggle buttons for the tabs panel, tools panel, agent management, Code Review, and notifications mailbox. Instead of a fixed layout, you can rearrange these buttons, move them between the left and right sides of the header, or hide the ones you don’t use. The side a button lives on also determines which side of the window its panel opens on, so you can tune Warp’s layout to match how you work. The configurable toolbar works with both [horizontal tabs](/terminal/windows/tabs/) and [vertical tabs](/terminal/windows/vertical-tabs/). [Configurable toolbar demo](https://www.loom.com/embed/292d126ecf7148f296fc8685e451790f) ## Key features [Section titled “Key features”](#key-features) * **Reorder items within a side** - Drag toolbar chips to change the left-to-right order on either side of the header. * **Move items across sides** - Drag a chip between the left and right drop zones to move its button (and the panel it opens) to the other side of the window. * **Hide items you don’t need** - Remove a chip from both sides to hide the button. Removed items become available again, so you can drop them back in later. * **Side placement drives panel side** - Moving the tools panel, tabs panel, or code review button flips the corresponding panel to open from the same side, with resize handles, borders, and anchored popups following along. * **Persistent across sessions** - Your layout is saved to settings and survives app restarts. ## Configurable items [Section titled “Configurable items”](#configurable-items) The following header buttons can be rearranged or hidden: * **Tabs panel** - Toggles the [vertical tabs](/terminal/windows/vertical-tabs/) sidebar. * **Tools panel** - Toggles the panel that contains the project explorer, global search, [Warp Drive](/knowledge-and-collaboration/warp-drive/), and conversation history. * **Agent management** - Toggles the agent management view for [cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/). * **Code review** - Toggles the [Code Review](/code/code-review/) panel. * **Notifications mailbox** - Toggles the [agent notifications](/agent-platform/capabilities/agent-notifications/) mailbox. The search bar and profile avatar are fixed and can’t be repositioned. An item only appears in the toolbar when its prerequisites are met. For example, the tabs panel button requires [vertical tabs](/terminal/windows/vertical-tabs/) to be enabled, and agent management requires Agent Mode to be enabled. If an item’s prerequisite becomes unavailable later, the button disappears but your saved layout is preserved, so the button reappears once the prerequisite is met again. ## Default layout [Section titled “Default layout”](#default-layout) The default layout matches Warp’s standard header: * **Left** - Tabs panel, tools panel, agent management. * **Right** - Code review, notifications mailbox. ## Editing the toolbar [Section titled “Editing the toolbar”](#editing-the-toolbar) You can open the toolbar editor from the header or from Settings. ### From the header [Section titled “From the header”](#from-the-header) Right-click any toolbar button (or any empty space between the buttons and the search bar) and select **Rearrange toolbar items**. The configurator modal opens. ### From Settings [Section titled “From Settings”](#from-settings) 1. In the Warp app, navigate to **Settings** > **Appearance** > **Tabs**. 2. Click **Edit toolbar**. ## How side placement affects panels [Section titled “How side placement affects panels”](#how-side-placement-affects-panels) Moving a button to the opposite side also moves where its panel opens, and Warp flips associated UI to stay readable: * **Tabs panel** - Opens its sidebar on whichever side its button sits. The hover detail sidecar, action buttons, and right-click menu flip to face the center of the screen. * **Tools panel** - Opens on the side its button sits. Warp Drive hover previews, kebab menus, and dialogs flip toward the center. The resize handle and border switch to the edge facing the main content. * **Code review** - Opens on the side its button sits, with a matching resize handle. * **Agent management** - Replaces the main content area when opened, so side placement only affects the button’s position, not where the view renders. * **Notifications mailbox** - The popover anchors under its button, and notification toasts appear on the same side as the mailbox button. When multiple panels are open on the same side, they render in the order their buttons appear in the toolbar. For example, if the left-side order is code review, tabs panel, tools panel, the panels open in that same order from left to right, with the main content to their right. ## Related pages [Section titled “Related pages”](#related-pages) * [Vertical tabs](/terminal/windows/vertical-tabs/) - The sidebar toggled by the tabs panel button. * [Code Review panel](/code/code-review/) - The panel toggled by the code review button. * [Agent notifications](/agent-platform/capabilities/agent-notifications/) - The mailbox toggled by the notifications button. * [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - The view toggled by the agent management button. * [Warp Drive](/knowledge-and-collaboration/warp-drive/) - One of the views available in the tools panel. # Global Hotkey > Show or hide Warp instantly with a global hotkey, including a dedicated Quake-style drop-down window. Note On macOS, [system keyboard shortcuts](https://support.apple.com/en-us/HT201236) like `CMD-ESC`, `CMD-BACKTICK`, `CMD-TAB`, `CMD-PERIOD`, and `CMD-TILDE` need to be [unbound](https://support.apple.com/guide/mac-help/keyboard-shortcuts-mchlp2262/mac) before you can use them in Warp. Caution On Linux, the Global Hotkey may not work for some X11 window managers that do not implement [Extended Window Manager Hints](https://en.wikipedia.org/wiki/Extended_Window_Manager_Hints). Some examples include: [sowm](https://github.com/dylanaraps/sowm), [catwm](https://github.com/pyknite/catwm), [Fvwm](https://www.fvwm.org/), [dwm](https://dwm.suckless.org/), [2bWM](https://github.com/venam/2bwm), [monsterwm](https://github.com/c00kiemon5ter/monsterwm), [TinyWM](https://github.com/mackstann/tinywm), [x11fs](https://github.com/sdhand/x11fs), [XMonad](https://xmonad.org/) ## How to access it [Section titled “How to access it”](#how-to-access-it) ### Dedicated window [Section titled “Dedicated window”](#dedicated-window) Dedicated Window allows you to customize the windows’ pinned position and its width and height ratio relative to your active screen size (also known as Quake Mode). 1. Open **Settings** > **Features** > **Keys** and select “Dedicated hotkey window” from the Global Hotkey dropdown to enable the feature. 2. Configure the keybinding, the windows position, screen, and relative size or uncheck “Autohides on the loss of keyboard focus” which will cause the dedicated Hotkey Window to stay on top when triggered regardless of mouse or keyboard focus. Caution On Linux and Windows, Warp does not support the “Autohides on the loss of keyboard focus” feature. ### Show/hide all windows [Section titled “Show/hide all windows”](#showhide-all-windows) Show/Hide All Windows allows you to configure a shortcut to show/hide all Warp windows. 1. Open **Settings** > **Features** > **Keys** and select “Show/hide all windows” from the Global Hotkey dropdown to enable the feature. 2. Configure your preferred keybinding. Caution On Linux, hidden windows may not appear in your `ALT-TAB` window switcher menu. Furthermore, the ordering of windows beyond the top window may change after toggling. ## How it works [Section titled “How it works”](#how-it-works) [![](/assets/terminal/Dedicated-Window.poster.jpg)](/assets/terminal/Dedicated-Window.mp4) [![](/assets/terminal/Show-Hide-All-Windows.poster.jpg)](/assets/terminal/Show-Hide-All-Windows.mp4) ## Troubleshooting hotkey dedicated window [Section titled “Troubleshooting hotkey dedicated window”](#troubleshooting-hotkey-dedicated-window) Review platform-specific instructions for troubleshooting the global hotkey below * macOS If the keybinding doesn’t work, check under `System Preferences > Security & Privacy > Accessibility` and tick the checkbox to grant Warp access. * Windows On Windows, there are no known issues with Global Hotkey Dedicated Window. If you find an issue, please [send feedback](/support-and-community/troubleshooting-and-support/sending-us-feedback/) to let us know. * Linux The hotkey window may appear on the incorrect monitor under certain window sizes. For example, with GNOME, if the hotkey window is supposed to show on a monitor having the taskbar (GNOME Panel), and the window height is 100%, causing an overlap, the hotkey window may fallback to showing on an external monitor if you have one. Try working around this by setting a window height to a lesser percentage, e.g. 90%. # Split panes > The split panes feature allows you to divide a tab into multiple rectangular panes, each of which is a unique terminal session. ## How to use split panes [Section titled “How to use split panes”](#how-to-use-split-panes) * macOS * Split panes to the right / down with `CMD-D` / `SHIFT-CMD-D` or in any direction by right-clicking on any Pane. * Activate the Previous / Next Pane with `CMD-[` / `CMD-]` or by clicking a pane. * Navigate among split panes with `OPT-CMD-ARROW`, the active pane will be marked with a triangle in the top corner. * Toggle Maximize Pane with `CMD-SHIFT-ENTER`. * Close the active Pane with `CMD-W`. * You can also drag and drop panes. Click and drag a Pane’s header around a given tab, drag the Pane to the tab bar to move it to another Tab, or make it into a Tab. * Windows * Split Panes to the right / down with `CTRL-SHIFT-D` / `CTRL-SHIFT-E` or in any direction by right-clicking on any Pane. * Activate the Previous / Next Pane with `CTRL-SHIFT-{` / `CTRL-SHIFT-}` or by clicking a pane. * Navigate among Split Panes with `CTRL-ALT-ARROW`, the active pane will be marked with a triangle in the top corner. * Toggle Maximize Pane with `CTRL-SHIFT-ENTER`. * Close the active Pane with `CTRL-SHIFT-W`. * You can also drag and drop panes. Click and drag a Pane’s header around a given tab, drag the Pane to the tab bar to move it to another Tab, or make it into a Tab. * Linux * Split Panes to the right / down with `CTRL-SHIFT-D` / `CTRL-SHIFT-E` or in any direction by right-clicking on any Pane. * Activate the Previous / Next Pane with `CTRL-SHIFT-{` / `CTRL-SHIFT-}` or by clicking a pane. * Navigate among Split Panes with `CTRL-ALT-ARROW`, the active pane will be marked with a triangle in the top corner. * Toggle Maximize Pane with `CTRL-SHIFT-ENTER`. * Close the active Pane with `CTRL-SHIFT-W`. * You can also drag and drop panes. Click and drag a Pane’s header around a given tab, drag the Pane to the tab bar to move it to another Tab, or make it into a Tab. Note You can quickly find all the **pane** shortcuts by using the [Command Palette](/terminal/command-palette/). You can also remap the shortcuts to your liking. See [Custom Keyboard Shortcuts](/getting-started/keyboard-shortcuts/#custom-keyboard-shortcuts) for more details. ### CTRL-TAB behavior [Section titled “CTRL-TAB behavior”](#ctrl-tab-behavior) `CTRL-TAB` shortcut defaults to activate the previous / next [Tabs](/terminal/windows/tabs/). You can configure the shortcut to cycle the most recent session, including any split panes, in **Settings** > **Features** > **Keys** > **Ctrl-Tab behavior** ## How split panes work [Section titled “How split panes work”](#how-split-panes-work) [Split Panes Demo](https://www.loom.com/embed/c1104b51cab848a9bef6792ec4fd8421) [![](/assets/terminal/split-panes-dragging-demo.poster.jpg)](/assets/terminal/split-panes-dragging-demo.mp4) # Tab Configs > Tab Configs let you define reusable tab setups — including directory, startup commands, pane layout, shell, and theme — in a simple TOML file. Tab Configs let you define reusable tab setups — including directory, startup commands, pane layout, shell, and theme — in a simple TOML file. Select a Tab Config from the `+` menu to open a fully configured tab with a single click. ## How Tab Configs work [Section titled “How Tab Configs work”](#how-tab-configs-work) Each Tab Config is a `.toml` file stored in `~/.warp/tab_configs/`. Every file defines a single tab layout with optional pane splits, startup commands, and parameterized inputs. Tab Configs appear in the `+` menu alongside your existing tabs, so you can launch a preconfigured workspace instantly. ## Creating a Tab Config [Section titled “Creating a Tab Config”](#creating-a-tab-config) ### From the UI [Section titled “From the UI”](#from-the-ui) 1. Click the **+** button in the tab bar to open the new-tab menu. 2. Click **+ New tab config**. Warp creates a new `.toml` file in `~/.warp/tab_configs/` and opens it for editing. ### Manually [Section titled “Manually”](#manually) 1. Create a new `.toml` file in `~/.warp/tab_configs/`. Use snake\_case for the file name (e.g., `dev_server.toml`). 2. Define the tab layout using the schema below, then save the file. The new config appears in the `+` menu automatically. ### Save an existing tab as a Tab Config [Section titled “Save an existing tab as a Tab Config”](#save-an-existing-tab-as-a-tab-config) You can also capture a tab’s current state as a reusable Tab Config without writing TOML. Right-click any tab in the [vertical tabs](/terminal/windows/vertical-tabs/) panel or horizontal tab bar to open the context menu, then click **Save as new config**. Warp generates a `.toml` file from the tab’s layout, commands, and directory and adds it to the `+` menu. ![Tab context menu in Warp's vertical tabs panel with Save as new config highlighted](/_astro/save-new-tab-config.Dsmhq0Di_Z6Qgvd.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Saving a tab config. ## Managing Tab Configs [Section titled “Managing Tab Configs”](#managing-tab-configs) Saved Tab Configs appear in the `+` menu for quick access. When you hover a Tab Config in the menu, a **sidecar panel** appears alongside it with options to: * **Edit config** — Open the underlying `.toml` file for manual editing. The editor also shows a footer to invoke the **update tab config** skill, so you can describe changes in natural language and have Warp’s agent apply them. * **Remove** — Remove the Tab Config from the `+` menu. * **Make default** — Assign the Tab Config as the default `Cmd T` action for new tabs. ![Warp's + menu open with a saved screenshots\_tab\_config entry highlighted, and a sidecar panel showing Make default, Edit config, and Remove action buttons](/_astro/saved-tab-config-menu.DEhwYYBm_1kkNMq.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Tab config menu with sidecar options. ## Using skills to manage Tab Configs [Section titled “Using skills to manage Tab Configs”](#using-skills-to-manage-tab-configs) Warp includes built-in skills for creating and modifying Tab Configs through natural language: * **Create Tab Config** — Generate a new Tab Config from a description (e.g., “create a 2x2 grid with one pane running my dev server”). * **Update Tab Config** — Modify an existing Tab Config by describing the changes you want. To use these skills, type `/skills` in Agent Mode and select the tab config skill, or use the footer that appears when editing a Tab Config file. ## Tab Config TOML schema [Section titled “Tab Config TOML schema”](#tab-config-toml-schema) ### Top-level fields [Section titled “Top-level fields”](#top-level-fields) * **`name`** (required, string) — display name shown in the `+` menu. * **`title`** (optional, string) — custom tab title. Supports `{{param}}` template variables. * **`color`** (optional, string) — tab color. One of: `"black"`, `"red"`, `"green"`, `"yellow"`, `"blue"`, `"magenta"`, `"cyan"`, `"white"`. Actual color values are derived from your Warp [Theme](/terminal/appearance/themes/). ### Pane list [Section titled “Pane list”](#pane-list) All panes are defined in a flat `[[panes]]` array. The first entry is the root of the pane tree. Each entry is either a **split node** (branch) or a **leaf node**. #### Leaf node fields [Section titled “Leaf node fields”](#leaf-node-fields) * **`id`** (required, string) — unique identifier for this pane. Use descriptive names like `"editor"` or `"server"`. * **`type`** (required, string) — `"terminal"` (standard shell), `"agent"` (opens in Agent Mode), or `"cloud"` (cloud mode pane, no local shell). * **`directory`** (optional, string) — initial working directory. Supports `~` expansion and `{{param}}` template variables. * **`commands`** (optional, array of strings) — commands to run in sequence when the tab opens. * **`shell`** (optional, string) — shell executable to use for this pane (e.g. `"pwsh"`, `"zsh"`, `"bash"`, `"fish"`). Only applies to `terminal` and `agent` pane types. If omitted or the specified shell is not installed, the user’s default shell is used. * **`is_focused`** (optional, bool) — set to `true` on at most one pane to give it initial focus. #### Split node fields [Section titled “Split node fields”](#split-node-fields) * **`id`** (required, string) — unique identifier for this split. * **`split`** (required, string) — `"horizontal"` (children arranged left-to-right) or `"vertical"` (children arranged top-to-bottom). * **`children`** (required, array of strings) — ordered list of child pane `id` values. Must contain at least 2 entries. Order determines visual order. Note All children within a split are equally sized. There are no flex or proportion values. ### Parameters [Section titled “Parameters”](#parameters) Parameters let users fill in values at open time via a modal prompt. Declare them with `[params.<name>]` tables and reference them in `directory`, `commands`, and `title` using `{{name}}` syntax. Each parameter has: * **`type`** (optional, string) — `"text"` (default, freeform input), `"branch"` (Git branch picker), or `"repo"` (repository picker). * **`description`** (optional, string) — label shown in the fill-in UI. * **`default`** (optional, string) — default value. `{{autogenerated_branch_name}}` is a reserved template variable. If a Tab Config references it, Warp generates a unique worktree branch name on each open instead of prompting the user. ## Examples [Section titled “Examples”](#examples) ### Single pane [Section titled “Single pane”](#single-pane) A simple config that opens a terminal in a project directory and starts a dev server: ```toml name = "Dev Server" [[panes]] id = "main" type = "terminal" directory = "~/code/my-app" commands = ["npm run dev"] ``` ### Two panes side by side [Section titled “Two panes side by side”](#two-panes-side-by-side) An editor and server running in parallel, with the editor focused: ```toml name = "Editor + Server" color = "green" [[panes]] id = "root" split = "horizontal" children = ["editor", "server"] [[panes]] id = "editor" type = "terminal" directory = "~/code/my-app" commands = ["nvim ."] is_focused = true [[panes]] id = "server" type = "terminal" directory = "~/code/my-app" commands = ["npm run dev"] ``` ### Cross-shell development [Section titled “Cross-shell development”](#cross-shell-development) A config that opens two panes side by side, each with a different shell: ```toml name = "Cross Shell" color = "cyan" [[panes]] id = "root" split = "horizontal" children = ["bash_pane", "pwsh_pane"] [[panes]] id = "bash_pane" type = "terminal" shell = "bash" directory = "~/code/my-app" is_focused = true [[panes]] id = "pwsh_pane" type = "terminal" shell = "pwsh" directory = "~/code/my-app" ``` ### Worktree with parameters [Section titled “Worktree with parameters”](#worktree-with-parameters) A parameterized config that creates a new Git worktree on open: ```toml name = "New Worktree" title = "{{branch_name}}" [[panes]] id = "main" type = "terminal" directory = "{{repo}}" commands = [ "git worktree add -b {{branch_name}} ../{{branch_name}} {{base_branch}}", "cd ../{{branch_name}}", ] [params.repo] type = "repo" description = "Repository path" [params.base_branch] type = "branch" description = "Base branch to branch from" [params.branch_name] type = "text" description = "New branch name" default = "my-feature" ``` ### Quick worktree setup [Section titled “Quick worktree setup”](#quick-worktree-setup) You can also create a worktree-based Tab Config directly from the `+` menu by clicking **New worktree config** and selecting the repo you want your worktree to be from. Warp generates the Tab Config automatically and saves it for future use. ## Related pages [Section titled “Related pages”](#related-pages) * [Launch Configurations (Legacy)](/terminal/sessions/launch-configurations/) — the previous session configuration format. Existing configs still work, but Tab Configs are the recommended approach for new setups. * [Tabs](/terminal/windows/tabs/) — tab management, keyboard shortcuts, and behavior settings * [Themes](/terminal/appearance/themes/) — customize the colors used by tab color settings * [Working Directory](/terminal/more-features/working-directory/) — how Warp resolves working directories * [Third-Party CLI Agents](/agent-platform/cli-agents/overview/) — use the `"agent"` pane type to open tabs in Agent Mode # Tabs > Organize your window into multiple terminal sessions with customizable tabs, complete with titles and ANSI colors. Note New Tabs will default to the active Tabs’ current [Working Directory](/terminal/more-features/working-directory/) and the actual color values will be automatically derived from your Warp [Theme](/terminal/appearance/themes/). ## How to use Tabs [Section titled “How to use Tabs”](#how-to-use-tabs) * macOS * Right-click on the new Tab button `+` to make a new tab, restore closed tab, or run a saved [Launch Configuration](/terminal/sessions/launch-configurations/). * Open a new Tab with `CMD-T` or by clicking on the `+` in the top bar. * Close the current Tab with `CMD-W` or by clicking on the `X` on hover over a Tab. * Reopen closed tabs with `SHIFT-CMD-T`. * Move a Tab to the Left / Right with `CTRL-SHIFT-LEFT` / `CTRL-SHIFT-RIGHT` or by clicking and dragging a Tab. * Activate the Previous / Next Tab with `SHIFT-CMD-{` / `SHIFT-CMD-}` or by clicking a Tab. * Activate the first through eighth Tabs with `CMD-1` thru `CMD-8`. * Switch to the last Tab with `CMD-9`. * Double-click a Tab to rename it. * Right-clicking on a Tab reveals more options you can explore within the [Command Palette](/terminal/command-palette/) or [Keyboard Shortcuts](/getting-started/keyboard-shortcuts/#fundamentals). * Windows * Right-click on the new Tab button `+` to make a new tab, restore closed tab, or run a saved [Launch Configuration](/terminal/sessions/launch-configurations/). * Open a new Tab with `CTRL-SHIFT-T` or by clicking on the `+` in the top bar. * Close the current Tab with `CTRL-SHIFT-W` or by clicking on the `x` on hover over a Tab. * Reopen closed tabs with `CTRL-ALT-T`. * Move a Tab to the Left / Right with `CTRL-SHIFT-LEFT` / `CTRL-SHIFT-RIGHT` or by clicking and dragging a Tab. * Activate the Previous / Next Tab with `CTRL-PGUP` / `CTRL-PGDN` or by clicking a Tab. * Activate the first through eighth Tabs with `CTRL-1` thru `CTRL-8`. * Switch to the last Tab with `CTRL-9`. * Double-click a Tab to rename it. * Right-clicking on a Tab reveals more options you can explore within the [Command Palette](/terminal/command-palette/) or [Keyboard Shortcuts](/getting-started/keyboard-shortcuts/#fundamentals). * Linux * Right-click on the new Tab button `+` to make a new tab, restore closed tab, or run a saved [Launch Configuration](/terminal/sessions/launch-configurations/). * Open a new Tab with `CTRL-SHIFT-T` or by clicking on the `+` in the top bar. * Close the current Tab with `CTRL-SHIFT-W` or by clicking on the `x` on hover over a Tab. * Reopen closed tabs with `CTRL-ALT-T`. * Move a Tab to the Left / Right with `CTRL-SHIFT-LEFT` / `CTRL-SHIFT-RIGHT` or by clicking and dragging a Tab. * Activate the Previous / Next Tab with `CTRL-PGUP` / `CTRL-PGDN` or by clicking a Tab. * Activate the first through eighth Tabs with `CTRL-1` thru `CTRL-8`. * Switch to the last Tab with `CTRL-9`. * Double-click a Tab to rename it. * Right-clicking on a Tab reveals more options you can explore within the [Command Palette](/terminal/command-palette/) or [Keyboard Shortcuts](/getting-started/keyboard-shortcuts/#fundamentals). Tip **Terminal Tip**\ Using your `.zshrc` or `.bashrc` files on macOS or Linux, you can set a new Tab name: ```bash # Set name, where MyTabName would be whatever you want to see in the Tab ( either a fixed string, $PWD, or something else ) function set_name () { export WARP_DISABLE_AUTO_TITLE=true echo -ne "\033]0;MyTabName\007" } # Add the function to the environment variable in either Zsh or Bash if [ -n "$ZSH_VERSION" ]; then preexec_functions+=(set_name) elif [ -n "$BASH_VERSION" ]; then PROMPT_COMMAND='set_name' fi ``` Learn more about Tab names [here](https://learn.microsoft.com/en-us/windows/terminal/tutorials/tab-title#set-the-shells-title). ### Tab Restoration [Section titled “Tab Restoration”](#tab-restoration) Tab Restoration enables you to reopen recently closed tabs for up to 60 seconds. Configure this feature in **Settings** > **Features** > **Session** > **Enable reopening of closed sessions** ### CTRL-TAB Behavior [Section titled “CTRL-TAB Behavior”](#ctrl-tab-behavior) `CTRL-TAB` shortcut defaults to activate the previous / next Tab. You can configure the shortcut to cycle the most recent session, including any [Split Panes](/terminal/windows/split-panes/), in **Settings** > **Features** > **Keys** > **Ctrl-Tab behavior** ### Tabs Behavior [Section titled “Tabs Behavior”](#tabs-behavior) Please see our [Appearance > Tabs Behavior](/terminal/appearance/tabs-behavior/) docs for more Tab related settings. ### How Tabs work [Section titled “How Tabs work”](#how-tabs-work) [Tabs Demo](https://www.loom.com/embed/84d15cc7eb5a4a668bb86be9e827f261) # Vertical Tabs > The vertical tabs panel replaces the horizontal tab bar with a sidebar showing rich metadata, drag-and-drop management, and display options for tabs and panes. The vertical tabs panel is a sidebar that replaces the traditional horizontal tab bar with a richer, more powerful tab management surface. Instead of a single row of tab titles, the panel displays every tab and pane with contextual metadata — Git branch, working directory, agent conversation status, diff stats, and more. Scan and switch between workstreams without losing context. Vertical tabs are especially useful when running multiple coding agents side by side, giving you a clear overview of each session’s state without switching tabs. ## Key features [Section titled “Key features”](#key-features) ### Rich metadata and status [Section titled “Rich metadata and status”](#rich-metadata-and-status) * **Pane metadata** - See working directory, Git branch, agent conversation status, diff stats, and PR badges at a glance for every pane. * **Agent status badges** - Pane icons display a colored badge overlay showing agent state (in progress, done, errored, cancelled, or blocked). [Third-party CLI agents](/agent-platform/cli-agents/overview/) like Claude Code, Codex, and Gemini CLI display their brand icon and color alongside badges. * **Notification indicators** - An accent-colored dot appears on pane rows with unread agent activity, so you can spot sessions that need attention without switching tabs. ### Display modes and customization [Section titled “Display modes and customization”](#display-modes-and-customization) * **Pane or tab view** - Display every split pane as its own row (**Panes**) or show only the focused pane per tab (**Tabs**). * **Compact and expanded modes** - Choose between a dense single-line view (default) or a detailed multi-line layout with full metadata. * **Configurable pane titles** - Control which metadata appears first: last command or conversation, working directory, or Git branch. * **Hover detail sidecar** - Hover any pane row to see full, un-clipped metadata in a floating detail card without changing focus. ### Tab management [Section titled “Tab management”](#tab-management) * **Search, drag and drop, and renaming** - Filter panes by title, directory, or branch; reorder tabs or move panes between tabs by dragging; double-click a tab to rename it inline. * **New tab menu** - Create agent tabs, terminal tabs, Oz cloud agent sessions, worktree configs, and [Tab Configs](/terminal/windows/tab-configs/) from a unified **+** menu. ## Enabling vertical tabs [Section titled “Enabling vertical tabs”](#enabling-vertical-tabs) To switch from horizontal tabs to the vertical tabs panel: 1. In the Warp app, navigate to **Settings** > **Appearance** > **Tabs**. 2. Toggle **Use vertical tab layout** on. The vertical tabs panel appears as a resizable sidebar on the left side of the window. The horizontal tab bar is hidden while vertical tabs are active. ![A Warp window with the vertical tabs sidebar on the left listing a Claude Code tab and a codex tab alongside the main terminal pane](/_astro/multi-agents.BnUFIPfc_ZoqSlt.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Vertical tab with agent details. Note You can also toggle vertical tabs from the [Command Palette](/terminal/command-palette/) by searching for “vertical tab layout.” ## View modes [Section titled “View modes”](#view-modes) The vertical tabs panel supports two display densities that you can switch between at any time. ### Compact mode [Section titled “Compact mode”](#compact-mode) Compact mode is the default. Each pane row displays an icon and title on one line, with an optional subtitle below it. The subtitle is configurable via the **Additional metadata** setting in the settings popup. ![Vertical tabs sidebar in compact mode with each pane row showing an icon, title, and a short subtitle below](/_astro/vertical-tabs-condensed.D_7Ir3Kr_Z2dciRF.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Vertical tabs in compact mode. ### Expanded mode [Section titled “Expanded mode”](#expanded-mode) Expanded mode shows each pane row with a title, description (such as the working directory or file path), and metadata (Git branch, diff stats badge, and PR badge when available). ![Vertical tab rows in expanded mode showing titles, working directories, Git branches, diff stats, and agent status badges](/_astro/vertical-tabs-multi-agent.BFeWyl4n_ZJrRky.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Vertical tabs overview. ### Switching view modes [Section titled “Switching view modes”](#switching-view-modes) Click the settings icon (sliders) in the control bar at the top of the vertical tabs panel. In the popup, use the **Density** segmented control to switch between compact and expanded views. The change takes effect immediately. ![The vertical tabs settings popup anchored to the sliders icon, showing View as, Density, Pane title as, Additional metadata, and Show details on hover options](/_astro/vertical-tab-settings.BXRWNhi8_Z1wqe6C.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Vertical tabs settings popup. ## Customizing vertical tabs [Section titled “Customizing vertical tabs”](#customizing-vertical-tabs) When vertical tabs are enabled, configure their appearance and behavior from the settings popup (click the sliders icon in the control bar) or from **Settings** > **Appearance** > **Tabs**. You can also rearrange the panel toggle buttons at the top of the Warp window — including the tabs panel, tools panel, agent management, code review, and notifications mailbox — and move them between the left and right sides of the header. See [Configurable toolbar](/terminal/windows/configurable-toolbar/) for details. | Setting | Availability | Options | Default | | ------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | **View as** | Always | **Panes** — each split pane gets its own row. **Tabs** — only the focused pane per tab is shown. | Panes | | **Density** | Always | **Compact** — smaller rows with title and optional subtitle. **Expanded** — larger rows with title, description, and metadata. | Compact | | **Pane title as** | Always | **Command / Conversation** — last command, conversation title, or CLI agent session name. **Working Directory** — pane’s working directory. **Branch** — checked-out Git branch. | Command / Conversation | | **Additional metadata** | Compact mode only | **Branch** **Working Directory** **Command / Conversation** (options depend on the **Pane title as** setting; duplicates are excluded). | Branch | | **Show** | Expanded mode only | **PR link** — pull request and status for the current branch (requires GitHub CLI). **Diff stats** — lines added/removed. | — | | **Show details on hover** | Always | On / Off — toggles the hover detail sidecar. | On | ### Automatic metadata [Section titled “Automatic metadata”](#automatic-metadata) The following metadata appears automatically and doesn’t require configuration: * **Git branch** - The currently checked-out branch for the pane’s working directory. * **Worktree** - The active [Git worktree](/code/git-worktrees/) path, if applicable. * **Agent status** - A colored badge on the pane icon indicating the agent’s current state (see [Agent status badges](#agent-status-badges) below). * **Notification dot** - An accent-colored dot on the title row when a pane has unread agent activity. ## Agent status badges [Section titled “Agent status badges”](#agent-status-badges) Agent pane icons display a small circular badge overlay in the bottom-right corner that reflects the agent’s current state: | Status | Icon | Meaning | | --------------- | ------------- | -------------------------------------------------- | | **In progress** | Magenta clock | The agent is actively running. | | **Done** | Green check | The agent’s last turn completed successfully. | | **Error** | Red triangle | The agent’s last turn completed with an error. | | **Cancelled** | Gray stop | The user cancelled the agent’s last turn. | | **Blocked** | Yellow stop | The agent is waiting for user approval to proceed. | ![Vertical tabs sidebar with four tab rows showing different agent status badges: a yellow blocked square, a magenta in-progress moon on the Claude Code brand icon, and green completion checks](/_astro/agent-status-badges.BZmH2FMT_200WhP.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Agent status badges on vertical tabs. Third-party CLI agents (Claude Code, Codex, Gemini CLI, and others) display their brand icon and color inside the circular pane icon, with the same status badge overlay. When a pane has unread agent activity, an accent-colored notification dot appears at the right edge of the title row. The dot clears when you focus the pane. ## Managing tabs [Section titled “Managing tabs”](#managing-tabs) ### Search [Section titled “Search”](#search) The control bar at the top of the vertical tabs panel includes a search field. Type to filter the visible tabs and panes by title, working directory, Git branch, PR label, or diff stats. Only matching tabs remain visible while the search query is active. ### New tab menu [Section titled “New tab menu”](#new-tab-menu) Click the **+** button in the control bar to open the new tab menu. The menu includes: * **Agent** - Open a new agent tab. * **Terminal** - Open a new terminal tab. * **Oz cloud agent** - Open a new Oz cloud agent session tab. * **Tab Configs** - Any [Tab Configs](/terminal/windows/tab-configs/) you’ve created appear as menu items for one-click setup. * **New worktree config** - Create a new worktree-based Tab Config. * **New tab config** - Create a new Tab Config from a starter template. ### Drag and drop [Section titled “Drag and drop”](#drag-and-drop) Reorder tabs by dragging tab group headers within the panel. To move a pane from one tab to another, drag the pane header over a different tab group in the panel. Warp switches to that tab so you can place the pane using the standard drop targets. Dropping a pane between tab groups creates a new tab at that position. ### Tab renaming [Section titled “Tab renaming”](#tab-renaming) Double-click a tab row to rename it inline. Press `Enter` to confirm or `Esc` to cancel. Note Renaming applies to tabs only. Individual panes can’t be renamed at this time. ## Hover detail sidecar [Section titled “Hover detail sidecar”](#hover-detail-sidecar) Hover any pane row to open a floating detail card anchored to the right side of the panel. The sidecar shows full, un-clipped metadata (complete directory paths, full branch names, and the full conversation or command title) without changing which pane is focused. ![The vertical tabs panel with a Claude Code tab hovered, showing a floating detail card with the agent's In progress status, working directory, and session title](/_astro/tab-hover-detail-card.mP2qkvae_1G3f2e.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Hover detail card for a vertical tab. The sidecar stays open as you move the cursor from the row into the card. Move away from both the row and the sidecar to dismiss it. Disable this behavior with the **Show details on hover** toggle in the settings popup. ## Keyboard shortcuts [Section titled “Keyboard shortcuts”](#keyboard-shortcuts) All existing tab keyboard shortcuts continue to work with vertical tabs. The sidebar layout changes how tabs are displayed, not how you interact with them. See [Terminal tabs](/terminal/windows/tabs/) for the full list of tab shortcuts. ## Related pages [Section titled “Related pages”](#related-pages) * [Terminal tabs](/terminal/windows/tabs/) - Horizontal tab bar usage and keyboard shortcuts * [Split panes](/terminal/windows/split-panes/) - Divide tabs into multiple terminal panes * [Tab Configs](/terminal/windows/tab-configs/) - Define reusable tab setups in TOML files * [Git Worktrees](/code/git-worktrees/) - Worktree support that surfaces in vertical tab metadata * [Tabs behavior](/terminal/appearance/tabs-behavior/) - Tab bar visibility, indicators, and close button settings * [Third-party CLI agents](/agent-platform/cli-agents/overview/) - Use Claude Code, Codex, Gemini CLI, and other third-party agents with Warp’s utility bar, including brand icons and status badges in the vertical tabs panel

This is the full developer documentation for Warp # Getting started with Warp and Oz > Get started with Warp, the Agentic Development Environment, and Oz, the orchestration platform for cloud agents. Warp is an [open source](https://github.com/warpdotdev/warp) **Agentic Development Environment**, a modern terminal combined with powerful agents that help you build, test, deploy, and debug code. Warp’s AI is powered by **Oz**, the orchestration platform for cloud agents. ![Warp, the Agentic Development Environment: Warp (a modern terminal built for coding with agents) and Oz (the orchestration platform for cloud agents)](/_astro/warp-oz-welcome.CJ98vPIF_1hNcu2.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Warp terminal with Oz orchestration. *** ## Warp [Section titled “Warp”](#warp) Warp is where you work — a fast, modern terminal built for coding with agents. **Key capabilities:** * [**Terminal and Agent modes**](/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes/): Switch between a clean terminal for commands and a dedicated conversation view for multi-turn agent workflows. * [**Modern terminal UX**](/terminal/editor/): Cursor movement, block-based navigation, multi-line editing, syntax highlighting, and rich completions. Built with Rust for high performance. * [**Code editor**](/code/overview/): File tree, code editor with LSP support, and interactive code review experience. * [**Third-Party CLI Agents**](/agent-platform/cli-agents/overview/): Run third-party CLI agents like Claude Code, Codex, and OpenCode with Warp’s agent toolbelt — rich input, code review, notifications, and more. ![Deep dive into Warp's core features](https://i.ytimg.com/vi/xhkoXsE9Wqc/sddefault.jpg) *** ## Oz: The orchestration platform for cloud agents [Section titled “Oz: The orchestration platform for cloud agents”](#oz-the-orchestration-platform-for-cloud-agents) Oz is the orchestration platform for cloud agents that powers all of Warp’s intelligent features. Oz is designed to coordinate agents at scale—understanding your codebase, executing tasks autonomously, and adapting to your workflows. Oz is multi-model by design, giving you flexibility to choose the best LLM for each task. Oz operates in two modes: ### Local agents [Section titled “Local agents”](#local-agents) Run directly in the Warp app for real-time, interactive coding assistance. * Write and refactor code across your codebase * Debug issues and fix errors * Run commands and interpret results * Plan and execute multi-step tasks Local agents keep you in control. You can review changes, steer the agent mid-task, and approve actions before they execute. → [Get started with local agents](/agent-platform/local-agents/overview/) ### Cloud agents [Section titled “Cloud agents”](#cloud-agents) Oz Cloud Agents run in the background on Warp’s infrastructure (or your own) for automation at scale. * **Triggers**: React to events from Slack, Linear, GitHub, or custom webhooks * **Schedules**: Run recurring tasks like dependency updates or dead code removal * **Parallelism**: Run many agents concurrently across repos or tasks * **Observability**: Every run is tracked, auditable, and shareable with your team Cloud agents are ideal for work that doesn’t need your immediate attention, like PR reviews, issue triage, routine maintenance, and integration-driven workflows. → [Learn about cloud agents](/agent-platform/cloud-agents/overview/) *** ## How they work together [Section titled “How they work together”](#how-they-work-together) Warp and Oz provide a unified experience across local and cloud development: * **Same agent, anywhere**: Whether you’re working interactively in Warp or running agents in the cloud, you’re using the same underlying agent capabilities. * **Seamless handoff**: Start a task in the cloud and take over locally in Warp when you want hands-on control, without losing progress or context. * **Shared context**: [Warp Drive](/knowledge-and-collaboration/warp-drive/), [Rules](/agent-platform/capabilities/rules/), and [MCP servers](/agent-platform/capabilities/mcp/) work across both local and cloud agents, so your team’s knowledge and tools are always available. * **Team collaboration**: Share agent sessions, review agents’ actions, and steer running tasks, regardless of who started them. *** ## Multi-model support [Section titled “Multi-model support”](#multi-model-support) Oz is multi-model by design. You can [choose your preferred LLM](/agent-platform/capabilities/model-choice/) from a curated set of top models. *** ## Open source [Section titled “Open source”](#open-source) Warp’s client is open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE). The source lives at [`warpdotdev/warp`](https://github.com/warpdotdev/warp), where you can read the code, file issues, and contribute alongside the Warp team. Development happens in the open with an agent-first workflow managed by Oz. → [Contributing to Warp](/support-and-community/community/contributing/) explains how to file issues, claim work, and ship code or themes. *** ## Privacy and security [Section titled “Privacy and security”](#privacy-and-security) Warp is **SOC 2 compliant** and has **Zero Data Retention** policies with all contracted LLM providers. No customer AI data is retained, stored, or used for training. Warp’s AI features can be globally disabled in **Settings** > **Agents** > **Warp Agent**. → [Read more about data privacy](https://www.warp.dev/privacy) *** ## Next steps [Section titled “Next steps”](#next-steps) * [**Quickstart**](/quickstart/): Get Warp installed and start coding * [**Warp Agents overview**](/agent-platform/local-agents/overview/): Explore all AI features available in Warp * [**Cloud Agents Overview**](/agent-platform/cloud-agents/overview/): Set up background automation * [**Oz Platform**](/agent-platform/cloud-agents/platform/): Learn about the CLI, API, SDK, and infrastructure # Agents overview > Oz is the orchestration platform for cloud agents, powering both interactive and autonomous agents for development workflows. Warp includes **Oz**, the orchestration platform for cloud agents. While Warp provides the terminal and coding surface you work in day-to-day, Oz is the underlying orchestration layer that makes running agents at scale possible. Warp’s client is open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE), so the editor and terminal that host your agents are fully auditable. See [Contributing to Warp](/support-and-community/community/contributing/) for the source and contribution flow. With Oz, you can: * Run interactive agent conversations in Warp for real-time coding assistance * Deploy autonomous agents that run in the cloud from triggers, schedules, or integrations * Coordinate multiple agents concurrently across machines, repos, and teams * Track, audit, and share agent activity with full visibility into what ran and what it did Oz is fully programmable—launch agents manually or build custom logic around them with triggers, schedules, environments, and your choice of hosting (Warp’s cloud or your own). *** ## Key capabilities [Section titled “Key capabilities”](#key-capabilities) * [**Local Agents**](/agent-platform/local-agents/overview/) - Interactive Oz agents embedded in Warp. Use natural language to write code, debug issues, run commands, and automate development tasks with full terminal access. * [**Third-Party CLI Agents**](/agent-platform/cli-agents/overview/) - Use Claude Code, Codex, OpenCode, and other CLI coding agents in Warp with rich input, notifications, code review, and remote session control. * [**Oz Cloud Agents**](/agent-platform/cloud-agents/overview/) - Autonomous Oz agents that run in the background in response to system events, schedules, or integrations. * [**Integrations**](/agent-platform/cloud-agents/integrations/) - Connect external system events to autonomous agent execution. Use [Slack](/agent-platform/cloud-agents/integrations/slack/), [Linear](/agent-platform/cloud-agents/integrations/linear/), [GitHub Actions](/agent-platform/cloud-agents/integrations/github-actions/), and other integrations to trigger agents in the cloud. * [**Oz Platform**](/agent-platform/cloud-agents/platform/) - The underlying infrastructure that powers Oz, including the CLI, API/SDK, orchestration layer, environments, secrets, and management/observability. *** ## Getting started [Section titled “Getting started”](#getting-started) * [**Agents in Warp**](/agent-platform/getting-started/agents-in-warp/) - Start using Oz agents interactively in Warp * [**Oz web app**](https://oz.warp.dev) - Create runs, manage schedules, browse skills, and configure integrations * [**Oz CLI**](/reference/cli/) - Run agents from the command line, in CI, or on remote machines * [**Oz API & SDK**](/reference/api-and-sdk/) - Programmatically create and monitor agent runs *** ## Learn more [Section titled “Learn more”](#learn-more) * [Warp Agents overview](/agent-platform/local-agents/overview/) - Interactive agents in Warp * [Third-Party CLI Agents](/agent-platform/cli-agents/overview/) - Claude Code, Codex, OpenCode, and more * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) - Background agents for automation at scale * [Agent Capabilities](/agent-platform/capabilities/) - Skills, planning, MCP, rules, and more * [Oz Platform](/agent-platform/cloud-agents/platform/) - CLI, API/SDK, orchestration, environments, and hosts * [Environments](/agent-platform/cloud-agents/environments/) - Configure execution context for cloud agents * [Integrations](/agent-platform/cloud-agents/integrations/) - Slack, Linear, GitHub Actions, and custom integrations * [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/) - Run agents from reusable skill definitions * [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - Monitor and manage agent activity # Capabilities overview > Core capabilities and configuration options that shape how agents behave, what context they have access to, and how they execute tasks. These capabilities are the foundational building blocks that define how agents operate. These include the context sources agents can access, the rules that guide their behavior, and the tools they can use. Understanding these capabilities helps you get the most out of agents by configuring them to match your workflows and preferences. ## Capabilities in this section [Section titled “Capabilities in this section”](#capabilities-in-this-section) * [Slash Commands](/agent-platform/capabilities/slash-commands/) - Quick actions and saved prompts accessible by typing `/` in Agent Mode. * [Skills](/agent-platform/capabilities/skills/) - Reusable, scoped instructions that teach agents how to perform specific tasks in your codebase. * [Planning](/agent-platform/capabilities/planning/) - Turn agent requests into organized, editable plans that execute step-by-step with full visibility. * [Task Lists](/agent-platform/capabilities/task-lists/) - Track complex workflows with automatic task lists that update progress in real time. * [Model Choice](/agent-platform/capabilities/model-choice/) - Pick your preferred LLM from a curated set of top models, or let Warp choose the optimal one. * [Rules](/agent-platform/capabilities/rules/) - Define global and project-level guidelines that shape agent behavior and responses. * [Full Terminal Use](/agent-platform/capabilities/full-terminal-use/) - Let the agent drive interactive terminal apps, seeing live output and running commands. * [Computer Use](/agent-platform/capabilities/computer-use/) - Let agents interact with desktop environments by taking screenshots, clicking, typing, and controlling the GUI. * [MCP](/agent-platform/capabilities/mcp/) - Connect external data sources and tools to Warp’s agents via the Model Context Protocol. * [Codebase Context](/agent-platform/capabilities/codebase-context/) - Let agents understand your codebase through semantic indexing of your Git-tracked files. * [Agent Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/) - Control what permissions and autonomy agents have to run commands and apply changes. * [Web Search](/agent-platform/capabilities/web-search/) - Allow agents to search the web for up-to-date information. ## Related [Section titled “Related”](#related) For hands-on agent interactions, see [Local Agents](/agent-platform/local-agents/overview/). # Agent Notifications > Warp surfaces notifications from coding agents, both in-app and via desktop alerts, so you know exactly when an agent needs your attention. Warp delivers notifications from any supported coding agent so you always know when an agent finishes a task, encounters an error, or needs your input. Notifications work whether you’re in a different tab or a different app. ## Notification types [Section titled “Notification types”](#notification-types) Warp categorizes agent notifications by what happened: * **Complete** - the agent finished its task successfully. You can review the output and continue working. * **Request** - the agent is blocked and needs your input. This includes command approval, permission requests, and idle prompts where the agent is waiting for you. * **Error** - the agent encountered an error that requires your attention. ## In-app notifications [Section titled “In-app notifications”](#in-app-notifications) When you’re working in Warp but not looking at the agent’s tab, Warp provides several visual signals. ### Toast notifications [Section titled “Toast notifications”](#toast-notifications) Floating toast notifications appear in the corner of the Warp window when an agent in another tab needs attention. Toasts auto-dismiss after a few seconds. Hover over a toast to pause the timer, or click it to jump directly to the agent’s session. Up to two toasts are visible at a time. If additional notifications arrive, the oldest toast is replaced. ![A Warp toast notification in the upper-right corner showing an agent task completed, with an Open conversation action and a keyboard shortcut chip](/_astro/toast-notification.BuQ9wEyc_Z2k4DB7.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Agent task completion notification. ### Notification mailbox [Section titled “Notification mailbox”](#notification-mailbox) The notification mailbox is a sidebar panel that collects all agent notifications in one place. Open it from the bell icon in the top-right corner of Warp. ![The Warp notification mailbox open in the upper-right of the window with All tabs and Unread filter tabs, a Mark all as read action, and a notification entry](/_astro/notification-mailbox.D2pVVRLz_iV8m6.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Agent notification mailbox. The mailbox includes: * **Filter tabs** - switch between **All tabs**, **Unread**, and **Errors** to find what needs attention. If there are no unreads or errors, those filters don’t appear. * **Mark all as read** - clear all unread indicators at once * **Click to navigate** - click any notification to jump directly to that agent’s tab **Keyboard shortcuts:** * `↑` / `↓` - select previous / next notification * `Enter` - open the selected notification’s session * `Shift-Tab` - cycle through filter tabs * `Esc` - close the mailbox ### Tab status indicators [Section titled “Tab status indicators”](#tab-status-indicators) Each tab displays an icon reflecting its agent’s current state — working, blocked, completed, or errored. Tabs with unread notifications show an attention badge so you can spot which sessions need action, even with many tabs open. Notifications are automatically marked as read when you navigate to the agent’s tab. ## Desktop notifications [Section titled “Desktop notifications”](#desktop-notifications) When Warp is in the background or minimized, agent notifications are delivered as native system-level desktop alerts. This ensures you’re aware of agent activity even while working in other apps. Note Desktop notifications require system permissions. If you’re not receiving them, check your OS notification settings for Warp. See [Desktop Notifications](/terminal/more-features/notifications/) for setup and troubleshooting. ## Supported agents [Section titled “Supported agents”](#supported-agents) Agent notifications currently work with: * **Oz agent** - supported out of the box. No setup required. * **Claude Code** - full support via notification plugin. * **Codex** - full support via native Codex configuration. * **OpenCode** - full support via notification plugin. ## Setting up notifications [Section titled “Setting up notifications”](#setting-up-notifications) For the **Oz agent**, notifications work out of the box — no setup needed. For **third-party CLI agents**, each agent requires a one-time setup. The process varies by agent: * **Claude Code** - one-click auto-install via a chip in Warp, or manual plugin commands. See [Claude Code setup](/agent-platform/cli-agents/claude-code/#setting-up-notifications). * **Codex** - add `notification_condition = "always"` under `[tui]` in `~/.codex/config.toml`, then restart Codex. See [Codex setup](/agent-platform/cli-agents/codex/#setting-up-notifications). * **OpenCode** - add `"@warp-dot-dev/opencode-warp"` to the `plugin` array in your OpenCode config. See [OpenCode setup](/agent-platform/cli-agents/opencode/#setting-up-notifications). ![The Enable Claude Code notifications chip in the agent utility bar with a tooltip reading Install the Warp plugin to enable rich agent notifications within Warp](/_astro/enable-cli-agent-notifications.WjIL6yWs_OXWh5.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Notification plugin install chip. If auto-install doesn’t work or you’re running an agent over SSH, Warp displays an installation-instructions chip in the terminal with setup steps you can follow directly. ## Related pages [Section titled “Related pages”](#related-pages) * [Desktop Notifications](/terminal/more-features/notifications/) - configure system-level notification permissions and troubleshoot delivery * [Managing Agents](/agent-platform/cloud-agents/managing-cloud-agents/) - monitor all agent conversations, filter by status, and inspect sessions * [Third-Party CLI Agents](/agent-platform/cli-agents/overview/) - overview of supported CLI agents and Warp features * [Claude Code](/agent-platform/cli-agents/claude-code/) - setup and notification plugin installation * [Codex](/agent-platform/cli-agents/codex/) - setup and notification configuration * [OpenCode](/agent-platform/cli-agents/opencode/) - setup and notification plugin installation # Profiles & Permissions > Agent Profiles let you customize how your Agent behaves, from its models and autonomy to the tools and permissions it can use. ## Agent Profiles [Section titled “Agent Profiles”](#agent-profiles) Agent Profiles let you configure how your Agent behaves in different situations. Each profile defines the Agent’s autonomy, base models, and tool access. You can create multiple profiles and edit them directly in **Settings** > **Agents** > **Profiles**. * **Default profile**: Every user starts with a default profile, you can edit it at any time, and new profiles will copy its settings as a starting point. * **Other profiles**: Set up different profiles for different workflows (e.g., “Safe & cautious”, “YOLO mode”, etc.). Manage them in the Profiles settings menu. ![Agent Profiles in Settings: define how your Agent operates.](/_astro/agent-profiles.BST_ybx4_11kXjS.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Agent Profile settings. **In each Agent Profile, you can configure:** * The name of the profile * **Base model**: The core engine for your Agent. It handles most interactions and invokes other models when needed (e.g. for code generation). This model is also used for [Planning](/agent-platform/capabilities/planning/) by default, though you can configure a separate planning model. * Agent autonomy and permissions ![Agent Profiles in Settings: editing a Profile.](/_astro/agent-profiles-settings.DstjVgNw_Z2dffoL.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Editing an Agent Profile. ## Agent Permissions [Section titled “Agent Permissions”](#agent-permissions) Agent Permissions let you define how your Agent in a specific Profile operates — control its autonomy, choose what tools or MCP servers it can access, and set when it should act independently or ask for approval. Caution **Still getting approval prompts?** If the Agent keeps asking for permission to run certain commands (like `curl`, `rm`, or `wget`) even though you’ve set permissions to “Always allow,” check your **Command denylist** in **Settings** > **Agents** > **Profiles**. The denylist always takes precedence over other permission settings. Remove commands from the denylist to allow them to auto-execute, or use [Run until completion](#run-until-completion) to bypass the denylist for the current task. You can control how much autonomy the Agent has when performing different types of actions under **Settings** > **Agents** > **Profiles** > **Permissions** . Agent permission types: * Apply code diffs * Read files * Create plans * Execute commands * Interact with running commands (via [Full Terminal Use](/agent-platform/capabilities/full-terminal-use/)) ![Fine-tuning agent control: This permissions panel lets users customize how much autonomy the Agent has when applying code diffs, reading files, creating plans, and executing commands.](/_astro/agent-permissions-with-full-terminal-use.BWHFlLjQ_Z2rNrUm.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) **Each permission has different levels of autonomy:** | Autonomy level | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Agent Decides | Agent will act autonomously when it’s confident, but prompt for approval when uncertain. This option balances speed with control, allowing the Agent to go ahead with common workflows while keeping you in the loop for more complex or risky steps. | | Always ask | Agent will request explicit user approval before taking any action. Choose this for sensitive actions. | | Always allow | Agent will perform the action without ever requesting explicit confirmation. Use this for tasks you fully trust the Agent to handle on its own. | | Never | Agent will not ever take the action (i.e. Create plans). | Note For **Apply code diffs**, `Agent decides` currently behaves the same as `Always ask` — the Agent always prompts you to review diffs before applying them. Only `Always allow` skips the review prompt. When all Agent permissions are set to **Always allow**, the Agent gains full autonomy (“YOLO mode”); however, any denylist rules will still override these settings. ### Command allowlist [Section titled “Command allowlist”](#command-allowlist) The Agent lets you define an allowlist of commands that run automatically without confirmation. It’s empty by default, but users often add read-only commands such as: * `which .*` - Find executable locations * `ls(\s.*)?` - List directory contents * `grep(\s.*)?` - Search file contents * `find .*` - Search for files * `echo(\s.*)?` - Print text output You can add your own regular expressions to this list in **Settings** > **Agents** > **Profiles** > **Command allowlist**. Commands in the allowlist will always auto-execute, even if they are not read-only operations. ![Command allowlist and denylists as part of an Agent Profile.](/_astro/agent-profiles-allow-and-denylists.BAGRosYO_1mr3Wq.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Command allowlist and denylists as part of an Agent Profile. ### Command denylist [Section titled “Command denylist”](#command-denylist) For safety, the Agent always prompts for confirmation before executing potentially risky commands. The default denylist includes several examples, such as: * `wget(\s.*)?` - Network downloads * `curl(\s.*)?` - Network requests * `rm(\s.*)?` - File deletion * `eval(\s.*)?` - Shell code execution The denylist takes precedence over both the allowlist and `Agent decides`. If a command matches the denylist, user permission will always be required, regardless of other settings. You can add your own regular expressions to this list in **Settings** > **Agents** > **Profiles** > **Command denylist**. ### MCP permissions [Section titled “MCP permissions”](#mcp-permissions) MCP servers let you extend the Agent with custom tools and data sources using standardized, plugin-like modules. In this settings menu, you can configure which MCP servers the Agent is allowed to call: * Use the MCP allowlist to give the Agent permission to call specific servers without asking. * Use the MCP denylist to require approval before calling certain servers, even if they’re also in the allowlist. * Or set the Agent to “decide” — it will act autonomously when confident, and ask for confirmation when uncertain. ![Customize how the Agent interacts with MCP servers by choosing between “Agent decides,” allowlist, or denylist settings.](/_astro/MCP_servers_agent_permissions.2tuGO4cq_e7wpW.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) MCP server interaction settings in an Agent Profile. Note To learn how to build and configure your own MCP server, check out the [MCP feature docs](/agent-platform/capabilities/mcp/). ## Run until completion [Section titled “Run until completion”](#run-until-completion) During an Agent interaction, you can give the Agent full autonomy for the current task. When auto-approve is on, every suggested command runs immediately until the task finishes, or you stop it with `Ctrl + C`. * macOS Auto-approve all Agent actions with: `CMD + SHIFT + I` * Windows Auto-approve all Agent actions with: `CTRL + SHIFT + I` * Linux Auto-approve all Agent actions with: `CTRL + SHIFT + I` ![A button overlay in the lower-right corner lets you enable auto-approve or end the Agent interaction.](/_astro/run-until-completion.BfbrneTP_2rBbQU.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Auto-approve and take-over controls. Note *Run until completion* ignores the denylist entirely. It’s the purest form of “YOLO” mode and essentially a fully “autonomous mode” where the Agent proceeds without asking for confirmation. *** ## Next steps [Section titled “Next steps”](#next-steps) Once you’ve configured how your agent operates, try giving it a larger task to plan and execute. * **[Planning](/agent-platform/capabilities/planning/)** - Break down complex tasks into structured, executable plans that the agent runs step by step. * **[Code diffs](/agent-platform/local-agents/code-diffs/)** - Review, refine, and apply code changes the agent generates. * **[Interactive Code Review](/agent-platform/local-agents/interactive-code-review/)** - Leave inline comments on agent-generated diffs and have the agent address your feedback. # Codebase Context > Warp indexes your Git-tracked codebase to help Agents understand your code and generate accurate, context-aware responses. No code is stored on Warp servers. Codebase Context helps Agents understand your project by indexing your local codebase. This allows Agents to generate more accurate completions, suggest context-aware edits, and answer questions using real knowledge of your code. ## Get started [Section titled “Get started”](#get-started) Index a project and see the difference in agent responses in a few minutes. Note **Don’t have a project to try?** Clone a popular open-source repo to test out codebase indexing: ```bash git clone https://github.com/vercel/next.js.git && cd next.js ``` 1. **Open a project folder in Warp.** Navigate to a Git repository using `cd` or open a folder from the file tree. Warp automatically detects the Git repo and begins indexing. 2. **Verify indexing status.** In Warp, go to **Settings** > **Code** > **Indexing and projects** and check the status under “Initialized / indexed folders.” Once the status shows **Synced**, your codebase is ready. 3. **Ask the Agent a question about your code.** Start an Agent conversation (`⌘+Enter` on macOS, `Ctrl+Shift+Enter` on Windows/Linux) and try a prompt like: * “Explain the architecture of this project” * “What are the main entry points?” * “Walk me through the most important modules” 4. **See the difference.** The Agent grounds its responses in actual files, functions, and line numbers from your codebase, producing more accurate and context-aware answers. *** ## Indexing your codebase [Section titled “Indexing your codebase”](#indexing-your-codebase) When you open a directory in Warp, we check if it is part of a Git repository. If it is, Warp begins indexing the source code to provide rich context for Agents. Warp also detects [Git worktree](/code/git-worktrees/) checkouts — each worktree is indexed as its own repository, so Agents always have accurate context for the branch you’re working on. Note Code indexed with Codebase Context is never stored on our servers. Codebase Context works with both local agent sessions and [cloud agent runs](/agent-platform/cloud-agents/overview/). Without Codebase Context enabled, agents will still be able use terminal commands (i.e. `grep`, `sed`) to navigate your code. Caution **Codebase Context (semantic indexing and search) is not yet available in SSH or WSL sessions.** Feature requests: * SSH: [GitHub #6831](https://github.com/warpdotdev/Warp/issues/6831) * WSL: [GitHub #6744](https://github.com/warpdotdev/Warp/issues/6744) ![Codebase indexing settings in Warp. Easily track sync status and manage which folders are indexed for AI-powered context and suggestions.](/_astro/codebase-context-main.CL_YR1bf_Z239czO.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Codebase indexing settings. **Codebase indexing intervals and triggers:** * Initially when you have Codebase Context enabled. * Warp automatically triggers a codebase index periodically. * Whenever a new Agent conversation begins. * When you click on the sync 🔄 button in **Settings** > **Code** > **Indexing and projects**. **This embeddings index helps Agents:** * Understand your project structure and reference relevant code * Generate completions that match your style and patterns * Suggest edits in the correct locations based on real context For large projects, indexing may take a few minutes. Agents will not use Codebase Context until indexing is complete, but **agentic coding features remain fully available in the meantime**. Note You can view and manage your indexed codebases in **Settings** > **Code** > **Indexing and projects** under “Initialized / indexed folders”. You can also choose whether to automatically index new folders as you navigate them. ![YouTube video](https://i.ytimg.com/vi/11rz9OYQ8Hg/sddefault.jpg) ### **Codebase indexing states** [Section titled “Codebase indexing states”](#codebase-indexing-states) When viewing indexed codebases in Warp under **Settings** > **Code** > **Indexing and projects**, you may see different status indicators: * **Synced** — Indexing is complete and the codebase is ready to be used as context. * **Discovering files** – Warp is currently scanning and indexing files in the codebase. * **Failed** – Indexing failed. Common reasons include unreadable `.git` directories or corrupted repositories. Try re-cloning the repo and syncing again. * **Codebase too large** – The number of files in the codebase exceeds your current plan’s limit. You can either reduce the number of files being indexed using `.warpindexingignore`, or [contact sales](https://warp.dev/contact-sales) for support with larger codebases. ![View and manage the indexing status of your codebases in Warp. Easily see which projects are synced, in progress, or require attention.](/_astro/codebase-context-statuses.Bvtcz4KP_Z15tjky.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Codebase indexing status overview. ### When does codebase syncing happen? [Section titled “When does codebase syncing happen?”](#when-does-codebase-syncing-happen) Warp automatically triggers a codebase sync initially and periodically, when you click on the sync 🔄 button in **Settings** > **Code** > **Indexing and projects**, or when you start a new Agent conversation. However, if many files have changed or the network is slow, the sync may not complete before the Agent tries to access context. Note In large projects (e.g. after a branch switch), there may be a short delay where the Agent references stale or outdated files. ### File and codebase limits [Section titled “File and codebase limits”](#file-and-codebase-limits) The number of codebases you can index and the maximum number of files per codebase vary by plan. All plans support indexing **at least 5,000 files per codebase**, with higher tiers including support for more files and additional codebases. For full details, visit our [pricing page](https://www.warp.dev/pricing). ### Ignore files [Section titled “Ignore files”](#ignore-files) For large codebases, Warp supports several ignore files to give you control over what gets indexed. This allows each developer to focus context on the parts of the codebase most relevant to their work. Warp respects the following ignore files: * `.gitignore` * `.warpindexingignore` * `.cursorignore` * `.cursorindexingignore` * `.codeiumignore` Use these files to skip indexing of folders, generated files, or any content you don’t want agents to reference. This can improve performance and result quality. Note Files excluded by ignore rules **do not** count toward your codebase’s file limit. ## Codebase Context in cloud agent runs [Section titled “Codebase Context in cloud agent runs”](#codebase-context-in-cloud-agent-runs) Codebase Context is available in all Oz cloud agent runs — including runs triggered from the CLI, API/SDK, integrations (Slack, Linear, GitHub Actions), and schedules — as long as Codebase Context is enabled for your account. **No additional configuration is needed.** If Codebase Context is enabled, cloud agents use it automatically. ## Multi-repo context [Section titled “Multi-repo context”](#multi-repo-context) Warp supports referencing context across multiple indexed repositories. Note that you don’t need to be inside a specific repo for agents to use its context. **This is especially useful when:** * Implementing a feature across multiple repos, such as full-stack work across client and server * Using one repo as a reference while building in another, for example: “copy the implementation from repo A into my repo B” Agents will only reference other repositories if they are already indexed. During cross-repo tasks, Warp’s Agents have access to the file paths of all indexed repos. It is more likely to use cross-repo context when you mention the exact name of the repo in your prompt. ## Demo: Explain my codebase with Warp [Section titled “Demo: Explain my codebase with Warp”](#demo-explain-my-codebase-with-warp) Here’s an example from [Warp Guides](/guides/), where Zach demonstrates how Warp uses Codebase Context to search for and use the relevant files as context: ![YouTube video](https://i.ytimg.com/vi/11rz9OYQ8Hg/sddefault.jpg) *** ## Next steps [Section titled “Next steps”](#next-steps) With your codebase indexed, you can browse your project directly in Warp and start letting agents take action on your code. * **[File Tree](/code/code-editor/file-tree/)** - Browse your project structure in Warp’s sidebar and open files directly. * **[Code editor](/code/code-editor/)** - Edit files with syntax highlighting, LSP support, and find-and-replace without leaving Warp. * **[Agent profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/)** - Configure how much autonomy the agent has when working with your code. # Computer use for agents > Let agents interact with desktop GUIs in sandboxed cloud environments for automated UI testing and validation. Computer Use is an experimental feature that enables Warp’s agents to interact with desktop environments. The agent can see what’s displayed on screen, click and drag, type text, use keyboard shortcuts, and perform other GUI interactions—all within a secure, isolated sandbox. A key use case is **testing UI changes** with a self-contained feedback loop, where the agent can verify that your code changes produce the expected visual and behavioral results without requiring manual testing. ## Overview [Section titled “Overview”](#overview) With Computer Use, agents can: * **Take screenshots** - Capture and analyze the current display * **Interact with applications** - Click buttons, fill forms, navigate interfaces * **Type and control keyboard** - Enter text and use keyboard shortcuts * **Automate testing workflows** - Test UI changes end-to-end without manual intervention * **Work with browser-based interfaces** - Test web apps and navigate the web Computer Use is only available in Warp’s sandboxed cloud environments, not in local interactive terminal sessions. *** ## Enabling Computer Use [Section titled “Enabling Computer Use”](#enabling-computer-use) Computer Use is **opt-in** and disabled by default. You can enable it through several entry points: ### Warp app settings [Section titled “Warp app settings”](#warp-app-settings) To enable Computer Use for [Cloud Agents](/agent-platform/cloud-agents/overview/), navigate to **Settings** > **Agents** > **Warp Agent** > **Experimental** > **Computer use in Cloud Agents** and toggle to enable. ### CLI [Section titled “CLI”](#cli) When running agents in the cloud via the [CLI](/reference/cli/), use flags to control Computer Use per run: ```bash oz agent run-cloud --computer-use --prompt "" oz agent run-cloud --no-computer-use --prompt "" ``` ### API [Section titled “API”](#api) When calling the Warp API to create agent runs, include the `computer_use_enabled` field in your request: ```json { "prompt": "Build a button component that matches this design, then test it in the browser", "computer_use_enabled": true, "environment_id": "optional-environment-id" } ``` For full API documentation, see the [Oz API & SDK](/reference/api-and-sdk/) reference. ### Web App [Section titled “Web App”](#web-app) In the Warp web app, you can enable or disable Computer Use for: * **New agent runs** - Configure Computer Use when starting a new agent run from the web app * **Scheduled agent runs** - Enable Computer Use for scheduled agents managed from the web app * **Integrations** - Configure Computer Use for Slack, Linear, and other integration-triggered agents *** ## How Computer Use works [Section titled “How Computer Use works”](#how-computer-use-works) ### Setup and requirements [Section titled “Setup and requirements”](#setup-and-requirements) Computer Use runs in a containerized sandbox, allowing headless cloud environments to render and interact with graphical applications. The sandbox is fully isolated—it does not have access to your local machine, credentials, or sensitive data outside the sandbox environment. Your cloud environment must include any applications you want the agent to control. For example, to test a web app in a browser, install Chrome or Firefox in your [environment configuration](/agent-platform/cloud-agents/environments/). ### Model selection [Section titled “Model selection”](#model-selection) Computer Use supports multiple Anthropic Claude models, including Claude 4.5 Sonnet, Claude 4.5 Opus, Claude 4.5 Haiku, Claude 4.6 Sonnet, and Claude 4.6 Opus. Warp uses an auto model selector to choose the best-suited model for each Computer Use task. *** ## Security considerations [Section titled “Security considerations”](#security-considerations) Computer Use is an experimental feature with unique security considerations. These risks are heightened when interacting with the internet. To minimize risks when using Computer Use: 1. **Avoid sensitive data** - Do not pass API keys, authentication tokens, or personal information to agents using Computer Use 2. **Limit internet access** - If your environment has internet access, consider restricting to an allowlist of known-safe domains 3. **Require human confirmation** - For tasks with real-world consequences (e.g., financial transactions, accepting legal terms), ask a human to confirm before the agent proceeds 4. **Review agent actions** - Regularly review what agents are doing on your behalf, especially when testing new workflows *** ## Example workflows [Section titled “Example workflows”](#example-workflows) ### Testing UI changes [Section titled “Testing UI changes”](#testing-ui-changes) Verify that code changes produce the expected visual results and behavior: * **Build from mockups** - Receive a Figma design or mockup image, build the UI, and test it matches * **Visual regression testing** - After code changes, verify UI renders correctly * **Form and interaction testing** - Test form submissions, validation, error handling * **Responsive design validation** - Test layout on different screen sizes **Example: Testing a React component** 1. You ask the agent: “Build a React button component that matches this design, then test it” 2. Agent takes a screenshot to see the current state 3. Agent opens your dev server in a browser 4. Agent navigates to the component, verifies it renders correctly 5. Agent tests interactions (hover, click) and reports back **Example: Testing a web form** 1. You provide a form design and ask the agent to build and test it 2. Agent renders your form in the browser 3. Agent fills fields with valid and invalid data 4. Agent verifies validation messages and submission behavior 5. Agent reports which fields worked correctly and which need adjustment **Example: Verifying UI responsiveness** 1. You ask the agent to test your app on different screen sizes 2. Agent resizes the browser window to mobile, tablet, and desktop widths 3. Agent takes screenshots at each size and verifies layout is correct 4. Agent reports any responsive design issues ### Browsing and web interaction [Section titled “Browsing and web interaction”](#browsing-and-web-interaction) Computer Use can also help with general web tasks: * Browse websites and interact with web interfaces * Fill out and submit web forms * Navigate multi-step workflows in web applications *** ## Related capabilities [Section titled “Related capabilities”](#related-capabilities) * [Images as Context](/agent-platform/local-agents/agent-context/images-as-context/) - Pass design mockups and screenshots as context * [Full Terminal Use](/agent-platform/capabilities/full-terminal-use/) - Let agents drive interactive terminal apps, see live output, and run commands # Full Terminal Use > Full Terminal Use means Warp's agents can interact with active terminal apps to monitor live output and run commands. Full Terminal Use lets Warp’s agent operate directly inside interactive terminal applications, such as database shells, debuggers, text editors, long-running servers, and more. The agent can see the live terminal buffer (terminal state), write to the PTY to run commands, respond to prompts, and continue working inside the running process while you stay in control. ![YouTube video](https://i.ytimg.com/vi/gBdehHrtb94/sddefault.jpg) ## Overview [Section titled “Overview”](#overview) With Full Terminal Use, Warp’s agent can attach to interactive tools like `psql`, `vim`, `python`, `gdb`, `top`, or your dev server, read the terminal output as it changes, and interact with the application as if you were typing. You can either ask the agent to start an interactive program, or you can start it yourself and then tag the agent in once the tool is already running. In both cases, the agent sees the same terminal buffer (and PTY session) you do and can act on it. ## How Full Terminal Use works [Section titled “How Full Terminal Use works”](#how-full-terminal-use-works) #### Start an interactive command [Section titled “Start an interactive command”](#start-an-interactive-command) You can either ask the agent to run an interactive command, or start one manually and then tag the agent in: * **Ask the agent to start an interactive tool** * Example: * “Open a Postgres shell and help me inspect the orders table.” * “Start the dev server and debug this 500 error.” * **Or start the command yourself, then tag the agent in** * Example: * If you’ve already launched an interactive tool (for example `psql` or `npm run dev`), you can bring the agent into the running session using the “Use Agent” button in the terminal footer or via `CMD + I` . ![Option to tag the agent into a running command.](/_astro/full-terminal-use-tag-hint.DM6M9wdZ_Z2r9k8i.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Option to tag the agent into a running command. * Once the agent is tagged in, you can follow up with natural-language requests such as: “Watch this process and help debug the error on the /session endpoint.” * Warp then attaches the agent to the active PTY so it can see the current terminal buffer and propose actions inside the session. [Tagging in the agent.](https://www.loom.com/embed/bcedc521071a4b6a9bbcf74b5156f903) ![Running a build command.](/_astro/full-terminal-use-build.-vzlHVBj_Z1gqnPm.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Running a build command. ![Tagging in the Agent to monitor the dev server.](/_astro/full-terminal-use-dev-monitor.DwZYeczz_1R0Kxt.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Tagging in the Agent to monitor the dev server. Warp attaches the agent to the running command so it can see and control the terminal buffer. #### Agents propose actions inside the session [Section titled “Agents propose actions inside the session”](#agents-propose-actions-inside-the-session) Once attached, you can continue using natural language and the agent turns your requests into concrete terminal actions. For example, in a Postgres shell: * You: “Show me all the tables and describe the orders table.” * Agent: proposes running commands like: `\dt` —> `\d+ orders` In the UI, you’ll see a request to: * Run a specific command * Optionally enable auto-approval for similar commands in this session #### Switching control between user and the agent [Section titled “Switching control between user and the agent”](#switching-control-between-user-and-the-agent) You can swap control at any time. **Take over** * Use the Takeover control to stop the agent from typing or performing any actions. * The shell stays open, and you can type directly into the same session. ![Option to take over from agent in the footer.](/_astro/full-terminal-use-takeover.CXmq55EP_ZbcbAV.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Option to take over from agent in the footer. **Hand back control** * When you’re ready for the agent to continue, click the control again. * The agent resumes where you left off, with full access to the current terminal state. ![Option to hand-off to the agent in the conversation footer.](/_astro/full-terminal-use-handoff.Dg0srGBm_2s0hhm.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Option to hand-off to the agent in the conversation footer. This makes it easy to: * Let the agent do mechanical work (paging output, trying variants of a command) * Step in for delicate or security-sensitive actions * Then let the agent continue once the critical step is done #### Long-running commands in terminal vs agent view [Section titled “Long-running commands in terminal vs agent view”](#long-running-commands-in-terminal-vs-agent-view) The behavior differs based on where you start the long-running command: * From terminal view 1. Run an interactive command (e.g., `python`, `psql`) 2. Press `⌘↩` (macOS) or `Ctrl+Shift+Enter` (Windows/Linux), or use `⌘I` (macOS) / `Ctrl+I` (Windows/Linux), to tag in the agent 3. The input switches to Agent Mode with full controls 4. When you exit, an agent conversation block appears in your terminal blocklist 5. Click the block to reopen the full conversation with your LRC interaction context * From agent view 1. The agent runs an interactive command as part of your conversation 2. Use `⌘↩` (macOS) or `Ctrl+Shift+Enter` (Windows/Linux) to tag in if the agent isn’t already interacting 3. The UI stays the same since you’re already in agent view 4. When you exit, the interaction remains part of your conversation. No separate block is created in the terminal blocklist 5. Commands run in agent view are automatically included as context Note You can also use `CMD + I` (macOS) or `CTRL + I` (Windows/Linux) to toggle agent control in either view. #### Showing and hiding agent responses [Section titled “Showing and hiding agent responses”](#showing-and-hiding-agent-responses) Warp gives you control over how much agent output appears in Full Terminal Use. **Toggle visibility** Use the `Hide responses` or `Show responses` button or `CMD + G` in the interactive command footer to switch between showing all agent output or hiding it from the terminal view. Note that this only affects the agent’s messages and proposals; your terminal state and command output remain unchanged. **Behavior when hidden** * When agent responses are hidden, your own agent requests automatically dismiss after **4 seconds** to keep the terminal clear. * You can also manually dismiss any user query at any time by hovering over it and clicking the X. *** ### Configuring agent permissions and autonomy [Section titled “Configuring agent permissions and autonomy”](#configuring-agent-permissions-and-autonomy) You control how much autonomy the agent has when interacting with the terminal. #### Session-level approvals [Section titled “Session-level approvals”](#session-level-approvals) Each time the agent wants to take an action inside an interactive shell, you’ll see the agent’s reasoning, a brief explanation, and the proposed command. From there you can: * Allow the command once (for example by approving it or pressing `ENTER`). * Turn on auto-approval for similar commands in this session (for example with `CMD + SHIFT + I`). * Refine the request with `CTRL + C`, which clears the proposed action and lets you follow up with a different query. * Take over manually with `CMD + I`, which stops the agent from issuing any further PTY writes until you hand control back. ![Allow, Refine, or Take over an agent response.](/_astro/allow-refine-takeover.DQirdZqB_Z2ci4In.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Allow, Refine, or Take over an agent response. ![Ability to accept or auto-approve future interactions.](/_astro/full-terminal-use-options-2.DF_SdCro_2gKxp3.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) This lets you tighten or loosen control for the current task: * For exploratory work, use **Always allow** to reduce friction. * For production systems or sensitive operations, use **Allow once** and review each step. #### Global permission settings [Section titled “Global permission settings”](#global-permission-settings) You can configure global defaults from your [Agent Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/) settings: * **Ask on first write**: The first write to a shell process requires approval. After that, all subsequent writes for that specific process/command will be approved. * **Always ask**: Every write to the shell process from the agent requires your explicit approval. * **Always allow**: The agent can write to the shell process without prompting you each time. These settings apply to every session that uses Full Terminal Use. You can still override them on a per-session basis when prompted. For example, you can enable **auto-approval** for similar commands in the current session using the fast-forward control, or switch to a **different AI profile** with its own permission settings for that conversation. Note **Note**: All [Secret Redaction](/support-and-community/privacy-and-security/secret-redaction/) features still apply during Full Terminal Use, so sensitive values in your environment or output remain protected. ### Credits usage [Section titled “Credits usage”](#credits-usage) All AI interactions from Full Terminal Use consume [credits](/support-and-community/plans-and-billing/credits/), including understanding your natural language requests. Credits are consumed in a similar way as other Oz actions that use the same model and a similar context size. **Interactive sessions can consume more credits if:** * The agent runs many commands in an interactive shell on your behalf. * There is a significant amount of terminal output to read and summarize. **To manage credit usage:** * Use tighter scopes: * “Describe just the orders table.” instead of “Explain the entire database.” * Pause autonomy for high-volume tasks with copious terminal output: * Take over manual control when running large batches or long logs. * Use stricter permissions: * Set global permissions to “Ask on first write” or “Always ask”, then approve only what you need. Note To learn more about what goes into a credit and how to get more value from AI usage in Warp, see: [*Getting the most out of credits in Warp*](https://www.warp.dev/blog/warp-ai-requests). ## Example workflows [Section titled “Example workflows”](#example-workflows) Here’s a demo from one of our engineers, Maggie, that walks through a couple of Full Terminal Use examples. Below are some common interactive tools where Full Terminal Use is particularly useful: database shells (Postgres, MySQL, SQLite), debuggers such as gdb, language-specific REPLs like python or node, text editors and file explorers, and long-running dev servers or monitoring tools such as top and htop. | Tool | Example tasks | Agents can… | | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Database shells (REPLs)** e.g. `psql`, `mysql`, `sqlite`, etc. | * “List all tables and describe the users and orders tables.” * “Create a new table to store archived user sessions.” * “Show me all rows in orders from the last 30 days, grouped by status.” * “Generate and run a query that finds the top 10 customers by revenue.” | - Navigate `\d`, `\dt`, `DESCRIBE`, etc. - Write and execute SQL queries - Summarize results in plain language | | **Text editors** e.g. `vim`, `nano`, etc. | * “Open this file in vim and add a Markdown header and a boilerplate section.” * “Insert a docstring above this function explaining what it does.” * “Generate a CSS utility class block and insert it in this file.” | - Navigate within the editor using keystrokes - Insert, edit, and delete text - Save and quit when done | | **Python REPLs** e.g. `python`, `ipython` | * “Start a Python REPL and define a function that calculates a moving average.” * “Write a unit test for this function and run it.” * “Plot x from 0 to 10 and y = sin(x).” | - Import modules - Define functions and classes - Run tests and small scripts - Print or summarize results back to you | | **Debuggers** e.g. `gdb`, `lldb`, language-specific debuggers | * “Start gdb for this binary and set a breakpoint on `handle_request`.” * “Run until the breakpoint, then show the stack and local variables.” * “Inspect this pointer and tell me if it looks invalid.” | - Issue debugger commands (break, run, next, continue, bt, etc.) - Walk through execution step by step - Summarize relevant state so you don’t have to remember every command | | **Long-running servers and services** e.g. `npm run dev`, `uvicorn`, Rails servers, etc | * “Run the dev server and debug the internal server error on /session.” * “Send a sample request to this endpoint and explain the failure.” * “Kill the server once you identify the error and propose a code diff.” | - Watch server logs in real time - Notice new errors as they appear - Stop the server when appropriate - Propose code changes (for example, via a diff) based on what it observes | | **Version control workflows** e.g. `git rebase -i`, complex git commands | * “Interactively rebase master onto `feature-branch` to squash these commits into one.” * “Resolve these merge conflicts and ensure tests pass.” | - Navigate interactive rebase prompts - Edit commit messages - Apply conflict resolutions you approve | | **Cloud provider CLIs** e.g. `gcloud`, `aws`, `az`, etc. | * “Use gcloud to create a new Kubernetes cluster with these settings.” * “Provision a new RDS instance for staging and show me the connection details.” | - Walk through multi-step CLI workflows - Handle prompts and confirmations - Summarize the resulting resources | # Model Context Protocol (MCP) > Configure MCP servers in the Warp desktop app to extend local agents with custom tools and data sources through a standardized interface. MCP servers extend Warp’s [local agents](/agent-platform/local-agents/interacting-with-agents/) in a modular, flexible way by exposing custom tools or data sources through a standardized interface — essentially acting as plugins for Warp. Warp supports a variety of connection protocols, including Streamable HTTPS and SSE, along with custom headers and environment variables. MCP is an open source protocol. Check out the official [MCP documentation](https://modelcontextprotocol.io/introduction) for more detailed information on how this protocol is engineered. Note This page covers MCP servers for local agents in the Warp desktop app. If you’re using cloud agents, see [MCP Servers for cloud agents](/agent-platform/cloud-agents/mcp/). ### How to access MCP Server settings [Section titled “How to access MCP Server settings”](#how-to-access-mcp-server-settings) You can navigate to the MCP servers page in any of the following ways: * From the [Settings Page](warp://settings/mcp): **Settings** > **Agents** > **MCP servers** * From [Warp Drive](/knowledge-and-collaboration/warp-drive/): under **Personal** > **MCP Servers** * From the [Command Palette](/terminal/command-palette/): search for `Open MCP Servers` * From the Warp app: **Settings** > **Agents** > **Warp Agent** > **Manage MCP servers** This will show a list of all configured MCP servers, including which are currently running. If you close Warp with an MCP server running, it will run again on next start of Warp. MCP servers that are stopped will remain so on next launch of Warp. ![MCP servers page](/_astro/mcp-servers-list.C9p6MT-__ZcHsrA.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) MCP servers page. ### Adding an MCP Server [Section titled “Adding an MCP Server”](#adding-an-mcp-server) To add a new MCP server, you can click the **+ Add** button. Configurations from most MCP Clients can be directly copied and pasted. MCP server types you can add: * CLI Server (Command) Provide a startup command. Warp will launch this command when starting up and shut it down on exit. ![Adding a CLI MCP Server (Command)](/_astro/mcp-servers-add-cli.Abb3ecAH_Z19CjXg.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Adding a CLI MCP Server (Command). Note Always set `working_directory` explicitly when your MCP server command or args include relative paths. This ensures consistent and predictable behavior across machines and sessions. **CLI Server (Command) MCP Configuration Properties** | Property | Type | Required | Description | | ------------------- | --------- | -------- | ----------------------------------------------------------------------------------- | | `command` | string | Yes | The executable to launch (e.g., `npx`). | | `args` | string\[] | Yes | Array of command-line arguments passed to `command` (e.g., module name, paths). | | `env` | object | No | Key-value object of environment variables (e.g., API Tokens). | | `working_directory` | string | No | Working directory path where the command is run, used for resolving relative paths. | * Streamable HTTP or SSE Server (URL) Provide a URL where Warp can reach an already-running MCP server that supports Server-Sent Events. ![Adding an SSE MCP Server (URL)](/_astro/mcp-servers-add-sse.CZz5tOsp_Z2ga1BC.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Adding an SSE MCP Server (URL). **Streamable HTTP or SSE Server (URL) MCP Configuration Properties** | Property | Type | Required | Description | | --------- | ------ | -------- | ----------------------------------------------------------------- | | `url` | string | Yes | The HTTP endpoint URL to connect to via Server-Sent Events (SSE). | | `headers` | object | No | Key-value object of header variables (e.g., Authorization). | ### Adding multiple MCP servers [Section titled “Adding multiple MCP servers”](#adding-multiple-mcp-servers) Warp supports configuring **multiple MCP servers** using a JSON snippet. Each entry under `mcpServers` is keyed by a unique name (`filesystem`, `github`, `notes`, etc). All servers defined in the example are added automatically — no manual setup required. To add a multiple MCP servers, you can click the **+ Add** button then paste in a JSON snippet like the example below: ```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"] }, "notes": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-notes", "--notes-dir", "/Users/you/Documents/notes"] }, "externalDocs": { "url": "http://localhost:4000/mcp/stream", "headers": { "my-header": "my-header-value" } } } } ``` ### File-based MCP servers [Section titled “File-based MCP servers”](#file-based-mcp-servers) Compared to manually adding a server in the Warp settings, file-based servers are defined in config files that Warp detects and can spawn automatically. They offer a few additional benefits: * **Configurable directly with an agent** - Use the [bundled skill](#using-agent-add-mcp) `/agent-add-mcp` so Warp’s agent can add or update an MCP server without leaving the conversation. * **Inherited across providers and repos** - Warp reads `.warp/.mcp.json` files and also picks up config from third-party agent providers (Claude Code, Codex, and others). The same server definition follows you across tools and repos. #### Supported providers [Section titled “Supported providers”](#supported-providers) Warp reads MCP server definitions from the following providers: | Provider | Global config | Project-scoped config | Auto-spawn | | ------------ | ---------------------- | ------------------------------------ | --------------- | | Warp | `~/.warp/.mcp.json` | `.warp/.mcp.json` at project root | On by default | | Claude Code | `~/.claude.json` | `.mcp.json` at project root | Requires toggle | | Codex | `~/.codex/config.toml` | `.codex/config.toml` at project root | Requires toggle | | Other agents | `~/.agents/.mcp.json` | `.agents/.mcp.json` at project root | Requires toggle | Global Warp servers auto-spawn by default. Global servers from all other providers auto-spawn only when **Auto-spawn servers from third-party agents** is enabled. Project-scoped servers from any provider require explicit approval. For provider-specific setup, see the [Claude Code MCP docs](https://code.claude.com/docs/en/mcp#user-scope) and [Codex MCP docs](https://developers.openai.com/codex/mcp/#connect-codex-to-an-mcp-server). #### Auto-spawn behavior [Section titled “Auto-spawn behavior”](#auto-spawn-behavior) Global Warp servers auto-spawn by default. Third-party agent servers require you to enable auto-spawn first. To auto-spawn global servers from third-party agents: 1. In the Warp app, go to **Settings** > **Agents** > **MCP servers**. 2. Toggle **Auto-spawn servers from third-party agents** on. ![Toggle to auto-spawn global file-based MCP servers](/assets/agent-platform/file-based-mcp-setting.png) Project-scoped servers from any provider must be toggled on individually from the MCP servers page. These are session-scoped — after restarting Warp, toggle them on again if you still trust the repo. #### Using `/agent-add-mcp` [Section titled “Using /agent-add-mcp”](#using-agent-add-mcp) The built-in `/agent-add-mcp` skill lets Warp’s agent create or update file-based MCP server definitions. Choose whether to save globally or in the current project — the skill writes the server definition to the matching file: * **Global:** `~/.warp/.mcp.json` * **Project-scoped:** `{repo_root}/.warp/.mcp.json` [![](/assets/agent-platform/file-based-mcp-demo.poster.jpg)](/assets/agent-platform/file-based-mcp-demo.mp4) The demo shows how to use `/agent-add-mcp` to add an MCP server, choose where Warp saves the file-based configuration, and review the generated `.warp/.mcp.json` file before using the server. #### Security mitigations [Section titled “Security mitigations”](#security-mitigations) MCP config files can start local commands and send data to external tools. Warp adds approval gates around file-based MCP servers to reduce the risk of untrusted config changes: * **Config edits require approval** - Warp prevents edits to MCP config files unless you explicitly approve the change. This keeps an agent or automation from silently adding a server that can run commands or access data. * **Project-scoped servers never auto-spawn** - Warp detects project-scoped MCP config files in cloned repos, but requires you to start each server manually. This prevents a cloned repo from automatically starting an MCP server that runs arbitrary local commands. Note File-based servers that require OAuth show an authentication modal on their first spawn. Credentials are saved for future spawns, the same as manually configured MCP servers. ### Managing MCP servers [Section titled “Managing MCP servers”](#managing-mcp-servers) After MCP servers are registered in Warp, you can **Start** or **Stop** them from the MCP servers page. Each running server will have a list of available tools and resources. You can rename and edit a server’s name, as well as delete the server. If you are a part of a Team, you can also share a MCP with your teammates. ### Sharing MCP servers [Section titled “Sharing MCP servers”](#sharing-mcp-servers) MCP servers can be shared with your teammates by clicking the share icon. When sharing, sensitive values in the `env` configuration will be automatically scrubbed and replaced with variables. ![Sharing a MCP Server](/_astro/mcp-servers-share.BrY797Q-_ZGrvJ5.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Sharing a MCP Server. Your teammates can find shared MCP servers under the `Shared` section of their MCP settings. When your teammates install your server configuration, they will be prompted to enter any scrubbed `env` values. Warp also provides out-of-the-box MCP servers that can be installed by anyone. These can be found under the `Shared` section of your MCP settings. ### Authentication in MCP servers [Section titled “Authentication in MCP servers”](#authentication-in-mcp-servers) Most MCP servers require authentication to connect to external services. Warp supports the following methods: * **Environment variables**: pass an API key or access token via the server’s environment variables. * **OAuth login (one-click installation)**: simplifies configuration by handling authentication through your browser. Warp stores credentials securely on your device and reuses them for future sessions. Re-authentication is required when opening Warp on a new machine. * Starting a server without existing credentials automatically opens a browser-based authentication flow. * Credentials can be revoked at any time from the MCP Servers pane in Warp. * **Custom Headers**: pass an Authentication Bearer token via the headers variable. ### Debugging MCP [Section titled “Debugging MCP”](#debugging-mcp) If you’re having trouble with an MCP server, you can check the logs for any errors or messages to help you diagnose the problem by clicking the `View Logs` button on a server from the MCP servers page. Caution If you choose to share your MCP server logs with anybody, **make sure to remove any sensitive information before sharing**, as they may contain API keys. Many SSE based MCP servers will state that your URL should be treated like a password, and can be used with no additional authentication. Note Tip: We’ve noticed that some models often work better with MCP servers than others. If you’re having trouble calling or using an MCP server, try using a different model. #### Debugging MCP Authentication issues [Section titled “Debugging MCP Authentication issues”](#debugging-mcp-authentication-issues) In some cases you may need to reset the auth token for some MCP servers. To do this delete the local MCP auth files by running the following: `rm -rf ~/.mcp-auth` Caution Note this will delete all your MCP auth tokens stored locally so you will need to login and re-authenticate. If the above doesn’t help and you need to reset or change authentication, you may need to switch to a CLI-based MCP server configuration and provide the token via environment variables. See [Sentry CLI MCP Example](/agent-platform/capabilities/mcp/#sentry). ### Where MCP logs are stored [Section titled “Where MCP logs are stored”](#where-mcp-logs-are-stored) Warp saves the MCP logs locally on your computer. You can open the files directly and inspect the full contents in the following location: * macOS ```bash cd "$HOME/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Stable/mcp" ``` * Windows ```powershell Set-Location $env:LOCALAPPDATA\warp\Warp\data\logs\mcp ``` * Linux ```bash cd "${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/mcp" ``` ## MCP server configuration examples [Section titled “MCP server configuration examples”](#mcp-server-configuration-examples) Below are examples for popular Model Context Protocol (MCP) servers. * **CLI Server (Command)** — local `npx` or `docker` command based MCP servers. * **Streamable HTTP or SSE Server (URL)** — remote or locally hosted MCP endpoints. ### **Engineering & Ops** [Section titled “Engineering & Ops”](#engineering--ops) * GitHub [GitHub MCP Docs](https://github.com/github/github-mcp-server) **GitHub CLI Server (Command)** ```json { "GitHub": { "command": "docker", "args": ["run","-i","--rm","-e","GITHUB_PERSONAL_ACCESS_TOKEN","ghcr.io/github/github-mcp-server"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "" } } } ``` **GitHub SSE Server (URL)** ```json { "GitHub": { "url": "https://api.githubcopilot.com/mcp/" } } ``` * Sentry [Sentry MCP Docs](https://docs.sentry.io/product/sentry-mcp/) **Sentry CLI Server (Command)** ```json { "Sentry": { "command": "npx", "args": ["-y","mcp-remote@latest","https://mcp.sentry.dev/mcp"] } } ``` **Sentry SSE Server (URL)** ```json { "Sentry": { "url": "https://mcp.sentry.dev/sse" } } ``` * Grafana [Grafana MCP Docs](https://github.com/grafana/mcp-grafana) **Grafana CLI Server (Command)** ```json { "Grafana": { "command": "docker", "args": ["run","--rm","-i","-e","GRAFANA_URL","-e","GRAFANA_API_KEY","mcp/grafana","-t","stdio","-debug"], "env": { "GRAFANA_URL": "http://localhost:3000", "GRAFANA_API_KEY": "" } } } ``` **Grafana SSE Server (URL)** ```json { "Grafana": { "url": "https://your-mcp-host.com/api/mcp/grafana/sse" } } ``` * Linear [Linear MCP Docs](https://linear.app/docs/mcp) **Linear CLI Server (Command)** ```json { "Linear": { "command": "npx", "args": ["-y","mcp-remote","https://mcp.linear.app/sse"] } } ``` **Linear SSE Server (URL)** ```json { "Linear": { "url": "https://mcp.linear.app/sse" } } ``` * Chroma **Chroma Package Search CLI Server (Command)** 1. Visit Chroma’s [Package Search](http://trychroma.com/package-search) page. 2. Click “Get API Key” to create or log into your Chroma account and issue an API key for Package Search. 3. After issuing your API key, click the “Other” tab and copy your API key. 4. Add the following to your Warp MCP config. Make sure to click “Start” on the server after adding. More info in [Chroma’s Package Search MCP Docs](https://docs.trychroma.com/cloud/package-search/mcp) ```json { "package-search": { "command": "npx", "args": ["mcp-remote", "https://mcp.trychroma.com/package-search/v1", "--header", "x-chroma-token: ${X_CHROMA_TOKEN}"], "env": { "X_CHROMA_TOKEN": "" } } } ``` ### **Design & Collaboration** [Section titled “Design & Collaboration”](#design--collaboration) * Figma **Figma Remote MCP Server (Recommended)** The official Figma remote MCP server supports OAuth for simple, one-click setup. 1. In Warp, go to **Warp Drive** > **MCP Servers** > **+ Add** and paste the configuration below. 2. Warp will open a browser window to authenticate with Figma. 3. After approving access, credentials are stored securely on your device. Note Note: A Figma account with [Dev Mode](https://www.figma.com/dev-mode/) enabled is required. ```json { "Figma": { "url": "https://mcp.figma.com/mcp" } } ``` **Figma Local MCP Server** 1. Enable the Official Figma MCP Server. [Figma MCP Docs](https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server) 2. Open the [Figma desktop app](https://www.figma.com/downloads/) and make sure you’ve [updated to the latest version](https://help.figma.com/hc/en-us/articles/5601429983767-Guide-to-the-Figma-desktop-app#h_01HE5QD60DG6FEEDTZVJYM82QW). 3. Create or open a Figma Design file. 4. In the upper-left corner, open the Figma menu. 5. Under **Preferences**, select **Enable local MCP Server**. 6. Enter the following configuration into **Warp** > **Warp Drive** > **MCP Servers** > **+ Add**. ```json { "Figma (Local)": { "url": "http://127.0.0.1:3845/mcp" } } ``` * Slack [Slack MCP Docs](https://github.com/korotovsky/slack-mcp-server/) **Slack CLI Server (Command)** Enter the following configuration into **Warp** > **Warp Drive** > **MCP Servers** > **+ Add**. ```json { "Slack": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-slack"], "env": { "SLACK_BOT_TOKEN": "xoxb-", "SLACK_APP_TOKEN": "xapp-", "SLACK_TEAM_ID": "T", "SLACK_CHANNEL_IDS": ", ", "MCP_MODE": "stdio" } } } ``` **Slack SSE Server (URL)** Enter the following configuration into **Warp** > **Warp Drive** > **MCP Servers** > **+ Add**. ```json { "Slack": { "url": "https://your-mcp-host.com/api/mcp/slack/sse" } } ``` * Atlassian [Atlassian MCP Docs](https://support.atlassian.com/rovo/docs/setting-up-ides/) **Atlassian CLI Server (Command)** Enter the following configuration into **Warp** > **Warp Drive** > **MCP Servers** > **+ Add**. ```json { "Atlassian": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/sse"] } } ``` * Notion [Notion MCP Docs](https://developers.notion.com/docs/mcp) **Notion CLI Server (Command)** Enter the following configuration into **Warp** > **Warp Drive** > **MCP Servers** > **+ Add**. ```json { "Notion": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"] } } ``` **Notion SSE Server (URL)** Enter the following configuration into **Warp** > **Warp Drive** > **MCP Servers** > **+ Add**. ```json { "Notion": { "url": "https://mcp.notion.com/sse" } } ``` ### MCP server demos [Section titled “MCP server demos”](#mcp-server-demos) [Warp Guides](/guides/) hosts a collection of demos and walkthroughs showing how MCP servers can extend your workflows. Each example highlights practical use cases you can try today: * [**GitHub**](/guides/external-tools/github-mcp-summarizing-open-prs-and-creating-gh-issues/) — access repositories, issues, and pull requests through MCP. * [**Sentry**](/guides/external-tools/sentry-mcp-fix-sentry-error-in-empower-website/) — surface error monitoring and alerts as agent-usable data. * [**Linear**](/guides/external-tools/linear-mcp-retrieve-issue-data/) — integrate project management tasks and tickets. * [**Puppeteer**](/guides/external-tools/puppeteer-mcp-scraping-amazon-web-reviews/) — run automated browser workflows via MCP. * [**Context7**](/guides/external-tools/context7-mcp-update-astro-project-with-best-practices/) — experiment with external data integrations. # Agent model choice > Choose from a curated set of top LLMs for Warp's Agents (or let Warp auto-select the best model). ## Available models [Section titled “Available models”](#available-models) Warp lets you choose from a curated set of Large Language Models (LLMs) to power your Agentic Development Environment. **Warp supports the following models.** The `model_id` values shown below can be used when configuring models via the [Oz Platform](/agent-platform/cloud-agents/platform/) or [CLI](/reference/cli/). ### Auto models [Section titled “Auto models”](#auto-models) | Model | `model_id` | Description | | --------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Auto (Responsive) | `auto` | Selects the highest-quality, fastest available model. May consume credits more quickly. | | Auto (Cost-efficient) | `auto-efficient` | Optimizes for lower credit consumption while maintaining strong output quality. | | Auto (Genius) | `auto-genius` | Adapts to task complexity and selects Warp’s most capable model when it’s worth it. Best for deep debugging, architecture decisions, and `/plan` sessions. | | Auto (Open-weights) | `auto-open` | Routes between the best open-source models available in Warp. Optimizes for low cost and fast speed using open-weights models. | All Auto models perform well across all agent workflows and are ideal if you prefer Warp to manage model selection dynamically. #### OpenAI [Section titled “OpenAI”](#openai) | Model | `model_id` | Reasoning Level | | ------------- | ---------------------- | --------------- | | GPT-5.5 | `gpt-5-5-low` | Low | | GPT-5.5 | `gpt-5-5-medium` | Medium | | GPT-5.5 | `gpt-5-5-high` | High | | GPT-5.5 | `gpt-5-5-xhigh` | Extra High | | GPT-5.4 | `gpt-5-4-low` | Low | | GPT-5.4 | `gpt-5-4-medium` | Medium | | GPT-5.4 | `gpt-5-4-high` | High | | GPT-5.4 | `gpt-5-4-xhigh` | Extra High | | GPT-5.3 Codex | `gpt-5-3-codex-low` | Low | | GPT-5.3 Codex | `gpt-5-3-codex-medium` | Medium | | GPT-5.3 Codex | `gpt-5-3-codex-high` | High | | GPT-5.3 Codex | `gpt-5-3-codex-xhigh` | Extra High | | GPT-5.2 Codex | `gpt-5-2-codex-low` | Low | | GPT-5.2 Codex | `gpt-5-2-codex-medium` | Medium | | GPT-5.2 Codex | `gpt-5-2-codex-high` | High | | GPT-5.2 Codex | `gpt-5-2-codex-xhigh` | Extra High | | GPT-5.2 | `gpt-5-2-low` | Low | | GPT-5.2 | `gpt-5-2-medium` | Medium | | GPT-5.2 | `gpt-5-2-high` | High | | GPT-5.2 | `gpt-5-2-xhigh` | Extra High | #### Anthropic [Section titled “Anthropic”](#anthropic) | Model | `model_id` | Variant | | ----------------- | ---------------------------- | -------------- | | Claude Opus 4.7 | `claude-4-7-opus-xhigh` | Default effort | | Claude Opus 4.7 | `claude-4-7-opus-high` | High effort | | Claude Opus 4.7 | `claude-4-7-opus-max` | Max effort | | Claude Opus 4.6 | `claude-4-6-opus-high` | Default effort | | Claude Opus 4.6 | `claude-4-6-opus-max` | Max effort | | Claude Sonnet 4.6 | `claude-4-6-sonnet-high` | Default effort | | Claude Sonnet 4.6 | `claude-4-6-sonnet-max` | Max effort | | Claude Opus 4.5 | `claude-4-5-opus` | Thinking off | | Claude Opus 4.5 | `claude-4-5-opus-thinking` | Thinking on | | Claude Sonnet 4.5 | `claude-4-5-sonnet` | Thinking off | | Claude Sonnet 4.5 | `claude-4-5-sonnet-thinking` | Thinking on | | Claude Haiku 4.5 | `claude-4-5-haiku` | — | #### Google [Section titled “Google”](#google) | Model | `model_id` | | -------------- | ---------------- | | Gemini 3.1 Pro | `gemini-3.1-pro` | #### Hosted models (via [Fireworks AI](https://fireworks.ai)) [Section titled “Hosted models (via Fireworks AI)”](#hosted-models-via-fireworks-ai) Warp also supports leading open source models hosted via Fireworks AI, so you can run them from inside Warp without setting up your own inference infrastructure. | Model | `model_id` | | ------------- | ------------------------- | | GLM 5 | `glm-5-fireworks` | | GLM 5.1 | `glm-5.1-fireworks` | | Kimi K2.5 | `kimi-k25-fireworks` | | Kimi K2.6 | `kimi-k26-fireworks` | | Minimax 2.7 | `minimax-2.7-fireworks` | | Qwen 3.6 Plus | `qwen-3.6-plus-fireworks` | ### How to change models [Section titled “How to change models”](#how-to-change-models) You can use the model picker in your prompt input to quickly switch between models. The currently active model appears directly in the input editor. ![Model selector dropdown showing available models with Intelligence, Speed, and Cost benchmarks](/_astro/model-selector-dropdown.C5X4qk_B_1dmhsq.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Model selector in Warp’s input. To change models, click the displayed model name (for example, *Claude Sonnet 4.5*) to open a dropdown with all supported options. Your selection will automatically persist for future prompts. ### Model fallback [Section titled “Model fallback”](#model-fallback) Warp uses a model fallback system to ensure uninterrupted service if your selected model becomes temporarily unavailable due to provider outages or capacity issues. **How it works:** * If your selected model isn’t available, Warp automatically uses a fallback model from a predefined chain to continue your conversation without errors. * As soon as your originally selected model becomes available again, Warp automatically switches back to it. * The fallback model is selected to provide comparable quality and capabilities to your original choice. ### Configuring models per Agent Profile [Section titled “Configuring models per Agent Profile”](#configuring-models-per-agent-profile) You can configure the base model for each [Agent Profile](/agent-platform/capabilities/agent-profiles-permissions/), alongside the Agent’s autonomy, tool access, and other permissions. The base model is also used for [Planning](/agent-platform/capabilities/planning/). Edit your default profile or any other profile directly in **Settings** > **Agents** > **Profiles**. ### Zero data retention policies [Section titled “Zero data retention policies”](#zero-data-retention-policies) Warp integrates with multiple Large Language Model (LLM) providers to power its AI-driven features. **These providers include, but are not limited to:** * OpenAI * Anthropic * Google * xAI * Fireworks AI Warp has executed **Zero Data Retention (ZDR)** agreements with these providers. This means that, by default across all plans: * LLM providers commit not to train their models on any customer-generated data processed through Warp’s services. * LLM providers commit to delete inputs and outputs after generating the relevant output, within a fixed time period. Warp enforces these commitments through both technical measures and contractual safeguards with the LLM providers. # Agent planning and execution > Turn requests into structured, editable plans that agents execute step-by-step with version control. Warp has native planning functionality that helps you break down complex engineering tasks into structured, executable steps. Planning is tightly integrated with Warp’s coding agent and provides a persistent plan editor, version history, selective execution, and deep links into your workspace. ![YouTube video](https://i.ytimg.com/vi/DawcFWyudV0/sddefault.jpg) *** ### Creating a plan [Section titled “Creating a plan”](#creating-a-plan) You can generate a plan using the `/plan` [slash command](/agent-platform/capabilities/slash-commands/) or by asking the agent in natural language. ![Prompting the agent to create a plan using the slash command.](/_astro/plan-slash-command.DJgVEABq_2aTiJg.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Creating a plan with the /plan command. The agent then creates a structured plan inside Warp’s native rich text editor, which is designed for long, multi-step workflows. The editor includes clean formatting, inline code blocks, and clickable file paths so you can open referenced files immediately in Warp (see below) or in your external editor. ### Reviewing and editing [Section titled “Reviewing and editing”](#reviewing-and-editing) Once a plan is generated, you can review it, reorganize steps, or refine details. You can edit the document manually or ask the agent to revise sections for you. ![Plan editor in Warp.](/_astro/planning-main-view.B3ScH40z_Z30qck.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Plan editor in Warp. Any update made by the agent **creates a new version**. Version history lets you compare past iterations and restore an older version if you want to revert your approach, preserving a clear decision trail as the plan evolves. ![Access previous versions of your plan.](/_astro/agent-plans-versioning.1TkBRzlY_Z4PQJF.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Access previous versions of your plan. ### Executing a plan [Section titled “Executing a plan”](#executing-a-plan) When you’re ready to start implementing, prompt the agent to run the plan. You can ask it to execute the full set of steps or only a specific section, such as “Implement phase 1 of the plan.” ![Manually referencing the plan using @ to kickoff the plan.](/_astro/manually-trigger-plan.C2Elml8l_1s2aFK.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Referencing a plan using @. The agent applies changes incrementally and updates files as it proceeds. This makes it easy to validate early steps before moving forward, adjust the plan mid-run, or try alternative paths without committing to the full workflow. If you revise the plan while the agent is running, you can notify it directly; the agent will adjust its execution based on your updates. ![Option to pass new plan to agent if plan changes during runtime.](/_astro/update-agent-mid-plan.Dg68fcOc_1GyFuJ.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Prompt to update the agent’s plan during execution. ### Monitoring progress [Section titled “Monitoring progress”](#monitoring-progress) While the agent is running, you can reopen the plan at any time by selecting **View plan** in the input. You can also follow each change in real time through the [Code Review](/code/code-review/) panel and add comments or guidance using [Interactive Code Review](/agent-platform/local-agents/interactive-code-review/). ![Monitoring progress with the task list and plan view.](/_astro/agent-plans-tasks.D4jtQV3D_ZoE1B2.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Monitoring progress with the task list and plan view. This gives you clear oversight, helps confirm expected behavior, and lets you intervene quickly if something needs correction. ### Saving and sharing [Section titled “Saving and sharing”](#saving-and-sharing) Warp automatically saves all plans in the *Plans* folder in [Warp Drive](/knowledge-and-collaboration/warp-drive/). You’ll see a confirmation when your plan is synced. ![Plans are automatically synced to Warp Drive.](/_astro/agent-plans-synced.DwmjsgGm_Z1c2JAo.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Plans are automatically synced to Warp Drive. You can export any plan as Markdown, check it into your repository, or share a link—useful for GitHub PRs, design reviews, or async collaboration. ![Different ways to share a plan.](/_astro/export-notebooks.Bp4-R4XJ_Z2k3gOy.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Different ways to share a plan. Because plans persist in Warp Drive, you can return to them later, reuse them for new work, or treat them as documentation for ongoing projects. This is also naturally passed to the agent as context. ![Plans are accessible directly from the Warp Drive side panel.](/_astro/plans-in-warp-drive-side-panel.TqXArAFT_ZKQKin.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Plans are accessible directly from the Warp Drive side panel. You can configure whether your plans will be automatically added and synced to Warp Drive in your [Agent Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/) under **Settings** > **Agents** > **Profiles**. ![Toggle in Agent Profiles & Permissions to automatically sync agent-generated plans to Warp Drive.](/_astro/auto-sync-plans-1.DXOypMLJ_xUBgg.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ### Using plans across conversations [Section titled “Using plans across conversations”](#using-plans-across-conversations) Plans are reusable across tasks and sessions. You can reference them in future prompts, continue where you left off, or build follow-up plans that rely on earlier work. The **@plans** command helps you quickly search for and reopen previously saved plans, making planning a consistent part of your development workflow rather than a one-off step. Learn more about attaching context using @ [here](/agent-platform/local-agents/agent-context/using-to-add-context/). ![Searching for and reopening previously saved plans with the @plans command.](/_astro/@-reference-plans.BfTnUOlO_Z1BRyd3.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) *** ## Next steps [Section titled “Next steps”](#next-steps) As the agent executes your plan, you’ll review code changes and may want to scale work to the cloud. * **[Interactive Code Review](/agent-platform/local-agents/interactive-code-review/)** - Leave inline comments on agent-generated diffs and have the agent revise in one pass. * **[Cloud Agents quickstart](/agent-platform/cloud-agents/quickstart/)** - Run agents in the cloud for longer tasks, background automation, or parallel work across repos. # Rules for agents > Create reusable Global or Project Rules to ensure Warp’s agents follow your coding standards, project conventions, and personal preferences. Warp’s **Rules** feature lets you create reusable guidelines that inform how agents respond to your prompts. Rules help tailor responses to match your coding standards, project conventions, and personal preferences, making agent interactions smarter and more consistent. Warp supports two types of rules: **Global Rules** and **Project Rules**. ![YouTube video](https://i.ytimg.com/vi/fDr0-3bLxMQ/sddefault.jpg) ## Global Rules [Section titled “Global Rules”](#global-rules) Global Rules apply across all projects and contexts. They’re ideal for: * Coding standards and best practices * Workspace-wide guidelines * Tool configurations or preferences you want applied everywhere Warp may also suggest Global Rules based on your usage patterns to make future interactions smarter and more consistent. ## Project Rules [Section titled “Project Rules”](#project-rules) Project Rules live in your codebase and apply automatically when working within that project. They’re stored in an `AGENTS.md` file (or `WARP.md` for backwards compatibility) and can be: * Placed in the root of your repository * Added in subdirectories for more targeted guidance Note Warp uses `AGENTS.md` as the default project rules file. Existing `WARP.md` files are still fully supported—if you have `WARP.md`, it will continue to work as expected. You can also rename `WARP.md` to `AGENTS.md` at any time without additional changes. If both `WARP.md` and `AGENTS.md` exist in the same directory, `WARP.md` takes priority. Caution The filename must be in **all caps** for Warp to recognize it (e.g., `AGENTS.md`, not `agents.md` or `Agents.md`). We recommend creating `AGENTS.md` for new projects. **When you’re in a directory:** * Warp automatically applies the `AGENTS.md` (or `WARP.md`) in the root and in the current directory. * If you edit files in another subdirectory, Warp makes a best-effort attempt to include that subdirectory’s rules file as well. Example project structure: * project/ * api/ * AGENTS.md API-specific rules * ui/ * AGENTS.md UI-specific rules * AGENTS.md Project-wide rules How Warp applies these Project Rules: * **If the current directory is `ui/`** * Automatically applied: `project/AGENTS.md` and `project/ui/AGENTS.md` * Best effort: `project/api/AGENTS.md` if editing files there * **If the current directory is `api/`** * Automatically applied: `project/AGENTS.md` and `project/api/AGENTS.md` * Best effort: `project/ui/AGENTS.md` if editing files there ### **Rules precedence** [Section titled “Rules precedence”](#rules-precedence) When multiple rules apply, Warp follows this order of precedence: 1. Rules in the current subdirectory’s project rules file 2. Rules in the root directory’s project rules file 3. Global Rules This ensures the most specific, project-relevant rules take priority over broader ones. *** ## How to access Rules [Section titled “How to access Rules”](#how-to-access-rules) * From [Warp Drive](/knowledge-and-collaboration/warp-drive/): **Personal** > **Rules** * From the [Command Palette](/terminal/command-palette/): search for “Open AI Rules” * From the Settings panel: **Settings** > **Agents** > **Knowledge** > **Manage Rules** * Here, you can manage both Global as well as Project Rules. * From the macOS Menu: `AI > Open Rules` * From the Slash Commands menu: `/open-project-rules` to open Project Rules directly in Warp’s code editor ![Project Rules UI open in a Rules pane](/_astro/project-scoped-rules-pane.COFN1ocC_1kVbc9.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Project Rules UI open in a Rules pane. ## How to create, edit, or delete Rules [Section titled “How to create, edit, or delete Rules”](#how-to-create-edit-or-delete-rules) #### Global Rules [Section titled “Global Rules”](#global-rules-1) * **From Warp Drive Rules pane:** **Personal** > **Rules** > **Global**\ Add, edit, or delete any number of rules. Each rule can include: * Name (optional) * Description (what the rule does and when to apply it) * **From the Slash Commands menu:** `/add-rule` in Auto or Agent input modes to create a new Global Rule (automatically opens the Warp Drive Rules pane). [Rules Demo (legacy) with just Global Rules. Project rules can also be found there.](https://www.loom.com/embed/3a49462c01e149cf9c040130cebe1184) #### Project Rules [Section titled “Project Rules”](#project-rules-1) * **When in a directory, set up Project Rules with a slash command:** Use `/init` in Auto-Detection or Agent Mode to: * Begin indexing your codebase or display indexing status * Generate an `AGENTS.md` file with initial context, or * Link an existing Rules file to `AGENTS.md` * Warp currently supports linking the following external Rules files: `CLAUDE.md`, `.cursorrules`, `AGENT.md`, `GEMINI.md`, `.clinerules`, `.windsurfrules`, `.github/copilot-instructions.md` To view all Project Rules and open them in Warp, access it via the Warp Drive Rules pane: **Personal** > **Rules** > **Project-based** ### Rules as Agent context [Section titled “Rules as Agent context”](#rules-as-agent-context) When relevant, Agents automatically pull in applicable rules to guide their responses. Rules used in an interaction will appear in the conversation under **References** or marked as derived from a specific rule. ![Context derived from memory](/_astro/context-derived-from-memory.CXs5UK2q_Z1yg7n0.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) An agent response showing which rules were applied. ![Context derived from memory](/_astro/context-references-memory.BSO301p__TWD1h.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Rules listed as references in an agent conversation. ### Rules privacy [Section titled “Rules privacy”](#rules-privacy) See our [Privacy Page](/support-and-community/privacy-and-security/privacy/) for more information on how we handle data with Rules. # Skills for agents > Create reusable instruction sets that teach agents specific tasks and share expertise across your team. Skills allow you to create reusable, shareable instructions that agents can invoke when performing tasks. Instead of repeating detailed prompts, you can encapsulate common workflows, coding patterns, or domain expertise into skill files that agents automatically discover and use. ## Key features [Section titled “Key features”](#key-features) * **Reusable instructions** - Define a task once and let Agents use it whenever relevant * **Project and global scopes** - Create skills specific to a project or available across all projects * **Automatic discovery** - Agents are aware of all available skills and invoke them when appropriate * **Simple markdown format** - Skills are just markdown files with a small amount of metadata * **Supporting files** - Include scripts, templates, or other resources alongside your skill instructions * **Slash command invocation** - Invoke any skill directly with `/{skill-name}` * **Parameterized skills** - Use argument placeholders to create dynamic, reusable skill templates ## How Skills work [Section titled “How Skills work”](#how-skills-work) When you start an [Agent conversation](/agent-platform/local-agents/interacting-with-agents/), the Agent receives a list of all available skills with their names and descriptions. When the Agent determines that a skill would help accomplish your task, it loads the skill’s full instructions and follows them to complete the task. Caution Skill discovery is based on your current working directory. For Git repositories, Warp includes all skills from your current directory up through the repository root. If you’re working in project A, you won’t have access to skills from project B. Note Skills complement Rules, which provide persistent guidelines that Agents always follow. Use Rules for constraints and preferences; use Skills for specific task workflows. ### Skill name conflicts [Section titled “Skill name conflicts”](#skill-name-conflicts) If you have skills with the same name in multiple directories, Warp handles the conflict differently depending on how the skill is invoked: * **Natural language** - The Agent receives a list of all in-scope skills including their names, descriptions, and file paths. The Agent can see all available options and chooses the appropriate skill based on its path. * **Slash commands** - When multiple skills share the same name, Warp displays all matching skills in the menu. You select which one to use based on the description. * **Background resolution** - When Warp resolves skill names automatically (without direct user selection), it prioritizes home directory (global) skills first, then skills from higher directories (closer to the repository root). ### Example interactions [Section titled “Example interactions”](#example-interactions) You can invoke skills in two ways: **Using natural language** - Describe what you want to accomplish: * “Use the deploy skill to push to staging” * “Check the docs for broken links” (invokes a link-checking skill) * “Create a DOCX file with my project’s README content” * “Draft documentation for the new API endpoint based on this PR” **Using slash commands** - Invoke a skill directly with `/{skill-name}`: * `/deploy` - Invokes the deploy skill * `/add-feature-flag` - Invokes the add-feature-flag skill The Agent recognizes when your request matches a skill’s purpose, loads the skill instructions, and follows them to complete the task. ## Skill file format [Section titled “Skill file format”](#skill-file-format) Skills are markdown files with YAML frontmatter. Each skill must have: * **name** - A unique identifier for the skill (typically kebab-case) * **description** - A brief explanation of what the skill does and when to use it ### Basic structure [Section titled “Basic structure”](#basic-structure) ```markdown --- name: your-skill-name description: Brief description of what this skill does and when to use it --- # Your Skill Name ## Instructions Provide clear, step-by-step guidance for the agent. You can use argument placeholders like $ARGUMENTS or $0 in the body (see [Skill arguments](#skill-arguments)). ## Examples Show concrete examples of using this skill. ``` ### Example skill file [Section titled “Example skill file”](#example-skill-file) Here’s a complete example of a skill that helps create feature flags: ```markdown --- name: add-feature-flag description: Add a new feature flag to the codebase with proper configuration and documentation --- # Add Feature Flag ## Instructions 1. Ask the user for the feature flag name and default value 2. Add the flag definition to `config/feature_flags.yaml` 3. Create a helper function in `src/utils/flags.ts` 4. Update the feature flags documentation in `docs/FEATURE_FLAGS.md` ## Configuration Format Feature flags should follow this format in the YAML file: feature_name: default: false description: "What this flag controls" owner: "team-name" ## Examples - "Add a feature flag for the new checkout flow" - "Create a flag to enable dark mode for beta users" ``` ## Skill arguments [Section titled “Skill arguments”](#skill-arguments) Skills can include argument placeholders that are automatically substituted with values you provide when invoking the skill. This lets you create reusable, parameterized skill templates. [Using Skill Arguments in Warp](https://www.loom.com/embed/4cb0a80e567c41788816cd9b5acbc7ed) ### Argument syntax [Section titled “Argument syntax”](#argument-syntax) Three placeholder formats are supported: * **`$ARGUMENTS`** — Replaced with the full raw argument string (everything after the skill name). * **`$ARGUMENTS[N]`** — Replaced with the Nth whitespace-separated argument (0-indexed). For example, `$ARGUMENTS[0]` is the first argument, `$ARGUMENTS[1]` is the second, etc. * **`$N`** — Shorthand for `$ARGUMENTS[N]`. For example, `$0` is equivalent to `$ARGUMENTS[0]`. ### How argument substitution works [Section titled “How argument substitution works”](#how-argument-substitution-works) When you invoke a skill, any text you type after the skill name is treated as the argument string. The argument string is split on whitespace to produce individual indexed arguments. **If the skill contains argument placeholders** (`$ARGUMENTS`, `$ARGUMENTS[N]`, or `$N`), the placeholders are replaced with the corresponding argument values before the skill instructions are sent to the agent. **If the skill does not contain any argument placeholders**, the extra text you provide is passed to the agent as a separate user message alongside the skill instructions. This means you can always add context when invoking a skill, whether or not it uses argument placeholders. Note If a placeholder references an argument index that wasn’t provided (e.g. `$2` when only two arguments were given), the placeholder is left as-is in the skill content. ### Example: Skill with arguments [Section titled “Example: Skill with arguments”](#example-skill-with-arguments) Here’s a skill that uses arguments to explain a topic for a specific audience: ```markdown --- name: explain-topic description: Explain a topic for a specific audience in a given tone --- # Explain Topic Explain $0 for an audience of $1 professionals. Use a $2 tone. Full request: $ARGUMENTS ``` Invoking this skill with: ```plaintext /explain-topic bears engineering fun ``` Produces the following instructions for the agent: ```plaintext Explain bears for an audience of engineering professionals. Use a fun tone. Full request: bears engineering fun ``` ### Example: Skill without arguments [Section titled “Example: Skill without arguments”](#example-skill-without-arguments) If a skill has no argument placeholders: ```markdown --- name: greet description: Greet the user with an Australian-style hello --- # Greet Greet the user warmly in an Australian style. ``` Invoking with extra text: ```plaintext /greet say it in French ``` The skill instructions are sent first, then “say it in French” is passed as a follow-up user message. The agent sees both and can combine them — in this case, greeting in French with an Australian flair. ## Skill locations [Section titled “Skill locations”](#skill-locations) Skills can be stored at two levels: project-level (accessible only within that project) and user-level (accessible from any project). ### Project skills [Section titled “Project skills”](#project-skills) Project skills live in your repository and are available when you’re working in that project. We recommend storing them at your project root, but skills in subdirectories are also discovered when you’re working within that subdirectory. This is useful for monorepos with separate `./frontend` and `./backend` directories. Store them in any of these directories: * **`.agents/skills/`** (recommended) * **`.warp/skills/`** * **`.claude/skills/`** * **`.codex/skills/`** * **`.cursor/skills/`** * **`.gemini/skills/`** * **`.copilot/skills/`** * **`.factory/skills/`** * **`.github/skills/`** * **`.opencode/skills/`** Each skill must be in its own subdirectory with a `SKILL.md` file. Any supporting files (scripts, templates, configs) should be referenced in `SKILL.md` so the Agent knows they exist: * your-project/ * .agents/ * skills/ * add-feature-flag/ * SKILL.md * run-migrations/ * SKILL.md * .claude/ * skills/ * review-code/ * SKILL.md * .github/ * skills/ * create-release/ * SKILL.md Note Warp scans all supported skill directory names in your project root, allowing you to maintain skills compatible with multiple AI coding tools in the same repository. ### Root directory skills (global) [Section titled “Root directory skills (global)”](#root-directory-skills-global) Root directory skills are stored in your home directory and are available across all projects on your machine. These are useful for personal workflows, coding patterns, or procedures you use regardless of the specific project. Store global skills in any of these directories in your home folder: * **`~/.agents/skills/`** (recommended) * **`~/.warp/skills/`** * **`~/.claude/skills/`** * **`~/.codex/skills/`** * **`~/.cursor/skills/`** * **`~/.gemini/skills/`** * **`~/.copilot/skills/`** * **`~/.factory/skills/`** * **`~/.github/skills/`** * **`~/.opencode/skills/`** The directory structure is the same as project skills: * `~/.agents/` * skills/ * git-workflow/ * SKILL.md * code-review/ * SKILL.md ### Project vs Root directory skills [Section titled “Project vs Root directory skills”](#project-vs-root-directory-skills) Understanding when to use each level: **Project skills** are best for: * Project-specific workflows (deployment, testing, migrations) * Team-shared procedures and standards * Repository-specific automation and tooling * Domain-specific patterns for that codebase **Root directory skills** are best for: * Personal coding preferences and patterns * General-purpose workflows used across all projects * Cross-project automation (git workflows, documentation templates) * Professional standards you apply everywhere ## Creating skills [Section titled “Creating skills”](#creating-skills) ### Step 1: Choose a location [Section titled “Step 1: Choose a location”](#step-1-choose-a-location) Decide whether your skill should be: * **Project-specific** - Place it in one of your project’s skill directories (`.agents/skills/`, `.warp/skills/`, `.claude/skills/`, etc.) * **Global** - Place it in one of your home directory’s skill folders (`~/.agents/skills/`, `~/.warp/skills/`, `~/.claude/skills/`, etc.) ### Step 2: Create the directory structure [Section titled “Step 2: Create the directory structure”](#step-2-create-the-directory-structure) Create a subdirectory for your skill with a descriptive name: ```bash mkdir -p .agents/skills/my-new-skill ``` ### Step 3: Write the skill file [Section titled “Step 3: Write the skill file”](#step-3-write-the-skill-file) Create `SKILL.md` in your skill directory: ```bash touch .agents/skills/my-new-skill/SKILL.md ``` ### Step 4: Add content [Section titled “Step 4: Add content”](#step-4-add-content) Write your skill with clear instructions: ```markdown --- name: my-new-skill description: One-line description of what this skill does --- # My New Skill ## When to use Explain the scenarios where this skill is helpful. ## Instructions 1. First step the Agent should take 2. Second step with specific details 3. Continue with clear, actionable steps ## Important notes - Any constraints or requirements - Common pitfalls to avoid ``` ## Skills with supporting files [Section titled “Skills with supporting files”](#skills-with-supporting-files) Skills can include supporting files like scripts, templates, or configuration files. Place these files in the same directory as your `SKILL.md`: * .agents/skills/ * check-broken-links/ * SKILL.md * `check_links.py` Supporting script * config.yaml Configuration file In your skill instructions, reference these files using relative paths. For example, in your `SKILL.md`: ```plaintext ## Running the check From the project root: python3 .agents/skills/check-broken-links/check_links.py --internal-only ``` This pattern is useful for: * **Automation scripts** - Python, shell, or Node scripts that perform complex tasks * **Templates** - Boilerplate files the Agent can copy and customize * **Configuration** - Default settings or schemas the skill references ## Managing skills [Section titled “Managing skills”](#managing-skills) ### Viewing available skills [Section titled “Viewing available skills”](#viewing-available-skills) Ask the Agent what skills are available: ```plaintext What skills do I have? ``` The Agent lists all discovered skills with their names and descriptions. This includes skills from all supported directories in both your current project and your home directory. ### Editing skills [Section titled “Editing skills”](#editing-skills) Use the [`/open-skill`](/agent-platform/capabilities/slash-commands/) slash command to modify existing skills: ```plaintext /open-skill ``` This opens an interactive menu where you can: * Browse project and root directory skills * See which directory each skill is located in * Open the skill file in your editor ### Best practices [Section titled “Best practices”](#best-practices) * **Write clear descriptions** - The description is how Agents decide whether to use your skill * **Be specific in instructions** - Include exact file paths, command syntax, and expected formats * **Include examples** - Show concrete use cases to help Agents understand intent * **Keep skills focused** - Each skill should do one thing well * **Use consistent naming** - Follow a naming convention like `verb-noun` (e.g., `add-feature-flag`, `run-migrations`) * **Version control your skills** - Commit project skills to your repo so the whole team benefits ## Pre-built skills [Section titled “Pre-built skills”](#pre-built-skills) Warp maintains a public collection of ready-to-use skills in the [warpdotdev/oz-skills](https://github.com/warpdotdev/oz-skills) repository. You can browse these skills for inspiration, copy them directly into your project’s `.agents/skills/` directory, or adapt them to fit your team’s workflows. These same skills also appear as suggested agents in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/), where you can run them directly in the cloud. ## Invoking skills with a prompt [Section titled “Invoking skills with a prompt”](#invoking-skills-with-a-prompt) You can pass additional context or instructions to a skill when invoking it with a slash command. **Using slash commands with a prompt:** * `/deploy push the latest changes to staging` — Invokes the deploy skill with additional instructions to target staging * `/code-review focus on error handling and edge cases` — Invokes the code-review skill with guidance on what to prioritize This is useful when you want to reuse a skill’s workflow but tailor the execution to a specific situation without modifying the skill itself. ## Running agents from skills [Section titled “Running agents from skills”](#running-agents-from-skills) Skills can be used with both local and [cloud agents](/agent-platform/cloud-agents/overview/) to create reusable, automated workflows. When running an agent via the CLI, web app, or API, you can specify a skill to provide the base instructions for the agent. For a complete guide to running skill-based agents—including CLI usage, the Oz web app, scheduling, skill discovery, and API integration—see [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/). ## Related features [Section titled “Related features”](#related-features) * [**Rules**](/agent-platform/capabilities/rules/) - Set persistent guidelines and constraints for Agent behavior * [**MCP Servers**](/agent-platform/capabilities/mcp/) - Expose external data sources and tools to Agents * [**Cloud Agents**](/agent-platform/cloud-agents/overview/) - Run Agents in the cloud on schedules or triggers * [**Agent Profiles**](/agent-platform/capabilities/agent-profiles-permissions/) - Control Agent permissions and autonomy *** ## Next steps [Section titled “Next steps”](#next-steps) Skills become even more powerful when you automate and share them. * **[Scheduled Agents quickstart](/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart/)** - Run a skill on a recurring cron schedule for tasks like weekly dependency checks or daily code cleanup. * **[Integrations quickstart](/agent-platform/cloud-agents/integrations/quickstart/)** - Trigger skills from Slack or Linear so your team can invoke agent workflows from the tools they already use. # Slash Commands > Use Slash Commands in Agent Mode or Auto-Detection Mode to quickly run built-in actions or saved prompts without leaving the input field. When using Agent Mode or Auto-Detection Mode, typing `/` in the input field opens the Slash Commands menu. ![Slash Commands menu](/_astro/slash-commands-menu.htjt3JiN_TXojC.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Slash Commands menu. As you type, the menu filters results in real time, making it easy to find and run the command or prompt you need. ## Static slash commands [Section titled “Static slash commands”](#static-slash-commands) Warp currently supports the following built-in Slash Commands: | Slash Command | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/add-mcp` | Add a new [MCP server](/agent-platform/capabilities/mcp/). | | `/add-prompt` | Add a new [Agent Prompt](/knowledge-and-collaboration/warp-drive/prompts/) in Warp Drive. | | `/add-rule` | Add a new [Global Rule](/agent-platform/capabilities/rules/) for the Agent. | | `/agent` | Start a new [agent conversation](/agent-platform/local-agents/interacting-with-agents/). Optionally include a prompt to send immediately. | | `/changelog` | Open the latest Warp [changelog](/changelog/). | | `/cloud-agent` | Start a new [cloud agent conversation](/agent-platform/cloud-agents/overview/). `*` | | `/compact` | Free up context by summarizing conversation history. | | `/compact-and` | Compact the current conversation and then send a follow-up prompt. | | `/conversations` | Open [conversation history](/agent-platform/local-agents/interacting-with-agents/). | | `/cost` | Toggle credit usage details in the current conversation. | | `/create-environment` | Create a [Warp Environment](/agent-platform/cloud-agents/environments/) (Docker image + repos) via guided setup. `*` | | `/create-new-project` | Have the Agent walk you through creating a new coding project. `*` | | `/export-to-clipboard` | Export the current conversation to clipboard in markdown format. | | `/export-to-file` | Export the current conversation to a markdown file. | | `/feedback` | Send feedback to the Warp team. Only the Agent-drafted flow consumes credits. See [Using `/feedback` in Warp](/support-and-community/troubleshooting-and-support/sending-us-feedback/#using-feedback-in-warp) for details. `*` | | `/fork` | [Forks the current conversation](/agent-platform/local-agents/interacting-with-agents/conversation-forking/) into a new thread with the full context and history of the original. You can optionally include a prompt that will be sent immediately in the forked conversation. | | `/fork-and-compact` | [Forks the current conversation](/agent-platform/local-agents/interacting-with-agents/conversation-forking/) and automatically compacts the forked version. Useful when you want a fresh, summarized starting point that preserves relevant context while trimming the rest. | | `/fork-from` | Open a searchable menu to [fork the conversation](/agent-platform/local-agents/interacting-with-agents/conversation-forking/) from a specific query. Select a query to create a fork that includes everything up to that point. | | `/index` | Index the current codebase using [Codebase Context](/agent-platform/capabilities/codebase-context/). | | `/init` | Index the current codebase and generate an [AGENTS.md file](/agent-platform/capabilities/rules/). `*` | | `/model` | Switch the base agent model for the current conversation. | | `/new` | Start a new [agent conversation](/agent-platform/local-agents/interacting-with-agents/) (alias for `/agent`). | | `/open-code-review` | Open the [code review](/code/code-review/) pane. | | `/open-file` | Open a file for editing in Warp’s [code editor](/code/code-editor/). | | `/open-mcp-servers` | View the status of your [MCP servers](/agent-platform/capabilities/mcp/). | | `/open-project-rules` | Open the [Project Rules](/agent-platform/capabilities/rules/#project-rules) file (`AGENTS`). | | `/open-repo` | Switch to another indexed repository. | | `/open-rules` | View all of your global and project [rules](/agent-platform/capabilities/rules/). | | `/open-settings-file` | Open the Warp [settings file](/terminal/settings/) (`settings.toml`) in Warp’s code editor. | | `/open-skill` | Open an interactive menu to browse and edit project or global [skills](/agent-platform/capabilities/skills/). | | `/orchestrate` | Break a task into subtasks and run them in parallel with multiple agents. `*` | | `/plan` | Prompt the Agent to do some research and create a [plan](/agent-platform/capabilities/planning/) for a task. | | `/pr-comments` | Pull GitHub PR review comments into Warp. `*` | | `/profile` | Switch the active [execution profile](/agent-platform/capabilities/agent-profiles-permissions/). | | `/prompts` | Search saved [prompts](/knowledge-and-collaboration/warp-drive/prompts/). | | `/rename-tab` | Rename the current tab. Include the new tab name as an argument (for example, `/rename-tab deploy`). | | `/rewind` | Rewind to a previous point in the conversation. | | `/skills` | Invoke a [skill](/agent-platform/capabilities/skills/) from a searchable menu. | | `/usage` | Open [billing and usage](/support-and-community/plans-and-billing/) settings. | Caution Slash commands marked with a `*` consume credits to complete the task. #### Using Agent Prompts via Slash Commands [Section titled “Using Agent Prompts via Slash Commands”](#using-agent-prompts-via-slash-commands) In addition to static commands, the menu also shows [Agent Prompts](/knowledge-and-collaboration/warp-drive/prompts/) saved in your [Warp Drive](/knowledge-and-collaboration/warp-drive/). * These prompts can be custom ones you’ve created or ones shared with you. * As you type after `/`, prompts are filtered dynamically, so you can quickly run them without leaving the input field. ![Slash Commands menu with filtered Agent Prompts](/_astro/slash-commands-prompts.Bn4xWVZN_Z1f5gjc.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Slash Commands menu with filtered Agent Prompts. ### Tips [Section titled “Tips”](#tips) * **Context-aware:** Many Slash Commands use your current working directory or file selection as context. * **Quick access:** Use `/` from anywhere in Agent Mode or Auto-Detection Mode to avoid navigating through menus. ### Example of using a Slash Command [Section titled “Example of using a Slash Command”](#example-of-using-a-slash-command) Below is an example interaction when `/init` is run: ![/init setup flow; 1 of 2](/_astro/init-setup-flow-1.c74TFMjc_BTWl9.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The /init setup flow, step 1 of 2. ![/init setup flow; 2 of 2](/_astro/init-setup-flow-2.DLdfslFK_1WJ6ng.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The /init setup flow, step 2 of 2. # Agent Task Lists > Track and manage complex Agent workflows with automatic task lists that break requests into clear, actionable steps and update progress in real time. The Agent can automatically break down complex requests into clear, trackable steps in the form of a task list with to-do items.\ \ When you make a sufficiently complex request that requires multiple actions, the Agent will automatically create a list of steps, execute them in order, and track progress from start to finish. There’s no need to adjust settings or enable a special mode—the Agent detects and creates task lists automatically. ![An example of a task list in progress.](/_astro/in-progress-tasklist.tVkayooj_Zr9nDt.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) An example of a Task List in progress. ### How task lists work [Section titled “How task lists work”](#how-task-lists-work) 1. **Automatic task creation** — For complex requests, the Agent generates a structured list of tasks to complete. 2. **Step-by-step execution** — The Agent works through each task in sequence, updating statuses in real time. 3. **Summary** — Once all tasks are complete, the Agent provides a concise summary of what was done, including outputs, results, and relevant context. If any tasks were skipped or couldn’t be completed, it explains why. After each step is completed, there is also a completion marker in the Agent conversation. ![Completion markers inside the Agent conversation after each task is completed.](/_astro/completion-markers.CYm85oBi_1FVKGA.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Task completion markers in a conversation. ### Task statuses [Section titled “Task statuses”](#task-statuses) Each task in the list has a visual indicator so you can quickly see its progress. | Status | Icon | Meaning | | ------------ | ----------------- | ----------------------------------------------- | | Current task | ● (filled circle) | The Agent is actively working on this task. | | Completed | ✔︎ | The Agent has finished this task successfully. | | Not started | ○ (empty circle) | The task is in the queue but work hasn’t begun. | | Cancelled | ■ (filled square) | The task was stopped before completion. | ![Task list popup showing 4 of 6 tasks completed with status indicators for each step](/_astro/tasklist-small.BpVCyVk7_ywstd.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ### Task list access [Section titled “Task list access”](#task-list-access) During any Agent conversation, a task list chip appears at the bottom-right of the screen (when input is pinned to the bottom; otherwise, it may appear along the right side). * Click the chip to open the current task list. * You can collapse or expand the view at any time without interrupting the Agent. ![Access the task list during an Agent conversation in the task list chip in the conversation.](/_astro/tasklist-popup.CBqLxdEA_Q6uqL.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Task List chip in an agent conversation. # Agent web search > Warp’s web search lets agents pull in real-time information, documentation, and cited sources whenever it improves an answer. Warp includes native web search for models that support first-party search tools. When enabled, agents can look up information in real time, consult documentation, retrieve current version numbers, and cite the sources used to generate responses. This page covers how web search works, supported models, what you can expect inside Warp, configuration options, and how this differs from attaching URLs directly to a prompt. *** ### When the Agent uses web search [Section titled “When the Agent uses web search”](#when-the-agent-uses-web-search) Models initiate a web search when it improves the quality or accuracy of an answer. **Common scenarios include:** * Retrieving official documentation or API references * Getting the latest version of a library or tool * Checking error messages, GitHub issues, or StackOverflow discussions * Looking up ongoing incidents or recent changes * Answering questions where recency matters (e.g., “best approach in 2025 to…”) Web searches are automatically triggered when the model considers them useful. You don’t need special syntax. ### How web search works in Warp [Section titled “How web search works in Warp”](#how-web-search-works-in-warp) **When a search occurs:** 1. Warp shows a “Searching the web…” indicator inside the conversation. 2. You can expand the search result to view: * The query issued * The pages retrieved 3. **The model reads results and produces a grounded response.** * Claude models cite sources in the references footer. * OpenAI models use inline citations and also show references in the footer. ### Supported and unsupported models [Section titled “Supported and unsupported models”](#supported-and-unsupported-models) Web search is available only for models that offer a native web search integration, that works in tandem with other custom tools. **Models that support web search** * Anthropic: `Claude 4.6 Series`, `Claude 4.5 Series`, `Claude 4 Series` * OpenAI: * `GPT-5.4`, `GPT-5.3 Codex`, `GPT-5.2 Codex`, `GPT-5.2` Warp uses each vendor’s official tool: * **Claude Web Search**: * **OpenAI Web Search**: Note **Note**: We plan to add native web search for additional models as soon as their APIs fully support it. We’ll continue updating the list of search-capable models as vendors roll out broader tooling. We’re also exploring custom web search tools that’ll work across all models. ### Viewing search results [Section titled “Viewing search results”](#viewing-search-results) You can inspect the web search UI at any time: * Expand the **Web Search** section in the agent response * You can see: * The list of pages fetched * The text used to answer your question * Citations and reference metadata ![An agent conversation in Warp showing the expanded Web Search section with the query 'Stripe API latest version 2025' and a list of 10 retrieved URLs](/_astro/web-search-results.BQ5qKFCF_1IzQR5.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) This makes it easy to verify accuracy, audit reasoning, and validate sources. ### Enabling or disabling web search [Section titled “Enabling or disabling web search”](#enabling-or-disabling-web-search) Web search is controlled per [Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/). To configure: 1. In the Warp app, navigate to **Settings** > **Agents** > **Profiles**. 2. Next to the agent profile, click **Edit**. 3. Scroll to **Call web tools** and toggle the setting on or off. ![The Profiles page in Warp Settings, with the Profile Editor open and the Call web tools toggle enabled](/_astro/web-search-settings.Cfuogey-_Z1XeLi0.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Disabling this prevents the agent from performing searches, even if a model would normally use them. ### Credit usage [Section titled “Credit usage”](#credit-usage) Web search incurs two types of credit usage: 1. A small fixed cost per search invocation 2. Additional cost proportional to retrieved content, since retrieved text is passed to the model You’ll see these contributions itemized in the conversation’s credit usage footer, alongside model calls, planning calls, and other tool usage. # Claude Code in Warp > Set up Claude Code in Warp with full notification support, rich input, code review, and more. Claude Code is Anthropic’s agentic coding tool that operates directly in your terminal. It understands your codebase, executes commands, edits files, and manages Git workflows — all through natural language. For full documentation, see the [official Claude Code docs](https://code.claude.com/docs). Warp auto-detects Claude Code when you run it, giving you access to rich input controls, code review, agent notifications, and other integrated features. For a product overview, see [Claude Code in Warp](https://warp.dev/agents/claude-code). For installation, authentication, project configuration, and productivity tips, see the [How to set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) guide. ## Setting up notifications [Section titled “Setting up notifications”](#setting-up-notifications) Warp supports agent notifications for Claude Code through a plugin. Once installed, Warp surfaces in-app and desktop alerts when Claude Code needs your input — such as command approval, code review, or error intervention. ### Auto-install [Section titled “Auto-install”](#auto-install) Each time you run Claude Code in Warp without the notification plugin installed, a notification chip appears offering one-click installation. Click the chip to install the plugin automatically. After installation, Warp immediately starts receiving notifications from Claude Code. ### Manual install [Section titled “Manual install”](#manual-install) Note The notification plugin requires `jq`. Install it with your package manager (e.g., `brew install jq` on macOS) if it’s not already available. If the auto-install chip doesn’t appear or fails to install the plugin, install it manually. From inside Claude Code, run: ```bash /plugin marketplace add warpdotdev/claude-code-warp /plugin install warp@claude-code-warp ``` Or from your terminal (outside of Claude Code): ```bash claude plugin marketplace add warpdotdev/claude-code-warp claude plugin install warp@claude-code-warp ``` After installing, restart Claude Code or run `/reload-plugins` to activate the plugin. Note If installation fails or you have an outdated version of the plugin, remove it first with `claude plugin marketplace remove claude-code-warp`, then re-run the install commands above. ### Installation instructions banner [Section titled “Installation instructions banner”](#installation-instructions-banner) If the auto-install chip doesn’t work, or if you’re running Claude Code over SSH or on a remote machine, Warp displays an installation instructions banner directly in the terminal. The banner shows step-by-step commands that you can run in place — no need to switch between tabs or copy-paste from external documentation. For plugin source and updates, see the [claude-code-warp GitHub repository](https://github.com/warpdotdev/claude-code-warp). ## Supported Warp features [Section titled “Supported Warp features”](#supported-warp-features) Claude Code supports the full set of Warp’s agent integration features: * **Agent notifications** - Receive in-app and desktop alerts when Claude Code needs your attention. The notification UI displays your current git branch alongside agent status. * **Rich input editor** - Press `Ctrl-G` to open an expanded input editor for composing longer prompts. * **Code review** - Send inline review comments directly to the agent from Warp’s code review panel. * **Attach code as context** - Select code and send it to the agent as context. * **Vertical tabs with agent metadata** - Monitor Claude Code sessions with status indicators in Warp’s tab bar. * **Tab Configs** - Save and restore Claude Code session configurations. * **Remote Control** - Share your Claude Code session with teammates via session sharing. ## Related pages [Section titled “Related pages”](#related-pages) * [How to set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) — step-by-step setup guide * [Claude Code in Warp](https://warp.dev/agents/claude-code) — product overview * [Third-Party CLI Agents Overview](/agent-platform/cli-agents/overview/) * [OpenCode](/agent-platform/cli-agents/opencode/) * [Codex](/agent-platform/cli-agents/codex/) # Codex CLI in Warp > Set up Codex in Warp with notification support, rich input, code review, and more. Codex is OpenAI’s open-source coding agent that runs in your terminal. It can write and edit code, execute commands, and navigate your codebase through natural language. For full documentation, see the [Codex GitHub repository](https://github.com/openai/codex). Warp auto-detects Codex when you run it, giving you access to rich input controls, code review, and other integrated features. For a product overview, see [Codex in Warp](https://warp.dev/agents/codex). For installation, authentication, project configuration, and productivity tips, see the [How to set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) guide. ## Setting up notifications [Section titled “Setting up notifications”](#setting-up-notifications) Codex supports native notifications that Warp surfaces as in-app and desktop alerts — such as when Codex completes a task, encounters an error, or needs your input. First, update Codex to the latest version — support for this setting was recently added. See the [Codex upgrade instructions](https://developers.openai.com/codex/cli#upgrade). Then add the following to `~/.codex/config.toml`: ```toml [tui] notification_condition = "always" ``` Then restart Codex. If this config isn’t set, Warp displays a setup chip in the terminal with instructions you can follow directly. ## Supported Warp features [Section titled “Supported Warp features”](#supported-warp-features) Codex supports the full set of Warp’s agent integration features: * **Agent notifications** - Receive in-app and desktop alerts when Codex needs your attention. Requires a one-time config change (see [Setting up notifications](#setting-up-notifications)). * **Rich input editor** - Press `Ctrl-G` to open an expanded input editor for composing longer prompts. * **Code review** - Send inline review comments directly to the agent from Warp’s code review panel. * **Attach code as context** - Select code and send it to the agent as context. * **Vertical tabs with agent metadata** - Monitor Codex sessions with status indicators in Warp’s tab bar. * **Tab Configs** - Save and restore Codex session configurations. * **Remote Control** - Share your Codex session with teammates via session sharing. ## Related pages [Section titled “Related pages”](#related-pages) * [How to set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) — step-by-step setup guide * [Codex in Warp](https://warp.dev/agents/codex) — product overview * [Third-Party CLI Agents Overview](/agent-platform/cli-agents/overview/) * [Claude Code](/agent-platform/cli-agents/claude-code/) * [OpenCode](/agent-platform/cli-agents/opencode/) # OpenCode in Warp > Set up OpenCode in Warp with notification support, rich input, code review, and more. OpenCode is an open-source terminal-based coding agent. It connects to multiple LLM providers and supports tool use, file editing, and command execution from your terminal. For full documentation, see the [OpenCode docs](https://opencode.ai/docs). Warp auto-detects OpenCode when you run it, giving you access to rich input controls, code review, agent notifications, and other integrated features. For a product overview, see [OpenCode in Warp](https://warp.dev/agents/opencode). For installation, authentication, project configuration, and productivity tips, see the [How to set up OpenCode](/guides/external-tools/how-to-set-up-opencode/) guide. ## Setting up notifications [Section titled “Setting up notifications”](#setting-up-notifications) Warp supports agent notifications for OpenCode through a plugin. Once installed, Warp surfaces in-app and desktop alerts when OpenCode needs your input. To set up the plugin, add `"@warp-dot-dev/opencode-warp"` to the `plugin` array in your `opencode.json` configuration file: ```json { "plugin": ["@warp-dot-dev/opencode-warp"] } ``` If the plugin isn’t installed, Warp displays an installation chip in the terminal when you run OpenCode, with setup steps you can follow directly. For plugin source and updates, see the [opencode-warp GitHub repository](https://github.com/warpdotdev/opencode-warp). ## Supported Warp features [Section titled “Supported Warp features”](#supported-warp-features) OpenCode supports the full set of Warp’s agent integration features: * **Agent notifications** - Receive in-app and desktop alerts when OpenCode needs your attention. The notification UI displays your current git branch alongside agent status. * **Rich input editor** - Press `Ctrl-G` to open an expanded input editor for composing longer prompts. * **Code review** - Send inline review comments directly to the agent from Warp’s code review panel. * **Attach code as context** - Select code and send it to the agent as context. * **Vertical tabs with agent metadata** - Monitor OpenCode sessions with status indicators in Warp’s tab bar. * **Tab Configs** - Save and restore OpenCode session configurations. * **Remote Control** - Share your OpenCode session with teammates via session sharing. ## Related pages [Section titled “Related pages”](#related-pages) * [How to set up OpenCode](/guides/external-tools/how-to-set-up-opencode/) — step-by-step setup guide * [OpenCode in Warp](https://warp.dev/agents/opencode) — product overview * [Third-Party CLI Agents Overview](/agent-platform/cli-agents/overview/) * [Claude Code](/agent-platform/cli-agents/claude-code/) * [Codex](/agent-platform/cli-agents/codex/) # Third-party CLI agents overview > Warp provides first-class support for third-party CLI coding agents with a rich input editor, notifications, code review, and more. Warp auto-detects supported CLI agents and enhances them with IDE-level features — a rich input editor, agent notifications, inline code review, remote session control, and more. Run your preferred coding agent inside Warp and get a better experience out of the box. This feature set is also known as **universal agent support**. ## Supported agents [Section titled “Supported agents”](#supported-agents) Warp currently supports the following CLI coding agents: * [**Claude Code**](/agent-platform/cli-agents/claude-code/) — Anthropic’s CLI coding agent * [**OpenAI Codex**](/agent-platform/cli-agents/codex/) — OpenAI’s CLI coding agent * [**OpenCode**](/agent-platform/cli-agents/opencode/) — Open-source CLI coding agent * **Amp** — Sourcegraph’s CLI coding agent * **Auggie** — Augment Code’s CLI coding agent * **Copilot CLI** — GitHub’s CLI coding agent * **Cursor CLI** — Cursor’s CLI coding agent * **Gemini CLI** — Google’s CLI coding agent * **Droid** — Factory’s CLI coding agent * **Pi** — Open-source CLI coding agent When you launch a supported agent inside Warp, the **agent toolbelt** appears automatically, giving you quick access to Warp’s enhanced features. ![The agent toolbelt appearing at the bottom of the pane when a supported CLI agent is running in Warp](/_astro/cli-agent-toolbelt.obz1DjuN_Z1WBmOA.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The agent toolbelt for CLI agents. ## Feature support [Section titled “Feature support”](#feature-support) Not every feature is available for every agent. The table below shows current support. | Feature | Claude Code | Codex | OpenCode | Amp | Auggie | Copilot CLI | Cursor | Gemini CLI | Droid | Pi | | ------------------------------------- | ----------- | ----- | -------- | --- | ------ | ----------- | ------ | ---------- | ----- | -- | | Rich input editor (`Ctrl-G`) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Agent notifications | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | | Code review comments | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Attach code as context | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Vertical tabs + metadata | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Tab Configs | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | Remote Control | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | Note Agent notifications require a one-time setup. Claude Code and OpenCode use a Warp notification plugin. Codex uses a native config change. See the individual agent pages for setup instructions. Amp, Auggie, Copilot CLI, Cursor, Gemini CLI, Droid, and Pi don’t support notifications yet. ## Customizing the toolbelt [Section titled “Customizing the toolbelt”](#customizing-the-toolbelt) The chips and buttons on the CLI agent toolbelt can be reordered, hidden, or moved between the left and right sides. Your layout is saved and persists across app restarts. In the Warp app, open the **Edit CLI agent toolbelt** modal in one of two ways: * Right-click the input area while a supported CLI coding agent is running and select **Edit CLI agent toolbelt**. * Go to **Settings** > **Agents** > **Third party CLI agents**, then click the **Toolbar layout** preview. ## Getting started [Section titled “Getting started”](#getting-started) Run a supported agent inside Warp — that’s it. Warp detects the agent automatically and activates the agent toolbelt with all available features. For **agent notifications**, each agent requires a one-time setup — either a notification plugin or a config change. See the individual agent pages for instructions. Note If you don’t see the agent toolbelt, make sure you’re on the latest version of Warp. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Agent Notifications](/agent-platform/capabilities/agent-notifications/) * [Tabs](/terminal/windows/tabs/) * [Tab Configs](/terminal/windows/tab-configs/) # Remote Control > Publish any third-party agent session to the cloud so you can monitor progress, steer the agent, and check in from your phone or another computer. Remote Control lets you publish a running third-party agent session — such as Claude Code, Codex, or OpenCode — to the cloud with a single click. Once published, you can monitor progress, review output, and steer the agent from your phone, a web browser, or another computer without staying at the original machine. See [Third-Party CLI Agents](/agent-platform/cli-agents/overview/) for the full list of supported agents. This is especially useful for long-running agent tasks. Start a coding agent, publish the session, and check back whenever you want. Note Remote Control is built on top of [Agent Session Sharing](/agent-platform/local-agents/session-sharing/). It uses the same underlying infrastructure to publish sessions and generate shareable links. ## Key capabilities [Section titled “Key capabilities”](#key-capabilities) * **One-click publish** - Click the `/remote-control` chip in the agent utility bar to publish instantly. The shareable link is copied to your clipboard automatically. * **Monitor from anywhere** - Check on agent progress from a phone, tablet, or another computer — no install required for web viewers * **Steer remotely** - Send input, approve commands, or redirect the agent without being at your original machine * **Team access** - Share the link with teammates so they can observe or collaborate on the session * **Persistent cloud access** - The session stays in sync while it’s active. New agent output and terminal activity appear for all viewers in real time. Syncing stops when you close or stop publishing the session. ## How it works [Section titled “How it works”](#how-it-works) When you publish a session through Remote Control, Warp uploads the session state to the cloud and generates a shareable link. The link stays live and in sync — any new agent output, tool use, or terminal activity appears for all connected viewers in real time. You control who can view and who can steer the agent. Remote Control differs from standard [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) in its intent: Session Sharing is designed for live collaborative work (pair-programming, interactive debugging), while Remote Control is designed for async monitoring and steering when you’re away from your machine. ## Publishing a session [Section titled “Publishing a session”](#publishing-a-session) 1. Start or resume a third-party agent session in Warp (for example, Claude Code or Codex). 2. Click the **`/remote-control`** chip in the agent utility bar. Warp publishes the session to the cloud and copies the shareable link to your clipboard. ![The /remote-control chip in the agent utility bar with a Start remote control tooltip](/_astro/remote-control.DBEQ99hf_uHHYJ.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The /remote-control chip in the agent utility bar. 3. A **Sharing link copied** toast notification confirms the link is on your clipboard, and the pane’s status icon changes to a red broadcast indicator to show that publishing is active. 4. Open the link on another device, or share it with a teammate. To stop publishing, click the **Stop sharing** button in the agent utility bar. The status icon returns to its normal state, confirming the session is no longer accessible remotely. ## Accessing a remote session [Section titled “Accessing a remote session”](#accessing-a-remote-session) Published sessions are accessible from: * **Web browser** - Open the shared link in any browser. No app install required. * **Warp desktop app** - Paste the link into Warp on a different machine for the full desktop experience * **Mobile** - Open the link on your phone or tablet browser to check on progress while away from your desk The web experience mirrors the desktop view, showing complete agent activity including thinking steps, tool use, and terminal output. ## Permissions [Section titled “Permissions”](#permissions) When you publish a session, you control access: * **View access** - Anyone with the link can watch the session, see agent output, and review terminal activity * **Edit access** - You can grant viewers permission to send input, approve commands, or redirect the agent Only you (the publisher) can revoke access or stop publishing the session. ## Related pages [Section titled “Related pages”](#related-pages) * [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) * [Third-Party CLI Agents](/agent-platform/cli-agents/overview/) * [Viewing Cloud Agent Runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) # Rich input editor > Warp's rich input editor gives you IDE-style editing, voice input, context attachment, and slash commands for any supported CLI coding agent. Warp’s rich input editor lets you write prompts for any CLI coding agent with the same editing experience you’d expect from an IDE — mouse support, context attachment, voice, and more. Press `Ctrl-G` (configurable) or click the **Rich Input** button in the agent utility bar to open it. ## Key capabilities [Section titled “Key capabilities”](#key-capabilities) * **IDE-style editing** - Click, select, and navigate your prompt with your mouse. Copy, cut, paste, undo, and word-level navigation all work. Write multi-line prompts with line breaks and soft wrapping. Vim keybindings are also supported. See [Modern text editing](/terminal/editor/) for the full list of shortcuts. * **Rich context with @mentions** - Reference files, folders, and code symbols with `@` mentions. Attach images for visual context. Search for specific symbols directly from the editor. See [Agent Context](/agent-platform/local-agents/agent-context/) for details. * **Voice input** - Dictate prompts instead of typing. See [Voice](/agent-platform/local-agents/interacting-with-agents/voice/) for details. * **Slash commands and skills** - Access saved `/prompts`, `/skills`, and [Warp Drive](/knowledge-and-collaboration/warp-drive/) content with `/`. The editor shows skills specific to the running agent’s provider (e.g., Claude-specific skills when running Claude Code). See [Slash Commands](/agent-platform/capabilities/slash-commands/) for details. * **Agent toolbar** - Browse files, view code changes, and manage the agent session from the toolbar. ## How to open [Section titled “How to open”](#how-to-open) There are two ways to open the rich input editor: 1. **Keyboard shortcut** - Press `Ctrl-G` (configurable) while a supported agent is running in the active pane. 2. **Rich Input button** - Click the **Rich Input** button in the agent utility bar at the bottom of the pane. ![The Rich Input button in the agent utility bar at the bottom of the pane](/_astro/rich-input-button.DUcuw3Dt_W4fF4.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Rich Input button in the agent utility bar. The rich input editor also auto-opens when an agent resumes from a blocked state (for example, after you approve a command). This requires the agent’s plugin to be supported and installed. Toggle **Auto show/hide based on agent status** in [Rich input settings](#rich-input-settings) to control this behavior. When the rich input editor is active, Warp hides the cursor inside the CLI agent and moves focus to the editor input. Submit your prompt from here and it goes directly to the running agent. ![The rich input editor open with a prompt being composed](/_astro/rich-input-prompt.Diz79TGU_Z1W2xjT.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The rich input editor. ## Rich input settings [Section titled “Rich input settings”](#rich-input-settings) In the Warp app, go to **Settings** > **Agents** > **Third party CLI agents** to configure the following: * **Auto show/hide based on agent status** - Automatically open the rich input editor when the agent needs input, and hide it when the agent is working. Works with agents that have plugin support and the plugin installed (Claude Code and OpenCode). * **Auto open on session start** - Automatically open the rich input editor when a CLI agent session starts. * **Auto dismiss after submission** - Close the editor after you send a prompt. * **Keyboard shortcut** - The default shortcut is `Ctrl-G`. Customize this in **Settings** > **Keyboard shortcuts**. * **Disable the Rich Input button** - Right-click the agent utility bar and remove the **Rich Input** chip, or disable the footer entirely in **Settings** > **Agents** > **Third party CLI agents**. ![Rich input settings panel](/_astro/rich-input-settings.DqFl5P-r_Z1YznsU.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Rich input settings in Warp. ## Related pages [Section titled “Related pages”](#related-pages) * [Third-Party CLI Agents Overview](/agent-platform/cli-agents/overview/) * [Remote Control](/agent-platform/cli-agents/remote-control/) * [Voice](/agent-platform/local-agents/interacting-with-agents/voice/) * [Slash Commands](/agent-platform/capabilities/slash-commands/) * [Agent Context](/agent-platform/local-agents/agent-context/) # Deployment Patterns > Common architectures for deploying cloud agents, including CLI-only, Oz-hosted, and self-hosted execution patterns. Teams adopt cloud agents in a few repeatable ways. This page outlines the most common architectures, what they’re good for, and how they fit together. #### Quick mental model [Section titled “Quick mental model”](#quick-mental-model) Oz cloud agent setups usually have four moving parts: 1. **Trigger**: something happens (CI step, webhook, cron, Slack mention). 2. **Orchestration**: something decides what to run and tracks it (Oz orchestrator, GitHub Actions, your internal system). 3. **Execution**: where the agent actually runs (your runner, Oz-hosted environment, or self-hosted workers). 4. **Visibility**: how the team monitors and intervenes (Oz dashboard, session sharing, APIs). *** ### Pattern 1: CLI-only agents (bring your own orchestrator) [Section titled “Pattern 1: CLI-only agents (bring your own orchestrator)”](#pattern-1-cli-only-agents-bring-your-own-orchestrator) Use this when you already have a system that schedules work (CI, dev boxes, internal orchestrators), and you just need a reliable, cloud-connected agent runner. #### What it looks like [Section titled “What it looks like”](#what-it-looks-like) * **Trigger**: GitHub Actions / CI, a script, a dev box action, or an internal orchestrator * **Orchestration**: your existing system * **Execution**: wherever that system runs * **Warp adds**: cloud connectivity, shared context, visibility, session sharing, and tracking #### Why teams choose it [Section titled “Why teams choose it”](#why-teams-choose-it) * You want a **drop-in replacement** for other CLI/SDK-based agents (Claude Code, Codex CLI, Gemini CLI/SDK-style flows). * You want to run agents anywhere without requiring Warp desktop. * You still want **team-level observability** even when execution is “outside Warp.” #### Common examples [Section titled “Common examples”](#common-examples) * **CI PR helper**: run formatting checks, generate review comments, suggest fixes, open PRs. * **Remote dev box agent**: run refactors or debugging tasks inside a pre-provisioned box. * **Internal orchestrator integration**: treat Warp as one agent option alongside other model providers. #### What you still get even without Warp orchestration [Section titled “What you still get even without Warp orchestration”](#what-you-still-get-even-without-warp-orchestration) * Access to your shared Warp context (for example MCP config, Warp Drive context, rules/prompts). * Agent Session Sharing to monitor/steer runs. * Read-only APIs for tracking and reporting. * A path to “handoff” workflows (where a run can be continued or inspected in richer surfaces). #### Minimal setup checklist [Section titled “Minimal setup checklist”](#minimal-setup-checklist) * A Warp team * A service account (recommended for automation) * The Oz CLI installed on the runner / box * Any needed credentials (often via secrets + environment variables) *** ### Pattern 2: Oz-hosted agents + Oz orchestration (managed cloud execution) [Section titled “Pattern 2: Oz-hosted agents + Oz orchestration (managed cloud execution)”](#pattern-2-oz-hosted-agents--oz-orchestration-managed-cloud-execution) Use this when you want Oz to run agent workloads on Warp-managed infrastructure, typically inside reproducible Docker environments, with built-in lifecycle management. ![Warp enterprise SaaS architecture showing customer infrastructure, isolated tenant sandboxes, Warp backend, and LLM providers](/_astro/cloud-agents-infra.BjJiuNhi_2afLhC.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### What it looks like [Section titled “What it looks like”](#what-it-looks-like-1) * **Trigger**: first-party integrations, cron schedules, API/SDK calls, or on-demand commands * **Orchestration**: Oz orchestrator * **Execution**: Oz-hosted environments (Docker-based) * **Visibility**: Oz dashboard + session sharing + APIs/SDKs #### Why teams choose it [Section titled “Why teams choose it”](#why-teams-choose-it-1) * You want the simplest path to reproducible, scalable cloud execution. * You want to run many tasks in parallel without building your own sandboxing and scaling layer. * You want a consistent “production” setup with standardized environments and centralized configuration. #### Common ways to trigger [Section titled “Common ways to trigger”](#common-ways-to-trigger) * **First-party integrations (Slack, Linear, etc.)** that create tasks automatically from external events. * **Scheduled agents** for recurring work (cron-like automation). * **Custom triggers** from your own systems using Warp’s API/SDK. * **On-demand cloud jobs** using CLI commands like oz agent run-cloud. #### Example recipe: daily dead-code cleanup [Section titled “Example recipe: daily dead-code cleanup”](#example-recipe-daily-dead-code-cleanup) 1. Define an Oz Environment with the repo + toolchain. 2. Create a schedule with a fixed prompt for cleanup. 3. Oz runs the agent on the cadence. 4. Your team monitors runs in the Oz dashboard, reviews artifacts (PRs, plans), and intervenes when needed. #### Example recipe: crash triage via Sentry webhook [Section titled “Example recipe: crash triage via Sentry webhook”](#example-recipe-crash-triage-via-sentry-webhook) 1. Define an Oz Environment with the target repo. 2. Register a Sentry webhook to your handler (server, cloud function, Zapier/n8n). 3. Handler extracts crash details, constructs a prompt, and calls the Oz orchestrator API/SDK to start a task. 4. Warp spins up the run in the environment and you monitor progress via UI/API. #### Example recipe: fan-out parallel work (sharding) [Section titled “Example recipe: fan-out parallel work (sharding)”](#example-recipe-fan-out-parallel-work-sharding) If a task is naturally divisible: * Launch multiple cloud agents via oz agent run-cloud, each with: * A shard of the repo (directory/module ownership) * A shard of the prompt (one responsibility) * Aggregate results (PRs, notes, plans) in whatever system you prefer. #### Example recipe: same task across multiple models [Section titled “Example recipe: same task across multiple models”](#example-recipe-same-task-across-multiple-models) * Launch N runs with the same prompt, but different profiles that map to different models. * Compare results and choose the best output (or merge). *** ### Pattern 3: Self-hosted execution [Section titled “Pattern 3: Self-hosted execution”](#pattern-3-self-hosted-execution) Use this when you need to control where agent execution happens while still using Oz orchestration and visibility. Repositories are cloned and stored only on your infrastructure; orchestration metadata, session transcripts, and LLM inference route through Warp’s backend under [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr). Note **Enterprise feature**: Self-hosted execution is available exclusively to teams on an Enterprise plan. Self-hosting has two architectures that differ on **who orchestrates agent runs** (both keep code and execution on your infrastructure): * **[Managed](/agent-platform/cloud-agents/self-hosting/#managed-architecture)** — Oz orchestrates. You run the `oz-agent-worker` daemon; Oz routes runs to it from Slack, Linear, schedules, the API, or `oz agent run-cloud`. Tasks execute in Docker containers, Kubernetes Jobs, or directly on the host. * **[Unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/)** — You orchestrate. Invoke `oz agent run` directly from your CI, Kubernetes, or dev environment. Warp provides session tracking and observability; it does not start or stop agents. Why teams choose self-hosted execution: * Code and execution must stay within your network boundary for compliance or security requirements. * Agents need to access services behind a VPN or self-hosted SCMs like GitLab or Bitbucket. Warp-hosted agents can also access GitLab and Bitbucket over the public internet — see the [GitLab](/agent-platform/cloud-agents/integrations/gitlab/) and [Bitbucket](/agent-platform/cloud-agents/integrations/bitbucket/) setup guides. * Your environments (multi-service stacks, heavy resource requirements) don’t fit in a single Docker container. For setup, decision guides, and a quickstart, start with [Self-hosting](/agent-platform/cloud-agents/self-hosting/). # Cloud agent environments > Environments ensure your cloud agents run with consistent toolchains across all triggers. Learn when to use environments and how to configure them. Environments ensure your [cloud agents](/agent-platform/cloud-agents/overview/) run with the same toolchain and setup every time, regardless of where they’re triggered from. An environment defines the execution context for automated agent runs: the **Docker image**, **repositories to clone**, **setup commands**, and **runtime configuration** Warp uses to prepare the workspace before the agent starts. Note You often don’t need an environment for interactive local runs where you’re already in a working checkout and relying on your existing machine setup. ## Key features [Section titled “Key features”](#key-features) What environments give you: * **Consistent behavior across triggers** – A workflow triggered from Slack behaves identically to one run from Linear or the CLI, using the same toolchain and setup steps every time. * **One configuration, many uses** – Define your Docker image and setup once, then reuse it across triggers and hosts without duplicating configuration. * **Full visibility into runs** – Inspect the image, repos, and commands used by a run, making it easy to debug failures or reproduce results. Note Don’t want to bring your own image? Warp provides [prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments) with common languages and tools pre-installed. ## About environments [Section titled “About environments”](#about-environments) Environments define *how* an agent runs, not *what* it does. They’re required for [Oz Platform](/agent-platform/cloud-agents/platform/) automation (cloud agents, integrations, API runs) but are not required for interactive local usage. An environment typically includes: * **Docker image (required)** – The toolchain and runtime the agent runs with. For self-hosted Kubernetes workers, a [`default_image`](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/) on the worker lets you skip creating an environment entirely. * **Repository/workspace** – One or more repos the agent can clone and operate on. * **Setup commands** – Commands to prepare the workspace (e.g., dependency install, builds, bootstrapping). Note Configuring runtime settings: * **Environment variables**: Configure these in your Dockerfile using Docker’s \`ENV\` directives or pass them when running the container. * **Secrets**: For credentials and sensitive data, use [Agent Secrets](/agent-platform/cloud-agents/secrets/). These are configured separately from environments and injected securely at runtime. What an environment is not: * Host – Hosts determine where execution happens (Warp-hosted vs. self-hosted infrastructure). * [Agent Profile](/agent-platform/capabilities/agent-profiles-permissions/) – Profiles control agent behavior like permissions, model choice, and defaults, not the runtime environment. * [Rules](/agent-platform/capabilities/rules/) – Rules determine agent responses and decisions but don’t define the container or toolchain. * [MCP Servers](/agent-platform/cloud-agents/mcp/) – connect agents to external tools and data via MCP. * Per-run context – Trigger-specific data like Slack threads, PR metadata, or CI logs attach to individual tasks, not the environment configuration. ## How environments fit into the Oz Platform [Section titled “How environments fit into the Oz Platform”](#how-environments-fit-into-the-oz-platform) An environment is the runtime layer for automated Oz Platform runs. It defines the container image, repos, and setup steps used when a trigger kicks off an agent task. Components in the execution flow: 1. **Trigger** – An event starts work (Slack mention, Linear comment, CI event, API call) 2. **Task** – Warp creates a tracked task for the run 3. **Environment** – The task uses an environment to define execution context 4. **Host** – The environment runs on a host (Warp-hosted or self-hosted infrastructure). 5. **Agent execution** – The workflow runs in the prepared environment 6. **Outputs** – The run produces PRs, messages, reports, or transcripts Note **Local agent** runs (using `oz agent run`) don’t require an environment. These runs use your current machine’s setup. Environments are required for **automated platform** runs like Oz cloud agents and integrations ### Hosts and environments [Section titled “Hosts and environments”](#hosts-and-environments) While environments define *how* an agent runs, hosts determine *where* the environment executes. Host options: * **Warp-hosted (default)** – Warp provides the infrastructure. Best for most users who want hands-off execution. * **[Self-hosted](/agent-platform/cloud-agents/self-hosting/)** – You provide the infrastructure (runners in your cloud or network). Best for compliance requirements, on-premise execution, or custom hardware needs. * Local (coming soon) – Run environments on your local machine for sandbox development and testing. The same environment can run on different hosts with identical behavior. For more details on hosting options, see [Deployment Patterns](/agent-platform/cloud-agents/deployment-patterns/) and [execution hosts](/agent-platform/cloud-agents/platform/#execution-hosts). ### What happens at runtime [Section titled “What happens at runtime”](#what-happens-at-runtime) When you trigger an agent, Warp follows this process: 1. **Warp receives the trigger.** Warp captures the message content (Slack thread, Linear issue) and any linked context. 2. **Warp creates an execution environment.** Warp spins up an isolated execution context from the Docker image defined in your environment. 3. **Repositories are cloned.** GitHub repositories associated with the environment are cloned into the container. 4. **Setup commands run.** Configured setup commands execute (installing dependencies, running builds, etc.) 5. **The agent workflow runs.** The agent executes the task using the provided context, tools, and permissions. 6. **Results are posted back.** Progress updates, summaries, and results post to the trigger source (Slack, Linear, etc.), or are available in the task transcript. 7. **The container is destroyed.** After completion, the container is torn down. Each run starts from a clean, isolated environment. This process ensures every run starts from the same baseline, making results reproducible and debugging straightforward. *** ## When to use environments [Section titled “When to use environments”](#when-to-use-environments) Use an environment when your run needs a predictable toolchain and repeatable setup, regardless of where it’s triggered from. * **Integrations and schedules** – Use an environment when runs start from Slack, Linear, GitHub Actions, schedules, or other integrations, and you need consistent behavior each time. * **CI and remote automation** – Use an environment when the host isn’t consistent (e.g., different runners, varying base images). * **Team standardization** – Use an environment when you want everyone’s automation runs to use the same image, repos, and setup steps. * **Toolchain-specific workflows** – Use an environment when the workflow depends on specific language versions, linters, build tools, or system packages. **When you can skip an environment** You often don’t need an environment for interactive local runs where you’re already in a working checkout and relying on your existing machine setup. **Decision checklist** Choose an environment if any of the following apply: * Runs must be consistent across triggers/hosts. The workflow should behave the same regardless of where it is triggered from. * The toolchain must be fixed. You need a known image and deterministic setup steps to avoid “it works on my machine” drift. * The workflow is shared across a team. Multiple people, or systems, will run the workflow and expect repeatable results. **Example:** If your team tags @Oz in Slack to fix a failing CI job, an environment ensures every run uses the same Docker image, clones the same repos, and runs the same setup commands. The fix the agent applies matches what runs in CI and what your teammates see when they review the PR. ### Where to configure environments [Section titled “Where to configure environments”](#where-to-configure-environments) You can create and configure environments with Warp’s guided setup, or through the CLI. Use the guided flow when you’re first getting started, and use the CLI when you want full control or need to automate environment creation. **Before you begin** Make sure you have: * One or more GitHub repositories that the agent should clone and work in. * **GitHub authorization configured** so the agent can access your repos. For user-triggered runs, each user authorizes GitHub individually. For automated workflows using team API keys, configure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) in the Admin Panel. * A publicly-accessible Docker image that can build and run your code. Official images like [node](https://hub.docker.com/_/node), [python](https://hub.docker.com/_/python), or [rust](https://hub.docker.com/_/rust) work for many projects. You can also use one of [Warp’s prebuilt dev images](https://github.com/warpdotdev/oz-dev-environments). Caution Musl-based Docker images (such as Alpine Linux) are not supported. The agent runtime requires glibc. Use glibc-based images like Debian, Ubuntu, or the default (non-Alpine) variants of official Docker Hub images. Note Create one environment per codebase, then reuse it across triggers like Slack, Linear, and CLI runs. ![Creating a new environment in the Oz Web App.](/_astro/oz-web-app-new-environment.6oAOc_HQ_1qTc4a.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Creating a new environment in the Oz web app. ### Create an environment with guided setup (recommended) [Section titled “Create an environment with guided setup (recommended)”](#create-an-environment-with-guided-setup-recommended) Use [`/create-environment`](warp://action/create_environment) when you want Warp to inspect your repos and recommend an environment configuration automatically. This is the fastest way to get started: Warp detects your languages, frameworks, and tools, then suggests appropriate images and setup commands. You can run the command inside a Git repo directory with no argument, or with one or more repo paths or URLs. owner/repo ```shellscript # Local file paths /create-environment ./warp-internal ./warp-server /create-environment warpdotdev/warp-internal warpdotdev/warp-server # GitHub URLs /create-environment https://github.com/warpdotdev/warp-internal.git ``` Warp will: * Detect the repositories you want the agent to work with and identify languages, frameworks, and tools * Look for an existing Dockerfile, recommend an official base image, or help build a custom image (if needed) * Suggest setup commands based on your scripts and package managers * Create the environment through the CLI and return an `environment ID` This produces a ready-to-use environment that can immediately be connected to integrations and cloud agents. ### Create an environment with the CLI [Section titled “Create an environment with the CLI”](#create-an-environment-with-the-cli) Use the CLI when you already know how you want to configure your environment, you have a custom Docker image you want to use, or when you’re automating environment creation. ```sh oz environment create \ --name \ --docker-image \ --repo \ --repo \ --setup-command "" \ --setup-command "" \ --description "Optional description" ``` Key flags: * `--name` (`-n`) — human-readable label for the environment. * `--docker-image` (`-d`) — image name on Docker Hub. If not specified, you’ll be prompted to select from available images (see `oz environment image list`). * `--repo` (`-r`) — repo to clone (repeatable). * `--setup-command` (`-c`) — commands run in the order provided (repeatable). * `--description` — optional description (max 240 characters). *** ## Managing environments [Section titled “Managing environments”](#managing-environments) Once created, you can use the [Oz CLI](/reference/cli/) to inspect and update environments. **List environments** ```sh oz environment list ``` **View an environment’s configuration.** Replace \ with the ID of the environment you want to view. ```sh oz environment get ``` **Update an environment** Add/remove repos, setup commands, and other properties without recreating the environment. Replace \ with the ID of the environment you want to modify. ```sh # Add a repo oz environment update --repo owner/repo # Remove a repo oz environment update --remove-repo owner/repo # Add a setup command oz environment update --setup-command "your command" # Remove a setup command (must match exactly) oz environment update --remove-setup-command "exact command" # Update the name, description, or Docker image oz environment update --name "new name" oz environment update --description "Updated description" oz environment update --docker-image node:22 ``` Additional flags: * `--remove-description` — clear the description. * `--force` — skip confirmation checks for environments used by integrations. **Delete an environment.** Replace \ with the ID of the environment you want to delete. ```sh oz environment delete ``` Add `--force` to skip confirmation checks for environments used by integrations. Note For end-to-end setup, see the [Integration setup](/reference/cli/integration-setup/) guide. *** ## Environment design and best practices [Section titled “Environment design and best practices”](#environment-design-and-best-practices) A well-designed environment removes guesswork by giving every run the same starting conditions. When an agent opens a PR from Slack or fixes a failed CI job, the result matches what your team can reproduce locally and in CI. **Design guidelines** * **Keep setup repeatable** – Write setup steps that are safe to rerun and that produce the same toolchain and workspace state for a given repo revision. This keeps agent runs reliable across triggers and hosts. * **Pin versions in the toolchain** – Prefer a Docker or base image that pins language runtimes and core tools, then use lockfiles (\`package-lock.json\`, etc.) for dependencies. * **Define a clear workspace boundary** – In multi-repo environments, explicitly state which repos are cloned and where setup commands run so the agent doesn’t “guess” the working directory. * **Make prerequisites explicit** – If the agent must run a build step, generate code, or install system packages before it can do meaningful work, encode that as setup. **Example setup commands** ```sh # Safer patterns (repeatable and stable) mkdir -p .cache npm ci # Less safe patterns (can fail on rerun or drift over time) mkdir .cache npm install ``` Note If your setup commands depend on secrets or credentials, configure them through Warp’s [secrets mechanism](/agent-platform/cloud-agents/secrets/) rather than hardcoding tokens. ### Common issues [Section titled “Common issues”](#common-issues) * **Setup assumes previous state** – Steps that rely on leftover caches, existing directories, or already-cloned repos can make runs unreliable. * Solution: Write idempotent setup commands that work on a fresh container. * **Missing credentials or secrets** – Builds fail when private repos, package registries, or external services require authorization. * Solution: Configure credentials with [Agent Secrets](/agent-platform/cloud-agents/secrets/). * **Repo access and GitHub authorization issues** – Runs fail when GitHub doesn’t have repo access or the triggering user lacks permissions. * Solution: See [Integration setup](/reference/cli/integration-setup/#how-github-authorization-works) for GitHub authorization setup. * **Docker image incompatibility** – You see the error: “VM failed before the agent could run. This is likely an issue with your Docker image.” * Possible cause: Alpine Linux and other musl-based images are not compatible with the agent runtime, which requires glibc. * Solution: Switch to a glibc-based image such as Debian, Ubuntu, or the default (non-Alpine) variants of official Docker Hub images (e.g. `node`, `python`, `rust`). # Cloud Agent FAQs > Frequently asked questions about cloud agents, including where agents run, how runs work, supported models, security, and common workflows. This page answers common questions about cloud agents, including where they run, how they’re configured, and how teams use cloud agents for day-to-day engineering work. ## Architecture and execution [Section titled “Architecture and execution”](#architecture-and-execution) ### Where do cloud agents run? What’s the architecture? [Section titled “Where do cloud agents run? What’s the architecture?”](#where-do-cloud-agents-run-whats-the-architecture) Agents run either **locally** (inside your Warp session) or **in the cloud** as a **cloud agent run**, inside an **environment** (see [Environments](/agent-platform/cloud-agents/environments/)). The cloud agents platform is built around modular, observable execution: * A **trigger** starts work (manual, schedule/cron, webhook, or an integration like Slack/GitHub). * The **agent** executes inside an **environment** (either a Warp-hosted cloud sandbox, or a **self-hosted sandbox** on your infrastructure, depending on plan/support). * Every step is recorded: **transcripts, tool calls, logs, and outputs**, so work is auditable and debuggable instead of a black box. The same agent can be invoked consistently across entry points (Warp conversation, cloud agent web app, the CLI, API/SDK, Slack/GitHub triggers) without rewriting the underlying instructions. ### What exactly are cloud agents in Warp? [Section titled “What exactly are cloud agents in Warp?”](#what-exactly-are-cloud-agents-in-warp) A **cloud agent** is a packaged automation unit made up of: * **Instructions** — A reusable skill/prompt (what it should do). * **Profile** — Model selection + tools + permissions (how it operates). * **Trigger** — Manual, cron/schedule, webhook, or integration event (when it starts). * **Environment** — Repo access, dependencies (Docker image), secrets, setup commands, and runtime config (where it runs). * **Host** — Local (interactive) or cloud (run), and optionally self-hosted execution (where supported). Because the agent definition is modular, the same cloud agent can be started from different surfaces (terminal, web app, CLI, integrations) with a consistent interface. ### Can we intervene mid-run? [Section titled “Can we intervene mid-run?”](#can-we-intervene-mid-run) Yes. For **cloud agent runs**, you can: * Inspect **run state**, tool calls, and logs. * **Steer** the agent while it’s running. * Unblock it with additional instructions or context. If you’re not happy with where it landed, you can take over to finish the task. That human handoff is a core part of making agents reliable beyond demos. ### Do cloud agents have access to Codebase Context and indexing? [Section titled “Do cloud agents have access to Codebase Context and indexing?”](#do-cloud-agents-have-access-to-codebase-context-and-indexing) Yes. [Codebase Context](/agent-platform/capabilities/codebase-context/) is enabled for all Oz cloud agent runs, as long as Codebase Context is enabled for your account. This includes runs triggered from the CLI, API/SDK, integrations (Slack, Linear, GitHub Actions), and schedules. No additional configuration is needed — if Codebase Context is enabled, cloud agents use it automatically. ### Can I access a shell inside a cloud agent environment? Are there limitations (Docker, Playwright, etc.)? [Section titled “Can I access a shell inside a cloud agent environment? Are there limitations (Docker, Playwright, etc.)?”](#can-i-access-a-shell-inside-a-cloud-agent-environment-are-there-limitations-docker-playwright-etc) Yes. Cloud agent runs execute in a full Linux environment and behave like a local development session. You can install dependencies, run Docker, and use headless tools like Playwright, subject to standard sandbox resource limits. ### Do cloud agents support a fully self-hosted, on-prem, or offline mode? [Section titled “Do cloud agents support a fully self-hosted, on-prem, or offline mode?”](#do-cloud-agents-support-a-fully-self-hosted-on-prem-or-offline-mode) The cloud agents platform supports self-hosting the **agent sandbox** (the execution environment) on your own infrastructure. The **control plane**—which handles orchestration, tracking, and auditability—remains Warp-managed and is not self-hosted. Self-hosted execution is available on **Enterprise** plans. See [Self-Hosting](/agent-platform/cloud-agents/self-hosting/) and [Deployment Patterns](/agent-platform/cloud-agents/deployment-patterns/) for details. Note [Bring Your Own Key (BYOK)](/support-and-community/plans-and-billing/bring-your-own-api-key/) does not apply to cloud agents. BYOK keys are stored locally on your device and cannot be passed to cloud-hosted or self-hosted agent runs. All cloud agent runs consume [Warp credits](/support-and-community/plans-and-billing/credits/). ## Models [Section titled “Models”](#models) ### Which models are supported? [Section titled “Which models are supported?”](#which-models-are-supported) Cloud agents are **multi-model by design**. You can choose models based on cost, latency, and capability, and teams commonly mix models by workflow: * Faster/cheaper models for triage and routine tasks. * Stronger models for complex changes (refactors, multi-file work, deeper reasoning). Model choice is configurable per **agent** (and often per environment/workflow), depending on how you set up your profiles. ### Can I choose which model cloud agents use? [Section titled “Can I choose which model cloud agents use?”](#can-i-choose-which-model-cloud-agents-use) Yes. Cloud agents support the same set of models available in Warp. Model selection is configurable per agent or environment. ### Can I authenticate cloud agents with my own ChatGPT or Claude Pro / Max plan? [Section titled “Can I authenticate cloud agents with my own ChatGPT or Claude Pro / Max plan?”](#can-i-authenticate-cloud-agents-with-my-own-chatgpt-or-claude-pro--max-plan) We’re strong proponents of this, but it ultimately depends on model provider policies. We’re actively working with providers to explore whether direct third-party authentication is possible. ### Do you support local or private LLMs for compliance or air-gapped environments? [Section titled “Do you support local or private LLMs for compliance or air-gapped environments?”](#do-you-support-local-or-private-llms-for-compliance-or-air-gapped-environments) Enterprise plans will support managed integrations like AWS Bedrock and Google Vertex. Fully local, offline LLM execution is difficult given the current cloud agents orchestration and runtime architecture, but private-model support via enterprise cloud providers is on the roadmap. ### Will cloud agents support Agent-to-Agent Protocols (A2A)? [Section titled “Will cloud agents support Agent-to-Agent Protocols (A2A)?”](#will-cloud-agents-support-agent-to-agent-protocols-a2a) It’s something we’re actively exploring. Our focus is on building durable orchestration primitives—runs, environments, observability, steering, and coordination—that can support A2A and other emerging standards over time. ## Security and billing [Section titled “Security and billing”](#security-and-billing) ### Will cloud storage for agent definitions, runs, and conversations be secure and encrypted? [Section titled “Will cloud storage for agent definitions, runs, and conversations be secure and encrypted?”](#will-cloud-storage-for-agent-definitions-runs-and-conversations-be-secure-and-encrypted) Yes. All cloud agent data stored in the cloud is encrypted at rest and in transit, and protected by Warp account–level access controls. Cloud agent environments are sandboxed by default, with scoped access to repos, secrets, and compute. Security and isolation are first-class design constraints for the cloud agent runtime. ### Are cloud agents included in the Build plan, or is it a separate add-on? [Section titled “Are cloud agents included in the Build plan, or is it a separate add-on?”](#are-cloud-agents-included-in-the-build-plan-or-is-it-a-separate-add-on) Cloud agents are included in the Build plan. Usage is metered via credits, with pricing based on agent runs and resource consumption. Concurrency limits and credit allocation details are still being finalized. ### How do cloud agents handle API keys and secrets for agents? [Section titled “How do cloud agents handle API keys and secrets for agents?”](#how-do-cloud-agents-handle-api-keys-and-secrets-for-agents) Secrets are managed via the cloud agents CLI. Secrets are encrypted at rest, scoped to your Warp account, and injected into the agent environment at runtime. They are never hard-coded into agent instructions or logs. To learn more about how secrets work in practice, see [Cloud Agent Secrets](/agent-platform/cloud-agents/secrets/). ## Workflows [Section titled “Workflows”](#workflows) ### How do agents handle branching, merge conflicts, and multi-agent coordination with cloud agents? [Section titled “How do agents handle branching, merge conflicts, and multi-agent coordination with cloud agents?”](#how-do-agents-handle-branching-merge-conflicts-and-multi-agent-coordination-with-cloud-agents) The cloud agents platform is intentionally flexible. As the developer, you decide how agents should branch, coordinate, and resolve conflicts. Interactive agents can plan work and spawn subagents to parallelize tasks. Cloud agents provide the building blocks for running and coordinating multiple concurrent agents, rather than enforcing a fixed workflow. ### Why focus on orchestration primitives instead of immediately adopting new agent standards? [Section titled “Why focus on orchestration primitives instead of immediately adopting new agent standards?”](#why-focus-on-orchestration-primitives-instead-of-immediately-adopting-new-agent-standards) We believe durable infrastructure matters more than transient standards. The cloud agents platform is designed to provide stable building blocks—agent runs, environments, auditability, steering, and coordination—that orchestration frameworks and emerging standards can plug into over time. ### Can cloud agents integrate with external tools, APIs, or services (like n8n connectors)? [Section titled “Can cloud agents integrate with external tools, APIs, or services (like n8n connectors)?”](#can-cloud-agents-integrate-with-external-tools-apis-or-services-like-n8n-connectors) Yes, and cloud agents do not rely on rigid, predefined workflows. Agents can install CLIs, call external APIs, use MCP servers, and access the internet directly. The intent is to delegate flexibility to agents rather than constrain them with fixed connectors. ### Can I export agent conversations and runs from cloud agents? [Section titled “Can I export agent conversations and runs from cloud agents?”](#can-i-export-agent-conversations-and-runs-from-cloud-agents) Yes. Conversations can be copied directly from the UI. The cloud agent CLI and API also provide access to full conversation text, logs, and outputs programmatically. ### How do cloud agents handle environment access, files, and security compared to SSH-based setups? [Section titled “How do cloud agents handle environment access, files, and security compared to SSH-based setups?”](#how-do-cloud-agents-handle-environment-access-files-and-security-compared-to-ssh-based-setups) Access is handled through Warp session sharing rather than SSH keys. Authentication is tied to Warp accounts and access controls, enabling secure person-to-person sharing. Configuration files and credentials can be managed using encrypted .env workflows (for example, dotenv-style encryption), avoiding repeated manual decrypt/encrypt cycles. ### Can cloud agents review PRs like a teammate? [Section titled “Can cloud agents review PRs like a teammate?”](#can-cloud-agents-review-prs-like-a-teammate) Yes. Common patterns for a **cloud agent** in PR review: * Summarize changes and intent. * Flag risky diffs and edge cases. * Suggest tests and missing coverage. * Propose refactors for maintainability. A typical workflow is: the agent leaves structured review comments and optionally opens a follow-up PR for mechanical fixes (or commits to the branch, if you choose to allow that). ### Can cloud agents write unit tests? [Section titled “Can cloud agents write unit tests?”](#can-cloud-agents-write-unit-tests) Yes, especially when: * The repo has a consistent test framework. * The **environment** is reproducible (dependencies and setup are reliable). The strongest loop is: a cloud agent generates tests, runs them in the environment, iterates until green, then opens a PR with the tests plus a short explanation of coverage and assumptions. ### Can cloud agents do big refactors? [Section titled “Can cloud agents do big refactors?”](#can-cloud-agents-do-big-refactors) It can help, but the best practice is to scope into smaller, reviewable chunks. Agents are strongest when they can continuously validate progress (tests, lint, typecheck). For large refactors, a staged approach with checkpoints (and possibly multiple subagents for parallel exploration) tends to work better than one giant prompt. ### Can cloud agents triage issues / tickets automatically? [Section titled “Can cloud agents triage issues / tickets automatically?”](#can-cloud-agents-triage-issues--tickets-automatically) Yes. A common cloud agent workflow: * When a ticket/issue is created (via integration trigger), a cloud agent gathers context (recent changes, logs/metrics links, ownership). * Proposes labels/priority and likely causes. * Drafts next steps or a response. * Asks clarifying questions back to the reporter when needed. ### Can cloud agents do dependency upgrades? [Section titled “Can cloud agents do dependency upgrades?”](#can-cloud-agents-do-dependency-upgrades) Yes. Scheduled dependency bumps are a classic cloud agent use case: * Open a PR. * Run tests. * Resolve simple conflicts. * Attach a risk summary (optional). This is usually implemented as a scheduled **cloud agent** producing recurring **runs**. ### Can cloud agents keep docs up to date? [Section titled “Can cloud agents keep docs up to date?”](#can-cloud-agents-keep-docs-up-to-date) Yes. With cloud agents, agents can: * Scan for drift (commands that no longer work, onboarding steps that changed). * Run validations in a docs/test environment. * Propose doc updates as PRs. This is most successful with “docs as code” workflows (GitBook/Mintlify/Docusaurus style), where updates go through normal review. ## Self-hosting [Section titled “Self-hosting”](#self-hosting) ### Where does my source code go with self-hosted agents? [Section titled “Where does my source code go with self-hosted agents?”](#where-does-my-source-code-go-with-self-hosted-agents) With self-hosting, repositories are cloned and stored only on your infrastructure — Warp never hosts your codebase. Warp uses a split architecture: * **Execution plane (your infrastructure)** — Repository clones, build artifacts, runtime secrets, and container filesystem state stay on the machines you control. * **Control plane (Warp-hosted)** — Session transcripts (which include code context from agent interactions), orchestration metadata, and LLM inference route through Warp’s backend under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. Warp does not persistently store your source code or use it for model training. See [Self-Hosting](/agent-platform/cloud-agents/self-hosting/) for deployment options and [Security Overview](/enterprise/security-and-compliance/security-overview/) for full details. ### Can I use `oz agent run` in CI or existing runners? [Section titled “Can I use oz agent run in CI or existing runners?”](#can-i-use-oz-agent-run-in-ci-or-existing-runners) Yes. The [unmanaged architecture](/agent-platform/cloud-agents/self-hosting/unmanaged/) is designed exactly for this. Run `oz agent run` in any environment where you can execute a CLI command — GitHub Actions, Jenkins, Buildkite, Kubernetes pods, or custom orchestrators. This is how the [`warpdotdev/oz-agent-action`](https://github.com/warpdotdev/oz-agent-action) GitHub Action works. The agent runs locally on the runner and its session is tracked on Warp’s backend for observability. ### Can self-hosted agents access services behind a VPN? [Section titled “Can self-hosted agents access services behind a VPN?”](#can-self-hosted-agents-access-services-behind-a-vpn) Yes. Since self-hosted agents run on your infrastructure, they inherit your network access. This means agents can reach self-hosted GitLab/Bitbucket instances, internal APIs, databases, and any other services behind your VPN. This is one of the primary reasons teams choose self-hosting. ### Does self-hosting work with GitLab or other non-GitHub SCMs? [Section titled “Does self-hosting work with GitLab or other non-GitHub SCMs?”](#does-self-hosting-work-with-gitlab-or-other-non-github-scms) Self-hosted agents can use any SCM accessible from your infrastructure. With the [unmanaged architecture](/agent-platform/cloud-agents/self-hosting/unmanaged/), agents run directly on your host and use whatever Git configuration and SCM access is already available. With the [managed architecture](/agent-platform/cloud-agents/self-hosting/#managed-architecture), automatic environment setup currently focuses on GitHub, but you can configure access to other SCMs via volume mounts, environment variables, setup commands, or Kubernetes Secrets (when using the [Kubernetes backend](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/)). See the [GitLab](/agent-platform/cloud-agents/integrations/gitlab/) and [Bitbucket](/agent-platform/cloud-agents/integrations/bitbucket/) setup guides for step-by-step instructions. ### Do LLM requests still go through Warp with self-hosting? [Section titled “Do LLM requests still go through Warp with self-hosting?”](#do-llm-requests-still-go-through-warp-with-self-hosting) Yes. LLM inference routes through Warp’s backend, which has [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements with all contracted model providers. Enterprise teams that need full control over inference routing can use [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) to route inference through their own cloud provider accounts. BYOLLM currently applies to interactive (local) agents; cloud agent support is coming. ### What about large monorepos with long environment setup times? [Section titled “What about large monorepos with long environment setup times?”](#what-about-large-monorepos-with-long-environment-setup-times) The [unmanaged architecture](/agent-platform/cloud-agents/self-hosting/unmanaged/) is well-suited for large monorepos because agents run directly in your pre-provisioned environment — there is no Docker image build or repo cloning step. For the [managed architecture](/agent-platform/cloud-agents/self-hosting/#managed-architecture), the Docker backend supports volume mounts (`-v` flag) to mount a pre-existing repo checkout from the host into task containers. With the Kubernetes backend, use `pod_template` to configure persistent volume claims or pre-populated storage for the same purpose. Note The managed architecture supports three execution backends: **Docker** (default), **Kubernetes**, and **Direct** (no container runtime). The Kubernetes backend runs each task as a Kubernetes Job and includes a Helm chart for deployment. See [Self-Hosting](/agent-platform/cloud-agents/self-hosting/#choosing-a-managed-backend) for details on choosing a backend. ### Do Kubernetes pods provide enough sandboxing for self-hosted agents? [Section titled “Do Kubernetes pods provide enough sandboxing for self-hosted agents?”](#do-kubernetes-pods-provide-enough-sandboxing-for-self-hosted-agents) This depends on your cluster configuration and risk profile. Evaluate your pod security policies, network policies, and RBAC settings based on your organization’s security requirements. ## Current limitations [Section titled “Current limitations”](#current-limitations) ### Do cloud agents support image attachments? [Section titled “Do cloud agents support image attachments?”](#do-cloud-agents-support-image-attachments) Cloud agent conversations do not currently support image attachments. Image attachment (via the toolbar button, clipboard paste, or drag-and-drop) is only available in [local agent conversations](/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes/). If you need to provide visual context to a cloud agent, you can describe the image contents in your prompt or reference image file paths within the agent’s [environment](/agent-platform/cloud-agents/environments/). # Integrations Overview > Configure Warp's first-party integrations by creating environments, connecting GitHub, and enabling agents to run your code and automate development workflows. Warp integrations let your team trigger agents directly from the terminal, or from tools like [Slack](/agent-platform/cloud-agents/integrations/slack/) and [Linear](/agent-platform/cloud-agents/integrations/linear/). Once set up, agents can: * Read conversation or issue context * Run code inside your codebase in a remote environment * Open pull requests and perform other multi-step agent workflows on your behalf Note For a full walkthrough of Warp’s integrations and configurable environments, please refer to [Integration setup](/reference/cli/integration-setup/). All of this is powered by the [Oz CLI](/reference/cli/). *** ## Quickstart [Section titled “Quickstart”](#quickstart) The fastest way to get agents running from Slack or Linear is to create an environment with the guided flow. An **environment** defines everything the agent needs to run your code remotely, including your Docker image, repos, and setup commands. ![YouTube video](https://i.ytimg.com/vi/ahFfInVD0HQ/sddefault.jpg) #### 1. Run /create-environment [Section titled “1. Run /create-environment”](#1-run-create-environment) From Warp, run the following slash command: ```plaintext /create-environment ``` You can run it inside any repo, or point it at multiple repos: ```plaintext /create-environment ./frontend ./backend /create-environment your-org/repo-name /create-environment https://github.com/your-org/api.git ``` Note Learn more about slash commands and how to use them in the [Slash Commands](/agent-platform/capabilities/slash-commands/) documentation. The guided flow will: * Detect which repos you want the agent to work with * Identify languages, frameworks, and tools * Suggest a Docker image (or build/push one if needed) * The Docker image can be your own custom image, an official base image (e.g. node, python), or one of Warp’s prebuilt dev images (see [repo](https://github.com/warpdotdev/oz-dev-environments)). * Recommend setup commands * Create the environment and return an environment ID This produces a ready-to-use environment that Warp can use across Slack, Linear, and terminal triggers. #### 2. Authorize GitHub [Section titled “2. Authorize GitHub”](#2-authorize-github) Warp will prompt you to install or update the Warp GitHub app so the agent can read and write to the repos you included. You only need to do this once. Teammates will authorize on their first run as needed. Note **Using Azure DevOps, GitLab, or Bitbucket?** Native integrations for these platforms are not yet available, but you can connect repositories by storing a personal access token as a Warp-managed secret and cloning via a setup command. See [Azure DevOps](/agent-platform/cloud-agents/integrations/azure-devops/), [GitLab](/agent-platform/cloud-agents/integrations/gitlab/), or [Bitbucket](/agent-platform/cloud-agents/integrations/bitbucket/) for step-by-step instructions. #### 3. Create an integration [Section titled “3. Create an integration”](#3-create-an-integration) Note For easier setup, use the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) at [oz.warp.dev](https://oz.warp.dev) to configure integrations with a guided flow. The web app works on mobile devices. Alternatively, use the CLI: For Slack: ```plaintext oz integration create slack --environment ``` For Linear: ```plaintext oz integration create linear --environment ``` The CLI opens an authorization page where you install Oz into your Slack workspace or Linear team. #### 4. Start using agents [Section titled “4. Start using agents”](#4-start-using-agents) In Slack: * Tag **@Oz** in a message or thread * Or DM the bot In Linear: * Tag @Oz on an issue Warp will read the thread/issue, spin up your environment, run the workflow in the cloud, and post progress + PRs back into the same conversation. *** For more details on configuring integrations and environments in Warp, please refer to [Integration setup](/reference/cli/integration-setup/). # Azure DevOps integration > Connect Oz cloud agents to Azure DevOps repos using personal access tokens and Warp-managed secrets. Oz cloud agents work with any Git repository, including those hosted on Azure DevOps. A native Azure DevOps integration is not yet available, but you can grant agents access to your repositories using a personal access token and Warp-managed secrets. Once configured, your environment works with any Oz trigger—Slack, Linear, schedules, or the CLI. This page explains how to generate an Azure DevOps personal access token, store it securely, and configure a cloud agent environment that clones your repository at runtime. Note This approach works for both Azure DevOps Services (dev.azure.com) and Azure DevOps Server (self-hosted) instances. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * A Warp account ([create an account at oz.warp.dev](https://oz.warp.dev)) * A repository hosted on Azure DevOps (cloud or self-hosted) * The [Oz CLI](/reference/cli/) installed and authenticated *** ## Step 1: Generate a personal access token [Section titled “Step 1: Generate a personal access token”](#step-1-generate-a-personal-access-token) 1. Sign in to your Azure DevOps organization at `dev.azure.com/{your-org}`. 2. Click the user settings icon (gear) in the top-right corner, then click **Personal access tokens**. 3. Click **+ New Token**. 4. Enter a descriptive name for the token (e.g. `warp-oz-agent`), choose the organization it applies to, and set an expiration date that matches your team’s rotation policy. 5. Under **Scopes**, select **Custom defined**, then select **Code** > **Read**. 6. Click **Create**. 7. Copy the token value immediately. Azure DevOps will not show it again. Note **Code (Read)** is the minimum required scope to clone a repository. If a future workflow requires the agent to push commits or open pull requests, you will also need **Code (Read & Write)**. Note For Azure DevOps Server (self-hosted), sign in at `https://{server}/{collection}` instead of `dev.azure.com`. The token creation steps are the same. *** ## Step 2: Store the token as a Warp-managed secret [Section titled “Step 2: Store the token as a Warp-managed secret”](#step-2-store-the-token-as-a-warp-managed-secret) Warp injects managed secrets as environment variables at runtime and never exposes them in logs or configuration files. See the [Secrets](/agent-platform/cloud-agents/secrets/) documentation for full details on scoping and managing secrets. 1. Run the following command: ```bash oz secret create --team AZURE_DEVOPS_TOKEN ``` 2. When prompted, paste the token. The value is stored and encrypted, and cannot be retrieved after creation. Note Use `--team` to create a shared token available to all teammates and automated triggers (schedules, Slack, Linear). Use `--personal` if each team member should authenticate with their own Azure DevOps token. Personal secrets work with all triggers and take precedence over a team secret of the same name when both exist. If you need to update a secret value, run: ```bash oz secret update --team --value AZURE_DEVOPS_TOKEN ``` *** ## Step 3: Create an environment with a clone setup command [Section titled “Step 3: Create an environment with a clone setup command”](#step-3-create-an-environment-with-a-clone-setup-command) Create an environment that uses your token to clone the repository at the start of each agent run. Because the `--repo` flag in `oz environment create` is designed for GitHub repositories, you clone your Azure DevOps repo via a setup command instead. 1. Run the following command: ```bash oz environment create \ --name "my-azure-devops-env" \ --docker-image \ --setup-command 'git clone https://$AZURE_DEVOPS_TOKEN@dev.azure.com/your-org/your-project/_git/your-repo' \ --setup-command 'cd your-repo && ' ``` Caution Use single quotes around setup commands that reference secrets. Double quotes cause your shell to expand `$AZURE_DEVOPS_TOKEN` immediately (to nothing), rather than letting Warp inject the secret at runtime inside the container. 2. Replace the following placeholders: * `` with your Docker image (for example, `node:22`, `python:3.12`, or a [Warp prebuilt dev image](https://github.com/warpdotdev/oz-dev-environments)) * `your-org` with your Azure DevOps organization name * `your-project` with your Azure DevOps project name * `your-repo` with your repository name * For Azure DevOps Server (self-hosted), replace `dev.azure.com` with your server’s hostname. * The second `--setup-command` with any dependency install or build steps your project requires. For example, `npm ci` or `pip install -r requirements.txt`. Caution Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [Environment design and best practices](/agent-platform/cloud-agents/environments/#environment-design-and-best-practices) for guidance. 3. Note the environment ID returned. You will need it in the next step. *** ## Step 4: Test your environment [Section titled “Step 4: Test your environment”](#step-4-test-your-environment) Before connecting to integrations, verify the environment works by running a one-off agent. 1. Run the following command, replacing `` with the environment ID from Step 3: ```bash oz agent run-cloud --environment --prompt "Your task here" ``` *** ## Next steps [Section titled “Next steps”](#next-steps) With your environment configured, you can connect it to any Warp trigger exactly as you would with a GitHub-backed environment: * **Slack** — Tag **@Oz** in a message to start an agent run against your Azure DevOps repo. See [Slack](/agent-platform/cloud-agents/integrations/slack/). * **Linear** — Tag **@Oz** on an issue to kick off a workflow. See [Linear](/agent-platform/cloud-agents/integrations/linear/). * **Scheduled agents** — Run agents on a recurring schedule. See [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/). Note Native support for opening Azure DevOps pull requests from agent-generated changes is planned as a future enhancement. # Bitbucket integration > Connect Oz cloud agents to Bitbucket repos using access tokens and Warp-managed secrets. Oz cloud agents work with any Git repository, including those hosted on Bitbucket. Unlike GitHub, Bitbucket does not have a native Warp integration, but you can grant agents access to your Bitbucket repositories using an access token and Warp-managed secrets. Once configured, your environment works with any Oz trigger—Slack, Linear, schedules, or the CLI. This page explains how to generate a Bitbucket access token, store it securely, and configure a cloud agent environment that clones your repository at runtime. Bitbucket Cloud and Bitbucket Data Center/Server use different token types: * **Bitbucket Cloud** uses **API tokens**, created through your Atlassian Account settings. * **Bitbucket Data Center/Server** uses **HTTP access tokens**, created through your Bitbucket profile settings. Follow the section that matches your setup. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * A Warp account ([create an account at oz.warp.dev](https://oz.warp.dev)) * A repository hosted on Bitbucket (Cloud or Data Center/Server) * The [Oz CLI](/reference/cli/) installed and authenticated *** ## Bitbucket Cloud [Section titled “Bitbucket Cloud”](#bitbucket-cloud) ### Step 1: Generate an API token [Section titled “Step 1: Generate an API token”](#step-1-generate-an-api-token) Note Bitbucket Cloud API tokens are managed through your Atlassian Account, which is a separate site from bitbucket.org. The following steps will take you there. 1. Click your avatar in the upper-right corner of Bitbucket, then click **Account settings**. 2. On the Atlassian Account page that opens, click the **Security** tab. 3. Click **Create and manage API tokens**, then click **Create API token with scopes**. 4. Enter a name for the token (e.g. `warp-oz-agent`) and choose an expiration date. 5. Click **Next**. 6. Select **Bitbucket** as the app and click **Next**. 7. Search for `repository` in the **Select Bitbucket scopes** search box, then select **read:repository:bitbucket** (View your repositories). 8. Click **Next**. 9. Click **Create token**. 10. Copy the token value immediately. It is only shown once and cannot be retrieved later. Note **read:repository:bitbucket** is the minimum required scope to clone a repository. If a future workflow requires the agent to push commits or open pull requests, you will also need **write:repository:bitbucket**. *** ### Step 2: Store the token as a Warp-managed secret [Section titled “Step 2: Store the token as a Warp-managed secret”](#step-2-store-the-token-as-a-warp-managed-secret) Warp injects managed secrets as environment variables at runtime and never exposes them in logs or configuration files. See the [Secrets](/agent-platform/cloud-agents/secrets/) documentation for full details on scoping and managing secrets. 1. Run the following command: ```bash oz secret create --team BITBUCKET_API_TOKEN ``` 2. When prompted, paste the token. The value is stored and encrypted, and cannot be retrieved after creation. Note Use `--team` to create a shared token available to all teammates and automated triggers (schedules, Slack, Linear). Use `--personal` if each team member should authenticate with their own Atlassian account token. Personal secrets work with all triggers and take precedence over a team secret of the same name when both exist. If you need to update a secret value, run: ```bash oz secret update --value BITBUCKET_API_TOKEN ``` *** ### Step 3: Create an environment with a clone setup command [Section titled “Step 3: Create an environment with a clone setup command”](#step-3-create-an-environment-with-a-clone-setup-command) Create an environment that uses your token to clone the repository at the start of each agent run. Use the static username `x-bitbucket-api-token-auth` in the clone URL — this is a Bitbucket-specific placeholder that works with API tokens and means you don’t need to store your Bitbucket username separately. 1. Run the following command: ```bash oz environment create \ --name "my-bitbucket-cloud-env" \ --docker-image \ --setup-command 'git clone https://x-bitbucket-api-token-auth:$BITBUCKET_API_TOKEN@bitbucket.org/your-workspace/your-repo.git' \ --setup-command 'cd your-repo && ' ``` Caution Use single quotes around setup commands that reference secrets. Double quotes cause your shell to expand `$BITBUCKET_API_TOKEN` immediately (to nothing), rather than letting Warp inject the secret at runtime inside the container. 2. Replace the following placeholders: * `` with your Docker image (for example, `node:22`, `python:3.12`, or a [Warp prebuilt dev image](https://github.com/warpdotdev/oz-dev-environments)) * `bitbucket.org/your-workspace/your-repo.git` with your actual repository URL * The second `--setup-command` with any dependency install or build steps your project requires (for example, `npm ci` or `pip install -r requirements.txt`) Caution Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [Environment design and best practices](/agent-platform/cloud-agents/environments/#environment-design-and-best-practices) for guidance. 3. Note the environment ID returned. You will need it in the next step. *** ## Bitbucket Data Center / Server [Section titled “Bitbucket Data Center / Server”](#bitbucket-data-center--server) ### Step 1: Generate an HTTP access token [Section titled “Step 1: Generate an HTTP access token”](#step-1-generate-an-http-access-token) 1. Click your profile avatar in Bitbucket, then click **Manage account**. 2. In the left sidebar, click **HTTP access tokens**. 3. Click **Create token**. 4. Enter a name for the token (e.g. `warp-oz-agent`) and choose an expiration date if required by your administrator. 5. Under **Permissions**, choose **Read** for the **Repository** permission. 6. Click **Create token**. 7. Copy the token value immediately. It is only shown once and cannot be retrieved later. Note **Repository read** is the minimum required permission to clone a repository. If a future workflow requires the agent to push commits, you will also need **Repository write**. *** ### Step 2: Store the token as a Warp-managed secret [Section titled “Step 2: Store the token as a Warp-managed secret”](#step-2-store-the-token-as-a-warp-managed-secret-1) Warp injects managed secrets as environment variables at runtime and never exposes them in logs or configuration files. See the [Secrets](/agent-platform/cloud-agents/secrets/) documentation for full details on scoping and managing secrets. 1. Run the following command: ```bash oz secret create --team BITBUCKET_TOKEN ``` 2. When prompted, paste the token. The value is stored and encrypted, and cannot be retrieved after creation. Note Use `--team` to create a shared token available to all teammates and automated triggers (schedules, Slack, Linear). Use `--personal` if each team member should authenticate with their own Bitbucket account token. Personal secrets work with all triggers and take precedence over a team secret of the same name when both exist. If you need to update a secret value, run: ```bash oz secret update --value BITBUCKET_TOKEN ``` *** ### Step 3: Create an environment with a clone setup command [Section titled “Step 3: Create an environment with a clone setup command”](#step-3-create-an-environment-with-a-clone-setup-command-1) Create an environment that uses your token to clone the repository at the start of each agent run. 1. Run the following command: ```bash oz environment create \ --name "my-bitbucket-dc-env" \ --docker-image \ --setup-command 'git clone -c "http.extraHeader=Authorization: Bearer $BITBUCKET_TOKEN" https://your-server.com/scm/your-project/your-repo.git' \ --setup-command 'cd your-repo && ' ``` Caution Use single quotes around setup commands that reference secrets, so `$BITBUCKET_TOKEN` is expanded at runtime inside the container rather than in your current shell. 2. Replace the following placeholders: * `` with your Docker image (for example, `node:22`, `python:3.12`, or a [Warp prebuilt dev image](https://github.com/warpdotdev/oz-dev-environments)) * `your-server.com/scm/your-project/your-repo.git` with your Bitbucket Data Center/Server repository URL. The `/scm/` path segment is standard for Bitbucket Data Center/Server. * The second `--setup-command` with any dependency install or build steps your project requires (for example, `npm ci` or `pip install -r requirements.txt`) Caution Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [Environment design and best practices](/agent-platform/cloud-agents/environments/#environment-design-and-best-practices) for guidance. 3. Note the environment ID returned. You will need it in the next step. *** ## Step 4: Test your environment [Section titled “Step 4: Test your environment”](#step-4-test-your-environment) Before connecting to integrations, verify the environment works by running a one-off agent. 1. Run the following command, replacing `` with the environment ID from Step 3: ```bash oz agent run-cloud --environment --prompt "Your task here" ``` *** ## Next steps [Section titled “Next steps”](#next-steps) With your environment configured, you can connect it to any Warp trigger exactly as you would with a GitHub-backed environment: * **Slack** — Tag **@Oz** in a message to start an agent run against your Bitbucket repo. See [Slack](/agent-platform/cloud-agents/integrations/slack/). * **Linear** — Tag **@Oz** on an issue to kick off a workflow. See [Linear](/agent-platform/cloud-agents/integrations/linear/). * **Scheduled agents** — Run agents on a recurring schedule. See [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/). Note Native support for opening Bitbucket pull requests from agent-generated changes is planned as a future enhancement. # Cloud Providers (Preview) > Connect Oz cloud agents to your AWS and GCP services. Oz cloud agents can securely access cloud providers using short-lived OpenID Connect credentials. This page explains how to configure a cloud agent environment to automatically authenticate to your cloud provider. Oz has built-in support for AWS and GCP, and can work with any provider that supports OIDC tokens. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * A Warp account ([create an account at oz.warp.dev](https://oz.warp.dev)) * A cloud provider account Follow the section for your cloud provider. *** ## AWS [Section titled “AWS”](#aws) ### Step 1: Create an OIDC identity provider [Section titled “Step 1: Create an OIDC identity provider”](#step-1-create-an-oidc-identity-provider) The first step is to configure your AWS account to trust OIDC tokens produced by Oz. 1. Open the AWS IAM console at . 2. Click **Identity Providers**, then click **Add provider**. 3. Set the provider type to **OpenID Connect**. 4. Set the **Provider URL** to `https://app.warp.dev`. 5. Set the **Audience** to `sts.amazonaws.com`. 6. Copy the ARN of the new identity provider, which will look like: `arn:aws:iam:::oidc-provider/app.warp.dev`. Note Verify that the provider was created correctly by: 1. Clicking on the `app.warp.dev` link in the list of identity providers. 2. Clicking on **Endpoint verification** 3. Checking that the thumbprint is `08745487e891c19e3078c1f2a07e452950ef36f6` *** ### Step 2: Configure an IAM role [Section titled “Step 2: Configure an IAM role”](#step-2-configure-an-iam-role) Next, you will need to set up an AWS IAM role with a trust policy that links it to the OIDC provider. 1. Open the AWS IAM console at . 2. Click **Roles**, then click **Create role**. 3. Select **Custom trust policy**, and fill in the following JSON trust policy: ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowOzFederation", "Effect": "Allow", "Principal": { "Federated": "" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "app.warp.dev:aud": "sts.amazonaws.com" }, "StringLike": { "app.warp.dev:sub": "scoped_principal:/*" } } } ] } ``` You will need to replace: * `` with the ARN of the OIDC provider added in Step 1. * `` with your Warp team UID. This is the last component of your [Admin Panel](/enterprise/team-management/admin-panel/) URL. For example, if the Admin Panel URL is `https://app.warp.dev/admin/abc123def456`, your team UID would be `abc123def456`. You can also get your team UID from the `oz whoami` command. The example above uses `StringLike` with the `scoped_principal:/*` pattern to allow any user or automation on your team to assume the role. See [the subject claim](#subject-sub) for the full format of `app.warp.dev:sub`. To restrict the role to a specific user, use `StringEquals` with the fully qualified subject: ```json ... "Condition": { "StringEquals": { "app.warp.dev:aud": "sts.amazonaws.com", "app.warp.dev:sub": "scoped_principal:/user:" } } ... ``` To allow multiple specific principals, use a list of subjects: ```json ... "Condition": { "StringEquals": { "app.warp.dev:aud": "sts.amazonaws.com", "app.warp.dev:sub": [ "scoped_principal:/user:", "scoped_principal:/user:", "scoped_principal:/service_account:" ] } } ... ``` 4. Click **Next** and add permissions policies. These policies determine what Oz agents can access in your AWS account. 5. Click **Next** and enter a role name and optional description. 6. Click **Create role**, then open the role and note down the role ARN. This will be of the form `arn:aws:iam:::role/`. *** ### Step 3: Enable AWS federation in your cloud agent environment [Section titled “Step 3: Enable AWS federation in your cloud agent environment”](#step-3-enable-aws-federation-in-your-cloud-agent-environment) Finally, configure the Oz cloud agent environment to use your new AWS role. 1. Open the Oz web app at . 2. Create or edit an environment. See [Environments](/agent-platform/cloud-agents/oz-web-app/#environments) for instructions. 3. Expand the **AWS** section and enter the AWS role ARN from Step 2. 4. Save the environment. Caution Currently, AWS federation can only be configured in the Oz web app, not the CLI. Oz agents running in this environment will now automatically assume the configured role when using the `aws` CLI or a compatible SDK. Note Oz uses the [**Assume role with web identity**](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-oidc) AWS authentication mechanism. The following environment variables are set while the agent is running: * `AWS_ROLE_ARN`: the ARN of the role configured above * `AWS_WEB_IDENTITY_TOKEN_FILE`: the path to a temporary file containing the agent’s Oz OIDC token * `AWS_ROLE_SESSION_NAME`: a derived session name, of the form `Oz_Run_`. *** ## GCP [Section titled “GCP”](#gcp) ### Step 1: Create a Workload Identity Pool and Provider [Section titled “Step 1: Create a Workload Identity Pool and Provider”](#step-1-create-a-workload-identity-pool-and-provider) The Oz GCP integration uses [Workload Identity Federation](https://docs.cloud.google.com/iam/docs/workload-identity-federation). You will need to configure a pool and provider to trust OIDC tokens produced by Oz. These instructions use the `gcloud` tool. You may also follow the OIDC instructions in [Configure Workload Identity Federation with other identity providers](https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-other-providers) to use the GCP console or Terraform. 1. Create a Workload Identity Pool using the `gcloud` CLI: ```bash gcloud iam workload-identity-pools create "" --location=global ``` Replace `` with the desired identifier for your pool, such as `oz-agent-pool`. 2. Create a Provider within the pool: ```bash gcloud iam workload-identity-pools providers create-oidc \ "" \ --location=global \ "--workload-identity-pool=" \ --issuer-uri="https://app.warp.dev" \ "--attribute-mapping=google.subject=assertion.sub,google.groups=assertion.teams,attribute.environment=assertion.environment" \ "--attribute-condition='' in assertion.teams" ``` Replace `` with the ID you used above, and `` with the desired identifier for your provider, such as `oz-oidc-provider`. Replace `` with the UID of your Warp team. This is the last component of your [Admin Panel](/enterprise/team-management/admin-panel/) URL. For example, if the admin panel URL is `https://app.warp.dev/admin/abc123def456`, your team UID would be `abc123def456`. Caution If you do not set an attribute condition, then *any* Oz agent will be able to use your Workload Identity Federation provider, even if they do not belong to your team. ### Step 2: Configure IAM policies [Section titled “Step 2: Configure IAM policies”](#step-2-configure-iam-policies) You will need to configure IAM policies in GCP that allow Oz agents in the Workload Identity Federation pool access to resources. To give all Oz agents on your team read-only access to all Compute Engine resources in a project, for example, you would run: ```bash gcloud projects add-iam-policy-binding \ --member "principalSet://iam.googleapis.com/projects//locations/global/workloadIdentityPools//attribute.teams/" \ --role "roles/compute.viewer" ``` See [Workload Identity Federation principal types](https://docs.cloud.google.com/iam/docs/workload-identity-federation#principal-types) for the full syntax supported. ### Step 3: Enable Workload Identity Federation in your cloud agent environment [Section titled “Step 3: Enable Workload Identity Federation in your cloud agent environment”](#step-3-enable-workload-identity-federation-in-your-cloud-agent-environment) Finally, configure the Oz cloud agent environment to use your Workload Identity Federation provider. 1. Open the Oz web app at . 2. Create or edit an environment. See [Environments](/agent-platform/cloud-agents/oz-web-app/#environments) for instructions. 3. Expand the **GCP** section and enter the project number, pool ID, and provider ID from Step 1. 4. Save the environment. Caution Currently, Workload Identity Federation can only be configured in the Oz web app, not the CLI. Oz agents running in this environment will now automatically configure [Application Default Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials) to use the configured pool. Both the `GOOGLE_APPLICATION_CREDENTIALS` and `CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE` environment variables are set, so both the `gcloud` CLI and official Google SDKs will use the Oz federated credentials. Oz uses [**executable-sourced credentials**](https://docs.cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#create-credential-config) to configure ADC for automatic token rotation. ## Other providers [Section titled “Other providers”](#other-providers) To authenticate from Oz to another provider that supports OIDC federation, you can issue tokens directly. Within the agent environment, use the `oz federate issue-token` command to produce an OIDC token with your provider as the audience: ```bash oz federate issue-token --audience your-provider.com --output-format json ``` Optionally, add `--duration ` to customize the token validity. This cannot exceed the maximum runtime of an Oz agent. You may then exchange this token for provider-specific credentials. ## OIDC token claims [Section titled “OIDC token claims”](#oidc-token-claims) All Oz OIDC tokens include standard claims like `iss` (issuer) and `iat` (issued at). ### Audience [Section titled “Audience”](#audience) The `aud` claim will reflect the default for your cloud provider. For AWS, this is always `sts.amazonaws.com`. For GCP, it is derived from the Workload Identity Federation provider, such as `https://iam.googleapis.com/projects//locations/global/workloadIdentityPools//providers/`. ### Subject (`sub`) [Section titled “Subject (sub)”](#subject-sub) The `sub` claim is set to the identity that an Oz agent is executing as. This will either be a Warp user ID or an autogenerated account ID for team-scoped agent runs. By default, the `sub` claim uses the format `:`: * `user:abc123def456`: Identifies a user with ID `abc123def456` * `service_account:abc123def456`: Identifies your autogenerated team account When authenticating to AWS, Oz will use a different `sub` claim format, because AWS trust policies cannot match on custom OIDC claims. The format above will be prefixed with your team UID: * `scoped_principal:xyz789/user:abc123def456`: Identifies the user `abc123def456`, who is a member of team `xyz789`. * `scoped_principal:user:abc123def456`: Identifies the user `abc123def456`, who is not on any team. * `scoped_principal:xyz789/service_account:abc123def456`: Identifies the autogenerated account for team `xyz789`. In addition, user OIDC tokens include an `email` claim with the user’s email address. To get possible user ID values, use the `oz whoami` command: ```bash oz whoami User ID: abc123 Email: user@warp.dev Team ID: xyz789 Team Name: My Team ``` You can also check the user IDs from past runs using the Oz API: ```bash curl https://app.warp.dev/api/v1/agent/runs -H "Authorization: Bearer $WARP_API_KEY" { "runs": [ { ... "creator": { "type": "user", "uid": "", "display_name": "User Name", "email": "user@warp.dev" } } ] } ``` ### Team [Section titled “Team”](#team) Every token includes a `teams` claim. The value will be a list with your team UID - currently, this list only ever contains a single value. ### Oz run [Section titled “Oz run”](#oz-run) The following claims are derived from an Oz agent run: * `run_id`: the unique identifier for the individual run. This is not suitable for configuring access, but is useful to log for debugging. * `environment`: the unique identifier for the agent’s [Environment](/agent-platform/cloud-agents/environments/). * `agent_name`: the name of the [Skill](/agent-platform/cloud-agents/skills-as-agents/) that the agent was invoked with. * `skill_spec`: the canonical identifier for the skill, such as `github-org/github-repo:.warp/skills/skill-name/SKILL.md`. * `host`: the execution host. This will either be `warp`, for Warp-hosted agents, or the worker ID if [self-hosting](/agent-platform/cloud-agents/self-hosting/). ### Example token [Section titled “Example token”](#example-token) The following OIDC token references an Oz agent running as a specific Warp user: ```json // JWT Header { "typ": "JWT", "alg": "ES256", "kid": "" } // JWT Payload { "aud": ["sts.amazonaws.com"], "sub": "user:", "email": "user@warp.dev", "teams": [""], "run_id": "", "environment": "", "agent_name": "", "skill_spec": "", "host": "warp", "iss": "https://app.warp.dev", "jti": "", "exp": 1775210175, "iat": 1775206575, "nbf": 1775206575 } ``` # Demo: Issue Triage Bot > A walkthrough demo showing how to trigger a cloud agent from a GitHub Action to automatically triage bug reports and create draft pull requests. ![YouTube video](https://i.ytimg.com/vi/dK2eohQ2Yow/sddefault.jpg) Note Example repository: [**https://github.com/warpdotdev/warp-agents-demo-github-issue-triage**](https://github.com/warpdotdev/warp-agents-demo-github-issue-triage) In this demo, Ben shows how to trigger Warp’s coding agent from a GitHub Action to automate bug report handling as soon as issues hit your repository. * The workflow acts like a maintainer-first “front door” for bugs: it evaluates whether a report is actionable, asks for missing details when it isn’t, and escalates directly into a draft pull request when it is **The first half focuses on triage.** * The agent reads the issue (and optionally your repo’s bug report template) and returns a simple ready/not-ready decision. * If the report is missing key context like a clear description or reproduction steps, the workflow automatically posts a friendly comment requesting the missing info and applies a “needs info” label for maintainers to track. **The second half extends the workflow into investigation + fix.** * When a report has sufficient detail, Ben shows the agent investigating the codebase, implementing a fix, adding tests, running verification, and returning a PR-ready summary. * The GitHub Action then commits the changes and opens a draft PR that follows the repo’s pull request template and links back to the original issue for review. # GitHub Actions > Run Oz agents in GitHub Actions to automate code review, issue triage, and CI fixes. Run Oz agents directly in your GitHub Actions workflows using `oz-agent-action`. The agent integrates seamlessly into your CI pipeline, automating tasks like code review, issue triage, bug fixing, and maintenance using your repository context and GitHub permissions. This page covers how the integration works, how to set it up, and common automation patterns for development teams. Note **Getting started?** See the [GitHub Actions quickstart](/agent-platform/cloud-agents/integrations/quickstart-github-actions/) to set up your first workflow, or visit the [oz-agent-action repository](https://github.com/warpdotdev/oz-agent-action) for detailed setup instructions and ready-to-use workflow templates. Watch this demo to see the integration in action: In this demo * Automated PR reviews with both summary feedback and inline suggestions * One-click batching and committing of agent suggestions directly from the GitHub UI * Automatically fixing failing CI checks by opening a suggested PR * Suggesting fixes for small review comments (“nits”) without checking out code locally *** ### What the GitHub Actions integration does [Section titled “What the GitHub Actions integration does”](#what-the-github-actions-integration-does) The `oz-agent-action` is a GitHub Action that wraps the Oz CLI and: * Runs an Oz agent inside an Actions job * Caches package installation for faster builds * Captures the agent’s output for use in subsequent workflow steps * Lets you pass workflow context, event data, and previous step outputs into the agent prompt * Allows the agent to comment on PRs, post results, or open branches via the GitHub CLI * Supports inline code suggestions that can be batched and committed directly from the GitHub pull request UI * Enables using pre-built skills or custom skills for specialized tasks ### Requirements [Section titled “Requirements”](#requirements) To use Oz agents in GitHub Actions, you need: * A [**Warp API Key**](/reference/cli/#generating-api-keys) stored as a [GitHub secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions) — this authenticates the agent with Warp * Workflow permissions that match your intended actions (for example, `pull-requests: write` if the agent should commit or comment on PRs) — the agent performs actions on your behalf using the GitHub token available to the workflow * The `oz-agent-action` step added to your workflow * **For private repositories using `@oz-agent` mention workflows**: The [`oz-agent`](https://github.com/oz-agent) GitHub user must be [invited as a member](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) of your GitHub organization (see [Responding to comments with @ mentions](#1-responding-to-comments-with--mentions) for details) * Familiarity with GitHub Actions concepts — see the official docs for [GitHub Actions](https://docs.github.com/en/actions) ### Using Skills [Section titled “Using Skills”](#using-skills) Skills provide reusable instructions for Oz agents. You can use pre-built skills from the [oz-skills repository](https://github.com/warpdotdev/oz-skills) or create custom [skills](/agent-platform/capabilities/skills/) for your specific workflows. Skills can also be deployed as [standalone agents](/agent-platform/capabilities/skills/#skills-as-agents) to run on a schedule or in response to events. #### How to use skills [Section titled “How to use skills”](#how-to-use-skills) You can specify a skill using the `skill` input parameter, either instead of or in combination with prompts: ```yaml - name: Run agent with a skill uses: warpdotdev/oz-agent-action@v1 with: skill: 'code-review' warp_api_key: ${{ secrets.WARP_API_KEY }} ``` #### Skill format options [Section titled “Skill format options”](#skill-format-options) The `skill` parameter supports multiple formats for referencing skills: * **`skill_name`** - Searches for the skill in your repository’s skill directories * **`repo:skill_name`** - Uses a skill from a specific repository * **`org/repo:skill_name`** - Uses a skill from a specific organization’s repository #### Combining skills with prompts [Section titled “Combining skills with prompts”](#combining-skills-with-prompts) You can combine skills with prompts to provide specialized context while customizing the specific task: ```yaml with: skill: 'code-review' prompt: 'Focus on security vulnerabilities in authentication code' warp_api_key: ${{ secrets.WARP_API_KEY }} ``` In this example, the `code-review` skill provides the base context and approach for code review, while the prompt narrows the focus to security concerns in authentication code. Note Skills help maintain consistency across your workflows and can encapsulate best practices for common tasks like code review, issue triage, or automated testing. *** ## Common use cases [Section titled “Common use cases”](#common-use-cases) The `oz-agent-action` supports several automation patterns commonly used in CI. ### 1. Responding to comments with @ mentions [Section titled “1. Responding to comments with @ mentions”](#1-responding-to-comments-with--mentions) * **File**: [`examples/respond-to-comment.yml`](https://github.com/warpdotdev/oz-agent-action/blob/main/examples/respond-to-comment.yml) * **Use case**: Add “@oz-agent fix this typo” or similar comments to a PR or Issue. What it does: * Listens for comments containing a trigger phrase * Sends the comment and thread context into the agent * Agent replies directly to the comment * If code changes are requested, the agent commits fixes to the PR branch **When to use:** * Interactive coding assistance during review or issue triage. Note **Private repositories require org membership for `@oz-agent`** If your repository is in a **private GitHub organization**, you must [invite the `oz-agent` user](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) as a member of your organization before using `@oz-agent` mention workflows. Without this: * `@oz-agent` will not appear in GitHub’s autocomplete when writing comments. * Comments containing `@oz-agent` will not trigger the workflow, because GitHub does not recognize the mention. This is a GitHub platform limitation for private organizations — any user must be an org member to be mentioned in comments on private repos. Public repositories are not affected by this requirement. ### 2. Automated pull request review [Section titled “2. Automated pull request review”](#2-automated-pull-request-review) * **File**: [`examples/review-pr.yml`](https://github.com/warpdotdev/oz-agent-action/blob/main/examples/review-pr.yml) * **Use case**: Provide automated agent feedback when a PR is opened or marked ready for review. What it does: * Automatically runs when PRs open or switch to “ready for review” * Agent inspects changed files, analyzes the diff, and comments inline * Optionally posts a summary comment **When to use:** * Fast initial review before human reviewers step in. ### 3. Automatically fix issues [Section titled “3. Automatically fix issues”](#3-automatically-fix-issues) * **File**: [`examples/auto-fix-issue.yml`](https://github.com/warpdotdev/oz-agent-action/blob/main/examples/auto-fix-issue.yml) * **Use case**: Apply the `oz-agent` label on an Issue to trigger automated fixes. What it does: * Detects when the label is added * Agent analyzes the issue description and repo context * Creates a PR with a fix (fix/issue-NUMBER) * Or comments explaining why automation wasn’t possible **When to use:** * Automating bug fixes, small features, or maintenance tasks. ### 4. Daily issue summaries [Section titled “4. Daily issue summaries”](#4-daily-issue-summaries) * **File**: [`examples/daily-issue-summary.yml`](https://github.com/warpdotdev/oz-agent-action/blob/main/examples/daily-issue-summary.yml) * **Use case**: Scheduled summaries of newly opened issues. What it does: * Runs daily at 09:00 UTC * Fetches issues created in the past 24 hours * Generates a categorized summary * Sends the summary to Slack via webhook **When to use:** * Daily visibility into new work across your repositories. ### 5. Fixing failing CI checks [Section titled “5. Fixing failing CI checks”](#5-fixing-failing-ci-checks) * **File**: [`examples/fix-failing-checks.yml`](https://github.com/warpdotdev/oz-agent-action/blob/main/examples/fix-failing-checks.yml) * **Use case**: Automatically attempt fixes when a workflow or test suite fails. What it does: * Triggers when specified CI workflows fail * Pulls failure logs * Attempts to diagnose and fix the root cause * Opens a PR with the fix and comments with a link **When to use:** * Reducing downtime from failing builds or flaky tests. ### 6. Suggest fixes for review comments [Section titled “6. Suggest fixes for review comments”](#6-suggest-fixes-for-review-comments) * **File**: [`examples/suggest-review-fixes.yml`](https://github.com/warpdotdev/oz-agent-action/blob/main/examples/suggest-review-fixes.yml) * **Use case**: Automatically propose code suggestions for small, actionable review comments such as typos, naming tweaks, and minor refactors. **What it does:** * Triggers when a pull request review is submitted * Fetches review comments and stores them in review\_comments.json * Sends comments and context to an agent to decide which ones are simple, actionable fixes * Generates `responses.json` with explanations and suggestion blocks for each fixable comment * Replies inline to the original review comments with the generated suggestions **When to use:** * Quickly addressing straightforward review feedback such as typos, naming tweaks, style nits, and small refactors. *** ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### `@oz-agent` mention doesn’t trigger the workflow [Section titled “@oz-agent mention doesn’t trigger the workflow”](#oz-agent-mention-doesnt-trigger-the-workflow) If you’re tagging `@oz-agent` in a PR or issue comment and the workflow doesn’t run: 1. **Check org membership (private repos only)**: In private organizations, the `oz-agent` GitHub user must be a [member of your organization](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization). Without this, GitHub won’t recognize the mention and the `issue_comment` event won’t match the workflow trigger. Ask an org admin to invite [`oz-agent`](https://github.com/oz-agent) via **Settings > People > Invite member**. 2. **Verify the workflow file**: Ensure your workflow is on the default branch and the trigger condition matches `@oz-agent` (e.g. `contains(github.event.comment.body, '@oz-agent')`). 3. **Check workflow permissions**: The workflow must have the appropriate permissions (e.g. `issues: read`, `pull-requests: write`) to respond. ### `@oz-agent` doesn’t appear in GitHub autocomplete [Section titled “@oz-agent doesn’t appear in GitHub autocomplete”](#oz-agent-doesnt-appear-in-github-autocomplete) GitHub only suggests users who are members of the organization when typing `@` in comments on private repositories. [Invite `oz-agent`](https://docs.github.com/en/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization) to your organization to make it appear in autocomplete. Note: Even if `@oz-agent` doesn’t autocomplete, you can still type the mention manually — but the workflow will only trigger if the user is an org member (for private repos). # GitLab integration > Connect Oz cloud agents to GitLab repos using personal access tokens and Warp-managed secrets. Oz cloud agents work with any Git repository, including those hosted on GitLab. Unlike GitHub, GitLab does not have a native Warp integration, but you can grant agents access to your GitLab repositories using a personal access token and Warp-managed secrets. Once configured, your environment works with any Oz trigger—Slack, Linear, schedules, or the CLI. This page explains how to generate a GitLab personal access token, store it securely, and configure a cloud agent environment that clones your repository at runtime. Note This approach works for both GitLab.com and self-hosted GitLab instances. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * A Warp account ([create an account at oz.warp.dev](https://oz.warp.dev)) * A repository hosted on GitLab (cloud or self-hosted) * The [Oz CLI](/reference/cli/) installed and authenticated *** ## Step 1: Generate a personal access token [Section titled “Step 1: Generate a personal access token”](#step-1-generate-a-personal-access-token) Note These steps generate a personal access token tied to your GitLab account. If your team prefers a shared bot user, [GitLab project access tokens](https://docs.gitlab.com/user/project/settings/project_access_tokens/) work the same way. 1. Sign in to GitLab. 2. Click your avatar in the top-right corner, then click **Edit profile**. 3. In the left sidebar, click **Access**, then click **Personal access tokens**. 4. Click **Add new token**. 5. Enter a descriptive name for the token (e.g. `warp-oz-agent`), and choose an expiration date that matches your team’s rotation policy. 6. Under **Select scopes**, select **read\_repository**. 7. Click **Generate token**. 8. Copy the token value immediately. GitLab will not show it again. Note **read\_repository** is the minimum required scope to clone a repository. If a future workflow requires the agent to push commits or open merge requests, you will also need **write\_repository**. *** ## Step 2: Store the token as a Warp-managed secret [Section titled “Step 2: Store the token as a Warp-managed secret”](#step-2-store-the-token-as-a-warp-managed-secret) Warp injects managed secrets as environment variables at runtime and never exposes them in logs or configuration files. See the [Secrets](/agent-platform/cloud-agents/secrets/) documentation for full details on scoping and managing secrets. 1. Run the following command: ```bash oz secret create --team GITLAB_TOKEN ``` 2. When prompted, paste the token. The value is stored and encrypted, and cannot be retrieved after creation. Note Use `--team` to create a shared token available to all teammates and automated triggers (schedules, Slack, Linear). Use `--personal` if each team member should authenticate with their own GitLab token. Personal secrets work with all triggers and take precedence over a team secret of the same name when both exist. If you need to update a secret value, run: ```bash oz secret update --value GITLAB_TOKEN ``` *** ## Step 3: Create an environment with a clone setup command [Section titled “Step 3: Create an environment with a clone setup command”](#step-3-create-an-environment-with-a-clone-setup-command) Create an environment that uses your token to clone the repository at the start of each agent run. Because the `--repo` flag in `oz environment create` is designed for GitHub repositories, you clone your GitLab repo via a setup command instead. 1. Run the following command: ```bash oz environment create \ --name "my-gitlab-env" \ --docker-image \ --setup-command 'git clone https://oauth2:$GITLAB_TOKEN@gitlab.com/your-group/your-repo.git' \ --setup-command 'cd your-repo && ' ``` Caution Use single quotes around setup commands that reference secrets. Double quotes cause your shell to expand `$GITLAB_TOKEN` immediately (to nothing), rather than letting Warp inject the secret at runtime inside the container. 2. Replace the following placeholders: * `` with your Docker image (for example, `node:22`, `python:3.12`, or a [Warp prebuilt dev image](https://github.com/warpdotdev/oz-dev-environments)) * `gitlab.com/your-group/your-repo.git` with your actual repository URL * For a self-hosted GitLab instance, replace `gitlab.com` with your server’s hostname. * The second `--setup-command` with any dependency install or build steps your project requires. For example, `npm ci` or `pip install -r requirements.txt`. Caution Setup commands run on a fresh container for every agent run. Write them to be idempotent — commands that assume existing state (such as a partially cloned repo or a pre-built cache) can fail unpredictably. See [Environment design and best practices](/agent-platform/cloud-agents/environments/#environment-design-and-best-practices) for guidance. 3. Note the environment ID returned. You will need it in the next step. *** ## Step 4: Test your environment [Section titled “Step 4: Test your environment”](#step-4-test-your-environment) Before connecting to integrations, verify the environment works by running a one-off agent. 1. Run the following command, replacing `` with the environment ID from Step 3: ```bash oz agent run-cloud --environment --prompt "Your task here" ``` *** ## Next steps [Section titled “Next steps”](#next-steps) With your environment configured, you can connect it to any Warp trigger exactly as you would with a GitHub-backed environment: * **Slack** — Tag **@Oz** in a message to start an agent run against your GitLab repo. See [Slack](/agent-platform/cloud-agents/integrations/slack/). * **Linear** — Tag **@Oz** on an issue to kick off a workflow. See [Linear](/agent-platform/cloud-agents/integrations/linear/). * **Scheduled agents** — Run agents on a recurring schedule. See [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/). Note Native support for opening GitLab merge requests from agent-generated changes is planned as a future enhancement. # Linear integration > Automate Linear issues with Oz agents that run code in the cloud and create pull requests on your behalf. The Linear integration lets your team delegate development work directly to agents from inside Linear. When you tag @Oz on an issue or comment, an agent will spin up in the cloud, clone the repos defined in your environment, and begin working through the task. Agents keep you updated inside Linear, generate pull requests using your GitHub account, and provide a link to join a live remote session so you can watch or steer the workflow in real time. ![YouTube video](https://i.ytimg.com/vi/FNefNmbSdmg/sddefault.jpg) This guide explains what the integration does, how it works end-to-end, and how to configure it for your Warp team. *** ### Using Oz inside Linear [Section titled “Using Oz inside Linear”](#using-oz-inside-linear) Tagging @Oz on an issue or in a Linear comment starts an agent run. Oz clones the repositories defined in your environment, sets up your development environment using your Docker image and setup commands, and begins working through the task with full context from your codebase and the Linear issue. Agents post updates as they progress, including a task list, elapsed time, and checkpoints, so you can follow along without leaving Linear. Agents also share a link to an interactive remote session using Warp’s [cloud agent session sharing](/agent-platform/cloud-agents/viewing-cloud-agent-runs/). Opening this link lets you view the live terminal output for the running agent in Warp or in the browser. From there, you can interrupt or guide the agent with additional instructions when needed. Once the agent finishes, it will create a pull request on your behalf — using your GitHub permissions — and post a summary of its work and the PR link back into Linear. You can start an agent in two ways: * **Tag @Oz in a comment** and describe what you want done. * **Assign the issue to Oz** as if it were a teammate. Oz will acknowledge the request directly in the Linear issue and begin working. Agents keep you informed through: * **Activity updates** inside Linear * A **running task list** and timeline showing what the agent is working on * A **shared session link** that opens a live view of the agent’s cloud environment Session sharing works in Warp or in a browser view and allows multiple teammates to watch the session. ![Live cloud agent session shared from a Linear issue, viewed in Warp on Web.](/_astro/linear-warp-on-web.Be6YiRoh_Z1gLBNg.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### Joining the remote session [Section titled “Joining the remote session”](#joining-the-remote-session) Selecting [**Open in Warp**](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) (or the web option) opens the active session. You’ll see: * The agent’s full execution log * The plan pane with the task list * An input box to add clarifying instructions * A real-time view identical to a local Warp task Any instructions you give will interrupt the agent, feed the new context, and resume work. When the task is complete: * Warp commits the changes using your GitHub identity * A pull request is created through the GitHub CLI * The PR includes a clean title and description based on the Linear issue and the agent’s work * A summary and link to the PR appear in the Linear issue Because PRs are created as *you*, this makes code review, auditing, and team collaboration straightforward. *** ### Requirements [Section titled “Requirements”](#requirements) * **Team membership** - The Linear integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. * **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available (any type of Warp credits work). See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. * **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/agent-platform/cloud-agents/self-hosting/) on their own infrastructure. * **Identity** - You must be logged into Warp with the same email as your Linear workspace. * **GitHub authorization** - You must authorize the Warp GitHub app the first time you trigger an agent. * The repositories involved must be included in your environment and accessible to the Warp GitHub app. * You must have write access to the repo if you want Warp to create PRs on your behalf. *** ### How to configure the integration [Section titled “How to configure the integration”](#how-to-configure-the-integration) Setup involves two steps powered by the [Oz CLI](/reference/cli/). For more instructions, see [Integrations Overview](/agent-platform/cloud-agents/integrations/). #### 1. Create an environment [Section titled “1. Create an environment”](#1-create-an-environment) An environment defines everything the agent needs to run your code: * A **Docker image** (public on Docker Hub) * A set of **GitHub repos** the agent should clone * Optional **setup commands** that run before the agent starts You can create an environment via: * The CLI * The guided flow using `/create-environment` ([Slash Commands](/agent-platform/capabilities/slash-commands/)) For full instructions, see our [Environment Setup](/agent-platform/cloud-agents/integrations/) docs. #### 2. Create the Linear integration [Section titled “2. Create the Linear integration”](#2-create-the-linear-integration) Once your environment exists, create the integration. Note For easier setup, use the [Oz web app](https://oz.warp.dev) to configure integrations with a guided flow. Alternatively, you can use the CLI: ```plaintext oz integration create linear --environment ``` The CLI will open a browser window prompting you to install the Oz app into your Linear workspace. After installation, the integration becomes available to all members of your Warp team. *** ### Uninstallation instructions [Section titled “Uninstallation instructions”](#uninstallation-instructions) To remove the Oz integration from Linear: 1. Only a Linear team admin can manage app permissions. 2. In Linear, go to **Settings**. 3. Navigate to Agents under the Features section. 4. Select Oz from the list of installed agents. 5. Click **Revoke access** to remove the integration for your workspace. After revoking access, Warp will no longer be able to read issues, receive triggers, or create updates in Linear. If you reinstall later, you’ll need to authorize Warp again during setup. ### Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) If something isn’t working as expected—missing repos, PR failures, Linear not detecting Oz, or environment issues—see our [Integrations Troubleshooting](/agent-platform/cloud-agents/integrations/#troubleshooting) page for detailed guidance on GitHub permissions, environment configuration, and common setup problems. # Integrations quickstart > Trigger your first Oz agent from Slack in ~15 minutes and get results in-thread. Oz integrations let you trigger cloud agents directly from the tools your team already uses. This guide walks you through connecting Oz to Slack. Once set up, anyone on your team can tag @Oz in a message or thread to kick off a cloud agent that runs the task and posts results back to the conversation. Note **Want to connect with Linear instead?** The setup is the same — just substitute `slack` with `linear` in the CLI commands, or select Linear in the Oz web app. See [Linear](/agent-platform/cloud-agents/integrations/linear/) for details. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Eligible plan** - The Slack integration requires a Warp team on Build, Max, or Business plan with at least 20 credits available. See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/). * **An Oz cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don’t have one yet, follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/) or run `/create-environment` in Warp. * **GitHub authorization** - Warp needs access to your repos to clone code and open PRs. You’ll be prompted to authorize the Warp GitHub app when you first create the integration. *** ## 1. Connect the Slack integration [Section titled “1. Connect the Slack integration”](#1-connect-the-slack-integration) The simplest way to set up the integration is **using the Oz web app**: 1. Navigate to the Oz web app at [oz.warp.dev/integrations](https://oz.warp.dev/integrations). 2. Click **Slack**. 3. Follow the guided flow to select your environment and authorize Oz in your Slack workspace. All members of your Warp team can now use the integration. **Using the Oz CLI instead:** Run `oz integration create` to connect the Slack integration: ```bash oz integration create slack --environment ``` Replace `` with your environment ID (see [Environments](/agent-platform/cloud-agents/environments/) if you need to create one). Find it with `oz environment list` on the Oz CLI or in the [Oz web app](https://oz.warp.dev). The CLI opens a browser window to authorize the Oz app in your workspace. To attach a default prompt that applies to every agent run triggered from this integration, add the `--prompt` flag: ```bash oz integration create slack \ --environment \ --prompt "Always open a draft PR and request review from the team-leads group." ``` ## 2. Tag @Oz in Slack [Section titled “2. Tag @Oz in Slack”](#2-tag-oz-in-slack) In any channel or thread in your Slack workspace, tag @Oz with a task: > @Oz scan the authentication module for security issues and summarize what you find Oz acknowledges the request immediately and starts an agent run in the cloud. You’ll see progress updates appear in the thread as the agent works. You can also tag @Oz inside an existing thread. Oz picks up the full thread history as context automatically, so you can tag it mid-discussion without repeating background. ## 3. Watch the run [Section titled “3. Watch the run”](#3-watch-the-run) While the agent works, progress updates appear directly in the Slack thread. To inspect the run in more detail: * **Click the session link** - Oz posts a link in the thread to open a live terminal view of the agent. Watch in real time, add follow-up instructions, or let it run to completion. * **Go to [oz.warp.dev/runs](https://oz.warp.dev/runs)** - See the full run transcript: status, commands executed, files changed, and agent output. See [Viewing Cloud Agent Runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) for a complete walkthrough. When the task is complete, Oz posts a summary back to the original Slack thread. **Breaking it down:** Oz reads the Slack thread as context, runs the agent inside the environment you configured — with your repos cloned and Docker image running — and returns results where the conversation started, in Slack, without anyone leaving the thread. *** ## Next steps [Section titled “Next steps”](#next-steps) * **Customize agent behavior** - Use a [skill](/agent-platform/cloud-agents/skills-as-agents/) as the base prompt for your integration to give Oz consistent, reusable instructions across every run. * **Trigger agents programmatically** - Use the [API & SDK](/reference/api-and-sdk/) to build custom automations and integrations on top of Oz agents. * **Read the full Slack reference** - [Slack](/agent-platform/cloud-agents/integrations/slack/) covers identity mapping, team access, monitoring runs, troubleshooting, and uninstall instructions. # GitHub Actions quickstart > Set up your first Oz agent in GitHub Actions in ~10 minutes. Run agents as workflow steps to automate code review and issue triage. Add Oz agents to your GitHub Actions workflows with [`oz-agent-action`](https://github.com/warpdotdev/oz-agent-action). This quickstart walks you through setting up your first GitHub Actions integration: a PR review workflow that automatically analyzes pull requests and posts inline review comments. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Warp API key** - In the Warp app, click your profile photo, then go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create one. Use a personal key if the agent needs to write to your repo. See [API Keys](/reference/cli/api-keys/) for details. * **A GitHub repository with Actions enabled** - The workflow file will live in `.github/workflows/` in your repo. *** ## 1. Add your API key as a GitHub Actions secret [Section titled “1. Add your API key as a GitHub Actions secret”](#1-add-your-api-key-as-a-github-actions-secret) Store your Warp API key as a GitHub Actions secret so workflows can authenticate without exposing the key in your code. 1. In your repository on GitHub, go to **Settings** > **Secrets and variables** > **Actions**. 2. Click **New repository secret**. 3. Set the name to `WARP_API_KEY`. 4. Paste your API key into the **Secret** field. 5. Click **Add secret**. ## 2. Create the workflow file [Section titled “2. Create the workflow file”](#2-create-the-workflow-file) This workflow triggers an Oz agent whenever a PR is opened or marked ready for review. The agent reviews the diff and posts inline comments. Create `.github/workflows/oz-pr-review.yml` in your repository with the following content: ```yaml name: Oz PR review on: pull_request: types: [opened, ready_for_review] permissions: contents: read pull-requests: write jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Review PR with Oz uses: warpdotdev/oz-agent-action@v1 with: prompt: | Review the code changes on this pull request: 1. Use `git diff origin/${{ github.base_ref }}...HEAD` to identify changes. 2. Analyze the diff for style, security, or correctness issues. 3. Use `gh pr review --comment` to post inline suggestions. warp_api_key: ${{ secrets.WARP_API_KEY }} ``` This workflow listens for pull request events and runs the `oz-agent-action` step, which executes the prompt to review code changes. Commit and push this file to your default branch to activate the workflow. ## 3. Open a pull request [Section titled “3. Open a pull request”](#3-open-a-pull-request) Create a new pull request in your repository to trigger the workflow. To verify the workflow ran: 1. Go to the **Actions** tab in your repository. 2. Click **Oz PR review** in the list of workflows. 3. Select the most recent run to see the agent’s output in the job logs. ## 4. View the run [Section titled “4. View the run”](#4-view-the-run) Each `oz-agent-action` step creates a cloud agent run you can inspect from the Oz dashboard: * **Oz web app** - Go to [oz.warp.dev/runs](https://oz.warp.dev/runs) to see the full run transcript: status, commands executed, files changed, and agent output. See [Viewing Cloud Agent Runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) for a complete walkthrough. * **Warp app** - Open the conversations panel to see the run alongside your other agent activity. When the run completes, the agent posts feedback as inline review comments on the PR. **Breaking it down:** The agent runs in Warp’s cloud infrastructure — not on GitHub’s runners — using the workflow’s GitHub token for repository access. Each run is isolated, tracked, and auditable, just like any manually triggered cloud agent run. *** ## Next steps [Section titled “Next steps”](#next-steps) * **Explore more workflow patterns** - The [oz-agent-action repository](https://github.com/warpdotdev/oz-agent-action) includes ready-to-use consumer workflow templates for responding to `@oz-agent` comments, auto-fixing labeled issues, daily issue summaries, fixing failing CI checks, and suggesting review fixes. Copy any template from `consumer-workflows/` into `.github/workflows/` in your repo. * **Use skills for reusable behavior** - Replace the inline `prompt` with a `skill` parameter to apply consistent, version-controlled instructions across all your CI workflows. See [Skills](/agent-platform/capabilities/skills/). * **Read the full reference** - [GitHub Actions](/agent-platform/cloud-agents/integrations/github-actions/) covers all action inputs, output handling, session sharing for debugging, and troubleshooting. # Slack integration > Trigger Oz agents from Slack to run cloud tasks, track progress, and create pull requests. ### Overview [Section titled “Overview”](#overview) The Slack integration lets your team trigger agents directly from conversations in Slack. When you tag **@Oz** in a message or DM the bot, Warp will start an agent in the cloud, clone the repositories defined in your environment, and begin working through the task with full context from your codebase and the Slack thread. Agents keep you updated as they work, generate pull requests using your GitHub account, and share a link to a live remote session so you can watch or guide the workflow in real time. This page explains what the integration does, how it behaves inside Slack, and how to configure it for your Warp team. *** ### Using Oz inside Slack [Section titled “Using Oz inside Slack”](#using-oz-inside-slack) Tagging @Oz in a message or thread starts an agent run. The agent clones the repositories in your environment, sets up your development environment using your Docker image and setup commands, and begins working with the context from the Slack conversation. Oz posts updates back into the thread as it progresses so you can follow along without opening your terminal. Agents also share a link to an interactive remote session using Warp’s [cloud agent session sharing](/agent-platform/cloud-agents/viewing-cloud-agent-runs/). Opening this link gives you a live terminal view of the cloud agent running your code. You can interrupt or steer the agent by providing additional instructions, and the agent will pick up where it left off with the new context. When the work is complete, Warp will create a pull request on your behalf using your GitHub permissions and send a summary and PR link back to the original Slack thread. ### Triggering an agent [Section titled “Triggering an agent”](#triggering-an-agent) You can start an agent in three ways: * **Tag @Oz in a channel message** Describe the task, and Oz will begin working with full context from the thread. * **Tag @Oz inside a thread** Oz will automatically collect the thread’s prior messages and use them as context. * **DM Oz directly** Useful for private tasks or experimentation. Oz will acknowledge the request in Slack and start running the task immediately. ### Monitoring agent progress [Section titled “Monitoring agent progress”](#monitoring-agent-progress) Agents keep you informed directly in Slack via: * Activity updates showing progress throughout the run * An evolving task list and timeline * Checkpoints indicating major steps completed * A direct link to the Oz run in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/), where you can view the full run transcript and metadata * A session-sharing link that opens a live terminal view of the remote agent [Cloud agent session sharing](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) works in Warp or in your browser and supports multiple teammates joining the same live session. ### Joining the live remote session [Section titled “Joining the live remote session”](#joining-the-live-remote-session) Selecting `View agent` opens the active agent session. Inside the session you’ll see: * The agent’s full execution log * The plan/task list * Real-time output just like a local Warp task * An input box for follow-up instructions Any instruction you type will interrupt the agent, incorporate the new guidance, and then resume execution. This is the best way to debug or steer multi-step tasks. ### Pull requests and output [Section titled “Pull requests and output”](#pull-requests-and-output) Once the agent finishes, it will: * Commit changes using your GitHub account * Create a pull request via the GitHub CLI * Generate a clean title and description referencing your Slack request * Post the summary and PR link directly into the Slack thread Because PRs are created as you, the workflow slots seamlessly into your team’s existing review process. *** ### Requirements [Section titled “Requirements”](#requirements) * **Team membership** - The Slack integration requires you to be part of a [Warp team](/knowledge-and-collaboration/teams/). Teams can be created on any plan, including Free. * **Plan and credits** - Your team must be on a plan that supports integrations (Build, Max, or Business) and have at least 20 credits available (any type of Warp credits work). See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details. * **Infrastructure** - By default, agents run on Warp-hosted infrastructure. Enterprise teams can [self-host agents](/agent-platform/cloud-agents/self-hosting/) on their own infrastructure. * **Identity** - You must be logged into Warp with the same email used in your Slack workspace. * **GitHub authorization** - You must authorize the **Warp GitHub app** the first time you trigger a Slack integration request. * The repositories involved must be included in your environment and accessible to the Warp GitHub app. * You must have write access for Warp to open PRs on your behalf. ### How to configure the Slack integration [Section titled “How to configure the Slack integration”](#how-to-configure-the-slack-integration) Setup involves two steps, powered by the [Oz CLI](/reference/cli/). #### 1. Create an environment [Section titled “1. Create an environment”](#1-create-an-environment) An environment defines everything the agent needs to run your code in the cloud: * A Docker image (public on Docker Hub) * The GitHub repos the agent should clone * Optional setup commands that run before the agent starts Create an environment via: * **Oz CLI** ```bash oz environment create \ --name \ --docker-image \ --repo \ --setup-command "" ``` * **Guided setup using `/create-environment`** ( [Slash Commands](/agent-platform/capabilities/slash-commands/)) This flow analyzes your repos, recommends a Docker image, suggests setup commands, and can build + push a custom image if needed. See the [Environment Setup](/agent-platform/cloud-agents/integrations/) docs for detailed instructions. #### 2. Create the Slack integration [Section titled “2. Create the Slack integration”](#2-create-the-slack-integration) Once your environment is ready, create the integration. Note For easier setup, use the [Oz web app](https://oz.warp.dev) to configure integrations with a guided flow. Alternatively, use the CLI: ```plaintext oz integration create slack --environment ``` The CLI will open a browser window to install the Oz app into your Slack workspace. After installation, the integration becomes available to all members of your Warp team. You can optionally attach a custom prompt that is applied to every agent run: ```plaintext oz integration create slack \ --environment \ --prompt "Always prefix PR titles with '[WARP]' and include detailed test steps." ``` ### Identity mapping and team access [Section titled “Identity mapping and team access”](#identity-mapping-and-team-access) * Integrations are scoped to your Warp team. * Any teammate in the same Slack workspace and Warp team can use the integration. * Warp maps Slack users to Warp accounts by email address. * Teammates must individually authorize GitHub on their first run. *** ### Uninstallation instructions [Section titled “Uninstallation instructions”](#uninstallation-instructions) To remove the Oz app from your Slack workspace: 1. Open Slack and go to **Apps** in the left sidebar. 2. Search for Oz. 3. Select the app, then open the **About** tab. 4. Click **Configuration**. This will open your workspace’s app configuration page in the browser. 5. Scroll to the bottom and select **Remove App**. 6. Confirm the removal. ![Warpy is just an internal Slackbot, your Warp slackbot should be called Oz.](/_astro/delete-warpy.DmayB7Fo_Z7bswT.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Oz Slackbot in Slack. ![Confirmation dialog to remove the Oz app from a Slack workspace.](/_astro/remove-slack-app.DOqrl9gO_2d2xih.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Once removed, Slack will immediately disable the integration for all teammates. ### Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) If something isn’t working—missing repos, Slack not detecting @Oz, PR failures, or environment configuration issues—see the [Integrations Troubleshooting](/agent-platform/cloud-agents/integrations/#troubleshooting) page. It covers: * GitHub authorization and repo access * Docker image pull errors * Environment visibility * Email and identity mismatches * Integration installation issues # Managing Cloud Agents > Monitor and manage cloud agent activity across your team with Warp's centralized management view, including filtering, status tracking, and session inspection. Warp provides a centralized management view where you can monitor agent activity across your account and (where applicable) your team. You can access this view in the Warp app or through the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) at [oz.warp.dev](https://oz.warp.dev), which works on mobile devices. The management view is designed to answer, at a glance: * Which agents have been running recently (and what’s running right now) * Which runs succeeded, failed, or were canceled * Where an agent run was triggered from (a local agent conversation, the Oz CLI, Slack, etc.) * How many credits those runs consumed This management view includes your **local (interactive) agents** and [cloud agent](/agent-platform/cloud-agents/overview/) runs. ![Warp's management view showing interactive and cloud agent runs.](/_astro/management-view-scannable-list.Pmn3h7Ez_1HmQt6.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Warp’s management view showing interactive and cloud agent runs. ### What appears in the management view [Section titled “What appears in the management view”](#what-appears-in-the-management-view) The management view includes two categories of agent activity. #### Interactive agents [Section titled “Interactive agents”](#interactive-agents) * Initiated from the Warp desktop app. * The conversation is owned by you. It opens locally in Warp, and can be shared via a link when needed. * Credit usage reflects inference. #### Cloud agent runs [Section titled “Cloud agent runs”](#cloud-agent-runs) * Background executions initiated by triggers such as integrations and automations (for example: Slack, Linear, schedules, GitHub Actions, or API/CLI invocations). * Each run produces a shared session that can be inspected after completion (including logs, messages, and outputs). * Credit usage reflects inference + compute, shown as a single combined value in this view. Caution All usage rolls up into Warp’s standard [**credit**](/support-and-community/plans-and-billing/credits/) system. In the **Personal** tab, you can view all of the interactive and cloud agent conversations that you own. In the **All** tab, you can see everything from the personal tab, as well as any cloud agent sessions that are shared with you by your teammates; right now, this only includes things triggered from integrations. *** ### The agents list [Section titled “The agents list”](#the-agents-list) Each row represents a single item in the management view (either an interactive conversation or a cloud agent run). The list is intended to be scannable: you should be able to understand “what happened” without opening anything. #### Fields you’ll see [Section titled “Fields you’ll see”](#fields-youll-see) **Source** Where the agent was launched from. Common sources include: * **Interactive:** an [agent conversation](/agent-platform/local-agents/overview/) started in the Warp app * **CLI**: a local run triggered by the [Oz CLI](/reference/cli/) * **API**: a run triggered by [Warp’s API](/reference/api-and-sdk/) * **Slack / Linear**: runs triggered by [integrations](/agent-platform/cloud-agents/integrations/) * **Scheduled**: runs triggered on a [cron schedule](/agent-platform/cloud-agents/triggers/scheduled-agents/) **Status** Warp uses a small set of statuses to help you quickly identify what needs attention: | Status | Icon | Description | | ------------------ | ---- | -------------------------------------------------------------------------------- | | `Working` | N/A | in progress (may include queued / running states) | | `Blocked` | 🟨 | *(interactive only)*the conversation is waiting on user input or a required step | | `Canceled` | ⬜️ | (interactive only) the interactive conversation was canceled before completion | | `Failed / Errored` | 🔺 | something went wrong (applies to both interactive and cloud agent runs) | | `Success` | ✅ | completed successfully (applies to both interactive and cloud agent runs) | **Duration (for cloud agent tasks)** * Shown for cloud agent runs to indicate how long the task executed. * Note: Interactive conversations generally don’t map cleanly to a single “run duration,” so this is currently omitted. *** ### Inspecting an agent [Section titled “Inspecting an agent”](#inspecting-an-agent) **The primary interaction is simple:** * Clicking a cloud agent row opens the [shared session](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) for that run (logs/messages/output). * Clicking an interactive row opens the conversation locally in the Warp app. This makes the management view a navigation surface: find the thing you care about, click once, and you’re in the right context to inspect or continue work. ### Filtering [Section titled “Filtering”](#filtering) In both *Personal* and *All* views, you can open the filter menu and filter by: * Source (interactive, API, CLI, Slack/Linear, scheduled) * Day of creation * Creator * Status This is the fastest way to isolate “everything that failed today,” “runs from Slack,” or “what a specific teammate triggered via integrations.” # MCP Servers for cloud agents > Connect cloud agents to external tools, APIs, and internal services using MCP servers. Cloud agents can call external tools through [Model Context Protocol (MCP) servers](/agent-platform/capabilities/mcp/). This lets agents reach beyond the terminal to automatically interact with systems like GitHub, dbt, Sentry, or any custom internal service, whenever the workflow requires it. ## When to use MCP servers [Section titled “When to use MCP servers”](#when-to-use-mcp-servers) Add MCP servers to a cloud agent when it needs to: * Read from or write to an external API (issue trackers, monitoring tools, cloud services) * Call local processes that expose MCP endpoints * Use internal developer tools that you’ve wrapped in an MCP interface The agent calls MCP tools automatically based on what the task requires, without the need for explicit instruction. ## How MCP configuration works [Section titled “How MCP configuration works”](#how-mcp-configuration-works) You can supply MCP configuration in two ways: * **At run time** — pass `--mcp` when calling `oz agent run` or `oz agent run-cloud`. See [MCP Servers](/reference/cli/mcp-servers/) in the CLI reference for the full syntax. * **In an agent config file** — define `mcp_servers` directly in a YAML or JSON agent config file (passed with `-f / --file`). This is the recommended approach for repeatable workflows. ## Configuration schema [Section titled “Configuration schema”](#configuration-schema) Each MCP server entry is keyed by a name you choose. A server config must have **exactly one** transport type: | Transport | Field(s) | When to use | | --------------------- | ----------------- | -------------------------------------------------------------- | | Warp-shared server | `warp_id` | Reference an MCP server already configured in Warp by its UUID | | Stdio (local process) | `command`, `args` | Launch a local executable as an MCP server | | Streamable HTTP / SSE | `url` | Connect to a remote or locally hosted MCP endpoint | ### Supported fields [Section titled “Supported fields”](#supported-fields) * **`warp_id`** — UUID of a Warp-shared MCP server (find UUIDs with `oz mcp list` or from **Settings** > **Agents** > **MCP servers**) * **`command`** — Executable to launch (stdio transport) * **`args`** — Arguments passed to `command` (only valid with `command`) * **`env`** — Environment variables passed to the process (only valid with `command`) * **`url`** — HTTP or HTTPS endpoint URL (streamable HTTP or SSE transport) * **`headers`** — HTTP headers sent with requests (only valid with `url`) You may define any number of MCP servers in a single config. ### Example configuration [Section titled “Example configuration”](#example-configuration) ```json { "github": { "url": "https://mcp.example.com/github" }, "dbt": { "command": "uvx", "args": ["dbt-mcp"], "env": { "DBT_HOST": "https://example.us1.dbt.com", "DBT_SERVICE_TOKEN": "${DBT_SERVICE_TOKEN}" } } } ``` ## Using MCP servers in an agent config file [Section titled “Using MCP servers in an agent config file”](#using-mcp-servers-in-an-agent-config-file) For repeatable cloud agent workflows, declare your MCP servers inside the agent config file passed to `-f / --file`: ```json { "name": "my-production-agent", "model_id": "claude-sonnet-4", "system_prompt": "You are a helpful assistant focused on backend development.", "environment_id": "SVhg783GBFQHk1OfdPfFU9", "mcp_servers": { "github": { "url": "https://mcp.example.com/github" }, "dbt": { "command": "uvx", "args": ["dbt-mcp"], "env": { "DBT_HOST": "https://example.us1.dbt.com", "DBT_SERVICE_TOKEN": "${DBT_SERVICE_TOKEN}" } } } } ``` Pass this file when running a cloud agent: ```sh oz agent run-cloud --environment -f my-agent-config.json --prompt "Check for regressions in the last deploy" ``` ## Requirements and defaults [Section titled “Requirements and defaults”](#requirements-and-defaults) * MCP configuration must be valid JSON, or YAML when embedded in a broader agent config file. * If `mcp_servers` is omitted, the agent runs with no MCP servers enabled. * Each server name must be unique and non-empty. * The `warp_id` transport is validated against your Warp account. Referenced servers must be accessible to you. ## Limitations [Section titled “Limitations”](#limitations) Caution Warp does not currently support OAuth-based MCP servers for cloud agents. This means MCP servers that require browser-based authentication, like some hosted Figma configurations, cannot be used directly. As a workaround, you can pass Figma mockups as **image context** to the agent, which can then build and test UI against those images. ## Learn more [Section titled “Learn more”](#learn-more) * [MCP Servers (CLI reference)](/reference/cli/mcp-servers/) — how to pass MCP configuration using the `--mcp` flag * [Model Context Protocol (MCP)](/agent-platform/capabilities/mcp/) — configuring MCP servers in Warp for local agents * [Environments](/agent-platform/cloud-agents/environments/) — set up the runtime context (repo, image, startup commands) for cloud agent tasks * [Secrets](/agent-platform/cloud-agents/secrets/) — store and inject credentials into agent runs safely # Cloud agents overview > Run background agents in the cloud from events, schedules, or integrations with team-wide observability. Oz Cloud Agents are **cloud-connected**, **background agents** that run on the [Oz Platform](/agent-platform/cloud-agents/platform/). **New to cloud agents?** Start with the [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/) to run your first cloud agent in \~10 minutes. ![YouTube video](https://i.ytimg.com/vi/poLkJhO7fdo/sddefault.jpg) ### What cloud agents are designed for [Section titled “What cloud agents are designed for”](#what-cloud-agents-are-designed-for) Cloud agents are designed for situations where: * **You need agents to react to system events.** * Examples include crashes, bug reports, Slack interactions, cron timers, or CI steps. * **You want observability into agent activity across a team or system.** * This includes being able to see what ran, when it ran, and what it did. * **You need more parallelism than local execution typically allows.** * For example, running many agent tasks concurrently in the cloud, sharding a repo-wide task into multiple runs, or fanning out the same task across multiple targets. * **You want agents to operate continuously as part of engineering infrastructure.** * This includes scheduled maintenance tasks and integration-driven automation. ![Oz use cases across the development lifecycle: Plan, Prototype, Build, Validate, Review + Merge, Deploy + Monitor](/_astro/oz-use-cases.C7LxcjFI_ZUdyDU.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) *** ### What is a cloud agent run? [Section titled “What is a cloud agent run?”](#what-is-a-cloud-agent-run) A cloud agent run is represented as an agent task. A task is created when a trigger fires (for example a webhook event or schedule) or when a user starts a run explicitly. Each task includes: * **Inputs**: a prompt, and often additional context from the triggering system (for example a Slack message, PR metadata, or CI logs). * **Execution context (optional)**: an [Environment](/agent-platform/cloud-agents/environments/) that defines the repo, image, and startup commands the agent should run with. * **Lifecycle state**: created → running → completed / failed. * **Persistent record**: status, metadata, and a session transcript that can be reviewed after the task completes. Note If you are evaluating whether something should be a cloud agent, a good test is whether you can define:\ (1) what triggers it, (2) what context it needs, and (3) how the team will inspect or validate the output. ### How cloud agents work [Section titled “How cloud agents work”](#how-cloud-agents-work) Cloud agents run on the [Oz Platform](/agent-platform/cloud-agents/platform/), which provides the primitives for triggering work, orchestrating tasks, executing agents (optionally in environments), injecting secrets, and inspecting results. * Something **triggers** an agent task. * The **orchestrator creates** and tracks the task. * The agent **executes** on a host, optionally inside an [environment](/agent-platform/cloud-agents/environments/), with whatever [secrets](/agent-platform/cloud-agents/secrets/) and credentials it needs. The exact way tasks are triggered and executed depends on your deployment model (for example CLI-only, Warp-hosted orchestration, or self-hosted execution). Those options are covered in the [Deployment Patterns](/agent-platform/cloud-agents/deployment-patterns/) pages. For teams that need execution to stay within their network boundary, self-hosting supports two architectures: a **managed** worker daemon that lets Oz orchestrate agents in Docker containers on your machines, and an **unmanaged** mode where you run `oz agent run` directly in your CI, Kubernetes, or dev environment. See [Self-Hosting](/agent-platform/cloud-agents/self-hosting/) for details. ### What you get by default [Section titled “What you get by default”](#what-you-get-by-default) Because cloud agents run on the [Oz Platform](/agent-platform/cloud-agents/platform/), each run is tracked and produces a persistent record that can be observed, shared, and audited (even if execution happens outside the Warp app). #### Codebase Context [Section titled “Codebase Context”](#codebase-context) Cloud agent runs automatically benefit from [Codebase Context](/agent-platform/capabilities/codebase-context/) for semantic code understanding and search, as long as Codebase Context is enabled for your account. See [Codebase Context in cloud agent runs](/agent-platform/capabilities/codebase-context/#codebase-context-in-cloud-agent-runs) for details. #### Observability and steerability [Section titled “Observability and steerability”](#observability-and-steerability) Cloud agent tasks are designed to be inspectable by the team: * [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) lets authorized teammates attach to a running task to monitor progress and, where supported, steer the agent while it runs. * Each run produces a session transcript and task metadata, which provides a record of what the agent did. * A [management experience](/agent-platform/cloud-agents/managing-cloud-agents/) surfaces task status and history. #### Centralized configuration [Section titled “Centralized configuration”](#centralized-configuration) Cloud agent workflows often rely on shared configuration such as [MCP servers](/agent-platform/cloud-agents/mcp/), rules, saved prompts, environment variables, and [secrets](/agent-platform/cloud-agents/secrets/). Warp supports centralized configuration so the same workflow behaves consistently across triggers (for example Slack + CI + schedules), without duplicating setup in every system. For details on configuring MCP servers for cloud agents, see [MCP Servers](/agent-platform/cloud-agents/mcp/). #### API access to tasks [Section titled “API access to tasks”](#api-access-to-tasks) The Oz Platform exposes task visibility via the [**Oz API and SDKs**](/reference/api-and-sdk/), so teams can: * Query which tasks are running or have run. * Fetch task metadata and outcomes. * Build internal dashboards or monitoring (for example success rates, runtime, failure reasons). ### Using cloud agents with or without the Warp app [Section titled “Using cloud agents with or without the Warp app”](#using-cloud-agents-with-or-without-the-warp-app) Cloud agents do not require the Warp desktop app. Teams can deploy and operate them through the [Oz Platform](/agent-platform/cloud-agents/platform/) using: * [Oz CLI](/reference/cli/) — run agents from scripts, CI, or the terminal * [Oz web app](/agent-platform/cloud-agents/oz-web-app/) — visual interface for managing runs, schedules, environments, and integrations (works on mobile) * [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) — attach to running tasks to monitor or steer * [Agent Management UX](/agent-platform/cloud-agents/managing-cloud-agents/) — view agent activity and run history * [APIs and SDKs](/reference/api-and-sdk/) — programmatic access for custom integrations If your team also uses Warp’s terminal, you get an additional workflow: tasks launched via the CLI can be handed off into an interactive session for review, edits, or continuation. *** ### Billing and plan requirements [Section titled “Billing and plan requirements”](#billing-and-plan-requirements) Cloud agents and [integrations](/agent-platform/cloud-agents/integrations/) run on the [Oz Platform](/agent-platform/cloud-agents/platform/) control plane, and usage is billed using credits. Note [Bring Your Own Key (BYOK)](/support-and-community/plans-and-billing/bring-your-own-api-key/) is not supported for cloud agent runs. BYOK keys are stored locally on your device and are not accessible to cloud-hosted agents. All cloud agent runs consume Warp credits. #### For Cloud Agents via CLI/API [Section titled “For Cloud Agents via CLI/API”](#for-cloud-agents-via-cliapi) Individual users can run cloud agents without being on a team. Requirements: * You need at least 20 credits (any type: normal Warp credits, [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits), or Build plan credits) * Cloud agents run on Warp-hosted infrastructure * Self-hosted agents require a team subscription #### For Integrations (Slack/Linear) [Section titled “For Integrations (Slack/Linear)”](#for-integrations-slacklinear) Integrations require you to be part of a [Warp team](/knowledge-and-collaboration/teams/) and additional requirements: * **Plan requirements** * **Supported plans**: Build, Max, Business * Not supported: Pro, Turbo, Lightspeed, legacy Business * Your plan must support Add-on Credits. * **Credit requirements** * Your team must have at least 20 credits available (any type of Warp credits work) to run cloud agents and integrations. * Usage is billed based on credit type and team configuration. * Normal credits, [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits), and [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) all work. For more details, see [Access, Billing, and Identity Permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/). Caution If your credit balance reaches zero, cloud agent runs will not be able to execute until credits are replenished. *** ### Learn more [Section titled “Learn more”](#learn-more) * [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/) — run your first cloud agent with an environment in \~10 minutes. * [Oz Platform](/agent-platform/cloud-agents/platform/) — CLI, Oz API/SDK, orchestration, tasks, environments, hosts, integrations, and more. * [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/) — run agents based on reusable skill definitions from the CLI, web app, API, or on a schedule. * [Oz CLI](/reference/cli/) — shows how to run Oz agents in non-interactive mode from CI, scripts, or remote machines, including auth and common commands. * [Environments](/agent-platform/cloud-agents/environments/) — explains how environments provide the runtime context (repo, image, startup commands) for agent tasks. * [Oz API and SDK](/reference/api-and-sdk/) — documents the REST API for creating, querying, and monitoring agent tasks programmatically. * [Agent Secrets](/agent-platform/cloud-agents/secrets/) — covers how to store, scope, and inject credentials into agent runs safely. * [MCP Servers](/agent-platform/cloud-agents/mcp/) — how to configure MCP servers for agent tool access and how MCP configuration is applied across runs. * [Deployment Patterns](/agent-platform/cloud-agents/deployment-patterns/) (beta) — compares common ways to deploy cloud agents and when to use each. * [Access, Billing, and Identity Permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/) — explains individual and team-level requirements, credit billing behavior, and the permission model for who can run, view, and steer cloud agent tasks. # Oz Web App for cloud agents > Use the Oz web app to manage cloud agents, view runs, create schedules, and configure environments and integrations from any browser or mobile device. The [Oz web app](https://oz.warp.dev) provides a visual interface for managing cloud agents. You can start runs, browse agents, create schedules, configure environments, and set up integrations—all without installing Warp or using the CLI. Note The Oz web app works on mobile devices, so you can monitor and manage your cloud agents from anywhere. Watch this short demo to create an environment and run an agent using the Oz web app: ![YouTube video](https://i.ytimg.com/vi/h9Wd77leIYg/sddefault.jpg) ## Quick reference [Section titled “Quick reference”](#quick-reference) | Page | Path | What you can do | | ---------------- | --------------- | -------------------------------------------------------------------------------------- | | **Dashboard** | `/dashboard` | Quick actions, suggested agents, recent agents, and featured reads | | **Runs** | `/runs` | View all runs, filter by status/source/creator, start new runs, inspect transcripts | | **Agents** | `/agents` | Browse skills from your environments, view suggested skills, dispatch skills as agents | | **Schedules** | `/schedules` | Create scheduled agents, pause/enable schedules, view run history | | **Environments** | `/environments` | Create and manage environments with repos, Docker images, and setup commands | | **Integrations** | `/integrations` | Connect Slack and Linear to trigger agents from external tools | ![The Oz Web App's management view.](/_astro/oz-web-app-runs-view.C3yU3nWA_Z1e0Gq6.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Oz web app management view. ## When to use the web app [Section titled “When to use the web app”](#when-to-use-the-web-app) The Oz web app is ideal when you want to: * **Monitor agent activity** — View runs, check status, and inspect outputs from any device * **Start quick runs** — Dispatch agents without opening a terminal * **Manage schedules visually** — Create and edit scheduled agents with a guided interface * **Configure environments** — Set up repos, Docker images, and setup commands through a form-based flow * **Set up integrations** — Connect Slack and Linear with a guided setup flow For scripting, automation, and CI/CD workflows, use the [Oz CLI](/reference/cli/) or [API](/reference/api-and-sdk/). *** ## Getting started [Section titled “Getting started”](#getting-started) When you first sign in to the Oz web app, you’ll see a guided onboarding flow that helps you get started based on your goals. The onboarding asks “What brings you to Oz?” and offers three paths: * **Create an agent automation** — Walks you through setting up a scheduled agent, integration-triggered agent, or other automation * **Run Oz Cloud Agents in Warp** — Opens the Warp desktop app (or takes you to the download page) to run cloud agents interactively * **Build an app that uses agents** — Links to the [Oz Platform](/agent-platform/cloud-agents/platform/) docs for using the CLI, SDK, or API You can skip onboarding at any time to go directly to the Runs page. *** ## Dashboard [Section titled “Dashboard”](#dashboard) The **Dashboard** page (`/dashboard`) is your starting point for common actions and discovery. It provides quick access to the features you use most. ### Quick actions [Section titled “Quick actions”](#quick-actions) Four action cards at the top let you immediately: * **New run** — Start a cloud agent run * **New agent** — Create a new skill * **New schedule** — Set up a scheduled agent * **New environment** — Configure a new execution environment Each action opens a guided side pane without leaving the Dashboard. ### Suggested agents [Section titled “Suggested agents”](#suggested-agents) A curated list of pre-built skills from Warp’s public [oz-skills repository](https://github.com/warpdotdev/oz-skills). Click **Run** on any suggested agent to start a run with that skill. ### Recent agents [Section titled “Recent agents”](#recent-agents) Shows the last three agents you’ve run, so you can quickly re-run common workflows. If you haven’t run any agents yet, you’ll see prompts to start a new run or create your first agent. ### Featured reads [Section titled “Featured reads”](#featured-reads) Links to curated articles and documentation to help you get the most out of Oz (visible on desktop). *** ## Runs [Section titled “Runs”](#runs) The **Runs** page (`/runs`) is your central view for monitoring cloud agent activity. It shows all runs across your account, including those triggered from the CLI, API, integrations, and schedules. ### Run details [Section titled “Run details”](#run-details) Each run displays the following information: | Field | Description | | --------------- | --------------------------------------------------------------------- | | **Status** | Working, succeeded, failed, canceled, errored, or blocked | | **Title** | The run’s title or prompt summary | | **Environment** | Which environment the agent ran in | | **Creator** | Who started the run | | **Source** | Where the run was triggered from (CLI, API, Slack, Linear, scheduled) | | **Artifacts** | Any outputs like PRs or files created | | **Credits** | How many credits the run consumed | Click any run to open the detail pane, where you can view the full transcript, artifacts, and metadata. ### Filtering and search [Section titled “Filtering and search”](#filtering-and-search) | Quick filter | Shows | | ------------- | --------------------------- | | **All** | All runs | | **Mine** | Only runs you created | | **Active** | Runs currently in progress | | **Failed** | Runs that failed | | **Recurring** | Runs triggered by schedules | You can also search by title, prompt, or skill name, and add advanced filters for source, status, creator, and date range. *** ### Starting a new run [Section titled “Starting a new run”](#starting-a-new-run) Note Click **New run** in the header to start a cloud agent. 1. **Select an agent (optional)** — Choose a skill to use as the base instructions, or select “Quick run” to run without a skill 2. **Select an environment** — Choose which environment the agent runs in 3. **Add a prompt** — Provide context and instructions for this specific run The skill provides base instructions; your prompt adds context for this particular execution. *** ## Agents [Section titled “Agents”](#agents) The **Agents** page (`/agents`) shows all skills available from your environments, plus suggested skills from Warp’s public [oz-skills repository](https://github.com/warpdotdev/oz-skills). ### Skill details [Section titled “Skill details”](#skill-details) Each skill displays: | Field | Description | | ---------------- | -------------------------------------------- | | **Name** | The skill’s identifier | | **Description** | What the skill does | | **Environments** | Which environments have access to this skill | ![The Agents page in the Oz Web App.](/_astro/oz-web-app-agents.C_9002ej_1aSY2N.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Agents page in the Oz web app. Filter by environment or switch to the **Suggested** tab to see pre-built skills for common workflows like code review, dependency updates, and documentation sync. ### Running a skill as an agent [Section titled “Running a skill as an agent”](#running-a-skill-as-an-agent) Click any skill to view its details, then click **Run** to start an agent with that skill. You can also click **New run** from the header to start a run with optional skill selection. Note For more details on how skills work with cloud agents, see [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/). ### Creating new agents [Section titled “Creating new agents”](#creating-new-agents) Click **New agent** to create a new skill. The guided flow helps you define the skill’s instructions, which are then available for future runs. ![Creating a new agent skill in the Oz Web App.](/_astro/oz-web-app-new-agent.Cc2_gAAi_2ekCiT.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Creating a new agent skill in the Oz web app. *** ## Schedules [Section titled “Schedules”](#schedules) The **Schedules** page (`/schedules`) lets you create and manage scheduled agents that run automatically on a cron schedule. ### Schedule details [Section titled “Schedule details”](#schedule-details) Each schedule displays: | Field | Description | | --------------- | ------------------------------------------------------------------------------ | | **Name** | A descriptive name for the scheduled task | | **Frequency** | Human-readable description of the cron schedule (e.g., “Every Monday at 10am”) | | **Next run** | When the schedule will next execute | | **Environment** | Which environment the scheduled agent runs in | | **Agent** | Which skill the schedule uses (if any) | | **Status** | Whether the schedule is active or paused | ![The Schedules page in the Oz Web App.](/_astro/oz-web-app-schedules.CiPmn9eL_Z22FMSo.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Schedules page in the Oz web app. *** ### Creating a schedule [Section titled “Creating a schedule”](#creating-a-schedule) Note Click **New schedule** in the header to create a scheduled agent. 1. **Name** — Give the schedule a descriptive name 2. **Frequency** — Set the cron schedule (with presets for common patterns) 3. **Environment** — Select the environment to run in 4. **Agent (optional)** — Choose a skill to use 5. **Prompt** — Define what the agent should do each time it runs *** ### Managing schedules [Section titled “Managing schedules”](#managing-schedules) Click any schedule to view its details and recent run history. From the detail pane, you can: * **Edit** the schedule configuration * **Pause** or **enable** the schedule * **Delete** the schedule * **View past runs** triggered by this schedule Note For CLI-based schedule management, see [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/). *** ## Environments [Section titled “Environments”](#environments) The **Environments** page (`/environments`) shows all environments configured for your account. Environments define the execution context for cloud agents, including repos, Docker images, and setup commands. ### Environment details [Section titled “Environment details”](#environment-details) Each environment displays: | Field | Description | | ------------------ | -------------------------------------- | | **Name** | The environment’s identifier | | **Docker image** | The container image used for execution | | **Repositories** | Which repos the agent can access | | **Setup commands** | Commands run before the agent starts | ![The Environments page in the Oz Web App.](/_astro/oz-web-app-environments.AFeoom-N_1sy3qW.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Environments page in the Oz web app. *** ### Creating an environment [Section titled “Creating an environment”](#creating-an-environment) Note Click **New environment** in the header to create a new environment. 1. **Name** — Give the environment a descriptive name 2. **Docker image** — Specify a Docker image (Warp provides prebuilt dev images, or use your own) 3. **Repositories** — Add GitHub repos the agent should have access to 4. **Setup commands** — Define commands to run when the environment starts (e.g., `npm install`) Note For advanced environment configuration, see [Environments](/agent-platform/cloud-agents/environments/) and the [CLI reference](/reference/cli/integration-setup/). *** ## Integrations [Section titled “Integrations”](#integrations) The **Integrations** page (`/integrations`) lets you configure first-party integrations with Slack and Linear. ### Available integrations [Section titled “Available integrations”](#available-integrations) | Integration | Description | | ----------- | ---------------------------------------------------------------------------------- | | **Slack** | Tag @Oz in messages or threads to trigger agents directly from Slack conversations | | **Linear** | Tag @Oz on issues to trigger agents from your issue tracker | ![The Integrations page in the Oz Web App.](/_astro/oz-web-app-integrations.nS54nztb_Z2gl1ih.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Integrations page in the Oz web app. ### Setting up an integration [Section titled “Setting up an integration”](#setting-up-an-integration) Click an integration to start the guided setup flow. You’ll authorize Warp to connect with the external service, select an environment, and configure any integration-specific settings. Note For detailed integration setup instructions, see [Slack](/agent-platform/cloud-agents/integrations/slack/) and [Linear](/agent-platform/cloud-agents/integrations/linear/). *** ## Related resources [Section titled “Related resources”](#related-resources) * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — Learn about cloud agents and when to use them * [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/) — Run agents based on reusable skill definitions * [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) — Run agents automatically on a cron schedule * [Environments](/agent-platform/cloud-agents/environments/) — Configure runtime context for cloud agents * [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) — Monitor agent activity and inspect runs * [Oz CLI](/reference/cli/) — Command-line interface for running agents * [Oz API & SDK](/reference/api-and-sdk/) — Programmatic access to cloud agents # Oz Platform overview > The Oz Platform provides the CLI, API/SDK, orchestration, environments, and observability for cloud agents. Cloud agents run on the **Oz Platform**. The platform gives you a consistent way to **trigger work**, **orchestrate and track tasks**, **execute agents** (in an optional [environment](/reference/cli/integration-setup/), on a host), and inspect outcomes with team visibility. First-party [integrations](/agent-platform/cloud-agents/integrations/) connect external events — like Slack messages, GitHub PRs, or CI failures — to cloud agents automatically. ![YouTube video](https://i.ytimg.com/vi/poLkJhO7fdo/sddefault.jpg) Note **New to cloud agents?** Start with the [Cloud agents quickstart](/agent-platform/cloud-agents/quickstart/) to run your first agent in \~10 minutes. **Most production setups follow the same flow:** 1. A **trigger** fires (schedule, integration event, CI step, webhook, API call, or manual run). 2. Warp’s **orchestration layer** creates a cloud agent task and tracks its lifecycle. 3. The agent executes on a **host**, optionally inside an environment, using the required configuration and credentials. 4. The task produces a **persistent record** (status, metadata, transcript, outputs) your team can review and manage. ![Oz Platform architecture showing Trigger, Agent, Environment, and Artifacts components](/_astro/most-flexible-platform-for-building-with-agents.7z7nd7gm_ZbYTbH.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ![Oz Platform detailed architecture showing components, triggers, orchestrator, and agent runners](/_astro/oz-diagram.B-Gg_8Tw_294hwH.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The sections below describe the Oz Platform primitives that power this flow, and how they compose. *** ### Key concepts [Section titled “Key concepts”](#key-concepts) Before diving into the components, it helps to align on a few terms: * **Trigger**: The event that starts work (for example: cron, Slack mention, PR opened, CI failure, “run now”). * **Task:** The unit of work Warp tracks. A task includes inputs, state, metadata, and an execution record (where it ran, what it did, and what it produced). * **Context**: Additional inputs attached to a task (for example: a Slack message, PR metadata, CI logs, repository diffs). * **Outputs:** What the task produced (for example: created a PR, posted a Slack reply, emitted a report, or just a transcript + summary). In practice: **triggers create tasks; tasks execute on a host (optionally in an environment); tasks produce outputs.** *** ### Oz CLI [Section titled “Oz CLI”](#oz-cli) The [Oz CLI](/reference/cli/) is the **headless interface** for running Oz agents in non-interactive mode. It’s commonly used in CI, scripts, and server environments where there is no interactive UI. For interactive workflows, use the [agent](/agent-platform/local-agents/overview/) embedded in Warp’s desktop app. A key property of the CLI is that it is **cloud-connected**. Even when an agent is started on a local machine or in CI, it reports progress to Warp’s servers. This enables team visibility, session sharing (where supported), and programmatic tracking through the API. #### When to use the CLI [Section titled “When to use the CLI”](#when-to-use-the-cli) Use the CLI when: * You want to run an agent anywhere (local machine, CI runner, remote dev box, server). * An external system is orchestrating runs (for example GitHub Actions, custom automation, incident tooling). * You want task observability and auditing without requiring Warp desktop. #### How it fits in the Oz Platform [Section titled “How it fits in the Oz Platform”](#how-it-fits-in-the-oz-platform) Depending on the command, the CLI typically: * Authenticates as you (or as a member of your team, if applicable). * Starts work by creating a task in the orchestrator (either directly via CLI commands, or indirectly via an integration/schedule). * Streams progress back to Warp for live observability and a persistent record. * Optionally attaches an environment and other configuration. #### Example (no environment) [Section titled “Example (no environment)”](#example-no-environment) You can also run an agent locally without an environment using a command like: ```bash oz agent run ... ``` *** ### Warp Orchestrator [Section titled “Warp Orchestrator”](#warp-orchestrator) The orchestration layer manages the lifecycle of cloud agent tasks. It creates tasks, tracks state transitions, and is the system of record for what’s running and what ran. #### What the orchestrator does [Section titled “What the orchestrator does”](#what-the-orchestrator-does) The orchestrator: * Runs on Warp’s servers (cloud control plane). * Creates tasks when triggers fire (integrations, schedules, API calls, or explicit starts). * Tracks lifecycle state (created → running → completed/failed) and associated metadata. * Exposes task lifecycle operations via the [Oz CLI](/reference/cli/) and a [REST API](/reference/api-and-sdk/) (create tasks, query history, and inspect status/outputs). * Powers SDKs (TypeScript/Python) for programmatic usage on top of the orchestrator API. #### When teams use the API/SDK [Section titled “When teams use the API/SDK”](#when-teams-use-the-apisdk) Teams typically use the API/SDK when: * Triggering agents from custom internal systems (incident tools, bots, internal automation). * Building internal dashboards or monitoring (success rates, runtime, failure reasons). * Coordinating many runs (fanout, sharding, queueing, retries, rate limiting at the app layer). * Creating higher-level workflows that treat tasks as building blocks. *** ### Environments [Section titled “Environments”](#environments) [Environments](/agent-platform/cloud-agents/environments/) define the execution context an agent should run in. **An Environment typically includes:** * A Docker image (toolchain and runtime). * One or more repositories (or a workspace definition). * Startup commands and configuration (setup steps, dependency install, bootstrapping). * Optional environment variables and other runtime settings. Note Environments are how teams make agent runs consistent across triggers (Slack, CI, schedules) and across hosts. #### Environments are optional [Section titled “Environments are optional”](#environments-are-optional) Agents can run without an environment (for example, against an existing local checkout or a CI workspace). Teams usually move to environments when they want stronger reproducibility, isolation, and standardization. #### When to use environments [Section titled “When to use environments”](#when-to-use-environments) Environments are recommended when: * The agent needs a consistent toolchain (linters, build tools, language runtimes). * You want repeatable execution across CI and cloud execution. * You want standard execution across a team (same repo state rules, same setup steps). * You want to reduce “works on my machine” variability across tasks. *** ### Oz API and SDK [Section titled “Oz API and SDK”](#oz-api-and-sdk) The Oz [Agent API](/reference/api-and-sdk/) is the HTTP interface to the Oz Platform. It lets you create and inspect cloud agent tasks from any system (CI, cron, backend services, internal tools), without requiring the Warp desktop app. **What you can do with the API** * Run an agent by submitting a prompt plus optional configuration (model, environment, MCP servers, base prompt, etc.). * Monitor execution by listing tasks and tracking state transitions over time (for example: `QUEUED` → `INPROGRESS` → `SUCCEEDED/FAILED`). * Inspect results and provenance by fetching a task’s full details, including the original prompt, creator/source metadata, session link, and resolved agent configuration. **Oz Agent SDKs** Oz provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDKs](https://github.com/warpdotdev/oz-sdk-typescript) that wrap the Oz API with: * Typed requests/responses (autocomplete, fewer schema mistakes) * Built-in retries and timeouts (with per-request overrides) * Consistent error types mapped to API status codes * Helpers for raw responses when you need headers/status/custom parsing If you’re building an integration (CI, Slack bots, internal tooling, orchestrators), the [SDKs](/reference/api-and-sdk/) are typically the quickest and safest starting point. **SDK vs raw REST** * Use the SDK when you want strong typing, standardized error handling, and easy concurrency patterns. * Use raw REST when you want minimal dependencies or full control over your HTTP client. Note For full endpoint semantics and schema definitions, please refer to the dedicated [API docs](/reference/api-and-sdk/) and Models/Schema reference, plus the [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) repos for the latest usage/examples. *** ### Execution hosts [Section titled “Execution hosts”](#execution-hosts) A host describes where the agent actually executes. Warp supports multiple execution models depending on your security, compliance, and operational requirements. #### Warp-hosted execution [Section titled “Warp-hosted execution”](#warp-hosted-execution) With Warp hosting: * Warp runs the environment on Warp-managed infrastructure. * This is the default model for teams that want the simplest setup and do not need execution to occur inside their network boundary. #### Self-hosted execution [Section titled “Self-hosted execution”](#self-hosted-execution) With self-hosting: * The agent runs on customer-managed infrastructure. * Oz orchestrator still manages lifecycle and observability. * This is used when teams want code and execution to remain on their own systems rather than being cloned or executed in Warp’s cloud. Note **Enterprise feature**: Self-hosted execution requires an Enterprise plan. See [Self-Hosting](/agent-platform/cloud-agents/self-hosting/) for setup instructions. *** ### Integrations [Section titled “Integrations”](#integrations) [Integrations](/agent-platform/cloud-agents/integrations/) connect external events to cloud agent tasks. When an event occurs in a third-party system, Warp creates a task with the relevant context and starts it automatically. Warp supports two integration models: * **First-party integrations** — Warp manages the event subscription and context extraction end to end. * **Custom integrations** — you handle event ingestion and filtering, then call the API or SDK to create tasks. #### First-party integrations [Section titled “First-party integrations”](#first-party-integrations) First-party integrations can be configured with a simple setup flow (for example via CLI): ```bash oz integration create … ``` Warp registers webhooks with the third-party system, receives events, extracts context (payload, metadata, links, logs), and creates a task — optionally in an [Environment](/agent-platform/cloud-agents/environments/). Examples of context extracted by first-party integrations: * [Slack](/agent-platform/cloud-agents/integrations/slack/): message text, channel, thread, and user identity * [GitHub](/agent-platform/cloud-agents/integrations/github-actions/): PR metadata, diffs, labels, and check results * CI: logs, job metadata, and artifacts #### Custom integrations [Section titled “Custom integrations”](#custom-integrations) With custom integrations, you own the webhook and event-handling logic. Your system receives an event, applies any filtering or enrichment you need, and then calls the Oz API (directly or via an SDK) to create a task. The resulting task is still a full Oz agent run — observable, manageable, and auditable like any other. Custom integrations are a good fit when: * You have internal event sources (custom tooling, proprietary systems). * You need custom filtering, routing, or enrichment before triggering an agent. * You want to implement your own permissioning, queueing, or governance around triggers. *** ### Secrets [Section titled “Secrets”](#secrets) Cloud agents often need credentials to access external systems (APIs, cloud providers, databases, internal tools, MCP servers). Warp provides a [secrets store](/agent-platform/cloud-agents/secrets/) that can inject secrets at runtime so agents can use authenticated tools without exposing secret values in logs or UI. #### What secrets are for [Section titled “What secrets are for”](#what-secrets-are-for) In most deployments, secrets power: * API keys and tokens (GitHub, Slack, Linear, internal APIs). * Shared team credentials (cloud providers, CI identities). * Database credentials (read-only query bots, reporting). * Credentials required by MCP servers (static tokens/keys). #### Scoping and control [Section titled “Scoping and control”](#scoping-and-control) Today, secrets support two scopes: * **Team secrets:** shared credentials available to the team (useful for shared infrastructure). * **Personal secrets**: credentials tied to an individual (useful when actions must be attributable to a specific person). *** ### Management and observability [Section titled “Management and observability”](#management-and-observability) Cloud agents are designed so task execution is visible to the team. While a task is executing, the agent reports progress and status back to Warp. After completion, the task retains a persistent record for review and debugging. Warp provides multiple surfaces for observability: * [Management UI](/agent-platform/cloud-agents/managing-cloud-agents/): lists tasks, status, timing, metadata, and history. * [Agent Session Sharing](/agent-platform/local-agents/session-sharing/): authorized teammates can attach to a running task to monitor and, where supported, steer it. * [APIs](/reference/api-and-sdk/) and SDKs: query task history, build monitoring, and generate reports. #### Access control [Section titled “Access control”](#access-control) **Access control is part of the model:** * Teams can restrict who can run, view, or intervene in agent tasks. * At the same time, organizations can enable system-wide visibility where appropriate for auditing and operations. ### Centralized configuration [Section titled “Centralized configuration”](#centralized-configuration) Cloud agent setups often include shared configuration such as: * [MCP Servers](/agent-platform/cloud-agents/mcp/) * [rules / guardrails](/agent-platform/capabilities/rules/) * [saved prompts](/knowledge-and-collaboration/warp-drive/prompts/) * [environment variables](/knowledge-and-collaboration/warp-drive/environment-variables/) * [secrets](/agent-platform/cloud-agents/secrets/) Warp supports centralized configuration so these settings apply consistently regardless of where a task is launched. This is especially useful when the same workflow can be triggered from multiple places (for example Slack, CI, and schedules). Instead of duplicating setup across systems, teams can keep configuration in one place and reuse it across triggers. ### Using the Oz Platform with or without the Warp app [Section titled “Using the Oz Platform with or without the Warp app”](#using-the-oz-platform-with-or-without-the-warp-app) [Cloud agents](/agent-platform/cloud-agents/overview/) do not require Warp’s desktop terminal. Teams can operate cloud agent workflows using: * [Oz CLI](/reference/cli/) — run agents from scripts, CI, or the terminal * [Oz web app](/agent-platform/cloud-agents/oz-web-app/) — visual interface at [oz.warp.dev](https://oz.warp.dev) for managing runs, schedules, environments, and integrations (works on mobile) * [Session sharing](/agent-platform/local-agents/session-sharing/) — attach to running tasks to monitor or steer * [Management UI](/agent-platform/cloud-agents/managing-cloud-agents/) — view agent activity and run history * [APIs and SDKs](/reference/api-and-sdk/) — programmatic access for custom integrations **If your team also uses Warp’s terminal, you gain an additional workflow:** * Tasks launched via the CLI can be handed off into an interactive session for review, edits, or continuation. * This is useful when you want a human checkpoint (final edits, validation, merge decisions) without losing the audit trail from the cloud agent run. # Cloud agents quickstart > Learn how to run your first Oz cloud agent in ~10 minutes. Cloud agents run in remote environments, enabling automation, scheduling, and team collaboration. **Oz cloud agents** run in a remote environment and can be triggered from events, schedules, integrations, or manually. This enables scaling agents off your laptop, automating development tasks, and building apps on top of agents. Oz handles the orchestration, execution, and observability. Cloud agents can run interactively (where you steer them in real-time) or autonomously (as background tasks). Each run creates a persistent session that your team can inspect, share, and query through the Warp app, the CLI, web app, or API. This guide walks you through running your first cloud agent with an environment in about 10 minutes. You’ll create an environment, if needed, and launch a cloud agent to help with a development task. **Common use cases for cloud agents:** * Launch parallel cloud coding agents to multithread complex development tasks * Automate repetitive development tasks (e.g., feature-flag cleanup, documentation updates, fixing server crashes) * Build apps on top of agents, like bug triage and incident response systems *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) Before you begin, make sure you have: * **Warp desktop app** - Download from [warp.dev](https://warp.dev) * **Warp account** - Create an account at [oz.warp.dev](https://oz.warp.dev) Note New to Warp? You’ll get credits to try cloud agents. You need at least 20 credits available to run cloud agents and integrations. *** ## Running your first Oz cloud agent [Section titled “Running your first Oz cloud agent”](#running-your-first-oz-cloud-agent) *\~10 minutes • Recommended for all users* ### 1. Open Warp [Section titled “1. Open Warp”](#1-open-warp) If you don’t have Warp yet, download it from [warp.dev](https://warp.dev) and sign in to your account. When you open the Warp desktop app, you’re automatically authenticated to Warp’s services. ### 2. Run the `/cloud-agent` command [Section titled “2. Run the /cloud-agent command”](#2-run-the-cloud-agent-command) In Warp’s terminal input, type: ```bash /cloud-agent ``` This launches a new cloud agent for you. **How this works:** The `/cloud-agent` command is your entry point to cloud agents. It checks if you have an environment set up, and if not, it guides you through creating one. ### 3. Create your environment [Section titled “3. Create your environment”](#3-create-your-environment) Note **Already have an environment?** The `/cloud-agent` command will use your existing one. To create additional environments for different projects, use `/create-environment`. If you don’t have an environment yet, the `/cloud-agent` setup flow will guide you through creating one. You will need: * **Name**: A label to identify this environment (required) * **Repo(s)**: Type repo in `owner/repo` format or select from the dropdown. Click **Auth with GitHub** if you need to connect your repos. * **Docker image**: Your runtime environment (e.g., `python:3.11`, `node:20`). Not sure? Click **Suggest image** and Warp will recommend one based on your repos. * **Setup command(s)**: Commands to prepare your workspace, like `pip install -r requirements.txt` or `npm ci`. Add each command separately by pressing Enter. * **Description**: Optional notes about what this environment is for. **How this works:** Environments are composed of Docker containers + Git repos + startup commands. They give your cloud agent a consistent workspace with your code and tools. Warp detects your project automatically and suggests the right setup. Environments can be shared with your team so everyone uses the same configuration. ### 4. Describe what you want the agent to do [Section titled “4. Describe what you want the agent to do”](#4-describe-what-you-want-the-agent-to-do) Enter your prompt (e.g., “analyze test coverage and suggest improvements”). The agent executes in the cloud with full access to your environment. You can continue conversing with the agent in real-time, watch its progress, and provide additional guidance as it works autonomously on your task. **How this works:** Your cloud agent is now running in Warp’s infrastructure (not on your machine). It clones your repos, runs your setup commands, and starts working on your prompt. The agent has full access to your code and can run tests, make changes, and create artifacts like PRs. ### 5. View run details [Section titled “5. View run details”](#5-view-run-details) You can view details of your agent’s run, including commands executed, files changed, and environment used, several different ways: * In the Warp app, open the [conversations panel](/agent-platform/local-agents/interacting-with-agents/#conversation-panel) to see all your agent runs. * Click the session link in your terminal output. * Go to [oz.warp.dev](https://oz.warp.dev) and navigate to the `Runs` tab. * Access from mobile via the [Oz web app](/agent-platform/cloud-agents/oz-web-app/). **Breaking it down:** Every cloud agent run is auto-tracked. You get a shareable link, a run record, and full visibility into what the agent did. You or your teammates can watch the agent’s progress in real-time and even steer it if needed. The run record persists after completion so you can review it later. ### 6. Make it reusable with a skill (optional) [Section titled “6. Make it reusable with a skill (optional)”](#6-make-it-reusable-with-a-skill-optional) Turn your successful run into a skill that you can reuse: ```bash /create-skill ``` Follow the prompts to save your task definition. Once created, you can run it again, schedule it, trigger it from Slack/Linear, or share it with your team. **How this works:** Skills capture successful agent workflows as reusable building blocks. Instead of typing the same prompt repeatedly, you define it once. You can use it yourself, share it with teammates, schedule it to run automatically, or trigger it from integrations. Learn more about [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/). **Prefer using the CLI?** See the [Oz CLI quickstart](/reference/cli/quickstart/) for CLI-based workflows. *** ## Next steps [Section titled “Next steps”](#next-steps) Now that you’ve run your first cloud agent, here are some next steps: ### Automate recurring tasks [Section titled “Automate recurring tasks”](#automate-recurring-tasks) [Schedule agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) to run on cron schedules for maintenance tasks like weekly dependency checks or daily dead code cleanup. ```bash oz schedule create \ --name "weekly-dependency-check" \ --cron "0 10 * * 1" \ --environment \ --prompt "check for dependency updates and open PR" ``` ### Trigger agents from integrations [Section titled “Trigger agents from integrations”](#trigger-agents-from-integrations) **Slack integration** - Tag @Oz in any Slack channel to get immediate help with code reviews, debugging, or incident response. Your team can discuss problems in Slack while Oz analyzes code, opens PRs, or investigates issues in the background. Results post directly back to the thread. [Learn more](/agent-platform/cloud-agents/integrations/slack/) **Linear integration** - Connect Oz to Linear to automate bug triage and fixes. Tag @Oz on an issue to reproduce the bug, identify root causes, and open a PR with a fix—closing the loop from bug report to resolution without leaving Linear. [Learn more](/agent-platform/cloud-agents/integrations/linear/) **GitHub Actions** - Run agents in CI/CD pipelines to automate tasks like generating release notes, running security audits, or validating migrations. Trigger agents on PRs, commits, or releases to keep workflows moving without manual intervention. [Learn more](/agent-platform/cloud-agents/integrations/github-actions/) Note Integrations require a team on Build, Max, or Business plan. ### Build automations and apps on top of Oz agents [Section titled “Build automations and apps on top of Oz agents”](#build-automations-and-apps-on-top-of-oz-agents) Use the [Oz API & SDK](/reference/api-and-sdk/) to trigger agents programmatically from your own systems and workflows. *** ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) **Environment creation fails**\ Use official Docker Hub images like `node`, `python`, or `rust` for best compatibility. Ensure your GitHub repos are accessible. If using a custom image, avoid Alpine/musl-based images—the agent runtime requires glibc. See [Environments](/agent-platform/cloud-agents/environments/) for more guidance on choosing Docker images. **Agent can’t access repos**\ Warp prompts you to authorize GitHub when you create an environment or trigger your first agent. If authorization fails or needs updating, see [How GitHub Authorization works](/reference/cli/integration-setup/#how-github-authorization-works). For automated workflows using team API keys, make sure [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured in the Admin Panel. Also verify that repos are correctly configured in your environment with `oz environment get `. **Not enough credits to run cloud agents**\ Your team needs at least 20 credits available (any type of Warp credits work). Check your credit balance in Settings or see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) for details on credit requirements and which plans support cloud agents. **More resources** * [Environments deep dive](/agent-platform/cloud-agents/environments/) * [Cloud Agents FAQs](/agent-platform/cloud-agents/faqs/) * [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) *** ## What to explore next [Section titled “What to explore next”](#what-to-explore-next) Now that you’ve run your first cloud agent, automate recurring work or connect agents to your team’s tools. * **[Scheduled Agents quickstart](/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart/)** - Set up an agent to run on a cron schedule for recurring tasks like weekly dependency checks. * **[Integrations quickstart](/agent-platform/cloud-agents/integrations/quickstart/)** - Connect Oz to Slack and Linear so your team can trigger agents from mentions and issues. * **[Skills](/agent-platform/capabilities/skills/)** - Turn successful agent workflows into reusable instructions you can schedule, trigger, or share. # Cloud agent secrets > Securely store, scope, and inject credentials for Warp cloud agents across CLI, Slack, Linear, and scheduled runs—without ever exposing secret values. Cloud agents often need to interact with external systems such as APIs, databases, cloud providers, or internal tooling. To do this safely, Warp provides Warp-managed **agent secrets**, a secure way to store, scope, and inject credentials into cloud agent runs without exposing secret values to users or logs. Warp-managed secrets are designed to work across [cloud agent](/agent-platform/cloud-agents/overview/) and [integration](/agent-platform/cloud-agents/integrations/) triggers (CLI, Slack, Linear, and schedules), support both team-wide and personal credentials, and give engineering and security teams visibility into what agents can access. **Warp-managed secrets are useful when:** * An cloud agent needs to call an API or CLI that does not support OAuth * You are using [MCP servers](/agent-platform/cloud-agents/mcp/) that expect static tokens or keys * An agent needs credentials for tools like cloud CLIs, databases, monitoring systems, or internal services * You want centralized auditing and control over what credentials agents can access ### Common use cases [Section titled “Common use cases”](#common-use-cases) * Run SQL queries against BigQuery or Metabase to answer questions like “what changed in last night’s pipeline run” or “how many users hit this error today,” using a read-only service account or API token. * Call cloud or infrastructure CLIs to take small, predefined remediation steps when an alert fires, such as restarting a service, scaling a deployment, or clearing a stuck job, using tightly scoped credentials. * List and review all API keys, service accounts, and tokens that cloud agents can access to verify scopes, rotation policies, and ownership match internal security requirements. *** ### How Warp-managed secrets work [Section titled “How Warp-managed secrets work”](#how-warp-managed-secrets-work) Warp provides a set of CLI commands for creating, updating, and listing secrets. Secret values are stored securely and cannot be retrieved once created. At runtime, **Warp sets the relevant secrets as environment variables** for each cloud agent run, based on who triggered the agent and how it was triggered. Note Secret values are available only to the agent process (and any subprocesses it spawns) during execution, and **can’t be viewed or retrieved afterward.** Key properties of secrets: * **Scoped** to either a team or an individual user * Secret values are **never readable after creation** (only metadata is visible) * **Automatically set** for cloud agent runs when in scope ### Secret scopes [Section titled “Secret scopes”](#secret-scopes) Each secret has a scope that determines who can use it. #### Team secrets [Section titled “Team secrets”](#team-secrets) Team secrets are shared across the entire team and are available to all cloud agents running on behalf of the team. **Key characteristics:** * Always injected into cloud agent runs, regardless of how the agent is triggered (CLI, Slack, Linear, or scheduled runs) * Available to agents running with or without a specific user context * Ideal for shared infrastructure credentials, service accounts, and read-only API keys Note Because team secrets are broadly available and may be used by fully automated or scheduled agents, they should generally be created **using bot or service accounts**, rather than credentials tied to an individual person. **For example:** * Use a Metabase service account or read-only API token, not a personal Metabase API key * Use cloud provider service accounts with minimal required permissions * Use integration-specific tokens created for automation This ensures credentials remain valid as team membership changes, permissions are tightly scoped, and ownership and rotation align with internal security policies. #### Personal secrets [Section titled “Personal secrets”](#personal-secrets) Personal secrets belong to an **individual user**. * Only available to cloud agents triggered by that user * Not accessible to teammates or user-less triggers * Useful for personal API keys or credentials tied to an individual account *** ## Managing agent secrets with the Oz CLI [Section titled “Managing agent secrets with the Oz CLI”](#managing-agent-secrets-with-the-oz-cli) Secrets are managed using the oz secret command family. You can create secrets interactively or from a file. **Create a team secret interactively** ```bash oz secret create --team METABASE_API_KEY ``` You will be prompted to enter the value securely in the terminal. **Create a personal secret from a file** ```bash oz secret create --personal --value-file api_key.txt METABASE_API_KEY ``` This is useful for long values such as JSON blobs or private keys. #### Adding descriptions [Section titled “Adding descriptions”](#adding-descriptions) Descriptions help with auditing and rotation tracking. ```bash oz secret create --team \ --description "Rotate every 2 weeks; owned by platform team" \ MY_SECRET ``` Descriptions are visible in listings but never expose the secret value. #### Updating a secret [Section titled “Updating a secret”](#updating-a-secret) Updating a secret replaces its value and/or description while keeping the same name and scope. **Update a secret value interactively** ```bash oz secret update --team --value METABASE_API_KEY ``` You will be prompted to enter the new value securely in the terminal. **Update a secret value from a file** ```bash oz secret update --team \ --value-file new_api_key.txt \ METABASE_API_KEY ``` This is the recommended way to rotate credentials. **Update a secret’s description (`-d`)** ```bash oz secret update --team \ --description "Rotated 2026-02-26; owned by platform team" \ METABASE_API_KEY ``` #### Deleting a secret [Section titled “Deleting a secret”](#deleting-a-secret) To permanently remove a secret, use `oz secret delete`: ```bash oz secret delete --team METABASE_API_KEY ``` You will be prompted for confirmation before the secret is deleted. Add `--force` to skip the confirmation prompt. Replace `--team` with `--personal` to delete a personal secret. ```bash oz secret delete --team --force METABASE_API_KEY ``` Caution Deleting a secret is permanent. Any cloud agent runs that depend on the deleted secret will no longer receive it as an environment variable. #### Listing secrets [Section titled “Listing secrets”](#listing-secrets) You can list all secrets you have access to. ```bash oz secret list ``` Example output: ```bash NAME SCOPE LAST UPDATED METABASE_API_KEY team 1 week ago GCP_SERVICE_ACCOUNT_JSON team yesterday MY_MCP_SERVER_TOKEN personal 10:00am ``` **Secret values are never displayed.** ### How secrets are made available to cloud agents [Section titled “How secrets are made available to cloud agents”](#how-secrets-are-made-available-to-cloud-agents) When an cloud agent starts, Warp determines which secrets are in scope and sets them as environment variables in the agent’s execution environment. Today, secrets are provided as environment variables using the secret name as the variable name. For example: ```bash METABASE_API_KEY=******** ``` *** ### Secret availability by trigger type [Section titled “Secret availability by trigger type”](#secret-availability-by-trigger-type) Which secrets an agent receives depends on how the agent was triggered. #### User-initiated triggers [Section titled “User-initiated triggers”](#user-initiated-triggers) When an agent is triggered by a specific user, such as: * Oz CLI * Slack mentions * Linear updates **The agent receives:** * All team-level secrets * The triggering user’s personal secrets It **does not receive personal secrets** belonging to other team members. When an agent is triggered without a user context, such as: * [Scheduled (cron) agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) * Fully automated [integrations](/agent-platform/cloud-agents/integrations/) The agent receives: * Team-level secrets only Caution Personal secrets are never injected in these cases. *** ### Auditing and security considerations [Section titled “Auditing and security considerations”](#auditing-and-security-considerations) Warp is designed to make secret usage auditable and predictable: * Secret values cannot be read or exported after creation * All secrets are explicitly scoped to a team or user * Engineering and security leads can list all secrets available to them * Rotation is handled by updating secrets in place * Cloud agents only receive secrets that are in scope for the trigger **Teams remain responsible for:** * Choosing appropriate scopes for each secret * Limiting permissions on external systems (for example, read-only API keys) * Rotating credentials according to internal policies * Managing which agents and triggers exist within their environment # Self-hosting overview > Run Oz cloud agents on your own infrastructure. Choose between a managed worker daemon orchestrated by Oz or unmanaged CLI-based execution you control. Self-hosting lets your team run Oz cloud agent workloads on your own infrastructure instead of Warp-managed servers. You control the execution environment, compute resources, and network access. Repositories are cloned and stored only on your machines, and agents can reach services behind your VPN or firewall. **New to self-hosting?** Start with the [Self-hosting quickstart](/agent-platform/cloud-agents/self-hosting/quickstart/) to get a managed worker running on Docker in under 10 minutes. **Want a CLI-only path with no Docker requirement?** Jump straight to the [Unmanaged quickstart](/agent-platform/cloud-agents/self-hosting/unmanaged/#unmanaged-quickstart) to run `oz agent run` directly on any host. Note **Enterprise feature**: Self-hosted Oz agents are available exclusively to teams on an Enterprise plan. To enable self-hosting for your team, [contact sales](https://warp.dev/contact-sales). ## Managed vs unmanaged [Section titled “Managed vs unmanaged”](#managed-vs-unmanaged) Self-hosting has two architectures. The core distinction is **who orchestrates agent runs** — not who owns the compute. Both models keep code and execution on your infrastructure. * **Managed** — Oz orchestrates agent runs. You run the `oz-agent-worker` daemon on your infrastructure; it connects to Oz and waits for work. Slack mentions, Linear comments, schedules, API calls, and `oz agent run-cloud` commands all route tasks to your worker, which executes them in isolated Docker containers, Kubernetes Jobs, or directly on the host. Similar to a [GitHub self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners). * **Unmanaged** — You orchestrate agent runs. You invoke `oz agent run` directly from your existing CI pipeline, Kubernetes pod, VM, or dev box. Oz provides session tracking and observability for each run, but does not start or stop agents for you. ### At a glance [Section titled “At a glance”](#at-a-glance) | Aspect | **Managed** | **Unmanaged** | | --------------------------------- | ------------------------------------------------------------------------- | ----------------------------------- | | **Who triggers runs** | Oz (Slack, Linear, schedules, API, `run-cloud`) | Your system (CI, cron, scripts) | | **What runs on your infra** | Long-lived `oz-agent-worker` daemon | One-shot `oz agent run` invocations | | **OS support** | Linux (macOS/Windows coming) | Linux, macOS, Windows | | **Execution isolation** | Docker container, Kubernetes Job, or direct host | Whatever your host provides | | **Automatic environment setup** | Yes (via Warp [environments](/agent-platform/cloud-agents/environments/)) | No (you manage it) | | **Session tracking and steering** | Yes | Yes | The two architectures are not mutually exclusive. Some teams run managed workers for integration-triggered work and unmanaged agents in CI pipelines. ## How self-hosting works [Section titled “How self-hosting works”](#how-self-hosting-works) Warp uses a split-plane architecture: **execution happens on your infrastructure**, while **orchestration, session management, and LLM inference route through Warp’s backend**. Agent interactions — including code context in session transcripts and LLM prompts — transit Warp’s control plane under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements. Warp does not persistently store your source code or train on it. ![Self-hosted Oz architecture showing customer-managed execution with Oz orchestration](/_astro/customer-dedicated-saas.DzTXurvP_Z3xTYW.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) With any self-hosted architecture: * **Agent runs are tracked and steerable** — View status, metadata, and session transcripts in the [Oz dashboard](https://oz.warp.dev), the Warp app, or via the [API/SDK](/reference/api-and-sdk/). Authorized teammates can attach to running sessions to monitor or steer agents. * **Connectivity to Warp’s backend is required** — Agents need outbound access to Warp for orchestration, session storage, and LLM inference. No inbound ports need to be opened. * **Resource limits are controlled by your infrastructure** — Concurrency and compute are only limited by the machines you provision, not by Warp. Note Enterprise teams that need full control over LLM inference routing can use [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) to route inference through their own cloud provider accounts. BYOLLM currently applies to interactive (local) agents; cloud agent support is coming. *** ## Choosing an architecture [Section titled “Choosing an architecture”](#choosing-an-architecture) Caution **OS support:** The managed architecture is **Linux-only** today (macOS and Windows support is coming). If you need agents to run on macOS or Windows, use the [unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/) architecture, which works on any platform Warp supports. Use these questions to decide between managed and unmanaged: 1. **Do you need agents to run on Windows or macOS?** * Yes → Use the [unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/) architecture. Managed is Linux-only today. * No, Linux works → Continue to the next question. 2. **Do you want Oz to handle starting and stopping agents** (from Slack, the web interface, the Warp app, schedules, or the API)? * Yes → Use the [managed](#managed-architecture) architecture. * No, you have your own triggering mechanism → Use the [unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/) architecture. 3. **Can your development environment run in a Docker container or Kubernetes pod?** * Yes, Docker → [Managed: Docker](/agent-platform/cloud-agents/self-hosting/managed-docker/) backend. * Yes, Kubernetes → [Managed: Kubernetes](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/) backend. * No (multi-service stacks that don’t fit a single container, or environments where container runtimes aren’t available) → [Unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/) or [Managed: Direct](/agent-platform/cloud-agents/self-hosting/managed-direct/). 4. **Do you have your own orchestrator** (CI/CD, Kubernetes, internal job scheduler) **that starts agents on demand?** * Yes → [Unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/), using `oz agent run` as a drop-in. * No → [Managed](#managed-architecture). ### Choosing a managed backend [Section titled “Choosing a managed backend”](#choosing-a-managed-backend) The managed architecture supports three backends for task execution: 1. **Are you deploying the worker into a Kubernetes cluster?** * Yes → Use the [Kubernetes backend](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/). Each task runs as a Kubernetes Job in your cluster; install with the included Helm chart. * No → Continue. 2. **Is Docker available on your worker host?** * Yes → Use the [Docker backend](/agent-platform/cloud-agents/self-hosting/managed-docker/) (default). Tasks run in isolated containers. * No → Use the [Direct backend](/agent-platform/cloud-agents/self-hosting/managed-direct/). Tasks run directly on the host. 3. **Do you need container-level isolation between tasks?** * Yes → [Docker](/agent-platform/cloud-agents/self-hosting/managed-docker/) or [Kubernetes](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/) backend. * No → Any backend works. 4. **Do you need Kubernetes-native scheduling, resource management, or policy enforcement?** * Yes → [Kubernetes backend](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/). * No → [Docker](/agent-platform/cloud-agents/self-hosting/managed-docker/) or [Direct](/agent-platform/cloud-agents/self-hosting/managed-direct/) is simpler to set up. *** ## Managed architecture [Section titled “Managed architecture”](#managed-architecture) With the managed architecture, you run the `oz-agent-worker` daemon on your infrastructure. The daemon connects to Oz’s backend, waits for tasks to be assigned to it, and executes those tasks on its host using one of three backends: * **[Docker backend](/agent-platform/cloud-agents/self-hosting/managed-docker/)** (default) — Runs each task in an isolated Docker container. * **[Kubernetes backend](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/)** — Runs each task as a Kubernetes Job in your cluster. * **[Direct backend](/agent-platform/cloud-agents/self-hosting/managed-direct/)** — Runs each task directly on the host without a container runtime. The managed architecture enables full orchestration by Oz — it can remotely start agents via Slack, Linear, the [Oz web app](https://oz.warp.dev), the API/SDK, and the `oz agent run-cloud` command. Agents can access host resources through volume mounts (Docker), Kubernetes-native configuration (Kubernetes), and injected environment variables. ## Unmanaged architecture [Section titled “Unmanaged architecture”](#unmanaged-architecture) With the [unmanaged architecture](/agent-platform/cloud-agents/self-hosting/unmanaged/), you run `oz agent run` inside your own orchestrator or dev environment. This works on any platform Warp supports (Linux, macOS, Windows), with no dependency on Docker or any other sandboxing platform. You’re responsible for executing `oz agent run` on your infrastructure — similar to how you’d integrate Claude Code or Codex CLI. The agent runs directly on the host, which could itself be a Kubernetes pod, VM, container, or CI runner. *** ## Routing runs to self-hosted workers [Section titled “Routing runs to self-hosted workers”](#routing-runs-to-self-hosted-workers) This section applies to **all managed backends** (Docker, Kubernetes, and Direct). Once a worker is connected, route Oz cloud agent runs to it by specifying the `--host` flag (or equivalent) with your worker ID. The `--host` value must match the `--worker-id` of a connected worker exactly. Note Unmanaged runs don’t need routing — you invoke `oz agent run` directly on the host where you want the agent to execute. Routing is only relevant for managed workers. ### From the CLI [Section titled “From the CLI”](#from-the-cli) ```bash oz agent run-cloud --prompt "Refactor the authentication module" --host "my-worker" ``` You can combine `--host` with any other `run-cloud` flags, such as `--environment`, `--model`, `--mcp`, `--skill`, `--computer-use`, and `--attach`. ### From scheduled agents [Section titled “From scheduled agents”](#from-scheduled-agents) When creating or updating a schedule, specify the host: ```bash oz schedule create --name "daily-cleanup" \ --cron "0 9 * * *" \ --prompt "Run dead code cleanup" \ --environment ENV_ID \ --host "my-worker" oz schedule update SCHEDULE_ID --host "my-worker" ``` ### From integrations [Section titled “From integrations”](#from-integrations) When creating or updating an integration, specify the host: ```bash oz integration create slack --host "my-worker" ... oz integration update linear --host "my-worker" ... ``` All tasks created through that integration route to your self-hosted worker. ### From the API and SDKs [Section titled “From the API and SDKs”](#from-the-api-and-sdks) When creating a run via the [Oz API](/reference/api-and-sdk/), include `worker_host` in the config: ```bash curl -X POST https://app.warp.dev/api/v1/agent/run \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "prompt": "Refactor the authentication module", "config": { "environment_id": "ENV_ID", "worker_host": "my-worker" } }' ``` ### From the web UI [Section titled “From the web UI”](#from-the-web-ui) When creating a run, schedule, or integration in the [Oz web app](https://oz.warp.dev), select your self-hosted worker from the host dropdown. *** ## Environments with self-hosted workers [Section titled “Environments with self-hosted workers”](#environments-with-self-hosted-workers) Self-hosted workers fully support [environments](/agent-platform/cloud-agents/environments/). When a task specifies an environment, the worker resolves the Docker image, clones the repositories, runs setup commands, and executes the agent inside the prepared container or Kubernetes Job. The same environment can be used for both Warp-hosted and self-hosted runs without modification. See [Environments](/agent-platform/cloud-agents/environments/) for details on creating and configuring them. Note With the Kubernetes backend, setting a [`default_image`](/agent-platform/cloud-agents/self-hosting/reference/#kubernetes-backend-config) on the worker lets you skip creating a Warp environment when all your tasks use the same base image. Caution Musl-based Docker images (such as Alpine Linux) are not supported as task images. The agent runtime requires glibc. Use glibc-based images like Debian, Ubuntu, or the default (non-Alpine) variants of official Docker Hub images. ## Monitoring runs [Section titled “Monitoring runs”](#monitoring-runs) Self-hosted runs have the same observability as Warp-hosted runs: * **Oz dashboard** — View task status, history, and metadata at [oz.warp.dev](https://oz.warp.dev). * **Session sharing** — Authorized teammates can attach to running tasks to monitor progress. * **APIs and SDKs** — Query task history and build monitoring using the [Oz API](/reference/api-and-sdk/). For infrastructure-level observability, the `oz-agent-worker` daemon can export OpenTelemetry metrics (worker health, task throughput, capacity saturation) to Prometheus, an OTLP collector, or the console. See [Monitoring](/agent-platform/cloud-agents/self-hosting/monitoring/) for setup, the full metric catalog, and sample PromQL queries. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosting quickstart](/agent-platform/cloud-agents/self-hosting/quickstart/) — Get a managed worker running in \~10 minutes. * [Unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/) — Run `oz agent run` in your CI, K8s, or dev environment. * [Managed: Docker](/agent-platform/cloud-agents/self-hosting/managed-docker/) — Default managed setup with the Docker backend. * [Managed: Kubernetes](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/) — Managed setup with the Kubernetes backend and Helm chart. * [Managed: Direct](/agent-platform/cloud-agents/self-hosting/managed-direct/) — Managed setup with no container runtime. * [Self-hosted worker reference](/agent-platform/cloud-agents/self-hosting/reference/) — CLI flags and config file schema. * [Monitoring](/agent-platform/cloud-agents/self-hosting/monitoring/) — OpenTelemetry metrics for worker health, task throughput, and capacity. * [Security and networking](/agent-platform/cloud-agents/self-hosting/security-and-networking/) — Data boundaries, network egress, and security considerations. * [Troubleshooting](/agent-platform/cloud-agents/self-hosting/troubleshooting/) — Worker won’t start, tasks not picked up, and other common issues. * [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) — How self-hosting compares to CLI-only and Warp-hosted deployment. * [Environments](/agent-platform/cloud-agents/environments/) — Define the runtime context for agent tasks. # Managed: Direct backend > Run the Oz managed worker with the Direct backend to execute cloud agent tasks directly on the host, without Docker or Kubernetes. Run the `oz-agent-worker` daemon with the **Direct backend** — tasks execute directly on the worker host without Docker or Kubernetes. Oz still orchestrates runs end to end (Slack, Linear, schedules, API, `oz agent run-cloud`); the worker just runs the agent in a per-task workspace on its own filesystem. Note This page covers the [managed architecture](/agent-platform/cloud-agents/self-hosting/#managed-architecture) with the Direct backend. For container-based task isolation, see [Managed: Docker](/agent-platform/cloud-agents/self-hosting/managed-docker/) or [Managed: Kubernetes](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/). For invocation-driven use cases, see [Unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/). ## When to use the Direct backend [Section titled “When to use the Direct backend”](#when-to-use-the-direct-backend) * Neither Docker nor Kubernetes is available on the worker host. * Tasks need direct access to host resources that are hard to expose through a container. * You want managed orchestration (triggering from Slack, Linear, schedules, API) without the operational overhead of a container runtime. Caution The Direct backend does not provide per-task container isolation. Each task runs in an isolated workspace directory, but shares the host OS and kernel. Evaluate whether this fits your security requirements before using it in production. *** ## How it works [Section titled “How it works”](#how-it-works) 1. The worker creates a per-task workspace directory under `workspace_root`. 2. If a `setup_command` is configured, it runs before the task with environment variables pointing to the workspace. 3. The `oz` CLI runs the agent task inside the workspace directory. 4. After the task completes, the optional `teardown_command` runs and the workspace is cleaned up. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Enterprise plan with self-hosting enabled** — [Contact sales](https://warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A worker host** with write access to `workspace_root` (defaults to `/var/lib/oz/workspaces`). * **The Oz CLI** installed and available in `PATH` on the worker host (or specify `oz_path` in the config file). See [Installing the CLI](/reference/cli/#installing-the-cli). * **A team API key** — In the Warp app, go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create a team-scoped API key. See [API Keys](/reference/cli/api-keys/) for details. *** ## Setup [Section titled “Setup”](#setup) ### 1. Set your API key [Section titled “1. Set your API key”](#1-set-your-api-key) Export the API key so the worker can authenticate to Oz: ```bash export WARP_API_KEY="your_team_api_key" ``` ### 2. Start the worker with the Direct backend [Section titled “2. Start the worker with the Direct backend”](#2-start-the-worker-with-the-direct-backend) Pass `--backend direct`: ```bash oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" --backend direct ``` Or with a [config file](/agent-platform/cloud-agents/self-hosting/reference/#config-file): ```yaml worker_id: "my-worker" backend: direct: workspace_root: "/var/lib/oz/workspaces" ``` **Expected outcome:** The worker connects to Oz and begins listening for tasks. Each assigned task runs in a freshly-created subdirectory of `workspace_root`. *** ## Workspace model [Section titled “Workspace model”](#workspace-model) Each task gets its own directory under `workspace_root`. The default is `/var/lib/oz/workspaces`; override it with the `workspace_root` config option shown above. After the task completes, the workspace is deleted (unless `--no-cleanup` is set, which keeps the directory around for debugging). *** ## Setup and teardown commands [Section titled “Setup and teardown commands”](#setup-and-teardown-commands) The `setup_command` runs before each task and receives the following environment variables: * `OZ_WORKSPACE_ROOT` — The workspace directory for the task. * `OZ_RUN_ID` — The unique task ID. * `OZ_ENVIRONMENT_FILE` — Path to a file where the setup script can write additional `KEY=VALUE` environment variables to inject into the task. * `OZ_WORKER_BACKEND` — Always set to `direct`. The `teardown_command` runs after each task and receives `OZ_WORKSPACE_ROOT`, `OZ_RUN_ID`, and `OZ_WORKER_BACKEND`. Use the setup command to clone repos, install dependencies, or write task-specific env vars into `OZ_ENVIRONMENT_FILE`. Use the teardown command for cleanup or reporting. *** ## Environment variables for Direct tasks [Section titled “Environment variables for Direct tasks”](#environment-variables-for-direct-tasks) Note The Direct backend starts tasks with a **minimal environment** (only `HOME`, `TMPDIR`, and `PATH` from the host) to avoid leaking sensitive worker credentials like `WARP_API_KEY` into tasks. Add variables explicitly via `environment` in the config file or `-e` flags on the worker CLI. Config file example: ```yaml worker_id: "direct-worker" max_concurrent_tasks: 2 backend: direct: workspace_root: "/var/lib/oz/workspaces" oz_path: "/usr/local/bin/oz" setup_command: "/opt/scripts/setup.sh" teardown_command: "/opt/scripts/teardown.sh" environment: - name: MY_VAR value: "hello" ``` *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosted worker reference](/agent-platform/cloud-agents/self-hosting/reference/#direct-backend-config) — Full config schema for the Direct backend. * [Self-hosting overview](/agent-platform/cloud-agents/self-hosting/) — Managed vs unmanaged and the backend decision guide. * [Routing runs to self-hosted workers](/agent-platform/cloud-agents/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. * [Security and networking](/agent-platform/cloud-agents/self-hosting/security-and-networking/) — Data boundaries and security considerations for the Direct backend. * [Troubleshooting](/agent-platform/cloud-agents/self-hosting/troubleshooting/#direct-backend) — Common Direct-backend issues. # Managed: Docker backend > Run the Oz managed worker daemon with the Docker backend to execute cloud agent tasks in isolated containers on your infrastructure. Run the `oz-agent-worker` daemon with the **Docker backend** — the default managed path. Each agent task runs in an isolated Docker container spawned from the worker, with full orchestration by Oz (Slack, Linear, schedules, API, `oz agent run-cloud`). Note This page covers the [managed architecture](/agent-platform/cloud-agents/self-hosting/#managed-architecture) with the Docker backend. For the Kubernetes backend, see [Managed: Kubernetes](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/). For host execution without a container runtime, see [Managed: Direct](/agent-platform/cloud-agents/self-hosting/managed-direct/). If you’d rather invoke agents yourself, see [Unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/). ## When to use the Docker backend [Section titled “When to use the Docker backend”](#when-to-use-the-docker-backend) * You want the simplest managed setup and have Docker available on the worker host. * You want per-task isolation without running a Kubernetes cluster. * You’re not already deploying workloads into Kubernetes. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Enterprise plan with self-hosting enabled** — [Contact sales](https://warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A machine to run the worker** — A VM, server, or local machine running Linux (recommended for production). For testing, macOS and Windows hosts running Docker Desktop work. * **Docker installed** — The worker uses Docker to spawn task containers. The Docker daemon must run Linux containers (Windows containers are not supported). Verify with `docker info`. * **A team API key** — In the Warp app, go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create a team-scoped API key. See [API Keys](/reference/cli/api-keys/) for details. Caution Task containers require a **linux/amd64** or **linux/arm64** Docker daemon. The worker host itself can be any OS — Docker Desktop on macOS and Windows runs a Linux VM that satisfies this requirement. ### Install Docker [Section titled “Install Docker”](#install-docker) If Docker is not already installed, follow the [official Docker installation guide](https://docs.docker.com/get-docker/) for your platform. Verify Docker is running: ```bash docker info ``` **Expected outcome:** `docker info` prints daemon details without errors. *** ## Set your API key [Section titled “Set your API key”](#set-your-api-key) Export your team API key so the worker can authenticate to Oz: ```bash export WARP_API_KEY="your_team_api_key" ``` ## Install and run the worker [Section titled “Install and run the worker”](#install-and-run-the-worker) The `oz-agent-worker` is open source. See the [oz-agent-worker repository](https://github.com/warpdotdev/oz-agent-worker) for source code, issues, and contribution guidelines. There are three ways to install and run the worker with the Docker backend. Docker is recommended for production; `go install` and building from source are primarily useful for contributors and one-off testing. The worker can be configured entirely via CLI flags, or via a YAML [config file](/agent-platform/cloud-agents/self-hosting/reference/#config-file) for more complex setups. ### Option 1: Docker (recommended) [Section titled “Option 1: Docker (recommended)”](#option-1-docker-recommended) The worker needs access to the Docker daemon to spawn task containers. Mount the host’s Docker socket into the worker container: ```bash docker run -v /var/run/docker.sock:/var/run/docker.sock \ -e WARP_API_KEY="$WARP_API_KEY" \ warpdotdev/oz-agent-worker --worker-id "my-worker" ``` **Expected outcome:** The worker connects to Oz and logs that it’s listening for tasks. ### Option 2: Go install [Section titled “Option 2: Go install”](#option-2-go-install) ```bash go install github.com/warpdotdev/oz-agent-worker@latest oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" ``` ### Option 3: Build from source [Section titled “Option 3: Build from source”](#option-3-build-from-source) ```bash git clone https://github.com/warpdotdev/oz-agent-worker.git cd oz-agent-worker go build -o oz-agent-worker ./oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" ``` Once started, the worker connects to Oz, waits for tasks routed to its `--worker-id`, runs each task in an isolated Docker container, and reports status and results back. The worker automatically reconnects if the connection drops. You can run multiple workers with the same `--worker-id` for redundancy — Oz distributes tasks across connected workers. *** ## Docker backend configuration [Section titled “Docker backend configuration”](#docker-backend-configuration) The worker can take configuration either via CLI flags or via a YAML [config file](/agent-platform/cloud-agents/self-hosting/reference/#config-file). CLI flags take precedence over config file values. **Common CLI flags:** ```bash docker run -v /var/run/docker.sock:/var/run/docker.sock \ -e WARP_API_KEY="$WARP_API_KEY" \ warpdotdev/oz-agent-worker \ --worker-id "prod-runner-1" \ --log-level debug \ --max-concurrent-tasks 4 \ --idle-on-complete 10m \ -v /opt/shared-cache:/cache:ro \ -e NPM_TOKEN=your_token \ -e GITHUB_TOKEN ``` Caution When running the worker via Docker, there are two levels of `-e` flags. Docker’s `-e` passes env vars to the **worker container** (e.g., `WARP_API_KEY`). The worker’s `-e` / `--env` flags pass env vars into the **task containers** the worker spawns. Keep these distinct: ```bash # Docker -e: passes WARP_API_KEY to the worker container # Worker -e: passes MY_SECRET to task containers docker run \ -e WARP_API_KEY="$WARP_API_KEY" \ warpdotdev/oz-agent-worker \ --worker-id "my-worker" \ -e MY_SECRET=hunter2 ``` **Equivalent config file** (`config.yaml`): ```yaml worker_id: "prod-runner-1" log_level: "debug" max_concurrent_tasks: 4 idle_on_complete: "10m" backend: docker: volumes: - "/opt/shared-cache:/cache:ro" environment: - name: NPM_TOKEN value: "your_token" - name: GITHUB_TOKEN # inherits from host environment ``` Pass it with `--config-file config.yaml`. See the [self-hosted worker reference](/agent-platform/cloud-agents/self-hosting/reference/) for the full flag and config schema. *** ## Docker connectivity [Section titled “Docker connectivity”](#docker-connectivity) The worker uses the standard Docker client discovery mechanism to find the Docker daemon: 1. **`DOCKER_HOST`** environment variable (e.g., `unix:///var/run/docker.sock`, `tcp://localhost:2375`). 2. **Default socket** (`/var/run/docker.sock` on Linux, `~/.docker/run/docker.sock` for rootless Docker). 3. **Docker context** via `DOCKER_CONTEXT` environment variable. 4. **Config file** (`~/.docker/config.json`) for context settings. Additional Docker environment variables the worker respects: * `DOCKER_API_VERSION` — Specify Docker API version. * `DOCKER_CERT_PATH` — Path to TLS certificates. * `DOCKER_TLS_VERIFY` — Enable TLS verification. Note If the worker itself runs in Docker, you must mount any relevant config files (e.g., `~/.docker/config.json`) into the worker container for Docker context and credential discovery to work. **Example: Connecting to a remote Docker daemon** ```bash export DOCKER_HOST="tcp://remote-host:2376" export DOCKER_TLS_VERIFY=1 export DOCKER_CERT_PATH="/path/to/certs" oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" ``` *** ## Private Docker registries [Section titled “Private Docker registries”](#private-docker-registries) The worker automatically uses credentials from your Docker config (`~/.docker/config.json`) when pulling task images. If your [environments](/agent-platform/cloud-agents/environments/) use images from a private registry, authenticate the worker’s host first: ```bash docker login your-registry.example.com ``` When running the worker via Docker, mount the Docker config into the container: ```bash docker run \ -v /var/run/docker.sock:/var/run/docker.sock \ -v ~/.docker/config.json:/root/.docker/config.json:ro \ -e WARP_API_KEY="$WARP_API_KEY" \ warpdotdev/oz-agent-worker --worker-id "my-worker" ``` Note Sidecar images (the `oz` binary and dependencies) are pulled from public registries and do not require authentication. *** ## Routing runs to this worker [Section titled “Routing runs to this worker”](#routing-runs-to-this-worker) Once your Docker worker is connected, route tasks to it with `--host ""`. Routing is the same across all managed backends — see [Routing runs to self-hosted workers](/agent-platform/cloud-agents/self-hosting/#routing-runs-to-self-hosted-workers) for CLI, scheduled, integration, API, and web UI examples. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosting quickstart](/agent-platform/cloud-agents/self-hosting/quickstart/) — \~10-minute path to a running Docker worker. * [Self-hosted worker reference](/agent-platform/cloud-agents/self-hosting/reference/) — Full CLI flag and config file schema. * [Environments](/agent-platform/cloud-agents/environments/) — Define the Docker image, repos, and setup commands for tasks. * [Security and networking](/agent-platform/cloud-agents/self-hosting/security-and-networking/) — Data boundaries, egress, and Docker socket considerations. * [Troubleshooting](/agent-platform/cloud-agents/self-hosting/troubleshooting/) — Common issues with the Docker backend. # Managed: Kubernetes backend > Deploy the Oz managed worker into a Kubernetes cluster with the included Helm chart. Each agent task runs as a Kubernetes Job in your cluster. Deploy the `oz-agent-worker` daemon into a Kubernetes cluster using the included Helm chart. Each agent task runs as a **Kubernetes Job** in your cluster. Oz orchestrates runs end to end (Slack, Linear, schedules, API, `oz agent run-cloud`); your cluster provides the compute, scheduling, and policy enforcement. Note This page covers the [managed architecture](/agent-platform/cloud-agents/self-hosting/#managed-architecture) with the Kubernetes backend. For the default Docker backend, see [Managed: Docker](/agent-platform/cloud-agents/self-hosting/managed-docker/). For host execution without a container runtime, see [Managed: Direct](/agent-platform/cloud-agents/self-hosting/managed-direct/). To route runs to a connected worker, see [Routing runs to self-hosted workers](/agent-platform/cloud-agents/self-hosting/managed-docker/#routing-runs-to-self-hosted-workers). ## When to use the Kubernetes backend [Section titled “When to use the Kubernetes backend”](#when-to-use-the-kubernetes-backend) * You already operate a Kubernetes cluster and want agents to run there. * You need Kubernetes-native scheduling, resource management, or policy enforcement. * You want to use Kubernetes Secrets, ServiceAccounts, and admission policies to control task behavior. *** ## How it works [Section titled “How it works”](#how-it-works) 1. The worker connects to the Kubernetes API server (using in-cluster auth by default, or an explicit kubeconfig). 2. On startup, the worker runs a short-lived **preflight Job** to verify that cluster permissions, admission policies, and Pod Security Standards are compatible. If the preflight fails, the worker exits with a diagnostic error before accepting any tasks. 3. For each assigned task, the worker creates a Kubernetes Job in the configured namespace. 4. The worker monitors the Job and Pod status via Kubernetes Watch (with a 30-second safety-net poll for watch disconnects). 5. After the task completes, the Job is cleaned up (unless `--no-cleanup` is set). *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Enterprise plan with self-hosting enabled** — [Contact sales](https://warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A Kubernetes cluster** with the worker process able to reach the API server. The cluster must: * Allow the worker’s namespace to create Jobs with a **root init container** (sidecar materialization depends on this pattern). * Grant the worker these namespace-scoped permissions: `create`, `get`, `list`, `watch`, `delete` on `jobs`; `get`, `list`, `watch` on `pods`; `get` on `pods/log`; `list` on `events`. * **[Helm](https://helm.sh/docs/intro/install/)** installed locally, plus `kubectl` authenticated against the target cluster. * **A team API key** — In the Warp app, go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create a team-scoped API key. See [API Keys](/reference/cli/api-keys/) for details. *** ## Install with the Helm chart [Section titled “Install with the Helm chart”](#install-with-the-helm-chart) The `oz-agent-worker` repository includes a namespace-scoped Helm chart at `charts/oz-agent-worker`. This is the recommended way to deploy the worker into a cluster. ### What the chart deploys [Section titled “What the chart deploys”](#what-the-chart-deploys) * A long-lived `Deployment` running `oz-agent-worker` with the Kubernetes backend. * A namespaced `ServiceAccount` for the worker. * A namespaced `Role` / `RoleBinding` with the minimum permissions needed to manage task Jobs and Pods. * A `ConfigMap` containing the worker config YAML. * An optional `Secret` for `WARP_API_KEY` (or a reference to an existing Secret). The chart does not create CRDs or cluster-scoped RBAC resources. ### 1. Set your API key and namespace [Section titled “1. Set your API key and namespace”](#1-set-your-api-key-and-namespace) ```bash export WARP_API_KEY="your_team_api_key" ``` Create the namespace if it doesn’t exist: ```bash kubectl create namespace warp-oz ``` ### 2. Create the API key Secret [Section titled “2. Create the API key Secret”](#2-create-the-api-key-secret) If you’re not using an existing Secret, create one with the API key: ```bash kubectl create secret generic oz-agent-worker \ --from-literal=WARP_API_KEY="$WARP_API_KEY" \ --namespace warp-oz ``` **Expected outcome:** `kubectl get secret -n warp-oz oz-agent-worker` shows the Secret. ### 3. Install the chart [Section titled “3. Install the chart”](#3-install-the-chart) Clone the worker repo and install the chart: ```bash git clone https://github.com/warpdotdev/oz-agent-worker.git helm install oz-agent-worker ./oz-agent-worker/charts/oz-agent-worker \ --namespace warp-oz \ --set worker.workerId=oz-k8s-worker \ --set image.tag= ``` Caution Set `image.tag` explicitly to pin the worker image. Check the [oz-agent-worker releases](https://github.com/warpdotdev/oz-agent-worker/releases) for the latest version. Do not rely on `latest`. **Expected outcome:** `kubectl get pods -n warp-oz` shows the worker Deployment pod as `Running`, and the worker logs show `Connected to Oz` / `Listening for tasks`. To scale horizontally, deploy multiple Helm releases with distinct worker IDs rather than increasing replicas on a single release. *** ## Key chart values [Section titled “Key chart values”](#key-chart-values) **Required:** * `worker.workerId` — The worker ID (same as `--worker-id`). * `image.tag` — The worker image tag to deploy. **Worker configuration:** * `worker.logLevel` — Log verbosity (`debug`, `info`, `warn`, `error`). Defaults to `info`. * `worker.cleanup` — Whether to clean up task Jobs after execution. Defaults to `true`. * `worker.maxConcurrentTasks` — Maximum concurrent tasks. Defaults to `0` (unlimited). * `worker.idleOnComplete` — Duration to keep the oz process alive after task completion. * `worker.resources` — Resource requests/limits for the worker Deployment. Defaults to `100m` CPU and `128Mi` memory. * `worker.livenessProbe` — Liveness probe for the worker Deployment. Defaults to an `exec` probe (`kill -0 1`). Override with a custom probe or set to `null` to disable. * `worker.nodeSelector`, `worker.tolerations`, `worker.affinity` — Scheduling constraints for the worker Deployment pod. **Kubernetes backend:** * `kubernetesBackend.namespace` — Namespace for task Jobs. Defaults to the release namespace. * `kubernetesBackend.defaultImage` — Default Docker image for task pods when the run has no Warp environment image. Leave empty (default) to fall back to `ubuntu:22.04`. * `kubernetesBackend.imagePullPolicy` — Image pull policy for task pods. Defaults to `IfNotPresent`. * `kubernetesBackend.preflightImage` — Image for the startup preflight Job. Set this if your cluster restricts allowed registries. * `kubernetesBackend.unschedulableTimeout` — How long a pod may remain unschedulable before failing. Defaults to `30s`. * `kubernetesBackend.setupCommand` — Shell command to run before each task. * `kubernetesBackend.teardownCommand` — Shell command to run after each task. * `kubernetesBackend.extraLabels` — Additional labels for task Jobs and Pods. * `kubernetesBackend.extraAnnotations` — Additional annotations for task Jobs and Pods. * `kubernetesBackend.activeDeadlineSeconds` — Maximum task Job lifetime. * `kubernetesBackend.workspaceSizeLimit` — Size limit for workspace `emptyDir` volume. * `kubernetesBackend.podTemplate` — Raw PodSpec YAML for task Jobs (same as `backend.kubernetes.pod_template` in the [config file](/agent-platform/cloud-agents/self-hosting/reference/#config-file)). **API key Secret:** * `warp.apiKeySecret.create` — Set to `true` to have the chart create a Secret from `warp.apiKeySecret.value`. Defaults to `false` (expects a pre-existing Secret). * `warp.apiKeySecret.value` — The API key value to store in the chart-managed Secret. Only used when `warp.apiKeySecret.create` is `true`. * `warp.apiKeySecret.name` — Name of the Secret containing `WARP_API_KEY`. Defaults to `oz-agent-worker`. * `warp.apiKeySecret.key` — Key within the Secret. Defaults to `WARP_API_KEY`. See the [self-hosted worker reference](/agent-platform/cloud-agents/self-hosting/reference/#kubernetes-backend-config) for the full config file schema. *** ## Cluster selection [Section titled “Cluster selection”](#cluster-selection) Cluster selection follows Kubernetes client config conventions: * Set `backend.kubernetes.kubeconfig` to use an explicit kubeconfig file. * If `kubeconfig` is omitted and the worker runs inside a Kubernetes pod, the worker uses in-cluster config automatically. * Otherwise, the worker falls back to the default kubeconfig loading rules and uses the current context. `namespace` selects the namespace inside the chosen cluster. It defaults to `default` when omitted. *** ## Pod template [Section titled “Pod template”](#pod-template) The `pod_template` field accepts standard Kubernetes PodSpec YAML and is the declarative way to configure task pod scheduling, service accounts, image pull secrets, resources, and environment variables. When using `pod_template`, define a container named `task` to customize the main task container directly. Otherwise, the worker appends its own `task` container to the PodSpec. Use `valueFrom.secretKeyRef` to inject Kubernetes Secret values into task container environment variables: ```yaml pod_template: serviceAccountName: agent-task-sa imagePullSecrets: - name: my-registry-creds containers: - name: task resources: requests: cpu: "2" memory: 4Gi limits: memory: 8Gi env: - name: GITHUB_TOKEN valueFrom: secretKeyRef: name: my-k8s-secret key: github-token tolerations: - key: "dedicated" operator: "Equal" value: "agents" effect: "NoSchedule" ``` Note The worker Deployment’s ServiceAccount is separate from the task Job `serviceAccountName` you configure in `pod_template`. The Deployment ServiceAccount needs RBAC to manage Jobs and Pods. The task ServiceAccount (if any) controls what the agent process can access at runtime. *** ## Preflight check [Section titled “Preflight check”](#preflight-check) On startup, the worker creates a short-lived preflight Job to verify that: * The worker has sufficient RBAC permissions in the target namespace. * Cluster admission policies (Pod Security Standards, OPA Gatekeeper, Kyverno, etc.) allow the worker’s task pod shape. * The preflight image can be pulled. If the preflight fails, the worker logs a diagnostic error and exits before accepting any tasks. This surfaces policy and configuration issues at deploy time rather than at task execution time. The preflight image defaults to `busybox:1.36`. If your cluster restricts allowed registries or images, set `preflight_image` to an allowlisted image. When `imagePullSecrets` is configured in `pod_template`, those secrets apply to the preflight Job as well, so you can point `preflight_image` at an image in your private registry. *** ## Environment variables for Kubernetes tasks [Section titled “Environment variables for Kubernetes tasks”](#environment-variables-for-kubernetes-tasks) There are two ways to pass environment variables to Kubernetes task containers: 1. **`pod_template`** (recommended for Kubernetes-native config) — Use standard Kubernetes `env` syntax in the `task` container, including `valueFrom.secretKeyRef` for Kubernetes Secrets. 2. **`-e` / `--env` flags** — Backend-agnostic runtime overrides that work across all managed backends. When configuring the Kubernetes backend via YAML or Helm, declarative task-container env belongs in `pod_template` rather than a separate top-level list. Note If your organization uses an external secrets manager (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, etc.), you can inject secrets into task pods via the CSI Secrets Store Driver or a similar operator. Configure the required `volumes`, `volumeMounts`, and annotations in `pod_template` just as you would for any other Kubernetes workload. See your secrets provider’s documentation for details. *** ## Setup and teardown commands [Section titled “Setup and teardown commands”](#setup-and-teardown-commands) Use `kubernetesBackend.setupCommand` (Helm value) or `backend.kubernetes.setup_command` ([config file](/agent-platform/cloud-agents/self-hosting/reference/#kubernetes-backend-config)) to run a shell command before each task. Use `teardownCommand` / `teardown_command` for cleanup after the task finishes. These run inside the task Pod and are useful for workspace bootstrapping or post-run reporting. *** ## Metrics [Section titled “Metrics”](#metrics) The Helm chart includes built-in support for exporting OpenTelemetry metrics from the worker. Enable metrics by setting `metrics.enabled=true`: ```bash helm install oz-agent-worker ./charts/oz-agent-worker \ --namespace warp-oz \ --set worker.workerId=oz-k8s-worker \ --set image.tag=VERSION \ --set metrics.enabled=true ``` With the default `metrics.exporter=prometheus`, the chart creates a `Service` with Prometheus scrape annotations and exposes port `9464`. For clusters using the Prometheus Operator, set `metrics.podMonitor.create=true` to create a `PodMonitor`. To push metrics to an OTLP collector instead, set `metrics.exporter=otlp` and configure the endpoint via `metrics.extraEnv`. See [Monitoring](/agent-platform/cloud-agents/self-hosting/monitoring/) for the full list of Helm values, the metric catalog, and sample PromQL queries. *** ## Operational notes [Section titled “Operational notes”](#operational-notes) * **Scaling** — The chart always deploys a single replica for a given `worker.workerId`. To run multiple workers, deploy multiple Helm releases with distinct worker IDs rather than scaling a single release horizontally. * **Security context** — The Deployment defaults to a non-root security context (`runAsUser: 10001`) with `allowPrivilegeEscalation: false` and all capabilities dropped. * **Liveness probe** — The Deployment includes a default `exec` liveness probe (`kill -0 1`). Override `worker.livenessProbe` for a custom probe, or set it to `null` to disable. * **In-cluster auth** — The chart assumes the worker runs inside the target cluster and uses in-cluster Kubernetes auth by default. * **Root init containers** — The worker Deployment itself is non-root, but task Jobs require a root init container for sidecar materialization. Ensure the task namespace’s Pod Security Standards allow this. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosted worker reference](/agent-platform/cloud-agents/self-hosting/reference/) — Full CLI flag and config file schema, including every Kubernetes backend field. * [Self-hosting overview](/agent-platform/cloud-agents/self-hosting/) — Managed vs unmanaged and the backend decision guide. * [Routing runs to self-hosted workers](/agent-platform/cloud-agents/self-hosting/#routing-runs-to-self-hosted-workers) — How to send tasks to your connected worker from the CLI, schedules, integrations, the API, and the web UI. * [Environments](/agent-platform/cloud-agents/environments/) — Define the task image, repos, and setup commands. * [Monitoring](/agent-platform/cloud-agents/self-hosting/monitoring/) — OpenTelemetry metrics, including Helm chart metrics values. * [Security and networking](/agent-platform/cloud-agents/self-hosting/security-and-networking/) — RBAC, admission policies, and data boundaries. * [Troubleshooting](/agent-platform/cloud-agents/self-hosting/troubleshooting/#kubernetes-backend) — Common Kubernetes-backend issues. # Self-hosted worker monitoring > Monitor self-hosted Oz workers with OpenTelemetry metrics. Export to Prometheus, OTLP, or console to track worker health, task throughput, and saturation. The `oz-agent-worker` daemon exports infrastructure-level metrics over [OpenTelemetry](https://opentelemetry.io/), giving your team real-time visibility into worker health, task throughput, and capacity. Combine these metrics with the [Oz dashboard](https://oz.warp.dev) for full observability across both the orchestration plane and your self-hosted compute. Note When running the binary directly, metrics export follows the [OpenTelemetry autoexport](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/exporters/autoexport) default — if `OTEL_METRICS_EXPORTER` is unset, the worker pushes OTLP to `localhost:4318`. Set `OTEL_METRICS_EXPORTER=none` to disable export. The Helm chart is opt-in: it only enables export when `metrics.enabled=true`. ## Key features [Section titled “Key features”](#key-features) * **Prometheus scrape** — Expose a `/metrics` endpoint for Prometheus to scrape, with optional `PodMonitor` support for the Prometheus Operator. * **OTLP push** — Push metrics to any OpenTelemetry-compatible collector (Grafana Alloy, Datadog Agent, New Relic, etc.). * **Standard configuration** — Exporter selection uses the standard [OpenTelemetry environment variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/), so the worker integrates with your existing observability stack without custom configuration. * **Pre-seeded series** — All metric series appear at startup (before any tasks run), so dashboards and alerts can reference them immediately. ## How it works [Section titled “How it works”](#how-it-works) The worker uses the [`go.opentelemetry.io/contrib/exporters/autoexport`](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/exporters/autoexport) package to select an exporter at runtime based on the `OTEL_METRICS_EXPORTER` environment variable. Supported values: * `prometheus` — Starts an in-process HTTP server serving `/metrics`. * `otlp` — Pushes metrics over OTLP (HTTP/protobuf by default). * `console` — Writes metrics to stdout (useful for debugging). * `none` — Disables metrics export entirely. When `OTEL_METRICS_EXPORTER` is unset, the worker defaults to OTLP push targeting `OTEL_EXPORTER_OTLP_ENDPOINT` (which itself defaults to `http://localhost:4318` for `http/protobuf` or `http://localhost:4317` for `grpc`). All metrics carry resource attributes (`service.name=oz-agent-worker`, `service.version`, `worker.id`, `worker.backend`) so each worker process shows up as a distinct series in your monitoring system. *** ## Enable Prometheus scrape [Section titled “Enable Prometheus scrape”](#enable-prometheus-scrape) Set these environment variables before starting the worker to expose a Prometheus-compatible `/metrics` endpoint: ```bash export OTEL_METRICS_EXPORTER=prometheus export OTEL_EXPORTER_PROMETHEUS_HOST=0.0.0.0 export OTEL_EXPORTER_PROMETHEUS_PORT=9464 oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" ``` Verify the endpoint is serving metrics: ```bash curl -s localhost:9464/metrics | grep oz_worker_ ``` **Expected outcome:** You see `oz_worker_connected`, `oz_worker_tasks_active`, and other `oz_worker_*` metric families in the output. Note Bind to `0.0.0.0` (not `localhost`) when running in Docker or Kubernetes so the Prometheus server, kubelet, or scrape target can reach the endpoint from outside the container. *** ## Enable OTLP push [Section titled “Enable OTLP push”](#enable-otlp-push) Set these environment variables to push metrics to an OpenTelemetry collector: ```bash export OTEL_METRICS_EXPORTER=otlp export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.observability.svc:4318 oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" ``` The worker pushes metrics at the SDK’s default interval. Configure the collector endpoint, protocol, and headers using standard [OTLP exporter environment variables](https://opentelemetry.io/docs/specs/otel/protocol/exporter/). *** ## Helm chart configuration [Section titled “Helm chart configuration”](#helm-chart-configuration) The [Helm chart](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/) includes built-in support for metrics. Enable metrics with `metrics.enabled=true`: ```bash helm install oz-agent-worker ./charts/oz-agent-worker \ --namespace warp-oz \ --set worker.workerId=my-worker \ --set image.tag=VERSION \ --set metrics.enabled=true ``` With `metrics.enabled=true` and the default `metrics.exporter=prometheus`, the chart adds: * A `containerPort: metrics` (default 9464) on the worker Deployment. * The `OTEL_METRICS_EXPORTER`, `OTEL_EXPORTER_PROMETHEUS_HOST`, and `OTEL_EXPORTER_PROMETHEUS_PORT` environment variables. * A namespace-scoped `Service` named `-oz-agent-worker-metrics` with `prometheus.io/scrape` annotations. * Optionally, a `PodMonitor` (`metrics.podMonitor.create=true`) for clusters using the Prometheus Operator. ### Helm values [Section titled “Helm values”](#helm-values) **Core:** * `metrics.enabled` — Enable metrics export. Defaults to `false`. * `metrics.exporter` — Exporter type: `prometheus` (default), `otlp`, `console`, or `none`. * `metrics.port` — Port for the Prometheus exporter. Defaults to `9464`. Ignored for `otlp`/`console`. * `metrics.extraEnv` — Extra environment variables for the worker container (e.g., `OTEL_EXPORTER_OTLP_ENDPOINT`). **Service (Prometheus scrape):** * `metrics.service.create` — Create a metrics `Service`. Defaults to `true`. * `metrics.service.type` — Service type. Defaults to `ClusterIP`. * `metrics.service.annotations` — Annotations on the Service. Defaults include `prometheus.io/scrape: "true"`. **PodMonitor (Prometheus Operator):** * `metrics.podMonitor.create` — Create a `PodMonitor`. Defaults to `false` (avoids requiring `monitoring.coreos.com` CRDs). * `metrics.podMonitor.interval` — Scrape interval. Defaults to `30s`. * `metrics.podMonitor.scrapeTimeout` — Scrape timeout. Defaults to `10s`. * `metrics.podMonitor.additionalLabels` — Extra labels on the `PodMonitor` resource. ### OTLP push via Helm [Section titled “OTLP push via Helm”](#otlp-push-via-helm) To push metrics to an OTLP collector instead of exposing a Prometheus endpoint, set `metrics.exporter=otlp` and forward the endpoint via `metrics.extraEnv`: ```yaml metrics: enabled: true exporter: otlp extraEnv: - name: OTEL_EXPORTER_OTLP_ENDPOINT value: http://otel-collector.observability.svc:4318 ``` *** ## Metric catalog [Section titled “Metric catalog”](#metric-catalog) All metrics use the `oz_worker_` prefix. Each worker process emits a distinct set of series, identified by the resource attributes `service.name`, `service.version`, `worker.id`, and `worker.backend`. * **`oz_worker_connected`** (gauge) — `1` while the worker has an active WebSocket connection to Oz’s backend, `0` otherwise. * **`oz_worker_tasks_active`** (gauge / UpDownCounter) — Tasks currently executing on this worker. * **`oz_worker_tasks_max_concurrent`** (gauge) — Configured concurrency limit (`0` means unlimited). * **`oz_worker_tasks_claimed_total`** (counter) — Total tasks accepted since process start. * **`oz_worker_tasks_rejected_total{reason}`** (counter) — Tasks the worker declined (e.g., `reason="at_capacity"`). * **`oz_worker_tasks_completed_total{result}`** (counter) — Completed tasks labeled `result="succeeded"` or `result="failed"`. * **`oz_worker_task_duration_seconds{result}`** (histogram) — Wall-clock task duration on the worker, labeled by result. * **`oz_worker_websocket_reconnects_total{reason}`** (counter) — WebSocket reconnect attempts (e.g., `reason="dial_failed"`, `reason="remote_close"`). Spikes indicate flapping workers. * **`oz_worker_info{version,backend,worker_id}`** (gauge, constant `1`) — Build and runtime metadata. Useful for joining other series by labels. *** ## Sample PromQL queries [Section titled “Sample PromQL queries”](#sample-promql-queries) Direct mappings for common operational questions: * **Workers available:** ```promql sum(oz_worker_connected) ``` * **Workers active (running at least one task):** ```promql count(oz_worker_tasks_active > 0) ``` * **Fleet saturation:** ```promql sum(oz_worker_tasks_active) / sum(oz_worker_tasks_max_concurrent > 0) ``` This ratio is only meaningful when every worker has a non-zero `oz_worker_tasks_max_concurrent`. Workers configured with `0` (unlimited) are excluded from the denominator, which can make the saturation result look misleadingly high or undefined for fleets that mix bounded and unlimited workers. * **Task success rate (5-minute window):** ```promql sum(rate(oz_worker_tasks_completed_total{result="succeeded"}[5m])) / sum(rate(oz_worker_tasks_completed_total[5m])) ``` * **Task duration p95:** ```promql histogram_quantile(0.95, sum by (le) (rate(oz_worker_task_duration_seconds_bucket[5m]))) ``` * **Failure rate:** ```promql sum(rate(oz_worker_tasks_completed_total{result="failed"}[5m])) ``` * **Reconnect storms (alert threshold):** ```promql sum(rate(oz_worker_websocket_reconnects_total[5m])) > 0.1 ``` *** ## Disabling metrics [Section titled “Disabling metrics”](#disabling-metrics) To fully disable metrics export, set `OTEL_METRICS_EXPORTER=none`: ```bash export OTEL_METRICS_EXPORTER=none oz-agent-worker --api-key "$WARP_API_KEY" --worker-id "my-worker" ``` Or in the Helm chart: ```yaml metrics: enabled: false ``` *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosting overview](/agent-platform/cloud-agents/self-hosting/) — Architecture, decision guide, and Enterprise requirements. * [Self-hosted worker reference](/agent-platform/cloud-agents/self-hosting/reference/) — CLI flags, config file schema, and metrics environment variables. * [Managed: Kubernetes](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/) — Helm chart deployment, including metrics values. * [Troubleshooting](/agent-platform/cloud-agents/self-hosting/troubleshooting/) — Diagnostics for metrics issues and other common problems. * [Security and networking](/agent-platform/cloud-agents/self-hosting/security-and-networking/) — Network egress and data boundaries. # Self-hosting quickstart > Get a managed self-hosted Oz worker running on Docker and route your first cloud agent run to it in under 10 minutes. Run your first Oz cloud agent on your own infrastructure in \~10 minutes using the managed architecture with the Docker backend — the default and fastest path to self-hosting. Note This quickstart sets up the [managed architecture](/agent-platform/cloud-agents/self-hosting/#managed-architecture), where Oz orchestrates the agent and your worker provides the compute. **Prefer a CLI-only path with no Docker requirement?** Jump to the [Unmanaged quickstart](/agent-platform/cloud-agents/self-hosting/unmanaged/#unmanaged-quickstart) to run `oz agent run` directly on any host. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Enterprise plan with self-hosting enabled** — [Contact sales](https://warp.dev/contact-sales) if self-hosting is not yet enabled for your team. * **A Linux machine with Docker** — A VM, server, or local machine with the Docker daemon running Linux containers. Verify with `docker info`. Docker Desktop on macOS or Windows works for testing. * **A team API key** — In the Warp app, go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create a team-scoped API key. See [API Keys](/reference/cli/api-keys/) for details. * **The Oz CLI** (for routing a test run) — See [Installing the CLI](/reference/cli/#installing-the-cli). *** ## Run your first self-hosted agent [Section titled “Run your first self-hosted agent”](#run-your-first-self-hosted-agent) *\~10 minutes* ### 1. Export your API key [Section titled “1. Export your API key”](#1-export-your-api-key) Export the team API key so the worker container can authenticate to Oz automatically: ```bash export WARP_API_KEY="your_team_api_key" ``` ### 2. Start the worker [Section titled “2. Start the worker”](#2-start-the-worker) Run the `oz-agent-worker` container, mounting the host’s Docker socket so the worker can spawn task containers. Choose any `--worker-id` meaningful for your team — you’ll use this value to route tasks to this worker. ```bash docker run -v /var/run/docker.sock:/var/run/docker.sock \ -e WARP_API_KEY="$WARP_API_KEY" \ warpdotdev/oz-agent-worker --worker-id "my-worker" ``` **Expected outcome:** The worker connects to Oz and begins listening for tasks. You should see log output confirming the connection (something like `Connected to Oz` / `Waiting for tasks`). Caution For production deployments, pin to a specific image digest (e.g., `warpdotdev/oz-agent-worker@sha256:...`) instead of the `latest` tag. ### 3. Route a run to your worker [Section titled “3. Route a run to your worker”](#3-route-a-run-to-your-worker) In a separate terminal on any machine with the Oz CLI, route a cloud agent run to your worker by passing `--host` with the worker ID you chose: ```bash oz agent run-cloud --prompt "List the files in the current directory" --host "my-worker" ``` **Expected outcome:** Oz accepts the task, routes it to your worker, and the worker spawns a Docker container to execute the agent. You’ll see the run appear in the [Oz dashboard](https://oz.warp.dev) with status moving from `QUEUED` → `INPROGRESS` → `SUCCEEDED`. ### 4. Verify the run [Section titled “4. Verify the run”](#4-verify-the-run) Open the [Oz dashboard](https://oz.warp.dev), find the new task, and confirm the session transcript shows the agent running against your worker. You can attach to the session at any time via [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) to monitor or steer it. *** ## Next steps [Section titled “Next steps”](#next-steps) * [Unmanaged quickstart](/agent-platform/cloud-agents/self-hosting/unmanaged/#unmanaged-quickstart) — \~5-minute CLI-only path: run `oz agent run` in your CI, Kubernetes pod, or dev box with no worker daemon and no Docker requirement. * [Managed: Docker](/agent-platform/cloud-agents/self-hosting/managed-docker/) — Full Docker backend setup, including private registries, volume mounts, and runtime configuration. * [Environments](/agent-platform/cloud-agents/environments/) — Define a repository, Docker image, and setup commands so agents have a reproducible workspace for every run. * [Routing runs to self-hosted workers](/agent-platform/cloud-agents/self-hosting/#routing-runs-to-self-hosted-workers) — How to route tasks from schedules, integrations (Slack, Linear), the API, and the Oz web app. * [Managed: Kubernetes](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/) — Deploy workers into a Kubernetes cluster with Helm. * [Self-hosted worker reference](/agent-platform/cloud-agents/self-hosting/reference/) — All CLI flags and config file options. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) **Worker won’t start**\ Verify Docker is running (`docker info`) and that the daemon platform is `linux/amd64` or `linux/arm64`. Musl-based (Alpine) worker hosts are not supported. **Worker won’t connect**\ Verify your API key has team scope. Ensure the machine has outbound internet access to `oz.warp.dev:443`. Increase log verbosity with `--log-level debug` to see connection details. **Task stays queued and never runs**\ Confirm the `--host` value you passed to `oz agent run-cloud` matches your `--worker-id` exactly (case-sensitive). Check that the worker’s team matches the team creating the task. For more, see [Troubleshooting](/agent-platform/cloud-agents/self-hosting/troubleshooting/). # Self-hosted worker reference > Complete reference for the oz-agent-worker daemon — CLI flags and config file schema for the Docker, Kubernetes, and Direct backends. Reference for the `oz-agent-worker` daemon: CLI flags and the full YAML config-file schema for all three [managed backends](/agent-platform/cloud-agents/self-hosting/#managed-architecture) — Docker, Kubernetes, and Direct. Note This page documents every flag and config option. For installation and backend-specific setup walkthroughs, see [Managed: Docker](/agent-platform/cloud-agents/self-hosting/managed-docker/), [Managed: Kubernetes](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/), or [Managed: Direct](/agent-platform/cloud-agents/self-hosting/managed-direct/). This reference applies to the managed architecture only; the [unmanaged architecture](/agent-platform/cloud-agents/self-hosting/unmanaged/) uses `oz agent run` instead. *** ## Worker flags [Section titled “Worker flags”](#worker-flags) The following flags are available when starting the worker. ### Required [Section titled “Required”](#required) * `--worker-id` — A string identifying this worker. This is the value you pass to `--host` when routing tasks. Choose something meaningful for your team (e.g., `prod-runner-1` or `ci-worker`). Multiple workers can share the same ID for load balancing. * `--api-key` or `WARP_API_KEY` env var — Your team API key for authentication. When running via Docker, pass it as `-e WARP_API_KEY="..."`. When running the binary directly, use `--api-key` or the environment variable. ### Optional [Section titled “Optional”](#optional) * `--config-file` — Path to a YAML [config file](#config-file). CLI flags take precedence over config file values. * `--backend` — Backend type: `docker` (default), `kubernetes`, or `direct`. See [Managed: Kubernetes](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/) and [Managed: Direct](/agent-platform/cloud-agents/self-hosting/managed-direct/) for backend-specific setup. * `--log-level` — Log verbosity. One of `debug`, `info`, `warn`, `error`. Defaults to `info`. * `--no-cleanup` — Keep task containers, Kubernetes Jobs, or workspace directories after execution instead of removing them. Useful for debugging failed tasks. * `-v` / `--volumes` — Mount host directories into task containers (Docker backend only). Format: `HOST_PATH:CONTAINER_PATH` or `HOST_PATH:CONTAINER_PATH:MODE` (where MODE is `ro` or `rw`). Can be specified multiple times. * `-e` / `--env` — Set environment variables for tasks. Format: `KEY=VALUE` (explicit value) or `KEY` (pass through from host environment). Can be specified multiple times. * `--max-concurrent-tasks` — Maximum number of tasks to run concurrently. Defaults to `0` (unlimited). When set, additional tasks wait until a slot is available. * `--idle-on-complete` — How long to keep the `oz` process alive after a task’s conversation finishes, allowing follow-up interactions via session sharing. Uses duration format (e.g. `45m`, `10m`, `0s`). Defaults to `45m` when not set. Set to `0s` to disable. Note Worker IDs starting with `warp` are reserved and cannot be used. The worker refuses to start if `--worker-id` begins with `warp`. ### Example with all flags [Section titled “Example with all flags”](#example-with-all-flags) ```bash docker run -v /var/run/docker.sock:/var/run/docker.sock \ -e WARP_API_KEY="$WARP_API_KEY" \ warpdotdev/oz-agent-worker \ --worker-id "prod-runner-1" \ --log-level debug \ --no-cleanup \ --max-concurrent-tasks 4 \ --idle-on-complete 10m \ -v /opt/shared-cache:/cache:ro \ -e NPM_TOKEN=your_token \ -e GITHUB_TOKEN ``` Caution When running the worker via Docker, there are two levels of `-e` flags. Docker’s `-e` passes env vars to the **worker container** (e.g., `WARP_API_KEY`). The worker’s `-e` / `--env` flags pass env vars into the **task containers** the worker spawns. Keep these distinct. *** ## Config file [Section titled “Config file”](#config-file) For complex setups, use a YAML config file instead of (or in addition to) CLI flags. Pass it with `--config-file`: ```bash oz-agent-worker --api-key "$WARP_API_KEY" --config-file config.yaml ``` CLI flags always take precedence over config file values. ### Docker backend config [Section titled “Docker backend config”](#docker-backend-config) ```yaml worker_id: "my-worker" cleanup: true max_concurrent_tasks: 4 idle_on_complete: "10m" backend: docker: volumes: - "/data:/data:ro" - "/cache:/cache" environment: - name: NPM_TOKEN value: "your_token" - name: GITHUB_TOKEN # inherits from host environment ``` ### Kubernetes backend config [Section titled “Kubernetes backend config”](#kubernetes-backend-config) ```yaml worker_id: "k8s-worker" max_concurrent_tasks: 4 backend: kubernetes: namespace: "warp-oz" default_image: "my-registry.io/dev-image:latest" unschedulable_timeout: "2m" pod_template: nodeSelector: kubernetes.io/os: linux containers: - name: task resources: requests: cpu: "2" memory: 4Gi env: - name: GITHUB_TOKEN valueFrom: secretKeyRef: name: my-k8s-secret key: github-token ``` ### Direct backend config [Section titled “Direct backend config”](#direct-backend-config) ```yaml worker_id: "direct-worker" max_concurrent_tasks: 2 backend: direct: workspace_root: "/var/lib/oz/workspaces" oz_path: "/usr/local/bin/oz" setup_command: "/opt/scripts/setup.sh" teardown_command: "/opt/scripts/teardown.sh" environment: - name: MY_VAR value: "hello" ``` ### Config file fields [Section titled “Config file fields”](#config-file-fields) **Top-level:** * `worker_id` — Worker identifier (same as `--worker-id` flag). * `cleanup` — Whether to clean up after tasks. Defaults to `true`. Set to `false` to keep containers/workspaces for debugging (equivalent to `--no-cleanup`). * `max_concurrent_tasks` — Maximum concurrent tasks. Defaults to unlimited. * `idle_on_complete` — Duration to keep the `oz` process alive after task completion (e.g. `"45m"`, `"0s"`). * `backend` — Backend configuration block. Only one backend (`docker`, `kubernetes`, or `direct`) may be specified. **`backend.docker`:** * `volumes` — List of volume mounts (same format as `-v` flag). * `environment` — List of environment variables with `name` and optional `value`. If `value` is omitted, the variable is inherited from the host. **`backend.kubernetes`:** * `namespace` — Kubernetes namespace for task Jobs. Defaults to `default`. Selects the namespace inside the chosen cluster; does not choose the cluster. * `kubeconfig` — Path to an explicit kubeconfig file. If omitted, the worker uses in-cluster config when running inside Kubernetes, or falls back to the default kubeconfig loading rules. * `default_image` — Default Docker image for task Jobs when the run has no Warp environment image. Precedence: Warp environment image > `default_image` > `ubuntu:22.04`. Set this to skip creating a Warp environment when all your tasks use the same base image. * `image_pull_policy` — One of `Always`, `Never`, or `IfNotPresent`. Defaults to `IfNotPresent`. * `preflight_image` — Image used for the startup preflight Job. Defaults to `busybox:1.36`. Override this if your cluster only allows pulling from an internal or allowlisted registry. * `setup_command` — Shell command to run before each task. * `teardown_command` — Shell command to run after each task completes. * `extra_labels` — Map of additional labels to add to task Jobs and Pods. * `extra_annotations` — Map of additional annotations to add to task Jobs and Pods. * `active_deadline_seconds` — Maximum lifetime for a task Job (Kubernetes `activeDeadlineSeconds`). * `workspace_size_limit` — Size limit for the workspace `emptyDir` volume (e.g., `10Gi`). * `unschedulable_timeout` — How long a pod may remain unschedulable before the task is failed early. Defaults to `30s`. Set to `0s` to disable the fail-fast behavior. * `pod_template` — Raw Kubernetes PodSpec YAML merged with the worker’s required fields at runtime. Use this to configure task pod scheduling, `serviceAccountName`, `imagePullSecrets`, `nodeSelector`, `tolerations`, resources, and environment variables (including `valueFrom.secretKeyRef` for Kubernetes Secrets). Define a container named `task` to customize the main task container directly; otherwise the worker appends its own. **`backend.direct`:** * `workspace_root` — Directory where per-task workspaces are created. Defaults to `/var/lib/oz/workspaces`. * `oz_path` — Path to the oz CLI binary. If omitted, the worker looks up `oz` in `PATH`. * `setup_command` — Shell command to run before each task. Receives `OZ_WORKSPACE_ROOT`, `OZ_RUN_ID`, `OZ_ENVIRONMENT_FILE`, and `OZ_WORKER_BACKEND` as environment variables. * `teardown_command` — Shell command to run after each task completes. * `environment` — List of environment variables (same format as the Docker backend). Note Only one backend can be configured at a time. Specifying more than one of `docker`, `kubernetes`, and `direct` in the same config file is an error. *** ## Metrics configuration [Section titled “Metrics configuration”](#metrics-configuration) The worker exports metrics over OpenTelemetry. Exporter selection is controlled by standard environment variables, not CLI flags or config file fields. Set these variables on the worker process (or the worker container via Docker `-e` / Kubernetes `env`). * `OTEL_METRICS_EXPORTER` — Exporter to use: `prometheus`, `otlp`, `console`, or `none`. When unset, defaults to `otlp`. * `OTEL_EXPORTER_PROMETHEUS_HOST` — Bind address for the Prometheus exporter. Defaults to `localhost`. Set to `0.0.0.0` when running in Docker or Kubernetes. * `OTEL_EXPORTER_PROMETHEUS_PORT` — Port for the Prometheus exporter. Defaults to `9464`. * `OTEL_EXPORTER_OTLP_ENDPOINT` — OTLP collector endpoint (e.g., `http://otel-collector.observability.svc:4318`). * `OTEL_EXPORTER_OTLP_PROTOCOL` — OTLP protocol: `http/protobuf` (default) or `grpc`. When deploying with the Helm chart, use the `metrics.*` values instead of setting these variables manually. See [Monitoring](/agent-platform/cloud-agents/self-hosting/monitoring/) for the full setup guide, metric catalog, Helm values, and sample PromQL queries. *** ## Routing runs to self-hosted workers [Section titled “Routing runs to self-hosted workers”](#routing-runs-to-self-hosted-workers) Once a worker is running, route cloud agent runs to it with the `--host` flag or its equivalents. See [Routing runs to self-hosted workers](/agent-platform/cloud-agents/self-hosting/#routing-runs-to-self-hosted-workers) for examples across the CLI, schedules, integrations, the API, and the web UI. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Managed: Docker](/agent-platform/cloud-agents/self-hosting/managed-docker/) — Docker backend setup, connectivity, and private registries. * [Managed: Kubernetes](/agent-platform/cloud-agents/self-hosting/managed-kubernetes/) — Kubernetes backend setup, Helm chart, pod template, and operational notes. * [Managed: Direct](/agent-platform/cloud-agents/self-hosting/managed-direct/) — Direct backend setup and workspace model. * [Self-hosting overview](/agent-platform/cloud-agents/self-hosting/) — Architecture, decision guide, and Enterprise requirements. * [Environments](/agent-platform/cloud-agents/environments/) — Define the Docker image, repos, and setup commands used by task containers. * [Monitoring](/agent-platform/cloud-agents/self-hosting/monitoring/) — OpenTelemetry metrics for worker health, task throughput, and capacity. * [Troubleshooting](/agent-platform/cloud-agents/self-hosting/troubleshooting/) — Worker and task failure diagnostics. # Security and networking > Security model, data boundaries, and network requirements for self-hosted Oz cloud agents — including per-backend considerations and BYOLLM. Self-hosting uses a split-plane architecture. Understanding which data stays on your infrastructure and which data routes through Warp is critical for security evaluation. This page summarizes the data model, network egress requirements, and backend-specific security considerations for self-hosted workers. Note This page applies to both the [managed](/agent-platform/cloud-agents/self-hosting/#managed-architecture) and [unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/) architectures. Backend-specific notes call out Docker-, Kubernetes-, and Direct-only considerations. ## Data boundaries [Section titled “Data boundaries”](#data-boundaries) **Stored and executed only on your infrastructure:** * Repository clones and source files. * Build artifacts and compiled outputs. * Runtime secrets and environment variables. * Container filesystem state (managed architecture) or host workspace (Direct backend / unmanaged). **Routes through Warp’s backend** (under [Zero Data Retention (ZDR)](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr)): * Orchestration metadata (task status, lifecycle events). * Session transcripts, which include agent-generated summaries of code context, file contents the agent reads, and command output. * LLM inference requests and responses, which include code context from the agent’s interactions. Note While repositories are cloned and stored only on your infrastructure, code content appears in session transcripts and LLM prompts as part of normal agent operation. All data routed through Warp’s backend is covered by [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements — Warp does not persistently store your source code or use it for model training. *** ## Network requirements [Section titled “Network requirements”](#network-requirements) Self-hosted Oz agents **do not require any network ingress**. They require outbound (egress) access to the following services: **Warp’s backend (all architectures):** * `app.warp.dev` — port 443 * `rtc.app.warp.dev` — port 443 * `sessions.app.warp.dev` — port 443 * `oz.warp.dev` — port 443 (managed architecture only) **Docker Hub** — for pulling task images (managed architecture only). Tasks use the following Docker images: * [`warpdotdev/warp-agent:latest`](https://hub.docker.com/r/warpdotdev/warp-agent) * [`warpdotdev/warp-xvfb-sidecar:latest`](https://hub.docker.com/r/warpdotdev/warp-xvfb-sidecar) (only if [computer use](/agent-platform/capabilities/computer-use/) is enabled) * [`warpdotdev/warp-claude-cli-sidecar:latest`](https://hub.docker.com/r/warpdotdev/warp-claude-cli-sidecar) (only if using Claude Code) * [`warpdotdev/warp-codex-cli-sidecar:latest`](https://hub.docker.com/r/warpdotdev/warp-codex-cli-sidecar) (only if using Codex) * The base image specified by your [environment](/agent-platform/cloud-agents/environments/) **GitHub (`github.com`)** — only with the managed architecture, when using a Warp [environment](/agent-platform/cloud-agents/environments/) with configured GitHub repositories. **Linux distribution-specific package repositories** — only with the managed architecture, when using a Warp environment whose base image does not have Git pre-installed. The exact repositories depend on the package manager configuration in the environment’s base image. Note All traffic uses HTTPS (port 443). No inbound ports need to be opened. *** ## Backend-specific security considerations [Section titled “Backend-specific security considerations”](#backend-specific-security-considerations) ### Docker backend [Section titled “Docker backend”](#docker-backend) * **Docker socket access** — The worker requires access to the Docker daemon to create task containers. When running the worker via Docker, this means mounting `/var/run/docker.sock`. Ensure appropriate access controls on the host. * **Volume mounts** — If using `-v` / `--volumes`, be mindful of what host paths you expose to task containers. * **Task isolation** — Each task runs in its own container. Containers are removed after execution by default (disable with `--no-cleanup` for debugging). ### Kubernetes backend [Section titled “Kubernetes backend”](#kubernetes-backend) * **Kubernetes RBAC** — The worker needs namespaced permissions to create, get, list, watch, and delete Jobs and Pods. The Helm chart creates a minimal Role/RoleBinding scoped to a single namespace. The task namespace must allow creating Jobs with a root init container, as sidecar materialization currently depends on that pattern. Review your Pod Security Standards and admission policies accordingly. * **Kubernetes service accounts** — The worker Deployment’s ServiceAccount (used by the long-lived worker process) is separate from the optional task Job `serviceAccountName` you may configure in `pod_template`. Scope each appropriately. * **API key management** — Store `WARP_API_KEY` in a Kubernetes Secret. Avoid hardcoding it in scripts or config files. If your organization uses an external secrets manager (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, etc.), you can inject secrets into task pods via the CSI Secrets Store Driver or a similar operator — configure the required `volumes`, `volumeMounts`, and annotations in `pod_template`. * **Task isolation** — Each task runs as a separate Kubernetes Job/Pod. Jobs are removed after execution by default (disable with `--no-cleanup` for debugging). ### Direct backend [Section titled “Direct backend”](#direct-backend) * **Shared host kernel** — The Direct backend does not provide container-level isolation. Each task runs in an isolated workspace directory but shares the host OS and kernel. * **Minimal environment by default** — The Direct backend intentionally starts tasks with a minimal environment (`HOME`, `TMPDIR`, `PATH` only). Sensitive worker credentials like `WARP_API_KEY` are not passed to tasks unless explicitly configured. * **Workspace cleanup** — Workspaces under `workspace_root` are removed after execution by default (disable with `--no-cleanup` for debugging). ### Unmanaged [Section titled “Unmanaged”](#unmanaged) * **Host inheritance** — Agents inherit the host’s network access, tools, and credentials. If the host has access to a VPN or internal services, the agent will too. Evaluate accordingly. * **Kubernetes pod isolation** — Whether Kubernetes pods provide sufficient sandboxing for agents depends on your cluster configuration and risk profile. Evaluate your pod security policies, network policies, and RBAC settings based on your organization’s security requirements. *** ## VPN and on-premises access [Section titled “VPN and on-premises access”](#vpn-and-on-premises-access) Since self-hosted agents run on your infrastructure, they inherit your network access. Self-hosted agents can reach services behind VPNs, self-hosted GitLab/Bitbucket instances, databases, and any other internal resources your host can reach. This is one of the primary reasons teams choose self-hosting. See [GitLab](/agent-platform/cloud-agents/integrations/gitlab/) and [Bitbucket](/agent-platform/cloud-agents/integrations/bitbucket/) setup guides for SCM integration details. *** ## LLM inference and BYOLLM [Section titled “LLM inference and BYOLLM”](#llm-inference-and-byollm) LLM inference routes through Warp’s backend, which has [ZDR](/enterprise/security-and-compliance/security-overview/#zero-data-retention-zdr) agreements with all contracted model providers. Enterprise teams that need full control over inference routing can use [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) to route inference through their own cloud provider accounts. BYOLLM currently applies to interactive (local) agents; cloud agent BYOLLM support is coming. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosting overview](/agent-platform/cloud-agents/self-hosting/) — Managed vs unmanaged and architecture decision guide. * [Security overview](/enterprise/security-and-compliance/security-overview/) — Warp’s broader security model, including ZDR. * [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/) — Route inference through your own cloud provider accounts. * [Self-hosted worker reference](/agent-platform/cloud-agents/self-hosting/reference/) — CLI flags and config schema, including every security-relevant option. # Self-hosting troubleshooting > Diagnose and fix common problems with self-hosted Oz worker daemons across Docker, Kubernetes, and Direct backends. Diagnostic guides for the `oz-agent-worker` daemon and its task execution. Use this page when a worker won’t start, won’t connect, tasks stay queued, or tasks fail. Note The steps below apply to the [managed architecture](/agent-platform/cloud-agents/self-hosting/#managed-architecture) (`oz-agent-worker` daemon). For [unmanaged](/agent-platform/cloud-agents/self-hosting/unmanaged/) deployments, refer to the documentation for the environment running `oz agent run` (e.g., GitHub Actions, Kubernetes). *** ## Worker won’t start [Section titled “Worker won’t start”](#worker-wont-start) ### Docker backend [Section titled “Docker backend”](#docker-backend) **Cause:** Docker isn’t running, or the daemon platform isn’t supported. **Fix:** 1. Verify Docker is running: `docker info`. 2. Confirm the daemon platform is `linux/amd64` or `linux/arm64`. Windows containers are not supported. 3. If the worker runs inside Docker, confirm the `/var/run/docker.sock` mount is correct and the mounting user has permission to the socket. ### Kubernetes backend [Section titled “Kubernetes backend”](#kubernetes-backend) **Cause:** The startup preflight Job failed. Common reasons include insufficient RBAC, restrictive Pod Security policies, or an unreachable Kubernetes API server. **Fix:** 1. Check the worker logs for the preflight diagnostic message. 2. Confirm the worker’s namespace has these permissions: `create`, `get`, `list`, `watch`, `delete` on `jobs`; `get`, `list`, `watch` on `pods`; `get` on `pods/log`; `list` on `events`. 3. Confirm the task namespace allows pods with a **root init container** (required for sidecar materialization). 4. If your cluster restricts image sources, set `preflight_image` in the worker config to an allowlisted image (default is `busybox:1.36`). 5. To pull the preflight image from a private registry, configure `imagePullSecrets` in `pod_template` — these secrets also apply to the preflight Job. ### Direct backend [Section titled “Direct backend”](#direct-backend) **Cause:** The `oz` CLI isn’t installed or isn’t on the worker’s `PATH`. **Fix:** 1. Install the Oz CLI on the worker host. See [Installing the CLI](/reference/cli/#installing-the-cli). 2. If the CLI isn’t on `PATH`, set `oz_path` in the config file to the absolute path of the `oz` binary. *** ## Worker won’t connect [Section titled “Worker won’t connect”](#worker-wont-connect) **Cause:** The API key is invalid, expired, or the host cannot reach Oz’s backend. **Fix:** 1. Confirm your API key is correct, not expired, and has team scope. 2. Regenerate the API key in **Settings** > **Cloud platform** > **Oz Cloud API Keys** if you suspect it’s invalid. 3. Ensure the host has outbound internet access to `oz.warp.dev:443`. 4. Check that no firewall rules are blocking WebSocket connections to `wss://oz.warp.dev`. 5. Increase log verbosity with `--log-level debug` to see connection details. See [Security and networking](/agent-platform/cloud-agents/self-hosting/security-and-networking/#network-requirements) for the full list of outbound endpoints the worker needs. *** ## Tasks not being picked up [Section titled “Tasks not being picked up”](#tasks-not-being-picked-up) **Cause:** The worker isn’t running, the `--host` value doesn’t match the worker’s `--worker-id`, or the worker and task belong to different teams. **Fix:** 1. Confirm the worker is running and connected. Check the worker logs for `Listening for tasks` or similar. 2. Verify the `--host` (or `worker_host`) value you passed matches your `--worker-id` exactly. Case-sensitive. 3. Ensure the worker’s team matches the team creating the task. *** ## Metrics not appearing [Section titled “Metrics not appearing”](#metrics-not-appearing) **Cause:** The worker is running but metrics aren’t showing up in Prometheus or your collector. **Fix:** 1. Verify `OTEL_METRICS_EXPORTER` is set correctly on the worker process. Run `curl -s localhost:9464/metrics` from the worker host (for `prometheus` mode) to confirm the endpoint is serving. 2. For Prometheus scrape mode, confirm the bind address is `0.0.0.0` (not `localhost`) when running in Docker or Kubernetes. `localhost` is only reachable from inside the container. 3. Confirm no firewall or network policy blocks the metrics port (default `9464`). 4. For OTLP push mode, verify `OTEL_EXPORTER_OTLP_ENDPOINT` points to a reachable collector and that the protocol matches (`http/protobuf` vs `grpc`). 5. When using the Helm chart, confirm `metrics.enabled=true` is set. Check that the `Service` and (optionally) `PodMonitor` were created: `kubectl get svc,podmonitor -n `. 6. If using `metrics.podMonitor.create=true`, verify the `monitoring.coreos.com` CRDs are installed in the cluster. The `PodMonitor` resource requires the Prometheus Operator. 7. Restart the worker with `--log-level debug` and look for metrics-related error messages at startup. See [Monitoring](/agent-platform/cloud-agents/self-hosting/monitoring/) for the full setup guide. *** ## Task failures [Section titled “Task failures”](#task-failures) **Cause:** A variety of reasons depending on backend. Start with the diagnostic steps common to all backends, then follow the backend-specific checks. **Fix (all backends):** 1. Review task logs in the [Oz dashboard](https://oz.warp.dev) or via [session sharing](/agent-platform/local-agents/session-sharing/). 2. Use `--no-cleanup` to keep the container, Job, or workspace around for inspection after failure. 3. Use `--log-level debug` to see detailed execution logs. 4. Ensure the worker machine or cluster has sufficient resources (CPU, memory, disk). ### Docker backend (task failures) [Section titled “Docker backend (task failures)”](#docker-backend-task-failures) 1. Verify Docker is running (`docker info`). 2. If using a custom image, confirm it is **glibc-based** (not Alpine/musl) and that its architecture matches the worker’s Docker daemon platform. ### Kubernetes backend (task failures) [Section titled “Kubernetes backend (task failures)”](#kubernetes-backend-task-failures) 1. Check task Job and Pod status: `kubectl get jobs,pods -n `. 2. Common issues: * **Unschedulable pods** — Check node selectors, tolerations, and resource requests in `pod_template`. * **Image pull failures** — Check `imagePullSecrets` in `pod_template`. * **Admission policy rejections** — Review Pod Security Standards, OPA Gatekeeper, Kyverno, or similar admission controllers. 3. The worker fails a task early if its pod remains unschedulable beyond `unschedulable_timeout` (default `30s`). Raise the timeout or fix the scheduling issue. ### Direct backend (task failures) [Section titled “Direct backend (task failures)”](#direct-backend-task-failures) 1. Verify the Oz CLI is accessible. 2. Verify the workspace root directory has write permissions for the user running the worker. *** ## Image pull failures [Section titled “Image pull failures”](#image-pull-failures) ### Docker backend (image pull) [Section titled “Docker backend (image pull)”](#docker-backend-image-pull) 1. If using a private registry, ensure Docker credentials are available to the worker. See [Private Docker registries](/agent-platform/cloud-agents/self-hosting/managed-docker/#private-docker-registries). 2. Try pulling the image manually on the worker host: `docker pull `. ### Kubernetes backend (image pull) [Section titled “Kubernetes backend (image pull)”](#kubernetes-backend-image-pull) 1. Configure `imagePullSecrets` in the `pod_template` section of your worker config. 2. Verify the Secret exists in the task namespace and contains valid credentials. ### Both backends (image pull) [Section titled “Both backends (image pull)”](#both-backends-image-pull) * Verify the image exists and the tag is correct. * Check network connectivity from the worker/cluster to the registry. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosting overview](/agent-platform/cloud-agents/self-hosting/) — Architecture and decision guide. * [Self-hosted worker reference](/agent-platform/cloud-agents/self-hosting/reference/) — CLI flags and config schema, including every flag mentioned here. * [Security and networking](/agent-platform/cloud-agents/self-hosting/security-and-networking/) — Outbound endpoints the worker needs. * [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) — Attach to running tasks to debug interactively. # Unmanaged architecture > Run Oz agents in your existing CI, Kubernetes, or dev environments using the oz agent run CLI with Warp tracking and observability. With the unmanaged architecture, **you orchestrate agent runs** by invoking `oz agent run` directly from your existing CI pipelines, Kubernetes pods, VMs, or dev boxes. The agent runs on whatever host the command is executed from; Warp tracks the session for you but does not start or stop agents. Note Unmanaged is the right choice if you already have a system that schedules work (CI, internal orchestrators, cron, dev environments). If you’d rather have Oz trigger and route runs from Slack, Linear, schedules, or the API, use the [managed architecture](/agent-platform/cloud-agents/self-hosting/#managed-architecture) instead. ## When to use unmanaged [Section titled “When to use unmanaged”](#when-to-use-unmanaged) * **CI/CD pipelines** — Run agents as part of a build or deployment workflow. This is how the [`warpdotdev/oz-agent-action`](https://github.com/warpdotdev/oz-agent-action) GitHub Action works. * **Kubernetes pods** — Run agents inside pods with access to your cluster’s network and services. * **Dev boxes and VMs** — Run agents in pre-provisioned development environments. Especially useful for large monorepos with long setup times. * **Existing orchestrators** — Drop `oz agent run` into any system that schedules work (Jenkins, Buildkite, internal job schedulers). Unmanaged works on any platform Warp supports (Linux, macOS, Windows) with no dependency on Docker or any other sandboxing platform. *** ## Unmanaged quickstart [Section titled “Unmanaged quickstart”](#unmanaged-quickstart) *\~5 minutes* No Docker, no worker daemon, no environment required — just the Oz CLI on any host that can reach the internet. ### Prerequisites [Section titled “Prerequisites”](#prerequisites) * **The Oz CLI** installed on the machine where agents will run. See [Installing the CLI](/reference/cli/#installing-the-cli) for platform-specific instructions. * **A Warp API key** — For automation, create a team-scoped API key in the Warp app at **Settings** > **Cloud platform** > **Oz Cloud API Keys**. See [API Keys](/reference/cli/api-keys/) for details. ### 1. Authenticate [Section titled “1. Authenticate”](#1-authenticate) Export your API key so the CLI can authenticate requests automatically: ```bash export WARP_API_KEY="your_team_api_key" ``` ### 2. Run an agent [Section titled “2. Run an agent”](#2-run-an-agent) Invoke `oz agent run` in the directory where you want the agent to operate. The agent has access to whatever tools, network resources, and credentials the host provides. ```bash oz agent run --prompt "Refactor the authentication module" --share team ``` **Expected outcome:** The agent starts immediately in the current working directory, and a tracked session appears in the [Oz dashboard](https://oz.warp.dev). ### 3. Control sharing [Section titled “3. Control sharing”](#3-control-sharing) Use `--share` to control who can attach to the session and steer the agent: * `--share` — Share the session with yourself (accessible on other devices or in a browser). * `--share team` or `--share team:view` — Give all team members read-only access. * `--share team:edit` — Give all team members read/write access. * `--share user@example.com` — Give a specific user read-only access. * `--share user@example.com:edit` — Give a specific user read/write access. The `--share` flag can be repeated to combine multiple sharing targets. If you authenticate with a team API key, agents are automatically team-scoped. *** ## Example: GitHub Actions [Section titled “Example: GitHub Actions”](#example-github-actions) Warp maintains the [`warpdotdev/oz-agent-action`](https://github.com/warpdotdev/oz-agent-action) action for running agents in GitHub Actions. The action wraps `oz agent run` and is a drop-in for CI workflows: ```yaml - name: Run Oz agent uses: warpdotdev/oz-agent-action@v1 # wraps `oz agent run` under the hood with: prompt: "Review the code changes on this branch" warp_api_key: ${{ secrets.WARP_API_KEY }} ``` See [GitHub Actions integration](/agent-platform/cloud-agents/integrations/github-actions/) for full details. ## Example: Kubernetes [Section titled “Example: Kubernetes”](#example-kubernetes) Run an agent inside a Kubernetes pod with access to your cluster’s services: ```yaml apiVersion: batch/v1 kind: Job metadata: name: oz-agent-task spec: template: spec: containers: - name: oz-agent image: warpdotdev/warp-agent:latest command: ["agent", "run", "--prompt", "Run the test suite and report failures"] env: - name: WARP_API_KEY valueFrom: secretKeyRef: name: warp-credentials key: api-key restartPolicy: Never ``` Caution For production deployments, pin to a specific Docker image digest (e.g., `warpdotdev/warp-agent@sha256:...`) instead of `latest` to ensure reproducible builds. Note Whether Kubernetes pods provide sufficient sandboxing for agents depends on your cluster configuration and risk profile. Evaluate your pod security policies, network policies, and RBAC settings based on your organization’s security requirements. *** ## Tracking and observability [Section titled “Tracking and observability”](#tracking-and-observability) Unmanaged agents are tracked on Warp’s backend. Each run creates a persistent session that your team can: * **View** in the [Oz dashboard](https://oz.warp.dev). * **Attach to** via [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) to monitor or steer. * **Query** through the [Oz API/SDK](/reference/api-and-sdk/) for custom dashboards or monitoring. Unmanaged sessions benefit from the same shared configuration as other cloud agent runs — [MCP servers](/agent-platform/cloud-agents/mcp/), [secrets](/agent-platform/cloud-agents/secrets/), Warp Drive context, and saved prompts all apply. *** ## Related pages [Section titled “Related pages”](#related-pages) * [Self-hosting overview](/agent-platform/cloud-agents/self-hosting/) — Compare managed and unmanaged, plus the architecture decision guide. * [GitHub Actions integration](/agent-platform/cloud-agents/integrations/github-actions/) — Run agents in CI with the official action. * [Deployment patterns](/agent-platform/cloud-agents/deployment-patterns/) — Pattern 1 (CLI-only) explains the unmanaged model conceptually. * [Oz CLI](/reference/cli/) — Full CLI reference for `oz agent run` and related commands. * [Agent Session Sharing](/agent-platform/local-agents/session-sharing/) — Attach to running sessions to monitor or steer them. # Skills as Agents > Run agents based on skills for consistent, repeatable workflows. Use skills with local or cloud agents from the CLI, Oz web app, API, or on a schedule. You can start an agent from a [skill](/agent-platform/capabilities/skills/)—a reusable set of instructions that defines what the agent should do. When you run an agent based on a skill, the skill provides the base prompt and behavior, while you supply additional context for that specific run. Skills work with both **local agents** (running on your machine) and **cloud agents** (running in Warp’s infrastructure). This is useful when you want: * **Consistent behavior** — The same skill produces the same workflow every time, regardless of who triggers it or where it runs. * **Repeatable automation** — Run skills on schedules for maintenance tasks like code cleanup, dependency updates, or issue triage. * **Shareable workflows** — Skills live in repositories, so your team can version, review, and collaborate on agent behavior. *** ## How Skills become available [Section titled “How Skills become available”](#how-skills-become-available) Skill discovery depends on whether you’re running a local or cloud agent. ### Local agents [Section titled “Local agents”](#local-agents) For local agent runs (`oz agent run`), skills are automatically discovered from your current repository. Warp scans these directories in order of precedence: * **`.warp/skills/`** * **`.agents/skills/`** * **`.claude/skills/`** * **`.codex/skills/`** * **`.cursor/skills/`** * **`.gemini/skills/`** * **`.copilot/skills/`** * **`.factory/skills/`** * **`.github/skills/`** * **`.opencode/skills/`** You can also specify a skill from any accessible repository using the fully qualified format: `owner/repo:skill-name`. ### Cloud agents [Section titled “Cloud agents”](#cloud-agents) For cloud agent runs (`oz agent run-cloud`), skills are discovered from repositories configured in your [environments](/agent-platform/cloud-agents/environments/). **Discovery workflow:** 1. **Create a skill** in your repository (see [Creating skills](/agent-platform/capabilities/skills/#creating-skills)) 2. **Add the repository** to an environment 3. **The skill appears** in the Agents list in the Oz web app Note You can also list available skills programmatically using the `GET /agent` endpoint. See the [Oz API](/reference/api-and-sdk/) reference for details. *** ## Running skill-based agents [Section titled “Running skill-based agents”](#running-skill-based-agents) You can start an agent from a skill using multiple entry points. ### Oz web app [Section titled “Oz web app”](#oz-web-app) The [Oz web app](/agent-platform/cloud-agents/oz-web-app/) at [oz.warp.dev](https://oz.warp.dev) provides a visual interface for running skill-based agents. From the web app, you can: * Browse all skills available from your environments on the **Agents** page * View suggested agents from Warp’s public [oz-skills repository](https://github.com/warpdotdev/oz-skills) * Start a new run by selecting a skill, environment, and prompt * Create scheduled agents that run skills on a cron schedule For a complete walkthrough of the web app interface, see [Oz Web App](/agent-platform/cloud-agents/oz-web-app/). ### CLI [Section titled “CLI”](#cli) Use the `--skill` flag with the Oz CLI: ```sh # Run locally with a skill oz agent run --skill "owner/repo:skill-name" --prompt "additional context" # Run in the cloud with a skill oz agent run-cloud \ --environment \ --skill "owner/repo:skill-name" \ --prompt "additional context" ``` For full CLI documentation, see [Using skills](/reference/cli/#using-skills) in the CLI reference. ### API & SDK [Section titled “API & SDK”](#api--sdk) Use the `skill_spec` parameter when creating a run: ```json { "prompt": "additional context for this run", "config": { "environment_id": "", "skill_spec": "owner/repo:skill-name" } } ``` For full API documentation, see [Agent configuration](/reference/api-and-sdk/#agent-configuration) in the API reference. *** ## Running skills on a schedule [Section titled “Running skills on a schedule”](#running-skills-on-a-schedule) One of the most powerful uses for skill-based agents is running them on a schedule. [Scheduled agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) execute automatically at specified times, making them ideal for: * **Dead code cleanup** — Weekly scans for unused code or stale feature flags * **Dependency updates** — Daily or weekly checks for security updates * **Issue triage** — Regular categorization and prioritization of open issues * **Documentation refresh** — Periodic updates to keep docs in sync with code **Creating a scheduled skill-based agent:** ```sh oz schedule create \ --name "Weekly Code Cleanup" \ --cron "0 10 * * 1" \ --environment \ --prompt "Scan for dead code and unused feature flags. Open a PR with removals." ``` You can also create schedules from the [Oz web app](/agent-platform/cloud-agents/oz-web-app/) using the **New schedule** action. For full scheduling documentation, see [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/). *** ## Suggested Skills [Section titled “Suggested Skills”](#suggested-skills) The [Oz web app](/agent-platform/cloud-agents/oz-web-app/) displays suggested agents from the public [warpdotdev/oz-skills](https://github.com/warpdotdev/oz-skills) repository. These are pre-built skills that demonstrate common use cases and can be used as starting points for your own workflows. Suggested skills appear on the Agents page under the **Suggested** filter. *** ## Related resources [Section titled “Related resources”](#related-resources) * [Skills](/agent-platform/capabilities/skills/) — How to create skills and skill file format * [Environments](/agent-platform/cloud-agents/environments/) — Configure repositories and runtime context for cloud agents * [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) — Run agents automatically on a cron schedule * [Oz Web App](/agent-platform/cloud-agents/oz-web-app/) — Visual interface for managing cloud agents * [Oz CLI](/reference/cli/) — Command-line interface for running agents * [Oz API & SDK](/reference/api-and-sdk/) — Programmatic access to cloud agents # Access, billing, and identity permissions > Understand how access to cloud agents works for individuals and teams, how billing and credits apply, and how Warp maps user identities across integrations. This page explains how access to cloud agents works for both individual users and teams, how billing and credits apply, and how Warp maps user identities across integrations. *** ## Overview: individual vs team access [Section titled “Overview: individual vs team access”](#overview-individual-vs-team-access) Cloud agents can be used in two ways: **Individual users** (without a team): * Can run cloud agents via CLI or API * Can use normal Warp credits, [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits), or a Build plan with available credits * Agents run on Warp-hosted infrastructure * Cannot use integrations (Slack, Linear) or self-hosted agents **Teams** (users who are part of a [Warp team](/knowledge-and-collaboration/teams/)): * All individual capabilities, plus: * Can use integrations (Slack, Linear) to trigger agents * Can self-host agents on their own infrastructure (Enterprise only) * Share team-level configuration (environments, secrets, integrations) * Team must be on Build, Max, or Business plan with at least 20 credits (any type) for cloud agents and integrations *** ## Individual access [Section titled “Individual access”](#individual-access) Individual users can run cloud agents via the CLI or API without being part of a team. **How it works:** * Run agents using `oz agent run-cloud` or the Oz API * Credits are drawn from your normal Warp credits, Cloud Agent Credits (if available), or Build plan credits * Agents execute on Warp-hosted infrastructure **What you can do:** * Run cloud agents from CI/CD pipelines * Trigger agents programmatically via API * Use personal secrets for authentication **What requires a team:** * Integrations (Slack, Linear) * Self-hosted agent execution * Team secrets and shared configuration *** ## Team access [Section titled “Team access”](#team-access) A [Warp team](/knowledge-and-collaboration/teams/) is a group of users who share configuration and collaborate on cloud agents. Teams can be created on any plan, including Free. **What teams enable:** * **Integrations** - Create Slack and Linear integrations that all team members can use * **Shared configuration** - Team-level environments, secrets, and settings * **Self-hosting** - Run agents on your own infrastructure (Enterprise only) * **Team visibility** - Shared observability into agent runs and history Integrations are created at the team level, not per-user. Once a Slack or Linear integration is installed, everyone on your Warp team can use **@Oz** in the connected workspace. The integration behaves the same way for all teammates, and everyone shares the same underlying environment configuration. When someone triggers a cloud agent for the first time, Warp may prompt them to grant GitHub authorization so the agent can open pull requests or push branches under their identity. This allows each run to use the correct permissions without requiring additional setup from an admin. #### Requirements for integrations [Section titled “Requirements for integrations”](#requirements-for-integrations) Integrations and [cloud agents](/agent-platform/cloud-agents/overview/) run inside Warp’s cloud, which means usage is billed based on [credits](/support-and-community/plans-and-billing/credits/). Your team must meet the following requirements to run integrations: * You must be on a plan that supports **[Reload Credits (Add-on Credits)](/support-and-community/plans-and-billing/add-on-credits/)**. * Supported: **Build, Max, Business** * Not supported: Pro, Turbo, Lightspeed, legacy Business. * Your team needs at least **20 credits** available to run cloud agents and integrations (any type of Warp credits work) When a user triggers an agent through an integration (like Slack or Linear), the run draws from credits in a specific order. It starts with any [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits) the user has, then moves to the user’s base credits, followed by the team’s Reload Credits, and finally the user’s own Reload Credits. Enterprises may have different payment options and credit plans that affect this flow. If all applicable credit sources are exhausted, integrations and cloud agents will not work until credits are added. Note If you’re on an Enterprise plan, please reach out to [warp.dev/contact-sales](https://warp.dev/contact-sales) with any billing questions related to integrations. ### Identity mapping [Section titled “Identity mapping”](#identity-mapping) Warp needs a reliable way to know which person a cloud agent run is acting for, across Warp, Slack, Linear, and GitHub. * Slack uses a dedicated account-linking flow to map a Slack user to their Warp account. This is the recommended path for Slack-triggered agents, since it doesn’t rely on email matching. * Linear currently maps identities using email address matching. Your Linear email must match your Warp account email for Warp to correctly attribute and scope agent runs. * Each teammate must authorize GitHub before an agent can write PRs or push branches on their behalf * Agents always operate using the GitHub permissions of the triggering user This ensures runs are scoped to what the user is allowed to see and modify, and that ownership of PRs remains clear across teams and repositories. *** ## Team GitHub authorization [Section titled “Team GitHub authorization”](#team-github-authorization) By default, Oz cloud agents authenticate with GitHub using the personal token of the user who triggered the run. Team GitHub authorization gives you an alternative: authenticate with the **Oz by Warp** GitHub App instead, so agents can clone repositories and open pull requests without relying on any individual’s token. This is useful for fully automated workflows that use a [team API key](/reference/cli/api-keys/), like CI/CD pipelines, scheduled agents, and SDK-triggered runs, where you want code changes attributed to the GitHub App rather than a specific person. ### How it works [Section titled “How it works”](#how-it-works) When an Oz agent task is initiated with a team API key, there is no individual user to authenticate on behalf of. Instead, Warp uses tokens issued by the **Oz by Warp** GitHub App installation to authenticate directly with GitHub. The GitHub App token gives the agent access to the repositories included in the app installation — it can clone repos, create branches, push commits, and open pull requests. During installation, you choose whether the app can access **all repositories** or only **selected repositories** in your GitHub organization, and this controls what team API key runs can access. ### Setting up team GitHub authorization [Section titled “Setting up team GitHub authorization”](#setting-up-team-github-authorization) 1. **Install the Oz by Warp GitHub App.** A user with admin permissions on the GitHub organization installs the [Oz by Warp](https://github.com/apps/oz-by-warp) GitHub App. During installation, grant the app access to **all repositories** or **selected repositories** in your org. Note There are two places you may encounter this installation flow: * During the first-time experience for Oz, when you connect your GitHub account. * When you click **Configure access on GitHub** in the repository selector while creating an environment. Each installation is scoped to a single GitHub organization or personal account — you can install the app to multiple orgs separately. ::: ![Oz by Warp GitHub App installation page showing repository access options](/_astro/oz-github-app-installation.CN42DA3d_nqzq2.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Installing the Oz by Warp GitHub App. 2. **Enable the GitHub org for your Warp team.** A Warp team admin opens the Admin Panel in the Warp app (**Settings** > **Admin Panel** > **Platform**) and adds the GitHub organization under **Enabled GitHub Orgs**. This associates the GitHub App installation with your Warp team. ![Enabled GitHub Orgs setting in the Admin Panel Platform section](/_astro/admin-panel-enabled-github-orgs.DgeT9Y28_ZqBhXs.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Enabled GitHub Orgs setting in the Admin Panel. 3. **Use a team API key.** Tasks initiated with a team API key now use tokens from the GitHub App installation to clone repos and push changes. No individual GitHub authorization is needed. ### How this relates to environments [Section titled “How this relates to environments”](#how-this-relates-to-environments) An [environment](/agent-platform/cloud-agents/environments/) is a template for an Oz cloud agent’s sandbox — it defines the Docker image, repos, and setup commands, but it does not carry its own GitHub permissions. The same environment can be used by different users or by team API key runs, and each will authenticate to GitHub independently. The environment configuration and the **Enabled GitHub Orgs** setting in the Admin Panel serve different purposes: * **Environment repo list** - “This agent needs repos A, B, and C.” * **Enabled GitHub Orgs** - “This team can use the Oz by Warp GitHub App to access repos in this GitHub organization.” ### Personal tokens vs. GitHub App tokens [Section titled “Personal tokens vs. GitHub App tokens”](#personal-tokens-vs-github-app-tokens) Team GitHub authorization is complementary to the existing personal token flow: * **User-triggered runs** (personal API key, Slack, Linear, Warp app) - The agent authenticates as Oz acting on the triggering user’s behalf. PRs and commits are attributed to that user. * **Team API key runs with GitHub App authorization** - The agent authenticates as the GitHub App installation. PRs and commits are not attributed to any individual user. Both flows can coexist on the same team. Personal tokens are still used for user-triggered runs, and the GitHub App installation token is used when a task is initiated with a team API key. Caution GitHub App installation tokens are scoped to a single GitHub organization at a time. If your team works across repos in multiple GitHub organizations, the agent can only use the installation token for the organization enabled in the Admin Panel. Repos in other organizations require user-triggered runs with a personal API key. Note To change which repositories the GitHub App can access, edit the app installation in your [GitHub settings](https://github.com/settings/installations). *** ## Data and permissions [Section titled “Data and permissions”](#data-and-permissions) #### Slack / Linear [Section titled “Slack / Linear”](#slack--linear) Installing the Oz app gives Warp access to the Slack channels or Linear teams where the app is installed. **When a run is triggered, Warp receives:** * The content of the tagged thread or issue * Relevant surrounding context used to build the agent prompt Warp stores only the content required for the agent to complete its task. You can message @Oz directly, mention it in channels, or tag it on specific issues depending on the integration. #### GitHub [Section titled “GitHub”](#github) Warp’s behavior in GitHub is defined by two layers of control: 1. **The Warp GitHub App installation scope** * Determines which organizations and repositories Warp can read and write to * Can be edited at any time in GitHub settings 2. **Permissions of the triggering user** * Agents inherit the user’s read/write privileges * Agents cannot elevate permissions, see additional repos, or write to repos the user cannot access **In practice, agents can only operate on repositories that:** * Are included in the environment configuration * Are accessible to both the GitHub app and the triggering user *** ## Additional notes: how cloud agents use credits [Section titled “Additional notes: how cloud agents use credits”](#additional-notes-how-cloud-agents-use-credits) Cloud agents can run automatically in the background when activated by a trigger such as a Slack mention, a Linear update, or a scheduled task. These runs require compute and model usage, which translates to credit consumption. **Typical credit usage:** Cloud agent runs consume credits based on the complexity of the task and whether an environment is used. The exact amount varies by run. #### How credit usage works [Section titled “How credit usage works”](#how-credit-usage-works) How credits are consumed depends on how the agent run is triggered and authenticated: **User-triggered runs** (CLI with personal API key, Slack, Linear, or the Warp app): * Runs are tied to the triggering user’s identity * Credits are consumed starting with any credit grants specifically allocated for cloud agent usage, then the user’s base credits, followed by the team’s Reload Credits, and finally the user’s own Reload Credits **Team API key runs** (fully automated or headless workflows): * Runs are not tied to any individual user * Only the team’s Reload Credit pool is used—no individual base credits are available * Ideal for CI/CD pipelines, scheduled tasks, and other automated workflows * For workflows that require code changes (opening pull requests, pushing branches, or writing to a repository), configure [team GitHub authorization](#team-github-authorization) so the agent can authenticate with the Oz by Warp GitHub App. Alternatively, use a [personal API key](/reference/cli/api-keys/) to authenticate as an individual user. For more details on creating and using API keys, see [API Keys](/reference/cli/api-keys/). Note When a user triggers an agent via Slack or Linear, the run follows the standard credit precedence, starting with any credit grants specifically allocated for cloud agent usage. This applies even for integrations—as long as the triggering user’s identity can be mapped to their Warp account. #### Who configures triggers and workflows [Section titled “Who configures triggers and workflows”](#who-configures-triggers-and-workflows) All triggers and instructions used by cloud agents are defined and controlled by your team’s authorized users. * Admins or other authorized users decide which triggers exist, when they fire, and what the agent should do in response. * Trigger behavior and the agent’s instructions (system prompts, workflow steps, repo access, etc.) are fully managed by your admins or other designated users. #### Staying aware of usage [Section titled “Staying aware of usage”](#staying-aware-of-usage) Because triggers and instructions are configured by your team, any credits used when an agent runs are billed to your team’s Reload Credit balance. * It’s the team’s responsibility to manage triggers, confirm they behave as intended, and monitor usage. * Reviewing triggers, prompts, and agent behavior periodically helps ensure that credit usage aligns with expectations. # Triggers overview > Configure triggers to run cloud agents automatically based on schedules or events. Triggers allow you to run cloud agents automatically without manual intervention. You can set up agents to run on schedules, in response to webhooks, or through other automation patterns. To set up your first recurring agent, follow the [Scheduled Agents Quickstart](/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart/). ## Available trigger types [Section titled “Available trigger types”](#available-trigger-types) * **[Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/)** - Run agents on a recurring schedule using cron expressions. * **[CLI](/reference/cli/)** - Trigger cloud agents directly from your terminal using the Oz CLI. * **[API & SDK](/reference/api-and-sdk/)** - Programmatically trigger agents via the Warp API or SDK. * **[Integrations](/agent-platform/cloud-agents/integrations/)** - Trigger agents from external services like Slack, Linear, or GitHub Actions. # Scheduled Agents > Run cloud agents on a cron schedule for automated maintenance and recurring tasks. Warp’s Scheduled Agents let you run cloud agents automatically on a **recurring schedule**. They are designed for routine, repeatable tasks that should happen without manual intervention, such as dead code cleanup, dependency maintenance, issue triage, or periodic refactors. ![YouTube video](https://i.ytimg.com/vi/wX9cDbsRXHs/sddefault.jpg) Scheduled Agents run in the background on Warp’s infrastructure. Each run starts from a clean session, executes a fixed prompt, and produces its own task and session history that can be inspected after the fact. *** ### What are Scheduled Agents? [Section titled “What are Scheduled Agents?”](#what-are-scheduled-agents) A Scheduled Agent is a [cloud agent](/agent-platform/cloud-agents/overview/) that runs on a cron-based schedule. **Key characteristics:** * Runs automatically based on a cron expression. * Uses a fixed prompt defined at schedule creation time. * Starts a fresh agent session for every run. * Executes in a specific Warp Environment, if provided. * Consumes credits when it runs. * Can be paused, updated, or deleted at any time. Scheduled Agents are ideal for work that should happen regularly and predictably, without needing a human to trigger the agent manually. ### Common use cases [Section titled “Common use cases”](#common-use-cases) Scheduled Agents are best suited for maintenance-style workflows, including skills that automate recurring tasks. For more on running skill-based agents on schedules, see [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/). Common use cases include: * Dead code or unused feature flag cleanup. * Dependency updates or security scans. * Issue or PR triage on a recurring cadence. * Periodic documentation refreshes. * Repository hygiene tasks like formatting or lint checks. * Scheduled reporting or audits. Because each run is isolated, Scheduled Agents are safe to use for tasks that benefit from a clean, repeatable execution environment. *** ### Scheduling agents with the Oz CLI [Section titled “Scheduling agents with the Oz CLI”](#scheduling-agents-with-the-oz-cli) Oz scheduled agents are managed through the Oz `schedule` family of CLI commands. All scheduling operations require the Oz CLI and an authenticated session #### Creating a schedule [Section titled “Creating a schedule”](#creating-a-schedule) Use `oz schedule create` (with required flags) to define a new Scheduled Agent. **Each schedule requires:** * A name, for identification. * A cron schedule. * A prompt or skill that the agent will execute. * An optional environment in which the agent will run. * An optional [model selection](/reference/cli/#using-agent-profiles). * [Optional MCP server configuration](/agent-platform/cloud-agents/mcp/). ```bash oz schedule create \ --name=NAME \ --cron=SCHEDULE \ --prompt=PROMPT \ [--environment=ENVIRONMENT_ID] \ [--skill=SPEC] \ [--host=WORKER_ID] \ [--mcp=SPEC] \ [--model=MODEL_ID] \ [--file=PATH] ``` **Optional flags:** * `--skill ` — use a skill as the base prompt (format: `repo:skill_name` or `org/repo:skill_name`). See [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/). * `--host ` — run on a specific self-hosted worker instead of Warp-hosted infrastructure. * `--mcp ` — attach MCP servers (inline JSON, file path, or UUID). Can be repeated. * `--model ` — override the default model. * `--file ` — load schedule configuration from a YAML or JSON file. Note Environments are optional — if you don’t specify one, the scheduled agent runs in a barebones sandbox. Without an environment, the agent won’t have access to your code repositories, pre-installed tools, or setup commands, so this is only suited for tasks that don’t need your codebase. **Example** The following command schedules an agent to clean up old feature flags every four days: ```bash oz schedule create \ --name "Feature Flag Cleanup" \ --cron "0 10 */4 * *" \ --prompt "Scan the repository for stale feature flags and remove any that are no longer referenced. Open a PR with the changes and include a summary." \ --environment "KB1ndNMQAs5kjPdX2jatA8" ``` Once created, the agent will automatically run at the specified times without further action. Scheduled Agents support the same [model selection](/reference/cli/) and [MCP server configuration](/agent-platform/cloud-agents/mcp/) as other cloud agent triggers. #### Cron schedule format [Section titled “Cron schedule format”](#cron-schedule-format) Warp uses standard cron syntax to define schedules. A cron expression consists of five fields: ```plaintext minute hour day-of-month month day-of-week ``` For example: * `0 10 * * *` runs every day at 10:00 AM. * `0 10 */4 * *` runs every four days at 10:00 AM. * `0 8 1 * *` runs at 8:00 AM on the first day of every month. Make sure your cron expression reflects the cadence you want, as Scheduled Agents will run exactly according to this schedule. ### Listing Scheduled Agents [Section titled “Listing Scheduled Agents”](#listing-scheduled-agents) To view all Scheduled Agents for your team, use: ```bash oz schedule list ``` This command prints a table with details about each schedule, including: * Schedule ID * Name * Cron schedule * Paused * Last run time * Next scheduled run * Scope | ID | Name | Schedule | Paused | Last Ran | Next Run | Scope | | ------ | -------------------- | -------------- | ------ | -------------------------------------------- | --------------------- | ----- | | abc123 | Feature Flag Cleanup | `0 10 */4 * *` | No | `2025-11-24 10:00 AM` | `2025-11-28 10:00 AM` | Team | | def456 | Issue Triage | `0 8 1 * *` | Yes | `2025-11-24 08:00 AM` | Paused | - | Each completed run also includes links to: * The task created by the agent. * The full agent session, including logs and outputs. This makes it easy to audit what ran, when it ran, and what the agent did. #### Viewing a specific Scheduled Agent [Section titled “Viewing a specific Scheduled Agent”](#viewing-a-specific-scheduled-agent) Use `oz schedule get` to view detailed information about a single Scheduled Agent. ```bash oz schedule get SCHEDULE_ID ``` This command returns additional details not shown in the list view, including: * Full schedule configuration * Prompt and model configuration * Environment and MCP settings * Recent runs and execution metadata * Links to related tasks and agent sessions This is useful when auditing behavior, debugging failures, or reviewing how a Scheduled Agent is configured. ### Pausing and unpausing schedules [Section titled “Pausing and unpausing schedules”](#pausing-and-unpausing-schedules) Scheduled Agents can be temporarily disabled without deleting them. ```bash oz schedule pause SCHEDULE_ID ``` When paused, the agent will not run at its scheduled times. **Example** ```bash oz schedule pause abc123 ``` #### Unpausing a schedule [Section titled “Unpausing a schedule”](#unpausing-a-schedule) ```bash oz schedule unpause SCHEDULE_ID ``` Once unpaused, the agent resumes running according to its original cron schedule. ### Editing Scheduled Agents [Section titled “Editing Scheduled Agents”](#editing-scheduled-agents) You can modify an existing schedule using `oz schedule update`. You may update one or more properties at a time, including: * The schedule name. * The cron schedule. * The prompt used for future runs. * The skill used as the base prompt. * The environment used for execution. * The model, MCP, and host configuration used for future runs. #### Command [Section titled “Command”](#command) ```bash oz schedule update SCHEDULE_ID \ [--name=NAME] \ [--cron=SCHEDULE] \ [--prompt=PROMPT] \ [--environment=ENVIRONMENT_ID] \ [--skill=SPEC] \ [--remove-skill] \ [--host=WORKER_ID] \ [--mcp=SPEC] \ [--remove-mcp=SERVER_NAME] \ [--model=MODEL_ID] ``` **Additional update flags:** * `--skill ` — update the skill used as the base prompt. * `--remove-skill` — remove the skill from this scheduled agent. * `--host ` — update the execution host. * `--mcp ` — add MCP servers to this schedule. * `--remove-mcp ` — remove an MCP server by name. * `--remove-environment` — remove the environment from this schedule. #### Examples [Section titled “Examples”](#examples) Change when a scheduled agent runs, leaving everything else unchanged: ```bash oz schedule update abc123 --cron "0 9 */4 * *" ``` Update the environment used for future runs: ```bash oz schedule update abc123 --environment=jkl789 ``` Changes apply only to future runs. Past runs and their session history remain unchanged. ### Deleting a Scheduled Agent [Section titled “Deleting a Scheduled Agent”](#deleting-a-scheduled-agent) To permanently remove a schedule, use: ```bash oz schedule delete SCHEDULE_ID ``` **Example** ```bash oz schedule delete abc123 ``` Deleting a schedule immediately stops all future runs. Previous runs and their session history remain accessible for auditing and review. *** ### Execution model and behavior [Section titled “Execution model and behavior”](#execution-model-and-behavior) Each scheduled run behaves like a standard cloud agent run, with a few important guarantees: * Every run starts a fresh session. * No state is carried over between runs unless your environment explicitly persists data. * Runs execute automatically without human intervention. * All usage is billed to the team’s shared credit balance. If a scheduled run fails, it does not block future runs. Each execution is independent. ### Permissions and responsibility [Section titled “Permissions and responsibility”](#permissions-and-responsibility) Scheduled Agents are created and managed by authorized users on a Warp team. By creating a Scheduled Agent, you are responsible for: * The cron schedule and how often the agent runs. * The instructions provided in the prompt. * The environment and integrations the agent has access to. * The credits consumed by scheduled executions. Carefully review prompts and schedules before deploying them broadly, especially for agents that can modify production code or infrastructure. ### When to use Scheduled Agents vs triggers [Section titled “When to use Scheduled Agents vs triggers”](#when-to-use-scheduled-agents-vs-triggers) Scheduled Agents are best when work should happen on a predictable cadence. If you want an agent to run in response to an event, such as a Slack mention, PR update, or issue change, use triggered cloud agents instead. Many teams use both together: triggers for reactive workflows, and Scheduled Agents for proactive maintenance. # Scheduled Agents quickstart > Schedule an Oz cloud agent to run recurring tasks automatically — issue triage, dependency checks, code cleanup, and more. Scheduled agents are Oz cloud agents that run on a recurring cron schedule, handling recurring tasks automatically without manual triggers. This guide walks you through setting up an agent that triages your GitHub bug reports every week, checks whether each issue has enough detail to investigate, and posts follow-up comments when information is missing. You’ll use a prebundled skill and the Oz web app; no CLI or custom code required. Watch this short demo of creating and testing a scheduled agent: ![YouTube video](https://i.ytimg.com/vi/M-zyyrGt2ug/sddefault.jpg) *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **A Warp account on an eligible plan** - Build, Max, or Business, with credits available. See [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/). * **An Oz cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don’t have one, follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/) to create one first. *** ## 1. Set up a scheduled agent [Section titled “1. Set up a scheduled agent”](#1-set-up-a-scheduled-agent) 1. From the [Schedules page](https://oz.warp.dev/schedules) in the Oz web app, click **New schedule**. 2. Enter a name, e.g. `Weekly bug report triage`. 3. Under **Agent**, select **github-bug-report-triage** from the suggested skills. 4. Choose your environment. 5. Under **Frequency**, choose a preset or enter a custom cron expression (e.g., `0 9 * * 1` for every Monday at 9 AM). 6. Click **Create schedule**. **Breaking it down:** The schedule lives in Oz’s cloud infrastructure. Unlike a local cron job, it fires even when your machine is off. Each run starts a fresh, isolated session with no state carried over from previous executions, and every run is tracked and auditable in the [Oz web app](/agent-platform/cloud-agents/oz-web-app/). *** ## 2. Watch your first run [Section titled “2. Watch your first run”](#2-watch-your-first-run) To verify your setup without waiting for the schedule to fire, trigger a test run now: 1. From the [Schedules page](https://oz.warp.dev/schedules) in the Oz web app, click the schedule you just created. 2. Click ⋮ and select **Run now**, then click **Run** to confirm. Your test run will appear under **All** on the [Runs page](https://oz.warp.dev/runs). Once the schedule fires on its cron, those runs will appear under **Recurring**. Runs are also accessible from the conversation panel view in the Warp app and on mobile via the Oz web app. Note **Prefer the CLI?** See [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) for `oz schedule create`, `oz schedule list`, and full schedule management commands. To use a custom skill instead of a prebundled one, see [Skills as Agents](/agent-platform/cloud-agents/skills-as-agents/). *** ## Next steps [Section titled “Next steps”](#next-steps) * **Trigger agents from your tools** - Connect Oz to Slack or Linear to trigger agents from mentions or issue updates. See [Integrations Quickstart](/agent-platform/cloud-agents/integrations/quickstart/). * **Manage and refine your schedule** - Change the frequency, swap skills, or pause and resume the schedule. See [Scheduled Agents](/agent-platform/cloud-agents/triggers/scheduled-agents/) for the full reference. * **Share with your team** - Schedules and environments are shared across your Warp team, so everyone benefits automatically. # Cloud agent session sharing > Open, inspect, and steer remote cloud agent runs in real time from Warp or the web. Cloud agent session sharing lets you open, inspect, and continue interacting with agent tasks that are running on remote virtual machines. Whether a cloud agent was triggered from [integrations](/agent-platform/cloud-agents/integrations/) like Slack, Linear, GitHub Actions, or the [Oz CLI](/reference/cli/), you can view its full session, follow along in real time, ask follow-up questions, and even “fork” the work into your local Warp environment. This makes cloud agent runs observable, steerable, and collaborative — even if they weren’t initiated from your machine. *** ### What it enables [Section titled “What it enables”](#what-it-enables) With cloud agent session sharing, you can view the full remote session for a cloud agent run and: * See every command the agent executed in the virtual environment * Inspect context, logs, and outputs directly in Warp or the web viewer * Ask follow-up questions or give additional instructions after the task completes * Bring the conversation into your local Warp session with Fork to local * Continue working on remote-generated code locally * Share links so teammates can view or collaborate on the session Everything is accessible whether or not Warp is installed on the viewer’s machine. ## How it works [Section titled “How it works”](#how-it-works) #### 1. Open a remote cloud agent run [Section titled “1. Open a remote cloud agent run”](#1-open-a-remote-cloud-agent-run) When a cloud agent starts working — for example, from a Slack mention, a Linear issue, or a [CLI](/reference/cli/) trigger — Warp attaches a shareable link to the run. * From [Slack](/agent-platform/cloud-agents/integrations/slack/), click **View Agent** in the agent response to open the session. * From [Linear](/agent-platform/cloud-agents/integrations/linear/), click the ↗ **Warp** button (“Open in Warp”) on the ticket to open the session. You can also open the session directly in your browser without installing Warp. Here, you’ll see the complete agent session running on a cloud VM, including all steps, logs, and context. #### 2. Inspect the session like it’s your own [Section titled “2. Inspect the session like it’s your own”](#2-inspect-the-session-like-its-your-own) Once the session loads, you can: * Scroll through the cloud agent’s actions * See the prompt, plan, and decisions it made * Review the code or config changes it produced * Understand what environment it executed in You’re viewing a remote VM, but the UI behaves like a local Warp session. #### 3. Keep chatting with the remote agent [Section titled “3. Keep chatting with the remote agent”](#3-keep-chatting-with-the-remote-agent) Even if the cloud agent has completed its task, you can still ask follow-up questions or request more work. Warp sends your message back to the remote VM and continues the conversation. Examples: * “Can you explain which flag you changed?” * “Give me a summary of what you modified.” * “Show me the reasoning behind your last step.” This works as long as the remote environment is still active. #### 4. Handle inactive or shut-down sessions [Section titled “4. Handle inactive or shut-down sessions”](#4-handle-inactive-or-shut-down-sessions) Cloud agent environments automatically shut down after a period of inactivity. When that happens, you’ll see a notice that the virtual machine has been stopped. If you still want to continue the conversation or work on the code, you can click **Fork to local**. #### 5. Fork the session to your local Warp [Section titled “5. Fork the session to your local Warp”](#5-fork-the-session-to-your-local-warp) Forking brings the cloud agent conversation into your local machine, so you can pick up where the agent left off. Once forked: * The session appears as a normal conversation in your local Warp * You can keep prompting the agent using all your local tools * You can continue inspecting or modifying the generated code * The agent responds using your local environment instead of the remote VM **Note:** If the cloud agent created a new git branch or repository in the remote VM, you’ll need to clone that branch locally first so the agent can keep working on the same code. Warp will streamline this workflow in a future release. ### Viewing sessions across devices [Section titled “Viewing sessions across devices”](#viewing-sessions-across-devices) Cloud agent sessions can be viewed from: * The Warp desktop app * A browser via the web viewer * Remote teammates using the shared link * Local Warp sessions after forking You get consistent visibility into the work regardless of where you open it. # Agents in Warp > Warp's Oz agents are capable collaborators that help you write code, debug issues, and complete terminal workflows, all from natural language prompts. ![Agent Mode Overview](https://i.ytimg.com/vi/qiQtD1jPF6s/sddefault.jpg) Warp includes Oz agents. These coding agents are designed to help you build, test, deploy, and debug while keeping you in control. Describe what you want to do in natural language (*you can even use your voice*), and Oz will take action using your environment, codebase, and saved context. ## What Oz agents can do [Section titled “What Oz agents can do”](#what-oz-agents-can-do) Oz agents understand your codebase and can execute tasks autonomously while keeping you in control: * **Write and edit code** - Create new files, refactor existing code, or make changes across multiple files in your codebase * **Debug and fix errors** - Analyze stack traces, interpret error output, and apply fixes * **Run commands** - Execute shell commands and use the output to guide next steps * **Recover from errors** - Automatically retry failed operations with adjustments * **Learn tools** - Integrate with any CLI tool by reading its `--help` or public documentation * **Use your context** - Leverage [Warp Drive](/knowledge-and-collaboration/warp-drive/), [MCP servers](/agent-platform/capabilities/mcp/), [Rules](/agent-platform/capabilities/rules/), and [codebase indexing](/agent-platform/capabilities/codebase-context/) for tailored responses **Try this prompt** — [*open in Warp*](https://app.warp.dev/drive/prompt/Clone-and-install-Warps-themes-repository-PkK9Zw16SCD3JKzOUoGuj4) ```text Detect my current operating system. Based on that, navigate to the appropriate Warp themes directory (e.g. ~/.warp/ on macOS). Then, clone the official Warp themes repository using SSH (git@github.com:warpdotdev/themes.git) into that directory, following the structure and instructions provided in the repo's README. If SSH does not work, try HTTPS (https://github.com/warpdotdev/themes.git) or via the GitHub CLI (gh repo clone warpdotdev/themes). ``` *** ## Agent autonomy [Section titled “Agent autonomy”](#agent-autonomy) Under **Settings** > **Agents** > **Profiles** > **Permissions**, you can control how much autonomy the agent has when performing different types of actions: * Reading files * Creating plans * Executing commands * Calling MCP servers For each action, set the autonomy level to: * **Let the agent decide** - The agent chooses when to ask for confirmation * **Always prompt for confirmation** - Require approval before each action * **Always allow** - Execute without prompting * **Never** - Disable this action entirely You can also configure an **allowlist** and **denylist** for specific commands you always want to run—either with or without confirmation. *** ## Agent profiles [Section titled “Agent profiles”](#agent-profiles) Profiles let you define different permission and model configurations for different contexts. Create and manage profiles in **Settings** > **Agents** > **Warp Agent**, then switch between them by clicking the profile icon in Warp’s input area. Common profile patterns: * **Default** - Balanced permissions for everyday use * **YOLO mode** - Loose permissions for personal projects where you want the agent to move fast * **Prod mode** - Restrictive permissions (“Always Ask”) for high-risk environments like production servers For more details, see [Agent Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/). *** ## Managing agents [Section titled “Managing agents”](#managing-agents) You can run multiple Oz agents simultaneously in Warp. All active agents—both local conversations and cloud agent runs—are tracked in the [management view](/agent-platform/cloud-agents/managing-cloud-agents/). Agents notify you when they need input, such as permission to run a command or approval to apply a code diff. This lets you focus on other work, knowing you’ll be alerted when your attention is required. To access conversations across devices, share them with teammates, or restore past conversations, enable [cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/). *** ## Context and knowledge [Section titled “Context and knowledge”](#context-and-knowledge) Oz agents work best when they understand your codebase and workflows. Warp provides several ways to give agents the context they need: * [**Codebase Context**](/agent-platform/capabilities/codebase-context/) - Warp indexes your Git-tracked files so agents can search and understand your code * [**Rules**](/agent-platform/capabilities/rules/) - Define global and project-level guidelines that shape agent behavior * [**Skills**](/agent-platform/capabilities/skills/) - Reusable instructions that teach agents how to perform specific tasks * [**MCP Servers**](/agent-platform/capabilities/mcp/) - Connect external tools and data sources (GitHub, Linear, databases) to your agents * [**Warp Drive**](/knowledge-and-collaboration/warp-drive/) - Save prompts, workflows, and notebooks that agents can reference *** ## Third-Party CLI Agents [Section titled “Third-Party CLI Agents”](#third-party-cli-agents) In addition to Warp’s built-in Oz agent, Warp provides first-class support for third-party CLI coding agents like Claude Code, Codex, and OpenCode. Run any supported agent inside Warp and get rich input, code review, agent notifications, vertical tabs with agent metadata, and more. → [Learn about Third-Party CLI Agents](/agent-platform/cli-agents/overview/) *** ## From local to cloud [Section titled “From local to cloud”](#from-local-to-cloud) The same Oz agent capabilities that power interactive conversations in Warp also run in the cloud. Cloud agents can: * React to events from Slack, Linear, or GitHub * Run on schedules for recurring tasks like dependency updates * Execute in parallel across repos or tasks * Produce tracked, auditable, shareable runs Cloud agents are ideal for work that doesn’t need your immediate attention—PR reviews, issue triage, routine maintenance, and integration-driven workflows. → [Learn about Cloud Agents](/agent-platform/cloud-agents/overview/) *** ## Resources [Section titled “Resources”](#resources) * [**Oz web app**](https://oz.warp.dev) - Create runs, manage schedules, browse skills, and configure integrations * [**Warp Agents overview**](/agent-platform/local-agents/overview/) - Detailed guide to working with agents in Warp * [**Capabilities**](/agent-platform/capabilities/) - All agent capabilities: planning, task lists, model choice, and more * [**Oz CLI**](/reference/cli/) - Run agents from the command line * [**Oz API & SDK**](/reference/api-and-sdk/) - Programmatic access to agent runs # Agent platform FAQs > Frequently asked questions about Warp's AI features, including supported models, privacy practices, credit limits, billing, and usage guidelines. ## General [Section titled “General”](#general) ### What data is sent and/or stored when using Agents in Warp? [Section titled “What data is sent and/or stored when using Agents in Warp?”](#what-data-is-sent-andor-stored-when-using-agents-in-warp) See our [Privacy Page](/support-and-community/privacy-and-security/privacy/) for more information on how we handle data used by Agents in Warp. ### What happened to the old Warp AI chat panel? [Section titled “What happened to the old Warp AI chat panel?”](#what-happened-to-the-old-warp-ai-chat-panel) Agent Mode has replaced the previous AI chat panel. Agent Mode is more powerful in all of the chat panel’s use cases. Not only can Agent Mode run commands for you, it can also gather context without you needing to copy and paste. To start a similar chat panel, click the AI button in the menu bar to open a new AI pane. ### Is my data used for model training? [Section titled “Is my data used for model training?”](#is-my-data-used-for-model-training) Warp reserves the right to use data collected to train models and improve Warp. Warp has Zero Data Retention with all its model providers (e.g. Anthropic, OpenAI, etc.). Please learn more about telemetry in our [Privacy Page](/support-and-community/privacy-and-security/privacy/). ### What model are you using for Agent Mode? [Section titled “What model are you using for Agent Mode?”](#what-model-are-you-using-for-agent-mode) Warp supports a curated list of LLMs from providers like OpenAI, Anthropic, and Gemini. To view the full list of supported models and learn how to switch between them, visit the [Model Choice](/agent-platform/capabilities/model-choice/) page. ### Can I use my own LLM API key? [Section titled “Can I use my own LLM API key?”](#can-i-use-my-own-llm-api-key) Warp supports [Bring Your Own Key (BYOK)](/support-and-community/plans-and-billing/bring-your-own-api-key/) for users on paid plans (starting with Build). You can connect your own Anthropic, OpenAI, or Google API keys to route requests directly through your account. Organizations on the Enterprise plan can additionally enable managed “Bring Your Own LLM” configurations to meet strict security or compliance requirements. ## Billing [Section titled “Billing”](#billing) Every Warp plan includes a set number of credits per user per month. See [pricing](https://www.warp.dev/pricing) to compare plans. Credit limits apply to Agent Mode, Generate (Legacy), and [AI autofill in Workflows](/knowledge-and-collaboration/warp-drive/workflows/#ai-autofill). For questions about what counts as a credit, what counts as a token, and how often credits refresh, see [Credits](/support-and-community/plans-and-billing/credits/) and the [Plans & Pricing](/support-and-community/plans-and-billing/plans-pricing-refunds/) page. ## Common AI error messages [Section titled “Common AI error messages”](#common-ai-error-messages) #### **”Message token limit exceeded” error** [Section titled “”Message token limit exceeded” error”](#message-token-limit-exceeded-error) This error means your input (plus attached context) exceeds the maximum context window of the model you’re using. If you exceed the limit for your selected model, you may receive no output. To fix this, try: * Starting a new conversation * Reducing the number of blocks or lines attached to your query #### ”Monthly request limit exceeded” or “Monthly credit limit exceeded” errors [Section titled “”Monthly request limit exceeded” or “Monthly credit limit exceeded” errors”](#monthly-request-limit-exceeded-or-monthly-credit-limit-exceeded-errors) Once you exceed your monthly credit limit (see [pricing](https://www.warp.dev/pricing) for current limits), premium models will be disabled until your quota resets at the start of your next billing cycle. On paid plans with Add-on Credits, you can continue using AI with usage-based billing. **Request failed with error: QuotaLimit** Once you exceed your AI token limits, all models will be disabled. Note that credits and tokens are calculated separately, and even though the plans may have a set number of credits, they also have a limited number of tokens. **Request failed with error: ErrorStatus (403, “Your account has been blocked from using AI features”)** This message means your account has been blocked from using AI features, typically due to a violation of our [Terms of Service](https://www.warp.dev/terms-of-service) or suspected abuse (e.g. attempting to bypass credit or token limits). To resolve or clarify this, please contact our team at if you believe this was an error. We’ll review your case and respond as soon as possible. Caution Note that any error that does not mention isn’t related to being blocked and should be reported as feedback or a bug. See [Sending Us Feedback](/support-and-community/troubleshooting-and-support/sending-us-feedback/) for more. ## Gathering AI conversation ID [Section titled “Gathering AI conversation ID”](#gathering-ai-conversation-id) In cases where you have issues with the Agent, we may ask for the AI conversation ID to troubleshoot the specific conversation. To gather the conversation ID, see [Gathering AI conversation ID](/support-and-community/troubleshooting-and-support/sending-us-feedback/#gathering-ai-conversation-id) for detailed steps. # Active AI Recommendations > Active AI Recommendations proactively suggest fixes and next actions based on your command line errors, inputs, and outputs. Note Active AI features can be disabled in **Settings** > **Agents** > **Warp Agent** with the Active AI toggle. ### Prompt Suggestions [Section titled “Prompt Suggestions”](#prompt-suggestions) Prompt Suggestions are contextual, AI-powered suggestions that activate Agent Mode. These banners will provide suggestions for what to ask Agent Mode in specific scenarios, similar to how Warp already suggests commands to run. To disable, please visit **Settings** > **Agents** > **Warp Agent** > **Active AI** > **Prompt Suggestions** ![Example of inline banner popping up when relevant contextually.](/_astro/prompt-suggestions-example-1.BoIgBq7k_1HCR1Q.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### Accepting a prompt suggestion [Section titled “Accepting a prompt suggestion”](#accepting-a-prompt-suggestion) If you press `CMD-ENTER` (on macOS), `CTRL-SHIFT-ENTER` (on Linux/Windows), or click on the chip, the suggestion will auto-populate into your input and run against [Agent Mode](/agent-platform/local-agents/interacting-with-agents/) (with the most recent block attached). Note Prompt Suggestions use an LLM to generate prompts based on your terminal session, specifically the most recent block. These AI requests do not contribute towards your AI limits, however, any accepted prompts run in Agent Mode contribute as normal. Visit **Settings** > **Agents** > **Warp Agent** > **Active AI** if you’d like to turn it off. If [Secret Redaction](/support-and-community/privacy-and-security/secret-redaction/) is enabled, any selected regexes are applied to content sent to Active AI features to prevent any sensitive data being leaked. ![Setting for Prompt Suggestions](/_astro/prompt-suggestions-setting-1.CuGmvj1k_17NNVt.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ### Next Command [Section titled “Next Command”](#next-command) Next Command uses AI to suggest the next command to run based on your active terminal session and command history. It uses your active terminal session contents and an LLM to generate commands. To disable, please visit **Settings** > **Agents** > **Warp Agent** > **Active AI** > **Next Command** ![Next Command suggestion appearing inline based on the active terminal session and command history.](/_astro/next-command.CKjdPQMB_t3ELb.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Note Next Command is an LLM-based feature that uses your command history (enriched with git branch, exit code, and directory metadata) as well as recent block input and output to generate the next command suggestions. [Secret Redaction](/support-and-community/privacy-and-security/secret-redaction/) is automatically applied to any content sent to Active AI features to prevent any sensitive data being leaked. #### Accepting Next Command suggestions [Section titled “Accepting Next Command suggestions”](#accepting-next-command-suggestions) Press `→` or `CTRL-F` to accept a Next Command suggestion into your input buffer, then press `ENTER` to execute it. You can change the accept keybinding (for example, to `TAB`) via the inline keybinding picker that appears next to the suggestion. #### Billing [Section titled “Billing”](#billing) Next Commands are unlimited across all of Warp’s plans, including the Free plan. For the latest information on other AI limits and other pricing details, visit [warp.dev/pricing](https://warp.dev/pricing). ### Suggested Code Diffs [Section titled “Suggested Code Diffs”](#suggested-code-diffs) Suggested Code Diffs automatically surface potential fixes for command-line errors encountered within Warp. These are most often compiler errors, but they may also include other situations where Warp can confidently predict a straightforward resolution, such as simple merge conflicts. !["Generating fix" banner shown after a command-line error while Warp prepares a proposed diff.](/_astro/suggested-code-diffs-generating-fix.CX54GxX0_Z1YyCvH.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) When an error occurs, Warp evaluates whether it is appropriate for an LLM to generate a fix. If so, a “Generating fix” banner will appear while Warp prepares a proposed diff. You can stop this process at any time by pressing `CTRL + C` or the stop button. ![Suggested code diff with options to dismiss or accept the proposed fix.](/_astro/suggested-code-diffs.BYBWFOox_Z1Q9a36.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### **Using a suggested code diff** [Section titled “Using a suggested code diff”](#using-a-suggested-code-diff) Once the diff is generated, you can either dismiss it or accept it. Acceptance can be done directly via the buttons in the diff view, or with `CMD + ENTER` on macOS and `CTRL + ENTER` on Windows/Linux. You can also view additional details of the diff by pressing `CMD + E` (macOS) or `CTRL + E` (Windows/Linux), which expands the view to allow further inspection (including refining or editing it). You can also use `↓` to view the entire diff. **Billing** Suggested Code Diffs do not count toward your AI request limits. There are maximum limits to the number of code diffs surfaced per month, which scales based on your plan tier. For the latest details on plan limits and pricing, please visit [warp.dev/pricing](https://warp.dev/pricing). ## Active AI privacy [Section titled “Active AI privacy”](#active-ai-privacy) See our [Privacy Page](/support-and-community/privacy-and-security/privacy/) for more information on how we handle data with Active AI. # Agent context overview > How to attach various forms of multi-modal context directly to Warp's Agent within a prompt. In Warp, you can pass different types of input directly to the Agent to guide its behavior and improve response quality. These inputs are known as **Agent Context**: ad-hoc pieces of information you manually supply during a session. **You can attach context in several ways:** * [Blocks as Context](/agent-platform/local-agents/agent-context/blocks-as-context/) - share output from your terminal to help the Agent understand errors, logs, or previous commands. * [Images as Context](/agent-platform/local-agents/agent-context/images-as-context/) - include screenshots, diagrams, or other visuals to provide additional clarity. * [URLs as Context](/agent-platform/local-agents/agent-context/urls-as-context/) - attach public webpages so the Agent can extract and reference their content. * [Selection as Context](/agent-platform/local-agents/agent-context/selection-as-context/) - attach code snippets from the editor or review panel to enrich your prompts with precise context. * [Using @ to Add Context](/agent-platform/local-agents/agent-context/using-to-add-context/) - reference files, folders, code symbols, or Warp Drive objects directly in your prompts. Commands you run inside an agent conversation are automatically included as context for your next prompt. For details, see [Blocks as Context](/agent-platform/local-agents/agent-context/blocks-as-context/). *** This is distinct from other persistent or automatic sources of context, such as [Rules](/agent-platform/capabilities/rules/), [Warp Drive as Agent Mode Context](/knowledge-and-collaboration/warp-drive/agent-mode-context/), and [Model Context Protocol (MCP)](/agent-platform/capabilities/mcp/), which the Agent also uses when available. # Blocks as Context > Attach blocks from your terminal as context so Warp’s Agent can understand errors, outputs, or previous commands when responding to your queries. ## Attaching blocks as context [Section titled “Attaching blocks as context”](#attaching-blocks-as-context) Warp’s Agent can use blocks from your Agent conversations as context to better understand your queries and generate more relevant responses. You can attach a block directly from the terminal blocklist by clicking the AI sparkles icon on it and selecting “Attach as context.” ![From a block of output, attach the block and ask Agent Mode to remove all untracked files.](/_astro/remove_all_untracked_files.B_XhdGz0_Z1LpzAJ.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Attaching a block as agent context. The most common use case is to ask the AI to fix an error. You can attach the error in a query to Agent Mode and type “fix it.” **If you’re already in Agent Mode, use the following ways to attach or clear context from your query:** * macOS **Attach a previous block** * To attach blocks to a query, you can use `CMD-UP` to attach the previous block as context to the query. While holding `CMD`, you can then use your `UP/DOWN` keys to pick another block to attach. * You may also use your mouse to attach blocks in your session. Hold `CMD` as you click on other blocks to extend your block selection. **Clear a previous block** * To clear blocks from a query, you can use `CMD-DOWN` until the blocks are removed from context. * You may also use your mouse to clear blocks in your session. Hold `CMD` as you click on an attached block to clear it. Note When using “Pin to the top” [Input Position](/terminal/appearance/input-position/), the direction for attaching or detaching is reversed (i.e. `CMD-DOWN` attaches blocks to context, while `CMD-UP` clears blocks from context). * Windows **Attach a previous block** * To attach blocks to a query, you can use `CTRL-UP` to attach the previous block as context to the query. While holding `CTRL`, you can then use your `UP/DOWN` keys to pick another block to attach. * You may also use your mouse to select blocks in your session. Hold `CTRL` as you click on other blocks to extend your block selection. **Clear a previous block** * To clear blocks from a query, you can use `CTRL-DOWN` until the blocks are removed from context. * You may also use your mouse to clear blocks in your session. Hold `CTRL` as you click on an attached block to clear it. Note When using “Pin to the top” [Input Position](/terminal/appearance/input-position/), the direction for attaching or detaching is reversed (i.e. `CTRL-DOWN` attaches blocks to context, while `CTRL-UP` clears blocks from context). * Linux **Attach a previous block** * To attach blocks to a query, you can use `CTRL-UP` to attach the previous block as context to the query. While holding `CTRL`, you can then use your `UP/DOWN` keys to pick another block to attach. * You may also use your mouse to select blocks in your session. Hold `CTRL` as you click on other blocks to extend your block selection. **Clear a previous block** * To clear blocks from a query, you can use `CTRL-DOWN` until the blocks are removed from context. * You may also use your mouse to clear blocks in your session. Hold `CTRL` as you click on an attached block to clear it. Note When using “Pin to the top” [Input Position](/terminal/appearance/input-position/), the direction for attaching or detaching is reversed (i.e. `CTRL-DOWN` attaches blocks to context, while `CTRL-UP` clears blocks from context). *** ## Block visibility across views [Section titled “Block visibility across views”](#block-visibility-across-views) Blocks in Warp belong to either the terminal view or a specific agent conversation: * **Terminal blocks** - Commands you run directly in the terminal. These always appear in your terminal blocklist and can be attached as context to multiple conversations. * **Agent conversation blocks** - Commands executed within an agent conversation (either by you or the agent). These only appear within that specific conversation and don’t clutter your terminal blocklist. This separation keeps your terminal view clean while preserving full context within each conversation. *** ## Automatic context in agent conversations [Section titled “Automatic context in agent conversations”](#automatic-context-in-agent-conversations) When you’re working inside an agent conversation, any shell commands you run are automatically included as context for your next query. This means you can: 1. Run a command to see its output 2. Ask the agent about the results without manually attaching the block For example, in an agent conversation, run `npm test` and then ask “why did these tests fail?”—the test output is already part of the conversation context. You can also manually attach terminal view blocks to add additional context from commands you ran outside the conversation. *** ## Pending and attached context [Section titled “Pending and attached context”](#pending-and-attached-context) When you select blocks in terminal view and start a new conversation, those blocks become **pending context**: * **Pending context** - Blocks are selected but the conversation hasn’t started yet. If you deselect the blocks (`ESC` or `CMD-K` on macOS, `ESC` or `CTRL-K` on Windows/Linux), they’re removed from the agent view. * **Attached context** - Once you submit your first query, the pending blocks become attached to the conversation and remain part of the context. # Images as Context > Attach screenshots, diagrams, or other images to your prompt so Warp’s Agent can use visual context when generating responses. ## **Attaching images as context** [Section titled “Attaching images as context”](#attaching-images-as-context) To provide visual context, you can attach images directly to an agent prompt. This is useful for including screenshots, diagrams, or other visual references alongside your query. You can attach images in the following ways: * Using the **image upload button** found on the toolbelt (either on the bottom left or right), depending on which input mode you’re using: ![Attaching 5 images on the new "Universal" input (bottom left toolbelt)](/_astro/image-as-context-universal.B6ZasAz2_ZxMsrQ.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Attaching images in Universal Input. ![Attaching 4 images on the "Classic" input (bottom right)](/_astro/image-as-context-classic.CpPwZTSm_RRplE.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Attaching images in Classic Input. * Copy and paste images directly (e.g. right-click an image > “Copy image” or copy from a file manager) into Warp. * Drag and drop images, such as from a file manager or screenshot utility. Note Warp accepts the following image formats: `.jpg` , `.jpeg` , `.png` , `.gif` , and .`webp` . You can attach up to **5 images per request**, and up to **20 images across a single conversation**. Each image is sent to the model provider and immediately discarded — nothing is stored on Warp’s servers. Caution **Cloud agent conversations do not currently support image attachments.** Image attachment is only available in local agent conversations. If you need to provide visual context to a cloud agent, describe the image contents in your prompt or reference the image file path within the cloud agent’s [environment](/agent-platform/cloud-agents/environments/). ### Model behavior and image handling [Section titled “Model behavior and image handling”](#model-behavior-and-image-handling) All supported models listed in [Model Choice](/agent-platform/capabilities/model-choice/) can interpret image input. Attaching images will consume additional requests, proportional to the number of images added. To stay within model limits, Warp will intelligently resize images before passing them as context, minimizing token usage and respecting the model’s maximum image dimensions. # Selection as Context > Attach text or diffs directly from Warp’s editor or Code Review panel as context for your Agent prompts. ### Attaching selections from Warp’s native code editor [Section titled “Attaching selections from Warp’s native code editor”](#attaching-selections-from-warps-native-code-editor) When you have Warp’s [native code editor](/code/code-editor/) open beside a regular pane, you can easily attach specific lines of code as context: 1. **Select text** in the editor. A tooltip will appear in the bottom-right corner of the selection. 2. **Add as context** by clicking the tooltip or using the keyboard shortcuts `Cmd + L` (macOS) or `CTRL + SHIFT + L` (Windows or Linux). 3. Warp automatically adds the relative file path and context, in addition to the line numbers of the hunk, as a formatted string into the prompt. This makes it easy to highlight just the lines you want the Agent to analyze or modify. ![Selecting a function and attaching it as context from Warp's native code editor.](/_astro/selection-as-context.C0c0cB7T_25unMY.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Selecting code as agent context. ### Attaching selections from Warp’s Code Review panel [Section titled “Attaching selections from Warp’s Code Review panel”](#attaching-selections-from-warps-code-review-panel) You can also directly attach context from the [Code Review panel](/code/code-review/): 1. Hover over any **diff hunk** to reveal the option to attach it as context. ![On-hover option to attach diff as context into the prompt.](/_astro/Add-diff-as-context.5bPxcKWV_24lOE6.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) 2. Attaching a diff will automatically insert the relevant file path and changed lines into your prompt. This helps the Agent understand exactly what has been modified, making it easier to request explanations, feedback, or follow-up edits. ![Code Review panel with diffs for review.](/_astro/git-diff-full-view.BejZPjt2_Z2aN26r.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ### Attaching code to a third-party agent session [Section titled “Attaching code to a third-party agent session”](#attaching-code-to-a-third-party-agent-session) You can select code, files, or snippets and feed them directly to a running third-party CLI agent session without copy-pasting or switching tools. When a third-party agent (Claude Code, Codex, OpenCode, etc.) is running in a Warp tab, select text in Warp’s code editor or Code Review panel and attach it as context to that agent’s session using `Cmd + L` (macOS) or `CTRL + SHIFT + L` (Windows/Linux). This works the same way as attaching context to Warp’s built-in Agent. For more on third-party agent support, see [Third-Party CLI Agents](/agent-platform/cli-agents/overview/). # URLs as Context > Attach a public URL to your prompt so the agent can reference that page's content. ## Referencing websites via URLs [Section titled “Referencing websites via URLs”](#referencing-websites-via-urls) You can attach a public URL to any prompt to provide page content as context. Warp will scrape the page and surface the extracted text directly to the model. * Only publicly accessible pages are supported. * The full page is added to the model’s context, which may increase credit usage for long documents. * Only the specific URL you provide is processed. The agent won’t explore the site, follow links, or crawl beyond that page. Note **Important**: URL attachments are different from web search. If you need the agent to look something up, gather real-time information, or pull in multiple sources, use [Web Search](/agent-platform/capabilities/web-search/) instead. ![Example of referencing docs via a URL](/_astro/url-as-context.CiiXjKAR_Z14xxA1.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Example of referencing docs via a URL. # Using @ to Add Context > Use @ to reference files, folders, code symbols, and Warp Drive objects as agent context. ## How the @ context menu works [Section titled “How the @ context menu works”](#how-the--context-menu-works) You can attach specific files, folders, code symbols, Warp Drive objects, and blocks from other sessions as context to a prompt using the @ symbol. When you’re inside a **Git repository**, typing @ opens a context menu that allows you to search for and select files or directories to include. Note Attaching context with @ works in **both natural language mode** (when interacting with Agents) and **classic terminal commands** for referencing file paths. **Note**: the search in the @-context menu is always relative to the root of the Git repository, even when you’re working in a subdirectory. This means you can reference *any* file or folder tracked in the repo, regardless of the current working directory. ![Using the @ symbol to search for and attach a file or folder from the project root.](/_astro/at-context.BuTee6-u_Z15cp9V.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) File search using the @ symbol. Additionally, no codebase indexing (via [Codebase Context](/agent-platform/capabilities/codebase-context/)) is required — file search is available immediately in any Git-initialized directory. The search also respects `.gitignore` rules and will exclude ignored files from the results. ![Filtering files using @app to locate files containing “app” in their name or path.](/_astro/at-context-app.CbJUeyAO_Z1rT5T1.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Filtering files with @app. ![Referencing a folder or all files within it by typing @styles.](/_astro/at-context-styles.DbO0wQu3_Z8CkhN.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Referencing a folder with @styles. ### Referencing code symbols [Section titled “Referencing code symbols”](#referencing-code-symbols) The @ menu can also be used to fuzzy-search for code symbols in your codebase. This includes functions, classes, interfaces, etc. If you type something like `@main`, Warp will surface a matching `main()` function and insert it into your prompt as a reference with the line number. By pointing the Agent to a specific symbol, you can give it exactly the context it needs to make a targeted edit or explanation. ### Referencing Warp Drive objects [Section titled “Referencing Warp Drive objects”](#referencing-warp-drive-objects) Warp Drive objects are another way to attach context with **@**. You can reference: * [Workflows](/knowledge-and-collaboration/warp-drive/workflows/) — parameterized commands you can name and save in Warp with descriptions and arguments. * [Notebooks](/knowledge-and-collaboration/warp-drive/notebooks/) — runnable documentation consisting of markdown text and list elements, code blocks, and runnable shell snippets that can be automatically executed in your terminal session. * [Rules](/agent-platform/capabilities/rules/) — reusable guidelines and constraints that inform how Agents respond to your prompts. When you select one of these objects, Warp inserts a reference token into your prompt. The contents of the object are then automatically passed as context to the Agent. ### Referencing blocks from other sessions [Section titled “Referencing blocks from other sessions”](#referencing-blocks-from-other-sessions) You are not limited to the current terminal session. With @, you can also bring in blocks of output from earlier sessions. In the demo below, Ian shows how he previously ran cargo clippy and now wants help fixing the reported errors. Typing `@cargo clippy` surfaces the relevant block, which you can insert into your prompt. Once added, the Agent parses the output and generates fixes or explanations directly. You can also reference live blocks, not just those that have already completed execution. ### Why @ to reference context? [Section titled “Why @ to reference context?”](#why--to-reference-context) Attaching context with @ helps you: * Reference exact outputs instead of copy-pasting entire logs * Attach relevant files or directories without leaving Warp * Reuse existing context and knowledge in Warp Drive This makes Agent interactions more accurate, clearer, and efficient, without additional setup. # Cloud-synced conversations > Sync agent conversations to the cloud to access them across devices, share with teammates, and continue past conversations from anywhere. Warp can sync your [agent conversations](/agent-platform/local-agents/interacting-with-agents/) to the cloud, making them accessible across devices, shareable with teammates, and persistent even after logging out. This enables you to pick up where you left off on any machine, share context with collaborators, and access past [cloud agent](/agent-platform/cloud-agents/overview/) conversations. ## Key capabilities [Section titled “Key capabilities”](#key-capabilities) * **Persistence across devices** - Your conversations remain available when you log out and back in, or switch to a different machine. * **Access to past cloud agent conversations** - View and restore cloud agent conversations after they complete. * **Link sharing with access controls** - Share conversations with specific teammates or your team, with configurable permissions. * **Web viewing** - View shared conversations in a browser without installing Warp. * **Local continuation** - Restore any cloud conversation and continue it locally on your machine. [Cloud-synced conversations](https://www.loom.com/embed/54038cf41219485dad3adb1d811e7e9a) ## Enabling cloud conversations [Section titled “Enabling cloud conversations”](#enabling-cloud-conversations) Cloud conversation sync is controlled by a setting in Warp: 1. Open **Settings** > **Privacy** 2. Enable **Store AI conversations in the cloud** When enabled, your Agent conversations automatically sync to the cloud as you interact with the Agent. When disabled, conversations are stored locally on your machine only. Caution If cloud conversations are disabled, conversation data is lost when you log out and cannot be shared with others. Cloud agent conversations are always stored in the cloud regardless of this setting. ## How it works [Section titled “How it works”](#how-it-works) ### Conversation syncing [Section titled “Conversation syncing”](#conversation-syncing) When cloud conversations are enabled, Warp automatically syncs your conversation data after each Agent interaction. This happens in the background and does not affect your workflow. Cloud conversations store a snapshot of the conversation state at each sync point. If you open the same conversation on two different machines, each continues independently from that snapshot—changes on one machine do not sync to the other in real time. ### Continuing vs. forking [Section titled “Continuing vs. forking”](#continuing-vs-forking) When you restore a cloud conversation: * **Your own conversations** - You can continue the conversation directly, and updates sync back to the cloud. * **Shared conversations from others** - Continuing creates a fork, giving you a new conversation that starts with the shared context but does not modify the original. This behavior mirrors [Conversation Forking](/agent-platform/local-agents/interacting-with-agents/conversation-forking/), where you branch off to explore a different direction without affecting the source conversation. ## Managing cloud-synced conversations [Section titled “Managing cloud-synced conversations”](#managing-cloud-synced-conversations) Cloud-synced conversations appear in all the usual conversation management entrypoints alongside your local conversations. You can browse, search, restore, and delete them just like any other conversation. See [Interacting with Agents](/agent-platform/local-agents/interacting-with-agents/) for detailed information on navigating and managing conversations, including keyboard shortcuts and the Conversation Panel in [Terminal and Agent modes](/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes/). * **Browse** - View all your local and cloud-synced conversations in one place. * **Search** - Find conversations by title or content. * **Restore** - Click a conversation to load it into your current session and continue where you left off. * **Delete** - Remove conversations you no longer need. Deletion is permanent and immediate. *** ## Sharing conversations [Section titled “Sharing conversations”](#sharing-conversations) You can share any cloud conversation with teammates via a link. ### Creating a share link [Section titled “Creating a share link”](#creating-a-share-link) To share a conversation: 1. Open the conversation you want to share 2. Access the share options through the conversation menu 3. Configure access permissions: * **Anyone on your team** (default) - All team members can view * **Specific people** - Enter email addresses to grant access * **Anyone with the link** - No authentication required By default, shared conversations are visible to anyone on your team. ### Viewing shared conversations [Section titled “Viewing shared conversations”](#viewing-shared-conversations) Recipients can view shared conversations in two ways: * **On the web** - Open the link in a browser to view the conversation transcript without installing Warp. * **In Warp** - Click “Open in Warp” to load the conversation in the desktop app, where you can continue it locally. When you continue a shared conversation from someone else, Warp creates a fork so you can build on the shared context without modifying the original. Note Cloud-synced conversations store snapshots of conversation data. For real-time collaboration on a live session, use [Agent Session Sharing](/agent-platform/local-agents/session-sharing/). ## Cloud agent conversations [Section titled “Cloud agent conversations”](#cloud-agent-conversations) [Cloud agents](/agent-platform/cloud-agents/overview/) run in the cloud, and their conversations are automatically stored regardless of your local cloud conversations setting. ### Accessing cloud agent conversations [Section titled “Accessing cloud agent conversations”](#accessing-cloud-agent-conversations) You can access any past cloud agent conversation: * **View transcripts** - Access the full conversation history of any past cloud agent run. * **Restore locally** - Load a cloud agent conversation into your local Warp session to review or continue the work. This is useful when a cloud agent completes a task and you want to review what it did or continue from where it left off. *** ## Privacy and data [Section titled “Privacy and data”](#privacy-and-data) ### Enterprise controls [Section titled “Enterprise controls”](#enterprise-controls) Enterprise administrators can disable cloud conversation storage for their organization through the [Admin Panel](/knowledge-and-collaboration/admin-panel/). When cloud conversation storage is disabled by your organization: * Conversations are stored locally only and not synced to the cloud * You cannot share conversations or access them across devices * Cloud agent conversations are still accessible through the Warp dashboard ### Storage limits [Section titled “Storage limits”](#storage-limits) Cloud conversation storage limits vary by plan. For free users, Warp automatically removes the oldest cloud conversations when you reach your limit to make room for new ones. Your conversations are always preserved locally on your machine—only the cloud-synced copies are removed. For current storage limits by plan, see our [pricing page](https://www.warp.dev/pricing). ### Deleting conversations [Section titled “Deleting conversations”](#deleting-conversations) When you delete a conversation, it is removed permanently and immediately. Make sure you no longer need a conversation before deleting it. *** ## Related features [Section titled “Related features”](#related-features) * [Interacting with Agents](/agent-platform/local-agents/interacting-with-agents/) - Learn about conversation mechanics, follow-ups, and context windows. * [Conversation Forking](/agent-platform/local-agents/interacting-with-agents/conversation-forking/) - Branch conversations to explore different directions. * [Session Sharing](/agent-platform/local-agents/session-sharing/) - Collaborate in real time on a live Agent session. * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) - Run agents in the cloud from triggers, schedules, or integrations. # Agent code diffs and review > How to review, refine, and apply code changes generated by Warp’s Agents with the built-in diff editor in Agent Conversations. ## Reviewing code diffs [Section titled “Reviewing code diffs”](#reviewing-code-diffs) During an Agent Conversation, Warp can generate code diffs that open directly in a built-in diff editor. This lets you review proposed changes line by line, refine them with natural language, or make manual edits before choosing whether to apply them. It’s a fast, transparent way to stay in control of agent-generated code. Caution If the `Apply Code Diffs` permission is set to `Always allow` in [Agent Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/), code diffs are applied automatically without being surfaced for review. If it’s set to `Agent decides` or `Always ask`, you’ll always be prompted to review diffs before they’re applied. Note Code diffs generated by Warp are never stored on our servers. Warp’s coding agent only works on local repositories. The agent can make changes on remote or docker repositories, but falls back to using terminal commands (i.e. `sed`, `grep` ) to make the changes. ![A code diff surfaced in an Agent Conversation.](/_astro/generated_blocklist_diff.DmSQWRjy_GYIGR.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) A code diff surfaced in an Agent Conversation. You can also choose whether Warp automatically opens the [Code Review](/code/code-review/) panel the first time you accept a diff in a conversation. ## **Navigating and applying diffs** [Section titled “Navigating and applying diffs”](#navigating-and-applying-diffs) When an Agent generates a code diff, Warp opens it in a built-in text editor with a visual diff view. Changes are grouped into clear hunks for easy inspection. * Use the `UP` and `DOWN` arrow keys (or mouse clicks) to move between hunks. * For multi-file changes, use `LEFT` and `RIGHT` arrow keys to switch between files. * Once satisfied with the changes, you can apply the diffs using `ENTER` or clicking “**Accept Changes**” to apply the modifications. Caution These modifications will not be applied to the files unless you explicitly accept them. ## **Refining or editing the diffs** [Section titled “Refining or editing the diffs”](#refining-or-editing-the-diffs) If the initial suggestion needs more work: * Press `R` or select the “**Refine**” button to provide follow-up instructions in natural language. The agent will regenerate the diff based on your input. * To manually adjust the code, press `E` or click “**Edit**” to switch into an editable view. * To cancel a pending operation, use `CTRL-C` (on macOS, Windows, or Linux). Similarly, you can exit the editor at any time with `ESC` . Note You can open up code files in Warp in various different ways, refer to: [Opening files in Warp](/code/code-editor/#opening-files-in-warp) ![Editing a code diff directly in Warp's native code editor](/_astro/editting_diff.hPtftNGh_1Xn049.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Editing a code diff in Warp’s code editor. ## Accepting diffs and continuing in Agent Mode [Section titled “Accepting diffs and continuing in Agent Mode”](#accepting-diffs-and-continuing-in-agent-mode) When the Agent generates a code diff outside of an active conversation — for example, from a suggested code banner or a passive recommendation — you can accept the diff and seamlessly continue in Agent Mode. After accepting, Warp opens (or returns to) the Agent conversation with the applied changes as context, so you can immediately ask follow-up questions or request further modifications without starting a new conversation. ### Demo: Editing Agent Code in Warp [Section titled “Demo: Editing Agent Code in Warp”](#demo-editing-agent-code-in-warp) Here’s an example from [Warp Guides](/guides/), where Zach demonstrates how to review and edit Agent code diffs natively in Warp: ![YouTube video](https://i.ytimg.com/vi/dm-P63USsVg/sddefault.jpg) # Generate (Legacy) > Use natural language to look up commands or input, accessible either directly from the command-line input or inside any interactive command or program. ## What is Generate? [Section titled “What is Generate?”](#what-is-generate) Generate helps turn natural language queries into precise commands as terminal input or contextual suggestions inside interactive commands and programs, whether you’re using psql, gdb, git, mysql, or any other CLI tool. Generate is backed by Large Language Models from API providers like OpenAI and Anthropic, and are completely opt-in. Note Currently, you need to be online to use this feature. If this feature doesn’t work, your ISP or firewall may be blocking the calls to `app.warp.dev` ## Ways to Generate with AI [Section titled “Ways to Generate with AI”](#ways-to-generate-with-ai) ### Generate commands as command-line input [Section titled “Generate commands as command-line input”](#generate-commands-as-command-line-input) Type `#` on the command-line input to generate command suggestions. ![Typing '#' on the command line opens the suggestions interface](/_astro/open-ai-commands.Djm9ZIDt_10IXIS.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Typing ’#’ on the command line opens the suggestions interface. [Generating commands as command-line input demo](https://www.loom.com/embed/424a763ef0c8455e8269e541301968f2) 1. Press `` CTRL-` `` or type `#` into the text input editor to search using natural language. 2. Type in the input box what you’d like to do. For example, “replace a string in a file.” 3. Results are generated in real-time, and you can keep the current prompt or modify the prompt to generate new commands. 4. When you’ve found the command you want to execute, it can be run or saved as a Workflow onto Warp Drive to easily recall it in the future. ### \[Legacy] Generate text and contextual suggestions in interactive CLIs [Section titled “\[Legacy\] Generate text and contextual suggestions in interactive CLIs”](#legacy-generate-text-and-contextual-suggestions-in-interactive-clis) Caution **Our legacy Generate feature which works in interactive CLIs has been replaced by** [Full Terminal Use](/agent-platform/capabilities/full-terminal-use/)**, where Warp’s agent can now run and control long-running or full-screen terminal applications**.\ The agent can provide input when prompted, navigate interactive screens, and continue execution without stalling. In interactive CLI applications, you can generate input using natural language. ![Generate a SQL query](/_astro/generate-psql.CVPH5T9f_Z1OzyUo.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Generating a SQL query using natural language. ![Generate Vim input](/_astro/generate-vim.IUngL5o8_1dJxXF.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Generating Vim commands using natural language. * macOS 1. Inside a long-running, interactive command, press `CMD-I` when you see the hint text appear. 2. Type what you would like to generate in the input box. For example, “show me all tables in my Postgres database” or in Vim, “generate a recursive Fibonacci function and save it to the file.” 3. Results are generated in real time using the [LLM of your choice](/agent-platform/local-agents/generate/#supported-interactive-cli-models). 4. To refine or follow up on your query, press `CMD-Y`. You can then either edit your last message by pressing `UP ↑` or add a follow-up by typing in new text. 5. When you’ve found the text you want to add or execute, press `Enter` or click the Accept button. * Windows 1. Inside a long-running, interactive command, press `CTRL-SHIFT-I` when you see the hint text appear. 2. Type what you would like to generate in the input box. For example, “show me all tables in my Postgres database” or in Vim, “generate a recursive Fibonacci function and save it to the file.” 3. Results are generated in real time using the [LLM of your choice](/agent-platform/local-agents/generate/#supported-interactive-cli-models) 4. To refine or follow up on your query, press `CTRL-SHIFT-Y`. You can then either edit your last message by pressing `UP ↑` or add a follow-up by typing in new text. 5. When you’ve found the text you want to add or execute, press `Enter` or click the Accept button. * Linux 1. Inside a long-running, interactive command, press `CTRL-SHIFT-I` when you see the hint text appear. 2. Type what you would like to generate in the input box. For example, “show me all tables in my Postgres database” or in Vim, “generate a recursive Fibonacci function and save it to the file.” 3. Results are generated in real time using the [LLM of your choice](/agent-platform/local-agents/generate/#supported-interactive-cli-models) 4. To refine or follow up on your query, press `CTRL-SHIFT-Y`. You can then either edit your last message by pressing `UP ↑` or add a follow-up by typing in new text. 5. When you’ve found the text you want to add or execute, press `Enter` or click the Accept button. A couple of other examples of interactive CLIs where you can invoke Generate: * **Database REPL** (e.g. `psql`, `mysql`, `sqlite`): Generate SQL queries such as “create a table to store user data” or “show me all the rows in orders for the last month” * **Text editors** (e.g. `vim`, `nano`): Quickly generate text such as a markdown header, a code block comment, or a boilerplate CSS class. * **Python REPL** (e.g. `ipython`, `python`): Quickly generate Python snippets such as “create a simple plot of x” or “write a unit test for this function” * **Debugger tools** (e.g. `gdb`, `lldb`): Get commands for setting breakpoints or inspecting memory * **Version control** (e.g. `git rebase -i`): Speed up complex git commands by describing your goal such as “interactively rebase master onto feature-branch” * **Cloud provider shells** (e.g. `gcloud`, `aws cli`): faster setup or resource management such as “create a new Kubernetes cluster” or “provision a new RDS instance” Caution If you experience any issues with Generate, please visit known issues for [troubleshooting steps](/support-and-community/troubleshooting-and-support/known-issues/#online-features-dont-work). # Interacting with agents > Manage agent conversations across sessions with follow-ups, context blocks, and multi-thread support. ## Conversations with Warp’s Agent [Section titled “Conversations with Warp’s Agent”](#conversations-with-warps-agent) Conceptually, a conversation is a sequence of AI queries and blocks. Conversations are tied to sessions and you can run multiple Agent Mode conversations simultaneously in different windows, tabs, or panes. Conversations work best when the queries are related. If your new question builds on the last one, continue in the same conversation. If it is unrelated, it is better to start a new one so that the context remains relevant. Note Long conversations can cause slower performance and lower-quality answers. When working on a separate task or question, start fresh rather than relying on context from earlier interactions. Note To access conversations across devices, share them with teammates, or restore past cloud Agent conversations, enable [Cloud-synced Conversations](/agent-platform/local-agents/cloud-conversations/). ### Staying in a conversation (follow-ups) [Section titled “Staying in a conversation (follow-ups)”](#staying-in-a-conversation-follow-ups) By default, if you ask an AI query immediately after interacting in Agent Mode, your query is sent as a **follow-up** to the current conversation. * In **Classic Input**, you’ll see both the pink highlight bar on the left side of the block and a bent follow-up arrow (↳) next to your input. The conversation input chip also shows which conversation you are in. * In **Terminal and Agent modes** (the default), the conversation view provides a dedicated space for multi-turn interactions. The conversation panel shows which conversation you are in. **To follow-up on a previous conversation:** * Simply continue prompting the agent if you are already in an active conversation. * Open the **Conversations menu** (`CMD + Y` on macOS, `CTRL + SHIFT + Y` on Windows/Linux), select a conversation, and then enter your query. * Alternatively, click the pink conversation chip in the input field to resume. ![Continuing an Agent conversation in Classic Input (with indicator)](/_astro/classic-input-follow-up.e9ArJTKM_Z1Bk0Mh.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Continuing an agent conversation in Classic Input. ![Continuing an Agent conversation in agent conversation view](/_astro/follow-up-universal-input.D_6hs_pw_Z1x1ymG.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Continuing an agent conversation in the conversation view. #### Agent tips in the input [Section titled “Agent tips in the input”](#agent-tips-in-the-input) While Warp’s agent is thinking and processing your request, Warp may surface short tips with helpful workflows and ways to use Warp. These tips appear under the Warping indicator. ![Agent tips appearing under the Warping indicator while the agent processes a request.](/_astro/agent-tips.Pt7iwydM_1Vb1uA.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) You can enable or disable these tips in two places: * **Settings**: **Settings** > **Agents** > **Warp Agent** > **Input** > **Show agent tips** * **Command Palette**: Open the Command Palette (`CMD + P` on macOS, `CTRL + SHIFT + P` on Windows/Linux), then select “**Show Agent Tips**” or “**Hide Agent Tips**” ### **Managing conversations** [Section titled “Managing conversations”](#managing-conversations) You can view previous conversations or start a new conversation via the **Conversations Menu** (`CMD + Y` on macOS, `CTRL + SHIFT + Y` on Windows/Linux). Note The “New Conversation” item disappears once you start searching for an actual conversation. ### **Starting a new conversation** [Section titled “Starting a new conversation”](#starting-a-new-conversation) Warp automatically creates a new conversation in a few situations. For example, if you ask an AI query after running a shell command or if three hours pass without activity, Agent Mode will start a fresh conversation. Visual indicators differ slightly depending on input mode: * In **Classic Input,** a new conversation begins when there is no follow-up arrow (↳) next to your input. * In **Terminal and Agent modes**, starting a new conversation opens a fresh conversation view. Use the conversation panel to see all active and past conversations. - macOS You can also start a new conversation manually at any time: * In **Classic Input**, press `CMD + I` or press `BACKSPACE` while in follow-up mode. * In **Terminal and Agent modes**, press `CMD + ↵` to start a new conversation, or use the `/new` slash command. * Open the **Conversations Menu** using `CMD + Y` and select “New Conversation”. - Windows You can also start a new conversation manually at any time: * In **Classic Input**, press `CTRL + I` or press `BACKSPACE` while in follow-up mode. * In **Terminal and Agent modes**, press `CTRL + SHIFT + ↵` to start a new conversation, or use the `/new` slash command. * Open the **Conversations Menu** using `CTRL + SHIFT + Y` and select “New Conversation”. - Linux You can also start a new conversation manually at any time: * In **Classic Input**, press `CTRL + I` or press `BACKSPACE` while in follow-up mode. * In **Terminal and Agent modes**, press `CTRL + SHIFT + ↵` to start a new conversation, or use the `/new` slash command. * Open the **Conversations Menu** using `CTRL + SHIFT + Y` and select “New Conversation”. ![Starting a new Conversation in Classic Input](/_astro/classic-input-new-convo.D7tP-0w9_PofOx.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Starting a new Conversation in Classic Input. ![Starting a new Agent Conversation in agent conversation view](/_astro/universal-input-new-convo.BBZQR34B_XNurT.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Starting a new Agent Conversation in agent conversation view. ## Context window management [Section titled “Context window management”](#context-window-management) Every conversation with an agent consumes tokens stored in a **context window**. The context window (sometimes called *context length*) is the amount of text (measured in tokens) that a Large Language Model (LLM) can process at one time. **The size of the context window depends on the model you are using.** As tokens accumulate and exceed the context window, performance and response quality may degrade. If the context window is exceeded, the model may lose track of earlier parts of the conversation, and **Warp will automatically summarize the conversation to free up space**. ### Warp provides a **context window usage indicator** to help you track this: [Section titled “Warp provides a context window usage indicator to help you track this:”](#warp-provides-a-context-window-usage-indicator-to-help-you-track-this) When less than 20% of the window is used, no indicator is shown. As more tokens accumulate, the usage bar progresses to reflect how much of the context window has been consumed. ![Context window usage indicator in its early state, with light usage shown.](/_astro/context-window-1.CJBG34Ms_Z1NRcip.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ![Context window usage indicator filling further as more tokens accumulate.](/_astro/context-window-2-1.CrQgp9te_Z1Ec2ai.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) As you approach the limit, the indicator turns red to warn that the context window is nearly full. ![Context window usage indicator turning red as the conversation approaches the model's context limit.](/_astro/context-window-2.ChcDYN3u_Z2oqPke.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Once the limit is exceeded, Warp automatically summarizes the conversation so you can continue without losing important context. ![Context window indicator after Warp automatically summarizes the conversation to free up space.](/_astro/context-window-3.BQjme9ej_2m9dvd.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The context window usage indicator is available in agent conversation views. Note If you switch models during a conversation, the context usage indicator updates only after you send your next message. ## Conversation segmentation [Section titled “Conversation segmentation”](#conversation-segmentation) Warp automatically detects when your query has shifted to a new topic. When this happens, it suggests starting a new conversation instead of continuing in the same context. These options appear in the blocklist, where you can decide whether to branch off into a new conversation or keep going with the current one. ![Suggestion in the blocklist to start a new conversation when Warp detects a topic shift.](/_astro/conversation-segmentation.Dhl7hoit_ZiJDmE.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) You can also create a new conversation manually at any time by using the keyboard shortcut, opening a new tab, or opening a new pane. * macOS * Start a new conversation: `CMD + SHIFT + N` * Open a new tab: `CMD + T` * Open a new pane: `CMD + D` * Windows * Start a new conversation: `CTRL + SHIFT + N` * Open a new tab: `CTRL + SHIFT + T` * Open a new pane: `CTRL + SHIFT + D` * Linux * Start a new conversation: `CTRL + SHIFT + N` * Open a new tab: `CTRL + SHIFT + T` * Open a new pane: `CTRL + SHIFT + D` ## Conversation Panel [Section titled “Conversation Panel”](#conversation-panel) The **Conversation Panel** on the left side of the window is the home for browsing and switching between agent conversations. It’s designed to make multi-threaded work obvious: you can see what’s active, what you ran recently, and jump back into any thread without guessing where your context went. ![Conversation Panel listing active and past agent conversations.](/_astro/agent-conversations-new-modality.ivoLCy2O_yk1sY.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ### Panel layout [Section titled “Panel layout”](#panel-layout) The conversation panel is split into two dropdowns (collapsible sections) that help you navigate between conversations: #### Active [Section titled “Active”](#active) The **Active** dropdown lists conversations where you have sent at least one query since opening them. Simply expanding a conversation does not make it active—you need to interact with the Agent first. * Select a conversation to switch to it immediately. * The conversation you’re currently viewing is highlighted. * Cloud agent conversations and Oz runs always appear in **Active** while they are open. #### Past [Section titled “Past”](#past) The **Past** dropdown lists your recent conversation history. Each row typically shows: * Conversation title * When it happened (for example, “8 min ago”, “3 days ago”) * Working directory (when relevant) Use **Past** to restore a previous conversation. When you select a past conversation, Warp reopens it in a new tab or your active pane, letting you continue where you left off. ### Conversation storage [Section titled “Conversation storage”](#conversation-storage) By default, your agent conversations are stored locally on your machine. You can optionally enable **cloud-synced conversations** to: * Access your conversation history across different devices * Share conversations with teammates * Retain conversations when you log out or switch machines For full details on enabling cloud sync, sharing conversations, and accessing cloud agent conversations, see [Cloud-synced Conversations](/agent-platform/local-agents/cloud-conversations/). Note To enable cloud sync, go to **Settings** > **Privacy** and toggle on **“Store AI conversations in the cloud”**. When disabled, conversations are stored locally only and cannot be shared. Note that cloud agent conversations are always stored in the cloud regardless of this setting. ### Search [Section titled “Search”](#search) Use the search field at the top of the conversation panel to quickly find your conversation. * Type to filter conversations by title (and, in some builds, by directory/context). * Useful when you have many threads and want to jump directly to one. ### New conversation [Section titled “New conversation”](#new-conversation) Click the **New conversation** button at the bottom of the **Active** conversation list to start a new conversation. Starting a new conversation creates a fresh thread in the **Active** dropdown, without deleting or overwriting your previous ones. ### Navigation behavior [Section titled “Navigation behavior”](#navigation-behavior) Navigation between [Terminal and Agent modes](/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes/) is designed to be direct: * **Clicking an active conversation** - Takes you directly to that conversation view. * **Clicking a past conversation** - Opens the conversation in a **new pane**, preserving your current context. * **Command Palette** - Open the Command Palette and type `conversations:` to filter and navigate directly to any conversation. * **`⌘Y` conversation selector** - Opens a dedicated menu showing your existing and past conversations. This works in both terminal view and agent view. * **Up-arrow history** - Shows both past shell commands and past prompts you’ve sent in recent conversations. The behavior differs by context: * **In terminal view** - Shows both past shell commands and recent conversations. * **In agent view** - Shows past prompts you’ve sent in conversations. *** ### Ways to move around [Section titled “Ways to move around”](#ways-to-move-around) Use `esc` or the back button to return to terminal mode, `⌘Y` to open the conversation selector, or `⌘↩` to start a new conversation. For a complete list of keyboard shortcuts and slash commands, see [Terminal and Agent modes - Keyboard shortcuts](/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes/#keyboard-shortcuts-quick-reference). ### Exit confirmation for in-progress conversations [Section titled “Exit confirmation for in-progress conversations”](#exit-confirmation-for-in-progress-conversations) Exiting a conversation that is still in progress will **cancel** the agent’s current work. To prevent accidental cancellations, Warp shows a confirmation hint: * **First exit attempt** - The hint changes to “Press again to exit” (or similar). * **Confirmation window** - You have about 2 seconds to press `esc` or `^C` again to confirm. * **After confirmation** - Warp exits the conversation and cancels the in-progress request. This confirmation step ensures you don’t accidentally lose work when the agent is mid-task. Note Empty new conversations (where you haven’t sent any messages yet) can be exited immediately without confirmation. # Conversation Forking > Branch into a new agent thread with full context to explore alternatives without altering the original conversation. Warp allows you to **fork conversations** to create a new thread that inherits all of the context, messages, and history from an existing conversation. This is useful when you want to branch off in a new direction without affecting the original conversation. ### How conversation forking works [Section titled “How conversation forking works”](#how-conversation-forking-works) * When you fork a conversation, the new thread starts with the same context and history as the original. * Any follow-ups in the forked conversation do **not** impact the original. Likewise, continuing in the original conversation does not change the fork. * Forked conversations behave just like any other conversation: you can move them into new windows, panes, or tabs. * Your selected model and execution profile are preserved in the forked conversation. *Example*: You can fork a conversation to explore an alternate solution, ask “what if” questions, or continue down two separate paths in parallel. ### How to fork a conversation [Section titled “How to fork a conversation”](#how-to-fork-a-conversation) There are five ways to fork an existing conversation: #### **1. From the Command Palette** [Section titled “1. From the Command Palette”](#1-from-the-command-palette) Open the menu using the Command Palette (`CMD + Y` on macOS / `CTRL + SHIFT + Y` on Windows/Linux). Select **Fork current conversation** to fork your current conversation, or fork a specific conversation from open conversations. ![Command Palette showing the Fork current conversation option highlighted](/_astro/conversation-forking-palette.BNHRy8Zx_uT3sq.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) In addition, when you hover over any open conversation in the Command Palette, you’ll see a **fork button**. This lets you fork not only active conversations, but also inactive and historical ones. ![Command Palette listing open conversations with a fork button visible on hover](/_astro/conversation-forking-open-conversations.Coq00-hC_1X3sJm.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) You can also access this conversation view from the conversation chip in the current conversation. ![Conversation chip in the input area showing the Manage conversations shortcut](/_astro/conversation-forking-chip.Dl8peSj9_15PHYP.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### **2. From the footer of the most recent AI response block** [Section titled “2. From the footer of the most recent AI response block”](#2-from-the-footer-of-the-most-recent-ai-response-block) In any conversation in the blocklist, click the **fork button** in the footer of the most recent AI block. A new conversation opens in a separate pane with the full context of the original. ![Fork conversation button in the footer of the most recent agent response block](/_astro/conversation-forking-footer.cfCl1sGv_ZxgHUu.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### **3. Using the `/fork` slash command** [Section titled “3. Using the /fork slash command”](#3-using-the-fork-slash-command) Type `/fork` in the input to fork the current conversation. You can optionally include a prompt after the command, and Warp will send that prompt in the newly forked conversation. * Press `Enter` to open the fork in a new pane (default) * Press `⌘+Enter` (macOS) or `Ctrl+Enter` (Windows/Linux) to open the fork in the current pane *Example*: `/fork Can you try a different approach?` Forks the selected conversation and immediately sends `Can you try a different approach?` in the forked conversation. #### **4. Using the /fork-and-compact slash command** [Section titled “4. Using the /fork-and-compact slash command”](#4-using-the-fork-and-compact-slash-command) Type `/fork-and-compact` to fork the current conversation and automatically compact the forked version. This combines forking with [context window management](/agent-platform/local-agents/interacting-with-agents/#context-window-management), giving you a fresh start with a summarized context. * Press `Enter` to open the fork in a new pane (default) * Press `⌘+Enter` (macOS) or `Ctrl+Enter` (Windows/Linux) to open the fork in the current pane ![Using the /fork-and-compact slash command to fork and summarize a conversation](/_astro/conversation-fork-and-compact.DfcxH8fj_Z1fdaDY.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### **5. Using the `/fork-from` slash command** [Section titled “5. Using the /fork-from slash command”](#5-using-the-fork-from-slash-command) Type `/fork-from` to open a searchable menu of all queries in the current conversation. Select a query to fork the conversation from that specific point—everything up to and including that exchange is included in the fork, but subsequent messages are excluded. This is a more discoverable alternative to right-clicking on an agent response block. ### Fork from anywhere in a conversation [Section titled “Fork from anywhere in a conversation”](#fork-from-anywhere-in-a-conversation) In addition to forking from the end of a conversation, you can fork from any point in the conversation history. This lets you return to an earlier agent response and branch off in a new direction from there. ![YouTube video](https://i.ytimg.com/vi/SlhF4_0bBxY/sddefault.jpg) To fork from a specific point, **right-click** on any agent response block or click the three-dot menu in the top-right corner of the block. * Select **Fork conversation from here** to create a new conversation that includes everything up to and including that response, but excludes any queries or responses that came after it. **This is particularly useful for:** * **Exploring alternate paths** - Go back to a point where the conversation was on track and try a different approach. * **Managing your context window** - If a conversation has grown too long, fork from an earlier point to continue with only the relevant context. * **Preventing context pollution** - When a conversation has accumulated errors or gone off track, fork from before those issues occurred to start fresh. ### Settings [Section titled “Settings”](#settings) You can configure the default layout for forked conversations in **Settings** > **Features** > **Open forked conversation layout**: * **Split Pane** (default): Opens the forked conversation in a new pane alongside your current view. * **New Tab**: Opens the forked conversation in a new tab. This setting controls the default behavior when forking via the Command Palette, AI block footer button, or slash commands (when pressing `Enter`). ### Using forked conversations [Section titled “Using forked conversations”](#using-forked-conversations) * Once forked, you can continue prompting as if you were still in the original conversation. The original conversation remains unchanged, allowing you to reference or continue both in parallel. * For example, after forking you can ask *“Could you explain more?”* and Warp responds using the inherited context. **Forking is especially useful when:** * You want to explore different approaches without losing the original thread. * You need to keep one conversation “clean” while experimenting in another. * You want to reuse context or specific blocks from older conversations. # Terminal and Agent modes > Warp provides two distinct modes: a clean terminal for commands, and a dedicated conversation view for multi-turn agent workflows. Warp provides two distinct modes: a clean terminal for commands, and a dedicated conversation view for multi-turn conversations with [Oz, Warp’s agent](/agent-platform/local-agents/interacting-with-agents/). ![YouTube video](https://i.ytimg.com/vi/J715YW5VC18/sddefault.jpg) *** ## Key terminology [Section titled “Key terminology”](#key-terminology) Before diving in, here are two key concepts: * **Terminal session** - Your shell environment where you run commands. This is the default mode when you open Warp—a clean, traditional terminal input. * **Oz agent conversation** - A multi-turn interaction with Oz. Conversations maintain context across exchanges and have their own dedicated view with richer controls. Terminal and Agent modes make switching between these two contexts seamless while keeping them visually distinct. *** ## Why two modes [Section titled “Why two modes”](#why-two-modes) Terminal and Agent modes separate your terminal and agent workflows into distinct contexts: * **Clean terminal by default** - Minimal input when you’re running commands. Agent controls appear only when you need them. * **Dedicated conversation view** - Multi-turn agent workflow spaces have full controls like model select, voice input, image attachments, and conversation history. * **Explicit mode switching** - The current mode is clearly visible, enabling better workflow organization—you can separate, minimize, and expand different conversations. *** ## Two distinct modes [Section titled “Two distinct modes”](#two-distinct-modes) ### Terminal mode (default) [Section titled “Terminal mode (default)”](#terminal-mode-default) Terminal mode is the default when you open a new tab or pane. * Looks and behaves like a traditional terminal input. * Agent controls are not always visible, keeping the interface clean. * A message bar shows contextual hints for interacting with agents. ![Default terminal mode in Warp, showing a clean terminal input.](/_astro/terminal-modality.D5yPuhbT_Z2p9RLG.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) **Terminal mode hints** The message bar at the bottom of the terminal provides contextual guidance: * **Default hint** - Shows `⌘↩ for new agent` when the input is empty. * **Send to agent** - Shows `⌘↩ to send to agent` when you have text that could be a prompt. * **Error block attachment** - When the last command failed, shows a hint to attach the output as agent context (e.g., `⌘↑ attach 'npm install...' output as agent context`). * **Attached context indicator** - Shows when you have blocks or text selections attached (e.g., `⌘↩ to send to agent with 'git status' attached`). * **Continue conversation** - When your last visible item is an agent conversation block, shows `⌘Y to continue conversation`. If auto-detection is enabled, Warp labels your input as “agent” or “shell” before you submit, showing “(autodetected)” in magenta. See [Understanding auto-detection](#understanding-auto-detection) for configuration and override methods. **Disabling the message bar:** To hide the terminal mode hint bar while keeping AI features enabled, go to **Settings** > **Features** > **Terminal Input** and toggle off **Show terminal input message line**. This only hides the contextual hints—it does not disable any AI functionality. Caution If you disable the message bar while auto-detection is enabled, you won’t see the visual indicator that tells you whether Warp detected your input as a shell command or an agent prompt. Consider also disabling auto-detection (**Settings** > **Agents** > **Warp Agent** > **Input**) if you turn off the message bar. Note The shortcuts shown on this page use macOS keybindings. For Windows and Linux shortcuts, see [Keyboard Shortcuts](/getting-started/keyboard-shortcuts/). ### Oz agent conversation view (expanded UI) [Section titled “Oz agent conversation view (expanded UI)”](#oz-agent-conversation-view-expanded-ui) * A dedicated conversation view with richer agent controls including model select, voice input, image attachments, and conversation management. * Familiar “charms” (current directory, git branch, diff view entry point, etc.) are still available. * Designed for multi-turn workflows and managing multiple conversations. ![The dedicated Agent Conversation View.](/_astro/agent-modality-conversation-view.Dg5PWVz0_YQ0ez.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The dedicated Agent Conversation View. **Key difference** Agent controls appear only when you’re in a conversation, keeping your terminal clean otherwise. In the previous UI, agent controls were always present. With Terminal and Agent modes, these controls are hidden by default and appear **once you enter an agent conversation.** Note Agent conversation views are identified with an alternative background color and the input toolbelt showing model selector, voice input, and image attachment buttons. #### Customizing the input toolbelt [Section titled “Customizing the input toolbelt”](#customizing-the-input-toolbelt) The chips and buttons on the agent input toolbelt can be reordered, hidden, or moved between the left and right sides of the input. Right-click the input in an agent conversation and select **Edit agent toolbelt** to open the editor. Your layout persists across app restarts. Agent Mode-specific items include the model selector, autodetection toggle, Context Usage, and fast forward toggle. Shared items like voice input, file attachment, and context chips appear in both the Agent Mode toolbelt and the [CLI coding agent toolbelt](/agent-platform/cli-agents/overview/#customizing-the-toolbelt). **Block origin and visibility** Blocks in Warp belong to either the terminal view or a specific agent conversation: * **Terminal blocks** - Commands you run directly in the terminal always appear in your terminal blocklist and can be attached as context to any conversation. * **Agent conversation blocks** - Commands executed within an agent conversation (either by you or the agent) only appear within that specific conversation and don’t appear in the terminal blocklist. In agent conversations, context is managed automatically, with optional manual attachment from terminal view: * **Automatic context** - Commands executed within an agent conversation are included as context for subsequent prompts. * **Manual attachment** - You can attach terminal blocks to bring in outputs from outside the conversation. * **Conversation scope** - Agent conversation blocks stay scoped to that conversation, while terminal blocks remain in the terminal blocklist. This separation keeps your terminal view clean while preserving full context within each conversation. For shortcuts, pending vs. attached context, and block selection behavior, see [Blocks as Context](/agent-platform/local-agents/agent-context/blocks-as-context/). #### Cloud agent conversations [Section titled “Cloud agent conversations”](#cloud-agent-conversations) In addition to local agent conversations, you can start **Oz cloud agent conversations** that run in an isolated cloud environment. Cloud agents are useful for: * Running parallel agents across multiple tasks * Running agents remotely on hosted computers (offloading compute from your local machine) * Running agents autonomously in the cloud * Checking in on your agents from anywhere To start a cloud agent conversation, press `⌥⌘↩` (Option+Command+Enter on macOS, or `Ctrl+Alt+Enter` on Windows/Linux) from terminal mode. You can also use the welcome block’s “Start cloud project” action. Cloud agent conversations have a few differences from local conversations: * **Environment selector** - Choose which [Warp Environment](/agent-platform/cloud-agents/environments/) to run in * **Credits indicator** - Shows your remaining cloud agent credits * **Different zero state** - The conversation header indicates “New Oz cloud agent conversation” Cloud agent conversations are always stored in the cloud. For more details on accessing and sharing cloud conversations, see [Cloud-synced Conversations](/agent-platform/local-agents/cloud-conversations/). **Accessing running or past cloud conversations:** * **From the conversation list panel** - Cloud conversations appear alongside local conversations. Click to open. * **From the management view** - Use the [Agent Management view](/agent-platform/cloud-agents/managing-cloud-agents/) to see all cloud agent runs, filter by status, and click any row to open the conversation. * **From the Oz web app** - Access your cloud agents at [oz.warp.dev](https://oz.warp.dev) to manage runs from any browser. For more on cloud agents, see [Cloud Agents Overview](/agent-platform/cloud-agents/overview/). *** ## Understanding auto-detection [Section titled “Understanding auto-detection”](#understanding-auto-detection) Auto-detection (which detects whether you’re typing natural language or a shell command) helps Warp interpret each input as either a shell command or an agent request. When auto-detection is enabled, Warp shows an **inline indicator** in the prompt (for example, “(autodetected)” in magenta). ![Inline "(autodetected)" indicator showing Warp routed terminal input to the agent.](/_astro/send-to-agent.BrqMAnSq_Z2fl74V.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ### How it works [Section titled “How it works”](#how-it-works) **In terminal mode:** When you type text that appears to be a natural language request (e.g., “Summarize the dependencies in this project”), Warp labels it as “agent” and displays the “(autodetected)” indicator. Pressing Enter will send your input directly to the agent in a new conversation, creating a “quicksend” workflow for text-only requests. **In agent conversation view:** When auto-detection identifies your input as a shell command, Warp displays a distinct UI border around the input to indicate the mode switch. This helps you understand that your input will run as a command rather than being sent to the agent. ### Settings [Section titled “Settings”](#settings) Note You can control auto-detection separately for terminal mode and agent conversation view. Both toggles are in **Settings** > **Agents** > **Warp Agent** > **Input**: * **Terminal mode:** Toggle **Autodetect agent prompts in terminal input** * **Agent conversation view:** Toggle **Autodetect terminal commands in agent input** ### Override methods [Section titled “Override methods”](#override-methods) There are multiple ways to override auto-detection: * **Keyboard shortcut** - Press `⌘I` to switch between command and Agent Mode. * **`!` prefix** - In agent view, prepend `!` to your input to force it to run as a shell command (e.g., `!ls` or `!git status`). Common examples: * You typed something that looks like a command, but you intended an agent request. * You typed a sentence, but you intended it to run as a command (rare, but it happens). Note **Note:** After you override, the selection is “sticky” for that entry, so you can submit confidently. ### Defaults for new vs existing users [Section titled “Defaults for new vs existing users”](#defaults-for-new-vs-existing-users) Auto-detection is enabled by default for new Warp users. For users who had Warp before Terminal and Agent modes were introduced, auto-detection is disabled by default to preserve their existing workflows. *** ## Entering and navigating conversations [Section titled “Entering and navigating conversations”](#entering-and-navigating-conversations) ### How to enter a conversation [Section titled “How to enter a conversation”](#how-to-enter-a-conversation) There are several ways to start or enter an Oz agent conversation: #### A) Use the `/agent` or `/new` slash command [Section titled “A) Use the /agent or /new slash command”](#a-use-the-agent-or-new-slash-command) Type `/agent` or `/new` in terminal mode to enter the agent conversation view. This is the recommended way to explicitly switch to Agent Mode. * `/agent` or `/new` - Opens a new agent conversation view with full controls * `/agent ` - Sends your prompt directly to the agent in a new conversation #### B) Use the keyboard shortcut [Section titled “B) Use the keyboard shortcut”](#b-use-the-keyboard-shortcut) Press `⌘↩` (Command+Enter on macOS, or `Ctrl+Shift+Enter` on Windows/Linux) to enter the conversation view immediately. This is a shortcut for `/agent`. **Use this when you want to:** * attach an image * use voice input * access other conversation-only controls before sending your first message #### C) Quicksend with auto-detection [Section titled “C) Quicksend with auto-detection”](#c-quicksend-with-auto-detection) When auto-detection is enabled in terminal mode, you can start a conversation immediately: 1. Type a natural language request (e.g., “Summarize the dependencies in this project”). 2. If Warp detects it as an agent request, it shows an “(autodetected)” indicator. 3. Press Enter to send directly to the agent in a new conversation. This “quicksend” method is useful for quick, text-only requests when you don’t need conversation-only controls like voice input or image attachments. #### D) Continue from the up-arrow history menu [Section titled “D) Continue from the up-arrow history menu”](#d-continue-from-the-up-arrow-history-menu) Press `↑` (up arrow) to open an inline history menu. The menu contents vary by context—see [Navigation behavior](/agent-platform/local-agents/interacting-with-agents/#navigation-behavior) for details on how up-arrow works in terminal view vs. agent view. #### E) Click an active AI suggestion [Section titled “E) Click an active AI suggestion”](#e-click-an-active-ai-suggestion) When [Active AI Recommendations](/agent-platform/local-agents/active-ai/) is enabled, Warp displays contextual prompt suggestions based on your recent activity. Clicking any of these suggestions opens the agent conversation view and sends that prompt immediately. *** ### Navigating conversations [Section titled “Navigating conversations”](#navigating-conversations) Warp includes a **Conversation Panel** for browsing and managing your agent conversations. For details on the panel layout, navigation, and conversation storage, see [Agent Conversations](/agent-platform/local-agents/interacting-with-agents/). ### Using slash commands [Section titled “Using slash commands”](#using-slash-commands) **In an agent conversation** ![Slash command menu open inside an agent conversation, showing the full set of commands.](/_astro/slash-commands-agent-modality.DX_bPYQF_1ILRuD.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) While you’re in an agent conversation, you can access Warp’s [slash commands](/agent-platform/capabilities/slash-commands/) any time by typing `/` in the input. * Type `/` to open the command menu * Keep typing to filter commands (for example: `/conversations`, `/compact`) * Use `↑` / `↓` to navigate and `Enter` to run * Press `esc` to dismiss the menu **Key slash commands in Agent Mode:** * `/new` or `/agent` - Start a new conversation. * `/plan` or `/plan ` - Enter agent view and start a planning conversation. The agent will create an implementation plan before making changes. * `/conversations` - Open the conversation list panel. * `/compact` - Summarize and compact the current conversation to free up context window space. * `/fork` - Fork the current conversation into a new thread. Press `Enter` to fork in the existing pane, or `⌘↩` (`Ctrl+Shift+Enter` on Windows/Linux) to fork in a new pane. * `/fork-and-compact` - Fork the conversation and automatically summarize it. * `/fork from` - Choose a specific point in the conversation to fork from. A menu appears showing your previous queries—select one to fork from that point. * `/model` - Select or change the AI model for the conversation. Slash commands are a quick way to take common actions without leaving the keyboard. **In terminal mode** ![Slash command menu open from terminal mode, showing a reduced set of quick actions.](/_astro/slash-commands-terminal-modality.DDtcN5_j_Z28s3S6.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Slash commands aren’t just for agent conversations. You can also type `/` in terminal mode to open a limited set of commands. Note Agent conversations expose the full set of slash commands (including `/fork`, `/compact`, and `/model`). Terminal mode exposes a reduced set focused on quick actions. For the complete list of available slash commands, see [Slash Commands](/agent-platform/capabilities/slash-commands/). ### Forking conversations [Section titled “Forking conversations”](#forking-conversations) Forking lets you branch off from an existing conversation to explore a different direction without losing your original thread. **How to fork:** 1. In an agent conversation, type `/fork` and press `Enter`. 2. Choose where to open the forked conversation: * `Enter` - Fork in the current pane (replaces the current view). * `⌘↩` (`Ctrl+Shift+Enter` on Windows/Linux) - Fork in a new pane (keeps the original visible). **Fork and compact:** Use `/fork-and-compact` to fork and automatically summarize the conversation. This is useful when your context window is getting full but you want to continue building on the same work. **Fork from a specific point:** Use `/fork from` to choose exactly where in the conversation you want to branch from: 1. Type `/fork from` and press `Enter`. 2. A menu shows your previous queries in the conversation. 3. Select the query you want to fork from. 4. Choose `Enter` (existing pane) or `⌘↩` / `Ctrl+Shift+Enter` (new pane). This is helpful when you want to go back to an earlier point and try a different approach. For more forking methods and use cases, see [Conversation Forking](/agent-platform/local-agents/interacting-with-agents/conversation-forking/). *** ## Using Agent Mode as the default experience [Section titled “Using Agent Mode as the default experience”](#using-agent-mode-as-the-default-experience) If you prefer to type natural language at any point in a terminal session and have it automatically routed to an agent, you can configure this using the “default mode for new sessions” setting. ![Using Agent as your default for new tab sessions](/assets/agent-platform/recreate-universal-input.gif) Using Agent as your default for new tab sessions. ### Step 1 — Set new tabs to open in agent view [Section titled “Step 1 — Set new tabs to open in agent view”](#step-1--set-new-tabs-to-open-in-agent-view) By default, new tabs and panes open in terminal mode. To launch directly into an Oz agent conversation instead: 1. Go to **Settings** > **Features** > **General**. 2. Change **Default mode for new sessions** to **Agent**. ### Step 2 — Enable auto-detection in Agent Mode [Section titled “Step 2 — Enable auto-detection in Agent Mode”](#step-2--enable-auto-detection-in-agent-mode) With auto-detection enabled in agent view, Warp automatically detects whether your input is natural language or a shell command, routing it to the agent or running it in the terminal accordingly. You can also use the “toggle input mode” keyboard shortcut to override auto-detection and force either “shell” or “agent” mode. 1. Go to **Settings** > **Agents** > **Warp Agent** > **Input**. 2. Toggle on **Autodetect terminal commands in agent input**. Press `⌘I` (macOS) or `Ctrl+I` (Windows/Linux) to manually toggle between shell and Agent Mode at any time, overriding auto-detection. Note Auto-detection is enabled by default for new Warp users. *** ## Keyboard shortcuts (quick reference) [Section titled “Keyboard shortcuts (quick reference)”](#keyboard-shortcuts-quick-reference) In conversation view, press `?` to show/hide the full shortcuts panel. Here are the key shortcuts: ### Navigation and mode switching [Section titled “Navigation and mode switching”](#navigation-and-mode-switching) * **Start new agent conversation** (from terminal mode) - `⌘↩` (macOS) / `Ctrl+Shift+Enter` (Windows/Linux) * **Start new cloud agent conversation** (from terminal mode) - `⌥⌘↩` (macOS) / `Ctrl+Alt+Enter` (Windows/Linux) * **Send to agent with attached context** (from terminal mode) - `⌘↩` (macOS) / `Ctrl+Shift+Enter` (Windows/Linux) when blocks are selected * **Tag agent into long-running command** - `⌘↩` (macOS) / `Ctrl+Shift+Enter` (Windows/Linux) while an interactive command is running * **Exit conversation** (back to terminal mode) - `esc` * **Stop agent / exit on empty input** - `^C` / `Ctrl+C` * **Open conversation selector** - `⌘Y` (macOS) / `Ctrl+Y` (Windows/Linux) * **Toggle conversation list panel** - `⌘⇧H` (macOS) / `Ctrl+Shift+H` (Windows/Linux) * **Override auto-detection** (switch shell ↔ agent) - `⌘I` (macOS) / `Ctrl+I` (Windows/Linux) ### Input modifiers [Section titled “Input modifiers”](#input-modifiers) * **`!`** - Prepend to force shell mode (e.g., `!ls`) * **`/`** - Open slash command menu * **`@`** - Open context menu (attach files, symbols, etc.) * **`?`** - Show/hide keyboard shortcuts panel ### Conversation actions [Section titled “Conversation actions”](#conversation-actions) * **Resume a paused/cancelled conversation** - `⌘⇧R` (macOS) / `Ctrl+Alt+R` (Windows/Linux) * **Toggle auto-accept** (for agent tool executions) - `⌘⇧I` (macOS) / `Ctrl+Shift+I` (Windows/Linux) * **Open code review pane** - `⌘⇧+` (macOS) / `Ctrl+Shift++` (Windows/Linux) * **Toggle plan panel** (if a plan exists) - `⌘⌥P` (macOS) / `Ctrl+Alt+P` (Windows/Linux) ### In slash command / fork menus [Section titled “In slash command / fork menus”](#in-slash-command--fork-menus) * **Navigate menu items** - `↑` / `↓` * **Select** (fork in existing pane) - `Enter` * **Select and open in new pane** - `⌘↩` (macOS) / `Ctrl+Shift+Enter` (Windows/Linux) * **Dismiss menu** - `esc` ### Customizing keybindings [Section titled “Customizing keybindings”](#customizing-keybindings) You can customize keyboard shortcuts for slash commands and other actions in **Settings** > **Keyboard shortcuts**. This lets you assign your preferred key combinations to frequently used commands. For example, to bind a keyboard shortcut to the `/agent` slash command: 1. Open **Settings** > **Keyboard shortcuts** 2. Search for “agent” or the slash command you want to bind 3. Click the shortcut field and press your desired key combination 4. The shortcut is saved automatically This is useful for actions you perform frequently, like starting a new conversation or opening the conversation list. # Voice input for agents > Voice enables natural language interaction with Warp, letting you speak commands and queries directly to your terminal. Warp’s Voice feature transforms how you interact with your terminal, letting you naturally speak commands and questions instead of typing them. This is especially powerful when combined with Agent Mode for complex operations or when you need to explain longer scenarios. Note Voice input functionality can be configured in **Settings** > **Agents** > **Warp Agent** > **Voice**. You can toggle voice input and select your preferred activation hotkey from pre-defined options. [Voice Demo](https://www.loom.com/embed/77399be4e434443488bbe267b3548552) ## Getting started with voice [Section titled “Getting started with voice”](#getting-started-with-voice) ### Initial setup [Section titled “Initial setup”](#initial-setup) First-time users will need to grant microphone permissions: * On macOS: Accept the system permission prompt or allow Warp microphone access in  > **System Settings** > **Privacy & Security** > **Microphone** * On Windows: Allow Warp microphone access in **Settings** > **Privacy & Security** > **Microphone** * On Linux: Configure through system sound settings ### Using voice [Section titled “Using voice”](#using-voice) There are two ways to activate Voice: 1. **Microphone Button in Agent Mode** * Click the microphone icon in Agent Mode * Start speaking when the indicator shows it’s listening * Click again to stop recording 2. **Hotkey Method** * macOS * Press and hold the `Fn` key (configurable) to start recording * Speak your command or query while holding the key * Release the `Fn` key to stop recording and transcribe * Windows * Press and hold the `ALT-RIGHT` key (configurable) to start recording * Speak your command or query while holding the key * Release the `ALT-RIGHT` key to stop recording and transcribe * Linux * Press and hold the `ALT-RIGHT` key (configurable) to start recording * Speak your command or query while holding the key * Release the `ALT-RIGHT` key to stop recording and transcribe ![Voice settings panel showing hotkey configuration and voice input toggle options](/_astro/voice-settings.Qx5sGqFC_ZPa9MP.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Voice input settings. ### Sample use cases [Section titled “Sample use cases”](#sample-use-cases) Voice input makes complex interactions with Agent Mode more natural and efficient. Instead of typing lengthy queries, you can speak naturally to accomplish various tasks. For example, you can say “Create a new Node.js project, install Express and MongoDB, then set up a basic server with a health check endpoint,” or “What’s the difference between chmod and chown? Give me examples of when to use each one.” You can also describe multi-step system tasks like “Find all log files in my project that contain errors from the last 24 hours, create a summary of the errors, and email it to me.” Agent Mode breaks down these requests into the necessary commands and provides detailed explanations. Voice input is not limited to just Agent Mode - it works across all of Warp’s input interfaces. Whether you’re using the Find dialog to search through text, entering commands in the terminal, or working with other input editors, you can use voice commands to quickly input your text. ![Voice input works across Warp's editor interfaces, including the Find dialog and other input editors](/_astro/voice-in-find.74euwCgu_Z1W6tPX.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Voice input in a Warp editor. ## Privacy & security [Section titled “Privacy & security”](#privacy--security) The transcription is powered by [Wispr Flow](https://wisprflow.ai/). Voice data is processed in real-time by Wispr Flow and is not retained as a recording after transcription. ## Usage limits [Section titled “Usage limits”](#usage-limits) Voice features have anti-abuse limits in place to ensure fair usage. These limits are subject to change as we continue to improve the service. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### Common issues [Section titled “Common issues”](#common-issues) 1. **Microphone not detected** If your microphone isn’t being detected, first check your system permissions to ensure Warp has access. You should also verify that your microphone is properly connected to your system. If issues persist, try restarting Warp to reset the connection. 2. **Poor transcription quality** To improve transcription quality, try to minimize background noise in your environment. Position yourself closer to the microphone while speaking, and verify that your microphone input levels are properly adjusted in your system settings. For best results, speak clearly at a natural pace and use complete sentences to provide better context. When referring to specific file names or commands, enunciate them clearly. It’s also recommended to review the transcription before sending to ensure accuracy. 3. **Feature not activating** If the Voice feature isn’t activating, confirm that your hotkey settings are correctly configured in Warp. Check for any conflicting keyboard shortcuts that might interfere with Voice activation. Also ensure that you’re running the latest version of Warp, as older versions can have compatibility issues. If you are on an Enterprise plan, your administrator may have disabled Voice functionality, or it may be pending approval. # Interactive Code Review > Review agent-generated code, leave inline comments, and have Warp's native agent or any supported third-party CLI agent apply your feedback. ### Overview [Section titled “Overview”](#overview) Interactive Code Review lets you review, annotate, and refine code generated by any supported agent, whether that’s Warp’s native Agent or a third-party CLI agent running in Warp. Instead of relying on an AI to review another AI’s output, Warp keeps the developer in control. You can inspect diffs, leave inline comments, batch feedback, and send all requested changes back to the agent in a single pass. ![YouTube video](https://i.ytimg.com/vi/jit_6eevt8w/sddefault.jpg) **Interactive Code Review builds on Warp’s existing** [Code Review](/code/code-review/) **panel.** For details on diff views, reverting hunks, opening files, and all available entry points, see the Code Review documentation. Note Note that both the [Code Review](/code/code-review/) panel and Interactive Code Review require working in a Git-indexed directory. ### Supported agents [Section titled “Supported agents”](#supported-agents) Interactive Code Review works with any supported agent running in Warp: * **Warp’s native Agent** — the built-in agent in Agent Mode * **Third-party CLI agents** — Claude Code, OpenAI Codex, OpenCode, Amp, Auggie, Copilot CLI, Cursor CLI, Gemini CLI, Droid, and Pi For the full feature matrix and setup details for each CLI agent, see [Third-Party CLI Agents](/agent-platform/cli-agents/overview/). *** When an agent modifies files, Warp automatically gathers those edits into a diff. Opening the Code Review panel shows you every change the agent made. From there, you can leave comments on specific lines or blocks, review your comment list, and submit all feedback to the agent at once. The agent applies the requested updates and returns an updated diff for further review. This gives you a familiar pull-request style workflow inside Warp without switching editors or tools. ### Leave inline comments [Section titled “Leave inline comments”](#leave-inline-comments) Select any changed line or block and add a comment describing what you want adjusted. Warp anchors each comment to the relevant file and line so the agent understands exactly what to fix. ![Adding an inline comment on a changed line in the Code Review panel.](/_astro/interactive-code-review-adding-comment.ADJXU_OG_Zeyu3O.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ### Batch comments and submit once [Section titled “Batch comments and submit once”](#batch-comments-and-submit-once) Add as many comments as you need before submitting them. The agent receives your entire batch of feedback, applies the changes in one iteration, and returns an updated diff for verification. ![Adding comments directly in the Code Review view.](/_astro/interactive-code-review-batch-comments.CDOsIJLb_Z1mgtz5.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Adding comments directly in the Code Review view. ### Example demo [Section titled “Example demo”](#example-demo) In the example from Kevin on the Warp team, you’ll see how to: * open the Code Review panel after an agent produces changes * browse the diffs for each edited file * add multiple inline comments * review all comments in the list view * send those comments to the agent for resolution * inspect the updated diffs once the agent applies the changes This workflow can be repeated until the code matches your expectations. *** ## Next steps [Section titled “Next steps”](#next-steps) Once you’re comfortable reviewing agent code locally, try running agents in the cloud for longer or parallel tasks. * **[Cloud Agents quickstart](/agent-platform/cloud-agents/quickstart/)** - Run agents on Warp’s infrastructure for background tasks like PR review, issue triage, and dependency updates. * **[Skills](/agent-platform/capabilities/skills/)** - Turn successful agent workflows into reusable, shareable instructions. # Warp Agents overview > Powerful AI features like agents, code review, voice, and active AI recommendations, fully integrated into the Warp Agentic Development Environment. ## AI in Warp [Section titled “AI in Warp”](#ai-in-warp) Warp includes intelligent Oz agents designed to help you build, test, deploy, and debug while keeping you in control. Interactive agent conversations in Warp can look up commands, execute tasks, fix bugs, and adapt to your workflows. You can manage agent behavior directly, with full context from your Warp Drive and your team. Note Warp’s AI features can be globally disabled in **Settings** > **Agents** > **Warp Agent** with the AI toggle.\ \ These features send input data to various LLM providers through their API. Warp is **SOC 2 compliant** and has **Zero Data Retention** policies with all contracted LLM providers — no customer AI data is retained, stored, or used for training. Read more about data privacy for Warp features [on our privacy page](https://www.warp.dev/privacy). Warp’s client is open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE) at [`warpdotdev/warp`](https://github.com/warpdotdev/warp). The agent surface you’re reading about is built in the open — see [Contributing to Warp](/support-and-community/community/contributing/) to read the code, file issues, or shape the roadmap. ## What you can do with agents [Section titled “What you can do with agents”](#what-you-can-do-with-agents) This section covers how to interact with Warp’s agents and the capabilities available during agent conversations: * [Interacting with Agents](/agent-platform/local-agents/interacting-with-agents/) - Manage AI conversations tied to sessions, attach context, continue previous threads, or start new ones. * [Agent Context](/agent-platform/local-agents/agent-context/) - Attach images, URLs, files, code blocks, and selections as context for your prompts. * [Model Choice](/agent-platform/capabilities/model-choice/) - Pick your preferred LLM from a curated set of top models, or let Warp choose the optimal one. * [Full Terminal Use](/agent-platform/capabilities/full-terminal-use/) - Let the agent drive interactive terminal apps, seeing live output and running commands. * [Interactive Code Review](/agent-platform/local-agents/interactive-code-review/) - Review agent-generated diffs, leave inline comments, and have the agent address your feedback. * [Task Lists](/agent-platform/capabilities/task-lists/) - Track complex workflows with automatic task lists that update progress in real time. * [Web Search](/agent-platform/capabilities/web-search/) - Allow agents to search the web for up-to-date information. * [Third-Party CLI Agents](/agent-platform/cli-agents/overview/) - Run third-party CLI agents like Claude Code and Codex with Warp’s built-in agent toolbelt. * [Active AI Recommendations](/agent-platform/local-agents/active-ai/) - Get proactive fix recommendations based on errors and outputs. * [Voice](/agent-platform/local-agents/interacting-with-agents/voice/) - Talk to Warp’s agent using voice commands. For foundational capabilities like planning, rules, MCP servers, and agent profiles, see [Capabilities](/agent-platform/capabilities/). # Agent Session Sharing > Share live agent sessions so collaborators can view, steer, and interact with agent activity from any device — in real time or asynchronously. **Agent Session Sharing** extends Warp’s regular [Session Sharing](/knowledge-and-collaboration/session-sharing/) to include full visibility and control over Agent activity. Share any agent session — Oz or third-party — so collaborators can watch progress, review output, and steer the agent from the Warp desktop app, a web browser, or a mobile device. [Agent Session Sharing in action — sharing a live session and collaborating across devices.](https://www.loom.com/embed/89e0e99c9bbf463a8a5e5bc2e96dabe4) ## Key capabilities [Section titled “Key capabilities”](#key-capabilities) * **Full Agent visibility** - Viewers see Agent prompts, responses, thinking states, tool use, planning steps, and [credit](/support-and-community/plans-and-billing/credits/) consumption in real time * **Cross-device access** - Open shared sessions from the Warp desktop app, any web browser, or a mobile device. No install required for web viewers. * **Collaborative editing** - Grant edit access so collaborators can send their own Agent queries, execute commands, and start new conversations * **Multi-viewer support** - Multiple participants can observe and interact with the same session simultaneously, each with their own cursor and avatar * **Remote Control** - Publish third-party agent sessions to the cloud for persistent, asynchronous monitoring and steering from anywhere. See [Remote Control](/agent-platform/cli-agents/remote-control/). ## How it works [Section titled “How it works”](#how-it-works) When you share an agent session, Warp publishes it to the cloud and generates a shareable link. The session stays in sync — any new agent output or terminal activity appears for all viewers in real time. The person who shares the session controls who can view and who can interact. ## Sharing a session [Section titled “Sharing a session”](#sharing-a-session) 1. Start or open an agent session in Warp. The agent can be an Oz agent, a third-party coding agent, or any interactive agent running in your terminal. 2. Open the share action from any of these entry points: * **Command Palette** - Search for “Share session” * **Pane header** - Click the overflow menu in the pane header * **Right-click context menu** - Right-click inside the session pane * **`/remote-control` chip** - For third-party agent sessions, click the `/remote-control` chip in the agent view footer or the CLI footer to publish and share instantly. See [Remote Control](/agent-platform/cli-agents/remote-control/) for details. 3. Choose your starting point (full scrollback, no scrollback, or a specific block). 4. Confirm the share. Warp uploads the session to the cloud and generates a shareable link. 5. Copy the link and share it with teammates, or open it on another device. ![Starting a shared agent session from the right-click context menu](/_astro/agent-session-sharing-right-click-menu.CDWYY3rB_227V8B.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Start a shared session via the right click menu. ![Starting a shared agent session from the Command Palette](/_astro/agent-session-sharing-command-palette.Cb5ExP7J_Z18ptUN.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Start a shared session via the Command Palette. ## Viewing shared sessions [Section titled “Viewing shared sessions”](#viewing-shared-sessions) Shared sessions are accessible from: * **Warp desktop app** - Paste the link into Warp on a different machine for the full desktop experience * **Web browser** - Open the shared link in any browser. No app install required. * **Mobile** - Open the link on a phone or tablet browser to check on progress while away from your desk The web experience mirrors the desktop view, showing complete Agent activity including thinking steps, tool use, and terminal output. ## Collaboration and steering [Section titled “Collaboration and steering”](#collaboration-and-steering) ### Watching Agent activity [Section titled “Watching Agent activity”](#watching-agent-activity) Viewers see Agent actions unfold live as the sharer interacts with the Agent: * **Thinking animations** - Real-time indicators of Agent reasoning * **Tool use and planning** - Visible tool calls and planning steps * **Credit consumption** - Live credit usage for the session * **Final responses** - Completed Agent output ### Edit access [Section titled “Edit access”](#edit-access) If a viewer requests edit access, the sharer can approve it. Once approved, collaborators can: * Send new Agent queries * Type directly into the prompt * Execute commands * Start and switch Agent conversations * Run terminal commands alongside Agent queries ### Multi-viewer sessions [Section titled “Multi-viewer sessions”](#multi-viewer-sessions) Multiple participants can join the same session from different machines, browsers, or environments. All participants: * See each other’s avatars and cursors * Watch Agent activity in sync * Edit together when granted access * Run terminal or Agent commands concurrently ## Related pages [Section titled “Related pages”](#related-pages) * [Remote Control](/agent-platform/cli-agents/remote-control/) * [Third-Party CLI Agents](/agent-platform/cli-agents/overview/) * [Cloud Agent Session Sharing](/agent-platform/cloud-agents/viewing-cloud-agent-runs/) * [Session Sharing (terminal)](/knowledge-and-collaboration/session-sharing/) # Changelog > Warp ships weekly updates, typically on Thursdays. Submit bugs and feature requests on our [GitHub board!](https://github.com/warpdotdev/Warp/issues/new/choose) * [**2026**](/changelog/2026/) * [**2025**](/changelog/2025/) * [**2024**](/changelog/2024/) * [**2023**](/changelog/2023/) * [**2022**](/changelog/2022/) * [**2021**](/changelog/2021/) # Changelog — 2021 > Warp release notes for 2021. Updates ship weekly, typically on Thursdays. Submit bugs and feature requests on our [GitHub board!](https://github.com/warpdotdev/Warp/issues/new/choose) ### 2021.12.29 (v0.2021.12.27.09.04) [Section titled “2021.12.29 (v0.2021.12.27.09.04)”](#20211229-v0202112270904) **New features** * Find in block (+ other find improvements) ### 2021.12.22 (v0.2021.12.20.09.04) [Section titled “2021.12.22 (v0.2021.12.20.09.04)”](#20211222-v0202112200904) **New features** * Windows, tabs, and panes are restored whenever you reopen Warp. Restoring block content is on its way! * Warp now supports completions for over 300 commands and more information about existing commands by using Fig’s completion specs * Git aliases are now included in completions menu - [210](https://github.com/warpdotdev/warp/issues/210) * Switch to next pane and previous pane with CMD-\[ and CMD-] - [392](https://github.com/warpdotdev/warp/issues/392) * Scrolling the Block list with PG-UP and PG-DOWN - [370](https://github.com/warpdotdev/warp/issues/370) * Copy and paste the file directory into Warp from Finder - [514](https://github.com/warpdotdev/warp/issues/514) * When the last Block is selected, can re-focus the input editor using CMD-DOWN key * Arrow down scrolls to bottom of last block **Bug fixes** * Copying selected text to clipboard creates a new entry for each selected character - [504](https://github.com/warpdotdev/warp/issues/504) * Needed an extra backspace to escape CTRL-R / history menu - [427](https://github.com/warpdotdev/warp/issues/427) * VIM performance improvements - we’ve made progress but would love more sample cases of slowness **Updates to Mac Menu Bar (Window)** * Zoom * Minimize * Tile Window to Left of Screen (Default) * Tile Window to Right of Screen (Default) * Move to X screen (Default) * Enter Full Screen (Default) * Bring All to Front ### 2021.12.15 (v0.2021.12.13.08.40) [Section titled “2021.12.15 (v0.2021.12.13.08.40)”](#20211215-v0202112130840) **New features** * Fuzzy search in CTRL-R and Command Palette * When you share a link to a block, up to 5 recipients may now download Warp’s beta via the link **Bug fixes** * Fix bug where opening file:// urls would not include query params like ‘?foo=bar’ - [426](https://github.com/warpdotdev/warp/issues/426) * More prominent highlights in CTRL-R, Command Palette, tab completion * Vim bug fixes and performance improvements - please let us know what else you see ### 2021.12.08 (v0.2021.12.06.19.09) [Section titled “2021.12.08 (v0.2021.12.06.19.09)”](#20211208-v0202112061909) **New features** * Added a send invite button in account section of the settings dialog * You can now request more invites in the invite modal **Bug fixes** * Copy on select persistence bug * UI Bug when trying to un-share a block - [439](https://github.com/warpdotdev/warp/issues/439) ### 2021.12.01 (v0.2021.11.29.18.59) [Section titled “2021.12.01 (v0.2021.11.29.18.59)”](#20211201-v0202111291859) **New features** * Added 15 extra invites for everyone! * Copy on select (highlighting text will automatically copy to clipboard). This can be turned off in the settings dialog - [077](https://github.com/warpdotdev/warp/issues/077) * CTRL-L shortcut to clear the screen - [049](https://github.com/warpdotdev/warp/issues/049) **Bug fixes** * Can now highlight and copy sections of a URL without it automatically opening - [138](https://github.com/warpdotdev/warp/issues/138) ### 2021.11.24 (v0.2021.11.23.17.55) [Section titled “2021.11.24 (v0.2021.11.23.17.55)”](#20211124-v0202111231755) **New features** * Background images + gradients in themes: You can now set a background image or gradient as your theme background. Warp ships with a few of these already or you can create your own via a yaml file. - [032](https://github.com/warpdotdev/warp/issues/032) * Changelog dialog * Emoji rendering: 😂, 😃, 🌍, 🍞, 🚗, 📞, 🎉, ❤️ - [075](https://github.com/warpdotdev/warp/issues/075) * Improved settings dialog * Theme search - [237](https://github.com/warpdotdev/warp/issues/237) **Bug fixes** * Properly escapes whitespace when you drag and drop files ### 2021.11.17 (v0.2021.11.16.20.05) [Section titled “2021.11.17 (v0.2021.11.16.20.05)”](#20211117-v0202111162005) **New features** * Drag and drop files & directories from finder - [069](https://github.com/warpdotdev/warp/issues/069) ### 2021.11.10 (v0.2021.11.09.19.46) [Section titled “2021.11.10 (v0.2021.11.09.19.46)”](#20211110-v0202111091946) **New features** * Autosuggestions: Warp now suggests commands as you type, similar to Fish or Gmail - [052](https://github.com/warpdotdev/warp/issues/052) * Button to copy the app/version - [106](https://github.com/warpdotdev/warp/issues/106) * Conda context to the prompt - [235](https://github.com/warpdotdev/warp/issues/235) **Bug fixes** * Conda info (prompt) locking input editor * CTRL-D now deletes forward one character * History now preserved across sessions - [337](https://github.com/warpdotdev/warp/issues/337) * Enter (numpad) was inputting as CTRL-C - [330](https://github.com/warpdotdev/warp/issues/330) ### 2021.11.03 (v0.2021.11.02.00.38) [Section titled “2021.11.03 (v0.2021.11.02.00.38)”](#20211103-v0202111020038) **New features** * CJK (Chinese, Japanese, and Korean) character support - [327](https://github.com/warpdotdev/warp/issues/327) * Autocompletions for missing tar commands * Enforcement of minimum contrasts in grid - [249](https://github.com/warpdotdev/warp/issues/249) **Bug fixes** * Runaway memory usage (from font loading on initial run) - [232](https://github.com/warpdotdev/warp/issues/232) * Directories with non-english filenames not rendering on screen - [309](https://github.com/warpdotdev/warp/issues/309) * App crashes from missing current working directory * Pure Prompt being inserted as a typehead into editor - [242](https://github.com/warpdotdev/warp/issues/242) ### 2021.10.27 (v0.2021.10.25.22.47) [Section titled “2021.10.27 (v0.2021.10.25.22.47)”](#20211027-v0202110252247) **New features** * Ability to unshare blocks in settings modal * Link to the documentation in kebab menu (three dots in top right corner) **Bug fixes** * Double character entry after input editor loses focus ### 2021.10.20 (v0.2021.10.19.21.38) [Section titled “2021.10.20 (v0.2021.10.19.21.38)”](#20211020-v0202110192138) **New features** * Switch theme based on OS appearance - [068](https://github.com/warpdotdev/warp/issues/068) * Toggles instead of buttons in the setttings! * Link to Custom themes documentation in the settings **Bug fixes** * IME support (non-English keyboards are now better supported in input box!) * Show a banner instead of a popup when app startup takes longer than expected * git log (and similar commands) no longer treated as a failed block ### 2021.10.13 (v0.2021.10.12.19.34) [Section titled “2021.10.13 (v0.2021.10.12.19.34)”](#20211013-v0202110121934) **Bug fixes** * Shell Bootstrapping should be a lot faster * Support 3-char color representation for hex colors in theme * Fix crashes relating to reading history files * Prevent block completion from stealing focus * Fix broken click handling for showing and hiding overflow menu ### 2021.10.06 (v0.2021.10.05.20.07) [Section titled “2021.10.06 (v0.2021.10.05.20.07)”](#20211006-v0202110052007) **Bug fixes** * Split pane navigation when ‘Left / Right Option is Meta’ settings are enabled * Crash when opening a new window ### 2021.09.29 (v0.2021.09.29.13.26) [Section titled “2021.09.29 (v0.2021.09.29.13.26)”](#20210929-v0202109291326) **New features** * Split panes: create multiple panes in the same tab via shortcuts (CMD-E/SHIFT-CMD-E), the Command Palette, or by right clicking in any pane. * Custom themes via files. You can now define your own theme as a yaml file in \~/.warp/themes. For more information on the file format and to see \~100 of the most popular themes already implemented in this format, see . The ability to add and share themes directly within Warp is coming soon! **Bug fixes** * Add better messaging when Warp does not have permission to autoupdate * Crash if a tab completion result was accepted after the cursor was moved to the beginning of the editor ### 2021.09.22 (v0.2021.09.21.20.54) [Section titled “2021.09.22 (v0.2021.09.21.20.54)”](#20210922-v0202109212054) **New features** * Theme picker available from the Command Palette **Bug fixes** * Occasional crash when opening a new Warp window * Font selection dropdown didn’t respect theme choice * Issues with padding and hover detection when toggling Compact Mode on or off ### 2021.09.15 (v0.2021.09.14.21.25) [Section titled “2021.09.15 (v0.2021.09.14.21.25)”](#20210915-v0202109142125) **Bug fixes** * Crash when closing full-screen window * Executables in path were not appearing for completions in Bash * Completions menu overlaps theme picker ### 2021.09.09 (v0.2021.09.09.0.0) [Section titled “2021.09.09 (v0.2021.09.09.0.0)”](#20210909-v02021090900) **New features** * New themes for Warp!!! (Access them via Settings on the overflow menu. We have Dracula, Solarized, & Gruvbox) * CMD-, opens the Settings menu **Bug fixes** * Fixed crash when we fail to load a font or when we scroll through fonts * Fixed visual artifacts around windows and modals jumping * Fixed crash that occurs when you CMD-F while selecting an already selected text ### 2021.08.31 (v0.2021.08.31.0.0) [Section titled “2021.08.31 (v0.2021.08.31.0.0)”](#20210831-v02021083100) **New features** * Support emacs bindings in input box * History up menu performs a prefix search based on input **Bug fixes** * Warp not rendering after executing long-running command * Stop powerlevel10k instant prompt from hanging on bootstrap * Changing “font-size” via CTRL— and CTRL-0 should stay in sync with font size in settings menu * Bracketed paste mode bug: 0\~ \~1 on every command when ssh-ing * Crash when tab completing with multibyte characters * Download page doesn’t render correctly on safari * Login is broken for some users using Chrome * Make it more prominent in onboarding that we are collecting telemetry during the beta ### 2021.08.25 (v0.2021.08.25.0.0) [Section titled “2021.08.25 (v0.2021.08.25.0.0)”](#20210825-v02021082500) **New features** * Custom fonts * Completions for aliases and environment variables **Bug fixes** * Completions loose ends, including completions for path names with spaces and if commands are separated by && * Function key support within running programs (such as htop) * Editor text respects zoom level * Regression that caused URLs to not be highlighted * Opening a new window required Internet connection ### 2021.08.18 (v0.2021.08.18.0.0) [Section titled “2021.08.18 (v0.2021.08.18.0.0)”](#20210818-v02021081800) **New features** * Re-run with sudo **Bug fixes** * Crash caused by pressing CMD-K * Completion not working when cursor is mid-line * Re-input of multi-line commands * [084](https://github.com/warpdotdev/warp/issues/084) - Rendering of colors correctly in diffs * Selection showing after closing and re-opening alt-screen ### 2021.08.09 (v0.2021.08.09.0.0) [Section titled “2021.08.09 (v0.2021.08.09.0.0)”](#20210809-v02021080900) **New features** * New settings modal (accessible from the top right overflow button) to set font size, toggle between light mode and dark mode, compact mode and normal mode * CTRL-U and CTRL-K now cut to clipboard * Typeahead: characters you type in a long-running command will now show up in the input box when the command completes **Bug fixes** * Handle arrow keys with modifiers (option and command) in CLIs and full-screen apps (Previously, users were unable to navigate with option and command keys in - Postgres CLI) * Straightening the text baseline * Translucent colors (e.g. for diff-so-fancy) are now correct (We now support the full range of opacity) * Dotfile path completions + Completions improvements for more commands * Artifacts when rendering svgs, especially on low res monitors. Overflow menu looks a lot better now! ### 2021.07.28 (v0.2021.07.28.0.0) [Section titled “2021.07.28 (v0.2021.07.28.0.0)”](#20210728-v02021072800) **New features** * Compact Mode (see GIF below) * Support for mouse events in Vim and other programs that can handle mouse input * Completions for npm / yarn scripts **Bug fixes** * Major improvements to the consistency of completions, especially for commands that can take multiple arguments (e.g. rm -rf) * Proper path completions for absolute paths * Hang when PROMPT\_COMMAND is set for the shell * Context Menu not closing when clicking outside of the menu * Crashes after executing multi-line commands and on older versions of macOS ### 2021.07.21 (v0.2021.07.21.0.0) [Section titled “2021.07.21 (v0.2021.07.21.0.0)”](#20210721-v02021072100) **New features** * Support for numpad ENTER * More npm & yarn completions **Bug fixes** * Down arrow sends unrecognized escape sequence to Github CLI * Can’t use UP arrow if item in history is multiple lines * Crash when closing a tab when there are multiple tabs * File-only completion signatures should also show directories ### 2021.07.13 (v0.2021.07.13.0.0) [Section titled “2021.07.13 (v0.2021.07.13.0.0)”](#20210713-v02021071300) **New features** * New invite system to add users to Warp. To invite new users, click the overflow menu at the top right and click ‘invite users’. For now we ask that you please don’t post these invites on social media! * URLs in the terminal screen are auto-linkified * Double clicking the title bar maximizes/minimizes the window **Bug fixes** * Various Command Palette bugs * Find box is populated with the user’s text selection * 3 second latency when changing the prompt upon first SSHing ### 2021.07.07 (v0.2021.07.07.0.0) [Section titled “2021.07.07 (v0.2021.07.07.0.0)”](#20210707-v02021070700) **New features** * Command Palette for most keyboard shortcuts (CMD-P) * Previously, tab completion descriptions were cut off. Now we display them in a floating box * You can now switch tabs using CTRL-TAB and CTRL-SHIFT-TAB **Bug fixes** * Intermittent crashes with Zsh sessions and switching tabs * Always fall back to path suggestions for completions * Various bugs related to completions ### 2021.06.29 (v0.2021.06.29.0.0) [Section titled “2021.06.29 (v0.2021.06.29.0.0)”](#20210629-v02021062900) **New features** * Multiple window support * New completions UI and in-line documentation for commands and flags * Horizontal scrolling of input box to support long commands **Bug fixes** * Crash when exiting from logout or exit when there’s a background process * Crash when bootstrapping from detecting incorrect shell name * Various bugs related to completions ### 2021.06.15 (v0.2021.06.15.19.04) [Section titled “2021.06.15 (v0.2021.06.15.19.04)”](#20210615-v0202106151904) **New features** * Mac File and Edit menus, along with Mac standard menu items (although New Window not yet working) **Bug fixes** * Crash when closing last window * CMD-F: when there are no matches, display 0/0 * CMD-F should not scroll away if navigating to a match on the same row * CMD-F: render the yellow rectangle at the layer of rendering the cell * Unable to move cursor upwards on multi-line previous command * Warp bootstrap commands showing up in history over ssh * Accept input via input box before terminal has bootstrapped * New tab button should have hover and click state * Output stops midway through session on iMac running Mojave 10.14.6 * Backspace doesn’t work while holding shift * Clipping issue in share dialog * Input suggestions closes if you click on the scrollbar * Hitting up/down while input suggestions are open causes menu to move * Paste is not working for full screen apps * Underline does not render with Hack font ### 2021.06.09 (v0.2021.06.09.15.14) [Section titled “2021.06.09 (v0.2021.06.09.15.14)”](#20210609-v0202106091514) **New features** * SSH support (Warp now works the same when you SSH as it does locally!) * Improved completions: we’ve built out new completions support that are snappier and have more intelligent suggestions for options and arguments for some of the most used commands * Find: Pressing CMD-F now brings up a find view to search for text in the terminal **Bug fixes** * Text rendering was faded on certain monitors # Changelog — 2022 > Warp release notes for 2022. Updates ship weekly, typically on Thursdays. Submit bugs and feature requests on our [GitHub board!](https://github.com/warpdotdev/Warp/issues/new/choose) ### 2022.12.15 (v0.2022.12.13.08.04) [Section titled “2022.12.15 (v0.2022.12.13.08.04)”](#20221215-v0202212130804) **New features** * You can now reorder and drag tabs around with your mouse! **Bug fixes** * The welcome Block now also works when using Fish shell. * AI Command Search no longer crashes from multi-byte characters when opened via the `#` prefix * Warp no longer crashes when starting a new session in a deleted or inaccessible directory * Resolved rendering bugs and hangs in full-screen applications like ‘k9s’ and ‘less’. * Added a login failure notification. ### 2022.12.06 (v0.2022.12.06.08.03) [Section titled “2022.12.06 (v0.2022.12.06.08.03)”](#20221206-v0202212060803) **New features** * Users may now opt out of telemetry (app analytics and crash reporting) * Added ‘Tail Warp network log’ workflow for viewing logs of all app network activity. **Bug fixes** * Full-screen CLI commands like mitmproxy now correctly span the entire view. * Improved styling and organization of Features page in settings. * Completions While Typing menu closes while generating new results. * Added a hidden completion result for root dir. * Warp now consumes less memory when a session has many blocks. * Fixed an issue over SSH where logs were being inserted into input. ### 2022.12.02 (v0.2022.11.29.08.03) [Section titled “2022.12.02 (v0.2022.11.29.08.03)”](#20221202-v0202211290803) **New features** * Users may now opt out of telemetry (app analytics and crash reporting) * Added ‘Tail Warp network log’ workflow for viewing logs of all app network activity. **Bug fixes** * Mitigated an issue where running a command over SSH would emit spurious output (specifically, ‘channel: open failed’ statements) in a block. ### 2022.12.01 (v0.2022.11.29.08.03) [Section titled “2022.12.01 (v0.2022.11.29.08.03)”](#20221201-v0202211290803) **New features** * Warp now supports using the find bar within the alt-screen! `CMD-F` now opens find within vim, less, and other alt-screen apps! **Bug fixes** * Respect symlinks in Warp configuration directories (for themes and workflows). * Fixed unwanted text appearing in the Input Editor when RPROMPT is set * Fixed the emoji composer not working properly. * Fixed a crash that could occur when using the Unicode Hex Input keyboard. * Fixed escape binding not closing the resource center * Move Backward/Forward One Word bindings can now be overridden. * Fixed crash when hovering over multiple byte text within the Input Editor * Fixed “command not found: sed” and “command not found: tr” issues with the SSH wrapper. * Fixed issue where tab completions and command search could be visible at the same time. ### 2022.11.15 (v0.2022.11.14.14.55) [Section titled “2022.11.15 (v0.2022.11.14.14.55)”](#20221115-v0202211141455) **New features** * Command Search: Ctrl-R opens a panel where you can search your history, workflows, and other command execution-related items, all in one place. * Sticky command header: Warp now pins the prompt/command section of a Block to the top of the screen; click it to scroll to the top of the Block. Can be toggled via Settings > Features > Show Sticky Command Header * Warp’s Input Editor now supports soft wrapping; long commands are now fully visible! **Bug fixes** * Warp now sets the TERM\_PROGRAM environment variable correctly in wrapped SSH sessions. ### 2022.11.10 (v0.2022.11.08.08.07) [Section titled “2022.11.10 (v0.2022.11.08.08.07)”](#20221110-v0202211080807) **New features** * Warp now offers Command Corrections! Warp will suggest corrections for errors in previous console commands * Warp now also detects invalid file paths — they are underlined red when error underlining is enabled * Added a toggle in `Settings > Appearance` to configure whether and how Warp enforces minimum contrast **Bug fixes** * Fixed an issue where toggling the default prompt would not update it immediately * Improved positioning of the `TAB` completions menu when using split panes ### 2022.11.03 (v0.2022.11.01.08.03) [Section titled “2022.11.03 (v0.2022.11.01.08.03)”](#20221103-v0202211010803) **New features** * Warp’s prompt now shows the number of modified files on your local git branch! Search “changed file count” in the Command Palette or right-click the Prompt to toggle. **Bug fixes** * Dim-styled colors are now restored properly. ### 2022.10.27 (v0.2022.10.25.08.06) [Section titled “2022.10.27 (v0.2022.10.25.08.06)”](#20221027-v0202210250806) **Bug fixes** * Fixed a bug when hovering over hover icons ### 2022.10.20 (v0.2022.10.18.08.10) [Section titled “2022.10.20 (v0.2022.10.18.08.10)”](#20221020-v0202210180810) **Bug fixes** * Modifying the mouse and scroll reporting settings now applies immediately * Fixed cursor not blinking when starting a shell instance * Fixed temporarily flashing the wrong prompt while Warp is still bootstrapping * Removed duplicate entry for toggling error underlining and syntax highlighting within the Command Palette ### 2022.10.13 (v0.2022.10.11.08.13) [Section titled “2022.10.13 (v0.2022.10.11.08.13)”](#20221013-v0202210110813) **New features** * Warp’s Input Editor now has Syntax Highlighting and Error Underlining, with no configuration! * Warp now uses a pointer cursor when hovering over links **Bug fixes** * Git branches in the completions menu now bold correctly * Warp no longer crashes when `/bin/bash` is missing ### 2022.10.06 (v0.2022.10.04.08.05) [Section titled “2022.10.06 (v0.2022.10.04.08.05)”](#20221006-v0202210040805) **New features** * Drag and drop a folder or file onto the Warp dock icon to open a new tab in this directory * Added dividers between Blocks in compact mode * Shell keywords are now supported for completions and Command Inspector **Bug fixes** * Accessibility support for context menu keybinding * Keystrokes typed while a command is still executing no longer gets dropped * Link recognition no longer includes trailing quotes * Find search results will continue to be highlighted after clearing the screen during a long running command * Fixed completions for commands prefixed with environment variables * Warp’s resource center is now center aligned ### 2022.09.29 (v0.2022.09.27.08.11) [Section titled “2022.09.29 (v0.2022.09.27.08.11)”](#20220929-v0202209270811) **New features** * Extend the currently selected text (within Blocks) with `SHIFT-LEFT`, `SHIFT-RIGHT`, `SHIFT-UP`, and `SHIFT-DOWN` * Double-click and drag to select text in the Input Editor * Insert the last word of the previous command with `META-.` * Added a toggle to enable mouse and scroll reporting to the settings dialog (`Settings > Features`) **Bug fixes** * The `clear` command no longer appears in the snackbar at the top of the window * Warp’s completions now support executables in remote sessions (no longer just bash) * Fixed subcommand completions for commands with proper prefixes of each other (e.g. `npm r` and `npm run`) * The completion spec for `lsd` now supports files ### 2022.09.22 (v0.2022.09.20.08.08) [Section titled “2022.09.22 (v0.2022.09.20.08.08)”](#20220922-v0202209200808) **New features** * After selecting a Block press `CTRL-M` to open its context menu * Commands in the tab completions menu and history menu can now be executed directly with `CMD-ENTER` * Completions now support shell builtins, git aliases, and also npm aliases **Bug fixes** * Command Palette now includes the most useful features at the top * Improved flag completions for cargo ### 2022.09.15 (v0.2022.09.13.08.15) [Section titled “2022.09.15 (v0.2022.09.13.08.15)”](#20220915-v0202209130815) **New features** * Warp Resource Center - explore Warp features and documentation by clicking the `?` icon or pressing `SHIFT-CTRL-?` * New icons in the completion menu denoting flags, folders, branches, etc. **Bug fixes** * Press `CMD-ENTER` within the history menu (`CTRL-R`) to directly execute the highlighted command * Fixed crash when opening many tabs (due to macOS’s default open file descriptor limits) * Fixed crash when laying out RTL text ### 2022.09.08 (v0.2022.09.07.14.56) [Section titled “2022.09.08 (v0.2022.09.07.14.56)”](#20220908-v0202209071456) **New features** * Global hotkey window can now float above full-screen apps * Tabs can now have their color customized (via right-clicking on a tab) * Terminal line height is now configurable (via Settings > Appearance) ### 2022.09.01 (v0.2022.08.31.18.11) [Section titled “2022.09.01 (v0.2022.08.31.18.11)”](#20220901-v0202208311811) **New features** * Tab completions now support fuzzy string matching * Improve completions for over 450 commands, including docker, kubernetes, cargo, node, and git **Bug fixes** * Properly send C0 control codes for \ keystrokes * Session restoration now also persists bold, underline, italic, and strikethrough formatting * Inspect mode now works for the changelog modal * Fixed a crash when highlighting a link * Fixed Find occasionally returning only partial results * Fixed occasional crash when loading images * Fixed display issue in the Mac Menu for keyboard shortcuts with special keys ### 2022.08.25 (v0.2022.08.23.08.06) [Section titled “2022.08.25 (v0.2022.08.23.08.06)”](#20220825-v0202208230806) **New features** * Experimental feature: support for always-on completions — the completions menu can now open automatically while typing (enable via Settings -> Features) **Bug fixes** * Custom tab titles no longer get overwritten when using multiple panes * A Block’s execution duration is now formatted in hours, minutes, and seconds * Improved rendering of the ‘Current session’ text in the Navigation Palette * Warp properly hides the cursor when a CLI sends the respective escape sequence * Warp stays focused (keyboard-interactive) after closing the Share Block menu and the context menu * Warp no longer lags when the Ctrl-R menu is opened * Confirming a tab suggestion appends a space to the buffer ### 2022.08.18 (v0.2022.08.16.10.16) [Section titled “2022.08.18 (v0.2022.08.16.10.16)”](#20220818-v0202208161016) **New features** * Launch Configurations - Save a configuration of windows, tabs, and panes to open later with `CTRL-CMD-L` * Session Navigation - Navigate to any session in Warp with `SHIFT-CMD-P` * Added exclusive theme for users who joined Warp through a referral **Bug fixes** * Prompt now shows Git SHA instead of HEAD when you’re not on a branch * Filepath completions now include current directory (’.’) and parent directory (’..’) * Support `SHIFT-HOME` and `SHIFT-END` keybindings to select text to line start and end. * Items in the Command Palette now highlight when you hover over them with your mouse * Improved how Warp cleans up the warptmp directory for Zsh SSH sessions * Already open dropdown menus are now properly closed when clicked * Warp no longer crashes when dragging a window that’s running htop * Warp no longer crashes when the find bar is open ### 2022.08.10 (v0.2022.08.08.09.21) [Section titled “2022.08.10 (v0.2022.08.08.09.21)”](#20220810-v0202208080921) **New features** * Can now Middle-click a tab to close it * Added additional tab reordering options (Close: tab, other tabs, and tabs to the right) via the Mac Menu, the Command Palette, and a tab’s context menu (right click) **Bug fixes** * Added a toggle to the Mac Menu for maximizing panes * Can now switch panes using keyboard shortcuts even when a pane is maximized * Add support for opening file paths with RubyMine, PhpStorm, and WebStorm * Fixed crash when highlighting links * Fixed issue where the HISTCONTROL environment variable was ignored in bash * Pressing `CTRL-R` to open history search no longer crashes Warp when you have multiple cursors ### 2022.08.03 (v0.2022.08.01.09.12) [Section titled “2022.08.03 (v0.2022.08.01.09.12)”](#20220803-v0202208010912) **New features** * Updated Mac menus to make Warp actions more discoverable - [101](https://github.com/warpdotdev/warp/issues/101) * Warp now supports opening file links and urls via CMD-CLICK! - [177](https://github.com/warpdotdev/warp/issues/177) **Bug fixes** * Various CLI tools no longer hang e.g. Bazel and Maven * Command Inspector hover no longer crashes with UTF-8 encoded strings * Opening the find / search bar (`CMD-F`) now automatically selects the text * Tab titles are no longer reset when changing panes ### 2022.07.27 (v0.2022.07.25.09.05) [Section titled “2022.07.27 (v0.2022.07.25.09.05)”](#20220727-v0202207250905) **Bug fixes** * Closing and re-opening the Command Palette now resets the selected item * The cursor’s position is now restored after exiting the Command History Search (`CTRL-R`) menu. * Shorthand and longhand flags are now correctly surfaced (based on the number of dashes) in tab completions * Added voiceover support for `BACKSPACE` and `DELETE` keystrokes within the Input Editor ### 2022.07.20 (v0.2022.07.18.09.06) [Section titled “2022.07.20 (v0.2022.07.18.09.06)”](#20220720-v0202207180906) **New features** * Command Inspector - hover over any piece of a command in Warp’s Input Editor to surface documentation or press `CMD+I` to inspect at the cursor’s current location * Improved ordering in the tab completions menu **Bug fixes** * Font color for links in light mode (themes) now set correctly * Moving forward by a word no longer moves farther than expected * Warp no longer hangs when passing an invalid file path * Fixed issues with persisting the selected theme when “Sync with OS” is enabled and the theme picker is launched from the Command Palette (or a keyboard shortcut) * Fixed issues with text input after clearing Blocks (`CMD-K`) while in a REPL environment. * Fixed shortcut for select-left-by-word (`SHIFT-CMD-B`), select-right-by-word (`SHIFT-CMD-F`), select-line-to-end (`SHIFT-CTRL-E`), and select-line-to-start (`SHIFT-CTRL-A`) ### 2022.07.13 (v0.2022.07.11.09.11) [Section titled “2022.07.13 (v0.2022.07.11.09.11)”](#20220713-v0202207110911) **Bug fixes** * Improved startup time for Fish shells * Find Bar no longer crashes on selected text * Scrollbar now supports jumping to where you click * Fixed a bug with the referral link for sharing Warp not loading ### 2022.07.07 (v0.2022.07.04.09.08) [Section titled “2022.07.07 (v0.2022.07.04.09.08)”](#20220707-v0202207040908) **New features** * Bookmark a Block (or multiple) for quick access via the scroll-bar * Added a referral counter to the Settings > Account screen and the referral screen * Added support for rendering text with a lower visual weight; enable the thin strokes option in Settings > Appearance (enabled by default for low-DPI displays) * Togglable settings, overflow menu items, and settings pages are now accessible through the Command Palette * CLI options are now surfaced by default without needing to type ’-’ * Press SHIFT-CMD-C while in VSCode (Visual Studio Code) to open a new Warp session **Bug fixes** * Fixed referral links and share by email * Fixed a hang that would sometimes occur when connecting with SSH * Now support requesting media permissions (camera, audio, etc) * Correctly parse Git commit SHAs in completion menus * Improved tab completion support for command line arguments that are behind flags ### 2022.07.06 (v0.2022.07.04.09.08) [Section titled “2022.07.06 (v0.2022.07.04.09.08)”](#20220706-v0202207040908) **New features** * Bookmark a Block (or multiple) for quick access via the scroll-bar * Added a referral counter to the Settings > Account screen and the referral screen * Added support for rendering text with a lower visual weight; enable the thin strokes option in Settings > Appearance (enabled by default for low-DPI displays) * Togglable settings, overflow menu items, and settings pages are now accessible through the Command Palette * CLI options are now surfaced by default without needing to type ’-’ * Press SHIFT-CMD-C while in VSCode (Visual Studio Code) to open a new Warp session **Bug fixes** * Fixed a hang that would sometimes occur when connecting with SSH * Now support requesting media permissions (camera, audio, etc) * Correctly parse Git commit SHAs in completion menus * Improved tab completion support for command line arguments that are behind flags ### 2022.06.29 (v0.2022.06.27.09.14) [Section titled “2022.06.29 (v0.2022.06.27.09.14)”](#20220629-v0202206270914) **Bug fixes** * Cursor changes when hovering over clickable UI elements and the Input Editor * Dim colors now render correctly ### 2022.06.27 (v0.2022.06.20.09.15) [Section titled “2022.06.27 (v0.2022.06.20.09.15)”](#20220627-v0202206200915) **New features** * Improved auto-focus behavior when closing panes by keeping track of history when navigating or clicking around panes * Performance improvements when executing Blocks: Warp no longer flashes on every command! **Bug fixes** * Input Editor re-focuses after renaming a tab * Reduced visual weight of the active tab title to improve legibility. * Improved blending along the inside edge of rounded corners * Global Hotkey Windows (Quake Mode) now correctly respect the active screen setting * Completions for flag arguments now support absolute and relative file paths (when applicable) * Git checkout <`TAB`> now also completes branches with the remote prefixed. * Pressing Arrow-up (`UP`) when the Input Editor is non-empty opens the command history with prefix filtering * Button to copy app version moved to main settings page ### 2022.06.22 (v0.2022.06.20.09.15) [Section titled “2022.06.22 (v0.2022.06.20.09.15)”](#20220622-v0202206200915) **New features** * Improved auto-focus behavior when closing panes by keeping track of history when navigating or clicking around panes * Performance improvements when executing Blocks: Warp no longer flashes on every command! **Bug fixes** * Input Editor re-focuses after renaming a tab * Reduced visual weight of the active tab title to improve legibility. * Improved blending along the inside edge of rounded corners * Global Hotkey Windows (Quake Mode) now correctly respect the active screen setting * Completions for flag arguments now support absolute and relative file paths (when applicable) * Git checkout <`TAB`> now also completes branches with the remote prefixed. * Pressing Arrow-up (`UP`) when the Input Editor is non-empty opens the command history with prefix filtering * Button to copy app version moved to main settings page ### 2022.06.17 (v0.2022.06.13.09.15) [Section titled “2022.06.17 (v0.2022.06.13.09.15)”](#20220617-v0202206130915) **New features** * Added keyboard shortcuts to reorder tabs (CTRL-SHIFT-LEFT and CTRL-SHIFT-RIGHT) **Bug fixes** * Warp no longer crashes on macOS 13 (Ventura) * Global Hotkey Window (Quake Mode) no longer overlaps Spotlight, Raycast, Alfred, and the macOS Dock * Now correctly display the user and hostname in the Prompt after exiting an SSH session * Fixed a memory leak on window close. ### 2022.06.15 (v0.2022.06.13.09.15) [Section titled “2022.06.15 (v0.2022.06.13.09.15)”](#20220615-v0202206130915) **New features** * Added keyboard shortcuts to reorder tabs (CTRL-SHIFT-LEFT and CTRL-SHIFT-RIGHT) **Bug fixes** * Global Hotkey Window (Quake Mode) no longer overlaps Spotlight, Raycast, Alfred, and the Mac Dock * Now correctly display the user and hostname in the Prompt after exiting an SSH session * Fixed a memory leak on window close. ### 2022.06.08 (v0.2022.06.06.09.05) [Section titled “2022.06.08 (v0.2022.06.06.09.05)”](#20220608-v0202206060905) **New features** * Now support renaming tabs (right click on your tab title!) * Now support enabling custom prompt from prompt context menu (right-click on prompt) * Now support splitting panes (left and right) from the context menu (right click) and through the Command Palette * Now support CTRL-Click as an alternative to right-clicking **Bug fixes** * Improved completions support for arguments nested under options (e.g. git branch -D \) * Modified files are now included (in addition to commit SHAs) for `git diff` ### 2022.06.01 (v0.2022.05.30.09.10) [Section titled “2022.06.01 (v0.2022.05.30.09.10)”](#20220601-v0202205300910) **New features** * Added information about rewards to the referral screen * Added a button that toggles regex search in the Find Bar * Added completion support for shell functions **Bug fixes** * Hotfix - a regression that caused Warp to stall when using nano * Improved kerning (font rendering) throughout the app * Added a hyperlink (to our changelog history) in the Changelog modal * Multiline commands that don’t have any output are no longer cut off ### 2022.05.26 (v0.2022.05.23.09.07) [Section titled “2022.05.26 (v0.2022.05.23.09.07)”](#20220526-v0202205230907) **New features** * Warp can now send you desktop notifications for long-running commands and password prompts - [628](https://github.com/warpdotdev/warp/issues/628) * Added keybinding to toggle fullscreen mode **Bug fixes** * Stopped prepending \ before \~ in tab titles for older versions of Bash * Added support for CMD-G and SHIFT-CMD-G to tab between results in the Find Bar ### 2022.05.18 (v0.2022.05.16.09.01) [Section titled “2022.05.18 (v0.2022.05.16.09.01)”](#20220518-v0202205160901) **New features** * Added exclusive theme available to anyone who has referred someone to Warp. (Open Theme Picker > Warp Referral to use it) **Bug fixes** * Improved rendering of rounded corners throughout the app * Fixed cell dimension computation for some fonts * Fixed labels rendering incorrectly in the font selector dropdown in settings * Fixed Bash remote sessions missing tab titles * Reduced UI flickering after executing commands * Fixed errors when sshing into remote machines which do not have xxd available * Fixed some anti-aliased glyphs getting clipped during rasterization * Fixed search bar stealing focus after command execution ### 2022.05.11 (v0.2022.05.09.09.06) [Section titled “2022.05.11 (v0.2022.05.09.09.06)”](#20220511-v0202205090906) **New features** * Filepath completions without needing to cd * Support for any font (not just monospaced) **Bug fixes** * Tab completions (cd) with international characters are now properly escaped (edited) * Improve rendering performance when many tabs are open (fixes non-responsiveness when searching history) * Fixed a race condition with autoupdate a11y announcements and other a11y messaging * Fixed a regression that would cut off the output of some long-running Blocks ### 2022.05.04 (v0.2022.05.02.09.00) [Section titled “2022.05.04 (v0.2022.05.02.09.00)”](#20220504-v0202205020900) **New features** * Added default tab titles for Bash * Improved default tab title in Zsh * Maximize a split pane * Support rcfiles that check PS1 to determine if it’s an interactive shell; this may explain missing aliases or commands in Warp! **Bug fixes** * History now correctly shows results after hitting ESC when a Block is focused * Fixed crash when quitting AI Command Search while a command was being generated * Global keybindings with function keys and numeric keys are now properly registered * Warp no longer jumps up and down for single-line commands that take more than 50ms ### 2022.05.02 (v0.2022.04.25.09.59) [Section titled “2022.05.02 (v0.2022.04.25.09.59)”](#20220502-v0202204250959) **New features** * Added a Quake Mode setting that configures whether Warp should automatically hide when losing focus - [1077](https://github.com/warpdotdev/warp/issues/1077) * Added a Quake Mode setting that configures which screen to pin Warp on - [862](https://github.com/warpdotdev/warp/issues/862) * Expanded the keybindings supported by Quake Mode / Global Hotkey Window - [856](https://github.com/warpdotdev/warp/issues/856) **Bug fixes** * Commands prepended with space are now stored in history if hist\_ignore\_space option is not set * Now support dotfile configurations with non-English quotation marks * Continued improving the reliability of login and auth within the app * Improved performance for commands with large outputs * Improved performance for long running commands * Improved text alignment within inline banners ### 2022.04.27 (v0.2022.04.25.09.59) [Section titled “2022.04.27 (v0.2022.04.25.09.59)”](#20220427-v0202204250959) **New features** * Added a Quake Mode setting that configures whether Warp should automatically hide when losing focus - [1077](https://github.com/warpdotdev/warp/issues/1077) * Added a Quake Mode setting that configures which screen to pin Warp on - [862](https://github.com/warpdotdev/warp/issues/862) * Expanded the keybindings supported by Quake Mode / Global Hotkey Window - [856](https://github.com/warpdotdev/warp/issues/856) **Bug fixes** * Commands prepended with space are now stored in history if hist\_ignore\_space option is not set * Now support dotfile configurations with non-English quotation marks * Continued improving the reliability of login and auth within the app * Improved performance for commands with large outputs * Improved performance for long running commands * Improved line height computation for some fonts * Improved text alignment within inline banners ### 2022.04.20 (v0.2022.04.18.09.08) [Section titled “2022.04.20 (v0.2022.04.18.09.08)”](#20220420-v0202204180908) **New features** * Support logging into Warp by pasting the auth url when “Take me to Warp” fails in browser **Bug fixes** * Improved reliability of login and auth within the app * Buttons within the find bar are now properly shaded for gradient themes * Workflows with default values are now registered by Warp * Fixed bootstrapping bug that affected Fish versions older than 3.2.0 * Fixed a memory leak that occurred when new tabs were opened or panes were split ### 2022.04.15 (v0.2022.04.11.09.09) [Section titled “2022.04.15 (v0.2022.04.11.09.09)”](#20220415-v0202204110909) **Bug fixes** * Support parsing PS1’s exit codes (Bash’s $?) and improved PS1 parsing for newer Bash versions (4.4+) * Fixed prompt showing up as exit in Bash - [793](https://github.com/warpdotdev/warp/issues/793) * Improved parsing of Zsh default prompts * Opening the find bar will automatically select any existing text - [831](https://github.com/warpdotdev/warp/issues/831) ### 2022.04.13 (v0.2022.04.11.09.09) [Section titled “2022.04.13 (v0.2022.04.11.09.09)”](#20220413-v0202204110909) **Bug fixes** * Support parsing PS1’s exit codes (Bash’s $?) and improved PS1 parsing for newer Bash versions (4.4+) * Fixed prompt showing up as exit in Bash - [793](https://github.com/warpdotdev/warp/issues/793) * Improved parsing of Zsh default prompts * Opening the find bar will automatically select any existing text - [831](https://github.com/warpdotdev/warp/issues/831) ### 2022.04.08 (v0.2022.04.04.09.07) [Section titled “2022.04.08 (v0.2022.04.04.09.07)”](#20220408-v0202204040907) **Bug fixes** * Block sharing dialog now scrolls properly ### 2022.04.01 (v0.2022.04.01.01.37) [Section titled “2022.04.01 (v0.2022.04.01.01.37)”](#20220401-v0202204010137) **New features** * Warm welcome! * A.I. Command Search **Bug fixes** * Warp now properly registers `SPACE` and `SHIFT` modifier keys for Global Hotkey Windows * Page Up and Page Down keys now work correctly in vim and other fullscreen apps - [560](https://github.com/warpdotdev/warp/issues/560) * SSH now supports bootstrapping if bash-preexec is included in a Debian VM’s system rcfiles (eg by default at Google) - [578](https://github.com/warpdotdev/warp/issues/578) * Corrected keyboard shortcut for split pane in context menu ### 2022.03.30 (v0.2022.03.29.02.23) [Section titled “2022.03.30 (v0.2022.03.29.02.23)”](#20220330-v0202203290223) **New features** * Workflows: an easier way to share, parameterize, and execute commands - [625](https://github.com/warpdotdev/warp/issues/625) * Quake mode / Focus Warp with a Global Hotkey - [091](https://github.com/warpdotdev/warp/issues/091) **Bug fixes** * Magnet, Swish and ALT-Tab window managers now work with Warp - [776](https://github.com/warpdotdev/warp/issues/776) * SSH now handles control master connection errors - [578](https://github.com/warpdotdev/warp/issues/578) * SSH now handles verbose mode, no longer leaks into the Input Editor as a typeahead - [578](https://github.com/warpdotdev/warp/issues/578) * SSH now boots normally for POSIX shells that aren’t supported by Warp’s wrapper - [578](https://github.com/warpdotdev/warp/issues/578) ### 2022.03.24 (v0.2022.03.23.22.10) [Section titled “2022.03.24 (v0.2022.03.23.22.10)”](#20220324-v0202203232210) **New features** * Fish support - [190](https://github.com/warpdotdev/warp/issues/190) * Basic screenreader support (Voiceover) - Warp is now an accessible terminal! * Added a toggle in the settings to disable the SSH wrapper - [821](https://github.com/warpdotdev/warp/issues/821) **Bug fixes** * Hitting tab with a text selection shows tab completions instead of indenting * SSH no longer hangs when /tmp is not writable for Zsh - [578](https://github.com/warpdotdev/warp/issues/578) * SSH no longer bootstrap the shell if it’s not meant to be an interactive session (e.g. if -T or a command is passed) - [578](https://github.com/warpdotdev/warp/issues/578) * SSH now supports Starship and Zsh’s $PROMPT variable - [803](https://github.com/warpdotdev/warp/issues/803) * Also import themes in subdirectories e.g. `~/.warp/themes/subdirectory/theme.yaml` ### 2022.03.16 (v0.2022.03.14.08.49) [Section titled “2022.03.16 (v0.2022.03.14.08.49)”](#20220316-v0202203140849) **New features** * Multi-block selections and corresponding actions - [146](https://github.com/warpdotdev/warp/issues/146) * Case-sensitive search **Bug fixes** * SSH no longer returns 0\~ and 1\~ after executing commands for Zsh 5.0.8 or older - [578](https://github.com/warpdotdev/warp/issues/578) * SSH now supports LocalCommand / RemoteCommand - [578](https://github.com/warpdotdev/warp/issues/578) * SSH over Zsh no longer depends on configuring locales on the remote machine - [578](https://github.com/warpdotdev/warp/issues/578) * SSH sources /etc/bash.bashrc which is an extra rcfile in Debian and other Linux distributions - [578](https://github.com/warpdotdev/warp/issues/578) * Improved completions stability when there are multiple panes on the same remote machine * Vim and other alt-screen apps properly expand to take up the full window - [552](https://github.com/warpdotdev/warp/issues/552) * Clicking into Warp from other foreground window focuses the clicked pane - [739](https://github.com/warpdotdev/warp/issues/739) * Warp now respects ignore-space history options for Zsh and Bash - [044](https://github.com/warpdotdev/warp/issues/044) * Warp now creates a \~/.warp folder to persist custom keybindings - [801](https://github.com/warpdotdev/warp/issues/801) ### 2022.03.09 (v0.2022.03.07.08.51) [Section titled “2022.03.09 (v0.2022.03.07.08.51)”](#20220309-v0202203070851) **Bug fixes** * Added missing actions to Command Palette * Option is meta is now in the settings menu * Fix for SSH hanging when Zsh is the remote login shell * Fix for SSH with Zsh that would break with certain rcfiles because of incorrectly set ZDOTDIR ### 2022.03.02 (v0.2022.02.28.08.45) [Section titled “2022.03.02 (v0.2022.02.28.08.45)”](#20220302-v0202202280845) **New features** * Can now edit the keybindings for arrow navigation (Up/Down/Left/Right) * Can now edit the keybindings for activating specific tabs (by number CMD-1, CMD-2, …) **Bug fixes** * Crash in theme chooser * Fix for tab completion sometimes deleting characters ### 2022.02.23 (v0.2022.02.21.08.55) [Section titled “2022.02.23 (v0.2022.02.21.08.55)”](#20220223-v0202202210855) **New features** * Zsh support over SSH * Partially complete autosuggestion (by word) using CTRL-RIGHT and ALT-RIGHT - [488](https://github.com/warpdotdev/warp/issues/488) * Added a Copy URL menu item after right-clicking a URL - [154](https://github.com/warpdotdev/warp/issues/154) * Indicator for conflicting keybindings in keyboard customization UI **Bug fixes** * Able to fill-in longest common prefix after filtering tab completions - [618](https://github.com/warpdotdev/warp/issues/618) * Block completion causes Input Editor to steal focus from find bar - [452](https://github.com/warpdotdev/warp/issues/452) * UP-arrow in history menu sometimes scrolls more than one item * CMD-F opens a no-op find bar in alt screen ### 2022.02.16 (v0.2022.02.14.08.44) [Section titled “2022.02.16 (v0.2022.02.14.08.44)”](#20220216-v0202202140844) **New features** * Customizable key bindings (accessible via the settings menu) - [579](https://github.com/warpdotdev/warp/issues/579) * Users can opt in to use their shell’s prompt rather than Warp’s default (select the Honor PS1 toggle under the settings menu) - [580](https://github.com/warpdotdev/warp/issues/580) * Added a timestamp showing Block runtime duration; hover to see start and end date + time - [178](https://github.com/warpdotdev/warp/issues/178) * CTRL-F now accepts autosuggestions - [403](https://github.com/warpdotdev/warp/issues/403) * CTRL-E and CMD-RIGHT accept autosuggestions when at the end of the buffer - [403](https://github.com/warpdotdev/warp/issues/403) * Allow input height to expand to half the pane height - [621](https://github.com/warpdotdev/warp/issues/621) **Bug fixes** * Arrow key presses now (up and down now) cycle themes in the theme picker - [294](https://github.com/warpdotdev/warp/issues/294) * ESC keypress now exits the theme picker * CMD-Down when on most recent block to focus input now clears Block selection * Fixed a bug where resizing a pane while a command was running made it impossible to scroll to the bottom of the pane * Fixed a bug where resizing a pane could cause Warp to show a blank screen * Parentheses, quotes, and brackets now also auto-close after typing an alphanumeric character * Remapped multi-cursor key bindings to CTRL-SHIFT-UP and CTRL-SHIFT-DOWN - [374](https://github.com/warpdotdev/warp/issues/374) * Restored OPT-CMD-UP and OPT-CMD-DOWN for switching panes up and down - [730](https://github.com/warpdotdev/warp/issues/730) ### 2022.02.02 (v0.2022.01.31.09.03) [Section titled “2022.02.02 (v0.2022.01.31.09.03)”](#20220202-v0202201310903) **New features** * Multi-cursor keybindings for adding cursors above and below current selections with OPT-CMD-UP/DOWN - [374](https://github.com/warpdotdev/warp/issues/374) **Bug fixes** * Double clicking the top of the window maximizes the app - [097](https://github.com/warpdotdev/warp/issues/097) * Icon, cursor and selection contrast fixes * Scrolling performance improvements with bg image themes * Changelog visual glitch * Resize bug - losing scroll position when viewing blocks with long output ### 2022.01.26 (v0.2022.01.24.08.55) [Section titled “2022.01.26 (v0.2022.01.24.08.55)”](#20220126-v0202201240855) **New features** * Auto-close symbols (parentheses, quotes, and brackets) like VSCode **Bug fixes** * Block sharing link no longer cuts off - [660](https://github.com/warpdotdev/warp/issues/660) * Right clicking a Block now focuses that Block * Mouse dragging in vim * Restoring history bug on session restore * Automatically focus the last active window on session restore ### 2022.01.19 (v0.2022.01.17.08.48) [Section titled “2022.01.19 (v0.2022.01.17.08.48)”](#20220119-v0202201170848) **New features** * Restore block contents * The longest common prefix in the completions menu auto-fills the Input Editor - [479](https://github.com/warpdotdev/warp/issues/479) * Add description for paths in completion results - [103](https://github.com/warpdotdev/warp/issues/103) * Can right click the prompt and copy: git branch, prompt, cwd - [346](https://github.com/warpdotdev/warp/issues/346) **Bug fixes** * Fixed bug where venv was inserted into input editor - [599](https://github.com/warpdotdev/warp/issues/599) * Improved url detection ### 2022.01.12 (v0.2022.01.10.17.24) [Section titled “2022.01.12 (v0.2022.01.10.17.24)”](#20220112-v0202201101724) **New features** * Added a Changelog page to our documentation **Bug fixes** * Double clicking text in a url now highlights the word instead of the whole url - [508](https://github.com/warpdotdev/warp/issues/508) * Double clicking a string with underscores now selects the whole string and not just the subword * Selection updates correctly when a block hit its max line length * Can now also close the Command Palette using CMD-P - [184](https://github.com/warpdotdev/warp/issues/184) * Moved check for update button to settings dialog - [070](https://github.com/warpdotdev/warp/issues/070) * Fixes tabs not opening in new windows when autoupdate is pending * Fix regression with input box not being focused on app relaunch ### 2022.01.05 (v0.2022.01.03.09.07) [Section titled “2022.01.05 (v0.2022.01.03.09.07)”](#20220105-v0202201030907) **New features** * Native undo and redo in the text editor using CMD-Z - [113](https://github.com/warpdotdev/warp/issues/113) * Added CMD-M to minimize the Window - [107](https://github.com/warpdotdev/warp/issues/107) * Added our open source licenses to the Warp Documentation * Split pane focus indicator - a triangle in the top left corner of the pane in focus **Bug fixes** * CTRL-SPACE is now properly passed to Emacs and other terminal apps - [499](https://github.com/warpdotdev/warp/issues/499) * Copy on select setting persists across sessions and does not reset after updates # Changelog — 2023 > Warp release notes for 2023. Updates ship weekly, typically on Thursdays. Submit bugs and feature requests on our [GitHub board!](https://github.com/warpdotdev/Warp/issues/new/choose) ### 2023.02.08 (v0.2024.02.13.08.02) [Section titled “2023.02.08 (v0.2024.02.13.08.02)”](#20230208-v0202402130802) **Bug fixes** * Fix the inputted command sometimes overlapping rprompt (right-sided prompt) ### 2023.02.01 (v0.2024.01.30.16.52) [Section titled “2023.02.01 (v0.2024.01.30.16.52)”](#20230201-v0202401301652) **Improvements** * Improved UX for pasting an auth token to complete the sign-in flow * Subversion (svn) information is now available in Warp’s prompt ### 2023.01.18 (v0.2024.01.16.16.31) [Section titled “2023.01.18 (v0.2024.01.16.16.31)”](#20230118-v0202401161631) **New features** * Warp on Linux (Private Beta): System fonts now load as expected **Bug fixes** * Warp on Linux (Private Beta): `ALT-TAB` no longer incorrectly inserts 4 spaces into the Input Editor ### 2023.01.11 (v0.2024.01.09.08.02) [Section titled “2023.01.11 (v0.2024.01.09.08.02)”](#20230111-v0202401090802) **New features** * New workflow metadata for shared workflows in Warp Drive! Hover over any workflow to learn how recently the workflow has been executed, who edited it last, and when it was last edited. ### 2023.12.21 (v0.2024.01.02.08.02) [Section titled “2023.12.21 (v0.2024.01.02.08.02)”](#20231221-v0202401020802) **Improvements** * The toolbelt displayed when hovering over background Blocks now has a solid background **Bug fixes** * The Markdown Viewer now respects the start number of ordered lists * Completing a path that includes the tilde (`~`) character now works as expected * Fixed an issue where Warp could quit before saving changes to Warp Drive * Fix Warp hanging when using the ‘Insert into Input’ context menu action ### 2023.12.14 (v0.2023.12.12.08.02) [Section titled “2023.12.14 (v0.2023.12.12.08.02)”](#20231214-v0202312120802) **New features** * Editing with Vim keybindings is now out of beta and generally available! Warp will detect vi mode in shell settings and suggest Vim keybindings. **Improvements** * You can now use `CMD-F` to search text in the Markdown Viewer **Bug fixes** * Block hover buttons now have a solid background when they overlap with your prompt * The Block filter editor now has a clear button * `J` and `K` (Vim Mode) can be used for navigation within a multi-line command * Fixed the left alignment of the tab bar when in full-screen mode on macOS * Fixed triple-click selection (selecting a line) when filtering a Block * Fixed potential crash when using the find bar * Fixed potential crash when retrieving accessibility contents * Fix bug where “R” is erroneously inserted into the input in zsh sessions ### 2023.12.07 (v0.2023.12.05.08.02) [Section titled “2023.12.07 (v0.2023.12.05.08.02)”](#20231207-v0202312050802) **Improvements** * Markdown file links can now be configured to open with the default external editor or Warp’s built-in markdown viewer * Warp Drive folders now keep their opened/closed state through app restarts **Bug fixes** * The Input Editor now refocuses correctly after pasting terminal contents and running a command * Fixed issue with missing toolbelt buttons when using fish wih Vim Mode ### 2023.11.30 (v0.2023.11.28.08.02) [Section titled “2023.11.30 (v0.2023.11.28.08.02)”](#20231130-v0202311280802) **Improvements** * Warp’s custom prompt builder now includes a context chip for Kubernetes context * Improved completions for kubectl, including suggestions for resource, global options, and namespaces **Bug fixes** * Fixed a UI bug in the workflows editor where the editor for arguments was overflowing * Search bar focuses as expected when you open Launch Configurations with the Command Palette ### 2023.11.16 (v0.2023.11.14.08.02) [Section titled “2023.11.16 (v0.2023.11.14.08.02)”](#20231116-v0202311140802) **Bug fixes** * The informational block that shows workflow metadata now resizes with your Warp window * The scrolling speed is now standardized across Warp ### 2023.11.09 (v0.2023.11.07.08.02) [Section titled “2023.11.09 (v0.2023.11.07.08.02)”](#20231109-v0202311070802) **New features** * New Markdown Viewer: You can now open .md files in Warp and run the shell commands within these files * Block Filtering: You can now filter block output (SHIFT-OPT-F) to quickly find matching lines based on a query. **Improvements** * Removed the workflow button from the toolbelt section (top-right buttons) of a block. It is still accessible through the right-click menu (see “Save as Workflow”) and its default keybinding CMD-S. * Improved performance of Warp Drive team and state syncing ### 2023.11.02 (v0.2023.10.31.08.03) [Section titled “2023.11.02 (v0.2023.10.31.08.03)”](#20231102-v0202310310803) **Improvements** * You can now invite new team members to your shared Warp Drive by email address and revoke invitations ### 2023.10.23 (v0.2023.10.17.08.03) [Section titled “2023.10.23 (v0.2023.10.17.08.03)”](#20231023-v0202310170803) **Improvements** * Indicators appear in the tab bar when the current pane is maximized (a full-screen icon) and when a command exits with an error * The Git context chip in Warp’s prompt now shows the commit hash instead of “HEAD” when in a detached state * Easier to add and remove allowlisted domains when inviting teammates to Warp Drive * Added a menu option for copying a workflow command (into the clipboard) ### 2023.10.19 (v0.2023.10.17.08.03) [Section titled “2023.10.19 (v0.2023.10.17.08.03)”](#20231019-v0202310170803) **Improvements** * Indicators appear in the tab bar when the current pane is maximized (a full-screen icon) and when a command exits with an error * The Git context chip in Warp’s prompt now shows the commit hash instead of “HEAD” when in a detached state * Easier to add and remove allowlisted domains when inviting teammates to Warp Drive * Added a menu option for copying a workflow command (into the clipboard) ### 2023.10.12 (v0.2023.10.10.08.06) [Section titled “2023.10.12 (v0.2023.10.10.08.06)”](#20231012-v0202310100806) **Improvements** * Warp can now support macOS’s proxy settings * You can now toggle whether to render Warp using the integrated GPU for dual GPU Macs * Warp now escapes the file path of an executable loaded from Finder **Bug fixes** * Fixed a crash on startup for some users on macOS Sonoma * The workflow info box now refreshes when edited ### 2023.10.05 (v0.2023.10.03.08.03) [Section titled “2023.10.05 (v0.2023.10.03.08.03)”](#20231005-v0202310030803) **New features** * Now you can use Vim keybindings to edit text on the command line in Warp. Navigate to Settings > Feature > Editor and enable “Edit commands with Vim keybindings.” This feature is currently in beta and available to try today. **Improvements** * Admins can now control whether the team invite link is accessible for other team members to copy and share. Admins can also reset the URL token if needed. * You can now add a 24-hour timestamp to your Warp prompt with context chips in the prompt editor. * The free preview for Warp AI and Warp Drive for teams has been extended. [Learn More](https://www.warp.dev/blog/free-preview-extended) ### 2023.09.28 (v0.2023.09.26.08.09) [Section titled “2023.09.28 (v0.2023.09.26.08.09)”](#20230928-v0202309260809) **New features** * If you have Cursor installed, you can now set this as your default code editor under Settings > Features > General. **Improvements** * Enhanced user accessibility by adding a tab bar button as a new entry point for the command palette. * Improved user guidance by displaying a warning when attempting to run a workflow while another command is already in progress. **Bug fixes** * Resolved an issue where autosuggestions were not being inserted when bound to certain keybindings. * Fixed a bug affecting Input Method Editor functionality on non-English keyboards, which caused incorrect positioning and prevented text input after opening a new window. ### 2023.09.14 (v0.2023.09.19.08.04) [Section titled “2023.09.14 (v0.2023.09.19.08.04)”](#20230914-v0202309190804) **New features** * You can now edit keybindings to scroll up and down by one line. **Improvements** * The input editor remains visible in inactive panes when using split panes. **Bug fixes** * Resolved a regression where the filled bookmark icon didn’t display on bookmarked blocks unless hovered on. * Fixed the `TAB` key not cycling through fields in the Workflow editor under certain circumstances. * Restored functionality of the keybinding for “New Tab” to work even when no windows are open. ### 2023.09.07 (v0.2023.09.06.18.09) [Section titled “2023.09.07 (v0.2023.09.06.18.09)”](#20230907-v0202309061809) **Improvements** * The new tab keyboard shortcut (`CMD-T` by default) can now be re-mapped. * Warp Drive now shows a loading indicator when syncing. **Bug fixes** * The command timestamp tooltip is no longer hidden when the Input Editor is pinned to the top. ### 2023.08.31 (v0.2023.08.29.08.04) [Section titled “2023.08.31 (v0.2023.08.29.08.04)”](#20230831-v0202308290804) **Improvements** * You can now delete custom themes from the Warp UI * You can now scroll to the top or bottom of a selected block from the Command Palette. **Bug fixes** * Fixed an issue where CPU was being used up by git processes ([3563](https://github.com/warpdotdev/warp/issues/3563)) * Fixed a Zsh bug where `set sh_word_split` could break Warp’s bootstrapping ### 2023.08.24 (v0.2023.08.22.08.03) [Section titled “2023.08.24 (v0.2023.08.22.08.03)”](#20230824-v0202308220803) **New features** * Secret Redaction - Warp can now automatically redact secrets and sensitive information in terminal output, including passwords, IP addresses, API keys, and PII. Enable Secret Redaction from the Command Palette or Settings > Privacy > Secret Redaction **Improvements** * Special keys used in conjunction with `META` e.g. `META-DELETE` should now work within the alt-screen * The line height for the text within the Input Editor should now actually change when the custom height in `Settings > Appearance > Text > Line Height` is updated * Alias Abbreviations in fish should no longer show a red error underline within the Input Editor * Reduced the bottom padding within the Input Editor when Warp is in Compact Mode ### 2023.08.17 (v0.2023.08.15.08.03) [Section titled “2023.08.17 (v0.2023.08.15.08.03)”](#20230817-v0202308150803) **New features** * Warp now displays richer metadata for each command in history, including exit code, working directory, git branch, and whether the command is part of a workflow. * Warp’s native prompt is now customizable directly within the app with drag-and-drop Context Chips (`Settings > Appearance > Prompt`) **Improvements** * Warp now supports xterm’s escape codes (sequences) for focus reporting * The Command Palette now supports searching for workflows with their Warp Drive folder name, in addition to the Workflow’s name and description. * Auto-generating custom themes from starting images now work even with a missing `~/.warp/themes` directory * The “New Workflow” modal now supports more text for longer commands ### 2023.08.10 (v0.2023.08.08.08.04) [Section titled “2023.08.10 (v0.2023.08.08.08.04)”](#20230810-v0202308080804) **New features** * Automatically create new themes based on a background image! Click the `+` button in the theme picker (`Settings -> Appearance -> Current Theme`) or search `Open Theme Picker` within the Command Palette **Improvements** * Workflows and folders in Warp Drive can now be sorted alphabetically and by last updated * Multiple JetBrains IDEs are now supported as external editors (e.g. WebStorm, PhpStorm, GoLand) * The Command Palette now shows which folders a Workflow is in (breadcrumbs) * Aliases like `...` and `....` no longer incorrectly have an error underline ### 2023.08.03 (v0.2023.08.01.08.05) [Section titled “2023.08.03 (v0.2023.08.01.08.05)”](#20230803-v0202308010805) **New features** * Reopen closed tabs with `SHIFT-CMD-T` for up to one minute; configure or disable this feature in `Settings > Features > Enable reopening of closed sessions` * Autogenerate descriptions for Workflows in Warp Drive using Warp AI **Improvements** * Nested folders in Warp Drive can now be collapsed all at once * Fixed issue where fish abbreviation expansion would include comments * Fixed a regression with fish history becoming inaccessible ### 2023.07.27 (v0.2023.07.25.08.03) [Section titled “2023.07.27 (v0.2023.07.25.08.03)”](#20230727-v0202307250803) **Improvements** * Fixed an issue where $PATH could be overwritten in Bash subshells * Fixed an issue where completions for file-paths broke when using Named Flags e.g. `ls --color=auto` * Fixed an issue where Warp Drive objects could get stuck in a sync state * The down arrow `DOWN` now correctly moves the cursor within Warp AI’s text editor ### 2023.07.20 (v0.2023.07.18.08.03) [Section titled “2023.07.20 (v0.2023.07.18.08.03)”](#20230720-v0202307180803) **New features** * Can now configure whether `TAB` accepts autosuggestions or opens the completions menu; switch between the configurations via `Settings > Features > Editor` * Improved completions behavior by improving common prefix detection, and supporting case sensitivity * Can now natively draw some Unicode block element characters instead of using font glyphs—improves alignment and reduces fuzziness * Warp’s Resource Center now displays new features and improvements **Improvements** * Increased the maximum blur radius from 18 to 64 ### 2023.07.13 (v0.2023.07.11.08.03) [Section titled “2023.07.13 (v0.2023.07.11.08.03)”](#20230713-v0202307110803) **New features** * Warp Drive items that failed to sync can now be retried * Workflows in Warp Drive can now be edited with the workflow execution modal **Improvements** * Fixed a bug where git information could sometimes be missing from the prompt * Adjusted some colors throughout Warp—replaced gradients with solid colors. ### 2023.07.06 (v0.2023.07.04.08.03) [Section titled “2023.07.06 (v0.2023.07.04.08.03)”](#20230706-v0202307040803) **New features** * A new AI Command Search experience that allows you to translate natural language to shell commands and integrates directly with workflows! Type ’#’ in the input to try it out! **Improvements** * Fixed a bug where Warp was not recognizing some single character commands and aliases. * Fixed a bug where command output would sometimes be cut off after finishing (most notably in Gradle). * Fixed a bug where two prompts could appear for remote Bash sessions ### 2023.06.29 (v0.2023.06.27.19.34) [Section titled “2023.06.29 (v0.2023.06.27.19.34)”](#20230629-v0202306271934) **New features** * App links of the form Warp\://launch/\ directly open a launch configuration * Added a new setting for creating new windows with a specific size in terms of rows and columns. **Improvements** * Fix rendering of multiple ANSI styles on the same character. This fixes rendering issues commonly encountered in Vim and emacs. * Fix tabs (indentations) sometimes being inserted into the Input Editor when the completion menu should open. * Added tooltip for “New tab” button * The “Launch Configurations” sub-menu (under the Mac File menu) now updates dynamically as launch configurations are added and removed. * Find bar is able to match double-width unicode characters, including CJK and emojis. * Fixed a crash that could occur when pasting a command in the workflow editor ### 2023.06.20 (v0.2023.06.20.08.04) [Section titled “2023.06.20 (v0.2023.06.20.08.04)”](#20230620-v0202306200804) **New features** * You can now bring the power of your Powerlevel10k (P10K) prompt to Warp! For best results, you’ll need the latest version of P10K; see their GitHub page for upgrade instructions * Right-side prompts are now supported in Zsh and fish! * Warp AI commands can now be executed as workflows. **Bug fixes** * Clicking on an inactive Warp window now focuses the underlying pane correctly. ### 2023.06.08 (v0.2023.06.13.08.03) [Section titled “2023.06.08 (v0.2023.06.13.08.03)”](#20230608-v0202306130803) **New features** * Added a settings page for our upgraded referral system—we’ve added new swag options. * Right-click a highlighted file path to open a context menu that now supports showing the file in Finder * The Command Palette can now search through Warp sessions, actions and launch configurations **Bug fixes** * The completions menu now supports fish abbreviations * Fixed an issue where certain aliases would be incorrect after expansion. * Fixed command search to ignore the extra whitespace before and after the search query * Restored background Blocks no longer create blank history entries * Fixed an issue where enabling the “Open completions as you type” setting could sometimes break path completions * Fixed an issue where Zsh could fail to bootstrap when `$PATH` is an a bad state * Fixed issue where Warp’s bootstrap logic could leak into Zsh’s history * Fix issue with properly underlining when hyperlinks are in lists or span across multiple lines ### 2023.06.01 (v0.2023.05.30.08.03) [Section titled “2023.06.01 (v0.2023.05.30.08.03)”](#20230601-v0202305300803) **New features** * Right-clicking the New Tab (`+`) button opens a context menu to select saved Launch Configurations * Use Page Up (`PG-UP`) and Page Down (`PG-DOWN`) in the Command Palette for faster navigation * Added support for Zed as a default code editor * Referral counts have been updated to only include referrals who’ve onboarded onto (actually tried) Warp **Bug fixes** * Warp’s hotkey window (Quake Mode) now properly retains its size * Fixed issue where command output would temporarily cutoff when resizing Warp. * Fixed the Sticky Command Header covering content for pager commands. * Fixed tabs showing stale text when being renamed. * Clicking a Mac menu bar item that has a sub-menu no longer incorrectly closes the menu * Warp now automatically focuses the shortcut search bar when the keyboard shortcuts pane is opened (`CMD-/`) * Fixed regression where Warp’s native prompt no longer showed the virtual environment ### 2023.05.25 (v0.2023.05.23.08.05) [Section titled “2023.05.25 (v0.2023.05.23.08.05)”](#20230525-v0202305230805) **Bug fixes** * Improved shell startup performance after a system restarts for users with Xcode installed * Fixed issue with Warpifying a pipenv shell subshell from zsh * Fixed issue with updating the git status prompt indicator in remote subshells ### 2023.05.18 (v0.2023.05.18.01.08) [Section titled “2023.05.18 (v0.2023.05.18.01.08)”](#20230518-v0202305180108) **New features** * Warp now supports subshells in Zsh, Bash, and fish for a better experience with Docker, GCP, Poetry, and more. Configure which commands you’d like to “Warpify” under Settings > Subshells **Bug fixes** * Fixed an issue with Warp’s completions when using flags that start with a single dash e.g. `-namespace` * Fixed an issue with Synchronized Inputs where switching from alt-screens focused on the incorrect terminal session * Fixed an issue where command history suggestions could cause Synchronized Inputs to get out of sync ### 2023.05.11 (v0.2023.05.09.08.03) [Section titled “2023.05.11 (v0.2023.05.09.08.03)”](#20230511-v0202305090803) **New features** * Warp now sends the output of background shell processes into new (distinct) Blocks—separate from user generated Blocks. * Synchronize (broadcast) input across multiple panes in a single tab or multiple tabs (`Mac Menu > Edit > Synchronize Inputs` or `Synchronize` within the Command Palette) * Added option to enable (disabled by default) an audible terminal bell (`Settings > Features > Terminal` or “Enable/Disable Audible Terminal Bell” within the Command Palette) * Now opens new windows with the same position and size of the most recently closed window (if there is one) * Fish aliases are now supported in the completions menu **Bug fixes** * Support for `SHIFT-UP` and `SHIFT-DOWN` within alt-screen editors * Fixed incorrect alt-screen scrolling behavior when scroll reporting is enabled * `SHIFT-TAB` now (correctly) sends the ANSI (backward-tab) escape sequence (for Vim and NeoVim) * SSH wrapper now also loads your /etc/profile and supports login-like prompts and interactions like printing the message of the day (MOTD) ### 2023.05.04 (v0.2023.05.02.08.03) [Section titled “2023.05.04 (v0.2023.05.02.08.03)”](#20230504-v0202305020803) **New features** * Indicate when Warp is downloading an update in Settings > Account > About Warp * Support alias expansion for bash/zsh aliases ### 2023.04.27 (v0.2023.04.25.08.05) [Section titled “2023.04.27 (v0.2023.04.25.08.05)”](#20230427-v0202304250805) **New features** * Support for Fish abbreviations * Right-click within the Input Editor to open a context menu where you can split panes, etc. **Bug fixes** * Starting a command with whitespace in the Workflow creation dialog no longer breaks its argument parser * Fixed a bug when commands were aliased to `comm` because of a naming clash with Warp’s wrapper * `Cut word left` (`CTRL-W`) and `Cut word right` (`OPT-D`) now use the shell clipboard instead of the system clipboard ### 2023.04.13 (v0.2023.04.11.08.03) [Section titled “2023.04.13 (v0.2023.04.11.08.03)”](#20230413-v0202304110803) **New features** * Navigation by subword within the Input Editor with `CTRL-OPT-LEFT` and `CTRL-OPT-RIGHT` * View prior Warp AI questions using the `UP` arrow even after the transcript is cleared **Bug fixes** * Fixed a bug in proxied SSH while not on the default shell * Background blur now also applies to windows that are opened via drag-and-drop from Finder * The Sticky Command Header no longer cuts off text for pagers ### 2023.04.06 (v0.2023.04.04.08.03) [Section titled “2023.04.06 (v0.2023.04.04.08.03)”](#20230406-v0202304040803) **New features** * The position of the input and direction of the terminal output are now configurable. You can start the input at the top and have it move down as new commands are run (to clear the screen and reset the position press `CTRL-L`, `CMD-K` or type `clear`). Or you can keep the input pinned to the top of the pane and have terminal outputs flow in reverse order. Settings are available under `Settings > Appearance > Input Position` * Added a button for “jumping to the bottom” of the currently hovered Block to make it easy to get to the bottom of an output. Configurable with a setting under `Settings > Appearance > Blocks` * Warp AI transcripts can now be navigated via keyboard (`UP` / `DOWN` arrows) * Added a right-click context menu in the alt-screen (that still respects mouse reporting and SGR\_MOUSE) * Warp AI’s past prompts can be accessed via `UP` (arrow) * `CMD-ENTER` within Warp AI now inputs the selected command into the Input Editor **Bug fixes** * Workflows can now be searched by their description in Command Search * Consolidated “Ask Warp AI” keybindings into one * Fixed an issue causing “Move cursor by word” and “Select left/right by word” to not work if “Left/Right Option key is Meta” is enabled * Can now unset cursor navigation bindings within an executing command ### 2023.03.30 (v0.2023.03.28.08.03) [Section titled “2023.03.30 (v0.2023.03.28.08.03)”](#20230330-v0202303280803) **New features** * Warning if a known-incompatible custom prompt is detected * Keybindings for cursor navigation in REPLs and subshells, e.g. ⌥←, ⌥→, ⌥⌫, ⌘←, ⌘→, ⌘⌫, ⌘fn⌫ **Bug fixes** * Fixed an issue where an input suggestion tooltip could overflow outside the visible window * Fixed keybinding conflict with Warp AI * Fixed completion and syntax highlighting when local paths contain separators, not in the prefix ### 2023.03.23 (v0.2023.03.21.08.02) [Section titled “2023.03.23 (v0.2023.03.21.08.02)”](#20230323-v0202303210802) **New features** * Added VSCode Insiders as a supported code editor * Added completions for pnpm. **Bug fixes** * Fixed an issue where AI command results with multiple commands would all render on the same line * The configurable width of Universal Search is now persistent (doesn’t reset to default in new sessions). * “Copy Prompt” now correctly respects your PS1 prompt, if enabled * Fixed automatic command corrections for cargo. ### 2023.03.20 (v0.2023.03.14.08.03) [Section titled “2023.03.20 (v0.2023.03.14.08.03)”](#20230320-v0202303140803) **New features** * Added support to configure which shell Warp should use when starting a terminal session. Configurable under Settings -> Features -> Session. * Tabs can now be renamed via mouse double-click. **Bug fixes** * Launch configuration templates now support use of `~` in the `cwd` field. * Double-clicking a button/tab in the title bar no longer resizes the whole window. * Context menus in the blocklist are now more pronounced and easier to dismiss by clicking. * Increased the clickable area of small search boxes. * A keyboard shortcut can now be registered to clear all blocks. * Fixed some locale-related issues due to use of `LC_ALL` environment variable. * Xterm escape code OSC 4 (“change color”) no longer crashes the app when it appears in PS1. * Fixed a crash that occurs when resizing windows after dismissing a notification banner. * Fixed crash that occurs if you unset the keybinding for the keyboard shortcuts side panel. * Added Warp AI to resource center. ### 2023.03.16 (v0.2023.03.07.08.02) [Section titled “2023.03.16 (v0.2023.03.07.08.02)”](#20230316-v0202303070802) **New features** * Introducing Warp AI ⚡ Get explanations for errors and outputs, ask for help with complicated workflows and scripts, easily execute suggested commands, all without leaving Warp! ### 2023.03.09 (v0.2023.03.07.08.02) [Section titled “2023.03.09 (v0.2023.03.07.08.02)”](#20230309-v0202303070802) **New features** * Added support for clearing a keybinding for an action [2300](https://github.com/warpdotdev/warp/issues/2300). * Added support for showing/hiding Warp windows with a system-wide Activation hotkey [2585](https://github.com/warpdotdev/warp/issues/2585). * Improved scroll speed for Sidebar menu ‘Warp Essentials’/‘Keyboard Shortcuts’ [2673](https://github.com/warpdotdev/warp/issues/2673). * Users may now set a custom keybinding to open the completions menu. * Enabling/disabling mouse reporting is no longer bound to CMD-R by default. * Toggling mouse reporting enabled shows a banner. **Bug fixes** * Fixed SSH wrapper hanging forever when SSH host is Arch Linux with the latest bash package [2636](https://github.com/warpdotdev/warp/issues/2636). * Fixed Bash commands having escape codes in the last 20 characters producing incorrect output. * Fixed a bug with bash prompt expansion on recent macOS versions. ### 2023.02.28 (v0.2023.02.28.08.03) [Section titled “2023.02.28 (v0.2023.02.28.08.03)”](#20230228-v0202302280803) **New features** * Warp now suggests a URL for creating a GitHub PR on `git push`. * Command Search and Workflow menus are now horizontally resizable. **Bug fixes** * Fixed a bug where Warp doesn’t correctly Auto-Raise. * Fixed issue where formatting is lost when pasting into nano. * Fixed issue where Warp doesn’t detect process termination when exiting `info`. * Fixed a bug with bash prompt expansion not working on v4.4 or earlier. * Fixed a bug where profile pictures don’t show in the Account menu. * Fixed Syntax Highlighting and Error Underlining’s handling of multi-byte characters. * Fixed issue where ‘Checking for Update’ doesn’t reflect the current status. ### 2023.02.23 (v0.2023.02.21.08.03) [Section titled “2023.02.23 (v0.2023.02.21.08.03)”](#20230223-v0202302210803) **New features** * Support for configuring the initial working directory for new sessions. New tabs/windows/split panes can have separate configurations, or you can set one value for all new sessions. **Bug fixes** * Warp now supports syntax highlighting and error underlining for multi-line inputs with multibyte characters * Fixed a bug where the update status in Warp’s `About Section` was incorrect. * Improved GPU memory consumption when multiple windows are open. ### 2023.02.16 (v0.2023.02.14.08.05) [Section titled “2023.02.16 (v0.2023.02.14.08.05)”](#20230216-v0202302140805) **New features** * Improved double-click selection. Double-clicking text now smart selects patterns like file paths, URLs, email addresses, etc. - [659](https://github.com/warpdotdev/warp/issues/659) * Warp can now be opened from Finder - [102](https://github.com/warpdotdev/warp/issues/102) **Bug fixes** * Warp no longer hangs after exiting the alt-screen—having searched for text using Find. * The Block-list now scrolls to the correct position after returning from the alt-screen. * Clicking above the scroll-bar no longer (incorrectly) changes its scroll position. * The terminal cell dimensions now update immediately after modifying the Font size. * Hyperlinks no longer incorrectly highlight on hover when Warp is not focused. * The Input Method Editor (non-English keyboards) is now positioned correctly in the alt-screen and in running Blocks * When there are no windows open, clicking `New Tab` from the Mac menu will create a new window ### 2023.02.09 (v0.2023.02.07.08.03) [Section titled “2023.02.09 (v0.2023.02.07.08.03)”](#20230209-v0202302070803) **Bug fixes** * Warp now sets the Mac window title; right-clicking on the dock icon will show the name of the active tab. * Fixed a bug where navigating the theme picker with the arrow keys would lead to a crash when no theme matches the search. * The Input Editor now refocuses correctly after clicking hyperlinks. * Custom keybindings incorporating the `SPACE` key now persist after closing Warp. * The Input Method Editor (non-English keyboards) now positions itself within the Input Editor ### 2023.01.26 (v0.2023.01.24.08.03) [Section titled “2023.01.26 (v0.2023.01.24.08.03)”](#20230126-v0202301240803) **New features** * Warp can now dim inactive terminal panes, navigate to `Settings > Appearance > Panes > Dim inactive panes` **Bug fixes** * Fixed crash when selecting multiple occurrences of multi-byte characters using `CTRL-G` ### 2023.01.19 (v0.2023.01.17.08.03) [Section titled “2023.01.19 (v0.2023.01.17.08.03)”](#20230119-v0202301170803) **New features** * The current Git branch can now be copied using the Command Palette (`CMD-P`) **Bug fixes** * Fixed bug where some keybinding actions would be applied to the wrong terminal pane. * Warp now checks the input values for font size and line height and ignores them if they are too small or large * The `missing update permissions banner`, can now be dismissed * Fixed a rare crash when closing panes created by a launch configuration ### 2023.01.12 (v0.2023.01.10.08.02) [Section titled “2023.01.12 (v0.2023.01.10.08.02)”](#20230112-v0202301100802) **New features** * Support setting window background transparency and blur radius, via sliders under `Settings > Appearance` * Revamped resource center! Click the Warp icon in the top right to see keyboard shortcuts and learn how to best use Warp * Quit modal: Quitting or closing Warp while a session is running triggers a warning prompt–that also lets you view which sessions are running * Added a toggle to disable cursor blinking **Bug fixes** * Can now support completions that have escaped paths * Can now support background images with paths that start with \~ * Can now properly restore a Warp window’s position when using multiple monitors * Commands from restored sessions run on the local machine no longer appear in the SSH server’s history * Fixed issues SSHing into RHEL/Fedora machines with PackageKit-command-not-found installed * Fixed incorrect handling of `->` as the user’s prompt * Fixed ls completions when using the —color option ### 2023.01.05 (v0.2023.01.03.08.03) [Section titled “2023.01.05 (v0.2023.01.03.08.03)”](#20230105-v0202301030803) **Bug fixes** * Trailing periods are no longer considered part of a URL. * Fixed regression where the “autocomplete symbols” setting was not being respected. # Changelog — 2024 > Warp release notes for 2024. Updates ship weekly, typically on Thursdays. Submit bugs and feature requests on our [GitHub board!](https://github.com/warpdotdev/Warp/issues/new/choose) ### 2024.12.26 (v0.2024.12.18.08.02) [Section titled “2024.12.26 (v0.2024.12.18.08.02)”](#20241226-v0202412180802) **Improvements** * We now immediately show an error when trying to Warpify unsupported shells over SSH. **Bug fixes** * Fixed blank lines being appended to some blocks on resize. * Fixed an issue where the AI context disappears when accepting the default autosuggestion. ### 2024.12.19 (v0.2024.12.18.08.02) [Section titled “2024.12.19 (v0.2024.12.18.08.02)”](#20241219-v0202412180802) **New features** * Introducing: Next Command! Next Command uses AI to suggest the next command to run based on your active terminal session and command history. Visit Settings > AI to turn it off. * Added support for block and underline-styled cursors in the input editor (while vim mode is disabled). **Improvements** * Clarified default permission information for sessions and Warp Drive objects. * F11 (configurable) now toggles fullscreen on Linux and Windows. * PowerShell environment variables are now recognized in completions. * Cursor shape is now more responsive to clickable buttons. **Bug fixes** * Characters from unhandled keystrokes no longer handled as typed characters in the alt screen, e.g. when using vim. * Fixed issue with copying secrets when secret redaction is disabled. * kubectl completions now respect your kubeconfig, specified through environment variables or command line flag. * ssh commands with permission issues should no longer suggest sudo. * Fixed an issue with lazygit entering a blank screen. * \[macOS] Fixed a bug where Warp disk images volumes might not be unmounted after an update. * \[macOS] Improved robustness of autoupdate process. ### 2024.12.13 (v0.2024.12.10.15.55) [Section titled “2024.12.13 (v0.2024.12.10.15.55)”](#20241213-v0202412101555) **New features** * Prompt Suggestions may appear above the input, helping you activate Agent Mode quickly in scenarios where it might be helpful. Note this feature sends activity to an LLM to generate prompts, head to Settings > AI > Agent Mode if you’d like to turn it off. * Warp now has support for Claude 3.5 Sonnet and Haiku. Choose which model to use in the dropdown menu above your Agent Mode prompts. * Agent Mode can now leverage your Warp Drive contents to tailor responses to your personal and team developer workflows. * Warp has added a Shell Selector - a dropdown menu next to the ‘New tab’ button in the tab bar - to quickly pick from the shells available on your system. * Agent Mode can now suggest code changes in a built-in code editor. * \[macOS] You can now configure whether closing the last window quits the app (in Settings > Features). **Improvements** * Added settings to manage Warp’s AI integration and permissions. Visit Settings > AI to learn more. * Single-window launch configs can be launched into the active window from the launch config palette using cmdorctrl-enter. * You can now set `PS1` with `PROMPT_COMMAND` in bash. **Bug fixes** * Fixed an issue where the ‘Git Uncommitted File Count’ prompt chip did not work on fish on Linux. * Fixed highlighting for arguments in workflows with multibyte characters * Hitting ENTER within the Launch Config Save Modal will work as expected. * Fixed issue with copying secrets when secret redaction is disabled. ### 2024.12.11 (v0.2024.12.10.15.55) [Section titled “2024.12.11 (v0.2024.12.10.15.55)”](#20241211-v0202412101555) **New features** * Prompt Suggestions may appear above the input, helping you activate Agent Mode quickly in scenarios where it might be helpful. Note this feature sends activity to an LLM to generate prompts, head to Settings > AI > Agent Mode if you’d like to turn it off. * Warp now has support for Claude 3.5 Sonnet and Haiku. Choose which model to use in the dropdown menu above your Agent Mode prompts. * Agent Mode can now leverage your Warp Drive contents to tailor responses to your personal and team developer workflows. * Warp has added a Shell Selector - a dropdown menu next to the ‘New tab’ button in the tab bar - to quickly pick from the shells available on your system. * Agent Mode can now suggest code changes in a built-in code editor. * \[macOS] You can now configure whether closing the last window quits the app (in Settings > Features). **Improvements** * Single-window launch configs can be launched into the active window from the launch config palette using cmdorctrl-enter. * You can now set `PS1` with `PROMPT_COMMAND` in bash. **Bug fixes** * Fixed an issue where the ‘Git Uncommitted File Count’ prompt chip did not work on fish on Linux. * Fixed highlighting for arguments in workflows with multibyte characters * Hitting ENTER within the Launch Config Save Modal will work as expected. ### 2024.12.05 (v0.2024.12.03.08.02) [Section titled “2024.12.05 (v0.2024.12.03.08.02)”](#20241205-v0202412030802) **New features** * You can now share shared sessions directly with your Warp team, another Warp user, and non Warp users via a URL. * You can now share Warp Drive objects directly with others via email or a URL. * Padding in the alt-screen can now be manually adjusted. Defaults to no padding. **Improvements** * Improved PTY throughput by \~13% through more efficient dirty region computation. ### 2024.12.02 (v0.2024.12.02.15.50) [Section titled “2024.12.02 (v0.2024.12.02.15.50)”](#20241202-v0202412021550) **Bug fixes** * Warp no longer uses so much CPU. ### 2024.11.27 (v0.2024.11.27.01.55) [Section titled “2024.11.27 (v0.2024.11.27.01.55)”](#20241127-v0202411270155) **Improvements** * \[Agent Mode] Code outputs no longer show a confusing code diff UI. * You can now sort Warp Drive objects by type, with folders on top. **Bug fixes** * \[Agent Mode] Single-line code suggestions are no longer hidden behind the horizontal scrollbar. * Fixed a crash interacting with Env Vars in the command palette. ### 2024.11.25 (v0.2024.11.25.16.32) [Section titled “2024.11.25 (v0.2024.11.25.16.32)”](#20241125-v0202411251632) **Improvements** * \[Agent Mode] Code outputs no longer show a confusing code diff UI. * You can now sort Warp Drive objects by type, with folders on top. **Bug fixes** * \[Agent Mode] Single-line code suggestions are no longer hidden behind the horizontal scrollbar. * Fixed a crash interacting with Env Vars in the command palette. ### 2024.11.22 (v0.2024.11.22.18.28) [Section titled “2024.11.22 (v0.2024.11.22.18.28)”](#20241122-v0202411221828) **Improvements** * \[Agent Mode] Code outputs no longer show a confusing code diff UI. * You can now sort Warp Drive objects by type, with folders on top. **Bug fixes** * \[Agent Mode] Single-line code suggestions are no longer hidden behind the horizontal scrollbar. * Fixed a crash interacting with Env Vars in the command palette. ### 2024.11.26 (v0.2024.11.19.08.02) [Section titled “2024.11.26 (v0.2024.11.19.08.02)”](#20241126-v0202411190802) **New features** * You can now use Warp without login! **Improvements** * \[Agent Mode] Code outputs no longer show a confusing code diff UI. * You can now sort Warp Drive objects by type, with folders on top. **Bug fixes** * \[Agent Mode] Single-line code suggestions are no longer hidden behind the horizontal scrollbar. * Fixed a crash interacting with Env Vars in the command palette. * Fixed a bug where `command substitution: ignored null byte in input` would appear as output while using a Bash subshell. ### 2024.11.19 (v0.2024.11.19.08.02) [Section titled “2024.11.19 (v0.2024.11.19.08.02)”](#20241119-v0202411190802) **New features** * You can now use Warp without login! **Improvements** * \[Agent Mode] Code outputs no longer show a confusing code diff UI. * You can now sort Warp Drive objects by type, with folders on top. **Bug fixes** * \[Agent Mode] Single-line code suggestions are no longer hidden behind the horizontal scrollbar. * Fixed a crash interacting with Env Vars in the command palette. ### 2024.11.18 (v0.2024.11.18.16.37) [Section titled “2024.11.18 (v0.2024.11.18.16.37)”](#20241118-v0202411181637) **Improvements** * Added padding after an expanded Agent Mode requested command. * Improved the quality of autosuggestions. * Warp Drive workflow links now open in the active terminal session rather than a new tab. * On the web, Warp Drive workflows now have a button to quickly open the workflow in Warp’s desktop app. **Bug fixes** * Fixed Graphite CLI (`gt`) completions. * Fixed completion and syntax highlighting behavior for arguments containing backslashes in PowerShell. * Fixed an issue where opening Warp Drive in a browser could cause the tab to stop responding. ### 2024.11.12 (v0.2024.11.12.08.02) [Section titled “2024.11.12 (v0.2024.11.12.08.02)”](#20241112-v0202411120802) **Improvements** * Added padding after an expanded Agent Mode requested command. * Improved the quality of autosuggestions. * Warp Drive workflow links now open in the active terminal session rather than a new tab. * On the web, Warp Drive workflows now have a button to quickly open the workflow in Warp’s desktop app. * \[Linux] Increased the app icon size to match other apps. **Bug fixes** * Fixed Graphite CLI (`gt`) completions. * Fixed completion and syntax highlighting behavior for arguments containing backslashes in PowerShell. * Fixed an issue where opening Warp Drive in a browser could cause the tab to stop responding. * \[Linux] Tightened timeout for looking up the system color scheme at app startup to avoid hangs if the `org.freedesktop.portal.Desktop` D-Bus service is unresponsive. * \[macOS] Fixed a crash that can occur when starting the app or opening a new window. ### 2024.11.11 (v0.2024.11.05.08.02) [Section titled “2024.11.11 (v0.2024.11.05.08.02)”](#20241111-v0202411050802) **Improvements** * Fixes a bug where Warpifying subshells could crash if you had something typed in your input. * Renamed the Subshells tab to Warpify in Settings. **Bug fixes** * Fixed an issue where kubectl resource names wouldn’t complete given a prefix. * Fixed bug causing not all memory to be immediately freed when clearing the blocklist. * \[macOS] Fixed a crash that can occur when starting the app or opening a new window. ### 2024.11.05 (v0.2024.11.05.08.02) [Section titled “2024.11.05 (v0.2024.11.05.08.02)”](#20241105-v0202411050802) **Improvements** * Fixes a bug where Warpifying subshells could crash if you had something typed in your input. * Renamed the Subshells tab to Warpify in Settings. **Bug fixes** * Fixed an issue where kubectl resource names wouldn’t complete given a prefix. * Fixed bug causing not all memory to be immediately freed when clearing the blocklist. ### 2024.10.23 (v0.2024.10.29.08.02) [Section titled “2024.10.23 (v0.2024.10.29.08.02)”](#20241023-v0202410290802) **Bug fixes** * Improved command completions to no longer attempt to use error messages as valid options. * Fixed some kubectl completions not working as intended. ### 2024.10.17 (v0.2024.10.15.08.02) [Section titled “2024.10.17 (v0.2024.10.15.08.02)”](#20241017-v0202410150802) **New features** * Warp.dev has a fresh look today! Check out what’s new and read about the design process behind the launch: **Improvements** * Created a setting allowing focus to follow mouse hover (requested in issue [699](https://github.com/warpdotdev/warp/issues/699)). * Automatically switch to shell command input mode if accepting a shell command autosuggestion from Agent Mode. * \[macOS] Adjusted default font smoothing (Appearance > “Use thin strokes”) configuration to improve text legibility. **Bug fixes** * Alt-screen find doesn’t beachball when scrolling through find matches. * You can now select individual cells in the alt-screen. * All find matches are correctly highlighted in the alt-screen. * Hitting ENTER within the Launch Config Save Modal will work as expected. * Removed node prompt chip due to slow performance. * Fixed an issue on Linux distributions where Warp took a long time to start up. ### 2024.10.11 (v0.2024.10.08.08.02) [Section titled “2024.10.11 (v0.2024.10.08.08.02)”](#20241011-v0202410080802) **Improvements** * Tab key always accepts active autosuggestions in zero-state. * Command suggestions from Agent Mode are now ghosted autosuggestions instead of direct buffer text. * Warp now shows a warning when closing a tab with running commands or shared sessions. * New Agent Mode panes will open to a useful minimum width if the Warp window is big enough to support it. * Clearing the terminal input via ctrl-c will now also close the command search. * \[macOS] You can now access Warp Drive features from mac menus. * \[macOS] You can click the mouse middle-button to paste from the clipboard. **Bug fixes** * Agent Mode queries are now de-duplicated in up-arrow history and Command Search. * `ctrl-d` can now be used to signal EOF when the shell is bootstrapping. * Double-clicking the tab bar now correctly toggles maximizing the Warp window even when an AI block is present in the focused pane. * Hovering over the block insertion menu at the bottom of a notebook no longer causes Warp to hang. * Fixed crash when search result in alt screen is scrolled out of view. * Fixed broken `cmd-shift-R`/`ctrl-shift-R` keybinding for accessing the Workflows view. ### 2024.10.10 (v0.2024.10.08.08.02) [Section titled “2024.10.10 (v0.2024.10.08.08.02)”](#20241010-v0202410080802) **Improvements** * Tab key always accepts active autosuggestions in zero-state. * Command suggestions from Agent Mode are now ghosted autosuggestions instead of direct buffer text. * Warp now shows a warning when closing a tab with running commands or shared sessions. * New Agent Mode panes will open to a useful minimum width if the Warp window is big enough to support it. * Clearing the terminal input via ctrl-c will now also close the command search. * \[macOS] You can now access Warp Drive features from mac menus. * \[macOS] You can click the mouse middle-button to paste from the clipboard. **Bug fixes** * Agent Mode queries are now de-duplicated in up-arrow history and Command Search. * `ctrl-d` can now be used to signal EOF when the shell is bootstrapping. * Double-clicking the tab bar now correctly toggles maximizing the Warp window even when an AI block is present in the focused pane. * Hovering over the block insertion menu at the bottom of a notebook no longer causes Warp to hang. ### 2024.09.24 (v0.2024.09.24.08.02) [Section titled “2024.09.24 (v0.2024.09.24.08.02)”](#20240924-v0202409240802) **New features** * Powershell is now supported! Make `pwsh` your default shell for your user account or select `pwsh` in Settings > Features > Startup shell for new sessions. * You can now save and sync environment variable collections in Warp Drive. To learn more, see [Environment Variables](https://docs.warp.dev/features/warp-drive/environment-variables). * Your Agent Mode blocks and queries are now restored across sessions. **Improvements** * Secret redaction now applies to AI Blocks within Warp, in addition to Command Blocks. * New Agent Mode panes always open to the right. * You can now navigate the trash index via your keyboard. **Bug fixes** * `fish` config is no longer sourced twice during shell startup. * The first window after launching Warp will now use a custom window size if set. * When opening a launch configuration, Warp now respects restored and custom window sizes. ### 2024.09.17 (v0.2024.09.17.08.02) [Section titled “2024.09.17 (v0.2024.09.17.08.02)”](#20240917-v0202409170802) **New features** * \[Linux] Warp now supports Wayland. You can configure the window system in `Settings > Features > System`. **Improvements** * Adds a Command Palette action called “Export all Warp Drive objects” that enables bulk export of a Warp Drive. * Completion suggestions for git commit hashes are now sorted reverse-chronologically. * History shows the working directory in which you made an Agent Mode query. * Agent Mode Blocks are surfaced in Find. **Bug fixes** * Fixed an infinite loop bug that could lead to runaway memory usage and the application hanging. * Fixes a regression where the Setup Guide didn’t work. ### 2024.09.05 (v0.2024.09.10.08.02) [Section titled “2024.09.05 (v0.2024.09.10.08.02)”](#20240905-v0202409100802) **Improvements** * Links are now detected in Agent Mode responses. **Bug fixes** * Fixed an infinite loop bug that could lead to runaway memory usage and the application hanging. ### 2024.08.29 (v0.2024.08.27.08.02) [Section titled “2024.08.29 (v0.2024.08.27.08.02)”](#20240829-v0202408270802) **Bug fixes** * Link highlights now correctly disappear when making changes in alt-screen programs. ### 2024.08.22 (v0.2024.08.20.08.02) [Section titled “2024.08.22 (v0.2024.08.20.08.02)”](#20240822-v0202408200802) **New Features** * You can now specify a cursor color in Warp themes. **Improvements** * Warp now restores fullscreen windows to fullscreen. **Bug fixes** * \[macOS] Completions for commands now work when you type a command name containing capital letters. This does not apply to aliases. ### 2024.08.14 (v0.2024.08.13.08.02) [Section titled “2024.08.14 (v0.2024.08.13.08.02)”](#20240814-v0202408130802) **New Features** * New enums for Workflow arguments. Now you can set a list of suggested options for any argument in a workflow so it’s easier to fill in parameters correctly. To learn more, see [Workflows](https://docs.warp.dev/knowledge-and-collaboration/warp-drive/workflows#working-with-arguments). ### 2024.08.07 (v0.2024.08.06.08.01) [Section titled “2024.08.07 (v0.2024.08.06.08.01)”](#20240807-v0202408060801) **New Features** * You can now find your past Agent Mode queries in Command Search (ctrl-r). **Improvements** * Completions-as-you-type now works in AI input for filepath completions. **Bug Fixes** * Warp now recognizes more escape codes for toggling alternate screen mode. ### 2024.07.30 (v0.2024.07.30.08.02) [Section titled “2024.07.30 (v0.2024.07.30.08.02)”](#20240730-v0202407300802) **Improvements** * Now it’s easier to find and configure settings related to AI on the command line. You can enable / disable natural language detection or input hint text under Settings > AI ### 2024.07.24 (v0.2024.07.23.08.02) [Section titled “2024.07.24 (v0.2024.07.23.08.02)”](#20240724-v0202407230802) **New features** * You can now find AI queries from other sessions in up-arrow history. **Improvements** * Clicking an attached block on an AI block no longer affects your pending query’s context selection. * Clicking the terminal input box will no longer remove the blocks you selected as context. * Added support for smart selections in AI blocks. * Increased priority of command matches when searching for a workflow. **Bug fixes** * Opening file links with line and column numbers in Zed now works. ### 2024.07.19 (v0.2024.07.16.08.02) [Section titled “2024.07.19 (v0.2024.07.16.08.02)”](#20240719-v0202407160802) **Improvements** * Completions for git push origin now include tags in addition to branches. * Docker extension: The “Open in Warp” feature now requires you to run the command in order to open the Warpified Docker subshell. Attempts to open an invalid link will display an error toast. **Bug fixes** * Warp prompt text now respects custom line height settings. * Scroll positions are now stable when hitting block line limits ([1355](https://github.com/warpdotdev/warp/issues/1355)). * Fixed binaries listed directly in `PATH` being automatically executed when running commands in Bash. ### 2024.07.18 (v0.2024.07.16.08.02) [Section titled “2024.07.18 (v0.2024.07.16.08.02)”](#20240718-v0202407160802) **Improvements** * Completions for git push origin now include tags in addition to branches. * Docker extension: The “Open in Warp” feature now requires you to run the command in order to open the Warpified Docker subshell. Attempts to open an invalid link will display an error toast. **Bug fixes** * Warp prompt text now respects custom line height settings. * Scroll positions are now stable when hitting block line limits ([1355](https://github.com/warpdotdev/warp/issues/1355)). * Fish commands containing syntax errors now correctly “finish” the block. * Fixed binaries listed directly in `PATH` being automatically executed when running commands in Bash. ### 2024.07.11 (v0.2024.07.09.08.01) [Section titled “2024.07.11 (v0.2024.07.09.08.01)”](#20240711-v0202407090801) **New features** * Same line prompt. Now you can choose whether you’d like your prompt on a new line (Warp’s default) or on the same line with commands, like a classic terminal. If you’re using PS1, Warp will use the same line prompt setting to respect theme configurations. Visit Settings > Appearance > Prompt to configure your prompt style. To learn more, see [Prompts](https://docs.warp.dev/terminal/appearance/prompt#same-line-prompt). **Improvements** * Added support for completions while using Agent Mode input. * Semantic selection now works in AI blocks. * Shift+click now lets you select text for alternate screen apps in SGR mouse mode. **Bug fixes** * Pressing Esc in Vim insert mode no longer closes the history menu. * Made sure terminal context menus close when opening the settings modal. ### 2024.06.27 (v0.2024.06.25.08.02) [Section titled “2024.06.27 (v0.2024.06.25.08.02)”](#20240627-v0202406250802) **New features** * Warp’s new Pro plan includes higher AI requests for individuals or small teams. * Learn more at **Bug fixes** * Text selection in full screen apps will change as you scroll. * \[macOS] Meta shortcuts, e.g. `OPT-U`, `OPT-I`, will no longer be ignored. ### 2024.06.21 (v0.2024.06.18.08.02) [Section titled “2024.06.21 (v0.2024.06.18.08.02)”](#20240621-v0202406180802) **Improvements** * The glyph over the cursor will take on a high-contrast color to make sure it’s legible. * Dragging a word or line selection in a notebook now extends the selection. **Bug fixes** * Fixes a crash where text layout would not expect the BOM marker at the beginning of a string. * \[Linux] Fix middle-click paste doubling the text. ### 2024.06.20 (v0.2024.06.18.08.02) [Section titled “2024.06.20 (v0.2024.06.18.08.02)”](#20240620-v0202406180802) **Improvements** * The glyph over the cursor will take on a high-contrast color to make sure it’s legible. * Dragging a word or line selection in a notebook now extends the selection. **Bug fixes** * Fixes a crash where text layout would not expect the BOM marker at the beginning of a string. ### 2024.06.17 (v0.2024.06.11.08.02) [Section titled “2024.06.17 (v0.2024.06.11.08.02)”](#20240617-v0202406110802) **New features** * New Agent Mode in Warp AI: Use plain English on the command line to accomplish multi-step workflows. * Learn more at ### 2024.06.13 (v0.2024.06.11.08.02) [Section titled “2024.06.13 (v0.2024.06.11.08.02)”](#20240613-v0202406110802) **Improvements** * Brackets and quotes are now autocompleted in the workflow editor. * Improved support for editing multi-line workflows. ### 2024.06.06 (v0.2024.06.04.08.02) [Section titled “2024.06.06 (v0.2024.06.04.08.02)”](#20240606-v0202406040802) **Improvements** * Warp now supports Unicode emoji presentation selectors when rendering glyphs * Removed the default keybindings for Warp Drive object creation actions, in order to free up more keyboard shortcut options. You can still assign custom keybindings to these actions in Settings > Keyboard shortcuts **Bug fixes** * When editing with Vim visual line mode and the cursor is at the end of the line, operators will only affect the correct lines ### 2024.05.30 (v0.2024.05.28.08.02) [Section titled “2024.05.30 (v0.2024.05.28.08.02)”](#20240530-v0202405280802) **Improvements** * Warp now renders terminal text ANSI colors as specified by the theme without any dimming ### 2024.05.23 (v0.2024.05.21.16.09) [Section titled “2024.05.23 (v0.2024.05.21.16.09)”](#20240523-v0202405211609) **Bug fixes** * Fixed a bug where a terminal session could get stuck in a bad state if an SSH connection is lost while the alternate screen is in use (e.g.: tmux, TUI programs, pagers) * Fixed a bug where 00\~ and 01\~ characters could get erroneously added to user-submitted commands after an SSH connection is lost ### 2024.05.16 (v0.2024.05.14.08.01) [Section titled “2024.05.16 (v0.2024.05.14.08.01)”](#20240516-v0202405140801) **New features** * Team admins can now make their teams discoverable to colleagues from the same custom email domain. This feature is available under Settings -> Teams. **Bug fixes** * The prompt and command should no longer overlap the output (or each other) for multi-line commands in Bash versions earlier than 4.4—such as the default Bash installation for macOS. ### 2024.05.09 (v0.2024.05.07.08.02) [Section titled “2024.05.09 (v0.2024.05.07.08.02)”](#20240509-v0202405070802) **Bug fixes** * Vim-related settings no longer appear in the Command Palette when editing with Vim keybindings is disabled * Warp’s Input Editor now immediately reflects any changes to the Vim status bar settings * Fixed a bug when handling URLs with parentheses in notebooks and Warp AI ### 2024.05.02 (v0.2024.04.30.08.02) [Section titled “2024.05.02 (v0.2024.04.30.08.02)”](#20240502-v0202404300802) **Bug fixes** * In Notebooks, code block menus no longer overlap with rich text menus * Fixed an issue that could cause Warp to display an invisible/empty window * Fixed a crash that could occur when unindenting multiple lines within the Input Editor * Fixed a Vim Mode bug when “cutting word left” (and similar actions) while the (up-arrow) history menu is open * \[Linux] Fixed an issue where Warp would flicker on Intel UHD 620 drivers when using Vulkan due to a bug in specific versions of Mesa * \[Linux] Fixed a regression in input latency ### 2024.03.27 (v0.2024.04.23.08.01) [Section titled “2024.03.27 (v0.2024.04.23.08.01)”](#20240327-v0202404230801) **New features** * The free preview for Warp AI and Warp Drive for teams has ended. \[Learn about Warp’s new self-service plan] **Improvements** * Shared links to notebooks and workflows are now opened directly in Warp and no longer need to go through a browser **Bug fixes** * Warp now supports completions for directories that contain spaces when in a remote session * Warp’s notebook editor now only shows hint text when it’s in edit mode ### 2024.04.18 (v0.2024.04.16.08.02) [Section titled “2024.04.18 (v0.2024.04.16.08.02)”](#20240418-v0202404160802) **Improvements** * You can now navigate and expand folders in Warp Drive with left/right arrow keys **Bug fixes** * Middle-click now works even when the mouse is within the prompt area * Already-open notebooks no longer open in a new tab * Fixed an issue where autocd completions were incorrect for file paths starting with `~` * Opening a Workflow through a link now focuses it, even while in trash view * Fixed a bug handling carriage returns in notebooks, the markdown viewer, and Warp AI ### 2024.04.11 (v0.2024.04.09.08.01) [Section titled “2024.04.11 (v0.2024.04.09.08.01)”](#20240411-v0202404090801) **Improvements** * Improved Warp’s prompt performance for large repositories * When switching panes directionally, Warp now automatically selects the most recently focused pane in that given direction **Bug fixes** * Fixed a pane management bug where dragging a pane to a new location wouldn’t initiate the option to drop it there ### 2024.04.04 (v0.2024.04.02.08.02) [Section titled “2024.04.04 (v0.2024.04.02.08.02)”](#20240404-v0202404020802) **New features** * Notebooks in Warp Drive. Create and share interactive runbooks with your team. [Learn more](https://www.warp.dev/blog/notebooks-in-warp-drive) **Improvements** * You can now export workflows and notebooks from Warp Drive * Middle-clicking to paste now automatically focuses the Input Editor * Warp no longer automatically expands aliases that are escaped using a backslash * \[Linux] Adds support for Android Studio, DataGrip, DataSpell, Goland, Pycharm, Rider, Rubymine, and Sublime Text as external editors **Bug fixes** * \[Linux] Warp now case-sensitively parses top-level commands on Linux * \[Linux] Fixed an issue where middle-click paste could paste across multiple panes ### 2024.03.21 (v0.2024.03.19.08.01) [Section titled “2024.03.21 (v0.2024.03.19.08.01)”](#20240321-v0202403190801) **Bug fixes** * Symlinks to a directory are now properly treated as a directory instead of as a file * \[Linux] Warp’s windows are no longer escalated into an urgent state (tiling window managers) after a Warp URL is opened ### 2024.03.14 (v0.2024.03.12.08.02) [Section titled “2024.03.14 (v0.2024.03.12.08.02)”](#20240314-v0202403120802) **Improvements** * Warp now supports the primary selection protocol, which allows you to paste with a middle click. On platforms that don’t support this, Warp will read/write from the default clipboard. * You can now filter out unwanted lines from a block, using the new “invert filter” toggle in the block filtering menu * Continuous block selections are now rendered with a single border instead of a border around each individual block * The `` and `^` patterns are now supported in Warp’s regex search (find bar and block filtering) * \[Linux] The hotkey window now has a unique instance name on X11. **Bug fixes** * “Copy on Select” now works within alt-screens ### 2024.03.07 (v0.2024.03.05.08.02) [Section titled “2024.03.07 (v0.2024.03.05.08.02)”](#20240307-v0202403050802) **Improvements** * You can now adjust the number of lines the mouse wheel scrolls in Warp. Go to Settings > Features > General > Lines Scrolled by Mouse Wheel Interval to configure this setting. * You can now close the Warp window using the Command Palette (`SHIFT-CMD-W` for Mac). * You can now quit Warp using the Command Palette (“Quit Warp”) * \[Linux] Warp can now automatically hide the window’s traffic lights when using a tiling manager * \[Linux] Improved (a window’s) rounded corners when using a tiling manager * \[Linux] You can now move tabs left or right using keyboard shortcuts. Use `SHIFT-CTRL-PGUP` to move a tab to the left and `SHIFT-CTRL-PGDN` to move a tab to the right **Bug fixes** * Fixed a bug where Warp could crash because of an invalid Vim command * \[Linux] Fixed a bug where errors encountered while running `pacman-key` could lead to an invalid pacman repository configuration ### 2024.03.05 (v0.2024.03.05.08.02) [Section titled “2024.03.05 (v0.2024.03.05.08.02)”](#20240305-v0202403050802) **Improvements** * Improved Warp’s appearance and behavior when running in some tiling window managers. **Bug fixes** * Fixed crash that occurs when dragging the mouse. ### 2024.02.29 (v0.2024.02.27.08.01) [Section titled “2024.02.29 (v0.2024.02.27.08.01)”](#20240229-v0202402270801) **Improvements** * Added completion support for `dnf` * Configuring the global hotkey window settings (Quake Mode) now updates the window in real time * \[Linux] Can now `CTRL-CLICK` to open a file * \[Linux] Added support for IntelliJ, CLion, Webstorm, and PhpStorm **Bug fixes** * Fix issue with typeahead commands overlapping the prompt’s content * Command X-Ray now recognizes builtins and functions, hover over a command in the Input Editor to see the command description * Fixed an issue where the shell couldn’t accept pasted text when an rc file expected user input. * \[Linux] Modified pacman-key -r invocation during Arch Linux auto-update to be more robust * \[Linux] Fixed crash on Linux that could occur if device was missing a symlink from libX11.so to libX11.so.6 * \[Linux] Fixed issues where opening external links would cause Firefox 123 to use 100% CPU and never launch * \[Linux] X11 Users can now open links when default browser is firefox * \[Linux] Fix some global hotkey combinations crashing the app. ### 2024.02.26 (v0.2024.02.20.08.01) [Section titled “2024.02.26 (v0.2024.02.20.08.01)”](#20240226-v0202402200801) **New features** * Warp is now available for Linux! **Improvements** * Completions for apt-get, aptitude, and pacman * You can now type to search in the font picker in Settings > Appearance ### 2024.02.20 (v0.2024.02.20.08.01) [Section titled “2024.02.20 (v0.2024.02.20.08.01)”](#20240220-v0202402200801) **Improvements** * Completions for apt-get, aptitude, and pacman. ### 2024.02.16 (v0.2024.02.16.17.24) [Section titled “2024.02.16 (v0.2024.02.16.17.24)”](#20240216-v0202402161724) **New features** * Warp on Linux (Private Beta): Added support for the Input Mode Editor (IME). ### 2024.02.14 (v0.2024.02.14.15.46) [Section titled “2024.02.14 (v0.2024.02.14.15.46)”](#20240214-v0202402141546) **New features** * Warp on Linux (Private Beta): Added support for the Input Mode Editor (IME). # Changelog — 2025 > Warp release notes for 2025. Updates ship weekly, typically on Thursdays. Submit bugs and feature requests on our [GitHub board!](https://github.com/warpdotdev/Warp/issues/new/choose) ### 2025.12.17 (v0.2025.12.17.17.17) [Section titled “2025.12.17 (v0.2025.12.17.17.17)”](#20251217-v0202512171717) **Improvements** * Warp now specifies what different models were used for in the credit transparency footer. * You can choose whether forked conversations open in a split pane or new tab. * `warp mcp list`, `warp environment list`, and `warp agent profile list` now support plain-text and JSON output. * MCP server configurations are now displayed in integration details (i.e. `warp integration list`). * Added support for configuring MCP servers in integrations. **Bug fixes** * Fixed a bug where Oz CLI runs could get stuck trying to run a denylisted command. ### 2025.12.10 (v0.2025.12.10.08.12) [Section titled “2025.12.10 (v0.2025.12.10.08.12)”](#20251210-v0202512100812) **Improvements** * Added ‘Initialize codebase’ button to Code Review, which appears when you’re in an uninitialized repo, making it easier to set up codebase indexing and LSP. * Added a new sub-menu to the model picker for selecting the reasoning level of reasoning models. * Added syntax highlighting for Vue template files. * Added support for specifying custom models for agents, integrations, and scheduled agents using the `--model` flag. * Added support for custom HTTP headers in MCP Streamable HTTP or SSE server connections. * Added `/conversations` slash command with a clock-rewind icon to open the conversation history palette. * Warp integrations will more proactively signal if the agent is blocked. **Bug fixes** * Fixed a bug where, in `Settings > Billing and usage`, the credit denomination wasn’t set to the proper value for teams with auto-reload on. * The code editor now opens to the right of the active tab when “Choose a layout to open files in Warp” is set to “New tab”. * Fixed mouse reporting for apps that don’t use the alternate screen buffer, e.g. Radare2. ### 2025.12.03 (v0.2025.12.03.08.12) [Section titled “2025.12.03 (v0.2025.12.03.08.12)”](#20251203-v0202512030812) **Improvements** * The Oz CLI now displays more detailed information when the agent tries to take a prohibited action. * Allow dragging file paths from the Project Explorer into active terminal commands like claude code and gemini for referencing files and folders. **Bug fixes** * Fixed a bug that could cause unbounded memory growth when using Warpified subshells or the legacy (non-tmux) SSH Warpify implementation. * Fixed a bug that could cause `comm` errors to appear in Warpified subshells. * \[Windows] Fixed keybinding for “find in code editor.” This is now `CTRL-SHIFT-F` and configurable from Settings > Keyboard shortcuts. * Ensured that the Oz CLI is available automatically on macOS. * Fixed toast messages showing “Notebook” instead of “Plan” when taking actions on Plans in Warp Drive. ### 2025.11.19 (v0.2025.11.19.08.12) [Section titled “2025.11.19 (v0.2025.11.19.08.12)”](#20251119-v0202511190812) **New features** * MCP server configurations can now be shared with others on your team. You can install a server shared by your team with minimal configuration. * Warp now provides out-of-box MCP servers for common services like Github and Linear that can be installed and run with a single click. * Find now works in the code review pane. ### 2025.11.18 (v0.2025.11.18.12.24) [Section titled “2025.11.18 (v0.2025.11.18.12.24)”](#20251118-v0202511181224) **New features** * [Full Terminal Use](https://docs.warp.dev/agent-platform/warp-agents/full-terminal-use): Let the agent use the terminal as you would: interact with REPLs, debuggers, and full-screen apps like `top`. Warp is the only product on the market with Full Terminal Use capabilities. * [`/plan`](https://docs.warp.dev/agent-platform/warp-agents/planning): do spec-driven development in Warp. Work with an agent to align on an implementation plan that can be saved, versioned, and even attached to a PR for teammates. * [Interactive Code Review](https://docs.warp.dev/agent-platform/warp-agents/interactive-code-review): Review an agent’s code like you would a teammate’s, directly in Warp, and ask the agent to address the comments. * [Slack and Linear integrations](https://docs.warp.dev/agent-platform/cloud-agents/integrations):\*\* Ask the agent to get to work from the tools you already use, track their progress, and take the wheel via live session sharing. * Warp’s Agents can now [search the web](https://docs.warp.dev/agent-platform/warp-agents/web-search) to retrieve information, when relevant. This capability is configurable via Agent Profiles. ### 2025.11.12 (v0.2025.11.12.08.12) [Section titled “2025.11.12 (v0.2025.11.12.08.12)”](#20251112-v0202511120812) **Improvements** * \[Vim mode] Paragraph text objects are now supported, e.g. `dip` to delete a paragraph. * \[Vim mode] In terminal mode, press `K` over part of a command to inspect it. * Agent notifications now reference conversations’ titles instead of their queries. **Bug Fixes** * The copy link button now works as expected after shared sessions have been closed. ### 2025.11.05 (v0.2025.11.05.08.12) [Section titled “2025.11.05 (v0.2025.11.05.08.12)”](#20251105-v0202511050812) **New Features** * From the code review panel, add file diffs or the entire diff set as context to an agent conversation. **Improvements** * Warp now defaults to requiring approval before the agent will execute a command. * Shared session links will open in a new tab by default, rather than a new window. * Display summarization tokens when conversation summarization is triggered. ### 2025.10.29 (v0.2025.10.29.08.12) [Section titled “2025.10.29 (v0.2025.10.29.08.12)”](#20251029-v0202510290812) **Improvements** * Display conversation summaries when summarization is triggered. * Added completions for the Oz CLI. * Updated community links from Discord to Slack throughout the app. **Bug Fixes** * Reduce padding on restored Agent Mode blocks and expanded shell commands. * Add support for delete key in vim mode in code editors. * Fix rendering for multi-line Agent Mode shell commands. ### 2025.10.22 (v0.2025.10.22.08.13) [Section titled “2025.10.22 (v0.2025.10.22.08.13)”](#20251022-v0202510220813) **New Features** * Warp will suggest new unit tests in addition to code fixes via Suggested Code Banners **Improvements** * Fixed an issue where the model specs menu would get cut off. **Bug Fixes** * Fixed the close icon from becoming too small on the Warp Drive notebook viewer. * Fixed an issue where the CLI would report invalid debug IDs in its troubleshooting output. ### 2025.10.15 (v0.2025.10.15.08.12) [Section titled “2025.10.15 (v0.2025.10.15.08.12)”](#20251015-v0202510150812) **New Features** * Warp now supports scaling the entire application. Change the zoom level in `Settings > Appearance > Window` or by pressing `CMD-+` on macOS or `CTRL-+` on Windows / Linux. **Improvements** * The code review pane can now show diffs against other base branches. * Added confirmation dialog when cancelling AI summarization requests. * You can now expand Suggested Code Diffs further on down arrow. * Restore closed panes using `CMD-SHIFT-T` or `CTRL-ALT-T` on Windows / Linux within 60 seconds of them being closed. * Added shell completions for the Oz CLI. * Warp Drive Environment Variables are now supported for Warp for Windows (PowerShell, Git Bash, and WSL). * Enriched the model picker to include detailed specs of each model’s intelligence, speed and cost. **Bug Fixes** * Fixed the custom window size setting not reliably applying on startup. ### 2025.10.08 (v0.2025.10.08.08.12) [Section titled “2025.10.08 (v0.2025.10.08.08.12)”](#20251008-v0202510080812) **Improvements** * Added the ability to sort team members by usage in `Settings > Billing and usage`. * Added UI indication of when Agent Mode conversation summarization is in progress, with a cancellation confirmation dialog. * Made the sizing for headings consistent across all collapsible blocks. * `@` menu no longer appears when running JS package manager subcommands, like `yarn workspace @org/package add`. * \[macOS] Resolved an issue re-mapping keybindings that conflict with macOS keybindings. **Bug Fixes** * Agent Mode requested command previews now only show the first line of multi-line commands. * Removed misleading “auto-approve” button while Warp is generating a fix for failed terminal commands. ### 2025.10.01 (v0.2025.10.01.08.12) [Section titled “2025.10.01 (v0.2025.10.01.08.12)”](#20251001-v0202510010812) **Improvements** * Editing suggested file changes now takes place in the same pane, instead of a new tab. * When using the `@` context menu outside of a repo, current folder’s contents are now listed. * The code mode file picker will now display gitignored files. * \[macOS] Warp now stores session restoration data in a more-secure application container. ### 2025.09.24 (v0.2025.09.24.08.11) [Section titled “2025.09.24 (v0.2025.09.24.08.11)”](#20250924-v0202509240811) **New features** * You can now create new files directly in Warp. Search “New File” in the command palette. macOS users can find it in the app menu under “File”. **Improvements** * Change the “Reject” label to “Refine” for code diffs and plans. They’re functionally the same, though we think this will clear up some confusion over what hitting “Reject” will do. * Added realtime form validation to Environment Variables when secret redaction is enabled. * Avoid showing the `@` context completions menu when typing a package name. This covers common installers for JS, Python, Ruby, Go, PHP, and more. * Add an “auto-approve” option with a keyboard shortcut for requested commands and MCP tool calls. This makes it easier to accept a command and auto-approve future commands in a single button. **Bug fixes** * Fixed error with fish shell v4. * Avoid showing multiple “stopped task” banners when toggling a resumed conversation back to stopped before the agent begins responding. * Fix input problems with Russian on PowerShell. ### 2025.09.17 (v0.2025.09.17.08.11) [Section titled “2025.09.17 (v0.2025.09.17.08.11)”](#20250917-v0202509170811) **New Features** * Warp agents are now available via the command line! [Learn more](https://docs.warp.dev/reference/cli) * Added support for custom Regex names in Enterprise Secret Redaction. **Improvements** * The @ context menu can now be activated outside of Git repositories (for actions such as attaching blocks/workflows), when in autodetection or AI input mode. * move the auto-approve button alongside the agent “stop” button for easier access. * Move the “stop” button alongside the “Warping…” indicator. This restores the “stop” button to classic input users, and offers a more intuitive experience for universal input users. * Added right-click context menu to code review pane with split pane controls. * Files selected in the file tree now open in a preview mode until interacted with. * Warp’s agent now shows reasoning traces from reasoning models. * Ctrl-c during a long running command run by the agent will also stop the agent, not just the command. **Bug Fixes** * Fixed nested lists in agent markdown output sometimes not rendering properly. * Fix slow scrolling on macOS Tahoe. * Fix todo lists overflowing off of the screen for 10 or more items. * Fix code review maximize button appearing outside of split pane mode. * Fix the stop button unexpectedly disappearing when accepting the “start a new conversation” suggestion. ### 2025.09.10 (v0.2025.09.10.08.11) [Section titled “2025.09.10 (v0.2025.09.10.08.11)”](#20250910-v0202509100811) **Improvements** * Added support for ignoring input suggestions. Click the X next to an item in your up-arrow history menu to hide that from showing up again. You can also enable the `Show autosuggestion ignore button` setting to add an X to autosuggestions directly in your input. * Git UI detects more changes in git worktrees. * You can now rename/delete items in the file picker and open them with the system file explorer. * Combine “refine” and “cancel” buttons into a single “reject” button. This lets you give feedback on code diffs, commands, and plans with a single button. * You can now switch node versions by clicking on the node version chip. * Added a “New Agent” button to the agent management panel to start a new agent conversation more easily.” **Bug fixes** * Fixed an issue where agent output in a code block could be inserted at the wrong place. * Fixed code review diff buttons incorrectly receiving mouse events. * Avoid auto-expanding an agent’s requested commands while you are using voice dictation. * Add back the auto-approve button for classic input mode. * Fixed keyboard navigation of chip menus in the input while an agent is running. * Properly reset context when user sends query to agent. ### 2025.09.03 (v0.2025.09.03.08.11) [Section titled “2025.09.03 (v0.2025.09.03.08.11)”](#20250903-v0202509030811) **Improvements** * Added support for rendering H4-H6 in markdown. ### 2025.09.01 (v0.2025.09.01.20.54) [Section titled “2025.09.01 (v0.2025.09.01.20.54)”](#20250901-v0202509012054) **New features** * Revert diff hunks directly from the Code Review Pane. * Add lines of a file to the context of a conversation from the Warp code editor. * You can now search and restore Agent conversations in your history using the `conversations:` prefix. * You can now search and navigate to indexed codebases using the `repos:` prefix. **Improvements** * Voice transcriptions are no longer cut off when unfocusing an input editor. * You can now select the $EDITOR environment variable as the default application for opening file links. * Added new header treatment for unfocused Warp windows. * \[macOS] A new dock icon option to celebrate Code Country - the Cow icon! (`Appearance > Icon` to change) * Pasting images in the terminal input switches to Agent Mode and attaches the image as context. * Added support for the Streamable HTTP transport for MCP servers. **Bug fixes** * \[Windows/Linux] Fixed keybinding conflict for split pane down action for the Input, when a code diff is not active. * Fixed tab tooltips displaying unwanted leading and trailing whitespace. * Pressing the up key while the model picker is open no longer opens the command history. Opening the model picker while the command history is open now closes the command history. ### 2025.08.27 (v0.2025.08.27.08.11) [Section titled “2025.08.27 (v0.2025.08.27.08.11)”](#20250827-v0202508270811) **New Features** * [Agent Profiles](https://docs.warp.dev/agent-platform/warp-agents/agent-profiles-permissions#agent-profiles): define how your agent operates. * New pane to view changes to a Git repository. * Files now open in a tabbed viewer. * Syntax highlighting for Scala files in Warp. **Bug Fixes** * Fix paths not inserted when pasted images are not attached. ### 2025.08.20 (v0.2025.08.20.08.11) [Section titled “2025.08.20 (v0.2025.08.20.08.11)”](#20250820-v0202508200811) **New features** * [Suggested Code Diffs](https://docs.warp.dev/agent-platform/warp-agents/active-ai#suggested-code-diffs) - Warp now intelligently suggests the appropriate fixes for any simple errors encountered in the command line e.g. compiler errors. Head to `Settings > Active AI` to toggle this feature. **Improvements** * Added setting to hide fixed prompt suggestions. * Updated default input type from ‘Classic’ to ‘Universal’. * Improve the styling and usability of tabs for narrow windows. **Bug fixes** * Fix failures to start zsh sessions when using prezto. * The agent status indicator no longer disappears while a command is running. * Selecting a workflow will correctly close the workflows menu. * Don’t auto-attach image if file pasted as plaintext. * Fixed issue with drag-drop images. * Fixed display of completions that may have included special characters. ### 2025.08.13 (v0.2025.08.13.08.12) [Section titled “2025.08.13 (v0.2025.08.13.08.12)”](#20250813-v0202508130812) **New Features** * Agent Mode now displays interactive code blocks when referencing snippets from your codebase. You can easily copy the snippet, add the snippet as Agent Mode context, or open the file in Warp’s built-in editor. * Agent Mode now creates and tracks task lists for more complex workflows. See [Agent Task Lists](https://docs.warp.dev/agent-platform/warp-agents/task-lists). * Added support for defining project-scoped rules with a WARP.md file. See [Rules](https://docs.warp.dev/knowledge-and-collaboration/rules#project-scoped-rules). * Added Slash Commands (/) in Agent Mode or Auto-Detection Mode to quickly run built-in actions or saved prompts without leaving the input field. See [Slash Commands](https://docs.warp.dev/agent-platform/warp-agents/slash-commands). **Improvements** * Added syntax highlighting for SQL in Warp’s code editor. * Added button to dismiss suggestions footer. * \[Linux and Windows] Added support for drag-dropping multiple images. * New files in Warp open in a pane by default. You can customize this behavior via `Settings > Features > General > Choose a layout to open files in Warp`, where you can switch between opening files in a pane or a new tab. * Input stays in Agent Mode after an image is attached, instead of switching to shell mode. **Bug Fixes** * Fixed behavior when clicking Agents chip in Classic input mode. * Repository-scoped Warp features are now available in git worktrees. * Fixed drag-drop of images for long-running commands (eg Claude Code, vim). * \[Linux and Windows] Fixed attaching images from pasted files. * Fixed “Find in selected block” feature after clicking on an active running block. * Fixed text overlap on narrow panes with Classic Warp Prompt with Same Line Prompt. * \[macOS] Fixed a bug that would cause text to disappear for very long Agent Mode prompts. ### 2025.08.06 (v0.2025.08.06.08.12) [Section titled “2025.08.06 (v0.2025.08.06.08.12)”](#20250806-v0202508060812) **New Features** * GPT-5 is now available to all users. Use the model selector in the input bar to try it yourself. * \[macOS] Added the ability to attach images as context by drag-and-dropping them or pasting from your clipboard. **Improvements** * You can now open any files within Warp’s editor (including txt/csv files)! * Warp can now edit Bazel files. * Warp can now edit `.bashrc` and `.zshrc` files. * Added `Always show secrets` to Secret Redaction for a less obtrusive secret redaction mode. * Added reset time to the Billing and usage menu. **Bug Fixes** * Fix fish version <= 3.7 when vi keybindings were activated. * Fixed bug affecting the “Open in Markdown Viewer by default” setting, you can use this setting to determine whether you’d like to view/edit MD files in Warp by default. * Fixed an issue where typeahead for the next command could be lost if you typed really quickly after hitting enter on the previous command. * Resolved an issue where stopping voice recording via the button would interrupt transcription. ### 2025.07.30 (v0.2025.07.30.08.12) [Section titled “2025.07.30 (v0.2025.07.30.08.12)”](#20250730-v0202507300812) **New Features** * You can now set a configurable block size limit for higher scrollback limits! Head to `Settings > Features > Session > Maximum rows in a block` to configure. * \[Linux] Added support for pasting images as context. **Improvements** * The “Open in Warp” banner now supports code files. * When using Agent Mode, user-configured redaction rules are now applied to the contents of diffs and files, in addition to terminal blocks. * Add SHIFT-ENTER keybinding. Claude Code users can use this to add linefeeds to their prompt. * Added an overflow menu button in the top right of AI blocks for copying contents. **Bug Fixes** * Deleted files no longer appear in the @-context selection box. * Users with Turkish locale will no longer see an extra letter “i” between commands. * \[Windows] Restored windows will no longer be positioned with the title bar above the top of the display. ### 2025.07.23 (v0.2025.07.23.08.12) [Section titled “2025.07.23 (v0.2025.07.23.08.12)”](#20250723-v0202507230812) **New Features** * \[Windows] Added support for pasting images from Clipboard into Agent Mode context. **Improvements** * Added image filename when pasting images into Agent Mode context. * Added support for restarting MCP servers when Warp restarts. * Added support for copying AI block and conversation contents via the context menu. * Added Node.js prompt chip. **Bug Fixes** * Fixed a bug where attaching a block as AI context would reset the input state. * Fixed a spacing issue with horizontal scrollbars in agent planning view. * Added support for auto-expanding manually executed Agent Mode suggested commands. * Fixed a bug where Warp would hang while updating code symbols in the @-context menu. * Modified secret redaction regexes to be case sensitive. Use a `(?i)` prefix to make your regex case insensitive. * Modified the Universal Input to no longer exit a conversation via “backspace”. ### 2025.07.16 (v0.2025.07.16.08.12) [Section titled “2025.07.16 (v0.2025.07.16.08.12)”](#20250716-v0202507160812) **New Features** * \[macOS] Support pasting images from clipboard into Agent Mode context. * Migrated Warp’s built-in set of Secret Redaction regexes into user’s regexes, giving users more fine-grained control over their secret redaction. * Added support for Find and Replace using `CMD-F` when viewing diffs or editing files in the built-in code editor. **Improvements** * Removed lock icon from Secret Redaction in favor of asterisks when ligatures are enabled. * Added individual keybinding shortcuts to change input modes. **Bug Fixes** * Fixed an issue where the hover tooltip for disabled prompt suggestions either didn’t render at all or was incredibly hard to read. * Fixed the background color of inline code in restored AI blocks. ### 2025.07.09 (v0.2025.07.09.08.11) [Section titled “2025.07.09 (v0.2025.07.09.08.11)”](#20250709-v0202507090811) **New Features** * New secret redaction strikethrough UI. Comes with new `Settings > Privacy > Hide secrets in block list` setting that defaults to off. **Improvements** * You can now resume stopped AI conversations: `CTRL-C` to stop and `CMD-SHIFT-R` to resume on macOS or `CTRL-SHIFT-R` on Windows and Linux. * Code Diff view’s default Edit and Revise keybindings changed and made configurable. * Added syntax highlighting for PowerShell, Kotlin and Swift. **Bug Fixes** * Fixed an issue with `.inc` file chunking. * Clicking on an active, long running block will no longer select the block, but focus the input. ### 2025.07.02 (v0.2025.07.02.08.36) [Section titled “2025.07.02 (v0.2025.07.02.08.36)”](#20250702-v0202507020836) **New features** * Tab close button can now be set to the left. **Improvements** * Added syntax highlighting for TOML, PHP, Lua, Ruby, and Groovy (with Java syntax). * Added conda chip support to new Universal Input prompt. * Increased color contrast on tabs. * Added “Upgrade” menu item for free users and “Billing and Usage” menu item for paid users in the user menu for easier access to subscription management. **Bug fixes** * When AI is disabled, ESC should no longer enter Agent Mode. * Fixed an issue on WSL where files created by Agent Mode would have CRLF line endings. * \[macOS] Tweaked autoupdate logic to more reliably remove old applications off disk. * Fixed “Manage plan suggestion setting” link. ### 2025.06.25 (v0.2025.06.25.08.12) [Section titled “2025.06.25 (v0.2025.06.25.08.12)”](#20250625-v0202506250812) **New Features** * Git branch and directory chip now are searchable. **Improvements** * Added support for HCL syntax highlighting in Terraform files. **Bug Fixes** * Fixed potential crash when displaying context chips with Unicode characters in file paths. * Fixed a rendering issue with line numbers in suggested diffs. * Attach context chip no longer appears if there is no context you can attach. ### 2025.06.20 (v0.2025.06.20.22.47) [Section titled “2025.06.20 (v0.2025.06.20.22.47)”](#20250620-v0202506202247) **New Features**\ \ **Warp 2.0 is here - The Agentic Development Environment** Built from the ground up for agentic workflows, Warp is the most powerful tool for prompting, coding, and collaborating with multiple agents. **Multithread yourself with agents** * Launch intelligent tasks (agents) with a prompt. Agents gather context using CLI commands, MCP, Warp Drive, and Codebase Context. * New Agent Management Panel to monitor, multitask, and intervene across multiple agents. * Set autonomy controls and get notified when agents need your help. **A state-of-the-art coding platform** * 70% on SWE-bench, #1 on Terminal-Bench — the highest quality coding agent available. * Codebase Context: Warp indexes and understands your codebase, allowing you to debug and write code faster without storing any code on Warp’s servers. * Review and edit diffs directly in Warp’s native code editor. **Still a great command-line**\n- * A new Universal Input: run commands or prompt agents from a single interface. Lock into command mode or Agent Mode, or let Warp detect automatically. * Choose your model, continue a conversation, attach images, link URLs, or reference files using `@`. * Modern, IDE-like terminal experience with completions, predictions, and mouse support, all built natively in Rust for performance. **Context for your teammates and agents** * A knowledge store where you can configure MCP, define Rules, and store shared commands, notebooks, env vars, and prompts as context. All of this comes with higher AI usage limits on our Pro and Turbo plans, plus new pay-as-you-go overages for continued access to premium models.\ \ **Watch the full Warp 2.0 launch event →** [**warp.dev/future**](https://warp.dev/future) ### 2025.06.11 (v0.2025.06.11.08.11) [Section titled “2025.06.11 (v0.2025.06.11.08.11)”](#20250611-v0202506110811) **New Features** * You can now attach images as context for Agent Mode! Simply use the image icon and select the files you wish to attach. **Improvements** * \[Linux] Added support for standard installed Zed and Zed Preview as default code editors. * \[macOS] Added support for Zed Preview as a default code editor. * Added syntax highlighting support for TSX and JSX. * Increased visibility of non-focused diff hunks when navigating diffs. * New Agent Mode output will no longer force-scroll. **Bug Fixes** * Fixed keybinding being missing for editing requested commands. * Removed keybindings for zero-state prompt suggestions, to avoid conflicting with tab switching keybindings. ### 2025.06.04 (v0.2025.06.04.08.11) [Section titled “2025.06.04 (v0.2025.06.04.08.11)”](#20250604-v0202506040811) **New Features** * Sonnet 4 is now an available model (enabled by default in the “auto” model). **Improvements** * Press the hovering fast-forward button to auto-execute all Agent actions until the task completes. * Added ability to share session via `RIGHT-CLICK` on tab. * You can now give the Agent permission to auto-execute MCP tool calls. **Bug Fixes** * Fixed an issue where Agent Mode would sometimes not find untracked files in Git repos. * Fixed Agent Mode file editor randomly scrolling to the first line of a file. ### 2025.05.28 (v0.2025.05.28.08.11) [Section titled “2025.05.28 (v0.2025.05.28.08.11)”](#20250528-v0202505280811) **New Features** * Added MCP server support. It’s now possible to extend Agent Mode’s capabilities using programs that support the [Model Context Protocol](https://docs.warp.dev/knowledge-and-collaboration/mcp). ### 2025.05.21 (v0.2025.05.21.08.11) [Section titled “2025.05.21 (v0.2025.05.21.08.11)”](#20250521-v0202505210811) **New Features** * Set new Agent Mode permissions around executing commands, reading files, coding, and planning in AI settings. **Improvements** * You can now choose the coding model behind Agent Mode. * Agent Mode conversations can now be paused via a hovering control panel in the right corner. * Improved maximum block output capacity to 50k lines. **Bug Fixes** * Fix edit icon positioning for shared sessions. ### 2025.05.14 (v0.2025.05.14.08.11) [Section titled “2025.05.14 (v0.2025.05.14.08.11)”](#20250514-v0202505140811) **Improvements** * Introduced refining functionality for requested commands. * Added ability to continue previous Agent Mode conversations directly from response blocks. * Overhauled the editing experience for suggested plans. * Renamed input auto-detection setting to natural language detection in Command Palette for better clarity. * Zero-state prompt suggestion chips are now horizontally clipped instead of being individually shrunk. **Bug Fixes** * Fixed incorrect ordering in history of executed commands and Agent Mode queries. * Copying text from Agent Mode plans and suggested code changes now works more reliably. * \[Windows] Made some changes to reduce false-positives from virus scanners. ### 2025.05.07 (v0.2025.05.07.08.12) [Section titled “2025.05.07 (v0.2025.05.07.08.12)”](#20250507-v0202505070812) **Improvements** * Redesigned env var collection block UX. * Added ability to embed Warp Drive Prompts inside Notebooks. * Added AI block loading animation. * Added ability to select and continue previous Agent Mode conversations. * \[macOS] Improved time to update and relaunch Warp. **Bug Fixes** * Fixed a bug where escape was clearing autosuggestions in Vim’s insert mode. * Stopped showing an unexpected block in the planning output for o3. * \[Windows] Fixed a bug when hovering symlinks in WSL sessions. * Fixed terminal input remaining hidden after cancelling an env var block. * Prevented unexpected empty code fences in Agent Mode when using Gemini 2.5 Pro or o3. ### 2025.04.30 (v0.2025.04.30.08.11) [Section titled “2025.04.30 (v0.2025.04.30.08.11)”](#20250430-v0202504300811) **New Features** * Added desktop notifications for Agent Mode. Now, you can be notified when an agent completes a task, or when an agent needs your attention to continue (i.e. to review a command, to run an unsafe command, etc). You can configure these settings from `Features > Notifications`. **Improvements** * Agent Mode is now more robust at applying code diffs. * Redesigned requested commands UX. * Improved readability for “needs password prompt” desktop notifications. ### 2025.04.23 (v0.2025.04.23.08.11) [Section titled “2025.04.23 (v0.2025.04.23.08.11)”](#20250423-v0202504230811) **Improvements** * Restored Agent Mode conversations can now be continued. * Agent Mode now has access to a filepath search tool for coding tasks. * Improved the reliability and positioning of suggestion dialogs for rules and Agent Mode workflows. * We reworked the command palette search to make it more useful. **Bug Fixes** * Fix XML parse errors complaining that a “thought” cannot be empty. * \[Windows] Fixed an issue where Agent Mode would fail to search when in WSL or Git Bash. * Show “copy” button and other text selection tools when right clicking selected environment variable text. * Fixed old shortcuts icon appearing in new tab page, if recommended AI prompts are disabled. * Fish commands containing syntax errors now correctly “finish” the block. ### 2025.04.16 (v0.2025.04.16.08.11) [Section titled “2025.04.16 (v0.2025.04.16.08.11)”](#20250416-v0202504160811) **New features** * After editing a code diff, you will now be returned to your original Agent Mode conversation. * Commands with certain invalid arguments will no longer be suggested, such as file paths, git branches, and docker images. * \[Windows/Linux] You can now open launch configurations in the current window with `SHIFT-ENTER` or `CTRL-ENTER` on the Command Palette. * Added more default regexes for Secret Redaction, pertaining to AI API keys. * Typing `ESC` in the terminal input editor now clears any Autosuggestions. **Bug Fixes** * Fixed issue with rendering performance for file links in AI output. * Fixed an issue that causes Warp to crash when Agent Mode outputs broken links. * New tab page no longer falls back to email if display name is not set. * Fixed prompt chips not being clickable in new session with prompt pinned to top. * Agent Mode now properly greps for queries containing double quotes. ### 2025.04.09 (v0.2025.04.09.08.11) [Section titled “2025.04.09 (v0.2025.04.09.08.11)”](#20250409-v0202504090811) **New features** * Recommended AI prompts are shown in new tabs, go to Settings > Features to disable. **Improvements** * Agent Mode is now better at searching for exact function / symbol / etc. names in your code. * Fix text selection for environment variable blocks. * You can now attach select text in a code block as the Agent Mode context. * Warp now supports marked text in the IME (non-English keyboards). * Make text selectable for non-expandable command outputs (ex. failed agent tasks). * Zero-state chips are no longer shown when entering AI input with a non-empty input buffer. **Bug fixes** * Fixed a bug that prevented copying of selected text of a code block when Agent Mode is enabled. * Fixed a bug that allows a selection in the code block and a selection on the text simultaneously. * \[macOS] Fixed shells installed via Homebrew not appearing in the list of available shells. ### 2025.04.02 (v0.2025.04.02.08.11) [Section titled “2025.04.02 (v0.2025.04.02.08.11)”](#20250402-v0202504020811) **New features** * Get early access to unreleased and experimental features with [Warp Preview](https://docs.warp.dev/support-and-community/community/warp-preview-and-alpha-program). **Improvements** * Improved login item management to respect when users manually remove Warp from login items in System Preferences. * The input editor now supports `CMD-SHIFT-UP/DOWN` on macOS or `CTRL-SHIFT-HOME/END` on Windows/ to move and select to the top/bottom of the text buffer. * Removed 3-hour conversation timeout, allowing AI conversations to remain active indefinitely. * Show a small popup when users who are at AI limits have their quota reset. * Display a notification when AI request quota resets after hitting the limit in the previous billing cycle. * \[Windows] Added “Open Warp in new tab / window” item for folders in the File Explorer context menu under “Show more options”. **Bug fixes** * Minor fixes for iTerm and Kitty images. * Fixed regression related to using keyboard shortcuts to navigate a command in an empty split pane. * Fixed some issues with Agent Mode failing to read files. * Click targets in scroll views should more reliably click while moving the mouse. * \[Linux] Window corners are correctly rounded with themes having background images. * Fix a few common failure modes for Agent Mode response deserialization errors. ### 2025.03.26 (v0.2025.03.26.08.10) [Section titled “2025.03.26 (v0.2025.03.26.08.10)”](#20250326-v0202503260810) **New features** * Kitty Image Protocol is now supported on macOS and Linux! **Improvements** * Agents may suggest using Dispatch to create a plan for complex tasks. You can disable suggestions to create plans under `Settings > AI > Dispatch`. * You can now resume auto-execution of a previously dispatched plan if your follow-up query is set to “Dispatch”, instead of creating a new plan. * Added a keyboard shortcut to accept the most recent command correction. * Zero-state suggestions are no longer shown when using a saved Prompt or past AI query. * Tabs will not resize while hovered, making closing multiple tabs easier. * The warning dialog for closing sessions now responds to the `ENTER` and `ESC` keys. * Selected text within Agent responses can now be copied via the `RIGHT-CLICK` menu. * \[Windows/Linux] You can now toggle whether a block is selected using `CTRL+CLICK`. **Bug fixes** * Fixed an issue that caused Agent Mode blocks to be incorrectly highlighted when performing rectangular selection. * Fixed an issue where duplicate cloud preferences could be created during sync operations. * Fixed keyboard shortcut padding for prompt suggestions. * Fixed color contrast issues with light themes for the Pair & Dispatch chip in Prompt Editor. * Agent Mode will no longer default to Windows-style line endings when creating a new file on macOS or Linux. * PowerShell sessions will start even if the profile has a terminating error. * The numpad `ENTER` key now behaves like the `ENTER` key in Agent Mode. * \[macOS] Fixed a scenario where Warp would beachball while updating. * \[Windows] In WSL, show completions for symlinked files. * \[Windows] Fixed completions with `.exe` suffixes. * \[Windows] Fixed setting Git Bash custom shell paths. ### 2025.03.12 (v0.2025.03.12.08.02) [Section titled “2025.03.12 (v0.2025.03.12.08.02)”](#20250312-v0202503120802) **New features** * Agent Mode output is now rendered with Markdown formatting. * You can now change the font used for Agent Mode output (Settings > Appearance). **Improvements** * \[Windows] Significantly improved pseudoconsole throughput (\~3x improvement). * The Agent Mode model will now automatically select the best model based on your specific task. * Ordered lists in Markdown now uses alphabetical or Roman numeral labels when nested. * \[Windows] We now search more locations for a PowerShell executable. * Reduced the size of Markdown headings. **Bug fixes** * Control whether Warp starts at login via a setting under Settings > Features > Start Warp at login (macOS only). * \[Windows] Fixed an issue where dynamic enums commands weren’t being executed. * Fixed a bug with the mouse cursor when hovering over buttons. * Fixed a bug that causes high CPU load with codebase context. ### 2025.03.05 (v0.2025.03.05.08.02) [Section titled “2025.03.05 (v0.2025.03.05.08.02)”](#20250305-v0202503050802) **New features** * iTerm Image Protocol is now supported on macOS and Linux! * \[macOS] Warp now starts at login (can be disabled in System Settings > Login Items & Extensions). **Improvements** * Input mode automatically returns to command mode when a command is detected in an AI follow-up request. (Only applies if natural language detection is turned on.) * Text selections can now be attached to Agent Mode queries as context. * \[Windows] Window transparency now works when using DirectX 12. * \[Windows] Added “Open Warp Here” item for folders in the File Explorer context menu under “Show more options”. **Bug fixes** * Fixed an issue where `bazel` completions could use up a lot of CPU. * \[macOS] Fixed a regression where the title bar would be transparent in fullscreen windows. * \[Windows] Fixed children of shell processes not always exiting properly at shell termination. * \[Windows] Fixed Warpification for custom-built WSL distributions. * \[Windows] Fixed Ctrl-Up and Ctrl-Down shortcuts not working in alt screen programs (e.g. vim and emacs). * \[Windows] Fixed last line of output getting truncated with some prompt configs in WSL. * \[Windows] Fixed some hangs when using Agent Mode. * \[Windows] Fixed issues starting PowerShell in strict mode. * \[Windows] Fixed an issue where `.` would turn into n in ZSH when using ohmyzsh in WSL with an Italian keyboard layout. ### 2025.02.26 (v0.2025.02.26.08.02) [Section titled “2025.02.26 (v0.2025.02.26.08.02)”](#20250226-v0202502260802) **New features** * Warp is now available for Windows! See our [Quickstart Guide](https://docs.warp.dev/getting-started/installation-and-setup#windows) * Prompt, plan, and execute fully autonomous tasks from [Agent Mode with Dispatch](https://docs.warp.dev/agent-platform/warp-agents/interacting-with-agents) (Beta) * Add codebase context support to Agent Mode. Currently enabled for Git repositories only. * \[macOS] You can now customize your [App Icon](https://docs.warp.dev/terminal/appearance/app-icons) in `Settings > Appearance > Icon`. * Create and store [Rules](https://docs.warp.dev/knowledge-and-collaboration/rules) to use as Agent Mode context. * Show default suggestions in Agent Mode input. **Bug fixes** * Multicursor input is now `ALT` on Linux and Windows. * Fix prompt chip misalignment for certain fonts. * Autosuggestions remain visible when the input is not focused, to prevent height flickering when the autosuggestion soft wraps. ### 2025.02.19 (v0.2025.02.19.08.02) [Section titled “2025.02.19 (v0.2025.02.19.08.02)”](#20250219-v0202502190802) **New features** * Create and store AI memories to use as Agent Mode context. **Improvements** * Expanded Prompt Suggestions to cover more use cases. **Bug fixes** * Fixed Warp Prompt clipping issues encountered with certain fonts. * Fixed inverse and double-underline cell styling not persisting through session restoration. ### 2025.02.12 (v0.2025.02.12.16.51) [Section titled “2025.02.12 (v0.2025.02.12.16.51)”](#20250212-v0202502121651) **New features** * `CTRL-TAB` is now configurable under `Settings > Features` to cycle between the most recently used sessions rather than just activating the next tab. **Improvements** * The LLM menu is now keyboard-navigable. **Bug fixes** * Clearing Blocks now also clears any active Prompt Suggestions. * Fix Kali Linux `.bashrc` breaking Warp. * Fix bug with Agent Mode in PowerShell sessions with multi-line commands. * Fixed a bug that prevented Autosuggestions from being accepted and Agent Mode model from being selected while up arrow history was open. * Fixed cases where dragged Warp tabs would get stuck. * Restores subshell Warpification script. * \[macOS] Fix hotkey keybinding not triggering on non-US keyboard input source. ### 2025.02.05 (v0.2025.02.05.08.02) [Section titled “2025.02.05 (v0.2025.02.05.08.02)”](#20250205-v0202502050802) **New features** * You can now talk to Warp to transcribe Agent Mode prompts or any other text! Set up the hotkey in `Settings > AI > Voice` or use the microphone button in AI input mode to trigger this. **Improvements** * Autosuggestions in the input now soft-wrap. * You can now attach default environment variables to a workflow. ### 2025.01.29 (v0.2025.01.29.08.02) [Section titled “2025.01.29 (v0.2025.01.29.08.02)”](#20250129-v0202501290802) **New features** * Added support for DeepSeek R1 and V3 in Agent Mode! Try them out by switching to Agent Mode and clicking on the model name in the prompt. * Agent Mode can now auto-execute readonly requested commands. Commands can also be explicitly allowlisted or denylisted. See `Settings` -> `AI` -> `Autonomy` to configure. **Improvements** * You can now use `j`/`k` keys to navigate up and down Warp Drive. * Agent Mode chip added to Warp prompt. * Next Command is preferred over Command Corrections in cases where Corrections has less confidence. * Moved the Settings modal to its own tab. **Bug fixes** * Fixed a bug that caused double-clicking to select the incorrect range of text when non-ASCII characters are present. * Saving workflow aliases no longer deletes aliases from other workflows. * Fixed cases where a small part of the bottom of the editor would be cut off at certain appearance settings. ### 2025.01.22 (v0.2025.01.22.08.02) [Section titled “2025.01.22 (v0.2025.01.22.08.02)”](#20250122-v0202501220802) **New features** * Generate input for any interactive CLI using ⌘I on macOS and Ctrl-Shift I on Linux. * You can now dynamically populate arguments in Workflows with shell commands. * Added support for rectangular selection when holding ⌘⌥ on macOS and Ctrl-Alt on Linux. **Improvements** * Settings are now searchable and rendered in a separate tab * Terminal font weight is now configurable. * Launch Configurations now save the focused window state and active pane. * Autosuggestions in the input now soft-wrap. **Bug fixes** * Fixed several issues where hovering over URLs in the blocklist sometimes resulted in URLs only being partially detected, or not detected at all. * Fixed issue with Prompt Suggestions occasionally remaining visible after subsequent command execution. * \[macOS] Changed the download location for new Warp updates to prevent corruption. ### 2025.01.15 (v0.2025.01.15.08.02) [Section titled “2025.01.15 (v0.2025.01.15.08.02)”](#20250115-v0202501150802) **New features** * Font ligatures in grids! See setting under Settings > Appearance > Text to enable. * You can now define aliases that expand to Warp Drive workflows. **Improvements** * Launch configurations now save focused tab state. * Added support for Windsurf as an external editor. * macOS-only: added a new AI app menu. **Bug fixes** * Fixed pane navigation when panes are not overlapping. * Fixed a bug where Agent Mode LLM choices weren’t populated correctly upon logging in. * Fixed bug with drag-and-drop files causing duplicated filepaths. ### 2025.01.08 (v0.2025.01.08.08.02) [Section titled “2025.01.08 (v0.2025.01.08.08.02)”](#20250108-v0202501080802) **New features** * A percentage of Warp users may now enable cloud syncing of their Warp settings under `Settings` > `Account`. We are gradually enabling this feature for all Warp users starting in this release. See the [documentation](https://docs.warp.dev/terminal/more-features/settings-sync) for more information. * Introduced a setting to hide the tab bar (Zen mode). See the [documentation](https://docs.warp.dev/terminal/appearance/tabs-behavior) for more information. * Introduced new profile menu. **Improvements** * Removed the Command Corrections banner, as there’s already an autosuggestion in the input editor. * Implemented `_`, `+`, and `-` motions in Vim mode. * Warp will now show a warning before closing a session with a long-running process. * Pasting multiple lines of content into the terminal’s `Find` feature will convert it into a single line of text, rather than hide previous lines. * Titles of notebooks imported from Markdown files no longer end in `.md`. * “What’s new” no longer shows on update. * Added the ability to hide blocklist lines. * Consolidated top bar navigation items. * Settings are now in the profile menu. * Scrollbars and pane controls only show on hover. **Bug fixes** * Fixed the rendering of keyboard shortcuts at larger font sizes. * Tab completion menu now closes after selecting a single remaining suggestion. * Warp displays an error if relaunching to apply an update failed. * Old prompt suggestions won’t reappear when issuing AI queries rapidly or after clearing the blocklist. * Accepting the ‘What happened here?’ autosuggestion no longer clears AI context blocks. * `alt` key now sends meta control codes to the shell in long-running blocks and the alt screen. * When secret redaction is disabled, secrets are not redacted in command corrections. * \[macOS] Fixed a bug where assigning `cmd-shift-left` and `cmd-shift-right` to an action sometimes wouldn’t work. ### 2025.01.02 (v0.2024.12.18.08.02) [Section titled “2025.01.02 (v0.2024.12.18.08.02)”](#20250102-v0202412180802) **Improvements** * We now immediately show an error when trying to Warpify unsupported shells over SSH. **Bug fixes** * Fixed blank lines being appended to some blocks on resize. * Fixed an issue where the AI context disappears when accepting the default autosuggestion. # Changelog — 2026 > Warp release notes for 2026. Updates ship weekly, typically on Thursdays. Submit bugs and feature requests on our [GitHub board!](https://github.com/warpdotdev/Warp/issues/new/choose) ### 2026.05.06 (v0.2026.05.06.15.42) [Section titled “2026.05.06 (v0.2026.05.06.15.42)”](#20260506-v0202605061542) **New features** * Added a `/set-tab-color` slash command for setting or clearing the current tab’s color from the input bar. **Improvements** * Added tab context menu actions to copy visible tab and pane metadata when available. * The conversation details panel can now be opened and closed with a configurable keyboard shortcut. * Conversation details side panel is now available for local Warp Agent conversations, not just cloud Oz runs. Click the info button in the pane header to open it for any active AI conversation. * Reduced memory usage and CPU work in the agent runs management view while a conversation is streaming. * Added support for drag-and-drop of image files into an active CLI agent session (e.g. Claude Code). Thanks @SagarSDagdu! * Recognize Mistral Vibe (vibe / vibe-acp) as a known CLI agent in the terminal, with brand-colored toolbar tile. Thanks @lonexreb! * Warp now renders inline local images and Mermaid diagrams in agent block output. * Warp now silently falls back to a regular SSH session on remote hosts where the prebuilt remote-server binary is incompatible (e.g. glibc < 2.31), instead of attempting an install that would fail at runtime. * Tighten orchestration event subscription scope so SSE runs only for active parent and child agent runs. * HTML files using the .htm extension now open with HTML syntax highlighting in Warp’s editor. * Recognize Block’s goose CLI agent — running goose now activates the CLI-agent toolbar, status, brand color, and icon like other recognized third-party agents. Thanks @webdevtodayjason! * Added a `/continue-locally` slash command to continue cloud conversations locally. * Added a “Show in Finder” (macOS) / “Show containing folder” (Linux/Windows) option to the tooltip that appears when clicking a detected file link. **Bug fixes** * Stop the Code Review pane from re-running `gh pr view` on every filesystem event when the current branch has no PR. Thanks @croaky! * Fixed `/feedback` recording “Unknown” instead of the installed Warp version on packaged builds. Thanks @SagarSDagdu! * Fixed find (`⌘+F`) selection jumping to a different match when new output streams into the active block. Thanks @amazansky! * Fixed a command injection vulnerability when opening files in external editors on Linux. * Fix Japanese IME losing the last character of a phrase that ends right before a punctuation mark on macOS. Thanks @s-zaizen! * Fixed local file tree blinking/reshuffling when connected to an SSH session * Fixed terminal text selection not auto-scrolling when dragging beyond bounds * Fixed `Ctrl+G` not closing CLI agent rich input on Linux when editor is focused (fixes #9286). Thanks @nihalxkumar! * Pressing backspace in the agent view when the buffer is empty no longer resets the conversation. * Fixed unnecessary reconnect attempts for remote SSH sessions after system sleep, reducing error noise * Fixed issue with repeated TUI redraws for CLI agents on terminal pane resize. * Fix new-session ”+” dropdown alignment when the Tabs Panel is placed on the right side of the header toolbar. * Copy keybinding now prioritizes selected text in the input over a selected block when both are active. * \[Windows] Fix hotkey window. * \[Windows] Symlink traversal fixed. * Fixed a crash on Windows when handing off a Web conversation to the native client (“Grid received input but did not receive Reset Grid OSC”). * Fixed a bug where multiple ‘open skill’ buttons shared hover state. * Fixed Page Up and Page Down from the prompt so they scroll terminal output when the suggestion menu is closed; shortcuts appear under Keyboard Shortcuts as editable scroll actions (terminal:scroll\_up\_one\_page / terminal:scroll\_down\_one\_page). Thanks @fadexadex! * Fixed the OSS Linux desktop entry so WarpOss launches through the packaged warp-terminal-oss command. Thanks @lonexreb! * Fixed Ctrl/Cmd shortcuts (e.g. copy, paste) failing on Windows when a non-Latin keyboard layout was active. * Fix macOS IME candidate popup positioning in code editor panes so it anchors to the editor caret instead of stale terminal/input positions. Thanks @qubaitian! * Fixed `/open-file` handling for relative WSL paths so Unix separators are preserved before opening files on Windows hosts. * Fixed background colour bleeding in alt screen programs (e.g. delta, diff-so-fancy) where coloured regions would incorrectly fill the entire viewport when they dominated the visible area. Thanks @JamieMcMillan! * Clip the warping indicator’s action chips (e.g. “Hide responses”, “Take over”, auto-approve, queue-next-prompt, stop) onto a new line on narrow panes instead of overflowing into the adjacent pane. * Inline .bmp, .tiff / .tif, and .ico images in agent block output now render correctly instead of falling back to plain text. Thanks @anshul-garg27! * Notifications and session UI from the community-maintained pi-mono plugin (Pi CLI agent) are now wired through Warp’s default session listener. Thanks @lonexreb! * Fixed an issue where attaching an image in block input did not immediately lock into Agent Mode, which could cause the NLD classifier to introduce uncertainty. * Remote-server installs no longer fail when the staging-directory cleanup hits a “Directory not empty” race after the binary has already been moved into place. * .command shell scripts now open with shell syntax highlighting in Warp’s editor. * Fix git diff chip flickering between tracked-only and all-files count when untracked files are present * Open File → Default App now opens files in the running Warp channel instead of routing to a different installed Warp. * Fixed vertical tabs settings popup items (View as, Density, Pane title as) being unclickable. Thanks @leozeli! * Fixed a macOS memory leak that occurred when Warp enumerated system fonts or built a font fallback chain. * Executable shell scripts opened from a file:// URL now run in the terminal instead of opening in the editor. Thanks @amriksingh0786! * Fixed Option+Enter, Option+Tab, and Option+Escape sending literal key names instead of correct escape sequences. Thanks @oliver-ni! * Fixed read\_files tool showing an empty box when the LLM requests line ranges beyond the end of a file. * Fixed Linux WarpOSS application-menu launcher pointing to a non-existent warp-oss binary; the .desktop Exec line now matches the installed warp-terminal-oss launcher. Thanks @lonexreb! * Prevent Warp from consuming too much memory when identifying filepaths in long block outputs. * Don’t trigger the agent onboarding tutorial when Warp is running in headless SDK/CLI mode. * Added `--version` flag support in the Oz CLI * Fixed file tree flickering when transitioning to an SSH remote session * Fixed scroll-to-start/end of selected block keybinding (`⌘+Shift+↑`/`⌘+Shift+↓` on macOS, `Ctrl+Shift+↑`/`Ctrl+Shift+↓` on Windows/Linux) not working when the input is focused. * Fix the terminal pane background appearing darker in horizontal tabs mode when the active theme has a background image or a custom window opacity. * AI code blocks tagged vue, xml, dockerfile, jsx, tsx, objective-c, or starlark now render with syntax highlighting. Common aliases like rs, py, js, ts, yml, kt, rb, golang, terraform, and docker are also recognized. * Reopen Closed Session is now reachable from the new-session menu on Linux and Windows. * Fixed missing syntax highlighting for C++ header files using .hpp, .hxx, or .H extensions. **Oz updates** * Add Codex as a supported harness for local child agents. * Configurable max context window per profile. ### 2026.04.29 [Section titled “2026.04.29”](#20260429) **Improvements** * New AI setting to control whether Oz adds an attribution co-author line to commit messages and pull requests it creates. * Git operation buttons now show tooltips explaining why they’re disabled (e.g. “No changes to commit”, “Enter a commit message”). * Long-running shell command indicator now shows a countdown to the agent’s next snapshot (e.g. “Next check in 12s”) instead of how long it’s been since the last one. **Bug fixes** * warp\://action/new\_tab?path=\~/foo (and /new\_window) now expand \~ to your home directory. * Tab configs in the + menu and default session mode dropdown are now sorted alphabetically by name instead of appearing in random order. * Fixed an issue where slash commands sent while an agent was still responding were silently dropped. Now, slash commands like /pr-comments run as follow-ups, just like typed messages. * Disabled the commit message editor while a git commit is being performed in the git operations dialog. * Project-scoped file-based MCP servers now spawn from the repo root by default (and global ones from \~), so configs with relative commands/args (and workspace launchers like pnpm/npm) work without an explicit working\_directory. * Stopped spamming agent-run metadata fetches on the WASM shared-session viewer, eliminating a flood of 403 responses on `/api/v1/agent/runs/{id}` for non-owner viewers. * Fixed dropped keystrokes when typing into a command block that started from a queued/typeahead command. * Fixed double-line visual artifacts between workspace panels in all panel arrangements. * Fixed a small memory leak on macOS that could accumulate Core Graphics objects during text rendering. * Fixed settings popup items (View as / Density) being unclickable (thanks @leozeli!). **Oz updates** * Reduced the oz CLI tarball download size by \~60% on both macOS and Linux. * Model selector no longer shows promotional discounts for models routed through your own API key (BYOK), since those discounts only apply to Warp-billed usage. ### 2026.04.27 [Section titled “2026.04.27”](#20260427) **New features** * Warp is now open source. * Warp is now configurable via a TOML settings file. Access the file from the settings page or ask Warp’s agent to update settings for you. **Improvements** * Add setting to disable suggested rules. * Added a `/feedback` slash command for submitting feedback about Warp. * The `oz run get` and `oz run list` commands now support JSON output, along with filtering via the `--jq` flag. * Feedback from the user menu, Help menu, Resource Center footer, and command palette now opens a guided `/feedback` agent flow when AI is available, and falls back to the GitHub issue form otherwise. * Middle-clicking a vertical tab now closes it, matching horizontal tabs. * Slash commands in the terminal are now available even when AI is disabled. * The network log viewer now opens as an in-app read-only pane backed by a 50-item in-memory buffer instead of writing `warp_network.log` to disk. * Added a “Check now” button next to the “Last seen by agent” indicator for long-running commands, letting users immediately deliver a fresh snapshot to the agent without waiting for its poll timer. * The agent mode input placeholder now reflects conversation state: “Warp anything” for new conversations, “Steer the running agent” while streaming, and “Ask a follow up” once finished. * The `/feedback` skill now supports attaching screenshots. When you run `/feedback` with one or more images attached, Warp drafts the issue with per-screenshot captions and opens GitHub’s new-issue page so you can drop the images into the issue body before submitting. * Pasting an absolute file path (e.g. from “Copy file path” in the Code Review pane) into the Command Palette file picker now correctly finds and opens the file. **Bug fixes** * Fixed wide Markdown table scrollbars in block list responses rendering over the terminal input. * Fixed vertical tabs close button appearing on the left side when the panel is positioned on the right. * Onboarding autonomy selections (Full / Partial / None) now correctly apply to the default execution profile, and existing users’ stored cloud profiles are preserved when logging in at the end of onboarding. * Fixed a crash that could occur in the project explorer while file-tree metadata was being updated. * Fixed issue where clicks in the vertical tabs settings panel were being ignored. * Fixed “View in Oz” button in the conversation details panel not responding to clicks. * \[Windows] WSL panes in restored sessions have the same PWD when you exited. * Restored the API Keys (BYOK) and AWS Bedrock sections in the Agents > Oz settings subpage. * Fixed a small memory leak on macOS when reading or writing user preferences. * Usernames with an apostrophe no longer break PowerShell sessions. * Fixed a hang that could occur when exiting an SSH session with the remote-server feature enabled. * Fixed a crash triggered by terminal output containing very long runs of zero-width characters (such as steganographic ZWJ/ZWNJ sequences embedded in HTML piped through the terminal), which could also reproduce at startup via session restoration if the offending output had been persisted into a block. * Fixed a small per-call memory leak triggered when opening a file in its default macOS application. * Fixed unreadable text in the CLI agent rich input when running alt-screen CLI agents, increasing the contrast against background (e.g. OpenCode). * Fixed a one-time startup memory leak in the macOS Services submenu setup. * Fixed a per-window memory leak of the window delegate in the macOS ObjC bridge (window\.m). * Fixed file tree sidebar incorrectly showing remote SSH session directories in local tabs. * Fixed a keycode-dictionary per-bucket over-retain in the macOS ObjC bridge (keycode.m). * Fixed a small per-window memory leak in the macOS ObjC bridge (host\_view\.m). * Fixed a per-hotkey memory leak when registering global hotkeys on macOS. * Tab title no longer changes to an agent-executed command name (e.g. cargo) during agent validation steps. * \[macOS] Fixed a memory leak on image pasting and app-icon changes. * Reopening a closed cloud-mode tab within the undo-close grace period now restores a live view of the cloud conversation instead of a frozen snapshot with a “session ended” banner. * Fixed privacy settings for logged-out users not persisting to the settings file. **Oz updates** * The feedback skill is now available on stable — turn rough app feedback into filed GitHub issues directly from Warp. ### 2026.04.22 (v0.2026.04.22.08.46) [Section titled “2026.04.22 (v0.2026.04.22.08.46)”](#20260422-v0202604220846) **New features** * Toolbar chips can now be rearranged by right-clicking anywhere in the top bar and selecting “Rearrange toolbar items”. * Mermaid diagrams now render in markdown notebooks. **Improvements** * Added support for pasting images into the rich input editor with CLI agents, such as Claude Code or Codex. * Typing `_text_` or `__text__` in a code review or rich-text comment now renders as italic or bold, matching the existing `*text*`/`**text**` behavior. * \[Windows] Added a “Start Warp at login” toggle under **Settings** > **Features** > **General** that registers Warp to launch automatically when you sign in to Windows. * Add View menu entries (with keyboard shortcuts) for the Global Search and Agent Conversations left panel items on macOS. * \[Windows] Added 408 new PowerShell cmdlet completions and improved suggestion quality for existing PowerShell completions. * Added completions for `pprof`. * `/fork` now opens the forked conversation in a new pane with Enter and in a new tab with Cmd+Enter. * Right-click a URL or file-path link inside an AI response to copy it directly via the context menu. * Added a setting to hide the lines added/removed counts from the code review button in the tab bar. * Reorganized settings into subpages for Agents, Code, and Cloud platform; improved settings search. * Wired branch completion into `git log` argument position. * Added notifications for OpenCode’s “Ask user question” tool. * Show discount chip on models with active promotions in the model picker. * Per-query image limit bumped to 20 (from 5) and per-conversation image limit bumped to 200 (from 20). * Performance improvement preventing lagginess after logging in when you have many Warp Drive objects. * Added support for file artifacts in agent conversations with download functionality and filtering options. **Bug fixes** * \[Windows] Fixed image paste into CLI coding agents (Claude Code, OpenCode, etc.). * Fixed MCP server tags overflowing off-screen when a server has many chips (e.g. GitHub MCP with many repo scopes). * Fixed MCP gallery items not being alphabetized consistently in the MCP servers settings page. * Fixed artifacts card clipping the “Continue locally” button on narrow panes. * Fixed code review submit button being incorrectly disabled when the terminal’s working directory casing didn’t match the on-disk repo path on macOS. * Fixed new accounts not being marked as onboarded on the server when signing up after completing the onboarding slides from a non-login-slide entrypoint. * Fixed Project Explorer getting stuck in loading state when opened after connecting to a remote SSH session. * Fixed a bug where the agent’s `read_files` tool returned extensionless text files (such as shell scripts) as binary content. * Fixed MCP settings page file-based server badges growing unbounded and incorrectly labelling Warp-scoped servers as “.warp” instead of “global”. * Fixed missing in-progress indicator in agent panes when a shell command is running but no agent message has been sent yet. * Fixed MCP OAuth authentication failing with providers that enforce strict redirect URI matching (e.g. Hydra/ORY). * Fixed MCP tool calls with integer-typed parameters failing due to being serialized as floats. * Fixed file edit tool dropping the end of a line when the LLM’s search block ended with a partial line match. * First find match now gets correctly selected when using the code editor with vim mode. * Fixed code review comments being silently dropped when sent after cancelling a running agent command with Ctrl+C. * Toolbar chips in the coding agent footer are no longer hard to read when running alt-screen CLI agents like OpenCode. * Fixed MCP servers (e.g. Figma) requiring re-authentication on every app restart. * \[Windows] Fixed a race condition that caused auto-updates to fail with file-in-use errors when Warp hadn’t fully exited before the installer ran. * Improved reliability of the Rich Input submission flow for Copilot CLI. * \[Windows] Fixed unbounded memory growth when rendering large amounts of CJK text with a primary font that does not include CJK glyphs. * Fixed settings search bar text overflowing when typing long queries. * Fixed Oz CLI hanging after command completes when the network is unavailable. * Fixed Ctrl+C not terminating the Oz CLI during shutdown. * Fixed `~` (tilde) not being expanded to the home directory in the `/open-file` slash command. * Fixed orchestration events breaking tool call ordering when a CLI subagent is active. **Oz updates** * Added a bundled Claude API skill for Claude API and Anthropic SDK development guidance. * Added support for `--share public:{access_level}` to oz CLI to set public access level on oz cloud runs. * `/feedback` skill now adds the `in-app-feedback` label to issues it files, for tracking. * `start_agent` no longer rejects remote child agents when `environment_id` is omitted; within a remote parent, the child inherits the parent’s environment automatically. ### 2026.04.15 (v0.2026.04.15.08.45) [Section titled “2026.04.15 (v0.2026.04.15.08.45)”](#20260415-v0202604150845) **Improvements** * Agent Mode now shows a “Last seen by agent at” indicator for long-running commands, so you can see how recently the agent received new output. * Added completions for npm package search, nx, brew, aws s3, tree, awk, sort, ip, uv, and nmap, and added pnpm workspace filter support. * Skill invocations now display with the same purple highlighted text as slash commands in the input and prompt views. * Added completions for `timedatectl`, `ack`, `watch`, `lsof`, `systemctl`, `ros2`, `nextflow`, `tsh`, `codex`, `asdf`, `sdk`, `pass`, `az`, `oc`, `scp`, `claude`, `git show`, `git rm`, `gsutil`, `aws ec2`, `docker-compose`, `yarn`, and `docker run`; improved `git switch`, `git diff`, `aws` static flags, `gt`, `kubectl`, `tf`, `pnpm`, `kubectl`, and SSH host completions; added `apt` repo package generator. * Code review comment buttons now remain visible when AI is disabled; comments can be sent to CLI agent terminals (e.g. Claude Code). * Review comments can now be sent to any available terminal in the tab, not just the focused one. If the focused terminal is busy, Warp will automatically route comments to another idle terminal in the same repo. * Skills are now searchable from the @-context menu in Agent Mode, inserting `/{skill_name}` into the prompt. * File-based MCP servers can now be configured via `~/.agents/.mcp.json` (global) or `.agents/.mcp.json` (project-local). **Bug fixes** * Fixed longer prompts for Claude Code not being fully submitted when using Rich Input in Warp. * Fixed settings being reset to defaults when a logged-out user creates a new account. * Updated openh264 dependency to resolve a heap overflow security vulnerability (GHSA-5pmw-9j92-3c4c). * Show “Resume Conversation” shortcut when agent conversations fail with transport or server errors. * Fixed `kubectl` resource completion breaking when `-n`/`--namespace` or other flags are placed before the subcommand. * Fixed markdown files with animated GIFs and WebPs using excessive memory by rendering them as first-frame previews. * Fixed autosuggestions and completions not appearing after shell bootstrap completes. * Fixed excessive CPU usage from redundant `git status` processes when multiple terminal tabs are open in the same repository. * Fixed a bug where conversations would stall if a long-running command finished while the user was in control. * Fixed thought block headers (“Thought for X >”) having a click area that extended to the full width of the pane; only the text and chevron are now clickable. * Fixed global search using excessive memory when matching files with very long lines (e.g. minified JavaScript). * Window title now respects custom tab names instead of always showing the generated name. * Fixed `git push` branch completion for force-push and refspec prefixes, HTML entity rendering in completion specs, and `npm i` short-form command priority. * Fixed repeated 403 errors when indexing large codebases. * Fixed ask-question option rows changing cursor shape while hovering over option text. **Oz updates** * Local child agents now inherit the parent agent’s AI profile (model and permissions). ### 2026.04.08 (v0.2026.04.08.08.36) [Section titled “2026.04.08 (v0.2026.04.08.08.36)”](#20260408-v0202604080836) **New features** * Vertical tabs are now available, offering a new way to organize your terminal tabs in a sidebar layout. * Tab configs allow you to save and share your workspace setup as customizable configurations. * You can easily create new worktrees with autogenerated branch names. These are saved as tab configs to then customize and edit. * New Rich Input available in third-party CLI agents (e.g. Claude Code, Codex, Gemini CLI, OpenCode, etc.). This allows you to use Warp’s rich input features with these coding agents. * Released a revamped notifications UI, and support for notifications for Claude Code and OpenCode. * Added support for the coding agent toolbar for auggie and pie. * Added a settings entry for the ask question tool to configure when it pauses for user input. **Improvements** * Conversation search now shows what it is searching for and its current activity. * Added `warp://settings/appearance` deep link to open Appearance settings directly. * Improved AI @context menu to prioritize blocks from the active terminal session and rank items by recency. * Added support for rendering markdown tables in notebooks and Warp’s built-in Markdown viewer. * The command palette file opener now supports `~` (tilde) expansion to the home directory when searching for files. * Added completions for `timedatectl`, `ack`, `watch`, `lsof`, `systemctl`, `ros2`, `nextflow`, `tsh`, `codex`, `asdf`, `sdk`, `pass`, `az`, `oc`, `scp`, `claude`, `git show`, `git rm`, `gsutil`, `aws ec2`, `docker-compose`, `yarn`, and `docker run`. * Improved dynamic completions for `git switch`, `git diff`, `gt`, `kubectl`, `tf`, `pnpm`, `apt` and SSH hosts. **Bug fixes** * Added prompt changes to avoid agents getting stuck navigating pagers in Full Terminal Use. * Removed the web inactivity logout that could sign out authenticated users unnecessarily while session-cookie expiration work lands. * Skip ask-user-question prompts while auto-approve is enabled in Agent Mode. * Fixed `git push` branch completion for force-push and refspec prefixes. * Fixed HTML entity rendering in completion specs. * Fixed `npm i` short-form command priority. **Oz updates** * Added an `oz whoami` command to get user information. ### 2026.04.01 (v0.2026.04.01.08.39) [Section titled “2026.04.01 (v0.2026.04.01.08.39)”](#20260401-v0202604010839) **New features** * \[macOS] Right-clicking on text files in Finder allows you to open in Warp’s code editor. * Send code review comments, attach diff hunks as context, and send substrings as context (`cmd L`) to 3rd party CLI tools such as Claude Code, Codex, Opencode, etc. * Oz agents can now ask users clarifying questions during Agent Mode interactions. * Warp’s agent now suggests followups when it is done. **Improvements** * Replaced warpify banner for subshell and SSH sessions with a footer to either warpify or tag an agent in. * Improved error messaging when session sharing times out via CLI `--share` flag, now suggesting that it may be disabled by a team administrator. * Added “Copy file path” option to the overflow menu in the file viewer for both code and markdown files. * Added “Sign up” option to the settings gear menu for non-logged-in users. * MCP config files edited by the agent now show an ‘Open config’ button in the code diff header, making it easy to jump directly to the config file. * Added `/skills` support in CLI agent rich input for browsing and invoking agent-specific skills. * Sandboxed Oz agents now have dedicated autonomy settings, instead of inheriting the team-level defaults. * Updated settings info icon tooltips to clarify they open documentation. * Improved quality and latency of prompt suggestions and suggested code diffs. * Cloud agents can now accept images and file attachments as context. **Bug fixes** * Fixed stale fallback model messaging persisting across new user queries. * Fixed scroll behavior when editing code review comments to properly reveal the comment editor. * Fixed WebSocket proxy connections timing out when the proxy listens on port 80. * Fixed PowerShell aliases and functions to be matched case-insensitively, matching PowerShell’s native behavior. * Fixed conversation search temp directory paths using mixed separators on Windows. * Fixed keyboard shortcuts settings panel being empty when first navigated to via search. * Fixed the `@` context menu dismissing after typing \~6 characters when filtering categories. * Fixed a crash with Oz CLI commands that read from stdin. * Fixed a production WebAssembly crash caused by native repository detection code being reached from shared Wasm call paths. * Fixed links in blocklist code review comments not opening when clicked. * Fixed “Out of credits” alert not dismissing when users provide their own API keys. * Fixed link detection being offset in AI conversations after conversation summaries or hidden reasoning blocks. * Simplified file explorer lazy-loaded folder handling and fixed transitions between standalone folders and indexed git repositories. * Fixed inline code snippet colors and underline colors not updating when switching editor themes in notebooks. * \[Windows] Fix rendering on an additional set of older Intel iGPU drivers. * Fixed web auth flows so session-cookie-authenticated clients can call authenticated server APIs without requiring an Authorization header. **Oz updates** * Fixed Oz session sharing failing behind HTTP proxies on port 80. * The `OZ_RUN_ID` environment variable is now available inside agent terminal sessions, set to the current task ID. * Improved error messages when agent session sharing fails, removing repetitive text and providing clearer guidance. * Oz agents can now ask users clarifying questions during Agent Mode interactions. ### 2026.03.25 (v0.2026.03.25.08.24) [Section titled “2026.03.25 (v0.2026.03.25.08.24)”](#20260325-v0202603250824) **New features** * You can now use the pr-comments skill using `/pr-comments` to fetch Pull Request comments from GitHub. * Warp now supports the Kitty Keyboard Protocol. **Improvements** * Onboarding now shows premium model tiers as disabled with an upgrade path for free users. * All inline menus are now resizable, and some inline menus now have tabs. * Adds new built-in `edit-figma-design` skill, invokable by users with Figma’s remote MCP server installed. * MCP server templates can now use dropdown selectors for enums. * Added a customizable toolbelt for the agent input footer — drag and drop to rearrange context chips and controls. * \[macOS] Migrate to Apple’s newest icon format. This will allow Warp’s icon to adapt to the chosen “Icon & Widget Style” preference if the default icon is selected. * Code review comments can now be sent directly to running CLI agents (Claude Code, Gemini CLI, etc.) from the code review panel. * Pressing `esc` now dismisses an empty code review comment composer. * Added the ability to always show or always hide agent thinking blocks. Visit **Settings** > **AI** > **Other** to change. * Add a `/changelog` command for reopening the latest changelog, and keep the update toast visible until dismissed. * Added syntax highlighting for Dockerfiles in the file editor. * Added a setting to hide agent-executed commands from shell history, now enabled by default. * MCP servers detected from third-party agents (Claude, Codex) are now visible and spawnable from the MCP servers page in Warp’s AI settings. For more, see our [docs](https://docs.warp.dev/agent-platform/warp-agents/mcp#file-based-mcp-servers) on file-based MCP servers. **Bug fixes** * Fixed visual jitter in agent toolbelt when opening the rich input composer. * Clarified the `/fork` slash command description. * MCP resource reads now respect autonomy settings instead of always prompting for approval. * You now get completions, syntax highlighting, and hover descriptions when your flag/value pairs are `=`-separated, e.g. `--flag=value`. * Fixed stale go-to-definition and symbol outlines when using code review with multiple tabs. * Fixed an issue where selecting a shell command from command search (`cmd-r`) while in Agent Mode with auto-detection disabled would treat the command as an agent prompt instead of executing it as a shell command. * Fixed `ctrl-c` not working during conversation search. * Fixed an issue where the follow-up prompt in `/compact-and` and `/fork-and-compact` was silently lost when summarization failed or was cancelled. * Fixed dismiss button and `ctrl-c` not working on suggested unit tests banner. * Git diff chip now appears in remote and subshell sessions. * Fixed input scrolling bug where clicks were sometimes applied one line up (instead of on the clicked line). * Fixed rendering of programs that use the synchronized output VT extension in shared sessions, such as Claude Code. **Oz updates** * Updated the `create-skill` bundled skill with the latest upstream version, adding eval/iteration workflow, benchmarking, and description optimization capabilities. * New chip in AI input mode for GitHub pull requests, whenever you have a pull request open for your current branch. ### 2026.03.18 (v0.2026.03.18.08.24) [Section titled “2026.03.18 (v0.2026.03.18.08.24)”](#20260318-v0202603180824) **New features** * Warp now automatically detects global and project-scoped MCP servers configured with `claude` or `codex`. Toggle **File-based MCP servers** in **Settings** > **AI** to auto-spawn servers based on your local configuration. See [docs](https://docs.warp.dev/agent-platform/warp-agents/mcp#file-based-mcp-servers) for more. * Added Go to Line dialog in the code editor (`CTRL-G`) with line:column support. **Improvements** * Added “Leave Agent Thinking expanded” setting to keep agent thinking blocks expanded after streaming. * Added “All” and “Current Directory” tabs to the inline conversations menu. * Updated settings copy to consistently use “Oz” instead of “the Agent” in MCP Servers and Rules sections. * Improved the performance of loading and rendering large AI conversations. * Added an inline plan selector for conversations with multiple plans. * \[macOS] The window traffic light buttons now look correct at different zoom levels. * Kitty keyboard protocol support is now available on Preview builds. * The Warp agent management view now links to associated skills for cloud agents. * `Ctrl-R` command search now includes AI query history from all past conversations, not just those currently open. * Enabled Kitty keyboard protocol support on dev builds. * Improved the ranking of items listed in @ context by considering recency. * Added new built-in skills `generate-figma-content` and `pull-figma-content` invokable by users with Figma’s remote MCP server installed. * Hidden directories and files (starting with `.`) now appear at the top of the Project Explorer, matching the convention used by most editors. * Updated setup command placeholder to show `cd my-repo &&` example. **Bug fixes** * Fixed “for terminal” text in pane header becoming bold when disabled, causing a layout shift. * Fixed notebook find bar showing `?/n` instead of proper match counter. * Fixed bug where editing a tab title always started with the pane title (instead of the tab’s custom title, if it existed). * Fixed “View latest changelog” action not appearing in the command palette. * Fixed issue where artifacts from cloud agent runs did not update live in the conversation details pane. * Fixed intermittent “Failed to update plan” toast appearing without user action when background plan auto-saves encountered transient failures. * Fixed tooltip for branch name in code review panel overlapping the truncated text — it now appears above the branch name. * Fixed `Ctrl+G` not being bound by default for “Go to line” in the code editor. * Fixed `cmd-O` files palette not toggling off when pressed again. * Fixed code review panel unnecessarily resetting scroll position and cached state when switching tabs. * Fixed some saved prompts not appearing in slash command menu when searching with a single character. * Fixed SSH warpification not triggering when using shell aliases for SSH commands. * Fixed a bug where SSH sessions run by the agent would incorrectly trigger warpification UI. * Fixed issue on macOS where New Window/New Tab menu items and keybindings occasionally became disabled when using global hotkey window. * Fixed code review branch dropdown only showing “Uncommitted changes” after closing and reopening the panel. * Fixed “New environment” button in Environment settings not opening the setup mode selector popup. * Fixed onboarding slides cutting off navigation buttons when the window is too short — content area is now scrollable. * \[Windows] Fixed path inconsistencies that caused codebases to fail indexing. * Show tooltip on the codebase indexing toggle when it is disabled by an admin policy, explaining why the setting cannot be changed. * \[Windows] Fixed rendering issues on old Intel UHD integrated GPUs. * Fixed a bug where only the first plan was shown inline when restoring a conversation with multiple plans created. * Fixed resume-conversation keybinding not working when a long-running command subagent is active. * Fixed broken documentation links in agent tips, settings, and onboarding content. * Fixed AI queries in `Ctrl-R` history not being sorted by time. **Oz updates** * Conversation search now uses real file tools for faster, more accurate history search. * Added `/open-repo` slash command for switching between indexed codebases. * Added tabs to the up-arrow history menu to filter to commands or prompts. * `oz agent run` now prints the run ID with a link to the Oz dashboard. ### 2026.03.11 (v0.2026.03.04.08.20) [Section titled “2026.03.11 (v0.2026.03.04.08.20)”](#20260311-v0202603040820) **Bug fixes** * The terminal input now automatically detects references to Figma and encourages the use of the Figma MCP. Images exported from Figma are also detected. ### 2026.03.05 (v0.2026.03.04.08.20) [Section titled “2026.03.05 (v0.2026.03.04.08.20)”](#20260305-v0202603040820) **New features** * Adds prompt customization for the new Warp prompt. **Improvements** * Adds new built-in skills `generate-figma-content` and `pull-figma-content` invokable by users with Figma’s remote MCP server installed. * Selected text is no longer auto-attached as agent context to prevent accidental attachment, and instead requires right click > attach as agent context. * Cloud conversations now appear in the @conversations context menu. * When Settings > MCP Servers > File-based MCP servers is toggled on, we now automatically detect and spawn global and project-scoped MCP servers installed via `codex`. * Global search now pre-populates with the active text selection from code, terminal, notebook, and plan views. * Warp prompt now has separate chips for git branch and git diff stats. * Show pending prompt indicator when using `/fork-and-compact` or `/compact-and` with a follow-up prompt. * Oz permission notifications now use “Oz” branding instead of “Agent Mode”. * \[macOS] The window traffic light buttons now look correct at different zoom levels. * Added “Copy plan ID” option to the plan document overflow menu. **Bug fixes** * Fixed an issue where changing directories from the prompt chip dropdown cleared the terminal input. * Fixed LSP error diagnostics (underlines) persisting on valid symbols after workspace reanalysis. * Resolved an issue where duplicate skills installed across multiple provider directories (e.g., `.claude` and `.agents`) would appear twice. * Fixed git diff stats chip incorrectly appearing in non-git directories. * Fixed global hotkey window opening on the wrong screen after sleep/wake when pinned to a specific display. * Fixed cursor position queries (`ESC[6n`) not working when connected via tmux control mode (`-CC`), which caused certain TUI applications to hang when Warpified in SSH (e.g. Codex CLI). * Fixed agent driver not waiting for automatic error retry on network failures. * Fixed incorrect ANSI colors in the Adeberry theme. * Fixed a bug where some MCP servers would fail to connect due to an unsupported `resources/list` method. * CLI now exits immediately with an error when credentials are invalid, instead of timing out while syncing Warp Drive. * Fixed a crash that could occur when selecting text during rapid terminal output. * Fixed ephemeral MCP servers not being included in multi-agent API requests. * Fixed settings page not updating profile picture after auth state changes. * Fixed the “Open in Warp” button not working for code snippets in restored and forked AI conversations. * Hide the free cloud credits banner on shared sessions and WASM builds. * Fixed a case where the newest plan created by the agent would not visually replace a previous plan that was open. * “Plan synced to Warp Drive” toast no longer appears when the synced plan is in a different tab. * Fixed “open file” button in code review diff view not working when the pane is maximized. * Fixed git metadata background operations after a terminal is closed. * Mobile soft keyboard will now work for LRCs. * Oz agents now report more detailed information about session-sharing failures. **Oz updates** * Oz agent tasks now report structured error codes to the server, enabling better error tracking and retryability handling. * Fixed Oz cloud agent not waiting for automatic error retry on network failures. * Added support for passing arguments to skill invocations (`$ARGUMENTS`, `$N`) and for including user queries with the invocation. ### 2026.02.25 (v0.2026.02.25.08.24) [Section titled “2026.02.25 (v0.2026.02.25.08.24)”](#20260225-v0202602250824) **New features** * Warp now has language server support in our native code editor. For details on the languages and features we support, check **Improvements** * Reintroduced customization support for the Warp prompt. * Maximizing the Code Review panel now opens the file list. * Docker image inputs in environment settings now show a link to the Docker Hub page when available. * Added `/compact-and` slash command to trigger conversation compaction and automatically send a follow-up prompt when it completes. * Added a new `/profile` command that allows you to switch between profiles using an inline menu. * Oz CLI now outputs a direct link to the Oz webapp run page when spawning cloud agents. **Bug fixes** * Fixed a bug where the Oz CLI would open the Warp GUI app rather than printing help output. * Fixed broken documentation links on the Referrals settings page and AI settings page. * Fix CLI agent footer detection when commands are prefixed with env var assignments. For example, `OPENCODE_EXPERIMENTAL_PLAN_MODE=1 opencode`. * Fixed rendering of codebase search tool calls when restoring conversations * Local-only slash commands such as `/open-file` are now disabled automatically in remote sessions * Fixed “View all cloud runs” button linking to a specific run instead of the runs list page * Fix tab alignment in monospace text blocks by using fixed-width tab stops. * Improve cloud-mode modal routing for concurrent-limit vs out-of-credits states. * Fix cloud-mode out-of-credits modal flicker and compact CTA alignment. * \[Linux] The `oz` CLI package is now named `oz-stable`. **Oz updates** * Add “Default mode for new sessions” setting to open new tabs and panes in agent view by default. ### 2026.02.18 (v0.2026.02.18.08.22) [Section titled “2026.02.18 (v0.2026.02.18.08.22)”](#20260218-v0202602180822) **New features** * Agents can now fetch and read content directly from URLs provided in your query. **Improvements** * Enabled multi-select in Notebooks and code editors. * Added a new setting under `Appearance > Tabs` to preserve the active tab’s color when creating new tabs. **Bug fixes** * Fixed Escape key closing the up-arrow menu instead of transitioning to normal mode when in vim insert mode. * Fixed Option-left and Option-right keys not working for word navigation in code review comments editor. ### 2026.02.11 (v0.2026.02.11.08.23) [Section titled “2026.02.11 (v0.2026.02.11.08.23)”](#20260211-v0202602110823) **Improvements** * Updated the tabs UI to be cleaner, more readable, and to make tab focus clearer. **Bug fixes** * Show the Input Type setting (Warp/PS1) regardless of global AI setting. ### 2026.02.10 (v0.2026.02.10.11.37) [Section titled “2026.02.10 (v0.2026.02.10.11.37)”](#20260210-v0202602101137) **New features** #### Introducing Oz: orchestration for cloud agents [Section titled “Introducing Oz: orchestration for cloud agents”](#introducing-oz-orchestration-for-cloud-agents) ![Introducting Oz image showing the new Oz logo and a preview of the oz.warp.dev site](https://releases.warp.dev/changelog_images/v0.2026.02.09.06.06.stable.png) Oz is Warp’s orchestration platform for cloud agents: launch parallel agents, automate recurring engineering work, and build apps on top of agents with full visibility and control. [Read the launch post →](https://www.warp.dev/blog/oz-orchestration-platform-cloud-agents) #### Oz Cloud Agents [Section titled “Oz Cloud Agents”](#oz-cloud-agents) * **Run Cloud Agents from anywhere with built-in tracking** — start agents from Warp or via the CLI, triggers, or schedules. Every run is auditable and steerable. [Cloud Agents docs →](https://docs.warp.dev/agent-platform/cloud-agents/overview) * **Cloud environments for consistent execution** — configure Docker-based environments (unlimited repos + setup commands) and run agents in isolated cloud sandboxes. [Environments docs →](https://docs.warp.dev/agent-platform/cloud-agents/environments) * **Track agents from the web** — manage runs, create schedules, configure environments, and set up integrations from any browser at [oz.warp.dev](https://oz.warp.dev). * **Schedule agents based on Skills** — run agents automatically on a cron schedule for code cleanup, dependency updates, and issue triage. [Scheduled Agents docs →](https://docs.warp.dev/agent-platform/cloud-agents/triggers/scheduled-agents) * **Programmable by default** — orchestrate agents via the CLI and integrate Oz into tools and services via the API/SDK. [API and CLI reference →](https://docs.warp.dev/reference) #### Warp Upgrades [Section titled “Warp Upgrades”](#warp-upgrades) * **Agent Modality** — two distinct modes: a clean terminal for commands, and a dedicated conversation view for multi-turn agent workflows with full controls (model select, voice, attachments). * **Cloud-Synced Conversations** — your agent conversations sync to the cloud and persist across devices. Share with teammates via link, view on the web, or continue locally. #### Agent Capabilities [Section titled “Agent Capabilities”](#agent-capabilities) * **Skills** — reusable instruction sets that agents auto-discover from your project or home directory. Invoke with `/{skill-name}` or run as scheduled cloud agents for repeatable automation. [Skills docs →](https://docs.warp.dev/agent-platform/warp-agents/skills) * **Computer Use** — agents can interact with desktop environments in sandboxed cloud containers—take screenshots, click, type, and test UI changes. [Computer Use docs →](https://docs.warp.dev/agent-platform/warp-agents/computer-use) ### 2026.02.04 (v0.2026.02.04.08.20) [Section titled “2026.02.04 (v0.2026.02.04.08.20)”](#20260204-v0202602040820) **New features** * Added full support for the Kitty keyboard enhancement protocol, enabling TUI applications like OpenCode to detect and use enhanced keyboard input. * Support agent footer when running Copilot CLI. * Added a new paid plan, **Max**, which comes with 12× more monthly credits than Build. Upgrade in `Settings > Billing and Usage`. **Improvements** * Improved environment update handling with better timestamp tracking and immediate UI refresh after edits. * `@` menu now shows function definitions when NLD is disabled. * Conversation deep links now open in a new tab instead of a new window. * Renamed `edit` slash command to `open`. * Fixed a race condition when using API keys with the Oz CLI. * Improved robustness of MCP connections (especially using the legacy SSE transport). “Transport closed” errors now trigger a reconnection to the server. * Added a new setting to keep the opened/closed state of the tool panel consistent across tabs in the same window (“Tools panel visibility is consistent across tabs”). **Bug fixes** * Fixed “Sharing in Warp Drive” onboarding block appearing mid-stream during agent responses. * Disabled codebase indexing on non-agent run commands. * Fixed scrolling behavior when typing in long-running commands — cursor is now scrolled into view. * Fixed sharing dialog copy link icon being slightly larger than the text. * Fixed issue where the code review panel would get stuck on “Loading open changes” when multiple repositories are open in the same tab. * Fixed a crash caused by orphaned wide character flags in the terminal grid. * Fixed clipping issue in terminal message bar. ### 2026.01.28 (v0.2026.01.28.08.14) [Section titled “2026.01.28 (v0.2026.01.28.08.14)”](#20260128-v0202601280814) **Improvements** * Files opened from code review panel, project explorer, and global search now respect your external editor setting. * Toggling the plan while the pane is maximized now restores the layout to show the plan. * Added “copy path” button to file headers in code review panel. * Pasting images into the input now enters Agent Mode, matching drag and drop behavior. **Bug Fixes** * Fixed an issue where conversations could break when the agent read large images from directories. * Fixed input buttons overflowing into adjacent panes in narrow layouts. * Fixed text in MCP tool call details not being copyable. * Fixed status indicator incorrectly showing for empty conversations in tab headers. * Fixed Drive team section header displaying in all caps. * Fixed Enter key not working in MCP installation modal. * Fixed slash command text not highlighting correctly in some cases. * Fixed input mode detection occasionally switching unexpectedly. * Fixed /edit command failing when filename had trailing whitespace. ### 2026.01.21 (v0.2026.01.21.08.14) [Section titled “2026.01.21 (v0.2026.01.21.08.14)”](#20260121-v0202601210814) **New Features** * Global search in files across your current directories. Use `CMD-F`/`CTRL-SHIFT-F` to open. * Expanded web search support to additional models. **Improvements** * Save AI prompts as Agent Mode workflows via context menu. * `/init` now generates AGENTS.md instead of WARP.md. * Added horizontal autoscrolling when jumping to line/column. * Better language detection for syntax highlighting. **Bug Fixes** * Fixed a memory leak that occurs when making an Agent Mode request. * Fixed an issue where “waiting for a password” notifications could be triggered incorrectly when launching certain terminal apps like neovim. * Fixed duplicate entries appearing in the agent management view for Slack-triggered conversations. * Fixed alias expansion being triggered in AI input when it should only apply to shell commands. * Fixed an issue where multiple shell commands could enter long-running mode in the same request batch. * Hide AI options in the command palette when AI is disabled. * Stopped highlighting search matches in reasoning blocks. * Fixed session viewer input being cleared when agent runs commands. ### 2026.01.14 (v0.2026.01.14.08.15) [Section titled “2026.01.14 (v0.2026.01.14.08.15)”](#20260114-v0202601140815) **New features** * Added footer for third party CLIs. * Added onboarding flow for new users. **Improvements** * Fixed duplicate rule suggestions on dismiss and save. * @-context search now matches on both name and content for notebooks, rules, and workflows. * Updated checkbox checkmark to use foreground color for better theme consistency. * Filter selections in the cloud agent management view now persist across app restarts. * MCP servers with OAuth authentication can now be used in warp agent run if previously authenticated in the desktop app. **Bug fixes** * Fixed a bug where text in the MCP tool call detail wasn’t selectable. * Fixed agent thread banner text overflow on smaller screens. ### 2026.01.07 (v0.2026.01.07.08.13) [Section titled “2026.01.07 (v0.2026.01.07.08.13)”](#20260107-v0202601070813) **New Features** * Added agent tips under the warping indicator. **Improvements** * Users can now create team-scoped API keys. * Agent tip now leads with `WARP.md` when mentioning project-scoped rule files. * The `oz agent run-cloud` command can now create cloud agent tasks that are shared with team members. * Updated agent profile switching tip to better explain why users would want to switch profiles. * Comments in the code review flow now render full width when there are 4 or fewer comments, improving readability. * When the completions menu is opened (tab), no completion item is selected by default. Pressing enter while no completion is selected directly runs the command currently in the input. Upon selecting a completion, it now automatically shows up in the input. This more closely mirrors behavior in traditional terminals. * The `oz agent run-cloud` command now supports saved prompts. * We added a new full terminal use model selector in the agents profile page so that you can select a specific model for full terminal use work. **Bug fixes** * Improved out-of-memory handling for cloud agents. * Fixed a configuration error creating team-scoped Warp-managed secrets. * Fixed ‘parameter not set’ error in zsh when users have setopt nounset enabled. * Fixed an issue where up arrow history could be ordered incorrectly on quit or restart Warp. # Built-in Code Editor > Make in-context code edits with Warp's built-in editor, featuring syntax highlighting, tabs, and Vim keybindings. Warp comes with a native code editor designed for quick, in-flow edits alongside your Agent conversations. Instead of switching back and forth to an IDE, you can open and edit files directly in Warp — with essentials like syntax highlighting, a tabbed file viewer, find and replace, Vim keybindings, and a file tree for browsing and adding files as context. The editor is built for fast changes to agent-generated code: renaming a variable, tweaking copy, or rewriting a short function. Having just enough editing power in-context makes it easier to land an agent’s changes and keep momentum. ### Opening files in Warp [Section titled “Opening files in Warp”](#opening-files-in-warp) **You can open files in the editor in several ways:** 1. **Click a file path** from the terminal output or an AI conversation and select “Open in Warp.” 2. **Use the file menu in the Command Palette** (`CMD + O` on macOS, `CTRL + SHIFT + O` on Windows or Linux) when in a Git-tracked repo to search for and open files inside that repo. 1. You can also access this via the magnifying glass icon in the pane coding toolbelt at the top left of any pane. ![Magnifying glass icon in the pane coding toolbelt for opening the file search.](/_astro/search-files-icon.G3ZlADOR_AFvgX.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) 3. **Browse via the** [File Tree (Project Explorer)](/code/code-editor/file-tree/) to open or create files. 4. **Opening a generated code diff** from an Agent Conversation: [Code Diffs in Agent Conversations](/agent-platform/local-agents/code-diffs/). **To save your changes to files**: use `CMD + S` on macOS or `CTRL + S` on Windows or Linux. ### Tabbed file viewer [Section titled “Tabbed file viewer”](#tabbed-file-viewer) Warp can group multiple files into a single tabbed viewer, reducing clutter and making it easier to work across multiple files. ![Multiple files grouped into a single tabbed file viewer in Warp's code editor.](/_astro/tabbed-file-viewer.Duz0bw_C_ZxaGH1.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) * Enabled by default for new users (can be toggled in **Settings** > **Features** > **General** > **Group files into a single editor pane**) * Reorder, close, or drag file viewers between tabs. * Merge entire panes together by dragging one into another. **Here’s a more in-depth demo:** ### **File layout options** [Section titled “File layout options”](#file-layout-options) Choose how new files open in Warp by default in: **Settings** > **Features** > **General** > **Choose a layout to open files in Warp** * **Split pane**: new files open alongside the current editor * **New tab**: new files open in their own tabbed viewer ### Supported languages [Section titled “Supported languages”](#supported-languages) The editor supports syntax highlighting and editing for a wide range of languages, including: Rust, Go, YAML, Python, JavaScript/TypeScript, JSX/TSX, Java/Groovy, C++, Shell/Bash, C#, HTML, CSS, C, JSON, HCL/Terraform, Lua, Ruby, PHP, TOML, Swift, Kotlin, Starlark, SQL, Powershell, and Elixir. We’re continuously expanding language support. ### Shared buffers [Section titled “Shared buffers”](#shared-buffers) When you open the same file in multiple tabs or panes, Warp keeps them in sync automatically. Edits made in one view are immediately reflected in all others, and when a file changes on disk (for example, after switching branches), every view updates together. ### Other editor features [Section titled “Other editor features”](#other-editor-features) Warp’s native code editor also supports the following features: * [Language Server Protocol (LSP)](/code/code-editor/language-server-protocol/) - Get hover info, go-to-definition, find references, inline diagnostics, and format-on-save powered by language servers for Rust, Go, Python, TypeScript/JavaScript, and C/C++. * [File Tree (Project Explorer)](/code/code-editor/file-tree/) - Browse, open, and manage your project with Warp’s native file tree. * [Find and Replace](/code/code-editor/find-and-replace/) - Use Warp’s built-in find and replace to quickly search across a file, jump between matches, and make precise edits with options for regex, case sensitivity, and smart case preservation. * [Code Editor Vim Keybindings](/code/code-editor/code-editor-vim-keybindings/) - Use Vim keybindings to edit code and text in Warp’s native code editor. # Code Editor Vim Keybindings > Use Vim keybindings in Warp's code editor for keyboard-driven navigation and editing. ## About Vim keybindings [Section titled “About Vim keybindings”](#about-vim-keybindings) The Vi family of programs (including Vim and Neovim) are modal text editors that allow for keyboard-driven text editing. Vi-style keybindings are especially popular among developers for their speed and precision in navigating and manipulating code. Warp’s [code editor](/code/code-editor/) now includes native support for Vim keybindings (also known as Vim mode), offering a familiar editing experience directly within your coding workflows. ### How to enable Vim keybindings [Section titled “How to enable Vim keybindings”](#how-to-enable-vim-keybindings) Vim mode in the code editor uses the same setting toggle as the input editor. To enable: * Through the [Command Palette](/terminal/command-palette/), search for “Vim Keybindings”. * Through **Settings** > **Features** > **Text Editing**, toggle “Edit code and commands with Vim keybindings”. Unlike the input editor, the Vim implementation in the code editor starts in Normal mode. ### Customizing Keybindings [Section titled “Customizing Keybindings”](#customizing-keybindings) At the moment, Warp only supports default Vim keybindings. One exception is the keyboard shortcut for exiting insert mode, which can be rebound under**Settings** > **Keyboard shortcuts** > **Exit Vim Insert Mode**, or through the [Command Palette](/terminal/command-palette/) search for “Exit Vim Insert Mode”. ## Supported Keybindings [Section titled “Supported Keybindings”](#supported-keybindings) Below is a list of the vim functionality implemented in Warp so far. ### Movement [Section titled “Movement”](#movement) See [Vim docs: motion](https://vimdoc.sourceforge.net/htmldoc/motion.html) for more information. #### Basic [Section titled “Basic”](#basic) | Command(s) | Description | | ---------------------------- | --------------------------------------------------- | | `h`, `j`, `k`, `l` | single-char movement | | ``, `` | single-char movement with line wrap | | `w`, `W`, `b`, `B`, `e`, `E` | word movement | | `ge`, `gE` | end of previous word | | `$` | end of line | | `0` | beginning of line | | `^` | first non-whitespace character of line | | `%` | jump to matching bracket | | `[`, `]` | prev/next unmatched bracket | | `_` | beginning of the current line | | `+` | first non-whitespace character of the next line | | `-` | first non-whitespace character of the previous line | | `{`, `}` | prev/next paragraph | #### Multi-line-related [Section titled “Multi-line-related”](#multi-line-related) | Command(s) | Description | | ---------- | ----------------------- | | `gg`, `G` | jump to first/last line | ### Editing [Section titled “Editing”](#editing) | Command(s) | Description | | ---------- | ----------------------------------------------------------- | | `r` | replace character under cursor | | `d`, `D` | delete a range or object | | `c`, `C` | change a range or object (delete, then go to insert mode) | | `s`, `S` | substitute (like change, but can only delete at the cursor) | | `x`, `X` | delete under cursor | | `y`, `Y` | yank (copy) into the clipboard | | `p`, `P` | paste from the clipboard | | `u`, `⌃r` | undo, redo | | `~` | toggle upper/lowercase under cursor | | `gu` | lowercase under cursor (`u` in visual mode) | | `gU` | uppercase under cursor (`U` in visual mode) | | `J` | join current and following lines | | `.` | repeat last edit | | `gcc` | toggle comments on current line | | `gc` | toggle comments on visual selection | See [Vim docs: editing](https://vimdoc.sourceforge.net/htmldoc/editing.html) for more information. #### Text Objects [Section titled “Text Objects”](#text-objects) | Command(s) | Description | | ---------------- | ------------------------------------------ | | `i` | inner (exclude delimiters in text object) | | `a` | around (include delimiters in text object) | | `w`, `W` | whitespace-delimited string (word) | | `"`, `'`, \`\`\` | quote-delimited string | | `(`, `{`, `[` | parenthesized/bracketed string | See [Vim docs: text objects](https://vimdoc.sourceforge.net/htmldoc/motion.html#text-objects) for more information. ### Search [Section titled “Search”](#search) #### Character Search [Section titled “Character Search”](#character-search) | Command(s) | Description | | ------------------ | ------------------------------------------------------ | | `t`, `T`, `f`, `F` | find next/prev matching character on line | | `;` | repeat last character search in the same direction | | `,` | repeat last character search in the opposite direction | See [Vim docs: left-right motions](https://vimdoc.sourceforge.net/htmldoc/motion.html#f) for more information. #### General Search [Section titled “General Search”](#general-search) Unlike Vim, general search commands don’t search within the buffer. Instead, they open Warp’s native command search. | Command(s) | Description | | ------------------ | ------------------------ | | `/`, `?`, `*`, `#` | open Warp command search | ### Mode Switching [Section titled “Mode Switching”](#mode-switching) | Command(s) | Description | | ---------- | ----------------------------------------------------------------- | | `i` | insert text before the cursor | | `I` | insert text before the first non-whitespace character in the line | | `a` | append text after the cursor | | `A` | append text at the end of the line | | `o` | begin new line below the cursor and insert text | | `O` | begin new line above the cursor and insert text | | `v` | visual character mode | | `V` | visual line mode | See [Vim docs: insert](https://vimdoc.sourceforge.net/htmldoc/insert.html#insert) and [Vim docs: visual mode](https://vimdoc.sourceforge.net/htmldoc/visual.html#visual-mode) for more information. ### Registers [Section titled “Registers”](#registers) | Command(s) | Description | | ---------- | --------------- | | `"` | register prefix | Warp currently supports the following registers: | Register name | Description | | ---------------- | ---------------------------------------------------------------- | | `a`–`z`, `A`–`Z` | named registers | | `+` | system clipboard | | `*` | system clipboard | | `"` | unnamed register, containing the text of the last delete or yank | See [Vim docs: registers](https://vimdoc.sourceforge.net/htmldoc/change.html#registers) for more information. ## Feedback [Section titled “Feedback”](#feedback) The best way to report bugs and request features is through Warp’s [GitHub Issues](https://github.com/warpdotdev/Warp/issues) page. Please note that the issue or request is for Vim Keybindings. # File Tree (Project Explorer) > Browse, open, and manage project files with Warp's native file tree and context menu actions. ![Warp's native file tree showing the project's file and folder structure in the left panel.](/_astro/filetree-main.B0QR6kNZ_Qq1Ws.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Warp includes a **native file tree** that makes it easy to explore and manage project files. The file tree is available whenever in any directory and it automatically reflects your project structure as files are added, removed, or changed. Note The file tree also works over SSH on macOS and Linux when Warp’s [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) is installed on the remote host. ### Opening the file tree [Section titled “Opening the file tree”](#opening-the-file-tree) You can open the file tree from the tools panel on the left hand side: * **Tools panel**: Click the Tools sidebar button, then open the File Tree tab (first tab in the panel). * Press `CMD + \` to open the left panel, then assign your own shortcut for File Tree (and Warp Drive) in **Settings** > **Keyboard shortcuts**. ![Opening the File Tree from the Tools panel sidebar in Warp.](/_astro/file-tree-project-explorer-tools-panel.BLIt4EpD_Z6Lbzs.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Note Warp supports icons for common file types. If a file type is missing an icon, please [file a GitHub issue](https://github.com/warpdotdev/Warp/issues) so we can review and add support. ### Browsing and opening files [Section titled “Browsing and opening files”](#browsing-and-opening-files) Clicking on a file opens it directly in Warp’s [**native Code Editor**](/code/code-editor/), where you can view and edit code in a separate pane or tab. ## File and folder actions [Section titled “File and folder actions”](#file-and-folder-actions) Right-clicking any **file** opens a context menu with several useful options: * **Open in new pane**: Open the file in a side-by-side pane. * **Open in new tab**: Open the file in a new tab. * **Attach as context**: Insert the file into an agent prompt so the Agent can analyze or reference it. * **Copy path**: Copy the absolute file path. * **Copy relative path**: Copy the path relative to your current working directory. ![Right-click context menu on a folder in the file tree.](/_astro/file-tree-context-menu.DWzoue-q_Z2ud9BP.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Right-click context menu on a folder in the file tree. Right-clicking any **folder** opens a context menu with the following options: * **Create new file**: Add a new file directly from the tree. ![Creating a new file directly from a folder's right-click context menu in the file tree.](/_astro/file-tree-new-file.BZUxMHZt_Zr34xb.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) * **Attach as context**: Insert the selected file into your agent prompt so the Agent can analyze or reference it. * **Copy path**: Copy the absolute file path to your clipboard. * **Copy relative path**: Copy the path relative to your current working directory. # Find and Replace > Search and replace text in Warp's code editor with regex, case sensitivity, and smart case preservation. ## Find [Section titled “Find”](#find) Press `CMD-F` on macOS or `CTRL-SHIFT-F` on Windows and Linux to open the find menu. As you type, all matches in the file are highlighted, and the match closest to your cursor is selected. * Press `ENTER` or use the down arrow to jump to the next match * Press `SHIFT-ENTER` or use the up arrow to go to the previous match * Click “Select All” to highlight all matches and close the menu You can toggle regex and case-sensitive search options directly in the query editor. [![](/assets/terminal/code-find-menu.poster.jpg)](/assets/terminal/code-find-menu.mp4) ## Replace [Section titled “Replace”](#replace) Click the dropdown to the left of the find menu to open the replace options. * Press Enter to replace the currently selected match * Use Replace All to replace all matches Toggle Preserve Case to keep the original casing of replaced text. Case is preserved in text that contains PascalCase, camelCase, hyphens, and underscores. For example: * Replacing “old” with “new” will turn “Old” into “New” and “OLD” into “NEW” * Replacing “oldValue” with “NewValue” will result in “newValue” * Replacing “OldValue” with “newValue” will result in “NewValue” * Replacing “my-Old-VALUE” with “my-new-value” will result in “my-New-VALUE” [![](/assets/terminal/code-replace-menu.poster.jpg)](/assets/terminal/code-replace-menu.mp4) # Language Server Protocol (LSP) > Get hover info, go-to-definition, diagnostics, and format-on-save via built-in LSP support. Warp’s code editor includes built-in support for the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), giving you IDE-grade code intelligence directly in the terminal. When you enable an LSP server for your project, you get hover documentation, go-to-definition, find references, inline diagnostics, and automatic formatting — all without leaving Warp. ## Supported languages [Section titled “Supported languages”](#supported-languages) Warp ships with support for the following language servers: | Language | Server | File extensions | | ----------------------- | ---------------------------- | -------------------------------------------------------------------- | | Rust | `rust-analyzer` | `.rs` | | Go | `gopls` | `.go` | | Python | `pyright` | `.py` | | TypeScript / JavaScript | `typescript-language-server` | `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs` | | C / C++ | `clangd` | `.c`, `.C`, `.h`, `.H`, `.hh`, `.cc`, `.cpp`, `.cxx`, `.hpp`, `.hxx` | We’re actively expanding language support. To request a language, [file a GitHub issue](https://github.com/warpdotdev/Warp/issues). ## How it works [Section titled “How it works”](#how-it-works) When you `cd` into a workspace with enabled language servers, Warp automatically starts them in the background. Features like hover, diagnostics, and go-to-definition become available once a server finishes initializing. As you edit, Warp sends incremental updates to keep everything in sync. If you close all files and terminals for a workspace, Warp shuts down the idle server to free resources. Note Warp uses your shell’s `PATH` to locate language server binaries. If a server isn’t found on your `PATH`, Warp can install it for you (see [Enabling a server](#enabling-a-server) below). ## Enabling and managing language servers [Section titled “Enabling and managing language servers”](#enabling-and-managing-language-servers) ### Enabling a server [Section titled “Enabling a server”](#enabling-a-server) Language servers are enabled **per workspace** (per Git repository root). When you open a file in a supported language for the first time, the **editor footer** shows an option to enable the appropriate language server. If the server binary is not installed on your system, Warp offers to install it for you. You can also manage servers from **Settings** > **Code** > **Indexing and projects**, where each initialized workspace shows its enabled language servers and their status. ### Server status indicator [Section titled “Server status indicator”](#server-status-indicator) The code editor footer displays a status icon for the active language server: * 🟢 **Green** - Server is running and ready. * 🟡 **Yellow** - Server is starting or processing a background task. * 🔴 **Red** - Server failed to start. Click the icon to see options. * ⚪ **Gray** - Server is stopped. Clicking the status icon opens a menu with options to **restart**, **stop**, **start**, or **view logs** for the server. ### Server logs [Section titled “Server logs”](#server-logs) Each language server writes logs to a file on disk. Access these logs from the footer menu (click the status icon and select “Open Logs”) or from **Settings** > **Code** > **Indexing and projects**. Logs are useful for debugging server startup failures or unexpected behavior. ## Editor features powered by LSP [Section titled “Editor features powered by LSP”](#editor-features-powered-by-lsp) ### Hover information [Section titled “Hover information”](#hover-information) Hover over a symbol to see its type signature, documentation, and other details provided by the language server. The hover tooltip appears after a brief delay and supports rich content including code blocks and Markdown. ### Go to definition [Section titled “Go to definition”](#go-to-definition) Hold `CMD` (macOS) or `CTRL` (Windows/Linux) and click a symbol to jump to its definition. If the definition is in a different file, Warp opens it in the code editor. While you hold the modifier key, the symbol is underlined on hover to indicate it is navigable. ### Find references [Section titled “Find references”](#find-references) `CMD`-click (macOS) or `CTRL`-click (Windows/Linux) on a symbol that is already at its definition to see a **Find References** card listing all references across the workspace. Click any reference to navigate to it. ### Inline diagnostics [Section titled “Inline diagnostics”](#inline-diagnostics) Warp displays errors and warnings from the language server as dashed underlines directly in the editor. Hover over an underlined range to see the full diagnostic message. Diagnostics update in real time as you edit and are briefly cleared while the server recalculates. ### Format on save [Section titled “Format on save”](#format-on-save) When you save a file (`CMD + S` / `CTRL + S`), Warp requests formatting from the language server before writing to disk. This applies the server’s configured formatting rules (indentation, trailing whitespace, final newlines, etc.). If the server doesn’t support formatting, the file is saved without formatting changes. ### Right-click context menu [Section titled “Right-click context menu”](#right-click-context-menu) When an LSP server is connected, right-clicking in the editor opens a context menu with LSP-powered actions, including go-to-definition and find references. LSP features stay in sync across [shared buffers](/code/code-editor/#shared-buffers) — if the same file is open in multiple tabs or panes, diagnostics, hover, and other features reflect the same content regardless of which view you’re looking at. ## Limitations [Section titled “Limitations”](#limitations) * **Local sessions only** - LSP is not available over SSH or WSL sessions. These are tracked in GitHub issues [#6831](https://github.com/warpdotdev/Warp/issues/6831) (SSH) and [#6744](https://github.com/warpdotdev/Warp/issues/6744) (WSL). * **One server per language** - Each language maps to a single server (for example, Rust always uses `rust-analyzer`). Custom server configurations are not yet supported. * **Project-scoped** - Language servers operate at the Git repository root level. Files outside a repository may not receive LSP features. * **Server availability** - Some features (like formatting) depend on the specific language server’s capabilities. Not all servers support all features. # Code Review panel > The Code Review panel lets you review, edit, and manage Git diffs in real time, with options to attach, revert, or open files directly. ## Overview [Section titled “Overview”](#overview) When you are working locally in a Git repository with uncommitted changes, the **Code Review panel** lets you inspect, edit, and manage code changes directly inside Warp. It integrates with Git and Warp’s Agents, giving you the ability to: * Review diffs and attach them as context for the Agent * Apply, edit, or revert changes in real time * See changes made outside of Warp or by Warp’s Agents automatically reflected Any uncommitted changes appear in the panel (or compare the changes on your branch against `main` or `master` ). Switching branches or saving files updates the panel instantly, so it always reflects the current state of your codebase. [Code Review Demo](https://www.loom.com/embed/96581523168742eb9b95c3973924728c) ![Full view of Code Review panel and terminal pane.](/_astro/code-review-panel-update.OokO3LEH_1Maom3.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Full view of Code Review panel and terminal pane. Note To review agent-generated diffs, leave inline comments, batch your feedback, and have the agent apply all requested changes, see [Interactive Code Review](/agent-platform/local-agents/interactive-code-review/). ## Opening the Code Review panel [Section titled “Opening the Code Review panel”](#opening-the-code-review-panel) The Code Review panel can be opened in several ways. Each entry point makes it easy to inspect and manage changes without leaving your workflow. Tip You can also open the Code Review panel with `CMD – SHIFT – +` on macOS or `CTRL – SHIFT – +` on Windows and Linux. #### 1. Git diff chip (terminal input) [Section titled “1. Git diff chip (terminal input)”](#1-git-diff-chip-terminal-input) In terminal mode, when you’re in a Git repository with changes, the Git diff chip shows the number of files modified along with lines added and removed. Clicking the chip opens the Code Review panel with the relevant diffs. ![Terminal input bar showing the Git diff chip with branch name, modified file count, and lines added and removed](/_astro/whole-UDI-bar.Dq745kRi_1zMYRX.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ![Git diff chip with a View changes tooltip showing branch name, file count, and lines changed](/_astro/git-chip-tooltip-1.DHuI0vKK_2ifyBU.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### 2. Agent conversation: review changes button [Section titled “2. Agent conversation: review changes button”](#2-agent-conversation-review-changes-button) When an Agent makes code edits in an [Agent Conversation](/agent-platform/local-agents/interacting-with-agents/), a `Review changes` button appears at the bottom of the conversation. Click the button to open the code review panel. ![Review changes at bottom of Agent Conversation.](/_astro/Blocklist-with-review-changes.2E5sJoew_25D94B.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ![Agent conversation footer with feedback buttons and a Review changes button](/_astro/review-changes-in-footer.BkDXacg7_1eqVjT.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### 3. Agent conversation: toolbelt (bottom right) [Section titled “3. Agent conversation: toolbelt (bottom right)”](#3-agent-conversation-toolbelt-bottom-right) During an Agent conversation, you can view all changed files in the toolbelt chips at the persistent bottom right. From there, you can open the Code Review panel directly. ![Agent conversation with toolbelt chips in the bottom right showing file changes and action buttons](/_astro/ai_control_panel_buttons_larger_view.Bv_iv2wN_Z1cQ8Bp.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### 4. Warp tab bar [Section titled “4. Warp tab bar”](#4-warp-tab-bar) In any Git-tracked repository, you can open the Code Review panel by clicking the `Code review` button in the top-right corner of Warp, next to your avatar. #### Viewing all edited files [Section titled “Viewing all edited files”](#viewing-all-edited-files) Inside the Code Review panel, you can open the file sidebar to browse all changed files in your repository. Clicking on a file will automatically scroll to that file in the panel. ![Viewing all edited files in the code review panel, with the file sidebar open.](/_astro/whole-git-diff-view-with-one-file-collapsed.K6v4OA7c_Z6MKLI.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Note By default, the Code Review panel opens as a pane on the right, but you can drag it to reposition wherever you prefer. ## Reviewing diffs [Section titled “Reviewing diffs”](#reviewing-diffs) By default, the Code Review panel shows all **uncommitted changes** on your current branch, excluding changes to files ignored by `.gitignore`. Warp offers two ways to review changes: 1. **Uncommitted changes**: view all edits you’ve made locally on the current branch. 2. **Changes vs. main**: compare your branch against `main` or `master` to see what would be included in a pull request to that branch, for instance. 1. Warp automatically detects the target branch and updates the comparison accordingly. 3. **Changes vs. another branch**: compare your work against any arbitrary branch for stacked PRs, feature comparisons, or alternate base branches. You can manually switch between the two views either in the Code Review panel or via the Git diff chip in the terminal input: ![Changing diff view in the Code Review Panel.](/_astro/diff-dropdown-to-change-base-from-the-code-review-pane.Cs6LBPHy_Zh3zXp.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ![Changing diff view from the terminal input.](/_astro/git-diff-change-base-dropdown.CtAXXlpi_2wfwxl.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ![Changing diff view against an arbitrary branch.](/_astro/arbitrary-branch-diff.r4zV7YE4_gqqYt.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Any saved edits made outside of Warp (e.g. in another editor), as well as changes applied by Warp’s Agents, appear automatically. The panel updates in real time, ensuring it always reflects the current state of your working file and directory. #### Attaching diffs as context [Section titled “Attaching diffs as context”](#attaching-diffs-as-context) The Code Review pane makes it simple to share changes with the Agent. You can attach an entire diff to a prompt so the Agent has full visibility into what was added or removed. ![Attaching a diff as context from the Code Review panel.](/_astro/attach-diff-hunk-as-context.Dqq-xqrq_Z28tmyE.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Attaching a diff as context from the Code Review panel. This ensures responses are grounded in your latest edits, whether you’re asking for feedback, explanations, or follow-up changes. For more details, see [Selection as Context](/agent-platform/local-agents/agent-context/selection-as-context/). #### Reverting diffs [Section titled “Reverting diffs”](#reverting-diffs) The Code Review panel lets you easily undo changes at different levels. In the gutter next to each diff, you’ll see an option to revert a hunk: roll back a specific set of changes (a “diff hunk”) within a file. This removes the added or modified lines and restores the previous version. ![Code diff gutter showing the Revert diff hunk tooltip on a changed line](/_astro/revert-diff-hunk.BJ1lv6RU_ZH63uw.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) When you revert, the changes are immediately updated in your working directory. The file is restored to match the selected version, so you can continue editing or commit without the reverted code. ### Opening Files from Code Review [Section titled “Opening Files from Code Review”](#opening-files-from-code-review) In addition to reviewing and editing diffs directly in the Code Review pane, you can open a file directly in Warp’s [Code Editor](/code/code-editor/). ![Code Review panel header showing file name, lines changed, and buttons for attach, revert, and open in editor](/_astro/code-review-header.BQGFE0jZ_2pXklL.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) * Clicking the **expand button** (right-most button on the header) opens the file in a new editor tab, allowing you to see the full file beyond just the changed lines. * This is useful when you need additional context around a diff, want to make broader edits, or prefer working in the full editor rather than inline. * Once opened, the file behaves like any other editor tab: you can scroll, edit, search, and save. * Any changes made in the editor automatically sync back into the Code Review pane, so the diff view always stays current. **Note**: from this code review file header, you can also attach a file diff as context into Warp’s agent, or discard all the changes on a single file. #### Directly editing code diffs [Section titled “Directly editing code diffs”](#directly-editing-code-diffs) Alternatively, from the Code Review panel, you are able to click and edit the diffs directly: ![Directly editing code in the Code Review panel inline diff view](/assets/terminal/directly-editing-diffs.gif) ### Sending comments to a running agent [Section titled “Sending comments to a running agent”](#sending-comments-to-a-running-agent) You can leave inline comments in the Code Review panel and send them directly to a running coding agent session, including third-party CLI agents like Claude Code, Codex, and others. This extends Warp’s [Interactive Code Review](/agent-platform/local-agents/interactive-code-review/) workflow to any supported CLI agent running in Warp. The agent receives your batch of comments and applies the requested changes. [![](/assets/terminal/code-review-inline-comment.poster.jpg)](/assets/terminal/code-review-inline-comment.mp4) For more on supported agents, see [Third-Party CLI Agents](/agent-platform/cli-agents/overview/). ### Discarding all changes [Section titled “Discarding all changes”](#discarding-all-changes) The Code Review panel also lets you discard every uncommitted change on your branch in one action. Clicking Discard all removes all local modifications shown in the panel and restores each file to its state on the base branch. This is useful when you want to reset your working directory, abandon a set of edits, or start a new iteration from a clean slate. ![Code Review panel header with Uncommitted changes dropdown, attach button, and Discard all button](/_astro/discard-all-changes.DDLHm61w_wbbkK.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Discarding changes will ask you confirm, but still make sure you’ve saved or backed up anything you want to keep before using it. Note Warp natively supports Git worktrees for Code Review and other features. See [Git worktrees](/code/git-worktrees/) for details. # Git worktrees > Warp natively supports Git worktrees, letting you work on multiple branches simultaneously with full Code Review, Codebase Context, and Agent support. Warp natively supports [Git worktrees](https://git-scm.com/docs/git-worktree) — a Git feature that lets you check out multiple branches simultaneously in separate directories, all backed by the same repository. This is different from simply switching branches: with worktrees, you can have `~/project` on `main` and `~/project-wt/feature-x` on `feature-x` at the same time, with no stashing or context-switching required. ## How worktrees work in Warp [Section titled “How worktrees work in Warp”](#how-worktrees-work-in-warp) Warp automatically detects worktree checkouts. When you open a terminal in a worktree directory, Warp recognizes the `.git` file that points back to the main repository and treats the worktree as a fully functional repository: * **Code Review panel** — Each worktree has its own Code Review panel showing uncommitted changes for that worktree’s branch. You can review diffs, revert hunks, and discard changes independently in each worktree. * **Git Status chip** — The Git diff chip and branch indicator in the input bar reflect the correct branch and change counts for whichever worktree your terminal is in. * **File watching** — Warp watches both the worktree’s working directory and the shared `.git` directory. Changes to shared Git state (such as new commits pushed to the remote) are detected and propagated across all open worktrees. * **Codebase Context** — Each worktree is indexed independently for [Codebase Context](/agent-platform/capabilities/codebase-context/), so Agents have accurate context for whichever worktree you’re working in. * **Repository-scoped features** — Project rules (`AGENTS.md`, `WARP.md`), ignore files, and other repository-scoped settings work correctly within each worktree. ## When to use worktrees [Section titled “When to use worktrees”](#when-to-use-worktrees) Worktrees are especially useful when: * **Reviewing a PR while working on your own branch** — Open the PR branch in a separate worktree without disrupting your in-progress work. * **Running tests on one branch while coding on another** — Keep a long test suite running in one worktree while continuing development in another. * **Parallel local agent work** — When orchestrating multiple local agents on the same repository, each agent can operate in its own worktree to avoid file conflicts. ## Creating a worktree [Section titled “Creating a worktree”](#creating-a-worktree) To create a new worktree from your terminal: ```bash # Create a worktree for an existing branch git worktree add ../my-feature feature-branch # Create a worktree with a new branch git worktree add -b new-branch ../new-branch main # List all worktrees git worktree list # Remove a worktree when done git worktree remove ../my-feature ``` Once created, open the worktree directory in a new Warp tab or pane. Warp detects it automatically — no additional configuration is needed. Note Commit state change notifications (e.g. detecting new commits) may be slightly delayed in worktrees compared to standard repositories. Warp is actively improving this. # Code overview > Generate and edit code with Warp's coding agent, review inline diffs, and apply changes across your codebase. Note On macOS and Linux SSH sessions, Warp’s [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) brings the file tree, native file reads, and native code diffs to remote hosts. See [Feature support over SSH](/code/ssh-feature-support/) for the current support matrix. ## From prompt to production [Section titled “From prompt to production”](#from-prompt-to-production) Warp Code is a suite of features designed to help you take agent-generated code from the initial prompt and project setup all the way to deployment and production. It is powered by Warp’s dedicated coding agent, which consistently ranks among the top results on [SWE-bench Verified](https://www.swebench.com/#verified) and [Terminal-Bench](https://www.tbench.ai/leaderboard). In addition to Warp’s modern, [native code editor](/code/code-editor/), it includes: * [Codebase Context](/agent-platform/capabilities/codebase-context/) for accurate, context-aware agent responses * [Project Rules](/agent-platform/capabilities/rules/) and Commands to tailor agent behavior per repository * A dedicated [Code Review](/code/code-review/) experience for reviewing and editing diffs * [Zero-state and setup flows](/code/overview/#getting-started-with-coding-in-warp) to quickly start a new project or initialize an existing one ### Coding Agent [Section titled “Coding Agent”](#coding-agent) Warp’s coding agent is designed to help you generate, edit, and manage code directly in the [Agentic Development Environment](https://www.warp.dev/blog/reimagining-coding-agentic-development-environment). It detects opportunities to apply code diffs and surfaces them inline, allowing you to review and apply changes without switching to an external IDE. When you need to make manual edits, you can open Warp’s native code editor. ### How it works [Section titled “How it works”](#how-it-works) * **Prompt-driven coding**: You write natural language prompts such as *“Add a retry mechanism to this API call”* or *“Fix the failing unit test in auth.test.ts.”* * **Inline code diffs**: When the agent proposes changes, it shows them as diffs you can inspect, modify, or reject. * **Agent steering**: You can refine prompts, interrupt and retry, or attach context (such as a file, diff, or selection) to guide the agent toward better results. ![Coding Features Overview](https://i.ytimg.com/vi/W8rCsznM5HA/sddefault.jpg) Note With the [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) installed on a remote macOS or Linux host, the coding agent applies edits using Warp’s native diff tool over SSH. When the extension isn’t installed, the agent falls back to terminal commands (i.e. `sed`, `grep`) to make changes. ### Examples of coding capabilities [Section titled “Examples of coding capabilities”](#examples-of-coding-capabilities) Code responds to prompts related to code generation, editing, and analysis. Here are some examples: * **Code creation** * “Write a function in JavaScript to debounce an input” * “Generate a Python class for managing user sessions with Redis.” * **Error-driven fixes** * “Fix the TypeScript error shown in the last build output.” * “Resolve this merge conflict by keeping backend changes and updating tests accordingly.” * **Refactoring** * “Update all instances of var to let in this file.” * “Extract the database logic from app.js into a new db.js module and update imports.” * **Multi-file and repo-wide changes** * “Add headers to all .py files in this directory.” * “Replace requests with httpx across the codebase, updating imports and error handling.” * **Complex workflows** (examples shown below — in practice, prompts should include more detail for best results) * “Implement OAuth2 authentication, update affected routes, and add tests.” * “Identify functions without test coverage and create Jest test files for them.” * “Optimize slow SQL queries in queries.sql and regenerate migrations.” ![How to kick off a coding task](https://i.ytimg.com/vi/IuFSuOYstfg/sddefault.jpg) ![How to interpret & edit Warp’s coding output](https://i.ytimg.com/vi/dm-P63USsVg/sddefault.jpg) ## Getting started with coding in Warp [Section titled “Getting started with coding in Warp”](#getting-started-with-coding-in-warp) Warp provides multiple entry points to begin coding with agents, whether you are starting a new project, opening an existing one, or cloning from GitHub. Each new tab shows a **zero state** that lets you choose how to proceed. ![Zero-state tab with 3 starting points for agentic coding in Warp.](/_astro/code_mode.CqXT0MNX_1ve2CP.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Zero-state tab with coding starting points. #### 1. Starting a new project [Section titled “1. Starting a new project”](#1-starting-a-new-project) To begin a new project, select **Create a New Project** from the tab. You can start directly with a prompt (Warp will suggest ideas) or configure the project manually. Warp sets up the repository with an `AGENTS.md` file (filename must be in all caps) containing [project rules](/agent-platform/capabilities/rules/#project-rules) and enables [codebase indexing](/agent-platform/capabilities/codebase-context/) to provide the agent with full context. #### 2. Open an existing repo [Section titled “2. Open an existing repo”](#2-open-an-existing-repo) Select **Open Repository** to use your computer’s file picker. If you choose a Git repository, Warp automatically changes into the directory and runs the `/init` setup command (a built-in “[slash command](/agent-platform/capabilities/slash-commands/)”) if the repo has not already been initialized. Warp will detect the repository, index the codebase, and prepare it for coding. * For non-Git folders, Warp simply changes into the directory without initialization. * If you have an existing project that is not yet initialized, you can run `/init` manually to bootstrap it with a version-controlled `AGENTS.md` file. * This view also shows a list of your three most recently used repositories and AI conversations for quick access, as well as a list of recent directories (which behave like running `cd`). #### 3. Clone a repo [Section titled “3. Clone a repo”](#3-clone-a-repo) Select **Clone Repository** to paste in a repo link or clone directly from GitHub. Warp places you in the cloned folder and automatically runs the `/init` flow to set up project rules and indexing. ## Learn more about code features: [Section titled “Learn more about code features:”](#learn-more-about-code-features) * [Code Editor](/code/code-editor/) - Warp’s built-in code editor lets you make quick, in-context edits with essentials like syntax highlighting, tabs, find and replace, Vim keybindings, and a file tree. * [Language Server Protocol (LSP)](/code/code-editor/language-server-protocol/) - Warp integrates with language servers to provide hover info, go-to-definition, find references, inline diagnostics, and format-on-save for Rust, Go, Python, TypeScript/JavaScript, and C/C++. * [Codebase Context](/agent-platform/capabilities/codebase-context/) - Warp indexes your Git-tracked codebase to help Agents understand your code and generate accurate, context-aware responses. No code is stored on Warp servers. * [Code Review](/code/code-review/) - review, edit, and manage Git diffs in real time, with options to attach, revert, or open files directly. * You can also enter [Interactive Code Review](/agent-platform/local-agents/interactive-code-review/) to comment on changes, guide the agent, or adjust individual edits as they happen. * [Code Diffs](/agent-platform/local-agents/code-diffs/) - Learn how to review, refine, and apply code changes generated by Warp’s agents using the built-in visual diff editor. # Feature support over SSH > A reference for which Warp coding features are available over SSH and which are limited to local sessions. When you [Warpify an SSH session](/terminal/warpify/ssh/), Warp’s core terminal features — the input editor, completions, blocks, history search, and more — work the same as they do locally. With Warp’s [SSH extension](/terminal/warpify/ssh/#installing-the-ssh-extension) installed on the remote host, additional coding features such as the file tree, native file reading, and native code diffs also work over SSH on macOS and Linux. This page documents which features are available based on which path you’re on: * **SSH extension** - Installed on first connect when you choose **Install Warp’s SSH extension**. Available on macOS and Linux remote hosts. * **Legacy tmux-based Warpification** - An older alternative that’s being deprecated. It remains available today for clients that don’t yet ship the SSH extension (for example, Windows clients). See [Legacy: tmux-based Warpification](/terminal/warpify/ssh/#legacy-tmux-based-warpification). Note When a native tool isn’t available on the current path, the Agent falls back to terminal commands (e.g. `cat`, `sed`, `grep`). You can still accomplish most coding tasks, but the experience is less seamless than working locally or through the SSH extension. ## Features that work over SSH [Section titled “Features that work over SSH”](#features-that-work-over-ssh) The following features work in Warpified remote sessions on both paths: * **Agent Mode conversations** — Chat with the Agent, ask questions, and request code changes on the remote host. * **Running shell commands** — The Agent can execute commands on the remote machine on your behalf. * **Grep and file glob** — The Agent can search for files and patterns using terminal-based grep and glob tools. * **MCP tools** — Model Context Protocol integrations remain available. * **Terminal features** — The input editor, command completions, autosuggestions, command history, blocks, and all other core terminal features work as expected. The following features require the **SSH extension**: * **File tree (Project Explorer)** — The [file tree sidebar](/code/code-editor/file-tree/) reflects the remote project structure and updates as you navigate or change files. * **Native file reading** — The Agent reads remote files through Warp’s built-in file reading tool instead of shelling out to `cat`. * **Native code diffs** — The Agent applies edits as inline [code diffs](/agent-platform/local-agents/code-diffs/) you can review and approve, instead of using `sed` or other shell commands. * **Reliable, parallel completions** — Generators run in parallel over a single multiplexed connection, so completions stop hitting the remote host’s `MaxSessions` ceiling and stop occasionally injecting errors into your blocks. ## Features not yet available over SSH [Section titled “Features not yet available over SSH”](#features-not-yet-available-over-ssh) The following features require local filesystem access and are not yet available in Warpified remote (SSH) sessions on either path: * **Code editor (file open/edit UI)** — Warp’s [native code editor](/code/code-editor/) is not yet available in remote sessions. You cannot open, view, or edit remote files in Warp’s built-in editor. * **Computer use** — The Agent cannot take screenshots or interact with the remote machine’s desktop. Note WSL sessions have the same limitations as SSH and are not currently covered by the SSH extension. Feature request for WSL support: [GitHub #6744](https://github.com/warpdotdev/Warp/issues/6744). # Enterprise overview > Warp Enterprise provides the security, control, and collaboration features organizations need to deploy Warp across their engineering teams at scale. Warp Enterprise is built for organizations that want to accelerate software development with agents while maintaining security, compliance, and administrative control. It brings Warp’s **Agentic Development Environment** to your entire engineering organization with the governance features IT and security teams require. Warp has two core products: * **Warp Terminal** - A modern terminal designed for agentic development where developers run commands, collaborate with agents, and orchestrate autonomous work from the command line. * **Oz** - Warp’s programmable agent for running and coordinating agents at scale. Oz powers all agents in Warp, whether they run locally or in the cloud, and provides the orchestration, tracking, and control plane for scalable agent workflows. ## Who Warp Enterprise is for [Section titled “Who Warp Enterprise is for”](#who-warp-enterprise-is-for) Warp Enterprise serves three primary audiences: * **IT admins and platform teams** - Deploy and manage Warp across your organization with SSO, centralized administration, and usage visibility * **Engineering managers** - Give your teams powerful agent development tools while enforcing coding standards and best practices through shared team resources * **Professional developers** - Accelerate your work across the entire SDLC with state-of-the-art agents, team knowledge sharing, and collaborative workflows that keep you in control ## Key capabilities [Section titled “Key capabilities”](#key-capabilities) ### Enterprise administration [Section titled “Enterprise administration”](#enterprise-administration) * **Single Sign-On (SSO)** - Authenticate via your existing identity provider (Okta, Microsoft Entra ID, Google Workspace, and more) * **Centralized Admin Panel** - Manage team settings, user permissions, and feature controls from one location * **User roles and permissions** - Control access with Team Owner, Team Admin, and Member roles * **Usage visibility** - Monitor team adoption and agent usage across your organization ### Security and compliance [Section titled “Security and compliance”](#security-and-compliance) * **SOC 2 Type II certified** - Meets enterprise security and compliance requirements * **Zero Data Retention (ZDR)** - No customer data is retained, stored, or used for training by contracted LLM providers * **Open source client** - Warp’s client code is published under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE) at [`warpdotdev/warp`](https://github.com/warpdotdev/warp) for security review and audit * **Bring Your Own LLM (BYOLLM)** - Route inference through your own cloud infrastructure (AWS Bedrock) * **Flexible deployment** - Choose Warp-hosted or hybrid deployment models * **Telemetry controls** - Configure what data is collected at the team level ### Team collaboration [Section titled “Team collaboration”](#team-collaboration) * **Warp Drive team workspace** - Share Workflows, Notebooks, Prompts, Plans, Rules, and Environment Variables across your team * **Codebase Context** - Team-level code indexing helps agents understand your repositories and generate accurate, context-aware responses * **MCP integrations** - Connect to your team’s tools (Linear, Sentry, Figma, GitHub, and more) for context-aware agent responses * **Session sharing** - Collaborate on terminal sessions and Oz conversations with shareable links ### Oz agent capabilities [Section titled “Oz agent capabilities”](#oz-agent-capabilities) * **State-of-the-art agents** - Multi-model agents with full terminal access, code editing, and autonomous task execution * **Oz cloud agents** - Run agents in the cloud for unlimited parallelization, background automation, and long-running workflows. Perfect for PR reviews, scheduled tasks, and distributed work across multiple repositories * **Integrated control plane** - Launch, orchestrate, and manage local, cloud, and autonomous agents from a unified interface. Track all agent activity across your team from the Oz dashboard * **Agent Profiles** - Customize agent behavior, models, autonomy levels, and permissions * **Rules and guardrails** - Enforce coding standards, tech stack preferences, and security practices through team-wide or project-specific rules * **Multi-agent support** - Support for all major models and CLI coding agents (Oz, Claude Code, Codex, Copilot) ## What this section covers [Section titled “What this section covers”](#what-this-section-covers) This section organizes Enterprise documentation to help you deploy, secure, and scale Warp across your organization: * **Getting started** - Installation, SSO setup, and onboarding for admins and developers * **Security and compliance** - Security overview and SSO configuration * **Enterprise features** - Bring Your Own LLM (BYOLLM) * **Team management** - Admin panel, roles and permissions, and access controls ## Getting started [Section titled “Getting started”](#getting-started) Note Warp Enterprise is available through annual contracts. [Contact our sales team](https://warp.dev/contact-sales) to learn more or start a trial. **For IT admins**: Start with the [Admin Panel](/enterprise/team-management/admin-panel/) to manage team settings, configure agent policies, and enforce security controls. See [Roles and permissions](/enterprise/team-management/roles-and-permissions/) for user access details. **For developers**: Jump to [Getting started for developers](/enterprise/getting-started/getting-started-developers/) to download Warp, log in, and start using key features like Codebase Context and Warp Drive. Or try the [Enterprise quickstart](/enterprise/getting-started/quickstart/) for a 10-minute walkthrough. **For security teams**: Review our [Security page](https://www.warp.dev/legal/security) and [Privacy documentation](/support-and-community/privacy-and-security/privacy/) to understand how Warp handles data, encryption, and compliance. ## Why enterprises choose Warp [Section titled “Why enterprises choose Warp”](#why-enterprises-choose-warp) Organizations adopt Warp Enterprise to: * **Accelerate development velocity** - Agents automate tedious tasks across the SDLC, from environment setup to incident response, so developers focus on what matters * **Maintain security and control** - Deploy on your infrastructure, route inference through your cloud accounts, and keep developers in control with full visibility and guardrails * **Scale best practices** - Share team knowledge, coding standards, and operational runbooks through Warp Drive to compound productivity gains across teams * **Reduce context switching** - Keep developers in flow with a terminal-first environment that integrates agents, code editing, and tool integrations in one place * **Get scaffolding built in** - Deploy agents at scale without building custom infrastructure—Warp provides orchestration, tracking, and collaboration out of the box ## Support and resources [Section titled “Support and resources”](#support-and-resources) * **Documentation** - Comprehensive guides throughout this enterprise section * **Contact sales** - [Schedule a demo or start a trial](https://warp.dev/contact-sales) * **Support** - Enterprise customers receive priority support via dedicated Slack/Teams channels * **Warp Guides** - Video tutorials and training at [docs.warp.dev/guides](/guides/) # Enterprise Analytics API > Programmatically access team-level usage data for Warp's enterprise plans — per-team summaries, per-user rollups, and message-level activity events. The Enterprise Analytics API lets enterprise admins pull Warp usage data into their own dashboards, cost-allocation tooling, or audit pipelines. It exposes three read-only endpoints over HTTPS that return aggregated team metrics, per-user rollups, and message-level activity events for the agents your team runs in Warp and Oz. Early access The Enterprise Analytics API is in Early Access. It is available to all enterprise teams. To start collecting data for your team, an admin must open the Warp app and turn on **Enterprise Usage Reporting (Early Access)** in **Admin Panel** > **Privacy** — no usage data is recorded until that toggle is on. The API exposes **aggregated usage metrics** only (counts, credit spend, code-change tallies, and message-level metadata). It does not return the raw text of agent conversations. To retain and inspect full conversation contents, enable [cloud-synced conversations](/agent-platform/local-agents/cloud-conversations/) under **Settings** > **Privacy**. ## What you can do with the API [Section titled “What you can do with the API”](#what-you-can-do-with-the-api) * **Build productivity dashboards** - Track adoption across users and teams over time using `summary` and `users`. * **Allocate credit spend** - Break down usage by user, model, or run type (`local` vs. `cloud`) to attribute cost to teams or projects. * **Audit message-level activity** - Filter the `events` endpoint by `run_type`, `user_id`, `conversation_id`, `message_type`, or `tool_type` for compliance reviews and incident investigation. * **Power custom reporting** - Pipe the JSON responses into your own warehouse, BI tool, or alerting system. ## Prerequisites and access [Section titled “Prerequisites and access”](#prerequisites-and-access) Before you can call the API, your team must satisfy all of the following: * **Enterprise plan** - The Analytics API is available to all enterprise teams during Early Access; no separate enrollment is required. * **Admin role on the team** - Calls are rejected unless the authenticated user has admin-level permissions on the enterprise team. See [Roles and permissions](/enterprise/team-management/roles-and-permissions/). * **A personal Warp API key** - Authenticate requests with a key from **Settings** > **Cloud platform** > **Oz Cloud API Keys** in the Warp app. See [API Keys](/reference/cli/api-keys/) for step-by-step instructions. Team API keys are not accepted by these endpoints — only personal API keys belonging to a team admin work. * **Enterprise Usage Reporting toggle enabled** - In the Warp app, go to **Admin Panel** > **Privacy** and turn on **Enterprise Usage Reporting (Early Access)**. Until this toggle is on, no usage data is recorded for your team and the endpoints will return empty datasets even if every other prerequisite is met. Caution Personal API keys inherit the access of the user who created them. Treat them like any other admin credential and rotate them when team membership changes. ## Quickstart [Section titled “Quickstart”](#quickstart) The following example fetches a team-level summary for the last day. Set your API key first: ```bash export WARP_API_KEY="wk-..." ``` Then call the `summary` endpoint: ```bash curl "https://app.warp.dev/api/v1/enterprises/analytics/summary" \ -H "Authorization: Bearer $WARP_API_KEY" ``` Once an admin has turned on the **Enterprise Usage Reporting (Early Access)** toggle for your team, you’ll get a JSON payload aggregating credit usage and conversation counts across the team. Continue to the [Endpoints](#endpoints) section for per-endpoint details. ## Endpoints [Section titled “Endpoints”](#endpoints) All endpoints share the same base URL, authentication, and shared validation rules: * **Base URL** - `https://app.warp.dev/api/v1/enterprises/analytics` * **Authentication** - `Authorization: Bearer $WARP_API_KEY` header on every request. * **Dates** - Pass `start_date` and `end_date` as RFC 3339 timestamps with timezone (for example, `2026-04-01T00:00:00Z` or `2026-04-01T00:00:00-07:00`). When omitted, the API defaults to a 1-day window ending at the current time. `start_date` must be strictly before `end_date`; otherwise the request returns `400 Bad Request`. * **Performance** - Wider date ranges and finer `group_by_period` granularity scan more data and can take noticeably longer to return. For dashboards that refresh frequently, prefer narrower windows or coarser grouping. ### `GET /api/v1/enterprises/analytics/summary` [Section titled “GET /api/v1/enterprises/analytics/summary”](#get-apiv1enterprisesanalyticssummary) Returns a single team-level rollup of conversation counts, credit spend, and code-change activity for the requested window. When `group_by_period` is set, the response is a time series with one bucket per period. **Query parameters:** * `start_date` (optional) - RFC 3339 timestamp. Defaults to one day before `end_date`. * `end_date` (optional) - RFC 3339 timestamp. Defaults to the current time. * `group_by_period` (optional) - One of `day`, `week`, or `month`. When set, the resulting `period_list` is capped at 365 periods; longer ranges with finer granularity are rejected with `400 Bad Request`. **Example:** ```bash curl "https://app.warp.dev/api/v1/enterprises/analytics/summary?start_date=2026-04-01T00:00:00Z&end_date=2026-04-30T23:59:59Z&group_by_period=day" \ -H "Authorization: Bearer $WARP_API_KEY" ``` **Ungrouped response shape:** ```json { "data": { "local": { "total_conversations_count": 1234, "total_credits_spent": 8421.5, "code_changes": { "file_changes": { "suggested": 412, "accepted": 305 }, "lines_of_code": { "suggested": { "added_count": 9821, "removed_count": 2104 }, "accepted": { "added_count": 7102, "removed_count": 1488 } } } }, "cloud": { "total_conversations_count": 412, "total_credits_spent": 2310.4, "code_changes": { "file_changes": { "suggested": 88, "accepted": 64 }, "lines_of_code": { "suggested": { "added_count": 1450, "removed_count": 320 }, "accepted": { "added_count": 1102, "removed_count": 248 } } } } } } ``` **Grouped response shape (`group_by_period=day`):** ```json { "group_by_period": "day", "period_list": ["2026-04-01", "2026-04-02", "..."], "data": { "local": { "total_conversations_count": [42, 51, "..."], "total_credits_spent": [310.1, 412.5, "..."], "code_changes": { "file_changes": { "suggested": [12, 18, "..."], "accepted": [9, 14, "..."] }, "lines_of_code": { "suggested": { "added_count": [240, 380, "..."], "removed_count": [55, 90, "..."] }, "accepted": { "added_count": [180, 290, "..."], "removed_count": [40, 70, "..."] } } } }, "cloud": { "...": "same shape as local" } } } ``` In the grouped response, every leaf array is the same length as `period_list`, and the index of each value corresponds to the same index in `period_list`. Periods with no recorded activity are filled with default empty values (`0` for numeric counts and credit totals, and `0`-valued sub-objects for `code_changes`). ### `GET /api/v1/enterprises/analytics/users` [Section titled “GET /api/v1/enterprises/analytics/users”](#get-apiv1enterprisesanalyticsusers) Returns per-user aggregated usage, split into `local` (Warp app) and `cloud` (Oz cloud agents) sections. Results are paginated. **Query parameters:** * `start_date` (optional) - RFC 3339 timestamp. Defaults to one day before `end_date`. * `end_date` (optional) - RFC 3339 timestamp. Defaults to the current time. * `group_by_period` (optional) - One of `day`, `week`, or `month`. When set, each user record’s per-run-type fields are arrays indexed by the response-level `period_list`. * `page` (optional) - Page number, 1-indexed. Default `1`. * `page_size` (optional) - Items per page. Default `10`. **Example:** ```bash curl "https://app.warp.dev/api/v1/enterprises/analytics/users?page=1&page_size=25" \ -H "Authorization: Bearer $WARP_API_KEY" ``` **Ungrouped response shape:** ```json { "data": [ { "user_id": "user-uuid-abc", "email": "alex@example.com", "local": { "distinct_conversation_count": 42, "credits_spent": 310.1, "model_usage": [ { "model_id": "claude-4-7-opus", "distinct_conversation_count": 30, "credits_spent": 240.0 } ], "code_changes": { "file_changes": { "suggested": 18, "accepted": 12 }, "lines_of_code": { "suggested": { "added_count": 412, "removed_count": 88 }, "accepted": { "added_count": 305, "removed_count": 64 } } } }, "cloud": { "...": "same shape as local" } } ], "pagination": { "current_page": 1, "page_size": 25, "total_pages": 4, "total_count": 87 } } ``` When `group_by_period` is set, each `local`/`cloud` block’s scalars become arrays indexed by the response-level `period_list` (same convention as the grouped `summary` response). Within `model_usage`, each entry’s `distinct_conversation_count` and `credits_spent` likewise become arrays. ### `GET /api/v1/enterprises/analytics/events` [Section titled “GET /api/v1/enterprises/analytics/events”](#get-apiv1enterprisesanalyticsevents) Returns paginated, message-level activity events for fine-grained audits and dashboards. Each row corresponds to a single message produced or processed by an agent — the same canonical message stream the client and Warp UI see. **Query parameters:** * `start_date` (optional) - RFC 3339 timestamp. Defaults to one day before `end_date`. The window between `start_date` and `end_date` cannot exceed 365 days. * `end_date` (optional) - RFC 3339 timestamp. Defaults to the current time. * `page` (optional) - Page number, 1-indexed. Default `1`. * `page_size` (optional) - Items per page. Default `10`. Maximum `100`. * `run_type` (optional) - Filter by `local` or `cloud`. * `user_id` (optional) - The unique identifier of a single team member, as returned by the `users` and `events` endpoints. * `conversation_id` (optional) - Restrict results to one conversation. * `message_type` (optional) - Filter by message variant. Common values include `agent_output`, `tool_call`, `tool_call_result`, `user_query`, and `agent_reasoning`; additional values are emitted as new agent capabilities ship. Internal scaffolding (for example `model_used`, `server_event`, `messages_received_from_agents`, `events_from_agents`, and `debug_output`) is not recorded and never appears here. * `tool_type` (optional) - For `tool_call` / `tool_call_result` messages, restrict to a specific tool. Values are the snake\_case name of the tool (for example `apply_file_diffs`, `run_shell_command`, `search_codebase`, `grep`, `call_mcp_tool`). Events are returned newest-first, ordered by `message_end_timestamp DESC, message_id DESC`. **Example:** ```bash curl "https://app.warp.dev/api/v1/enterprises/analytics/events?run_type=cloud&message_type=tool_call&tool_type=apply_file_diffs&page_size=100" \ -H "Authorization: Bearer $WARP_API_KEY" ``` **Response shape:** ```json { "data": [ { "message_id": "msg-uuid", "llm_request_ids": ["llm-req-uuid"], "message_type": "tool_call", "tool_type": "apply_file_diffs", "message_start_timestamp": "2026-04-15T19:21:08Z", "message_end_timestamp": "2026-04-15T19:21:11Z", "conversation_id": "conv-uuid", "user_id": "user-uuid-abc", "email": "alex@example.com", "user_selected_model": "auto", "run_type": "cloud", "model_ids": ["claude-4-7-opus"], "credit_charged": 0.42, "code_changes": { "file_changes": { "suggested": 3, "accepted": 2 }, "lines_of_code": { "suggested": { "added_count": 48, "removed_count": 12 }, "accepted": { "added_count": 36, "removed_count": 8 } }, "was_edited_by_user": false }, "git_context": { "head": "a1b2c3d", "branch": "feature/analytics-api" }, "error_type": null } ], "pagination": { "current_page": 1, "page_size": 100, "total_pages": 12, "total_count": 1180 } } ``` Fields are populated as follows: * `llm_request_ids` and `model_ids` are arrays. Most LLM-backed messages have a single entry, but some messages may be backed by multiple LLM requests. * `credit_charged` is the per-message proportional share of the backing LLM request’s cost. Messages with no LLM call (for example client-submitted `tool_call_result` rows) carry `0`. * `code_changes` is omitted (or `null`) for messages that don’t suggest or apply file changes. * `was_edited_by_user` is `true` when the user edited the diff before accepting, `false` when accepted as-is, and `null` when the message had no acceptance event. * `git_context` is omitted (or `null`) when no git state was captured for the message. * `error_type` is populated only when the backing LLM request errored. ## Pagination [Section titled “Pagination”](#pagination) The `users` and `events` endpoints use offset-based pagination with `page` and `page_size` query parameters. Every paginated response includes a `pagination` block: * `current_page` - The page returned, 1-indexed. * `page_size` - The number of items requested per page. * `total_pages` - The total number of pages available for the current query. * `total_count` - The total number of records matching the query across all pages. To iterate, request `page=1` first, then increment `page` until you’ve fetched `total_pages` pages. The `events` endpoint caps `page_size` at `100`; values above that are rejected. The `users` endpoint defaults to `page_size=10`. ## Common use cases [Section titled “Common use cases”](#common-use-cases) * **Executive dashboards** - Combine the `summary` endpoint’s grouped output with your BI tool to chart team-wide adoption and credit spend over time. * **Cost allocation** - Use the `users` endpoint to attribute credit spend to individuals, teams, or projects for chargeback or showback. * **Adoption monitoring** - Track per-user `distinct_conversation_count` over time to identify power users, onboard slow adopters, and measure rollout impact. * **Compliance audit trails** - Pull the `events` endpoint with `message_type=tool_call` filters to log code-changing actions for security review. ## FAQ [Section titled “FAQ”](#faq) ### How fresh is the data? [Section titled “How fresh is the data?”](#how-fresh-is-the-data) Usage data is recorded as agents run and is typically available within a few minutes. There is no guaranteed SLA on freshness during Early Access. ### Who can call the API? [Section titled “Who can call the API?”](#who-can-call-the-api) Any authenticated user with admin-level permissions on an enterprise team. Calls from non-admin users return `403 Forbidden`. ### What kind of API key works? [Section titled “What kind of API key works?”](#what-kind-of-api-key-works) Only **personal** Warp API keys created by an admin from **Settings** > **Cloud platform** > **Oz Cloud API Keys**. Team API keys are explicitly rejected by these endpoints. See [API Keys](/reference/cli/api-keys/) for how to create one. ### Are these calls billed? [Section titled “Are these calls billed?”](#are-these-calls-billed) No. Analytics API calls don’t consume Warp credits. ### What time range can I query? [Section titled “What time range can I query?”](#what-time-range-can-i-query) The `events` endpoint enforces a hard 365-day window between `start_date` and `end_date`. The `summary` and `users` endpoints don’t enforce a fixed window, but the grouped variants are capped at 365 periods. ## Related resources [Section titled “Related resources”](#related-resources) * [API Keys](/reference/cli/api-keys/) - Create and manage personal Warp API keys. * [Admin Panel](/enterprise/team-management/admin-panel/) - Manage team settings, including the **Privacy** section. * [Roles and permissions](/enterprise/team-management/roles-and-permissions/) - Required admin role for Analytics API access. * [Architecture and deployment](/enterprise/enterprise-features/architecture-and-deployment/) - Where enterprise data is stored and how it transits Warp’s infrastructure. # Architecture and deployment > Understand Warp's system architecture and choose the right deployment model for your organization - Warp-hosted, self-hosted, or hybrid. Warp’s architecture separates the **control plane** (orchestration, observability, and LLM inference) from the **execution plane** (where agents run, code is accessed, and commands execute). This separation gives enterprise teams flexibility to choose where sensitive workloads run while maintaining centralized management and visibility. Use this information to evaluate which deployment model fits your organization’s security, compliance, and operational requirements. ## System architecture overview [Section titled “System architecture overview”](#system-architecture-overview) Warp’s cloud agent infrastructure has four key components: 1. **Trigger** - What starts an agent run (CI step, webhook, cron schedule, Slack mention, CLI command, or API/SDK call). 2. **Orchestration** - What decides what to run and tracks it (Oz orchestrator or your own system). 3. **Execution** - Where the agent actually runs (Warp-hosted environment, your infrastructure, or your existing CI/orchestrator). 4. **Visibility** - How the team monitors and intervenes (Oz dashboard, session sharing, APIs/SDKs). ### High-level data flow [Section titled “High-level data flow”](#high-level-data-flow) * **Warp terminal (client)** ↔ **Warp backend (control plane)** ↔ **LLM providers** * The Warp backend handles task orchestration, observability, and LLM inference routing. * LLM providers operate under **Zero Data Retention (ZDR)** agreements. They do not store or train on your data. * The **execution plane** is where source code is accessed, commands run, and build artifacts are produced. This can run on Warp’s infrastructure or yours. ## Warp-hosted (SaaS) [Section titled “Warp-hosted (SaaS)”](#warp-hosted-saas) Warp-hosted is the default deployment model. Oz agents run on Warp-managed infrastructure with no setup required from your team. ### How it works [Section titled “How it works”](#how-it-works) * Agents execute in **isolated Docker containers** on Warp-hosted infrastructure (GCP). * The Oz orchestrator manages agent lifecycle - provisioning, execution, monitoring, and cleanup. * Environments are ephemeral and destroyed after each run. ### Triggers [Section titled “Triggers”](#triggers) Warp-hosted agents can be triggered by: * **First-party integrations** - Slack, Linear, and other connected tools * **Scheduled agents** - Cron-like automation for recurring work * **CLI** - `oz agent run-cloud` for on-demand cloud execution * **API/SDK** - Programmatic triggers from your own systems ### When to use [Section titled “When to use”](#when-to-use) * You want the simplest path to scalable cloud agent execution. * You need to run many tasks in parallel without building sandboxing infrastructure. * Your security requirements are met by Warp’s SOC 2 Type II certified infrastructure with ZDR. ## Self-hosted execution [Section titled “Self-hosted execution”](#self-hosted-execution) For organizations that need agent execution and source code to remain within their own network boundary, Warp supports self-hosted execution. Note Self-hosted execution is available exclusively on Warp’s **Enterprise** plan. ### Split architecture [Section titled “Split architecture”](#split-architecture) Self-hosted deployments use a split architecture: * **Execution plane (customer-hosted)** - Source code repositories, build artifacts, shell commands, and runtime secrets stay on your infrastructure. Note that during agent interactions, code context is included in LLM prompts and session transcripts that route through Warp’s servers under ZDR agreements (see [What transits Warp’s servers](#what-transits-warps-servers)). * **Control plane (Warp-hosted)** - Task orchestration, observability data, and LLM inference route through Warp’s servers under Zero Data Retention (ZDR) agreements. ### Deployment modes [Section titled “Deployment modes”](#deployment-modes) **Unmanaged** - Use `oz agent run` to run agents in your existing orchestrator or CI environment. Supports Linux, macOS, and Windows with no Docker dependency. * Best for teams that already have CI/CD infrastructure or internal orchestrators. * You control scheduling, scaling, and environment setup. * Warp provides cloud connectivity, shared context, visibility, and session sharing. **Managed** - Run the `oz-agent-worker` daemon to let the Oz platform orchestrate agents in isolated Docker containers on your infrastructure. * The worker process connects to Oz via WebSocket and receives tasks automatically. * Agents run in isolated Docker containers managed by the worker. * You get the same orchestration capabilities as Warp-hosted, but execution stays on your infrastructure. ### Network requirements [Section titled “Network requirements”](#network-requirements) Self-hosted agents require **outbound-only** network access. No inbound network access is required. **Egress requirements:** * Outbound access to Warp’s backend services (for orchestration and observability) * For managed mode: access to Docker Hub and GitHub (for container images and repository access) ### When to use [Section titled “When to use”](#when-to-use-1) * Compliance or security requirements prevent using Warp-hosted compute. * Source code and execution must stay within your network boundary. * You want Oz orchestration and visibility without sending code to Warp’s infrastructure. ## Hybrid deployments [Section titled “Hybrid deployments”](#hybrid-deployments) Organizations can combine Warp-hosted and self-hosted execution to balance convenience with security requirements. ### How it works [Section titled “How it works”](#how-it-works-1) * Route sensitive workloads (e.g., production code, regulated data) to self-hosted agents. * Route less sensitive workloads (e.g., open-source tooling, internal utilities) to Warp-hosted agents. * Both execution modes share the same Oz dashboard, session sharing, and API/SDK visibility. ### Example configurations [Section titled “Example configurations”](#example-configurations) * **By sensitivity** - Production repositories run on self-hosted agents; staging and development run on Warp-hosted. * **By team** - Security-sensitive teams (e.g., infrastructure, payments) use self-hosted; other teams use Warp-hosted. * **By task type** - Scheduled maintenance tasks run on Warp-hosted; ad-hoc debugging runs self-hosted in dev environments. ## Data flow and boundaries [Section titled “Data flow and boundaries”](#data-flow-and-boundaries) Understanding what data stays where is critical for security and compliance decisions. ### What stays on customer infrastructure (self-hosted) [Section titled “What stays on customer infrastructure (self-hosted)”](#what-stays-on-customer-infrastructure-self-hosted) * **Source code** - Repository contents and version history * **Build artifacts** - Compiled outputs and generated files * **Shell commands** - Terminal commands and their output * **Runtime secrets** - Environment variables and credentials * **Execution logs** - Agent run logs and diagnostics ### What transits Warp’s servers [Section titled “What transits Warp’s servers”](#what-transits-warps-servers) * **Task orchestration** - Scheduling, routing, and lifecycle management * **Observability data** - Run status, duration, and metadata * **LLM inference** - Prompts and responses (which include code context from agent interactions) routed through Warp to contracted LLM providers under ZDR agreements * **Session sharing data** - Session transcripts, which include code context from agent interactions, when session sharing is enabled for monitoring and collaboration ## Choosing a deployment model [Section titled “Choosing a deployment model”](#choosing-a-deployment-model) Consider the following when selecting a deployment model: **Warp-hosted** is right if: * You want zero infrastructure management for agent execution. * Your security team is comfortable with SOC 2 Type II certified, ZDR-covered infrastructure. * You need maximum parallelization and scalability. **Self-hosted** is right if: * Compliance requirements mandate that code stays within your network. * You need to integrate with existing CI/CD or infrastructure tooling. * You want full control over the execution environment. **Hybrid** is right if: * Different teams or repositories have different security requirements. * You want the convenience of Warp-hosted for most work but need self-hosted for sensitive workloads. ## Related resources [Section titled “Related resources”](#related-resources) * [Deployment Patterns](/agent-platform/cloud-agents/deployment-patterns/) - Detailed patterns for CLI-only, Oz-hosted, and self-hosted setups * [Security overview](/enterprise/security-and-compliance/security-overview/) - Data handling, encryption, and compliance details * [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) - Route inference through your own cloud infrastructure * [Admin Panel](/enterprise/team-management/admin-panel/) - Configure agent policies and security settings * [Contact sales](https://warp.dev/contact-sales) - Discuss deployment options for your organization # Bring your own LLM > Route Warp's agents through your AWS Bedrock models for billing control and infrastructure flexibility. Warp supports **Bring Your Own LLM (BYOLLM)** for enterprise teams that need to run inference on their own cloud infrastructure. With BYOLLM, your team can use Warp’s agents while routing inference through models hosted in your AWS Bedrock environment. This gives you control over cloud spend and model hosting, without changing how your team works in Warp. Caution BYOLLM currently supports **AWS Bedrock** only. Coming soon: Azure Foundry and Google Vertex support. BYOLLM applies to interactive Oz agents in the terminal. Oz cloud agents do not yet support BYOLLM routing. Note BYOLLM is only available on Warp’s Enterprise plan. Contact [warp.dev/contact-sales](https://warp.dev/contact-sales) to learn more. ## Key features [Section titled “Key features”](#key-features) * **Cloud-native credentials** - Authenticate using each user’s AWS IAM identity. Warp does not store API keys. * **Admin-enforced routing** - Team admins configure which models are available to users in AWS Bedrock, with the ability to disable non-Bedrock model access entirely. * **Consolidated billing** - Inference costs are billed directly to your AWS account, leveraging existing cloud commitments. ## How BYOLLM works [Section titled “How BYOLLM works”](#how-byollm-works) When BYOLLM is enabled, Warp redirects inference calls to your AWS Bedrock environment instead of using model providers’ direct APIs. Here’s the high-level flow: 1. **Admin configures routing** - Your team admin sets routing policies in Warp’s admin settings (e.g., “Route Claude Sonnet 4.5 through AWS Bedrock; disable direct Anthropic API”). 2. **Team members authenticate** - Each team member authenticates to AWS locally using the AWS CLI (`aws login`). 3. **Warp routes requests** - When a team member uses an interactive Oz agent in the terminal, Warp uses their short-lived session credentials to authenticate requests to your configured AWS Bedrock API endpoint. 4. **Inference executes in your cloud** - The model runs in your AWS account. Responses return to the Warp client. ### Credential lifecycle [Section titled “Credential lifecycle”](#credential-lifecycle) BYOLLM uses **cloud-native IAM authentication**, not long-lived API keys: * **Automatic refresh** - Session tokens refresh automatically every \~15 minutes. Users can enable auto-refresh by opening **Settings** and searching for `AWS Bedrock`, or when prompted during first credential expiration. With auto-refresh enabled, sessions can run uninterrupted for up to 12 hours (depending on your AWS admin configuration). * **Per-user credentials** - Credentials are not shared across the organization. Your cloud provider’s default credential provider chain (e.g., AWS CLI) provisions and refreshes them locally. * **No storage or logging** - Warp never stores or logs your cloud session tokens on its servers. This approach ensures access management stays with your cloud provider, giving admins member-by-member control. ### Model availability [Section titled “Model availability”](#model-availability) BYOLLM supports the intersection of models that Warp supports and models available on AWS Bedrock. Currently, only **Claude models** (Anthropic) are available through AWS Bedrock. OpenAI and Google models are not available on Bedrock. To determine which models you can use with BYOLLM: * [Model Choice](/agent-platform/capabilities/model-choice/) - Full list of Warp-supported models. * [Supported models in Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) - AWS Bedrock model availability. A model must appear on both lists to be available through BYOLLM. ## Enabling BYOLLM [Section titled “Enabling BYOLLM”](#enabling-byollm) ### Prerequisites [Section titled “Prerequisites”](#prerequisites) Before configuring BYOLLM, confirm the following: * Your organization has the desired models enabled in AWS Bedrock. * You have admin access to both Warp’s [Admin Panel](/enterprise/team-management/admin-panel/) and your AWS IAM settings. * Team members have the AWS CLI installed locally. ### Step 1: Configure routing policies (admin) [Section titled “Step 1: Configure routing policies (admin)”](#step-1-configure-routing-policies-admin) In the [Admin Panel](/enterprise/team-management/admin-panel/), configure which models should route through AWS Bedrock: 1. From the [Admin Panel](/enterprise/team-management/admin-panel/), navigate to the BYOLLM or model routing settings. 2. Select which models should use your cloud provider (e.g., “Claude Sonnet 4.5 via AWS Bedrock”). 3. Optionally, disable direct API access to enforce provider-only routing. ### Step 2: Provision IAM roles (cloud admin) [Section titled “Step 2: Provision IAM roles (cloud admin)”](#step-2-provision-iam-roles-cloud-admin) Grant your team members the necessary permissions in AWS. Use least-privilege IAM policies. **Example: AWS Bedrock minimum IAM policy** ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "BedrockModelAccess", "Effect": "Allow", "Action": [ "bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream" ], "Resource": [ "arn:aws:bedrock:*::foundation-model/*", "arn:aws:bedrock:*:*:inference-profile/*", "arn:aws:bedrock:*:*:application-inference-profile/*" ] } ] } ``` Note This policy covers Warp’s current usage. Warp uses global inference profiles for models when available. ### Step 3: Authenticate locally (team member) [Section titled “Step 3: Authenticate locally (team member)”](#step-3-authenticate-locally-team-member) Each team member authenticates to AWS using the AWS CLI: ```bash aws login ``` Confirm your AWS environment and region are correctly configured before using Warp. ### Step 4: Validate [Section titled “Step 4: Validate”](#step-4-validate) Run a test prompt in Warp using a model configured for BYOLLM routing. Verify: * The request completes successfully. * Logs appear in AWS CloudWatch. ## BYOLLM usage and billing behavior [Section titled “BYOLLM usage and billing behavior”](#byollm-usage-and-billing-behavior) ### Billing [Section titled “Billing”](#billing) When a request routes through BYOLLM: * **Warp does not consume credits** for that request. * Your cloud provider account receives the inference costs directly. ### Routing behavior [Section titled “Routing behavior”](#routing-behavior) Warp’s agents automatically select the best model for your task while respecting your admin’s routing policies. If you configure a model for BYOLLM, requests for that model route to AWS Bedrock. ### Failover behavior [Section titled “Failover behavior”](#failover-behavior) If a BYOLLM request fails (e.g., due to expired credentials, insufficient permissions, or provider quota limits), Warp attempts to fall back to the next available model your admin has enabled. For example, if Claude Sonnet 4.5 on Bedrock fails but your admin also enabled it via direct API, Warp falls back to the direct API to avoid disruption. If a fallback uses a direct API model, that request consumes Warp credits. If no fallback is available (e.g., the admin disabled all non-Bedrock models), Warp displays a clear error message. ## Security and data handling [Section titled “Security and data handling”](#security-and-data-handling) ### Credential security [Section titled “Credential security”](#credential-security) * **No long-lived API keys** — BYOLLM uses cloud-native IAM with short-lived session tokens. * **Per-user authentication** — Each team member authenticates individually; credentials are not shared. * **No storage or logging** — Warp never stores or logs your cloud session tokens on its servers. ### Zero Data Retention (ZDR) [Section titled “Zero Data Retention (ZDR)”](#zero-data-retention-zdr) Warp maintains **SOC 2 compliance** and has **Zero Data Retention (ZDR)** agreements with its contracted LLM providers. However, when using BYOLLM: * **Your** cloud account settings determine data retention policies. * Warp cannot enforce ZDR for requests routed through your infrastructure. * If your cloud account does not have ZDR enabled, your provider may retain data according to their terms. ### Auditability [Section titled “Auditability”](#auditability) * Warp keeps all runs fully steerable and logged within Warp. * Your cloud account retains provider-side logs (usage, latency, errors). ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### Common errors [Section titled “Common errors”](#common-errors) * **Missing or expired credentials** — Re-authenticate using `aws login`. To avoid interruptions, enable auto-refresh by opening **Settings** and searching for `AWS Bedrock`, or when prompted during credential expiration. * **Insufficient permissions** — Verify your IAM policy includes the required actions and resources. * **Region or model mismatch** — Confirm the model is enabled in your AWS region and that your environment is configured for the correct region. * **Provider quota limits** — Check your AWS Bedrock quota and request increases if needed. ### Debugging steps [Section titled “Debugging steps”](#debugging-steps) 1. Verify local authentication: run `aws sts get-caller-identity`. 2. Check your effective IAM policy for the required permissions. 3. Confirm the model ID and region match your Warp configuration. 4. Inspect AWS CloudWatch logs for request details and errors. ## FAQ [Section titled “FAQ”](#faq) ### How is BYOLLM different from BYOK? [Section titled “How is BYOLLM different from BYOK?”](#how-is-byollm-different-from-byok) **BYOK (Bring Your Own Key)** lets individual users add their own API keys for direct model provider access (e.g., Anthropic, OpenAI, Google). Warp stores keys locally on the user’s device. **BYOLLM (Bring Your Own LLM)** routes inference through your organization’s cloud infrastructure (AWS Bedrock) using cloud-native IAM. Admins configure it at the admin level and it applies to the entire team. | Feature | BYOK | BYOLLM | | ------------------- | ----------------------- | ------------------------- | | Configuration level | User | Admin/Team | | Authentication | API keys (local) | Cloud IAM (per-user) | | Billing | Direct to provider | Your cloud account | | Data locality | Provider infrastructure | Your cloud infrastructure | ### Does BYOLLM work with Auto? [Section titled “Does BYOLLM work with Auto?”](#does-byollm-work-with-auto) Auto model selection is disabled as soon as your admin disables **any** Direct API model, regardless of your AWS Bedrock configuration. If all Direct API models remain enabled and BYOLLM is configured, Auto will try to use your enabled AWS Bedrock models first, falling back to Direct API only if that fails (e.g., invalid/missing AWS credentials, Bedrock outage). ### Where does compute run and who pays? [Section titled “Where does compute run and who pays?”](#where-does-compute-run-and-who-pays) Inference runs in **your AWS account**. You pay AWS directly for compute usage. Warp does not consume credits for BYOLLM-routed requests. ### What data does Warp store? Do you store our cloud credentials? [Section titled “What data does Warp store? Do you store our cloud credentials?”](#what-data-does-warp-store-do-you-store-our-cloud-credentials) Warp **does not store or log** your cloud session tokens. Credentials are used transiently to sign requests and are never persisted on Warp servers. Warp stores standard run metadata (timestamps, model used, etc.) but does not retain the content of your prompts or responses when using BYOLLM. ### Can admins enforce provider-only routing and disable Warp-managed models? [Section titled “Can admins enforce provider-only routing and disable Warp-managed models?”](#can-admins-enforce-provider-only-routing-and-disable-warp-managed-models) Yes. Admins can configure routing policies to require specific models to use BYOLLM and disable direct API access to Warp-managed model endpoints. ## Related resources [Section titled “Related resources”](#related-resources) * [Bring Your Own API Key](/support-and-community/plans-and-billing/bring-your-own-api-key/) * [Model Choice](/agent-platform/capabilities/model-choice/) — Full list of supported models * [Admin Panel](/enterprise/team-management/admin-panel/) — Configure team settings * [Contact Sales](https://warp.dev/contact-sales) — Get help with enterprise setup # Enterprise FAQ > Answers to common questions about Warp Enterprise, including login issues, SSO, and getting started. ## Login and SSO [Section titled “Login and SSO”](#login-and-sso) ### I can’t log in with SSO [Section titled “I can’t log in with SSO”](#i-cant-log-in-with-sso) **Problem:** Error message when trying to log in via SSO. **Solution:** 1. Make sure you’re logging in through [app.warp.dev/login](https://app.warp.dev/login), not your SSO provider’s portal. 2. Select **Continue with SSO** and enter your work email or domain. 3. If you have an existing Warp account, log in with your original credentials and [link it to SSO first](https://app.warp.dev/link_sso). 4. Complete the linking process. 5. Log out and log back in with **Continue with SSO**. ### I logged in with another method before and can’t use SSO now [Section titled “I logged in with another method before and can’t use SSO now”](#i-logged-in-with-another-method-before-and-cant-use-sso-now) **Problem:** You created a Warp account with email/Google/GitHub, but your organization now requires SSO. **Solution:** 1. Go to [app.warp.dev/login](https://app.warp.dev/login). 2. Log in with your original method. 3. Navigate to [app.warp.dev/link\_sso](https://app.warp.dev/link_sso). 4. Complete the linking process. 5. Log out and log back in with **Continue with SSO**. ### Warp won’t open from my SSO provider [Section titled “Warp won’t open from my SSO provider”](#warp-wont-open-from-my-sso-provider) **Problem:** Clicking Warp in Okta/Microsoft Entra ID portal shows an error. **Solution:** This is a known limitation. Warp cannot be launched directly from SSO provider portals. Instead: 1. Go to [app.warp.dev/login](https://app.warp.dev/login). 2. Click **Continue with SSO**. 3. Complete authentication. ## Team and access [Section titled “Team and access”](#team-and-access) ### Team invite links not working [Section titled “Team invite links not working”](#team-invite-links-not-working) **Common causes:** * Invite link expired or was revoked. * User’s email domain doesn’t match configured restrictions. **Solution:** 1. Generate a new invite link. 2. Verify domain restrictions match the user’s email. ### Users can’t see new admin settings [Section titled “Users can’t see new admin settings”](#users-cant-see-new-admin-settings) **Problem:** You changed a setting in the Admin Panel, but users don’t see the change. **Solution:** 1. Verify the setting is not set to “Respect User Setting.” 2. Ask users to restart Warp to force a settings refresh. 3. Confirm users are members of the correct team. 4. Check that users have logged in with SSO (not a personal account). ## Additional help [Section titled “Additional help”](#additional-help) For more troubleshooting, see: * [Troubleshooting login documentation](/support-and-community/troubleshooting-and-support/troubleshooting-login-issues/) * Contact your team admin for organization-specific issues. * Reach out to Warp support via your team’s dedicated Slack/Teams channel. * Join Warp’s [Slack community](https://go.warp.dev/join-preview) to connect with other Warp users and engineers. # Getting started for developers > Download Warp, log in to your team, and start using agents, Codebase Context, and collaborative features to accelerate your development workflow. This guide helps developers get up and running with their team in Warp. You’ll learn how to download Warp, log in with your organization’s SSO, and configure key features like Codebase Context, Warp Drive, and Agent Profiles to accelerate your work across the entire SDLC (all while staying in your terminal). When you use agents in Warp, you’re using **Oz agents**. Oz is Warp’s programmable agent for running and coordinating agents at scale, whether they run locally on your machine or in the cloud. Oz provides the orchestration, tracking, and control plane that makes scaling agent workflows seamless. Note New to Warp Enterprise? Try the [Enterprise quickstart](/enterprise/getting-started/quickstart/) for a 10-minute walkthrough of SSO login, Warp setup, and running your first Oz agent. ## Step 1: Download and install Warp [Section titled “Step 1: Download and install Warp”](#step-1-download-and-install-warp) Warp is available for macOS, Linux, and Windows. ### Download Warp [Section titled “Download Warp”](#download-warp) Visit [warp.dev/download](https://warp.dev/download) and select your platform: * **macOS** - Download the `.dmg` installer (macOS 10.15 Catalina or later) * **Linux** - Download the `.deb`, `.rpm`, or use the install script * **Windows** - Download the `.exe` installer (Windows 10 or later) ### Install Warp [Section titled “Install Warp”](#install-warp) **macOS:** 1. Open the downloaded `.dmg` file. 2. Drag Warp to your Applications folder. 3. Launch Warp from Applications or Spotlight. **Linux:** ```bash # Debian/Ubuntu sudo dpkg -i warp-terminal_*.deb # Fedora/RHEL sudo rpm -i warp-terminal-*.rpm # Or use the install script curl -fsSL https://warp.dev/install.sh | bash ``` **Windows:** 1. Run the downloaded `.exe` installer. 2. Follow the installation wizard. 3. Launch Warp from the Start menu. ## Step 2: Log in to your team [Section titled “Step 2: Log in to your team”](#step-2-log-in-to-your-team) ### Logging in with SSO [Section titled “Logging in with SSO”](#logging-in-with-sso) If your organization uses SSO (most enterprise teams do): 1. Launch Warp. 2. When prompted, log in or create an account. 3. Click **Continue with SSO**. 4. Enter your work email or your organization’s domain. 5. Complete authentication with your SSO credentials when redirected to your identity provider. Caution Do not attempt to launch Warp directly from your SSO provider’s app portal (e.g., Okta dashboard). This will result in an error. Always log in through Warp at [app.warp.dev/login](https://app.warp.dev/login). ### Logging in with an invite link [Section titled “Logging in with an invite link”](#logging-in-with-an-invite-link) If you received an invite link from your team admin: 1. Click the invite link in your email or message. 2. From the signup page, log in using SSO if it’s configured for your team, otherwise use one of the other sign in methods (Google, GitHub, or email). 3. After authentication, you’ll automatically join your team. ### Linking an existing account to SSO [Section titled “Linking an existing account to SSO”](#linking-an-existing-account-to-sso) If you were using Warp before your organization enabled SSO: 1. Go to [app.warp.dev/login](https://app.warp.dev/login). 2. Log in with your original method (email, Google, or GitHub). 3. Once logged in, navigate to [app.warp.dev/link\_sso](https://app.warp.dev/link_sso). 4. Follow the prompts to link your account to SSO. 5. From now on, use **Continue with SSO** to log in. ## Step 3: Set up key features [Section titled “Step 3: Set up key features”](#step-3-set-up-key-features) ### Codebase Context [Section titled “Codebase Context”](#codebase-context) Codebase Context indexes your Git repositories so agents can understand your code and provide accurate, context-aware responses across large, multi-repo systems. **Setting up Codebase Context:** First, enable codebase indexing in your settings: 1. Go to **Settings** > **Code** > **Indexing and projects**. 2. Toggle **Enable Codebase Indexing** to turn it on. 3. Optionally, enable **Index new folders by default** to automatically index repositories as you navigate to them. Caution Codebase Context is a feature your team admin controls. If you don’t see these settings or they are disabled, contact your admin to enable this feature for your team. **Indexing your repositories:** Once codebase indexing is enabled, you can index individual repositories: 1. Navigate to a Git repository in your terminal. 2. Run the `/init` command. 3. Warp begins indexing your codebase. 4. You’ll be prompted to create an `AGENTS.md` file (optional but recommended). **What gets indexed:** * All Git-tracked files in your repository * Up to 200,000 files per repository * Files excluded in `.gitignore` or `.warpindexingignore` are automatically skipped **Privacy:** During indexing, your code is sent to Warp’s servers for processing where embeddings are created and stored. The code itself is not saved—only the embeddings are persisted. This allows agents to understand your codebase structure and context without storing your actual source code. Note For Oz cloud agents: Code snippets may be stored as part of conversation records when agents create or modify files, since diffs are preserved in the conversation history. ### Agent Profiles [Section titled “Agent Profiles”](#agent-profiles) Agent Profiles let you configure how Warp’s built-in Oz agents behave. Profiles give you direct control over model selection, autonomy, tools, and permissions for your agent workflows. **Creating an Agent Profile:** 1. Go to **Settings** > **Agents** > **Profiles**. 2. Click **New Profile**. 3. Configure: * **Name and description** * **Model** - Choose which LLM to use * **Autonomy level** - How much agents can do without asking * **Tools** - Enable/disable terminal use, code editing, web search * **Permissions** - What agents can access (repos, files, secrets) 4. Click **Save**. **Using profiles:** Switch between profiles based on your task: * **High autonomy** for routine tasks like writing tests or updating docs * **Low autonomy** for sensitive operations like infrastructure changes * **Specific models** for cost optimization or task requirements ### Warp Drive [Section titled “Warp Drive”](#warp-drive) Warp Drive is your workspace for saving and sharing Workflows, Notebooks, Prompts, Rules, and Environment Variables. **Accessing Warp Drive:** 1. Click the tools panel icon in the top left of Warp. 2. Click the Warp Drive icon from the top of the tools panel. 3. Two Warp Drive sections display: * **Team** (top) - Resources shared across your team. * **Personal** (bottom) - Your individual resources. **What you can add to Warp Drive:** * **Workflows** - Parameterized commands you use repeatedly (e.g., deploy scripts, environment setup) * **Notebooks** - Interactive runbooks combining markdown and executable code blocks * **Prompts** - Saved agent prompts for recurring tasks (e.g., “review this PR”, “write unit tests”) * **Plans** - Agent-generated execution plans for complex tasks that agents can then run step-by-step * **Rules** - Coding standards and conventions agents should follow * **Environment Variables** - Configuration that can be loaded into your terminal session **Creating your first Workflow:** 1. From Warp Drive, click **+** in your Personal or Team section. 2. Select **Workflow**. 3. Enter a name, description, and command. 4. Add parameters if needed (e.g., `{{branch_name}}`). 5. Click **Save**. **Using team resources:** Your team admin may have already created shared resources. Explore the Team section of Warp Drive to see what’s available—including onboarding notebooks, deployment workflows, and coding standards rules. ### MCP (Model Context Protocol) [Section titled “MCP (Model Context Protocol)”](#mcp-model-context-protocol) MCP connects Warp’s agents to external tools and services for enhanced context. **Configuring MCP servers:** 1. Go to **Settings** > **Agents** > **MCP servers** or access via Warp Drive. 2. Browse the library of available MCP servers: * **Linear** - Access issues and project context * **Sentry** - Pull error tracking and stack trace information * **Figma** - Reference designs and specifications * **GitHub** - Access repository and PR context * And more… 3. Click **+** next to a server to add it. 4. Configure credentials and connection details. 5. Toggle the server on/off as needed. Your team may have shared MCP configurations. Check for a share icon next to team-configured servers to use them without manual setup. ## Step 4: Start using Warp [Section titled “Step 4: Start using Warp”](#step-4-start-using-warp) ### Everyday workflows [Section titled “Everyday workflows”](#everyday-workflows) Warp keeps you in your terminal with agent help across the entire SDLC: **Environment setup** * “Set up Node 20, Python 3.12, and Docker Desktop” * Save setup steps as a Workflow in Warp Drive for future use **Understanding codebases** * “How does authentication flow through this system?” * “What patterns does this repo use for error handling?” **Writing code** * Use the `/plan` command for complex features * Review diffs in real-time with the code review panel * Leave comments on specific lines for the agent to address **Debugging** * Start a debugger (`gdb`, `lldb`) and bring in an agent * Agents can operate debuggers and REPLs in natural language * Attach terminal output to agent conversations for analysis **Version control** * “Stage these changes and write a detailed commit message” * “Create a PR with a description following our template” * Set up Rules to enforce Git commit conventions **Testing** * “Write unit tests for this function following our existing patterns” * “Run the test suite and explain what failed” * Configure Oz cloud agents to run test suites and validate coverage on PRs in the background ### Learning resources [Section titled “Learning resources”](#learning-resources) * **Warp Guides** - Short video tutorials at [docs.warp.dev/guides](/guides/) * Getting Started with Warp * Warp Code features * Developer workflows * MCP, Rules, and Prompts * **Documentation** - Comprehensive guides at [docs.warp.dev](https://docs.warp.dev) ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) For common login, SSO, and access issues, see the [Enterprise FAQ](/enterprise/getting-started/faq/). ## Next steps [Section titled “Next steps”](#next-steps) Now that you’re set up: * **Explore agent capabilities** - Learn about [agents in Warp](/agent-platform/local-agents/overview/) and [Oz cloud agents](/agent-platform/cloud-agents/overview/) * **Contribute to team knowledge** - Add useful Workflows, Prompts, and Rules to your team’s Warp Drive to compound productivity gains across your team * **Stay updated** - Check the [Warp changelog](/changelog/) for new features ## Support and feedback [Section titled “Support and feedback”](#support-and-feedback) * **Send feedback** - Use `Cmd+Shift+F` (macOS) or `Ctrl+Shift+F` (Linux/Windows) or go to **Help** > **Send Feedback** * **Request features** - Share ideas by [sending us feedback](/support-and-community/troubleshooting-and-support/sending-us-feedback/) * **Get help** - Enterprise teams have access to priority support via dedicated Slack/Teams channels * **Join the community** - Connect with other Warp users in our [Slack community](https://go.warp.dev/join-preview) # Getting started with Warp Enterprise > Set up Warp Enterprise for your organization with SSO configuration, team management, and admin controls. This guide walks your IT or platform admin through initial Warp setup for your organization: configuring SSO, creating your team, inviting users, and setting Admin Panel policies. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) Before you begin: * You have an active Warp Enterprise subscription * You have admin access to your organization’s identity provider (Okta, Microsoft Entra ID, Google Workspace, etc.) * You’ve identified which team members should have admin privileges in Warp ## Step 1: Configure Single Sign-On (SSO) [Section titled “Step 1: Configure Single Sign-On (SSO)”](#step-1-configure-single-sign-on-sso) Warp uses SSO to authenticate users and control access to your organization’s Warp team. Warp supports Okta, Microsoft Entra ID, Google Workspace, OneLogin, and any SAML 2.0 or OIDC compatible provider through [WorkOS](https://workos.com). SSO setup is coordinated with Warp’s team — contact your account team or [enterprise support](https://warp.dev/contact-sales) to get started. For the full setup process and supported providers, see [Single Sign-On (SSO)](/enterprise/security-and-compliance/sso/). **Before rolling out to your team**, test SSO login in an incognito window to confirm it works. See [Testing SSO](/enterprise/security-and-compliance/sso/#testing-sso) for steps. Note After enabling SSO, existing users who signed up with email or OAuth will need to [link their accounts to SSO](https://app.warp.dev/link_sso) before they can continue using Warp with your organization. See [troubleshooting SSO account linking](/support-and-community/troubleshooting-and-support/troubleshooting-login-issues/#i-logged-in-with-another-method-before-and-now-cant-use-sso) for details. ## Step 2: Create and configure your team [Section titled “Step 2: Create and configure your team”](#step-2-create-and-configure-your-team) ### Creating your team [Section titled “Creating your team”](#creating-your-team) During Enterprise onboarding, Warp’s team will work with you to set up your team. This typically happens in one of two ways: * **Warp provisions your team** - In most cases, Warp creates the team on your behalf and adds your admin so you can begin configuration right away. * **You create or bring your own team** - If you already have a Warp team, or prefer to create one yourself, Warp’s team will apply the Enterprise plan to it during onboarding. In either case, the Enterprise plan must be applied by Warp internally — this cannot be self-served. Your account team will coordinate this with you. To get started, contact your account manager. ### Team settings [Section titled “Team settings”](#team-settings) Some team settings are configured in different places: * **Team name** - Configured in **Settings** > **Teams** in the Warp app. Help users identify the right team to join. * **Domain restrictions** - Limit team invites to specific email domains (e.g., `@yourcompany.com`) * **Auto-join** - Automatically adds users to your team when they sign in via SSO from your configured domain. The domain must be configured by the Warp team during onboarding — contact your account team to set up or update your team domain. * **SSO** - Configured through WorkOS, not the Admin Panel. See [Step 1](#step-1-configure-single-sign-on-sso). ## Step 3: Invite and manage users [Section titled “Step 3: Invite and manage users”](#step-3-invite-and-manage-users) ### Inviting users [Section titled “Inviting users”](#inviting-users) There are several ways to add users to your Warp team: **Option 1: Invite by email** 1. Navigate to **Settings** > **Teams**. 2. Enter email addresses in the **Invite by Email** field (comma-separated). 3. Click **Invite**. **Option 2: Share invite link** 1. Navigate to **Settings** > **Teams**. 2. Copy the team invite link. 3. Share the link via email, Slack, or your preferred communication channel. **Option 3: Domain auto-join** Note Domain configuration is set up by the Warp team during onboarding. Contact your Warp account team to configure or update your team domain. 1. Once your team domain is configured, users who sign in via SSO from your domain are automatically added to your Warp team. ### User roles and permissions [Section titled “User roles and permissions”](#user-roles-and-permissions) Warp has three user roles: * **Team Owner** - Has full access to the Admin Panel and can manage team settings, invite users, assign roles, and transfer ownership of the team. There can only be one Owner. * **Team Admin** - Same permissions as the Owner, except they can’t transfer ownership of the team. * **Member** - Standard access to Warp features and team resources ### Managing admins [Section titled “Managing admins”](#managing-admins) To promote or demote team admins: 1. Navigate to **Settings** > **Teams** > **Team Members**. 2. Find the user you want to modify. 3. Click the **…** (three dots) next to their name. 4. Select **Promote to admin** or **Demote admin**. Note Teams can have multiple admins. We recommend at least one admin in addition to the Team Owner to prevent access issues if one is unavailable. ## Step 4: Configure the Admin Panel [Section titled “Step 4: Configure the Admin Panel”](#step-4-configure-the-admin-panel) The Admin Panel gives you centralized control over Warp features, permissions, and usage across your team. ### Accessing the Admin Panel [Section titled “Accessing the Admin Panel”](#accessing-the-admin-panel) 1. In Warp, open **Settings**. 2. Navigate to the **Billing and usage** section. 3. Click **Open Admin Panel**. Alternatively, visit [app.warp.dev/admin](https://app.warp.dev/admin) directly. ### Key Admin Panel sections [Section titled “Key Admin Panel sections”](#key-admin-panel-sections) * **Billing** - View your plan type and AI usage limit information * **Teams** - Manage team members, roles, and invites — the same controls available in **Settings** > **Teams** in the Warp app * **AI** - Configure general and AI autonomy settings for your team * **Models** - Configure which models are available to your team and AWS Bedrock * **Code** - Enable Codebase Context for your team * **Platform** - Configure Oz cloud agent settings * **Privacy** - Configure user-generated content data collection, cloud conversation storage, and enterprise secret redaction * **Sharing** - Configure direct link sharing and “anyone with link” sharing permissions ### How settings enforcement works [Section titled “How settings enforcement works”](#how-settings-enforcement-works) Settings configured in the Admin Panel are enforced at the team level: * **Enforced settings** - Cannot be overridden by individual users (e.g., BYOLLM routing policies) * **Respect User Setting** - Defers to each user’s own preference, letting individual team members configure that setting themselves ## Step 5: Set up team resources [Section titled “Step 5: Set up team resources”](#step-5-set-up-team-resources) ### Enable Codebase Context [Section titled “Enable Codebase Context”](#enable-codebase-context) Codebase Context indexes your Git repositories to help agents understand your code across large, multi-repo systems: 1. Navigate to **Admin Panel** > **Code**. 2. Toggle **Codebase Indexing** to **Enabled**. Warp prompts team members to index repositories when they navigate to a Git-tracked directory. ### Create shared Warp Drive resources [Section titled “Create shared Warp Drive resources”](#create-shared-warp-drive-resources) Populate your team’s Warp Drive with shared resources to scale best practices and compound productivity gains: * **Workflows** - Parameterized commands for common tasks (deployments, environment setup) * **Notebooks** - Interactive runbooks for onboarding and operational procedures * **Prompts** - Saved agent prompts for recurring tasks (code review, test generation) * **Rules** - Coding standards and conventions that agents should follow * **Environment Variables** - Shared configuration for development environments See [Warp Drive documentation](/knowledge-and-collaboration/warp-drive/) for details on creating team resources. ### Configure MCP integrations [Section titled “Configure MCP integrations”](#configure-mcp-integrations) Connect Warp to your team’s tools for enhanced agent context. Navigate to **Settings** > **Agents** > **MCP servers** to get started. Some integrations (like Linear, GitHub, and Sentry) are available to enable with a single click, while you can also add any custom MCP server configuration your team needs. Once configured, click the share icon on a server to make it available to your team. See the [MCP documentation](/agent-platform/capabilities/mcp/) for full configuration details. ## Next steps [Section titled “Next steps”](#next-steps) Once your team is set up: * **For developers** - Share the [Getting started for developers](/enterprise/getting-started/getting-started-developers/) guide with your team * **Agent Profiles** - Configure default [Agent Profiles](/agent-platform/capabilities/agent-profiles-permissions/) for different types of work to give teams appropriate autonomy and control * **BYOLLM** - Set up [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) to route inference through your cloud infrastructure for data locality and cost control * **Monitor usage** - Review usage analytics in the Admin Panel to track adoption and measure engineering productivity gains * **Self-hosting** - Run Oz agents on your own infrastructure to control where agents run and keep repository clones on your own machines. See [Self-Hosting](/agent-platform/cloud-agents/self-hosting/) for setup instructions ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### SSO login issues [Section titled “SSO login issues”](#sso-login-issues) For common SSO problems (login failures, account linking, provider portal errors), see [SSO troubleshooting](/enterprise/security-and-compliance/sso/#troubleshooting). ### Team invite links not working [Section titled “Team invite links not working”](#team-invite-links-not-working) **Common causes:** * Invite link expired or was revoked * User’s email domain doesn’t match configured restrictions **Solution:** 1. Generate a new invite link. 2. Verify domain restrictions match user’s email. ## Support and resources [Section titled “Support and resources”](#support-and-resources) * [Admin Panel documentation](/enterprise/team-management/admin-panel/) * [Troubleshooting login issues](/support-and-community/troubleshooting-and-support/troubleshooting-login-issues/) * [Contact enterprise support](https://warp.dev/contact-sales) - Priority support via dedicated Slack/Teams channel # Enterprise quickstart > Get up and running with Warp Enterprise in under 10 minutes. Log in, set up your terminal, and run your first Oz agent. This quickstart walks you through the essentials: logging in via SSO, setting up Warp, and running your first Oz agent. You can complete this in under 10 minutes. ## Step 1: Log in via SSO [Section titled “Step 1: Log in via SSO”](#step-1-log-in-via-sso) 1. Go to [app.warp.dev/login](https://app.warp.dev/login). 2. Click **Continue with SSO**. 3. Enter your work email or your organization’s domain. 4. Complete authentication with your identity provider. Caution Do not launch Warp from your SSO provider’s app portal (e.g., Okta dashboard). Always log in through [app.warp.dev/login](https://app.warp.dev/login). If you have an existing Warp account from before your organization enabled SSO, [link it to SSO first](https://app.warp.dev/link_sso). ## Step 2: Download and set up Warp [Section titled “Step 2: Download and set up Warp”](#step-2-download-and-set-up-warp) 1. Visit [warp.dev/download](https://warp.dev/download) and select your platform (macOS, Linux, or Windows). 2. Install Warp: * **macOS** - Open the `.dmg` and drag Warp to Applications. * **Linux** - Install via `.deb`, `.rpm`, or the install script. * **Windows** - Run the `.exe` installer. 3. Launch Warp and log in with SSO (Step 1). 4. Verify you see your team name in **Settings** > **Teams**. ## Step 3: Configure and run your first Oz agent [Section titled “Step 3: Configure and run your first Oz agent”](#step-3-configure-and-run-your-first-oz-agent) When you use agents in Warp, you’re using **Oz agents**. Oz is Warp’s programmable agent for running and coordinating agents at scale, whether they run locally on your machine or in the cloud. ### Index your codebase [Section titled “Index your codebase”](#index-your-codebase) 1. Navigate to a Git repository in Warp. 2. Warp automatically detects the repo and begins indexing. 3. Optionally, run `/init` to manually trigger indexing or re-indexing after significant code changes. 4. Once indexed, Oz agents understand your code structure, patterns, and conventions. ### Run your first Oz agent locally [Section titled “Run your first Oz agent locally”](#run-your-first-oz-agent-locally) Start an Oz conversation right in the terminal. Try the following prompt: ```plaintext Explain the architecture of this project ``` Oz reads your codebase, understands its structure, and responds with a context-aware explanation. ### Try more prompts [Section titled “Try more prompts”](#try-more-prompts) * **Write code** - “Add input validation to the signup form” * **Debug** - “Why is this test failing?” (paste the error output) * **Explore** - “What patterns does this repo use for error handling?” * **Plan** - Use `/plan` to have Oz create a structured task plan for complex features ## Step 4: Run an Oz cloud agent [Section titled “Step 4: Run an Oz cloud agent”](#step-4-run-an-oz-cloud-agent) Oz cloud agents run in the cloud for background work, unlimited parallelization, and long-running tasks. ### Create an environment [Section titled “Create an environment”](#create-an-environment) Environments define the execution context for cloud agents (repo access, dependencies, secrets, compute). You can create an environment in several ways: **Option 1: Slash command in Warp** From the Warp app terminal input, run the command: ```plaintext /create-environment ``` This launches an interactive flow that guides you through environment setup. **Option 2: Oz web app** Go to [app.warp.dev/environments](https://app.warp.dev/environments) and click **Create Environment**. ### Run a cloud agent [Section titled “Run a cloud agent”](#run-a-cloud-agent) Once your environment is ready, use the following command to launch a cloud agent (use the environment ID from above): ```bash oz agent run-cloud --env my-env --prompt "Review the open PRs in this repo" ``` Monitor and steer Oz cloud agents from the Oz dashboard or directly in Warp. ## Next steps [Section titled “Next steps”](#next-steps) * **Set up key features** - Follow the full [Getting started for developers](/enterprise/getting-started/getting-started-developers/) guide to configure Codebase Context, Warp Drive, MCP integrations, and Agent Profiles. * **Explore Oz cloud agents** - Learn about [Oz cloud agents](/agent-platform/cloud-agents/overview/) for background automation and parallel workflows. * **Learn more** - Visit [Warp Guides](/guides/) for video tutorials and end-to-end workflows. # Security overview > Understand Warp's security architecture, data handling practices, and compliance certifications to ensure your organization's requirements are met. Warp builds security and compliance into its core, keeping **developers in control** while enabling powerful agent workflows. This overview explains how Warp handles your data, what security controls are available, and how Warp meets enterprise security standards. ## Transparency and control [Section titled “Transparency and control”](#transparency-and-control) Warp’s security philosophy centers on **transparency and developer control**: * **Complete visibility** - View exactly what telemetry is collected through our [exhaustive telemetry table](/support-and-community/privacy-and-security/privacy/#exhaustive-telemetry-table) * **Real-time monitoring** - Use Warp’s [Network Log](/support-and-community/privacy-and-security/network-log/) to monitor all network requests in real time * **Opt-out controls** - Disable telemetry and crash reporting at any time while retaining full functionality * **Team-level enforcement** - Admins can configure telemetry and data collection policies for the entire organization * **Open source client** - Warp’s client code is published under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE) at [`warpdotdev/warp`](https://github.com/warpdotdev/warp), so security teams can audit the codebase directly. See [Contributing to Warp](/support-and-community/community/contributing/) for the source repository and the security reporting process. ## What telemetry does Warp collect and why? [Section titled “What telemetry does Warp collect and why?”](#what-telemetry-does-warp-collect-and-why) ### Zero Data Retention (ZDR) [Section titled “Zero Data Retention (ZDR)”](#zero-data-retention-zdr) Warp has **Zero Data Retention (ZDR)** agreements with its contracted LLM providers (Anthropic, OpenAI, Google), meaning they do not store or train on your data. ZDR applies across all Warp plans. How data collection works by plan: * **Free tier** - Individual users can disable data collection in **Settings** > **Privacy**. * **Paid teams** - Team admins can enforce data collection settings for the entire team. Data collection is enabled by default. * **Business and Enterprise** - Team admins can enforce data collection settings for the entire team. Data collection is **disabled by default**. Note Some product features — including cloud conversations and Oz runs — require storing conversation data to function. This data is stored to power the product experience and is separate from analytics or telemetry data collection. Enterprise subscriptions also include: * **Team-level enforcement** - Admins configure data collection and telemetry policies for the entire organization through the Admin Panel * **Secret redaction** - All AI interactions automatically apply [secret redaction](/support-and-community/privacy-and-security/secret-redaction/) to prevent sensitive data exposure ### Telemetry categories [Section titled “Telemetry categories”](#telemetry-categories) When telemetry is enabled, Warp collects: 1. **Product usage analytics** - High-level metrics on feature adoption and usage patterns (e.g., “Agent Mode was opened,” “workflow was executed”). 2. **Performance and stability** - Crash reports, error tracking, and performance metrics to identify and fix issues. When data collection is disabled, Warp does not collect: * Personally identifiable information beyond user IDs and email addresses * Network traffic or external API calls ### Disabling telemetry [Section titled “Disabling telemetry”](#disabling-telemetry) Users can opt out of telemetry individually: 1. Navigate to **Settings** > **Privacy**. 2. Toggle off **Help improve Warp** and/or **Send crash reports**. With telemetry disabled, Warp stops collecting usage and interaction data for analytics purposes. Team admins can enforce telemetry settings organization-wide through the Admin Panel. On Business and Enterprise plans, data collection is disabled by default. ## Data handling and privacy [Section titled “Data handling and privacy”](#data-handling-and-privacy) ### Where your data lives [Section titled “Where your data lives”](#where-your-data-lives) * **Code and files** - Stay on your machine unless you explicitly use features that transmit them (e.g., Codebase Context indexing, session sharing, Warp Drive team resources) * **Codebase Context** - During indexing, code is sent to Warp’s servers to generate embeddings; the raw code is not stored, only the resulting embeddings are retained * **Agent requests** - Warp sends requests to contracted LLM providers (Anthropic, OpenAI, Google) with Zero Data Retention agreements for Enterprise teams * **BYOLLM** - Requests are proxied through Warp’s servers to your cloud infrastructure, where inference runs. Warp does not store the content of these requests. ### Encryption [Section titled “Encryption”](#encryption) * **In transit** - All data transmitted to Warp servers uses TLS 1.2 or higher * **At rest** - Warp encrypts all user data at rest using AES-256 ### Secret redaction [Section titled “Secret redaction”](#secret-redaction) Warp automatically detects and redacts sensitive information before sending any data to LLM providers, keeping developers in control of what gets shared: * API keys and tokens * Passwords and secrets * SSH keys and certificates * Custom secret patterns (configurable via Admin Panel) See [Secret Redaction documentation](/support-and-community/privacy-and-security/secret-redaction/) for details. ### Data retention [Section titled “Data retention”](#data-retention) * **ZDR** - Warp’s contracted LLM providers do not retain or train on your data * **Telemetry data** - When collected, Warp retains telemetry data indefinitely for analytics and debugging * **User accounts** - Data deletion requests are processed securely within 30 days at no cost, following verified authentication and compliance with legal and contractual obligations ## Compliance and certifications [Section titled “Compliance and certifications”](#compliance-and-certifications) ### SOC 2 Type II [Section titled “SOC 2 Type II”](#soc-2-type-ii) Warp is SOC 2 Type II certified, demonstrating compliance with industry-standard security controls for: * **Security** - Infrastructure protection, access controls, and monitoring * **Availability** - System uptime and disaster recovery * **Confidentiality** - Data protection and privacy controls * **Processing integrity** - Accurate, complete, and authorized processing SOC 2 reports are available to Enterprise customers upon request. ## Infrastructure security [Section titled “Infrastructure security”](#infrastructure-security) ### Warp-hosted infrastructure [Section titled “Warp-hosted infrastructure”](#warp-hosted-infrastructure) When using Warp’s hosted infrastructure: * **Cloud provider** - Hosted on GCP with SOC 2 and ISO 27001 certified datacenters * **Network isolation** - Workloads run in isolated VPCs with strict network policies Warp’s operational security practices — including access controls, monitoring, and vulnerability management — are validated through SOC 2 Type II certification. See [Compliance and certifications](#compliance-and-certifications) for details. ### Self-hosted deployments [Section titled “Self-hosted deployments”](#self-hosted-deployments) Enterprise teams can self-host Oz cloud agent execution to control where agents run and keep repositories on their own infrastructure. Self-hosted deployments use a split architecture: * **Execution plane (customer-hosted)** - Repository clones, build artifacts, runtime secrets, and container filesystem state stay on your infrastructure * **Control plane (Warp-hosted)** - Session transcripts (which include code context from agent interactions), orchestration metadata, and LLM inference route through Warp’s servers under Zero Data Retention (ZDR) agreements. Warp does not persistently store your source code or use it for model training Two deployment modes are available: * **Unmanaged** - Use `oz agent run` to run agents in your existing orchestrator or CI environment. Supports Linux, macOS, and Windows with no Docker dependency. * **Managed** - Run the `oz-agent-worker` daemon to let the Oz platform orchestrate agents in isolated Docker containers on your infrastructure. Agent runs are fully tracked and steerable in both modes. No inbound network access is required. **Network egress requirements** Self-hosted agents require outbound access to Warp’s backend services and, for the managed architecture, Docker Hub and GitHub. ## Access controls and authentication [Section titled “Access controls and authentication”](#access-controls-and-authentication) ### Single Sign-On (SSO) [Section titled “Single Sign-On (SSO)”](#single-sign-on-sso) Warp supports SSO via Okta, Microsoft Entra ID, Google Workspace, OneLogin, and any SAML 2.0 or OpenID Connect (OIDC) compatible provider. Admins can require SSO for all team members and enforce MFA through your identity provider. See [Single Sign-On (SSO)](/enterprise/security-and-compliance/sso/) for setup instructions, SCIM provisioning, account linking, and troubleshooting. ### Team permissions [Section titled “Team permissions”](#team-permissions) Warp uses role-based access control with three roles — Team Owner, Team Admin, and Member — to manage team access and Admin Panel privileges. See [User roles and permissions](/enterprise/getting-started/getting-started-enterprise/#user-roles-and-permissions) for details. Resource sharing in Warp Drive has granular controls for who can view, edit, and share. ### Admin Panel governance [Section titled “Admin Panel governance”](#admin-panel-governance) The Admin Panel gives security and IT teams centralized control over AI behavior, data handling, and sharing policies. Settings can be **enforced** (overriding individual user preferences organization-wide) or set to **respect user setting** (deferring to individual preferences). Security-relevant controls include: * **Privacy** - Configure user-generated content (UGC) data collection, cloud conversation storage, and enterprise secret redaction * **Sharing** - Restrict or permit direct link sharing and “anyone with link” sharing permissions * **AI** - Configure AI autonomy settings and general agent behavior for the team * **Models** - Control which LLM models are available to team members, including AWS Bedrock * **Platform** - Configure Oz cloud agent access and settings ## Security features for developers [Section titled “Security features for developers”](#security-features-for-developers) ### Bring Your Own LLM (BYOLLM) [Section titled “Bring Your Own LLM (BYOLLM)”](#bring-your-own-llm-byollm) Route agent inference through your own cloud infrastructure for complete control: * **Data locality** - Cloud agent inference runs in your AWS account * **Cloud-native IAM** - Authenticate using your user’s existing identity and access management process * **No key storage** - Warp never stores your cloud credentials or API keys * **Billing control** - Inference costs billed directly to your cloud account See [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) for configuration details. ### Docker Sandboxes [Section titled “Docker Sandboxes”](#docker-sandboxes) Isolate agent execution in containerized environments: * **Process isolation** - Agents run in separate Docker containers, isolated from your host system * **Resource limits** - Configure CPU, memory, and disk quotas per sandbox * **Network controls** - Restrict outbound network access from sandboxes * **Ephemeral environments** - Sandboxes are destroyed after use, leaving no trace ### Agent permissions [Section titled “Agent permissions”](#agent-permissions) Configure what agents can access and execute: * **Tool restrictions** - Enable/disable terminal use, code editing, web search, and file system access * **Repository scoping** - Limit agents to specific repositories or directories * **Execution approvals** - Require manual approval for sensitive commands * **Visibility** - When cloud conversation storage is enabled, agent actions are logged with full context for review ## Incident response and support [Section titled “Incident response and support”](#incident-response-and-support) ### Security issue reporting [Section titled “Security issue reporting”](#security-issue-reporting) If you discover a security vulnerability in Warp: 1. Email . 2. Include detailed steps to reproduce. 3. Do not publicly disclose until Warp has addressed the issue. Warp follows responsible disclosure practices and works with reporters to coordinate disclosure timelines. ### Enterprise support [Section titled “Enterprise support”](#enterprise-support) Enterprise customers receive priority security support: * **Dedicated channels** - Private Slack/Teams channels for security questions * **Security advisories** - Proactive notifications of security updates * **Incident assistance** - Support during security incidents or breach investigations * **Compliance assistance** - Help with compliance questionnaires and audits ## Additional resources [Section titled “Additional resources”](#additional-resources) * **Privacy policy** - [warp.dev/legal/privacy-policy](https://www.warp.dev/legal/privacy-policy) * **Trust center** - [trust.warp.dev](https://trust.warp.dev) — security documentation and compliance reports. See also [Trust Center](/enterprise/security-and-compliance/trust-center/) for details on requesting SOC 2 reports, subprocessors, and vendor security assessments. * **Subprocessors** - [warp.dev/legal/subprocessors](https://www.warp.dev/legal/subprocessors) * **Privacy documentation** - [Privacy guide](/support-and-community/privacy-and-security/privacy/) with complete telemetry table * **Contact** - for privacy questions, for security issues Note For vendor security assessments, compliance questionnaires, or access to SOC 2 reports, contact your account manager or email . # Single Sign-On (SSO) > Configure Single Sign-On (SSO) to authenticate and manage access to Warp across your organization. Warp uses SSO to authenticate users and control access to your organization’s Warp team. This guide covers configuring SSO, testing your setup, and managing user access through your identity provider. ## Supported identity providers [Section titled “Supported identity providers”](#supported-identity-providers) Warp supports the following identity providers: * **Okta** * **Microsoft Entra ID** * **Google Workspace** * **OneLogin** * **Any SAML 2.0 or OpenID Connect (OIDC) compatible provider** ## SSO enforcement and session management [Section titled “SSO enforcement and session management”](#sso-enforcement-and-session-management) * **SSO enforcement** - Admins can require SSO for all team members, preventing login via other methods. * **Multi-factor authentication** - MFA is enforced through your identity provider’s policies. Warp respects MFA requirements configured in Okta, Microsoft Entra ID, Google Workspace, etc. * **Session management** - Configurable session timeouts and re-authentication policies through your identity provider. ## Setting up SSO [Section titled “Setting up SSO”](#setting-up-sso) SSO is configured through [WorkOS](https://workos.com) in coordination with Warp’s team: 1. Contact your Warp account team or [enterprise support](https://warp.dev/contact-sales) to initiate SSO setup. 2. Warp creates an organization for your team in WorkOS and sets your team domain. 3. Your IT admin receives an email invite from WorkOS. 4. Follow the WorkOS setup wizard to connect your identity provider (configure SAML attributes or OAuth scopes, provide your SSO URL and certificate). 5. Once complete, team members can log in via **Continue with SSO** at [app.warp.dev/login](https://app.warp.dev/login). Note After enabling SSO, existing users who signed up with email or OAuth need to link their accounts. See [Linking existing accounts](#linking-existing-accounts) below. ## Testing SSO [Section titled “Testing SSO”](#testing-sso) Before rolling out to your team: 1. Open an incognito/private browser window. 2. Navigate to [app.warp.dev/login](https://app.warp.dev/login). 3. Click **Continue with SSO**. 4. Enter your organization’s domain. 5. Verify you’re redirected to your identity provider and can log in successfully. Caution Warp cannot be launched directly from your SSO provider’s app portal (e.g., Okta dashboard). Users must log in through [app.warp.dev/login](https://app.warp.dev/login) and select **Continue with SSO**. ## SCIM provisioning [Section titled “SCIM provisioning”](#scim-provisioning) Warp supports SCIM for user lifecycle management. Provisioning works through Just-In-Time (JIT) provisioning combined with SSO and domain capture: * **User provisioning** - Add users to the Warp application in your identity provider. Once they sign in via SSO, they are automatically added to your Warp team. * **Domain auto-join** - Users who sign in with SSO from your configured domain are automatically joined to your team. See [Domain auto-join](#domain-auto-join) for setup details. * **User deprovisioning** - Removing a user from the Warp application in your identity provider prevents future SSO logins. Existing sessions are not immediately revoked. Note Warp does not currently support SCIM group sync. User provisioning is handled via JIT — users appear in your Warp team after their first SSO login, not at the time they are assigned in your identity provider. ## Linking existing accounts [Section titled “Linking existing accounts”](#linking-existing-accounts) Users who created a Warp account before your organization enabled SSO need to link their accounts: 1. Log in to Warp with the original method (email, Google, or GitHub). 2. Navigate to [app.warp.dev/link\_sso](https://app.warp.dev/link_sso). 3. Complete the linking process. 4. Log out and log back in with **Continue with SSO**. ## Domain auto-join [Section titled “Domain auto-join”](#domain-auto-join) Domain auto-join allows users from your organization to automatically join your Warp team after SSO authentication. Note Domain configuration is set up by the Warp team during onboarding. Contact your Warp account team to configure or update your team domain. Once your team domain is configured, users who sign in via SSO from your domain are automatically added to your Warp team. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### Users can’t log in with SSO [Section titled “Users can’t log in with SSO”](#users-cant-log-in-with-sso) **Common causes:** * SSO not properly configured in your identity provider. * User trying to launch Warp directly from SSO provider (not supported). * User has an existing Warp account that needs to be [linked to SSO](https://app.warp.dev/link_sso). **Solution:** 1. Verify SSO configuration in your identity provider. 2. Have users log in through [app.warp.dev/login](https://app.warp.dev/login) and select **Continue with SSO**. 3. For existing accounts, follow the [SSO linking process](https://app.warp.dev/link_sso). ### Warp won’t open from SSO provider portal [Section titled “Warp won’t open from SSO provider portal”](#warp-wont-open-from-sso-provider-portal) **Problem:** Clicking Warp in Okta/Microsoft Entra ID portal shows an error. **Solution:** Log in directly through [app.warp.dev/login](https://app.warp.dev/login) and select **Continue with SSO** instead. ## Related resources [Section titled “Related resources”](#related-resources) * [Security overview](/enterprise/security-and-compliance/security-overview/) - Enterprise security posture and compliance * [Getting started for admins](/enterprise/getting-started/getting-started-enterprise/) - Full admin onboarding guide * [Troubleshooting login issues](/support-and-community/troubleshooting-and-support/troubleshooting-login-issues/) # Warp Trust Center > Access Warp's security documentation, compliance certifications, and third-party assessment resources to complete your vendor security review. Warp’s [Trust Center](https://trust.warp.dev) is the central hub for security documentation, compliance certifications, and third-party assessments. It provides the information security teams, procurement, and compliance officers need to evaluate Warp as a vendor and complete security reviews. ## Compliance certifications [Section titled “Compliance certifications”](#compliance-certifications) ### SOC 2 Type II [Section titled “SOC 2 Type II”](#soc-2-type-ii) Warp is **SOC 2 Type II certified**, demonstrating compliance with industry-standard security controls across the following trust service criteria: * **Security** - Infrastructure protection, access controls, and monitoring * **Availability** - System uptime and disaster recovery * **Confidentiality** - Data protection and privacy controls * **Processing integrity** - Accurate, complete, and authorized processing **Requesting SOC 2 reports:** Enterprise customers can request SOC 2 reports directly through the [Trust Center portal](https://trust.warp.dev), through their account manager, or by emailing . ## Subprocessors [Section titled “Subprocessors”](#subprocessors) Warp publishes a list of subprocessors — third-party service providers that process data on Warp’s behalf. This includes infrastructure providers, LLM providers, and other services that support Warp’s operations. View the current list of subprocessors at [warp.dev/legal/subprocessors](https://www.warp.dev/legal/subprocessors). Note Warp maintains **Zero Data Retention (ZDR)** agreements with its contracted LLM providers (Anthropic, OpenAI, Google), meaning they do not store or train on your data. ## Security documentation [Section titled “Security documentation”](#security-documentation) The following resources provide detailed information about Warp’s security practices: * **[Trust Center portal](https://trust.warp.dev)** - External portal with downloadable compliance reports and real-time security status * **[Security overview](/enterprise/security-and-compliance/security-overview/)** - Warp’s security architecture, data handling, and compliance certifications * **[Privacy policy](https://www.warp.dev/legal/privacy-policy)** - How Warp collects, uses, and protects personal data * **[Subprocessors](https://www.warp.dev/legal/subprocessors)** - Third-party service providers that process data on Warp’s behalf ## Requesting security information [Section titled “Requesting security information”](#requesting-security-information) If you’re conducting a vendor security assessment or completing a compliance questionnaire, Warp can provide: * **SOC 2 Type II reports** - Available upon request for Enterprise customers * **Compliance questionnaire assistance** - Warp’s security team can help complete vendor security questionnaires * **[Architecture and deployment](/enterprise/enterprise-features/architecture-and-deployment/)** - Details about Warp’s infrastructure, deployment models, and data flows To request any of these materials, contact your account manager or email . ## Penetration testing and vulnerability management [Section titled “Penetration testing and vulnerability management”](#penetration-testing-and-vulnerability-management) Warp conducts regular security assessments as part of its SOC 2 program. The details of Warp’s vulnerability management and penetration testing practices are validated through its SOC 2 Type II certification. ### Responsible disclosure [Section titled “Responsible disclosure”](#responsible-disclosure) If you discover a security vulnerability in Warp, please report it responsibly: 1. Email with detailed steps to reproduce the issue. 2. Allow Warp time to investigate and address the vulnerability before any public disclosure. Warp works with reporters to coordinate disclosure timelines. # Enterprise billing > Learn about billing for Warp Enterprise, including credits, cloud agent costs, and billing management. This page covers general information about credits, cloud agent costs, and BYOLLM billing for enterprise teams. If you have specific questions about custom pricing, credit allocation, or contract terms, contact your Warp account manager. ## Credits [Section titled “Credits”](#credits) Warp uses a credit-based billing model. Any interaction with Oz agents consumes credits based on the complexity of the task, the model used, and the amount of context processed. ### How credits work [Section titled “How credits work”](#how-credits-work) * Each agent interaction consumes **at least one credit**, though complex interactions may use multiple credits. * Credit usage is influenced by the LLM model used, the number of tool calls, task complexity, amount of context, and prompt caching behavior. * Credit usage is **non-deterministic**. Two similar prompts may consume different numbers of credits. For details on how credits are calculated, see [Credits](/support-and-community/plans-and-billing/credits/). ### Credit allocation [Section titled “Credit allocation”](#credit-allocation) Enterprise plans include a custom team-wide credit pool as part of your contract. Credits are primarily shared across the entire team rather than allocated per seat. Individual credit grants may also occur (e.g., support refunds), but the core allocation is team-wide. Note Credit allocations vary by contract. Contact your account manager for details on your team’s specific allocation. ## Cloud agent billing [Section titled “Cloud agent billing”](#cloud-agent-billing) Oz cloud agents consume credits that include a small hosting fee in addition to AI usage costs. ### How credits are consumed [Section titled “How credits are consumed”](#how-credits-are-consumed) On Enterprise plans, both local and cloud agent usage draw from the same team credit pool. There are no separate “cloud agent credits” or “local credits” — all agent usage consumes from your available credit sources. For team API key runs (e.g., CI/CD pipelines, scheduled tasks), credits also draw from the team’s shared pool since these runs are not tied to any individual user. For more details, see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/). ## BYOLLM billing [Section titled “BYOLLM billing”](#byollm-billing) When using [Bring Your Own LLM (BYOLLM)](/enterprise/enterprise-features/bring-your-own-llm/), Warp routes requests through your cloud infrastructure (AWS Bedrock, Google Vertex, or Azure Foundry). BYOLLM requests **consume credits at a reduced rate** which is approximately 80% slower than standard usage. Inference costs are also billed directly to your cloud account. If a BYOLLM request fails and Warp falls back to a direct API model, that fallback request consumes Warp credits at the standard rate. ## Managing billing [Section titled “Managing billing”](#managing-billing) Your Warp account manager handles all billing for your Enterprise contract. Contact your account manager or dedicated Slack/Teams channel for: * Invoices and payment changes * Contract modifications * Credit allocation adjustments For urgent billing issues, email . ### Spending controls [Section titled “Spending controls”](#spending-controls) Administrators can configure monthly spending limits and receive alerts to prevent unexpected charges. Configure these controls in the [Admin Panel](https://app.warp.dev/admin/) under the **Billing** tab. #### Monthly spending limits [Section titled “Monthly spending limits”](#monthly-spending-limits) Enterprise administrators can set monthly spending limits across the following four categories: * **Cloud spending limit** - Cap monthly spend on Oz cloud agent usage. * **Local spending limit** - Cap monthly spend on local agent usage in the Warp app. * **Total spending limit** - Cap combined monthly spend across both cloud and local agents. * **Per-user spending limit** - Cap monthly spend for any individual user. Set a default that applies to all users, or configure limits on a per-user basis for predictable individual spend. Spending is tracked across all payment types (Add-on Credits, pay-as-you-go usage) so limits apply consistently regardless of how usage is funded. #### Monthly spend alerts [Section titled “Monthly spend alerts”](#monthly-spend-alerts) Warp sends alerts to administrators as team usage approaches each configured spending limit, so you can adjust caps, purchase more credits, or communicate with your team before agent usage is blocked at the cap. #### Credit pool depletion alerts [Section titled “Credit pool depletion alerts”](#credit-pool-depletion-alerts) For enterprises with credit pools, administrators receive alerts as the team credit pool approaches full consumption. This gives you time to top up your credits or change your reload configuration before agent usage is interrupted for the entire team. ## Related resources [Section titled “Related resources”](#related-resources) * [Credits](/support-and-community/plans-and-billing/credits/) - How credits are calculated and consumed * [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) - Purchase additional credits and configure auto-reload * [Pricing FAQs](/support-and-community/plans-and-billing/pricing-faqs/) - Common billing questions * [Bring Your Own LLM](/enterprise/enterprise-features/bring-your-own-llm/) - BYOLLM billing and configuration * [Admin Panel](/enterprise/team-management/admin-panel/) - Configure spending limits and billing settings # Feedback and feature requests > Report bugs, request features, and get support as a Warp Enterprise customer. Warp Enterprise customers have access to dedicated support channels for reporting issues, requesting features, and getting help. This page explains how to reach the right team and provide the information needed to resolve issues quickly. ## Enterprise support channels [Section titled “Enterprise support channels”](#enterprise-support-channels) Enterprise customers receive **priority support** through dedicated channels: * **Dedicated Slack or Teams channel** - Your primary support channel. A private channel shared with Warp engineers for real-time assistance, bug reports, and feature discussions. * **Account manager** - Your direct contact for escalations, strategic feature requests, and enterprise-specific questions. Note For the fastest response, use your dedicated Slack or Teams channel. Warp engineers monitor these channels during business hours. ## Reporting bugs [Section titled “Reporting bugs”](#reporting-bugs) When reporting a bug, include the following to help Warp’s team investigate quickly: 1. **Description** - What happened and what you expected to happen. 2. **Steps to reproduce** - How to trigger the issue. 3. **Conversation ID** (for Agent issues) - Right-click on the Agent conversation block in question, select **Copy conversation ID**, and include it in your report. When an Agent conversation produces an error, an option to copy the conversation ID also appears inline. See [Gathering conversation ID](/support-and-community/troubleshooting-and-support/sending-us-feedback/#gathering-ai-conversation-id) for more details. 4. **Logs** (if relevant) - See [Gathering logs](#gathering-logs) below. 5. **Environment details** - OS, Warp version, and any relevant configuration. Note Most Enterprise teams have user-generated content (UGC) collection disabled, which limits the diagnostic information available from conversation IDs. Logs and detailed reproduction steps are especially important for Enterprise bug reports. ### Gathering logs [Section titled “Gathering logs”](#gathering-logs) Warp’s logs do not contain console input or output. Log file locations by platform: * **macOS** - `~/Library/Logs/warp.log*` * **Windows** - `%LOCALAPPDATA%\warp\Warp\data\logs\warp.log*` * **Linux** - `~/.local/state/warp-terminal/warp.log*` You can also access logs directly in the app: open the **Command Palette** (`⌘P` on macOS / `Ctrl+Shift+P` on Windows/Linux) and search for **View Warp Logs**. For detailed log gathering instructions, including how to zip logs and capture crash reports, see [Sending Feedback & Logs](/support-and-community/troubleshooting-and-support/sending-us-feedback/). ## Requesting features [Section titled “Requesting features”](#requesting-features) To request a new feature or enhancement: * **Enterprise customers** - Share feature requests through your dedicated Slack/Teams channel or with your account manager. This ensures your request is tracked and prioritized by the product team. * **Public feature requests** - Open an issue on [GitHub Issues](https://github.com/warpdotdev/warp/issues/new/choose) for visibility and community discussion. ## Specialized contacts [Section titled “Specialized contacts”](#specialized-contacts) For security or privacy inquiries, reach out to the appropriate team directly: * **Security issues** - * **Privacy questions** - For all other inquiries — including billing, technical issues, and feature requests — contact your account manager or dedicated Slack/Teams channel. ## Related resources [Section titled “Related resources”](#related-resources) * [Troubleshooting login](/enterprise/support-and-resources/troubleshooting-login/) - Resolve login and SSO issues # Troubleshooting login > Resolve common login and SSO issues for Warp Enterprise users and IT admins. This page covers common login issues for Warp Enterprise users, with a focus on SSO-related problems. For SSO setup and configuration, see [Single Sign-On (SSO)](/enterprise/security-and-compliance/sso/). ## SSO login issues [Section titled “SSO login issues”](#sso-login-issues) ### Can’t open Warp from your SSO provider [Section titled “Can’t open Warp from your SSO provider”](#cant-open-warp-from-your-sso-provider) When launching Warp directly from Okta or another SSO provider’s app dashboard, you may see an error like “Unable to process request due to missing initial state.” This is a known limitation with the authentication flow. **To fix it:** 1. Go to [app.warp.dev/login](https://app.warp.dev/login). 2. Choose **Continue with SSO**. 3. Log in with your normal SSO credentials. ### Previously logged in with another method [Section titled “Previously logged in with another method”](#previously-logged-in-with-another-method) If you originally created your Warp account with email, Google, or GitHub and now need to use SSO: 1. Go to [app.warp.dev/login](https://app.warp.dev/login). 2. Log in with your **original** method (email, Google, or GitHub). 3. Once logged in, visit [app.warp.dev/link\_sso](https://app.warp.dev/link_sso). 4. Click **Link SSO** to connect your existing account. You can now use **Continue with SSO** going forward. Note IT admins: if multiple team members need to link their accounts to SSO, share these steps during your SSO rollout. ## Common login issues [Section titled “Common login issues”](#common-login-issues) ### Can’t sign up or log in [Section titled “Can’t sign up or log in”](#cant-sign-up-or-log-in) If clicking the sign-up or login button opens a blank popup or nothing happens: * Your ISP or firewall may be blocking calls to `*.googleapis.com`. Try using a proxy or allowlisting this domain. * In some older Ruby development environments, `.dev` domains don’t resolve properly. If applicable, delete `/etc/resolver/dev` ([more info](https://superuser.com/questions/1374892/dev-domains-dont-resolve)). ### Browser-specific issues [Section titled “Browser-specific issues”](#browser-specific-issues) If you see authentication errors or blank popups across browsers: 1. **Disable ad blockers** for `app.warp.dev`. 2. **Clear cookies and cache**, or try an incognito / private browser window. 3. Try [app.warp.dev/login](https://app.warp.dev/login) again. **Safari-specific:** If you see “Unable to access localStorage” errors, go to **Safari Preferences** > **Privacy** and uncheck **Block all cookies**. Firebase Auth requires cookies to track login state. ## Proxy issues [Section titled “Proxy issues”](#proxy-issues) If you’re behind a proxy, QUIC traffic may not pass through correctly. Disabling QUIC in your browser forces a fallback to TCP, which typically resolves the issue: **Chrome / Chromium-based browsers (Edge, Opera, Arc):** 1. Navigate to `chrome://flags`. 2. Search for **Experimental QUIC protocol**. 3. Set it to **Disabled**. 4. Relaunch the browser. **Firefox:** 1. Navigate to `about:config`. 2. Accept the risk warning. 3. Search for `network.http.http3.enable`. 4. Double-click to set it to `false`. 5. Restart Firefox. **Safari:** There is no built-in option to disable QUIC in Safari. ## Flagged as fraudulent [Section titled “Flagged as fraudulent”](#flagged-as-fraudulent) If you see “This account has been flagged as fraudulent,” your account has triggered Warp’s fraud detection system. This can happen due to multiple account creation or use of throwaway emails (both against Warp’s [Terms of Service](https://www.warp.dev/terms-of-service)). ### False positives [Section titled “False positives”](#false-positives) Ad blockers or systems like Pi-hole can sometimes trigger false positives. Try temporarily disabling them and attempting login again. ### Requesting an appeal [Section titled “Requesting an appeal”](#requesting-an-appeal) If you’re still unable to authenticate, email with the email address of the affected account. Appeals may take 5–10 days. Enterprise customers can also contact their account manager or dedicated Slack/Teams channel for faster resolution. ## Browser doesn’t open when signing in [Section titled “Browser doesn’t open when signing in”](#browser-doesnt-open-when-signing-in) If the browser doesn’t open automatically from Warp when you click “Sign up” or “Sign in”: 1. Go to the [Signup](https://app.warp.dev/signup) or [Login](https://app.warp.dev/login) page in your browser. 2. Complete authentication in the browser. 3. On the logged-in page, if “Take me to Warp” doesn’t work, click the **here** link to copy the authentication token. 4. Paste the token into Warp. Note On Linux and Windows, the default paste shortcut is `CTRL+SHIFT+V`. ## Getting help [Section titled “Getting help”](#getting-help) * **Enterprise customers** - Contact your dedicated Slack/Teams channel or account manager. * **All other users** - Visit [warp.dev/contact](https://www.warp.dev/contact) for support. ## Related resources [Section titled “Related resources”](#related-resources) * [Single Sign-On (SSO)](/enterprise/security-and-compliance/sso/) - SSO setup and configuration * [Feedback and feature requests](/enterprise/support-and-resources/feedback-and-feature-requests/) - Report bugs and request features * [Troubleshooting login (full guide)](/support-and-community/troubleshooting-and-support/troubleshooting-login-issues/) - Complete troubleshooting reference # Admin Panel for teams > Centralized management for team administrators to configure Warp settings, control agent behavior, and enforce security policies across your organization. The Admin Panel provides administrators with centralized control over team settings in Warp. Configure agent behavior, security policies, codebase indexing, and collaboration features for your entire organization from a single interface. ## What is the Admin Panel? [Section titled “What is the Admin Panel?”](#what-is-the-admin-panel) The [Admin Panel](https://app.warp.dev/admin/) is your control center for managing Warp at scale. It allows IT admins, platform teams, and engineering managers to: * **Control agent behavior** - Set autonomy levels, command permissions, and safety guardrails organization-wide * **Enforce security policies** - Configure secret redaction, telemetry controls, and data handling * **Manage team resources** - Enable Codebase Context, configure BYOLLM, and control sharing permissions * **Monitor usage** - Track credit consumption and set spending limits * **Maintain compliance** - Apply consistent policies that meet your organization’s security requirements Note Warp restricts Admin Panel access to team administrators. Regular team members can view settings that affect them but cannot modify organization-wide policies. ## Accessing the Admin Panel [Section titled “Accessing the Admin Panel”](#accessing-the-admin-panel) ### For team admins [Section titled “For team admins”](#for-team-admins) Access the Admin Panel in two ways: **Option 1: Direct URL** 1. Navigate to [app.warp.dev/admin](https://app.warp.dev/admin/). 2. Log in with your SSO credentials. 3. The Admin Panel opens with all organization settings. **Option 2: From Warp Settings** 1. Open Warp and click your profile icon in the top right. 2. Click **Settings**. 3. Navigate to the **Admin Panel** tab (visible only to team admins). ### For team members [Section titled “For team members”](#for-team-members) Team members see organization-enforced settings in their personal Settings panel: * Settings controlled by admins appear grayed out * Indicated by message: “Your organization has configured this setting” * Users retain control over settings where admins have selected “Respect User Setting” ## How settings enforcement works [Section titled “How settings enforcement works”](#how-settings-enforcement-works) The Admin Panel uses a three-tier enforcement model that keeps administrators in control while allowing appropriate flexibility. ### Setting enforcement levels [Section titled “Setting enforcement levels”](#setting-enforcement-levels) **Organization enforced** * Setting applies to all team members regardless of individual preferences * Users cannot override these settings * Use for security-critical policies (e.g., secret redaction, command denylists) **Respect user setting** * Allows individual team members to control the setting themselves * Admins set a default, but users can customize * Use for preferences that don’t impact security or compliance (e.g., AI model selection) **Tier restricted** * Setting is locked based on billing plan * Cannot be changed until plan is upgraded * Indicated by message: “Configuring this setting is not available on your plan” ### Testing before enforcement [Section titled “Testing before enforcement”](#testing-before-enforcement) Note Changes made in the Admin Panel take effect immediately for all team members. Test settings in your own Warp environment before applying organization-wide enforcement. To safely roll out new policies: 1. Configure settings with “Respect User Setting” initially. 2. Test with a small group of users. 3. Gather feedback and adjust configuration. 4. Switch to “Organization enforced” once validated. ## Plan limitations [Section titled “Plan limitations”](#plan-limitations) The features available in the Admin Panel scale with your Warp plan: ### Free tier [Section titled “Free tier”](#free-tier) * Most settings are fixed and non-configurable * Limited Codebase Context (2 repositories) * No BYOLLM support * Basic sharing features ### Business plans [Section titled “Business plans”](#business-plans) * Most settings become configurable by administrators * Enhanced agent autonomy control * Advanced sharing and privacy features * Increased Codebase Context limits ### Enterprise plans [Section titled “Enterprise plans”](#enterprise-plans) * **Full admin control** - Configure all available settings * **Enterprise secret redaction** - Custom regex patterns for secrets * **BYOLLM** - Route inference through your cloud infrastructure * **Self-hosting cloud agent workers** - Deploy Oz cloud agent workers on your own infrastructure * **Advanced compliance** - SOC 2, HIPAA, and custom data handling agreements * **Priority support** - Dedicated Slack/Teams channels For complete plan details, visit [warp.dev/pricing](https://www.warp.dev/pricing) or [contact sales](https://warp.dev/contact-sales). ## Admin Panel sections [Section titled “Admin Panel sections”](#admin-panel-sections) The Admin Panel is organized into six main areas: ### AI settings [Section titled “AI settings”](#ai-settings) Configure how agents behave across your organization, including autonomy levels and command permissions. This is where you balance agent productivity with organizational safety requirements. #### General AI settings [Section titled “General AI settings”](#general-ai-settings) **AI in remote sessions** * Controls whether agents are available during SSH sessions and remote connections * Enterprise plans can toggle this setting * Consider disabling for production servers or sensitive environments **Prompt summarization caching** * When conversations become long, the LLM provider caches summaries temporarily * Improves performance for extended agent interactions * Zero Data Retention agreements cover caching (short-lived) #### Autonomy settings [Section titled “Autonomy settings”](#autonomy-settings) Configure how much independence agents have when performing actions. Choose between: * **Agent Decides** - Agent acts autonomously when confident, asks when uncertain (recommended) * **Always Ask** - Require explicit approval for every action * **Always Allow** - Maximum autonomy without confirmations * **Respect User Setting** - Allow individual users to set their preference **Apply code diffs** Controls whether agents can apply code changes without approval. For production-critical codebases, consider “Always Ask” to maintain tight control. **Create plans** Whether agents can create structured task plans (`/plan` command) without user approval. **Execute commands** Manages the agent’s ability to run terminal commands autonomously. Pair with command allowlists/denylists for granular control. **Read files** Controls agent access to reading files in the codebase. Enable for better context, restrict for sensitive repositories. #### Directory and command control [Section titled “Directory and command control”](#directory-and-command-control) **Directory allowlist** Specify directories where agents can read files without restriction. Use absolute paths: * `~/git/internal-tooling` - Grant access to specific projects * `/home/user/repos/public-*` - Use wildcards for patterns **Command allowlist** Regular expressions matching commands agents can execute without asking permission. Common patterns: * `grep .*` - Text search * `ls(\\s.*)?` - Directory listing * `git status` - Version control queries * `which .*` - Finding executables **Command denylist** Regular expressions for commands that **always** require explicit user approval, regardless of autonomy settings: * `rm -rf.*` - Recursive deletion * `sudo.*` - Administrative commands * `curl.*|wget.*` - Network requests * `docker rm.*` - Container operations * `.*production.*` - Commands containing “production” Caution Command denylist rules take precedence over allowlist rules and agent autonomy settings. Use denylists to prevent high-risk operations even in high-autonomy configurations. ### Privacy settings [Section titled “Privacy settings”](#privacy-settings) Manage data collection and security policies to meet your organization’s compliance requirements. **User-generated content (UGC) data collection** Controls how Warp collects and uses user-generated content to improve the service: * **Disabled** - Warp collects no UGC data from your organization * **Enabled** - Allow data collection for service improvement * **Respect User Setting** - Let individual users decide Enterprise teams with Zero Data Retention agreements can disable this completely. **Enterprise secret redaction** Automatically detects and redacts sensitive information before sending data to LLM providers: * Enterprise plans enable this by default * Includes automatic detection of common secret patterns (API keys, passwords, certificates) * Supports custom regex patterns for organization-specific secrets * Applies unconditionally across all team members Configure custom patterns in the Admin Panel to match your organization’s secret formats. ### Code settings [Section titled “Code settings”](#code-settings) Control codebase indexing and agent code features for your team. **Codebase Context** Determines whether Warp indexes your team’s Git repositories to provide context for agents: * **Disabled** - No codebase indexing * **Enabled** - Index codebases for improved agent responses across large, multi-repo systems * **Respect User Setting** - Allow individual control When enabled, agents understand your code patterns, architecture, and conventions across all indexed repositories. Enterprise plans support: * Unlimited repositories * Up to 200,000 files per repository * Team-wide indexing with centralized configuration ### Billing settings [Section titled “Billing settings”](#billing-settings) Configure billing preferences and spending controls to manage costs at scale. **Usage-based pricing** Enable pay-as-you-go billing for credits beyond your plan’s included quota: * Set monthly spending limits to control costs * View current overage usage and costs * Receive alerts when approaching spending thresholds **Credit allocation** For Enterprise plans with negotiated credit pools: * Allocate credits across teams or projects * Monitor usage by team * Set per-team spending limits Contact your account manager to configure advanced credit allocation. ### Sharing settings [Section titled “Sharing settings”](#sharing-settings) Control how team members collaborate and share Warp Drive resources. **Direct link sharing** Allow team members to share Notebooks, Workflows, Prompts, and other Warp Drive objects via direct links: * **Enabled** - Team members can generate shareable links * **Team only** - Links work only for team members * **Disabled** - No link sharing **Anyone with link sharing** Enable public access to shared objects: * **Enabled** - Anyone with the link can view content without being a team member * **Disabled** - Links require team membership to access For organizations with sensitive internal processes, disable “Anyone with link” sharing to prevent accidental exposure. ### Platform settings [Section titled “Platform settings”](#platform-settings) Configure Oz cloud agent settings for your team, including GitHub authorization for automated workflows. **Enabled GitHub Orgs** The **Enabled GitHub Orgs** setting associates your Warp team with one or more GitHub App installations, enabling Oz cloud agents initiated with a [team API key](/reference/cli/api-keys/) to clone repositories and open pull requests using the Oz by Warp GitHub App. To configure: 1. Navigate to the **Platform** section of the Admin Panel. 2. Under **Enabled GitHub Orgs**, review the list of GitHub organizations where the Oz by Warp GitHub App is installed. 3. Select which organizations your team should have access to. ![Enabled GitHub Orgs setting in the Admin Panel Platform section](/_astro/admin-panel-enabled-github-orgs.DgeT9Y28_ZqBhXs.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Enabled GitHub Orgs setting in the Admin Panel. The organizations and repository access shown here reflect the Oz by Warp GitHub App installation scope, which is configured in [GitHub settings](https://github.com/settings/installations). To change which repositories the app can access, edit the installation directly in GitHub. Note This setting controls GitHub access for team API key runs only. Runs triggered by individual users (via personal API key, Slack, or Linear) continue to use that user’s personal GitHub token. For more details, see [Team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization). ## Multi-admin functionality [Section titled “Multi-admin functionality”](#multi-admin-functionality) Warp supports multiple team administrators to prevent single points of failure and enable distributed management. ### Promoting and demoting admins [Section titled “Promoting and demoting admins”](#promoting-and-demoting-admins) Team admins can grant or revoke admin privileges: 1. Navigate to **Settings** > **Teams** > **Team Members**. 2. Find the user you want to modify. 3. Click the role dropdown next to their name. 4. Select **Admin** or **Member**. 5. Click **Save**. Note We recommend at least one admin in addition to the Team Owner to prevent access issues if one is unavailable. The Team Owner has full access and can transfer ownership; Team Admins have the same permissions except they can’t transfer ownership. ## Common admin workflows [Section titled “Common admin workflows”](#common-admin-workflows) ### Initial enterprise setup [Section titled “Initial enterprise setup”](#initial-enterprise-setup) After purchasing a Warp enterprise plan: 1. **Configure SSO** - Set up authentication with your identity provider. 2. **Enable Codebase Context** - Index your organization’s repositories. 3. **Set agent autonomy** - Configure initial safety levels. 4. **Apply secret redaction** - Add custom patterns for your organization. 5. **Configure BYOLLM** (optional) - Route inference through your cloud accounts. 6. **Create shared resources** - Populate team Warp Drive with Workflows, Rules, and Prompts. See [Roles and permissions](/enterprise/team-management/roles-and-permissions/) for details on user roles and access controls. ### Adjusting policies for different teams [Section titled “Adjusting policies for different teams”](#adjusting-policies-for-different-teams) For organizations with multiple teams (e.g., DevOps, Data, Frontend): 1. Create separate Warp teams for each group. 2. Assign team-specific admins. 3. Configure different autonomy levels per team. 4. Use directory allowlists to scope agent access to team repositories. ### Responding to security incidents [Section titled “Responding to security incidents”](#responding-to-security-incidents) If an agent performs an unintended action: 1. **Immediate:** Review agent action logs in the affected user’s session. 2. **Short-term:** Add specific commands to the command denylist. 3. **Long-term:** Adjust autonomy settings to prevent similar incidents. 4. **Review:** Check the Admin Panel settings for the affected user’s team to confirm what autonomy levels, allowlists, and restrictions were in effect. Warp logs all agent actions with full context, making incident investigation straightforward. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### Users can’t see new settings [Section titled “Users can’t see new settings”](#users-cant-see-new-settings) **Problem:** You changed a setting in the Admin Panel, but users report they don’t see the change. **Solution:** 1. Verify the setting is not set to “Respect User Setting”. 2. Ask users to restart Warp to force a settings refresh. 3. Confirm users are members of the correct team. 4. Check that users have logged in with SSO (not a personal account). ### Setting is grayed out in Admin Panel [Section titled “Setting is grayed out in Admin Panel”](#setting-is-grayed-out-in-admin-panel) **Problem:** A setting you want to configure appears grayed out or shows “Not available on your plan.” **Solution:** * This setting is restricted to higher-tier plans * Review plan features at [warp.dev/pricing](https://www.warp.dev/pricing) * Contact your account manager or [sales team](https://warp.dev/contact-sales) to upgrade ### Command allowlist not working [Section titled “Command allowlist not working”](#command-allowlist-not-working) **Problem:** Agents still ask permission for commands that match your allowlist patterns. **Solution:** 1. Verify regex patterns are correct (test with a regex validator). 2. Check that commands don’t also match the denylist (denylist takes precedence). 3. Confirm autonomy settings allow command execution. 4. Remember: Some commands are always restricted regardless of allowlist. ## Support [Section titled “Support”](#support) Enterprise customers have access to priority support: * **Dedicated channels** - Private Slack or Teams channels with Warp engineers * **Account manager** - Direct contact for escalations and feature requests * **Technical support** - Help with Admin Panel configuration and troubleshooting Reach out through your dedicated Slack/Teams channel or contact your account manager. # Roles and permissions > Understand user roles, permissions, and access controls for managing your Warp Enterprise team. Warp uses a role-based access model to control what team members can do within your organization. Admins manage team settings and enforce policies, while members use Warp’s features within the boundaries admins define. ## User roles [Section titled “User roles”](#user-roles) Warp has three user roles: * **Team Owner** - Has full access to the Admin Panel and can manage team settings, invite users, assign roles, and transfer ownership of the team. There can only be one Owner. * **Team Admin** - Same permissions as the Owner, except they can’t transfer ownership of the team. * **Member** - Standard access to Warp features and team resources. Members can use agents, access shared Warp Drive resources, and configure personal settings within the limits set by admins. ## Managing admins [Section titled “Managing admins”](#managing-admins) Teams can have multiple admins. We recommend at least one admin in addition to the Team Owner to prevent access issues if one is unavailable. ### Promoting or demoting admins [Section titled “Promoting or demoting admins”](#promoting-or-demoting-admins) 1. Navigate to **Settings** > **Teams** > **Team Members**. 2. Find the user you want to modify. 3. Click the three-dot menu icon next to their name. 4. Select **Promote to Admin** or **Demote from Admin**. 5. Confirm the change when prompted. Caution Team Admins cannot demote or modify the Team Owner role. ## Permission details [Section titled “Permission details”](#permission-details) ### What admins can do [Section titled “What admins can do”](#what-admins-can-do) * **Team management** - View members, invite users, remove users, and assign roles. * **Authentication** - Configure SSO and login requirements. * **Agent policies** - Set autonomy levels, command allowlists/denylists, and directory access controls. * **Security settings** - Configure secret redaction, telemetry controls, and data handling policies. * **Feature controls** - Enable or disable Codebase Context, BYOLLM, sharing, and other features. * **Billing** - Monitor credit usage, set spending limits, and manage subscriptions. ### What members can do [Section titled “What members can do”](#what-members-can-do) * **Use agents** - Run Oz agents locally and in the cloud within the policies admins define. * **Access team resources** - Use shared Workflows, Notebooks, Prompts, Rules, and Environment Variables in Warp Drive. * **Configure personal settings** - Adjust settings where admins have selected “Respect User Setting.” * **Share sessions** - Collaborate via session sharing (if enabled by admins). * **Index codebases** - Trigger Codebase Context indexing for repositories (if enabled by admins). ### Settings enforcement [Section titled “Settings enforcement”](#settings-enforcement) Admin-configured settings follow a three-tier model: * **Organization enforced** - Applies to all members. Users cannot override these settings. Use for security-critical policies (e.g., secret redaction, command denylists). * **Respect user setting** - Admins set a default, but individual users can customize. Use for preferences that don’t impact security. * **Tier restricted** - Setting is locked based on billing plan and cannot be changed until the plan is upgraded. See the [Admin Panel](/enterprise/team-management/admin-panel/) documentation for details on configuring each setting. ## Resource sharing controls [Section titled “Resource sharing controls”](#resource-sharing-controls) Admins control how team members collaborate and share Warp Drive resources: * **Direct link sharing** - Allow team members to share Notebooks, Workflows, Prompts, and other objects via direct links. * **Team-only links** - Restrict links so only team members can access them. * **Public link sharing** - Enable or disable access for anyone with the link (even non-team members). For organizations with sensitive internal processes, disable public link sharing to prevent accidental exposure. ## Related resources [Section titled “Related resources”](#related-resources) * [Admin Panel](/enterprise/team-management/admin-panel/) - Configure team settings and enforce policies * [Getting started for developers](/enterprise/getting-started/getting-started-developers/) - Developer onboarding guide # Team management in Warp > Create and manage teams in Warp to organize users, share resources, and collaborate across your engineering organization. ## What is a team? [Section titled “What is a team?”](#what-is-a-team) A team is a group of Warp users who collaborate together. Teams share a dedicated workspace in [Warp Drive](/knowledge-and-collaboration/warp-drive/), giving members access to shared Workflows, Notebooks, Prompts, Rules, Plans, and Environment Variables. Teams are the foundation of Warp’s enterprise experience — they enable centralized administration, shared configuration, and team-wide policy enforcement through the [Admin Panel](/enterprise/team-management/admin-panel/). Note Each Warp user can be an admin or member of one team at a time. ## Creating a team [Section titled “Creating a team”](#creating-a-team) You can create a new team in two ways: * From the **Warp Drive** side panel, click **+ Create a team**. * In Warp, navigate to **Settings** > **Teams** and follow the prompts. When creating a team, give it a meaningful name that represents your organization, company, or project. The person who creates the team becomes the **Team Owner**. Note You can rename your team at any time by going to **Settings** > **Teams**, clicking on the team name, entering the new name, and pressing `Enter`. ### Inviting team members [Section titled “Inviting team members”](#inviting-team-members) Under **Settings** > **Teams**, copy the invite link and share it with your teammates through a secure channel like Slack or email. Caution On paid plans, adding new members automatically adds them as paid seats. New members are billed on a prorated basis for the remainder of the billing cycle. See [Billing](/enterprise/support-and-resources/billing/) for details. ## Restricting team invites by domain [Section titled “Restricting team invites by domain”](#restricting-team-invites-by-domain) Team Admins can restrict team membership to users with specific email domains — for example, your company’s email domain. To enable domain restriction: 1. Navigate to **Settings** > **Teams**. 2. Toggle on **Restrict by domain**. 3. Add your allowed email domains to the allowlist. When domain restriction is enabled, users who attempt to join with a non-matching email domain will be prompted to authenticate via an emailed link sent to an email address on an allowed domain. ## Joining a team [Section titled “Joining a team”](#joining-a-team) If you’ve received an invite link, use it to sign up or log in and join the team. If the team uses domain restriction, you’ll need to verify that you have access to an email address on an allowed domain before joining. ## Leaving and deleting teams [Section titled “Leaving and deleting teams”](#leaving-and-deleting-teams) * **Members and Admins** - Can leave a team at any time by visiting **Settings** > **Teams** and clicking **Leave team**. * **Team Owners** - Can delete a team, but only after removing all other team members first. Caution If you’re a Team Owner and choose to [delete your Warp account](/support-and-community/privacy-and-security/privacy/#delete-your-account-and-data), you’ll need to assign a team member as the new owner before your account can be deleted. ## Team discoverability [Section titled “Team discoverability”](#team-discoverability) Team admins can make their team discoverable to colleagues who share the same email domain. When enabled, new users with a matching domain can find and join the team without needing a direct invite link. To enable discoverability, go to **Settings** > **Teams** > **Make team discoverable**. Note While discoverability is enabled, any new user who joins the team will add a prorated charge to the team’s next billing cycle. ## Transferring team ownership [Section titled “Transferring team ownership”](#transferring-team-ownership) Team Owners can transfer ownership to another team member: 1. Navigate to **Settings** > **Teams** > **Team Members**. 2. Click the three-dot menu icon next to the member you want to transfer ownership to. 3. Click **Transfer ownership**. Only the current Team Owner can initiate an ownership transfer. After the transfer, the previous owner becomes a regular member (or admin, depending on the team’s configuration). Note If the new owner’s email is not on a work domain, team discoverability will be automatically disabled as a safety measure. ## Team roles and permissions [Section titled “Team roles and permissions”](#team-roles-and-permissions) Warp uses three roles to manage team access: * **Team Owner** - Full access to the Admin Panel and all team settings. Can manage members, assign roles, configure policies, and transfer ownership. There can only be one Owner per team. * **Team Admin** - Same permissions as the Owner, except they cannot transfer team ownership. Teams on Enterprise plans can have multiple admins. * **Member** - Standard access to Warp features and team resources. Members can use agents, access shared Warp Drive resources, and configure personal settings within the limits set by admins. Note We recommend having at least one Team Admin in addition to the Team Owner to prevent access issues if one is unavailable. ### Permissions overview [Section titled “Permissions overview”](#permissions-overview) | | Owner | Admin | Member | | ------------------------------ | ------------- | ----- | ------ | | | Create a team | ✓ | ✓ | | Restrict invites by domain | ✓ | ✓ | | | Invite members | ✓ | ✓ | ✓ | | Remove team members | ✓ | ✓ | | | | Leave a team | | ✓ | | Delete a team | ✓ | | | | Transfer ownership | ✓ | | | | Promote/demote admins | ✓ | ✓ | | | Manage billing | ✓ | ✓ | | | Configure Admin Panel settings | ✓ | ✓ | | ### Multi-admin support [Section titled “Multi-admin support”](#multi-admin-support) Teams on the **Enterprise** plan can have multiple admins, enabling distributed management and preventing single points of failure. To promote or demote a team admin: 1. Navigate to **Settings** > **Teams** > **Team Members**. 2. Find the user you want to modify and click the three-dot menu icon next to their name. 3. Click **Promote to Admin** or **Demote from Admin**. 4. Confirm the change when prompted. Caution Team Admins cannot demote or modify the Team Owner’s role. The Owner role can only change through an ownership transfer. For detailed information on what each role can do and how settings enforcement works, see [Roles and permissions](/enterprise/team-management/roles-and-permissions/). ## Related resources [Section titled “Related resources”](#related-resources) * [Admin Panel](/enterprise/team-management/admin-panel/) - Configure team settings and enforce policies * [Roles and permissions](/enterprise/team-management/roles-and-permissions/) - Detailed permission breakdowns and settings enforcement * [Getting started for admins](/enterprise/getting-started/getting-started-enterprise/) - Admin onboarding guide * [Billing](/enterprise/support-and-resources/billing/) - Understand team billing and seat management # Keyboard Shortcuts > View, customize, and remap keyboard shortcuts for all Warp features. Warp opens with a shortcut screen showing some of the most commonly used keyboard shortcuts. Hide the shortcut screen by clicking the x button. Quickly view keyboard shortcuts via the [Command Palette](/terminal/command-palette/) or the Resource Center keyboard shortcut sidebar. ## Custom keyboard shortcuts [Section titled “Custom keyboard shortcuts”](#custom-keyboard-shortcuts) Set custom, clear, or default keyboard shortcuts by navigating to **Settings** > **Keyboard shortcuts**. Search through the re-mappable actions or existing shortcuts using the search bar. Remap the keyboard shortcuts using a file. See our [keysets repository](https://github.com/warpdotdev/keysets/tree/main) for instructions. Note On macOS, [system keyboard shortcuts](https://support.apple.com/en-us/HT201236) like `CMD-ESC`, `CMD-BACKTICK`, `CMD-TAB`, `CMD-PERIOD`, and `CMD-TILDE` need to be [unbound](https://support.apple.com/guide/mac-help/keyboard-shortcuts-mchlp2262/mac) before you can use them in Warp. Caution Keybinds that conflict with others are highlighted with an orange border. ![keybinds that conflict with others are highlighted in orange](/_astro/keybinds-conflict.O8JIUjCq_Z19PQKz.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) An example of a keybinding conflict warning. ## All available shortcuts [Section titled “All available shortcuts”](#all-available-shortcuts) * macOS **Warp Essentials** | Shortcut | Command | Action | | -------------- | ---------------------------- | ---------------------------------------------- | | `CMD-D` | Split Pane Right | `pane_group:add_right` | | `CTRL-CMD-L` | Launch Configuration Palette | `workspace:toggle_launch_config_palette` | | `CTRL-CMD-T` | Open Theme Picker | `workspace:show_theme_chooser` | | `CTRL-R` | Command Search | `workspace:show_command_search` | | `CTRL-SHIFT-R` | Workflows | `input:toggle_workflows` | | `` CTRL-` `` | Generate | `input:toggle_natural_language_command_search` | | `CMD-L` | Focus Terminal Input | `terminal:focus_input` | | `CTRL-I` | Warpify Subshell | `terminal:trigger_subshell_bootstrap` | | `CMD-\` | Warp Drive | `terminal:toggle_warp_drive` | | `CMD-O` | File search | | | `CMD-P` | Open Command Palette | | **Blocks** | Shortcut | Command | Action | | ----------------- | --------------------------------- | ------------------------------------------------------ | | `ALT-DOWN` | Select the Closest Bookmark Down | `terminal:select_bookmark_down` | | `ALT-SHIFT-CMD-C` | Copy Command Output | `terminal:copy_outputs` | | `ALT-UP` | Select the Closest Bookmark Up | `terminal:select_bookmark_up` | | `CMD-A` | Select All Blocks | `terminal:select_all_blocks` | | `CMD-K` | Clear Blocks | `terminal:clear_blocks` | | `CMD-B` | Bookmark Selected Block | `terminal:bookmark_selected_block` | | `CMD-DOWN` | Select Next Block | `terminal:select_next_block` | | `CMD-I` | Reinput Selected Commands | `terminal:reinput_commands` | | `CMD-UP` | Select Previous Block | `terminal:select_previous_block` | | `CTRL-M` | Open Block Context Menu | `terminal:open_block_list_context_menu_via_keybinding` | | `SHIFT-CMD-C` | Copy Command | `terminal:copy_commands` | | `SHIFT-CMD-I` | Reinput Selected Commands as Root | `terminal:reinput_commands_with_sudo` | | `SHIFT-CMD-S` | Share Selected Block | `terminal:open_share_modal` | | `SHIFT-DOWN` | Expand Selected Blocks Below | `terminal:expand_block_selection_below` | | `SHIFT-UP` | Expand Selected Blocks Above | `terminal:expand_block_selection_above` | **Scrolling** | Shortcut | Command | Action | | ---------------- | ------------------------------------ | --------------------------------------------- | | `PAGE UP` | Scroll Up One Page | `terminal:page_up` | | `PAGE DOWN` | Scroll Down One Page | `terminal:page_down` | | `HOME` | Scroll to Top | `terminal:home` | | `END` | Scroll to Bottom | `terminal:end` | | `SHIFT-CMD-UP` | Scroll to Top of Selected Block | `terminal:scroll_to_top_of_selected_block` | | `SHIFT-CMD-DOWN` | Scroll to Bottom of Selected Block | `terminal:scroll_to_bottom_of_selected_block` | | | Scroll Terminal Output Up One Line | `terminal:scroll_up_one_line` | | | Scroll Terminal Output Down One Line | `terminal:scroll_down_one_line` | Note “Scroll Terminal Output Up/Down One Line” has no default keybinding. You can assign one in Settings > Keyboard shortcuts or trigger it from the [Command Palette](/terminal/command-palette/). During long-running or full-screen commands, `PAGE UP`, `PAGE DOWN`, `HOME`, and `END` are forwarded to the running program. **Input Editor** | Shortcut | Command | Action | | ----------------- | ----------------------------------------- | ------------------------------------------ | | `ALT-BACKSPACE` | Delete Word Left | `editor:delete_word_left` | | `ALT-CMD-F` | Fold Selected Ranges | `editor_view:fold_selected_ranges` | | `ALT-CMD-[` | Fold | `editor_view:fold` | | `ALT-CMD-]` | Unfold | `editor_view:unfold` | | `ALT-DELETE` | Delete Word Right | `editor:delete_word_right` | | `CMD-A` | Select All | `editor_view:select_all` | | `CMD-BACKSPACE` | Delete All Left | `editor_view:delete_all_left` | | `CMD-DELETE` | Delete All Right | `editor_view:delete_all_right` | | `CMD-DOWN` | Move Cursor to the Bottom | `editor_view:cmd_down` | | `CMD-I` | Inspect Command | `editor_view:cmd_i` | | `CMD-LEFT` | Home | `editor_view:home` | | `CMD-RIGHT` | End | `editor_view:end` | | `CTRL-A` | Move to Start of Line | `editor_view:move_to_line_start` | | `CTRL-B` | Move Cursor Left | `editor_view:left` | | `CTRL-C` | Clear Command Editor | `editor_view:clear_buffer` | | `CTRL-D` | Delete | `editor_view:delete` | | `CTRL-E` | Move to End of Line | `editor_view:move_to_line_end` | | `CTRL-F` | Move Cursor Right / Accept Autosuggestion | `editor_view:right` | | `CTRL-G` | Add Selection for Next Occurrence | `editor_view:add_next_occurrence` | | `CTRL-H` | Remove the Previous Character | `editor_view:backspace` | | `CTRL-J` | Insert Newline | `editor_view:insert_newline` | | `CTRL-K` | Cut All Right | `editor_view:cut_all_right` | | `CTRL-L` | Clear Screen | `input:clear_screen` | | `CTRL-N` | Move Cursor Down | `editor_view:down` | | `CTRL-P` | Move Cursor Up | `editor_view:up` | | `CTRL-SHIFT-A` | Select to Start of Line | `editor_view:select_to_line_start` | | `CTRL-SHIFT-B` | Select One Character to the Left | `editor_view:select_left` | | `CTRL-SHIFT-DOWN` | Add Cursor Below | `editor_view:add_cursor_below` | | `CTRL-SHIFT-E` | Select to End of Line | `editor:select_to_line_end` | | `CMD-Z` | Undo | `editor:undo` | | `CMD-SHIFT-Z` | Redo | `editor:redo` | | `CTRL-SHIFT-F` | Select One Character to the Right | `editor:select_right` | | `CTRL-SHIFT-N` | Select Down | `editor_view:select_down` | | `CTRL-SHIFT-P` | Select Up | `editor_view:select_up` | | `CTRL-SHIFT-UP` | Add Cursor Above | `editor_view:add_cursor_above` | | `CTRL-U` | Copy and Clear Selected Lines | `editor_view:clear_and_copy_lines` | | `CTRL-W` | Cut Word Left | `editor_view:cut_word_left` | | `META-.` | Insert Last Word of Previous Command | `editor:insert_last_word_previous_command` | | `META-A` | Move to the Start of the Paragraph | `editor_view:move_to_paragraph_start` | | `META-B` | Move Backward One Word | `editor_view:move_backward_one_word` | | `META-D` | Cut Word Right | `editor_view:cut_word_right` | | `META-E` | Move to the End of the Paragraph | `editor_view:move_to_paragraph_end` | | `META-F` | Move Forward One Word | `editor_view:move_forward_one_word` | | `CTRL-OPT-LEFT` | Move Backward One Subword | `editor_view:move_backward_one_subword` | | `CTRL-OPT-RIGHT` | Move Forward One Subword | `editor_view:move_forward_one_subword` | | `SHIFT-CMD-K` | Clear Selected Lines | `editor_view:clear_lines` | | `SHIFT-META-<` | Move to the Start of the Buffer | `editor_view:move_to_buffer_start` | | `SHIFT-META->` | Move to the End of the Buffer | `editor_view:move_to_buffer_end` | | `SHIFT-META-B` | Select One Word to the Left | `editor_view:select_left_by_word` | | `SHIFT-META-F` | Select One Word to the Right | `editor_view:select_right_by_word` | **Terminal** | Shortcut | Command | Action | | ----------------- | ------------------------------------------------- | -------------------------------------------- | | `ALT-CMD-DOWN` | Switch Panes Down | `pane_group:navigate_down` | | `ALT-CMD-LEFT` | Switch Panes Left | `pane_group:navigate_left` | | `ALT-CMD-RIGHT` | Switch Panes Right | `pane_group:navigate_right` | | `ALT-CMD-UP` | Switch Panes Up | `pane_group:navigate_up` | | `ALT-CMD-V` | \[a11y] Set Concise Accessibility Announcements | `workspace:set_a11y_concise_verbosity_level` | | `ALT-CMD-V` | \[a11y] Set Verbose Accessibility Announcements | `workspace:set_a11y_verbose_verbosity_level` | | `CMD-,` | Open Settings | `workspace:show_settings_modal` | | `CMD-,` | Open Settings: Account | `workspace:show_settings_account_page` | | `CMD-G` | Find the Next Occurrence of Your Search Query | `find:find_next_occurrence` | | `CMD-P` | Toggle Command Palette | `workspace:toggle_command_palette` | | | Toggle Mouse Reporting | `workspace:toggle_mouse_reporting` | | `CMD-[` | Activate Previous Pane | `pane_group:navigate_prev` | | `CMD-]` | Activate Next Pane | `pane_group:navigate_next` | | `CTRL-CMD-DOWN` | Resize Pane > Move Divider Down | `pane_group:resize_down` | | `CTRL-CMD-K` | Open Keybindings Editor | `workspace:show_keybinding_settings` | | `CTRL-CMD-LEFT` | Resize Pane > Move Divider Left | `pane_group:resize_left` | | `CTRL-CMD-RIGHT` | Resize Pane > Move Divider Right | `pane_group:resize_right` | | `CTRL-CMD-UP` | Resize Pane > Move Divider Up | `pane_group:resize_up` | | `CTRL-SHIFT-?` | Open Resource Center | `workspace:toggle_resource_center` | | `SHIFT-CMD-D` | Split Pane Down | `pane_group:add_down` | | `SHIFT-CMD-ENTER` | Toggle Maximize Active Pane | `pane_group:toggle_maximize_pane` | | `SHIFT-CMD-G` | Find the Previous Occurrence of Your Search Query | `find:find_prev_occurrence` | | `SHIFT-CMD-P` | Toggle Navigation Palette | `workspace:toggle_navigation_palette` | **Fundamentals** | Shortcut | Command | Action | | ------------------ | -------------------------- | -------------------------------- | | `CMD--` | Decrease Font Size | `workspace:decrease_font_size` | | `CMD-0` | Reset Font Size to Default | `workspace:reset_font_size` | | `CMD-1` | Switch to 1st Tab | `workspace:activate_first_tab` | | `CMD-2` | Switch to 2nd Tab | `workspace:activate_second_tab` | | `CMD-3` | Switch to 3rd Tab | `workspace:activate_third_tab` | | `CMD-4` | Switch to 4th Tab | `workspace:activate_fourth_tab` | | `CMD-5` | Switch to 5th Tab | `workspace:activate_fifth_tab` | | `CMD-6` | Switch to 6th Tab | `workspace:activate_sixth_tab` | | `CMD-7` | Switch to 7th Tab | `workspace:activate_seventh_tab` | | `CMD-8` | Switch to 8th Tab | `workspace:activate_eighth_tab` | | `CMD-9` | Switch to Last Tab | `workspace:activate_last_tab` | | `CMD-=` | Increase Font Size | `workspace:increase_font_size` | | `CMD-C` | Copy | `terminal:copy` | | `CMD-F` | Find | `terminal:find` | | `CMD-V` | Paste | `terminal:paste` | | `CMD-T` | Open New Tab | `workspace:open_new_tab` | | `SHIFT-CMD-T` | Reopen Closed Tab | `workspace:reopen_closed_tab` | | `CTRL-SHIFT-LEFT` | Move Tab Left | `workspace:move_tab_left` | | `CTRL-SHIFT-RIGHT` | Move Tab Right | `workspace:move_tab_right` | | `SHIFT-CMD-{` | Activate Previous Tab | `workspace:activate_prev_tab` | | `SHIFT-CMD-}` | Activate Next Tab | `workspace:activate_next_tab` | * Windows **Warp Essentials** | Shortcut | Command | Action | | -------------- | ---------------------------- | ---------------------------------------------- | | `CTRL-SHIFT-D` | Split Pane Right | `pane_group:add_right` | | | Launch Configuration Palette | `workspace:toggle_launch_config_palette` | | | Open Theme Picker | `workspace:show_theme_chooser` | | `CTRL-R` | Command Search | `workspace:show_command_search` | | `CTRL-SHIFT-R` | Workflows | `input:toggle_workflows` | | `` CTRL-` `` | Generate | `input:toggle_natural_language_command_search` | | `CTRL-SHIFT-L` | Focus Terminal Input | `terminal:focus_input` | | `CTRL-I` | Warpify Subshell | `terminal:trigger_subshell_bootstrap` | | `CTRL-SHIFT-\` | Warp Drive | `terminal:toggle_warp_drive` | **Blocks** | Shortcut | Command | Action | | ------------------ | --------------------------------- | ------------------------------------------------------ | | `ALT-DOWN` | Select the Closest Bookmark Down | `terminal:select_bookmark_down` | | `CTRL-SHIFT-ALT-C` | Copy Command Output | `terminal:copy_outputs` | | `ALT-UP` | Select the Closest Bookmark Up | `terminal:select_bookmark_up` | | `CTRL-SHIFT-A` | Select All Blocks | `terminal:select_all_blocks` | | `CTRL-SHIFT-K` | Clear Blocks | `terminal:clear_blocks` | | `CTRL-SHIFT-B` | Bookmark Selected Block | `terminal:bookmark_selected_block` | | `CTRL-DOWN` | Select Next Block | `terminal:select_next_block` | | `CTRL-SHIFT-I` | Reinput Selected Commands | `terminal:reinput_commands` | | `CTRL-UP` | Select Previous Block | `terminal:select_previous_block` | | | Open Block Context Menu | `terminal:open_block_list_context_menu_via_keybinding` | | `CTRL-SHIFT-C` | Copy Command | `terminal:copy_commands` | | | Reinput Selected Commands as Root | `terminal:reinput_commands_with_sudo` | | `CTRL-SHIFT-S` | Share Selected Block | `terminal:open_share_modal` | | `SHIFT-DOWN` | Expand Selected Blocks Below | `terminal:expand_block_selection_below` | | `SHIFT-UP` | Expand Selected Blocks Above | `terminal:expand_block_selection_above` | **Scrolling** | Shortcut | Command | Action | | ----------------- | ------------------------------------ | --------------------------------------------- | | `PAGE UP` | Scroll Up One Page | `terminal:page_up` | | `PAGE DOWN` | Scroll Down One Page | `terminal:page_down` | | `HOME` | Scroll to Top | `terminal:home` | | `END` | Scroll to Bottom | `terminal:end` | | `CTRL-SHIFT-UP` | Scroll to Top of Selected Block | `terminal:scroll_to_top_of_selected_block` | | `CTRL-SHIFT-DOWN` | Scroll to Bottom of Selected Block | `terminal:scroll_to_bottom_of_selected_block` | | | Scroll Terminal Output Up One Line | `terminal:scroll_up_one_line` | | | Scroll Terminal Output Down One Line | `terminal:scroll_down_one_line` | Note “Scroll Terminal Output Up/Down One Line” has no default keybinding. You can assign one in Settings > Keyboard shortcuts or trigger it from the [Command Palette](/terminal/command-palette/). During long-running or full-screen commands, `PAGE UP`, `PAGE DOWN`, `HOME`, and `END` are forwarded to the running program. **Input Editor** | Shortcut | Command | Action | | ------------------ | ----------------------------------------- | ------------------------------------------ | | `CTRL-BACKSPACE` | Delete Word Left | `editor:delete_word_left` | | `CTRL-ALT-F` | Fold Selected Ranges | `editor_view:fold_selected_ranges` | | `CTRL-ALT-[` | Fold | `editor_view:fold` | | `CTRL-ALT-]` | Unfold | `editor_view:unfold` | | `CTRL-DELETE` | Delete Word Right | `editor:delete_word_right` | | `CTRL-A` | Select All | `editor_view:select_all` | | `CTRL-Y` | Delete All Left | `editor_view:delete_all_left` | | | Delete All Right | `editor_view:delete_all_right` | | `CTRL-END` | Move Cursor to the Bottom | `editor_view:cmd_down` | | `CTRL-I` | Inspect Command | `editor_view:cmd_i` | | `HOME` | Home | `editor_view:home` | | `END` | End | `editor_view:end` | | `CTRL-A` | Move to Start of Line | `editor_view:move_to_line_start` | | `CTRL-B` | Move Cursor Left | `editor_view:left` | | `CTRL-C` | Clear Command Editor | `editor_view:clear_buffer` | | `CTRL-D` | Delete | `editor_view:delete` | | `CTRL-E` | Move to End of Line | `editor_view:move_to_line_end` | | `CTRL-F` | Move Cursor Right / Accept Autosuggestion | `editor_view:right` | | `CTRL-G` | Add Selection for Next Occurrence | `editor_view:add_next_occurrence` | | `CTRL-H` | Remove the Previous Character | `editor_view:backspace` | | `CTRL-J` | Insert Newline | `editor_view:insert_newline` | | `CTRL-K` | Cut All Right | `editor_view:cut_all_right` | | `CTRL-L` | Clear Screen | `input:clear_screen` | | `CTRL-N` | Move Cursor Down | `editor_view:down` | | `CTRL-P` | Move Cursor Up | `editor_view:up` | | | Select to Start of Line | `editor_view:select_to_line_start` | | `CTRL-SHIFT-B` | Select One Character to the Left | `editor_view:select_left` | | `CTRL-SHIFT-DOWN` | Add Cursor Below | `editor_view:add_cursor_below` | | | Select to End of Line | `editor:select_to_line_end` | | `CTRL-Z` | Undo | `editor:undo` | | `CTRL-SHIFT-Z` | Redo | `editor:redo` | | `CTRL-SHIFT-F` | Select One Character to the Right | `editor:select_right` | | | Select Down | `editor_view:select_down` | | `CTRL-SHIFT-P` | Select Up | `editor_view:select_up` | | `CTRL-SHIFT-UP` | Add Cursor Above | `editor_view:add_cursor_above` | | `CTRL-U` | Copy and Clear Selected Lines | `editor_view:clear_and_copy_lines` | | `CTRL-W` | Cut Word Left | `editor_view:cut_word_left` | | `META-.` | Insert Last Word of Previous Command | `editor:insert_last_word_previous_command` | | `META-A` | Move to the Start of the Paragraph | `editor_view:move_to_paragraph_start` | | `CTRL-LEFT` | Move Backward One Word | `editor_view:move_backward_one_word` | | `ALT-D` | Cut Word Right | `editor_view:cut_word_right` | | `META-E` | Move to the End of the Paragraph | `editor_view:move_to_paragraph_end` | | `CTRL-RIGHT` | Move Forward One Word | `editor_view:move_forward_one_word` | | `CTRL-ALT-LEFT` | Move Backward One Subword | `editor_view:move_backward_one_subword` | | `CTRL-ALT-RIGHT` | Move Forward One Subword | `editor_view:move_forward_one_subword` | | `SHIFT-META-<` | Move to the Start of the Buffer | `editor_view:move_to_buffer_start` | | `SHIFT-META->` | Move to the End of the Buffer | `editor_view:move_to_buffer_end` | | `CTRL-SHIFT-LEFT` | Select One Word to the Left | `editor_view:select_left_by_word` | | `CTRL-SHIFT-RIGHT` | Select One Word to the Right | `editor_view:select_right_by_word` | **Terminal** | Shortcut | Command | Action | | ------------------ | ------------------------------------------------- | -------------------------------------------- | | `CTRL-ALT-DOWN` | Switch Panes Down | `pane_group:navigate_down` | | `CTRL-ALT-LEFT` | Switch Panes Left | `pane_group:navigate_left` | | `CTRL-ALT-RIGHT` | Switch Panes Right | `pane_group:navigate_right` | | `CTRL-ALT-UP` | Switch Panes Up | `pane_group:navigate_up` | | `CTRL-ALT-V` | \[a11y] Set Concise Accessibility Announcements | `workspace:set_a11y_concise_verbosity_level` | | `CTRL-ALT-V` | \[a11y] Set Verbose Accessibility Announcements | `workspace:set_a11y_verbose_verbosity_level` | | `CTRL-,` | Open Settings | `workspace:show_settings_modal` | | `CTRL-,` | Open Settings: Account | `workspace:show_settings_account_page` | | `F3` | Find the Next Occurrence of Your Search Query | `find:find_next_occurrence` | | `CTRL-SHIFT-P` | Toggle Command Palette | `workspace:toggle_command_palette` | | | Toggle Mouse Reporting | `workspace:toggle_mouse_reporting` | | `CTRL-SHIFT-[` | Activate Previous Pane | `pane_group:navigate_prev` | | `CTRL-SHIFT-]` | Activate Next Pane | `pane_group:navigate_next` | | | Resize Pane > Move Divider Down | `pane_group:resize_down` | | `CTRL-CMD-K` | Open Keybindings Editor | `workspace:show_keybinding_settings` | | | Resize Pane > Move Divider Left | `pane_group:resize_left` | | | Resize Pane > Move Divider Right | `pane_group:resize_right` | | | Resize Pane > Move Divider Up | `pane_group:resize_up` | | `CTRL-SHIFT-/` | Open Resource Center | `workspace:toggle_resource_center` | | `CTRL-SHIFT-E` | Split Pane Down | `pane_group:add_down` | | `CTRL-SHIFT-ENTER` | Toggle Maximize Active Pane | `pane_group:toggle_maximize_pane` | | `SHIFT-F3` | Find the Previous Occurrence of Your Search Query | `find:find_prev_occurrence` | | | Toggle Navigation Palette | `workspace:toggle_navigation_palette` | **Fundamentals** | Shortcut | Command | Action | | ------------------ | -------------------------- | -------------------------------- | | `CTRL--` | Decrease Font Size | `workspace:decrease_font_size` | | `CTRL-0` | Reset Font Size to Default | `workspace:reset_font_size` | | `CTRL-1` | Switch to 1st Tab | `workspace:activate_first_tab` | | `CTRL-2` | Switch to 2nd Tab | `workspace:activate_second_tab` | | `CTRL-3` | Switch to 3rd Tab | `workspace:activate_third_tab` | | `CTRL-4` | Switch to 4th Tab | `workspace:activate_fourth_tab` | | `CTRL-5` | Switch to 5th Tab | `workspace:activate_fifth_tab` | | `CTRL-6` | Switch to 6th Tab | `workspace:activate_sixth_tab` | | `CTRL-7` | Switch to 7th Tab | `workspace:activate_seventh_tab` | | `CTRL-8` | Switch to 8th Tab | `workspace:activate_eighth_tab` | | `CTRL-9` | Switch to Last Tab | `workspace:activate_last_tab` | | `CTRL-=` | Increase Font Size | `workspace:increase_font_size` | | `CTRL-SHIFT-C` | Copy | `terminal:copy` | | `CTRL-SHIFT-F` | Find | `terminal:find` | | `CTRL-SHIFT-V` | Paste | `terminal:paste` | | `CTRL-SHIFT-T` | Open New Tab | `workspace:open_new_tab` | | `CTRL-ALT-T` | Reopen Closed Tab | `workspace:reopen_closed_tab` | | `CTRL-SHIFT-LEFT` | Move Tab Left | `workspace:move_tab_left` | | `CTRL-SHIFT-RIGHT` | Move Tab Right | `workspace:move_tab_right` | | `CTRL-PAGEUP` | Activate Previous Tab | `workspace:activate_prev_tab` | | `CTRL-PAGEDOWN` | Activate Next Tab | `workspace:activate_next_tab` | * Linux **Warp Essentials** | Shortcut | Command | Action | | -------------- | ---------------------------- | ---------------------------------------------- | | `CTRL-SHIFT-D` | Split Pane Right | `pane_group:add_right` | | | Launch Configuration Palette | `workspace:toggle_launch_config_palette` | | | Open Theme Picker | `workspace:show_theme_chooser` | | `CTRL-R` | Command Search | `workspace:show_command_search` | | `CTRL-SHIFT-R` | Workflows | `input:toggle_workflows` | | `` CTRL-` `` | Generate | `input:toggle_natural_language_command_search` | | `CTRL-SHIFT-L` | Focus Terminal Input | `terminal:focus_input` | | `CTRL-I` | Warpify Subshell | `terminal:trigger_subshell_bootstrap` | | `CTRL-SHIFT-\` | Warp Drive | `terminal:toggle_warp_drive` | **Blocks** | Shortcut | Command | Action | | ------------------ | --------------------------------- | ------------------------------------------------------ | | `ALT-DOWN` | Select the Closest Bookmark Down | `terminal:select_bookmark_down` | | `CTRL-SHIFT-ALT-C` | Copy Command Output | `terminal:copy_outputs` | | `ALT-UP` | Select the Closest Bookmark Up | `terminal:select_bookmark_up` | | `CTRL-SHIFT-A` | Select All Blocks | `terminal:select_all_blocks` | | `CTRL-SHIFT-K` | Clear Blocks | `terminal:clear_blocks` | | `CTRL-SHIFT-B` | Bookmark Selected Block | `terminal:bookmark_selected_block` | | `CTRL-DOWN` | Select Next Block | `terminal:select_next_block` | | `CTRL-SHIFT-I` | Reinput Selected Commands | `terminal:reinput_commands` | | `CTRL-UP` | Select Previous Block | `terminal:select_previous_block` | | | Open Block Context Menu | `terminal:open_block_list_context_menu_via_keybinding` | | `CTRL-SHIFT-C` | Copy Command | `terminal:copy_commands` | | | Reinput Selected Commands as Root | `terminal:reinput_commands_with_sudo` | | `CTRL-SHIFT-S` | Share Selected Block | `terminal:open_share_modal` | | `SHIFT-DOWN` | Expand Selected Blocks Below | `terminal:expand_block_selection_below` | | `SHIFT-UP` | Expand Selected Blocks Above | `terminal:expand_block_selection_above` | **Scrolling** | Shortcut | Command | Action | | ----------------- | ------------------------------------ | --------------------------------------------- | | `PAGE UP` | Scroll Up One Page | `terminal:page_up` | | `PAGE DOWN` | Scroll Down One Page | `terminal:page_down` | | `HOME` | Scroll to Top | `terminal:home` | | `END` | Scroll to Bottom | `terminal:end` | | `CTRL-SHIFT-UP` | Scroll to Top of Selected Block | `terminal:scroll_to_top_of_selected_block` | | `CTRL-SHIFT-DOWN` | Scroll to Bottom of Selected Block | `terminal:scroll_to_bottom_of_selected_block` | | | Scroll Terminal Output Up One Line | `terminal:scroll_up_one_line` | | | Scroll Terminal Output Down One Line | `terminal:scroll_down_one_line` | Note “Scroll Terminal Output Up/Down One Line” has no default keybinding. You can assign one in Settings > Keyboard shortcuts or trigger it from the [Command Palette](/terminal/command-palette/). During long-running or full-screen commands, `PAGE UP`, `PAGE DOWN`, `HOME`, and `END` are forwarded to the running program. **Input Editor** | Shortcut | Command | Action | | ------------------ | ----------------------------------------- | ------------------------------------------ | | `CTRL-BACKSPACE` | Delete Word Left | `editor:delete_word_left` | | `CTRL-ALT-F` | Fold Selected Ranges | `editor_view:fold_selected_ranges` | | `CTRL-ALT-[` | Fold | `editor_view:fold` | | `CTRL-ALT-]` | Unfold | `editor_view:unfold` | | `CTRL-DELETE` | Delete Word Right | `editor:delete_word_right` | | `CTRL-A` | Select All | `editor_view:select_all` | | `CTRL-Y` | Delete All Left | `editor_view:delete_all_left` | | | Delete All Right | `editor_view:delete_all_right` | | `CTRL-END` | Move Cursor to the Bottom | `editor_view:cmd_down` | | `CTRL-I` | Inspect Command | `editor_view:cmd_i` | | `HOME` | Home | `editor_view:home` | | `END` | End | `editor_view:end` | | `CTRL-A` | Move to Start of Line | `editor_view:move_to_line_start` | | `CTRL-B` | Move Cursor Left | `editor_view:left` | | `CTRL-C` | Clear Command Editor | `editor_view:clear_buffer` | | `CTRL-D` | Delete | `editor_view:delete` | | `CTRL-E` | Move to End of Line | `editor_view:move_to_line_end` | | `CTRL-F` | Move Cursor Right / Accept Autosuggestion | `editor_view:right` | | `CTRL-G` | Add Selection for Next Occurrence | `editor_view:add_next_occurrence` | | `CTRL-H` | Remove the Previous Character | `editor_view:backspace` | | `CTRL-J` | Insert Newline | `editor_view:insert_newline` | | `CTRL-K` | Cut All Right | `editor_view:cut_all_right` | | `CTRL-L` | Clear Screen | `input:clear_screen` | | `CTRL-N` | Move Cursor Down | `editor_view:down` | | `CTRL-P` | Move Cursor Up | `editor_view:up` | | | Select to Start of Line | `editor_view:select_to_line_start` | | `CTRL-SHIFT-B` | Select One Character to the Left | `editor_view:select_left` | | `CTRL-SHIFT-DOWN` | Add Cursor Below | `editor_view:add_cursor_below` | | | Select to End of Line | `editor:select_to_line_end` | | `CTRL-Z` | Undo | `editor:undo` | | `CTRL-SHIFT-Z` | Redo | `editor:redo` | | `CTRL-SHIFT-F` | Select One Character to the Right | `editor:select_right` | | | Select Down | `editor_view:select_down` | | `CTRL-SHIFT-P` | Select Up | `editor_view:select_up` | | `CTRL-SHIFT-UP` | Add Cursor Above | `editor_view:add_cursor_above` | | `CTRL-U` | Copy and Clear Selected Lines | `editor_view:clear_and_copy_lines` | | `CTRL-W` | Cut Word Left | `editor_view:cut_word_left` | | `META-.` | Insert Last Word of Previous Command | `editor:insert_last_word_previous_command` | | `META-A` | Move to the Start of the Paragraph | `editor_view:move_to_paragraph_start` | | `CTRL-LEFT` | Move Backward One Word | `editor_view:move_backward_one_word` | | `ALT-D` | Cut Word Right | `editor_view:cut_word_right` | | `META-E` | Move to the End of the Paragraph | `editor_view:move_to_paragraph_end` | | `CTRL-RIGHT` | Move Forward One Word | `editor_view:move_forward_one_word` | | `CTRL-ALT-LEFT` | Move Backward One Subword | `editor_view:move_backward_one_subword` | | `CTRL-ALT-RIGHT` | Move Forward One Subword | `editor_view:move_forward_one_subword` | | `SHIFT-META-<` | Move to the Start of the Buffer | `editor_view:move_to_buffer_start` | | `SHIFT-META->` | Move to the End of the Buffer | `editor_view:move_to_buffer_end` | | `CTRL-SHIFT-LEFT` | Select One Word to the Left | `editor_view:select_left_by_word` | | `CTRL-SHIFT-RIGHT` | Select One Word to the Right | `editor_view:select_right_by_word` | **Terminal** | Shortcut | Command | Action | | ------------------ | ------------------------------------------------- | -------------------------------------------- | | `CTRL-ALT-DOWN` | Switch Panes Down | `pane_group:navigate_down` | | `CTRL-ALT-LEFT` | Switch Panes Left | `pane_group:navigate_left` | | `CTRL-ALT-RIGHT` | Switch Panes Right | `pane_group:navigate_right` | | `CTRL-ALT-UP` | Switch Panes Up | `pane_group:navigate_up` | | `CTRL-ALT-V` | \[a11y] Set Concise Accessibility Announcements | `workspace:set_a11y_concise_verbosity_level` | | `CTRL-ALT-V` | \[a11y] Set Verbose Accessibility Announcements | `workspace:set_a11y_verbose_verbosity_level` | | `CTRL-,` | Open Settings | `workspace:show_settings_modal` | | `CTRL-,` | Open Settings: Account | `workspace:show_settings_account_page` | | `F3` | Find the Next Occurrence of Your Search Query | `find:find_next_occurrence` | | `CTRL-SHIFT-P` | Toggle Command Palette | `workspace:toggle_command_palette` | | | Toggle Mouse Reporting | `workspace:toggle_mouse_reporting` | | `CTRL-SHIFT-[` | Activate Previous Pane | `pane_group:navigate_prev` | | `CTRL-SHIFT-]` | Activate Next Pane | `pane_group:navigate_next` | | | Resize Pane > Move Divider Down | `pane_group:resize_down` | | `CTRL-CMD-K` | Open Keybindings Editor | `workspace:show_keybinding_settings` | | | Resize Pane > Move Divider Left | `pane_group:resize_left` | | | Resize Pane > Move Divider Right | `pane_group:resize_right` | | | Resize Pane > Move Divider Up | `pane_group:resize_up` | | `CTRL-SHIFT-/` | Open Resource Center | `workspace:toggle_resource_center` | | `CTRL-SHIFT-E` | Split Pane Down | `pane_group:add_down` | | `CTRL-SHIFT-ENTER` | Toggle Maximize Active Pane | `pane_group:toggle_maximize_pane` | | `SHIFT-F3` | Find the Previous Occurrence of Your Search Query | `find:find_prev_occurrence` | | | Toggle Navigation Palette | `workspace:toggle_navigation_palette` | **Fundamentals** | Shortcut | Command | Action | | ------------------ | -------------------------- | -------------------------------- | | `CTRL--` | Decrease Font Size | `workspace:decrease_font_size` | | `CTRL-0` | Reset Font Size to Default | `workspace:reset_font_size` | | `CTRL-1` | Switch to 1st Tab | `workspace:activate_first_tab` | | `CTRL-2` | Switch to 2nd Tab | `workspace:activate_second_tab` | | `CTRL-3` | Switch to 3rd Tab | `workspace:activate_third_tab` | | `CTRL-4` | Switch to 4th Tab | `workspace:activate_fourth_tab` | | `CTRL-5` | Switch to 5th Tab | `workspace:activate_fifth_tab` | | `CTRL-6` | Switch to 6th Tab | `workspace:activate_sixth_tab` | | `CTRL-7` | Switch to 7th Tab | `workspace:activate_seventh_tab` | | `CTRL-8` | Switch to 8th Tab | `workspace:activate_eighth_tab` | | `CTRL-9` | Switch to Last Tab | `workspace:activate_last_tab` | | `CTRL-=` | Increase Font Size | `workspace:increase_font_size` | | `CTRL-SHIFT-C` | Copy | `terminal:copy` | | `CTRL-SHIFT-F` | Find | `terminal:find` | | `CTRL-SHIFT-V` | Paste | `terminal:paste` | | `CTRL-SHIFT-T` | Open New Tab | `workspace:open_new_tab` | | `CTRL-ALT-T` | Reopen Closed Tab | `workspace:reopen_closed_tab` | | `CTRL-SHIFT-LEFT` | Move Tab Left | `workspace:move_tab_left` | | `CTRL-SHIFT-RIGHT` | Move Tab Right | `workspace:move_tab_right` | | `CTRL-PAGEUP` | Activate Previous Tab | `workspace:activate_prev_tab` | | `CTRL-PAGEDOWN` | Activate Next Tab | `workspace:activate_next_tab` | # Migrate to Warp > Move your settings and mental model into Warp. Pick the tool you're coming from for step-by-step guidance and Warp equivalents. Warp users come from every kind of terminal, editor, and AI coding tool. This section has a dedicated page for each of the most common sources, with step-by-step migration guidance, notes on what transfers automatically, and a cross-reference for the Warp features that replace what you use today. Pick the tool you’re switching from: * [**Claude Code**](/getting-started/migrate-to-warp/migrate-to-warp-from-claude-code/) - use Claude Code inside Warp, or switch from Claude Code to Warp’s built-in Agent Mode. Covers context, rules, and model setup. * [**Cursor**](/getting-started/migrate-to-warp/migrate-to-warp-from-cursor/) - use Warp alongside Cursor as your agent terminal, or replace Cursor entirely with Warp’s built-in code editor and Agent Mode. * [**Ghostty**](/getting-started/migrate-to-warp/migrate-to-warp-from-ghostty/) - translate your Ghostty config to Warp and find equivalents for quick terminal, tabs, and GPU rendering. * [**iTerm2**](/getting-started/migrate-to-warp/migrate-to-warp-from-iterm2/) - use Warp’s built-in iTerm2 importer to transfer themes, fonts, keybindings, and hotkey windows in a few clicks. * [**macOS Terminal**](/getting-started/migrate-to-warp/migrate-to-warp-from-macos-terminal/) - match your Terminal.app setup and discover the split panes, tabs, and Agent Mode features Terminal.app lacks. * [**VS Code terminal**](/getting-started/migrate-to-warp/migrate-to-warp-from-vs-code-terminal/) - use Warp alongside VS Code for a richer terminal, or replace VS Code entirely with Warp’s built-in code editor. * [**Windows Terminal**](/getting-started/migrate-to-warp/migrate-to-warp-from-windows-terminal/) - map Windows Terminal profiles, PowerShell settings, and color schemes into Warp on Windows. ## Coming from something else? [Section titled “Coming from something else?”](#coming-from-something-else) Warp works well for developers migrating from many other sources. If you’re switching from a tool that isn’t listed above - for example, Alacritty, WezTerm, Kitty, Hyper, or a Linux default like GNOME Terminal or Konsole - drop a note in our [Discord community](https://discord.gg/warpdotdev) so we can prioritize coverage. # Migrate to Warp from Claude Code > Keep using Claude Code in Warp — with rich input, code review, and notifications — or switch from Claude Code to Warp's Agent Mode as your primary coding agent. Claude Code is different from the other sources in this section: it’s not a terminal emulator, it’s a CLI agent that runs inside any terminal. Warp is an agentic development environment with a built-in [code editor](/code/code-editor/), [Code Review](/code/code-review/), [team collaboration](/knowledge-and-collaboration/warp-drive/), and [MCP](/agent-platform/capabilities/mcp/) support — so you have two paths to choose from: * **[Using Claude Code inside Warp](#using-claude-code-inside-warp)** - you want to keep using Claude Code as your coding agent and run it in Warp’s terminal. * **[Switching to Agent Mode from Claude Code](#switching-to-agent-mode-from-claude-code)** - you want to replace Claude Code with Warp’s built-in [Agent Mode](/agent-platform/local-agents/overview/). ## Using Claude Code inside Warp [Section titled “Using Claude Code inside Warp”](#using-claude-code-inside-warp) Warp provides first-class support for Claude Code through its [third-party CLI agents](/agent-platform/cli-agents/overview/) integration. Open a new tab and run: ```bash claude ``` Warp auto-detects Claude Code and unlocks IDE-level features on top of the TUI: * **[Rich input editor](/agent-platform/cli-agents/rich-input/)** (`Ctrl+G`) - compose multi-line prompts with `@` mentions, voice input, and slash commands. * **[Agent notifications](/agent-platform/capabilities/agent-notifications/)** - in-app and desktop alerts when Claude Code needs your input. Requires a one-time plugin install (Warp prompts you). * **Inline code review** - send review comments directly to the agent from Warp’s [Code Review](/code/code-review/) panel. * **[Vertical tabs with agent metadata](/terminal/windows/vertical-tabs/)** - track multiple Claude Code sessions across tabs with status indicators. * **[Remote control](/agent-platform/cli-agents/remote-control/)** - share or steer a Claude Code session from another device. * **[Tab Configs](/terminal/windows/tab-configs/)** - save and reopen Claude Code session layouts. For full setup steps (notification plugin, productivity tips, troubleshooting), see [Claude Code in Warp](/agent-platform/cli-agents/claude-code/) and the [How to set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) guide. ### Tips [Section titled “Tips”](#tips) * **Run Claude Code in [terminal mode](/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes/)**, not Agent Mode. Press `⌘+I` (macOS) or `Ctrl+I` (Linux/Windows) to toggle modes if you’re in Agent Mode by accident. * **`Shift+Enter` for newlines.** Use `Shift+Enter` to insert a newline in Claude Code’s prompt. If it submits the message instead, check that you’re in terminal mode (not Agent Mode) and that you’re on a recent Warp version. * **Copy/paste handling.** Warp enables bracketed paste by default, so multi-line pastes into Claude Code work without extra configuration. * **Resuming after a Warp restart.** Warp’s [session restoration](/terminal/sessions/session-restoration/) preserves tabs and panes, but not running CLI processes — closing Warp ends Claude Code’s session. Use Claude Code’s built-in resume options (e.g., `claude --resume`) to continue a conversation after reopening Warp. ### API keys and authentication [Section titled “API keys and authentication”](#api-keys-and-authentication) Claude Code’s authentication (API key or Anthropic account) is handled by Claude Code itself, not Warp. Warp does not proxy or modify Claude Code’s network calls. Configure your `ANTHROPIC_API_KEY` environment variable via [Warp Drive environment variables](/knowledge-and-collaboration/warp-drive/environment-variables/) to share it across sessions without committing it to shell config files. ## Switching to Agent Mode from Claude Code [Section titled “Switching to Agent Mode from Claude Code”](#switching-to-agent-mode-from-claude-code) If you’re ready to replace Claude Code with Warp’s built-in agent, the core workflow is: 1. Open a new tab in Warp. 2. To switch to switch to [Agent Mode](/agent-platform/local-agents/overview/) from terminal mode, press `⌘+Enter` (or `Ctrl+Shift+Enter`) 3. Describe what you want in natural language. Warp’s agent reads your codebase, runs commands, and edits files the same way Claude Code does. ### What transfers: context and rules [Section titled “What transfers: context and rules”](#what-transfers-context-and-rules) A recurring question from Claude Code users: **what files and context does Warp’s agent read automatically?** Warp picks up project rules from an `AGENTS.md` (or `WARP.md`) at your repo root — the direct equivalent of Claude Code’s `CLAUDE.md`. Run `/init` in Agent Mode to generate one, or rename your existing rules file and you’re done — no rewriting needed. Warp’s agent also pulls context from several other explicit sources: * **[Codebase Context](/agent-platform/capabilities/codebase-context/)** - when you open a directory, Warp indexes your Git-tracked files so the agent can search and reference your code without you pasting snippets. * **[Rules](/agent-platform/capabilities/rules/)** - global and project-scoped rules. `AGENTS.md` and `WARP.md` are automatically picked up at the project root; additional rules live in Warp Drive. * **[Warp Drive](/knowledge-and-collaboration/warp-drive/)** - notebooks, workflows, and environment variables you’ve saved are available to the agent as context. * **[Agent Mode context](/knowledge-and-collaboration/warp-drive/agent-mode-context/)** - pin specific files or notebooks to a conversation so the agent always has them in scope. * **[MCP](/agent-platform/capabilities/mcp/)** - any MCP servers you’ve configured give the agent access to external tools and data. ### What to reconfigure [Section titled “What to reconfigure”](#what-to-reconfigure) * **Bring over your `CLAUDE.md`.** Rename it to `AGENTS.md` (or copy it into a Warp [Rule](/agent-platform/capabilities/rules/) if you want it scoped beyond the repo). Warp applies it automatically to new conversations. * **Set up [MCP servers](/agent-platform/capabilities/mcp/)** you relied on in Claude Code. * **Pick a model** per conversation using the model selector. See [model choice](/agent-platform/capabilities/model-choice/). Warp supports Claude, GPT, Gemini, and Auto. * **Configure [agent profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/)** for what the agent can auto-execute. ### Key differences from Claude Code [Section titled “Key differences from Claude Code”](#key-differences-from-claude-code) * **Tight terminal integration.** Agent Mode runs inside Warp and sees the full state of your terminal session — open files, command history, environment variables — without needing you to paste context. * **Parallel agents.** Warp runs multiple agent conversations across tabs simultaneously, each with its own state, which you can track in the Agent Management Panel. * **Code Review built in.** Agent-generated diffs open in Warp’s [Code Review](/code/code-review/) panel, not the terminal. * **Cloud orchestration.** Long-running or scheduled agent work can be offloaded to [Oz](/agent-platform/cloud-agents/overview/). ## Warp-native equivalents [Section titled “Warp-native equivalents”](#warp-native-equivalents) Claude Code concepts and their closest Warp analog: | From Claude Code | In Warp | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CLAUDE.md` | `AGENTS.md` (or `WARP.md`) at the project root, picked up as a [Rule](/agent-platform/capabilities/rules/) | | Claude Code slash commands | Warp’s own [slash commands](/agent-platform/capabilities/slash-commands/) (`/init`, `/plan`, `/model`, etc.); save your own as [Warp Drive prompts](/knowledge-and-collaboration/warp-drive/prompts/) | | Tool definitions | [MCP](/agent-platform/capabilities/mcp/) | | Resume conversation | Warp persists agent conversations per tab; pair with [tab configs](/terminal/windows/tab-configs/) to reopen the same project layout | For a deeper tour of Agent Mode, see [Coding in Warp](/getting-started/quickstart/coding-in-warp/) and the [Warp Agents docs](/agent-platform/local-agents/overview/). # Migrate to Warp from Cursor > Reconfigure your terminal and agent settings when switching to Warp from Cursor, or run Warp alongside Cursor as your agent terminal. Warp gives Cursor users two clean migration paths: keep Cursor as your editor and use Warp for terminal and agent work, or move fully to Warp’s built-in code editor and Agent Mode. This page walks through both options. ## What transfers automatically [Section titled “What transfers automatically”](#what-transfers-automatically) Warp doesn’t ship a Cursor importer. Cursor is built on the VS Code codebase, so its terminal settings live in `settings.json` under keys like `terminal.integrated.fontFamily` and `terminal.integrated.defaultProfile.*`. Open your user settings with **Command Palette** > **Preferences: Open User Settings (JSON)** to reference them while you reconfigure Warp. ## Use Warp’s agent to migrate your settings (recommended) [Section titled “Use Warp’s agent to migrate your settings (recommended)”](#use-warps-agent-to-migrate-your-settings-recommended) The fastest way to bring over your Cursor terminal setup is to ask Warp’s agent to translate your `settings.json` directly. Warp ships a [`settings.toml` file](/terminal/settings/) and a bundled `modify-settings` skill that lets the agent read your existing config and write equivalent values into Warp’s settings. 1. In Warp, open a new tab and switch to [Agent Mode](/agent-platform/local-agents/overview/) with `⌘+I` (macOS) or `Ctrl+I` (Linux/Windows). 2. Paste a prompt like: > Read my Cursor `settings.json` (`~/Library/Application Support/Cursor/User/settings.json` on macOS) and port the equivalent terminal settings (font, cursor style, default profile) into my Warp `settings.toml` using the `modify-settings` skill. Show me a diff before applying. 3. Review the proposed diff and approve. Warp hot-reloads `settings.toml`, so changes take effect immediately. If you’d rather configure each setting manually through the Settings UI, the steps below cover the most common cases. ## What to reconfigure manually [Section titled “What to reconfigure manually”](#what-to-reconfigure-manually) ### Terminal settings [Section titled “Terminal settings”](#terminal-settings) Terminal settings in Cursor follow the same schema as VS Code. The migration steps are identical to the VS Code terminal migration - see [Migrate to Warp from VS Code terminal](/getting-started/migrate-to-warp/migrate-to-warp-from-vs-code-terminal/) for step-by-step guidance on shell, font, theme, and keybinding setup. ### Agent and AI settings [Section titled “Agent and AI settings”](#agent-and-ai-settings) Cursor’s Composer and Agent features don’t have a one-to-one migration path - they map to different Warp concepts. * **Composer / Agent** in Cursor maps to Warp’s [Agent Mode](/agent-platform/local-agents/overview/). Start an agent conversation in any tab. * **Rules files** (`.cursorrules`) - Warp uses [Rules](/agent-platform/capabilities/rules/) stored in Warp Drive or committed to your repo as `AGENTS.md` (or `WARP.md`). Run `/init` in Agent Mode to generate an `AGENTS.md`, or copy your `.cursorrules` content directly. * **MCP servers** - Warp supports MCP natively. See [MCP](/agent-platform/capabilities/mcp/) for configuration. ### Model choice [Section titled “Model choice”](#model-choice) Cursor lets you pick a model per conversation. Warp does the same - use the model selector in any agent conversation. See [model choice](/agent-platform/capabilities/model-choice/). ### Keybindings [Section titled “Keybindings”](#keybindings) Warp’s [keyboard shortcuts](/getting-started/keyboard-shortcuts/) differ from Cursor’s. Most notably, `⌘+I` (or `Ctrl+I` on Linux/Windows) toggles between terminal and Agent Mode. From terminal mode you can also press `⌘+Enter` (or `Ctrl+Shift+Enter`) as an alternate shortcut into Agent Mode. ## Choosing your setup [Section titled “Choosing your setup”](#choosing-your-setup) ### Use Warp alongside Cursor [Section titled “Use Warp alongside Cursor”](#use-warp-alongside-cursor) Keep Cursor as your editor for tight in-file AI assistance, and use Warp as the terminal you switch to for: * Long-running commands and SSH. * [Agent Mode](/agent-platform/local-agents/overview/) conversations that execute commands, not just edit files. * [Code Review](/code/code-review/) for managing diffs. * [Warp Drive](/knowledge-and-collaboration/warp-drive/) for team knowledge. ### Replace Cursor with Warp [Section titled “Replace Cursor with Warp”](#replace-cursor-with-warp) Warp’s built-in [code editor](/code/code-editor/) supports Language Server Protocol, a [file tree](/code/code-editor/file-tree/), [find and replace](/code/code-editor/find-and-replace/), and [Vim keybindings](/code/code-editor/code-editor-vim-keybindings/). Combined with Agent Mode, Code Review, and Warp Drive, the full Cursor workflow is reachable in Warp without a separate editor. ## Warp-native equivalents [Section titled “Warp-native equivalents”](#warp-native-equivalents) Cursor features and their Warp counterparts: | From Cursor | In Warp | | ----------------------------- | ------------------------------------------------------------------------------------------------------- | | Composer / Agent panel | [Agent Mode](/agent-platform/local-agents/overview/) in any tab (toggle with `⌘+I`) | | Agent tabs | Multiple [agents in parallel](/agent-platform/local-agents/overview/) across tabs | | `.cursorrules` | `AGENTS.md` / `WARP.md` at the project root, picked up as a [Rule](/agent-platform/capabilities/rules/) | | MCP servers | [MCP](/agent-platform/capabilities/mcp/) | | Model choice per conversation | [Model selector](/agent-platform/capabilities/model-choice/) | | Codebase indexing | [Codebase Context](/agent-platform/capabilities/codebase-context/) | | Inline diff review | [Code Review](/code/code-review/) | See [Coding in Warp](/getting-started/quickstart/coding-in-warp/) for a tour of the development workflow. # Migrate to Warp from Ghostty > Moving to Warp from Ghostty? Here's how to bring over your themes, fonts, and keybindings, plus where to find Warp's equivalents for Ghostty's native features. Warp gives Ghostty users a fast path to bring over themes, fonts, and keybindings — plus native equivalents for the Ghostty features you rely on, from the quick terminal to native tabs and splits. ## What transfers automatically [Section titled “What transfers automatically”](#what-transfers-automatically) Warp doesn’t ship a Ghostty importer, but it can do most of the work for you agentically. Ghostty stores its configuration in a plain-text key-value file at `~/.config/ghostty/config`. ## Use Warp’s agent to migrate your settings (recommended) [Section titled “Use Warp’s agent to migrate your settings (recommended)”](#use-warps-agent-to-migrate-your-settings-recommended) The fastest way to bring over your Ghostty setup is to ask Warp’s agent to translate your config directly. Warp ships a [`settings.toml` file](/terminal/settings/) and a bundled `modify-settings` skill that lets the agent read your existing config and write equivalent values into Warp’s settings, including translating your Ghostty theme into a Warp [custom theme](/terminal/appearance/custom-themes/). 1. In Warp, open a new tab and switch to [Agent Mode](/agent-platform/local-agents/overview/) with `⌘+I` (macOS) or `Ctrl+I` (Linux/Windows). 2. Paste a prompt like: > Read my Ghostty config at `~/.config/ghostty/config` and any referenced theme files in `~/.config/ghostty/themes/`. Port the equivalent settings (theme, font, keybindings, shell) into my Warp `settings.toml` using the `modify-settings` skill, and create a matching custom theme. Show me a diff before applying. 3. Review the proposed diff and approve. Warp hot-reloads `settings.toml`, so changes take effect immediately. If you’d rather configure each setting manually through the Settings UI, the steps below cover the most common cases. ## What to reconfigure manually [Section titled “What to reconfigure manually”](#what-to-reconfigure-manually) ### Theme and colors [Section titled “Theme and colors”](#theme-and-colors) 1. Open **Settings** > **Appearance** > **Themes** in Warp. 2. Pick a built-in theme that matches your Ghostty setup, or [create a custom theme](/terminal/appearance/custom-themes/) by translating your Ghostty colors into a YAML theme file. 3. Ghostty’s theme files live in `~/.config/ghostty/themes/`. Open the file named in your Ghostty `theme` setting to copy the foreground, background, and 16 ANSI color values. ### Font and text [Section titled “Font and text”](#font-and-text) 1. In **Settings** > **Appearance** > **Text, fonts, & cursor**, match your Ghostty `font-family` and `font-size` values. 2. If you use font ligatures, ensure **Ligatures** is enabled. ### Keybindings [Section titled “Keybindings”](#keybindings) Warp’s [default keyboard shortcuts](/getting-started/keyboard-shortcuts/) cover most Ghostty bindings. For custom bindings from your Ghostty `keybind` lines, open **Settings** > **Keyboard shortcuts** and add them manually. ### Shell and prompt [Section titled “Shell and prompt”](#shell-and-prompt) Warp detects your login shell automatically. To override it, go to **Settings** > **Features** > **Session** and pick a shell from **Startup shell for new sessions**. For prompts, choose between Warp’s [native prompt](/terminal/appearance/prompt/#warp-prompt) (drag-and-drop context chips) or the [shell prompt (PS1)](/terminal/appearance/prompt/#custom-prompt) if you want to keep your existing prompt configuration. ### Quick terminal (Quake mode) [Section titled “Quick terminal (Quake mode)”](#quick-terminal-quake-mode) Configure Warp’s equivalent via **Settings** > **Features** > **Window** > **Global hotkey**. See [global hotkey](/terminal/windows/global-hotkey/) for the full configuration. ## Warp-native equivalents [Section titled “Warp-native equivalents”](#warp-native-equivalents) Features Ghostty users commonly miss, and where they live in Warp: | From Ghostty | In Warp | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | Quick terminal / dropdown window | [Global hotkey](/terminal/windows/global-hotkey/) | | Native tabs and splits | [Tabs](/terminal/windows/tabs/), [vertical tabs](/terminal/windows/vertical-tabs/), [split panes](/terminal/windows/split-panes/) | | Command palette | [Command Palette](/terminal/command-palette/) (`⌘+P` on macOS, `Ctrl+Shift+P` on Linux) | | GPU-accelerated rendering | GPU-rendered natively on all supported platforms | | Kitty graphics protocol | Image rendering for most common workflows (see [more features](/terminal/more-features/)) | | Shaders and custom visual effects | Not supported; closest: [size, opacity, and blurring](/terminal/appearance/size-opacity-blurring/) + [pane dimming](/terminal/appearance/pane-dimming/) | Beyond parity, Warp adds [Agent Mode](/agent-platform/local-agents/overview/), [Code Review](/code/code-review/), and [Warp Drive](/knowledge-and-collaboration/warp-drive/) for AI-assisted development and team collaboration. For more on what you can configure, see [Customizing Warp](/getting-started/quickstart/customizing-warp/). # Migrate to Warp from iTerm2 > Import your iTerm2 profile into Warp to transfer themes, fonts, keybindings, hotkey windows, and more in a few clicks. Warp imports your iTerm2 profile automatically, bringing over theme, font, keybindings, hotkey window, and more in a few clicks. This page walks through the importer, what it covers, and what to reconfigure manually after. ## What transfers automatically [Section titled “What transfers automatically”](#what-transfers-automatically) Warp ships a built-in iTerm2 importer that reads your default profile from `~/Library/Preferences/com.googlecode.iterm2.plist`. It imports: * **Theme** - foreground, background, cursor, and all 16 ANSI colors (light and dark variants if configured). * **Font** - family and size (when the font exists on your system and is supported by Warp). * **Default shell** - if you’ve set a custom Command in your iTerm2 profile. * **Working directory behavior** - Warp translates iTerm2’s “Reuse previous session’s directory” and similar options. * **Window dimensions** - rows and columns. * **Opacity and blur.** * **Copy-on-select, mouse and scroll reporting, and Option-as-Meta settings.** * **Global hotkey** - if you use a hotkey window or hotkey activation, Warp maps it. To run the importer: 1. In Warp, open the [Command Palette](/terminal/command-palette/). 2. Search for **Import External Settings**. 3. Select **iTerm2 Profile: Default**. Warp only imports the profile marked as your Default Bookmark in iTerm2. 4. Choose which settings to keep or skip on the preview screen. ![Select a settings profile to import](/_astro/migrate-to-warp.KuxN2T8c_bmeMj.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Select a settings profile to import. ## Use Warp’s agent for follow-up settings [Section titled “Use Warp’s agent for follow-up settings”](#use-warps-agent-for-follow-up-settings) If the importer doesn’t pick up something you care about — a non-default profile, an unusual keybinding, a specific setting — ask Warp’s agent to translate it directly. Warp ships a [`settings.toml` file](/terminal/settings/) and a bundled `modify-settings` skill that lets the agent read your iTerm2 plist and write equivalent values into Warp’s settings. 1. In Warp, switch to [Agent Mode](/agent-platform/local-agents/overview/) with `⌘+I`. 2. Paste a prompt like: > Read my iTerm2 preferences with `defaults read com.googlecode.iterm2` and port any settings that the importer didn’t cover (extra profiles, custom keybindings) into my Warp `settings.toml` using the `modify-settings` skill. Show me a diff before applying. 3. Review the proposed diff and approve. Warp hot-reloads `settings.toml`. ## What to reconfigure manually [Section titled “What to reconfigure manually”](#what-to-reconfigure-manually) A few iTerm2 features don’t map directly and need a manual pass after import: * **Multiple profiles.** Warp imports only your Default profile. If you rely on multiple iTerm2 profiles, create equivalent [tab configs](/terminal/windows/tab-configs/) in Warp. * **Keyboard shortcuts.** Warp’s [keyboard shortcuts](/getting-started/keyboard-shortcuts/) cover most iTerm2 bindings out of the box, but custom bindings need to be recreated in **Settings** > **Keyboard shortcuts**. * **Split panes and arrangements.** Rebuild using [split panes](/terminal/windows/split-panes/) and [tab configs](/terminal/windows/tab-configs/). * **Triggers.** Warp doesn’t have a direct equivalent. Reach similar outcomes through [YAML workflows](/terminal/entry/yaml-workflows/) or Agent Mode. ### Choose your prompt [Section titled “Choose your prompt”](#choose-your-prompt) After the import, choose which [prompt](/terminal/appearance/prompt/) to use: 1. [**Warp prompt**](/terminal/appearance/prompt/#warp-prompt) - Warp’s native prompt with drag-and-drop context chips for git branch, directory, timestamps, and more. Configure in **Settings** > **Appearance** > **Prompt**. 2. [**Shell prompt (PS1)**](/terminal/appearance/prompt/#custom-prompt) - inherits your existing shell prompt configuration unchanged. Pick this if you want Warp to match your iTerm2 prompt exactly. ## Warp-native equivalents [Section titled “Warp-native equivalents”](#warp-native-equivalents) Features switchers commonly look for after leaving iTerm2, and where they live in Warp: | From iTerm2 | In Warp | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Hotkey window (Quake mode) | [Global hotkey](/terminal/windows/global-hotkey/) (imported automatically when detected in your iTerm2 profile) | | Triggers | [YAML workflows](/terminal/entry/yaml-workflows/) for repeatable actions; Agent Mode for pattern-based automation | | Profiles | [Tab configs](/terminal/windows/tab-configs/) for layouts; [Warp Drive](/knowledge-and-collaboration/warp-drive/) for shared team setups | | Autocomplete menu | [Autosuggestions](/terminal/command-completions/autosuggestions/) + [tab completions](/terminal/command-completions/completions/) | | Instant replay | [Session restoration](/terminal/sessions/session-restoration/) | | Password manager integration | [Warp Drive environment variables](/knowledge-and-collaboration/warp-drive/environment-variables/) | For more on what you can configure after migrating, see the [Warp quickstart](/quickstart/) and [Customizing Warp](/getting-started/quickstart/customizing-warp/). # Migrate to Warp from macOS Terminal > Switch from the default macOS Terminal app to Warp. Match your setup and discover what Warp adds beyond the basics. Warp gives Terminal.app users everything they already have — shell, theme, font, prompt — plus split panes, tabs, blocks, and Agent Mode for an AI-assisted workflow. This page walks through both an agent-driven migration and the manual GUI steps. ## What transfers automatically [Section titled “What transfers automatically”](#what-transfers-automatically) Warp doesn’t ship a Terminal.app importer, but it can do most of the work for you agentically. Most Terminal.app users run near-default settings, so the migration usually takes only a few minutes either way. ## Use Warp’s agent to migrate your settings (recommended) [Section titled “Use Warp’s agent to migrate your settings (recommended)”](#use-warps-agent-to-migrate-your-settings-recommended) The fastest way to bring over a Terminal.app theme is to ask Warp’s agent to translate it directly. Warp ships a [`settings.toml` file](/terminal/settings/) and a bundled `modify-settings` skill that lets the agent read your Terminal.app preferences and write equivalent values into Warp’s settings, including creating a matching [custom theme](/terminal/appearance/custom-themes/). 1. In Warp, open a new tab and switch to [Agent Mode](/agent-platform/local-agents/overview/) with `⌘+I`. 2. Paste a prompt like: > Read my Terminal.app preferences with `defaults read com.apple.Terminal` and port the active profile (theme, font, window size) into my Warp `settings.toml` using the `modify-settings` skill. Create a matching custom theme. Show me a diff before applying. 3. Review the proposed diff and approve. Warp hot-reloads `settings.toml`. If you’d rather configure each setting manually through the Settings UI, the steps below cover the most common cases. ## What to reconfigure manually [Section titled “What to reconfigure manually”](#what-to-reconfigure-manually) ### Shell [Section titled “Shell”](#shell) Warp auto-detects your login shell on first launch. macOS has shipped with `zsh` as the default since Catalina (2019); if you changed your shell with `chsh`, Warp picks that up too. To change it later, go to **Settings** > **Features** > **Session** and pick a shell from **Startup shell for new sessions**. ### Theme and colors [Section titled “Theme and colors”](#theme-and-colors) Terminal.app ships with a handful of profiles (Basic, Pro, Homebrew, Ocean, etc.). Match them in Warp: 1. Open **Settings** > **Appearance** > **Themes**. 2. Pick a preset theme. Warp’s built-in library includes many themes similar to Terminal.app’s defaults. 3. For exact color matches, [create a custom theme](/terminal/appearance/custom-themes/) using the ANSI color values you can inspect in Terminal.app’s **Settings** > **Profiles** > **Text** tab. ### Font [Section titled “Font”](#font) 1. In **Settings** > **Appearance** > **Text, fonts, & cursor**, pick your font family and size to match what you use in Terminal.app. ### Window size and transparency [Section titled “Window size and transparency”](#window-size-and-transparency) Configure in **Settings** > **Appearance** > **Size, opacity, & blurring**. See [size, opacity, and blurring](/terminal/appearance/size-opacity-blurring/). ### Prompt [Section titled “Prompt”](#prompt) Terminal.app uses whatever prompt your shell’s PS1 (or zsh’s PROMPT) defines. In Warp, choose: 1. [**Warp prompt**](/terminal/appearance/prompt/#warp-prompt) - Warp’s native prompt with drag-and-drop chips for git branch, directory, and more. 2. [**Shell prompt (PS1)**](/terminal/appearance/prompt/#custom-prompt) - keeps your existing shell prompt exactly as it appears in Terminal.app. Configure in **Settings** > **Appearance** > **Prompt**. ## Warp-native equivalents [Section titled “Warp-native equivalents”](#warp-native-equivalents) Most Terminal.app features have a Warp equivalent with additional capabilities on top: | From Terminal.app | In Warp | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Profiles | [Tab configs](/terminal/windows/tab-configs/) for layouts and startup commands; [themes](/terminal/appearance/themes/) for appearance (Warp has no single profile object) | | Window groups / arrangements | [Tab configs](/terminal/windows/tab-configs/) | | Tabs | [Tabs](/terminal/windows/tabs/), [vertical tabs](/terminal/windows/vertical-tabs/) | | Split panes | [Split panes](/terminal/windows/split-panes/) (Terminal.app doesn’t support) | | Copy-on-select | **Settings** > **Features** > **Session** | | Inspector | [Command inspector](/terminal/editor/command-inspector/) (exit code, duration, working directory) | Beyond matching Terminal.app, Warp adds [Agent Mode](/agent-platform/local-agents/overview/) for natural-language commands, [blocks](/terminal/blocks/) for structured command output, and [Warp Drive](/knowledge-and-collaboration/warp-drive/) for shared workflows. New to Warp? Start with the [Warp quickstart](/quickstart/). # Migrate to Warp from VS Code terminal > Replicate your VS Code integrated terminal setup in Warp - shell, fonts, keybindings - or run Warp alongside VS Code as a richer terminal. Warp lets VS Code users choose their own path: keep VS Code for editing and run Warp as the terminal alongside it, or replace both with Warp’s built-in code editor. This page walks through reconfiguring your terminal settings for either path. ## What transfers automatically [Section titled “What transfers automatically”](#what-transfers-automatically) Warp doesn’t ship a VS Code importer — it’s a standalone application, not a VS Code extension — but it can do most of the work for you agentically. Your VS Code terminal settings live in your user `settings.json` under keys like: ```json "terminal.integrated.defaultProfile.osx": "zsh", "terminal.integrated.fontFamily": "MesloLGS NF", "terminal.integrated.fontSize": 14, "terminal.integrated.cursorStyle": "line", "terminal.integrated.profiles.osx": { ... } ``` ## Use Warp’s agent to migrate your settings (recommended) [Section titled “Use Warp’s agent to migrate your settings (recommended)”](#use-warps-agent-to-migrate-your-settings-recommended) The fastest way to bring over your VS Code terminal setup is to ask Warp’s agent to translate `settings.json` directly. Warp ships a [`settings.toml` file](/terminal/settings/) and a bundled `modify-settings` skill that lets the agent read your existing config and write equivalent values into Warp’s settings. 1. In Warp, open a new tab and switch to [Agent Mode](/agent-platform/local-agents/overview/) with `⌘+I` (macOS) or `Ctrl+I` (Linux/Windows). 2. Paste a prompt like: > Read my VS Code `settings.json` (`~/Library/Application Support/Code/User/settings.json` on macOS) and port the equivalent terminal settings (`terminal.integrated.*` keys) into my Warp `settings.toml` using the `modify-settings` skill. Show me a diff before applying. 3. Review the proposed diff and approve. Warp hot-reloads `settings.toml`. If you’d rather configure each setting manually through the Settings UI, the steps below cover the most common cases. ## What to reconfigure manually [Section titled “What to reconfigure manually”](#what-to-reconfigure-manually) ### Shell [Section titled “Shell”](#shell) Warp auto-detects your login shell. To override - for example, to match `terminal.integrated.defaultProfile.*` - go to **Settings** > **Features** > **Session** and pick a shell from **Startup shell for new sessions**. ### Font and cursor [Section titled “Font and cursor”](#font-and-cursor) In Warp’s **Settings** > **Appearance** > **Text, fonts, & cursor**, set the font family and size to match `terminal.integrated.fontFamily` and `terminal.integrated.fontSize`. ### Theme [Section titled “Theme”](#theme) VS Code’s terminal uses the color scheme from your overall editor theme. In Warp, pick a comparable theme from **Settings** > **Appearance** > **Themes**, or [create a custom theme](/terminal/appearance/custom-themes/) that matches your VS Code theme’s `terminal.*` color tokens. ### Keybindings [Section titled “Keybindings”](#keybindings) Warp’s [default keyboard shortcuts](/getting-started/keyboard-shortcuts/) are largely consistent with VS Code terminal shortcuts (splits, new tab, find). For any custom bindings you configured in VS Code, add them in Warp’s **Settings** > **Keyboard shortcuts**. ## Choosing your setup [Section titled “Choosing your setup”](#choosing-your-setup) ### Use Warp alongside VS Code [Section titled “Use Warp alongside VS Code”](#use-warp-alongside-vs-code) Many developers keep VS Code as their editor and use Warp as the terminal they switch to for long-running commands, SSH sessions, or AI-assisted workflows. No changes to VS Code needed - just install Warp and open it when you want a richer terminal. VS Code’s integrated terminal still works; use it for quick one-off commands, and jump to Warp when you need [blocks](/terminal/blocks/), [Agent Mode](/agent-platform/local-agents/overview/), or [persistent sessions](/terminal/sessions/session-restoration/). ### Replace VS Code with Warp [Section titled “Replace VS Code with Warp”](#replace-vs-code-with-warp) Warp includes a built-in [code editor](/code/code-editor/) with Language Server Protocol (LSP) support, a [file tree](/code/code-editor/file-tree/), [find and replace](/code/code-editor/find-and-replace/), and [Vim keybindings](/code/code-editor/code-editor-vim-keybindings/). Combined with [Code Review](/code/code-review/), many developers use Warp as their primary editor and drop VS Code entirely. Open a directory with `warp .` from the command line to start editing. ## Warp-native equivalents [Section titled “Warp-native equivalents”](#warp-native-equivalents) VS Code terminal features and their Warp equivalents: | From VS Code terminal | In Warp | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | Split terminal | [Split panes](/terminal/windows/split-panes/) | | Multiple terminals (tab strip) | [Tabs](/terminal/windows/tabs/), [vertical tabs](/terminal/windows/vertical-tabs/) | | Tasks (`tasks.json`) | [YAML workflows](/terminal/entry/yaml-workflows/) or [tab configs](/terminal/windows/tab-configs/) | | Terminal profiles | [Tab configs](/terminal/windows/tab-configs/) + per-session shell overrides | | Shell integration | Built in via [Warpify](/terminal/warpify/); enables working-directory tracking and command-level [blocks](/terminal/blocks/) | For an overview of what Warp adds beyond a terminal, see [Coding in Warp](/getting-started/quickstart/coding-in-warp/). # Migrate to Warp from Windows Terminal > Switch from Windows Terminal to Warp on Windows. Reconfigure profiles, shells, fonts, keybindings, and find Warp equivalents. Warp on Windows covers everything you use Windows Terminal for today — profiles, PowerShell, color schemes, keybindings — with Agent Mode and blocks on top. This page walks through the migration. ## What transfers automatically [Section titled “What transfers automatically”](#what-transfers-automatically) Warp doesn’t ship a Windows Terminal importer, but it can do most of the work for you agentically. Windows Terminal stores its settings in a single JSON file at: ```powershell %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json ``` ## Use Warp’s agent to migrate your settings (recommended) [Section titled “Use Warp’s agent to migrate your settings (recommended)”](#use-warps-agent-to-migrate-your-settings-recommended) The fastest way to bring over your Windows Terminal setup is to ask Warp’s agent to translate `settings.json` directly. Warp ships a [`settings.toml` file](/terminal/settings/) and a bundled `modify-settings` skill that lets the agent read your existing config and write equivalent values into Warp’s settings, including translating your color schemes into a Warp [custom theme](/terminal/appearance/custom-themes/). 1. In Warp, open a new tab and switch to [Agent Mode](/agent-platform/local-agents/overview/) with `Ctrl+I`. 2. Paste a prompt like: > Read my Windows Terminal `settings.json` at `%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json` and port the active profile and color scheme into my Warp `settings.toml` using the `modify-settings` skill. Create a matching custom theme. Show me a diff before applying. 3. Review the proposed diff and approve. Warp hot-reloads `settings.toml`. If you’d rather configure each setting manually through the Settings UI, the steps below cover the most common cases. ## What to reconfigure manually [Section titled “What to reconfigure manually”](#what-to-reconfigure-manually) ### Default shell [Section titled “Default shell”](#default-shell) Warp on Windows supports PowerShell (`pwsh` and `powershell.exe`), Command Prompt (`cmd`), bash, zsh, and fish. Warp auto-detects your login shell; to override, go to **Settings** > **Features** > **Session** and pick a shell from **Startup shell for new sessions**. If you use PowerShell modules or a custom `$PROFILE`, Warp loads them the same way Windows Terminal does. ### Profiles [Section titled “Profiles”](#profiles) Windows Terminal uses profiles to group shell, theme, starting directory, and font together. Warp doesn’t have a single profile concept; instead, match each dimension separately: * **Shell** - **Settings** > **Features** > **Session**. * **Starting directory** - **Settings** > **Features** > **Session** > Working directory. * **Font family, size** - **Settings** > **Appearance** > **Text, fonts, & cursor**. * **Color scheme** - **Settings** > **Appearance** > **Themes**. Translate your Windows Terminal color scheme into a [custom Warp theme](/terminal/appearance/custom-themes/) using the same 16 ANSI color values. * **Reusable layouts** - create a [tab config](/terminal/windows/tab-configs/) for each workflow that used to be a profile. ### Color scheme [Section titled “Color scheme”](#color-scheme) Windows Terminal’s `schemes` array defines foreground, background, cursor, and ANSI colors. To match an existing scheme: 1. Copy the color values from the scheme you use in your `settings.json`. 2. Open **Settings** > **Appearance** > **Themes** in Warp and either pick a preset that matches or [create a custom theme](/terminal/appearance/custom-themes/). ### Keybindings [Section titled “Keybindings”](#keybindings) Warp’s [default keyboard shortcuts](/getting-started/keyboard-shortcuts/) cover most Windows Terminal bindings. For custom bindings from `settings.json`’s `actions` array, add them in **Settings** > **Keyboard shortcuts**. ### Prompt [Section titled “Prompt”](#prompt) If you use `oh-my-posh` or a custom PowerShell prompt, it continues to work in Warp. To choose between Warp’s native prompt and your existing shell prompt, go to **Settings** > **Appearance** > **Prompt**. See [prompt](/terminal/appearance/prompt/). ## Warp-native equivalents [Section titled “Warp-native equivalents”](#warp-native-equivalents) Features Windows Terminal users commonly look for in Warp: | From Windows Terminal | In Warp | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Profiles | [Tab configs](/terminal/windows/tab-configs/) + [themes](/terminal/appearance/themes/) + per-session shell settings | | Tabs and panes | [Tabs](/terminal/windows/tabs/), [vertical tabs](/terminal/windows/vertical-tabs/), [split panes](/terminal/windows/split-panes/) | | Command palette | [Command Palette](/terminal/command-palette/) (`Ctrl+Shift+P`) | | Oh My Posh prompts | Keep using them; pick [Shell prompt (PS1)](/terminal/appearance/prompt/#custom-prompt) in Warp | | Quake mode | [Global hotkey](/terminal/windows/global-hotkey/) | Beyond Windows Terminal’s feature set, Warp adds [Agent Mode](/agent-platform/local-agents/overview/), [blocks](/terminal/blocks/), and [Warp Drive](/knowledge-and-collaboration/warp-drive/). See [Warp for Windows installation](/getting-started/quickstart/installation-and-setup/) if you haven’t installed yet. # Coding in Warp > Agents can generate and edit code directly from within Warp. When you enter a Git repo for the first time, Warp will enter an initialization flow to index your codebase and generate an AGENTS.md file. As you’re in the repo, Warp will enter an advanced code generation flow that supports both single-line and multi-file changes when it detects an opportunity to write code. For example, Warp may write code when you prompt: * **Code creation**: “Write a function in JavaScript to debounce an input” * **Based on error outputs, suggest fixes**: “Fix this TypeScript error.” * **Edit a single file**: “Update all instances of ‘var’ to ‘let’ in this file.” * **Make batch changes**: “Add headers to all .py files in this directory” **The best way to experience this is to try it yourself —** [*open the Prompt below in Warp*](https://app.warp.dev/drive/prompt/Generate-a-custom-Warp-theme-K8oloLrCZAHuaYKfz2cNqI) ```text Detect the correct Warp themes directory based on the current operating system: - On macOS, use ~/.warp/themes/ - On Linux, use ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/themes/ - On Windows, use $env:APPDATA\warp\Warp\data\themes\ Create the directory if it doesn’t already exist. Then, generate a custom Warp theme named {{theme_name}} in valid YAML format, following the official structure from Warp’s documentation. Exclude the background_image field, and do not include any extra or missing fields. Save the theme as {{theme_name}}.yaml in the detected themes directory. Once the theme is created and verified, confirm completion by telling me where the theme file was saved. ``` *** ### Context [Section titled “Context”](#context) #### Codebase Context [Section titled “Codebase Context”](#codebase-context) Warp can index your Git-tracked codebases to help agents understand your code and generate accurate, context-aware responses. **No code is stored on Warp servers**. You can view and manage your indexed codebases in **Settings** > **Code** > **Indexing and projects** under “Initialized/ indexed folders”. You can also specify whether to automatically index new folders as you navigate them. If your codebase is large, you can exclude specific files by adding them to a `.warpindexingignore` file. #### Other types of context [Section titled “Other types of context”](#other-types-of-context) You can provide different types of input as context directly to the agent to guide its behavior and improve response quality. This includes: * [Blocks](/agent-platform/local-agents/agent-context/blocks-as-context/) from your terminal output * [Images](/agent-platform/local-agents/agent-context/images-as-context/) * [Files and code](/agent-platform/local-agents/agent-context/using-to-add-context/) (using the @ symbol) * [Public websites](/agent-platform/local-agents/agent-context/urls-as-context/) via URLs #### Warp Drive as Context [Section titled “Warp Drive as Context”](#warp-drive-as-context) Agents pull directly from your [**Warp Drive**](/knowledge-and-collaboration/warp-drive/) contents to generate more accurate responses — including your **Workflows**, **Notebooks**, **Prompts**, and **Environment Variables**. * When used, context appears under the “References” or “Derived from” section in the conversation. * This setting is **enabled by default** and can be managed via: **Settings** > **Agents** > **Knowledge** > **Warp Drive as Agent Mode Context**. #### Rules [Section titled “Rules”](#rules) **Rules** let you provide persistent context to Agents, enabling smarter and more personalized responses. You can create global rules (accessed through [Warp Drive](/knowledge-and-collaboration/warp-drive/) >**Personal** > **Rules**) or project scoped rules, defined in an `AGENTS.md` file. Note: the filename must be in all caps for Warp to recognize it. **Examples of Rules include:** * Coding standards and best practices * Project- or workspace-specific guidelines * Personal preferences for tools, formatting, or behavior How to access project-specific Rules 1. From the file-searcher, CMD+O and search “AGENTS.md” 2. From the file tree, click the “code” icon when in a repo How to access Global Rules 1. From the [Warp Drive](/knowledge-and-collaboration/warp-drive/) >**Personal** > **Rules** 2. From the [Command Palette](/terminal/command-palette/), search for “Open AI Rules” 3. From the Settings panel, **Settings** > **Agents** > **Knowledge** > **Manage Rules** 4. From the macOS Menu, `AI > Open Rules` # Customizing Warp > A complete guide to customizing Warp: themes, vertical tabs, tab configs, prompt chips, keybindings, AI models, and more. Warp is deeply customizable. Whether you use Warp primarily as a modern terminal or as an AI-powered development environment, you can tailor the experience to fit how you work. Configure the terminal side (themes, keybindings, vertical tabs, tab configs) and the AI side (model choice, agent autonomy, default mode) independently. Use the quick-reference table to find what you need, or browse the sections below for more details. If you want to go further than configuration, Warp’s client is open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE) — see [Contributing to Warp](/support-and-community/community/contributing/) to build a custom variant or contribute changes upstream. ## Quick reference [Section titled “Quick reference”](#quick-reference) | What to customize | Where to find it | Quick action | | ----------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------- | | Theme | **Settings** > **Appearance** | Pick a preset or [create a custom YAML theme](/terminal/appearance/custom-themes/) | | Prompt chips | Right-click prompt area > **Edit prompt** | Drag and drop context chips (directory, git branch, time, etc.) | | AI model | Model selector in agent conversation | Choose Claude, GPT, Gemini, or Auto | | Keybindings | **Settings** > **Keyboard shortcuts** | Import from another terminal or set custom shortcuts | | Vertical tabs | **Settings** > **Appearance** > **Tabs** | Switch to a sidebar tab layout for more horizontal space | | Tab configs | **Settings** > **Features** or `/` menu | Save and restore tab layouts with startup commands | | Settings file | **Open settings file** button in the Settings footer | Edit [`settings.toml`](/terminal/settings/) directly for version control and scripting | | Input format | **Settings** > **Appearance** > **Input** | Choose Standard or Classic | | App icon | **Settings** > **Appearance** > **Icon** | Pick a custom icon (macOS) | | Font & text | **Settings** > **Appearance** > **Text** | Change font, size, and cursor style | | Agent autonomy | **Settings** > **Agents** > **Profiles** | Set what the agent can do without asking | | Default mode | **Settings** > **Agents** > **Warp Agent** > **Input** | Choose whether new tabs open in terminal mode or Agent Mode | *** ## Appearance [Section titled “Appearance”](#appearance) In Warp, navigate to **Settings** > **Appearance** to access these options and control how Warp looks: * **[Themes](/terminal/appearance/themes/)** - Choose from pre-loaded themes or create your own [custom theme](/terminal/appearance/custom-themes/) using YAML or a background image. * **[Prompt chips](/terminal/appearance/prompt/)** - Customize the context chips in your Warp prompt. Right-click the prompt area and select **Edit prompt** to drag and drop chips like directory, git branch, Kubernetes context, and time. * **[App icons](/terminal/appearance/app-icons/)** - Choose a custom app icon to distinguish Warp in your dock (macOS). * **[Text, fonts, and cursor](/terminal/appearance/text-fonts-cursor/)** - Change your font type, size, and cursor style. * **[Input position](/terminal/appearance/input-position/)** - Move your prompt and command line to the top or bottom of the window. * **[Size, opacity, and blurring](/terminal/appearance/size-opacity-blurring/)** - Adjust window transparency and blur effects. * **[Pane dimming](/terminal/appearance/pane-dimming/)** - Dim inactive panes to focus on the active one. ## Layout [Section titled “Layout”](#layout) Organize your workspace with tabs, panes, and window configurations. * **[Vertical tabs](/terminal/windows/vertical-tabs/)** - Switch to a vertical sidebar layout for tabs, giving you more horizontal space and better visibility when you have many open sessions. * **[Tabs](/terminal/windows/tabs/)** - Organize sessions into tabs with custom titles and colors. Right-click a tab to pick a color. * **[Split panes](/terminal/windows/split-panes/)** - Divide any tab into multiple panels, side-by-side or stacked. * **[Tab configs](/terminal/windows/tab-configs/)** - Save and restore tab layouts with predefined pane arrangements and startup commands. * **[Global hotkey](/terminal/windows/global-hotkey/)** - Set up a dedicated hotkey window (Quake Mode) that appears and hides with a keyboard shortcut. ## Input and editor [Section titled “Input and editor”](#input-and-editor) Configure how you type and interact with the terminal input. * **[Standard vs Classic input](/terminal/input/classic-input/)** - Standard input provides easier access to AI features and is the default for new users. Classic input resembles a traditional terminal prompt. Switch between them in **Settings** > **Appearance** > **Input**. * **[Keyboard shortcuts](/getting-started/keyboard-shortcuts/)** - Warp supports common shortcuts and lets you create custom ones. Manage them from **Settings** > **Keyboard shortcuts**, or import keybindings from another terminal during [migration](/getting-started/migrate-to-warp/). * **[Vim keybindings](/terminal/editor/vim/)** - Enable Vim keybindings for keyboard-driven text editing in the input editor. * **Tab key behavior** - Configure what `Tab` does in **Settings** > **Features**. Options include accepting autosuggestions or triggering completions. ## AI and models [Section titled “AI and models”](#ai-and-models) Control how Warp’s agents behave and which models they use. * **[Model choice](/agent-platform/capabilities/model-choice/)** - Choose your preferred AI model (Claude, GPT, Gemini, or Auto) from the model selector in any agent conversation. * **[Agent profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/)** - Configure how much autonomy the agent has: what it can auto-execute, what requires approval, and command allowlists/denylists. * **Default mode for new sessions** - Choose whether new tabs open in terminal mode or Agent Mode by default. Set this in **Settings** > **Agents** > **Warp Agent** > **Input**. ## Import and sync [Section titled “Import and sync”](#import-and-sync) Bring your existing settings into Warp or keep settings synchronized across machines. * **[Migrate from another terminal](/getting-started/migrate-to-warp/)** - Per-source guides for switching to Warp from iTerm2, Ghostty, macOS Terminal, Windows Terminal, VS Code, Cursor, Claude Code, and more. Includes automatic settings import for iTerm2. * **[Settings sync](/terminal/more-features/settings-sync/)** - Sync your Warp settings across machines (Beta). *** ## Next steps [Section titled “Next steps”](#next-steps) Now that Warp looks and feels like yours, the next step is to put it to work on a real project. Open a codebase to unlock context-aware agents, or start an agent conversation to see how terminal commands and AI work together. * **[Codebase Context](/agent-platform/capabilities/codebase-context/)** - Open a project and index your codebase so agents give you context-aware answers about your code. * **[Terminal and Agent modes](/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes/)** - Learn how terminal mode and agent conversations work together. # Installation and setup > Install Warp on macOS, Windows, or Linux. All installation options include auto-update for new features, bug fixes, and performance improvements. Note **Platform support:** Warp is supported on macOS (Intel and Apple silicon), Windows (x86\_64 and ARM64), and Linux (x86\_64 and ARM64). ## Install Warp [Section titled “Install Warp”](#install-warp) Caution **Visit** [Known Issues](/support-and-community/troubleshooting-and-support/known-issues/) **to get more details on setting up and troubleshooting Warp.** * macOS Note **Minimum requirements:** Intel or Apple silicon macOS 10.14 or above and hardware that supports [Metal](https://support.apple.com/en-us/HT205073). **Download Warp and drag into your Applications folder** [Download Warp](https://www.warp.dev/download) **Install using Homebrew by running the command below** ```bash brew install --cask warp ``` After installation, you can find Warp in your Applications folder. * Windows Note **Minimum requirements:** Warp requires Windows 10 version 1809 (build 17763) or later, Windows Server 2019 (build 17763) and Windows Server 2022 (build 20348) or later. This is a requirement for [Windows Pseudo Console (ConPTY)](https://devblogs.microsoft.com/commandline/windows-command-line-introducing-the-windows-pseudo-console-conpty/). **Download Warp, then open and run the installer** [Download Warp](https://www.warp.dev/download) **Install using WinGet by running the command below** ```powershell winget install Warp.Warp ``` After installation, you can find Warp in the Start menu. * Linux Note **Minimum requirements:** Linux distribution with glibc >= 2.31 (released Feb. 2020) and support for *either* [OpenGL ES 3.0+ or Vulkan](https://github.com/gfx-rs/wgpu?tab=readme-ov-file#supported-platforms). This includes (but is not limited to) the following: * Ubuntu 20.04 * Debian 11 (“bullseye”) * Fedora 32 * Arch Linux **Visit the Warp download page for the full list of Linux installation options** [Download Warp](https://www.warp.dev/download) **Debian- and Ubuntu-based distributions** The easiest way to install Warp is to download [x64 .deb package](https://app.warp.dev/download?package=deb) or [ARM64 deb package](https://app.warp.dev/download?package=deb_arm64). After downloading, you can install the package with: ```plaintext sudo apt install ./.deb ``` Installing the .deb package will automatically set up the Warp apt repository and signing key needed to automatically update Warp and verify the integrity of the downloaded packages. Alternatively, you can manually configure the Warp apt repository and install Warp by running the following commands: ```plaintext sudo apt-get install wget gpg wget -qO- https://releases.warp.dev/linux/keys/warp.asc | gpg --dearmor > warpdotdev.gpg sudo install -D -o root -g root -m 644 warpdotdev.gpg /etc/apt/keyrings/warpdotdev.gpg sudo sh -c 'echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/warpdotdev.gpg] https://releases.warp.dev/linux/deb stable main" > /etc/apt/sources.list.d/warpdotdev.list' rm warpdotdev.gpg sudo apt update && sudo apt install warp-terminal ``` **RHEL-, Fedora-, and CentOS-based distributions** The easiest way to install Warp is to download the [x64 .rpm package](https://app.warp.dev/download?package=rpm) or [ARM64 .rpm package](https://app.warp.dev/download?package=rpm_arm64). After downloading, you can install the package with: ```bash sudo dnf install ./.rpm ``` Installing the .rpm package will automatically set up the Warp yum repository. On first update, `dnf` will retrieve the signing key needed to verify the integrity of the downloaded packages. Alternatively, you can manually configure the Warp yum repository and install Warp by running the following commands: ```bash sudo rpm --import https://releases.warp.dev/linux/keys/warp.asc sudo sh -c 'echo -e "[warpdotdev]\nname=warpdotdev\nbaseurl=https://releases.warp.dev/linux/rpm/stable\nenabled=1\ngpgcheck=1\ngpgkey=https://releases.warp.dev/linux/keys/warp.asc" > /etc/yum.repos.d/warpdotdev.repo' sudo dnf install warp-terminal ``` **Arch Linux-based distributions** The easiest way to install Warp is to download the [x64 .pkg.tar.zst package](https://app.warp.dev/download?package=pacman) or [ARM64 pacman package](https://app.warp.dev/download?package=pacman_arm64). After downloading, you can install the package with: ```bash sudo pacman -U ./.pkg.tar.zst ``` The first time you update Warp through the app, it will guide you through setting up the Warp pacman repository and signing key. Alternatively, you can manually configure the Warp pacman repository and install Warp by running the following commands: ```bash sudo sh -c "echo -e '\n[warpdotdev]\nServer = https://releases.warp.dev/linux/pacman/\$repo/\$arch' >> /etc/pacman.conf" sudo pacman-key -r "linux-maintainers@warp.dev" sudo pacman-key --lsign-key "linux-maintainers@warp.dev" sudo pacman -Sy warp-terminal ``` **OpenSUSE- and SLE-based distributions** The Warp yum repository also works for OpenSUSE- and SLE-based systems. Download the [x64 .rpm package](https://app.warp.dev/download?package=rpm) or [ARM64 .rpm package](https://app.warp.dev/download?package=rpm_arm64). After downloading, you can install the package with: ```bash sudo zypper install ./.rpm ``` Installing the .rpm package will automatically set up the Warp yum repository. On first update, `zypper` will retrieve the signing key needed to verify the integrity of the downloaded packages. Alternatively, you can manually configure the Warp yum repository and install Warp by running the following commands: ```bash sudo rpm --import https://releases.warp.dev/linux/keys/warp.asc sudo sh -c 'echo -e "[warpdotdev]\nname=warpdotdev\ntype=rpm-md\nbaseurl=https://releases.warp.dev/linux/rpm/stable\nenabled=1\nautorefresh=1\ngpgcheck=1\ngpgkey=https://releases.warp.dev/linux/keys/warp.asc\nkeeppackages=0" > /etc/zypp/repos.d/warpdotdev.repo' sudo zypper install warp-terminal ``` **AppImage** We also provide an [AppImage](https://appimage.org), a single-file executable version of Warp. Installing Warp via a package manager is recommended, as it will ensure your system has all necessary dependencies installed. You can download the Warp AppImage with the following commands: ```bash # On x64 systems curl -L "https://app.warp.dev/download?package=appimage" -o Warp-x64.AppImage chmod +x Warp-x64.AppImage ``` ```bash # On ARM64 systems curl -L "https://app.warp.dev/download?package=appimage_arm64" -o Warp-ARM64.AppImage chmod +x Warp-ARM64.AppImage ``` **Running Warp on Linux** If you installed a package, find Warp in your desktop manager or run `warp-terminal` on your terminal. If you’re using the AppImage, you can launch it by navigating to the directory where the AppImage is located and running `./Warp-*.AppImage`. Note Want to try our newest features? [Warp Preview](/support-and-community/community/warp-preview-and-alpha-program/) is available on all platforms and architectures (macOS, Windows, Linux) for early access to experimental features. ## Build from source [Section titled “Build from source”](#build-from-source) Warp’s client is open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE), so you can build it yourself from [`warpdotdev/warp`](https://github.com/warpdotdev/warp). Clone the repo, bootstrap toolchain dependencies, and start a development build: ```bash git clone https://github.com/warpdotdev/warp.git cd warp ./script/bootstrap cargo run ``` `cargo run` launches a `warp-oss` binary built from your local checkout. See the repo’s `README.md` and `CONTRIBUTING.md` for full prerequisites (Xcode on macOS, the pinned Rust toolchain, `protoc`) and development setup. Note Use the official builds for daily use. Self-built `warp-oss` binaries use a separate config and data directory, so they run alongside official Warp without conflicting, but they don’t auto-update and don’t carry the production code-signing identity. Use them for developing, auditing, or contributing back upstream. ## Initial setup [Section titled “Initial setup”](#initial-setup) ### Log in to Warp (Optional) [Section titled “Log in to Warp (Optional)”](#log-in-to-warp-optional) After installation, you have the option to create a Warp account through the “Sign up” button (top right), or by navigating to **Settings** > **Account** > **Sign up**. Optionally, you can skip this step. If you’re having issues logging in, see the [Login Troubleshooting](/support-and-community/troubleshooting-and-support/troubleshooting-login-issues/) page. Note If you sign up using Google or GitHub, Warp only gets access to the associated email address. Visit the [Privacy](/support-and-community/privacy-and-security/privacy/) page for more details on Warp’s approach to privacy. ### Use Warp offline [Section titled “Use Warp offline”](#use-warp-offline) You will only need an active internet connection when you open the Warp app for the first time. Once opened, [Warp is able to run with no internet connection](/support-and-community/troubleshooting-and-support/using-warp-offline/), although certain features that require an internet connection like AI and real-time collaboration features will be unavailable. ### Import your settings [Section titled “Import your settings”](#import-your-settings) If you are migrating to Warp from another terminal, editor, or AI coding tool, see the [Migrate to Warp](/getting-started/migrate-to-warp/) docs for per-source guides including settings-import steps and feature equivalents. ### Set up your Warp default shell [Section titled “Set up your Warp default shell”](#set-up-your-warp-default-shell) Warp tries to load your login shell by default. Currently, Warp supports bash, fish, zsh, and PowerShell (pwsh). If your login shell is set to something else (for example, Nushell) Warp will load zsh by default. Zsh is the default login and interactive shell on macOS (starting with macOS Catalina in 2019), replacing the bash shell. For most Linux distributions, the default shell is bash. You can change your default shell by going to **Settings** > **Features** > **Session**. In the Startup shell for new sessions section, you can choose which shell you want Warp to use. # Supported Shells > Warp supports bash, zsh, fish, PowerShell, and WSL2 across macOS, Windows, and Linux. ## Warp default shell [Section titled “Warp default shell”](#warp-default-shell) Warp tries to load your login shell by default. Currently, Warp supports bash, fish, zsh, and PowerShell (pwsh). If your login shell is set to something else (e.g. Nushell) Warp will show a banner indicating it’s not supported and load the default shells listed below: * On macOS, zsh is the default shell. * On Windows, PowerShell (pwsh) is the default shell. * On Linux, bash is the default shell. Note If you run into issues configuring your RC files (`~/.bashrc`, `~/.zshrc`, `config.fish`, `Microsoft.PowerShell_profile.ps1`) with Warp, please see [Configuring and debugging your RC files](/support-and-community/troubleshooting-and-support/known-issues/#configuring-and-debugging-your-rc-files). ### Changing what shell Warp uses [Section titled “Changing what shell Warp uses”](#changing-what-shell-warp-uses) To change the default shell, we recommend you choose a shell in Warp by going to **Settings** > **Features** and scrolling to the `Session` section, then select the “Startup shell for new sessions” Note The changes to your shell will only take effect when you start a new session. ## Customizing your shell environment [Section titled “Customizing your shell environment”](#customizing-your-shell-environment) ### Customize your zsh shell environment [Section titled “Customize your zsh shell environment”](#customize-your-zsh-shell-environment) Zsh can be customized via the `~/.zshrc` file, which runs whenever a new session starts (window, tab, or pane). Use it to set environment variables, aliases, and customize the [prompt](/terminal/appearance/prompt/). #### Editing the .zshrc file [Section titled “Editing the .zshrc file”](#editing-the-zshrc-file) Edit `~/.zshrc` using `nano ~/.zshrc` or `vi ~/.zshrc`. Note Files starting with a dot (`.`) are hidden by default. Check your file explorer’s settings to show hidden files. #### Reloading the zshrc file [Section titled “Reloading the zshrc file”](#reloading-the-zshrc-file) Apply changes by running `source ~/.zshrc` or restarting Warp/opening a new session. ### Customize your Bash shell environment [Section titled “Customize your Bash shell environment”](#customize-your-bash-shell-environment) Bash is pre-installed on macOS and can be customized using `~/.bashrc` (for non-login shells) or `~/.bash_profile` (for login shells). Use these files to set environment variables, aliases, and customize the [prompt](/terminal/appearance/prompt/). #### Editing the .bashrc file [Section titled “Editing the .bashrc file”](#editing-the-bashrc-file) Edit `~/.bashrc` using `nano ~/.bashrc` or `vi ~/.bashrc`. #### Reloading the bashrc file [Section titled “Reloading the bashrc file”](#reloading-the-bashrc-file) Apply changes by running `source ~/.bashrc` or restarting Warp/opening a new session. Note Files starting with a dot (`.`) are hidden by default. Check your file explorer’s settings to show hidden files. ### Customize your Fish shell environment [Section titled “Customize your Fish shell environment”](#customize-your-fish-shell-environment) Fish is a user-friendly shell with autosuggestions and syntax highlighting. Its configuration file is `~/.config/fish/config.fish`. #### Editing the config.fish file [Section titled “Editing the config.fish file”](#editing-the-configfish-file) Edit `~/.config/fish/config.fish` using `nano ~/.config/fish`. Use it to set environment variables, aliases, and functions. #### Reloading the config.fish file [Section titled “Reloading the config.fish file”](#reloading-the-configfish-file) Apply changes by running `source ~/.config/fish` or restarting Warp/opening a new session. Note Unlike Bash and Zsh, Fish does not use `export VAR=value`. Use `set -Ux VAR value` for persistent environment variables. ### Customize your PowerShell shell environment [Section titled “Customize your PowerShell shell environment”](#customize-your-powershell-shell-environment) PowerShell can be customized via its profile script, located at `$PROFILE`. Check if it exists with `Test-Path $PROFILE`, and create it if needed with `New-Item -Path $PROFILE -ItemType File -Force`. #### Editing the PowerShell profile [Section titled “Editing the PowerShell profile”](#editing-the-powershell-profile) Edit the profile using `code $PROFILE`, and use it to set environment variables, aliases, custom prompts, and scripts. #### Reloading the PowerShell profile [Section titled “Reloading the PowerShell profile”](#reloading-the-powershell-profile) Apply changes by restarting Warp or opening a new session. Note PowerShell’s execution policy may block scripts. Enable profile execution with: ```powershell Set-ExecutionPolicy RemoteSigned -Scope CurrentUser ``` ## Additional shell guidance for macOS [Section titled “Additional shell guidance for macOS”](#additional-shell-guidance-for-macos) #### Setting up zsh on Warp [Section titled “Setting up zsh on Warp”](#setting-up-zsh-on-warp) By default, macOS ships with [zsh](https://zsh.sourceforge.io/Doc/Release/zsh_toc.html) located in `/bin/zsh`. You can confirm this location by typing `which zsh` in Warp. You can also check the version of zsh installed on your system by simply typing the following: `$ zsh --version` ### Using fish shell with Warp on macOS [Section titled “Using fish shell with Warp on macOS”](#using-fish-shell-with-warp-on-macos) #### Step 1: Install fish [Section titled “Step 1: Install fish”](#step-1-install-fish) While bash, and zsh come pre-installed on macOS systems, fish shell does not. So before using fish with Warp, you will need to install it. Install fish 3.6 or above using one of the methods listed below - 1. With Homebrew: If you already have homebrew installed, you can simply type `brew install fish`, and follow the instructions. 2. Download the installer at [fishshell.com](https://fishshell.com/) #### Step 2: Switch to fish as the default shell [Section titled “Step 2: Switch to fish as the default shell”](#step-2-switch-to-fish-as-the-default-shell) Once you’ve installed fish on your computer, you can set it as your default shell, so Warp will use it every time a new tab, pane, or window is opened. You can either make fish the default shell for only Warp, from the session settings (**Settings** > **Features** > **Session**), or for your user account. To change your account’s default shell, you need to run two commands. **If you used Homebrew to install fish on macOS or if you used the macOS installer** available on fishshell.com to install fish, type the following two commands in Warp: ```plaintext echo $(which fish) | sudo tee -a /etc/shells chsh -s $(which fish) ``` Note If you prefer, you can also manually edit the `/etc/shells` file using the editor of your choice (you may need sudo privileges). Note **Why the different locations?** The location of fish depends on how it was installed. Homebrew installs programs under `/usr/local` on macOS with Intel processors, but under `/opt/homebrew` on macOS with Apple Silicon. So, if you used Homebrew to install fish on macOS with Apple Silicon, the location of the executable is - `/opt/homebrew/bin/fish`.\ You can identify where fish is installed by running `which fish`. ### Using PowerShell (pwsh) with Warp on macOS [Section titled “Using PowerShell (pwsh) with Warp on macOS”](#using-powershell-pwsh-with-warp-on-macos) #### Step 1: Install PowerShell [Section titled “Step 1: Install PowerShell”](#step-1-install-powershell) While bash, and zsh come pre-installed on macOS systems, PowerShell shell does not. So before using PowerShell with Warp, you will need to install it. Install PowerShell 7.0 or above using one of the methods listed below - 1. With Homebrew: If you already have homebrew installed, you can simply type `brew install powershell/tap/powershell`, and follow the instructions. 2. Download from the [official Microsoft website](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell). #### Step 2: Switch to pwsh as the default shell [Section titled “Step 2: Switch to pwsh as the default shell”](#step-2-switch-to-pwsh-as-the-default-shell) Once you’ve installed PowerShell on your computer, you can set it as your default shell, so Warp will use it every time a new tab, pane, or window is opened. You can either make pwsh the default shell for only Warp, from the session settings (**Settings** > **Features** > **Session**), or for your user account. To change your account’s default shell, you need to run two commands. ```plaintext echo $(which pwsh) | sudo tee -a /etc/shells chsh -s $(which pwsh) ``` Note If you prefer, you can also manually edit the `/etc/shells` file using the editor of your choice (you may need sudo privileges). Note **Why the different locations?** The location of pwsh depends on how it was installed. Homebrew installs programs under `/usr/local` on macOS with Intel processors, but under `/opt/homebrew` on macOS with Apple Silicon. So, if you used Homebrew to install pwsh on macOS with Apple Silicon, the location of the executable is - `/opt/homebrew/bin/pwsh`. You can identify where pwsh is installed by running `which pwsh`. ## Using Warp with shells on Windows [Section titled “Using Warp with shells on Windows”](#using-warp-with-shells-on-windows) On Windows, Warp’s default shell is PowerShell 7 (pwsh). Warp for Windows supports several shells: * PowerShell 7 (default) * PowerShell 5 * Windows Subsystem for Linux (WSL2) * Git Bash Note Windows Command Prompt (cmd.exe) is not currently supported. For more information and updates about cmd.exe support, please see [this GitHub issue](https://github.com/warpdotdev/Warp/issues/5882). # Guides > Step-by-step guides for Warp, the agentic development environment — from first setup to coding agent workflows, MCP integrations, and full app builds. Practical, task-oriented walkthroughs that help you get productive with Warp’s coding agents. Each guide walks through a real AI coding workflow with actual prompts, code, and reproducible results. Browse by topic in the sidebar, or start with one of these featured guides. Note **New to Warp?** Start with [Welcome to Warp](/guides/getting-started/welcome-to-warp/), then explore [10 Warp Coding Features You Should Know](/guides/getting-started/10-coding-features-you-should-know/). ## Featured guides [Section titled “Featured guides”](#featured-guides) * [**Explain your codebase with agents**](/guides/agent-workflows/how-to-explain-your-codebase-using-warp-rust-codebase/) — Use semantic and symbol search to explore and understand unfamiliar code. * [**Create project rules**](/guides/configuration/how-to-create-project-rules-for-an-existing-project-astro-typescript-tailwind/) — Set up an AGENTS.md file so coding agents always understand your project’s setup and conventions. * [**Fix errors with Sentry MCP**](/guides/external-tools/sentry-mcp-fix-sentry-error-in-empower-website/) — Connect the Sentry MCP server to Warp and auto-diagnose production errors. * [**Run multiple agents in parallel**](/guides/agent-workflows/how-to-run-3-agents-in-parallel-summarize-logs-analyze-pr-modify-ui/) — Work on coding, debugging, and analysis tasks simultaneously across tabs. * [**Build a real-time chat app**](/guides/build-an-app-in-warp/building-a-real-time-chat-app-github-mcp-railway/) — Go from idea to deployed app with FastAPI, JavaScript, and GitHub MCP — all inside Warp. * [**Connect agents to external tools**](/guides/external-tools/using-mcp-servers-with-warp/) — Set up MCP servers to give agents access to Linear, GitHub, Figma, and more. ## What’s in this section [Section titled “What’s in this section”](#whats-in-this-section) * **Getting started** — First steps with Warp: setup, appearance, key features * **Agent workflows** — Use coding agents to explain code, review PRs, and run parallel tasks * **Configuration** — Rules, agent profiles, saved prompts, and monorepo sync * **External tools & integrations** — Connect coding agents to Sentry, Figma, Linear, GitHub, and more via MCP * **Build an app in Warp** — End-to-end app builds with AI coding workflows: chat apps, Chrome extensions, Slackbots * **DevOps & infrastructure** — Agent-assisted cloud logs, Docker, Kubernetes, testing, and database optimization * **Frontend & UI** — Build and refine UI components with coding agents # How to: Edit Agent Code in Warp > Review, edit, and refine AI-generated code diffs directly in Warp — accept, reject, or modify changes before applying them. Warp lets you see, edit, and refine AI-generated code diffs directly within the app.\ This makes debugging and bug-fix workflows fast, transparent, and interactive. ![YouTube video](https://i.ytimg.com/vi/dm-P63USsVg/sddefault.jpg) *** ### 1. Starting an Agent Task [Section titled “1. Starting an Agent Task”](#1-starting-an-agent-task) When you start an agent task, Warp: 1. Uses your prompt and context 2. Builds a task list 3. Searches across your codebase using tools like: * Grep * Codebase embeddings * Semantic search Warp shows progress step-by-step, including what it’s searching and which files are being modified. *** ### 2. Reviewing Diffs [Section titled “2. Reviewing Diffs”](#2-reviewing-diffs) Warp generates diffs for every proposed change.\ You can: * Accept changes * Refine them with a follow-up prompt (`Cmd + R`) * Or directly edit the code in the inline editor view This editor view works like a lightweight IDE — perfect for quick corrections before applying. *** ### 3. Applying or Skipping Changes [Section titled “3. Applying or Skipping Changes”](#3-applying-or-skipping-changes) Once you’re happy with a diff: * Click Apply Changes to accept it * Or Fast-Forward to let Warp automatically continue the rest of the fix sequence You can control this level of autonomy globally in Settings → AI → Autonomy. *** ### 4. Compiling and Verifying Fixes [Section titled “4. Compiling and Verifying Fixes”](#4-compiling-and-verifying-fixes) After applying changes, you can immediately test your build, like: ```bash cargo run ``` Warp monitors compilation, verifies results, and runs post-checks automatically. *** ### 5. Visual Verification [Section titled “5. Visual Verification”](#5-visual-verification) In this example, the bug involved a checkbox not being honored in the UI.\ \ After the agent’s fix: * The checkbox logic now works as intended * The model picker toggles correctly * The UI behaves as expected # How to: Explain Your Codebase Using Warp (Rust Codebase) > Use Warp's coding agents with semantic and symbol search to explore, understand, and modify unfamiliar codebases — demonstrated on a large Rust project. Learn how to use Warp’s agents to explore and understand large, unfamiliar codebases — using semantic and symbol-level search. ![YouTube video](https://i.ytimg.com/vi/11rz9OYQ8Hg/sddefault.jpg) *** ## Overview [Section titled “Overview”](#overview) This walkthrough shows: * How Warp explains unknown sections of code * How it combines semantic and keyword searches * How to use these insights to modify UI components *** 1. #### Prompt [Section titled “Prompt”](#prompt) ```plaintext Please explain how the agent popup code is structured, where it lives in the codebase, and how it is rendered and called. I want to understand the full data flow and structure so I can add a new agent button to it. ``` 2. #### How Warp’s Agent Searches [Section titled “How Warp’s Agent Searches”](#how-warps-agent-searches) Warp begins by using **semantic (vectorized) search** to locate relevant files.\ Once it finds probable matches (e.g., `agent_management_popup.rs`), it switches to **symbolic search** (`grep` and direct code reads). Warp intelligently reads large files (splitting them into smaller chunks) to extract relevant definitions and render logic. 3. #### Generated Explanation [Section titled “Generated Explanation”](#generated-explanation) Warp returns a full breakdown: * File paths where the popup is defined * How it’s rendered within the workspace * Which actions and UI components trigger it * A step-by-step view of data flow through the popup component # How to review AI-generated code > Review AI-generated code in Warp with visual diffs and inline comments — works with Claude Code, Codex, or any CLI agent. Coding agents can produce hundreds of lines of code in seconds, but shipping that code without review is risky. This guide provides a practical workflow for reviewing agent-generated code in Warp, catching common issues, and giving structured feedback that the agent can act on. Plan on about 10 minutes to complete. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **A Git-tracked project** — Code review in Warp works on any Git repository. * **An AI coding agent** — This workflow applies to any CLI agent: [Claude Code](/guides/external-tools/how-to-set-up-claude-code/), [Codex](/guides/external-tools/how-to-set-up-codex-cli/), OpenCode, or Warp’s built-in agent. See [Third-party CLI agents](/agent-platform/cli-agents/overview/) for setup. ## Why review matters [Section titled “Why review matters”](#why-review-matters) Agents are fast but imperfect. They hallucinate imports, introduce subtle logic errors, make bad architectural decisions, and duplicate code. Reviewing agent output is the step that turns agentic development from vibe coding into a workflow you can trust. Common issues in AI-generated code: * **Hallucinated imports** — referencing packages or modules that don’t exist in your project * **Redundant logic** — duplicating existing functionality instead of reusing it * **Questionable architectural decisions** — adding new patterns instead of following existing ones, or restructuring code in ways that conflict with your project’s architecture * **Security gaps** — hardcoded credentials, missing input validation, or overly permissive permissions * **Style drift** — ignoring your project’s conventions for naming, error handling, or file structure * **Incomplete error handling** — happy-path code that crashes on edge cases ## 1. Give the agent a task [Section titled “1. Give the agent a task”](#1-give-the-agent-a-task) Whether you’re using Claude Code, Codex, or Warp’s built-in agent, start by giving your agent a task. For example: ```plaintext Fix the authentication middleware to handle expired tokens gracefully ``` The agent will modify one or more files. ## 2. Open the Code Review panel [Section titled “2. Open the Code Review panel”](#2-open-the-code-review-panel) Once the agent has finished the task, open Warp’s [Code Review panel](/code/code-review/) to see every file that changed. You can open it in several ways: * **Keyboard shortcut**: `⌘+Shift++` (macOS) or `Ctrl+Shift++` (Windows/Linux) * **Git diff chip**: Click the diff chip in the terminal input that shows files modified and lines changed * **Review changes button**: After an agent conversation, click **Review changes** at the bottom of the conversation * **Tab bar**: Click the Code Review button in the top-right corner of Warp ![Code Review button in the top-right corner of the Warp title bar showing file and line change counts](/_astro/code-review-button.DZUr27E-_ZyFu3U.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Code Review button. The panel shows all uncommitted changes as a visual diff, grouped by file. Additions are highlighted in green with a `+` prefix, removals in red with a `-` prefix. ![Code Review panel showing file diffs between branches](/_astro/code-review-panel-with-diffs.CCVOOkoI_wzMgE.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Code Review panel with diffs. ## 3. Review diffs by file [Section titled “3. Review diffs by file”](#3-review-diffs-by-file) With the Code Review panel, you can review changes file-by-file: * **Browse all changed files** using the file sidebar. * **Switch diff views** to compare against uncommitted changes or against `main`/`master` to see the full scope of what would land in a PR. * **Click anywhere in the code** to edit diffs directly in the panel. Focus on the areas where agents are most likely to make mistakes: imports, error handling, and anything that touches security or authentication. ![Code Review panel with file navigation sidebar showing changed files](/_astro/code-review-file-sidebar.BCa0ojDy_1qp0hg.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Changed files sidebar. ## 4. Leave inline comments on issues [Section titled “4. Leave inline comments on issues”](#4-leave-inline-comments-on-issues) Click the “Add comment” button on any line or block of code and add a comment describing what needs to change. Warp anchors each comment to the exact file and line, so any agent understands precisely what to fix. You can add as many comments as you need before submitting — Warp batches them so the agent receives all your feedback at once instead of processing changes one at a time. ![Adding an inline comment on a diff line in the Code Review panel](/_astro/code-review-inline-comment.BAsMDFkf_2rcxBL.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Inline comments on specific diff lines. ## 5. Submit all comments to the agent [Section titled “5. Submit all comments to the agent”](#5-submit-all-comments-to-the-agent) Once you’ve reviewed each file and left comments, submit the complete batch. The agent receives all your feedback, applies the requested changes in one pass, and returns an updated diff. Review the updated diff to verify the fixes. Repeat this cycle until the code meets your standards: comment, submit, review. Note This workflow applies to **any CLI agent** running in Warp, not just the built-in agent. You can leave inline comments on diffs generated by Claude Code, Codex, or OpenCode and send them back to the running agent session. ## 6. Run your project’s checks before committing [Section titled “6. Run your project’s checks before committing”](#6-run-your-projects-checks-before-committing) Before accepting the changes, run your project’s test suite, linter, and type checker. Agent-generated code might pass a visual review but fail automated checks. ```bash # Example: run tests and lint npm test && npm run lint ``` If checks fail, you can either fix the issues manually in the Code Review panel or send the error output back to the agent as context for another iteration. Note **Quick review checklist**: When reviewing agent-generated changes, check that imports resolve, new code doesn’t duplicate existing functionality, credentials aren’t hardcoded, error handling covers failure cases, style matches your project, tests still pass, and the agent only changed what was asked. ## Productivity tips [Section titled “Productivity tips”](#productivity-tips) * **Attach diffs as context** — Select a diff hunk in the Code Review panel and attach it to your next prompt. This grounds the agent’s response in your actual code changes. See [Selection as context](/agent-platform/local-agents/agent-context/selection-as-context/) for details. * **Revert individual hunks** — Don’t like one specific change? Revert just that hunk from the Code Review panel without undoing the rest of the agent’s work. * **Compare against main** — Switch the diff view to “Changes vs. main” to see how the agent’s work fits into the full scope of your branch, not just the latest edits. * **Use rules to prevent recurring issues** — If you notice the agent repeatedly making the same mistake (wrong import paths, incorrect naming conventions), add a [Rule](/agent-platform/capabilities/rules/) so it learns your project’s standards. ## Next steps [Section titled “Next steps”](#next-steps) You now have a structured workflow for reviewing AI-generated code in Warp: visual diff review, inline comments that feed back to the agent, and batch feedback submission. This workflow works with any CLI coding agent: Claude Code, Codex, OpenCode, or Warp’s built-in agent. Explore related guides and features: * [Set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) or [Set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) to start using third-party agents in Warp * [Run multiple agents at once](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) to compare outputs from different agents on the same task * [Claude Code in Warp](https://warp.dev/agents/claude-code) | [Codex in Warp](https://warp.dev/agents/codex) | [Gemini CLI in Warp](https://warp.dev/agents/gemini-cli) | [OpenCode in Warp](https://warp.dev/agents/opencode) — agent-specific overviews on the Warp marketing site * [Code Review panel](/code/code-review/) — full reference for all Code Review features * [Interactive Code Review](/agent-platform/local-agents/interactive-code-review/) — detailed docs on inline comments and batch feedback * [Third-party CLI agents](/agent-platform/cli-agents/overview/) — all supported agents and Warp’s universal agent features # How To: Review PRs Like A Senior Dev > Prompt Warp's coding agent to generate structured PR reviews with risk assessment, critical issues, and merge confidence scoring. Learn how to prompt Warp’s AI to review pull requests like an experienced engineer — focusing on structure, red flags, and clarity ![YouTube video](https://i.ytimg.com/vi/NVwqQyphlAw/sddefault.jpg) *** 1. #### Intro [Section titled “Intro”](#intro) This tutorial teaches you how to use Warp to make **pull-request reviews faster and smarter**.\ Instead of relying on AI summaries, you’ll prompt Warp to generate an **index and priority list**, guiding your review order while flagging risky sections. Although this example focuses on large PRs, the same workflow applies to **code reviews**, **design docs**, or **feature diffs**. 2. #### The Problem [Section titled “The Problem”](#the-problem) Large PRs are difficult to parse.\ AI summaries gloss over nuance and may miss subtle issues — you need structured, prioritized insight instead. 3. #### The Prompt [Section titled “The Prompt”](#the-prompt) Use this in Warp’s AI input: ```plaintext ## Prompt: Structured PR Review Format > Review this pull request and format your response for rapid scanning by a busy maintainer. Follow the structure below. --- ### 1. 🚨 Risk Assessment **Overall Risk:** 🔴 HIGH | 🟠 MEDIUM | 🟢 LOW **Complexity:** [Simple | Moderate | Complex | Very Complex] **Blast Radius:** [Isolated | Module-wide | System-wide | External APIs affected] **Requires Immediate Review:** [YES / NO – why] --- ### 2. 🔍 Critical Issues _If none, write “None found” and skip to the next section._ #### 1. [CRITICAL ISSUE TITLE] **File:** `path/to/file.js:L125` **Impact:** Data loss / Security hole / System crash **Fix:** // Quick code fix example here --- ### 3. ⚠️ Concerns _Should discuss or fix before merge. If none, write “None found.”_ **Examples:** - [PERFORMANCE] Unindexed query on large table - [SECURITY] Missing input sanitization in login form --- ### 4. 🎯 Maintainer Decision Guide **Merge confidence:** [0–100]% - □ Safe to merge after fixing blockers - □ Needs architecture discussion first - □ Requires performance testing - □ Get security team review - □ Author should split into smaller PRs **Time to properly review:** ~[X] minutes **Recommended reviewer expertise:** [Backend | Security | Database | Frontend] --- ### 5. 🧭 Formatting Rules - Use emoji headers for instant visual recognition - Keep sections short; if empty, say “None found” - Blockers get full detail, everything else stays concise - Include code examples only for blockers - Bold key impact/risk words - Use consistent prefixes like [SECURITY], [PERFORMANCE], [LOGIC] for easy scanning - If PR is genuinely fine, end with: ✅ “This PR is safe to merge as-is.” ``` # How To: Run 3 Agents in Parallel > Run three agent tasks simultaneously in Warp — modify UI, analyze code reviews, and summarize production logs in parallel. Note This educational module demonstrates Warp’s multi‑threading features — running coding, debugging, and analysis tasks simultaneously in multiple agent tabs. ![YouTube video](https://i.ytimg.com/vi/3jwus1bfKv4/sddefault.jpg) *** ### 🧠 Overview [Section titled “🧠 Overview”](#-overview) Warp allows you to launch several agents at once, each focused on a separate task.\ In the demo, we run three parallel workflows: * Modify UI behavior * Analyze team code reviews * Summarize logs from production 1. #### Launch Agents in Parallel [Section titled “Launch Agents in Parallel”](#launch-agents-in-parallel) Each agent runs in its own tab. * UI Fix Remove the background and border from unfocused input panes. ```plaintext I'd like to make a coding change. Please create a new branch to do this. What i want to do is for the Universal Developer Input, remove the border and background if it's being rendered in the same pane that is not focused. Please look at the reference file and at the attached screenshot. In the screenshot, you'll see what it looks like right now - there are two equally prominent input areas, even though one is focused and one is not. What I want to do is make the non-focused one not have a border and not have a background. Please check out this linear issue for more information. Also, give me a plan before you make any changes. ``` * Code Review Check Analyze how many pull requests a team member has assigned. ```plaintext Use the Github CLI tool to summarize all open PRs for review that are assigned to user. I'd like to see who is the author of the PR, when was it opened, how long has it been open for, which repo is it in, are there open an dunaddressed commens on it, and is it ready for review? ``` * Log Analysis Summarize Cloud Run logs by error severity. ```plaintext Use the gcloud tool to list all my open projects. Once you've done that, let me select a project. Once I've selected a project, we will want to see all the Cloud Run instances that are available. Then once I've picked a Cloud Run instance, I'd like to get a sumary of the last 2000 logs from that Cloud Run instance to see the history histogram of different types of logging on info, warning, and error levels. ``` 2. #### Monitor All Agents [Section titled “Monitor All Agents”](#monitor-all-agents) The **task pane** in Warp shows all running agents.\ You can view plans, progress, and results live without interrupting other tasks. 3. #### Review Results [Section titled “Review Results”](#review-results) * **Coding Agent:** Implements UI fixes accurately. * **Code Review Agent:** Reports 26 open PRs (identifies bottlenecks). * **Log Agent:** Analyzes 1,000 log entries, categorizing errors and flagging Gemini API issues. 4. #### Why This Matters [Section titled “Why This Matters”](#why-this-matters) Warp multi‑agent execution allows you to: * Run multiple tasks without context switching. * Keep coding, debugging, and ops visible simultaneously. * Use AI assistants collaboratively for faster iteration. Tip Multi‑agent workflows let you debug, code, and analyze in parallel — boosting throughput without leaving the terminal. # How to run multiple AI coding agents > Run Claude Code, Codex, and other AI coding agents in parallel using vertical tabs, tab configs, and notifications to manage multiple sessions at once. Different agents have different strengths. Claude Code might handle refactoring well while Codex might excel at test generation. Instead of choosing one, you can run them in parallel. Assign different tasks to different agents, compare their outputs on the same problem, or have one agent build while another reviews. This guide shows you how to set up a multi-agent workflow in Warp and manage it effectively. Plan on about 15 minutes. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Any coding agent** — For example, Warp’s built-in agent, [Claude Code](/guides/external-tools/how-to-set-up-claude-code/), or [Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/). Any combination of supported agents works well: Oz by Warp, Claude Code, Codex, OpenCode, Gemini CLI, Amp, Pi, Droid, and others. * **A Git-tracked project** — Notifications and code review work best in a Git repository. ## 1. Switch to vertical tabs [Section titled “1. Switch to vertical tabs”](#1-switch-to-vertical-tabs) Vertical tabs are the foundation of a multi-agent workflow. Unlike horizontal tabs, they show rich metadata for each session: which agent is running, which branch you’re on, which directory, and the current status. To enable vertical tabs: 1. In the Warp app, go to **Settings** > **Appearance** > **Tabs**. 2. Select **Use vertical tab layout**. You can configure what information to display for each tab: * The running agent (Oz, Claude Code, Codex, etc.) * The current Git branch * The working directory * A status indicator showing whether the agent is active, waiting for input, or idle ![Warp vertical tabs sidebar showing multiple terminal sessions with branch metadata](/_astro/vertical-tabs-multi-agent.BFeWyl4n_ZJrRky.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Vertical tabs overview. ## 2. Launch agents in separate tabs [Section titled “2. Launch agents in separate tabs”](#2-launch-agents-in-separate-tabs) Open a new tab for each agent session. Within each tab, navigate to your project directory and start an agent: **Tab 1 — Claude Code:** ```bash cd ~/your-project claude ``` **Tab 2 — Codex:** ```bash cd ~/your-project codex ``` Give each agent a different task, or give them the same task to compare approaches: ```plaintext # Claude Code: refactor the authentication module Refactor src/auth/ to use async/await instead of callbacks # Codex: write tests for the same module Write comprehensive tests for src/auth/ covering edge cases ``` ![Multiple agent tabs in Warp's vertical sidebar showing session status, branch, and directory metadata](/_astro/multi-agents.BnUFIPfc_ZoqSlt.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Vertical tab with agent details. ## 3. Monitor agents with notifications [Section titled “3. Monitor agents with notifications”](#3-monitor-agents-with-notifications) When you have multiple agents running, you don’t need to watch each tab. Warp sends notifications when an agent needs your attention, for example, when it needs permission to run a command or approval to apply a code diff. Look for the attention-needed indicator on the tab in the vertical sidebar. Click the tab to jump directly to the agent that needs input. Notification setup varies by agent: * **Claude Code** — Install the [Warp notification plugin](https://github.com/warpdotdev/claude-code-warp). Warp shows a one-click install chip when you first run Claude Code, or you can install manually. See the [Claude Code guide](/guides/external-tools/how-to-set-up-claude-code/) for details. * **Codex** — Warp automatically sets up notifications when you first run Codex. No manual setup required. * **OpenCode** — Add the [Warp notification plugin](https://github.com/warpdotdev/opencode-warp) to your `opencode.json` configuration. Note Agent notifications are currently supported for Claude Code, Codex, and OpenCode. For setup details, see [Agent notifications](/agent-platform/capabilities/agent-notifications/). For a full breakdown of which features work with each agent, see the [third-party CLI agents feature matrix](/agent-platform/cli-agents/overview/). ![Warp notification popup showing an agent requesting permission to edit a file](/_astro/tab-notification-indicator.C7-oNGMk_Z1Pp6Ii.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Agent approval notification. ## 4. Compare outputs from different agents [Section titled “4. Compare outputs from different agents”](#4-compare-outputs-from-different-agents) A practical use of parallel agents is running the same task in different Git worktrees, with different agents, to compare their approaches. For example, prompt both Claude Code and Codex with the following: ```plaintext Optimize the database query in src/api/users.ts to reduce response time ``` After both agents complete, open the [Code Review panel](/code/code-review/) (`⌘+Shift++`) in each tab to compare their diffs side-by-side. You might find one agent produces cleaner code while the other catches an edge case the first missed. ## 5. Save your workspace with tab configs [Section titled “5. Save your workspace with tab configs”](#5-save-your-workspace-with-tab-configs) If you regularly work with the same multi-agent setup, save it as a tab config so you can recreate it with one click: 1. Hover over the tab and click the three dots on the right-hand side. 2. Click **Save as new config**. ![Creating a new tab config from the tab context menu in Warp](/_astro/save-new-tab-config.Dsmhq0Di_Z6Qgvd.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Saving a tab config. Tab configs are TOML files that define the directory, startup commands, and layout for a tab. For example, you might create a config that: * Opens two panes side-by-side * Drops you into your project repo automatically * Starts Claude Code in one pane and Codex in the other Note Tab configs pair well with [Git worktrees](/code/git-worktrees/). Create a worktree for each agent so they work on isolated branches, then merge the best results. ## 6. Use Git worktrees for isolated agent workspaces [Section titled “6. Use Git worktrees for isolated agent workspaces”](#6-use-git-worktrees-for-isolated-agent-workspaces) When multiple agents modify the same files, they can create conflicts. Git worktrees solve this by giving each agent its own copy of your repo on a separate branch. Create worktrees for each agent: ```bash git worktree add ../your-project-claude feature/claude-refactor git worktree add ../your-project-codex feature/codex-refactor ``` Then point each agent tab at its own worktree directory. Tab configs complement this workflow. Define each worktree directory and agent startup command in a config, then recreate the full setup with one click. After both agents finish, compare the branches and merge the best results: ```bash git diff feature/claude-refactor..feature/codex-refactor ``` ## Productivity tips [Section titled “Productivity tips”](#productivity-tips) * **Use the Agent Management Panel** — Open the Agent Management Panel to see all active agents across tabs. This gives you a dashboard view of what’s running, what’s waiting, and what’s finished. * **Color-code your tabs** — Assign different themes or colors to agent tabs so you can visually distinguish them at a glance in the vertical sidebar. * **Compose with `Ctrl+G`** — Use Warp’s rich input editor (`Ctrl+G`) when composing prompts for third-party agents. This gives you click-to-edit instead of arrow-key navigation in the raw CLI. * **Review all changes before committing** — After running multiple agents, open the Code Review panel to see the combined diff across all files. Use “Changes vs. main” view to see the full scope of all agent-generated changes on your branch. ## Next steps [Section titled “Next steps”](#next-steps) You set up a multi-agent workspace with vertical tabs, launched different agents in parallel, monitored them with notifications, compared their outputs, and learned how to use tab configs and Git worktrees for isolated, reproducible multi-agent workflows. Explore related guides and features: * [How to review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code/) — review and refine the code your agents produced * [Set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) or [Set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) if you haven’t installed both yet * [Claude Code in Warp](https://warp.dev/agents/claude-code) — overview of Claude Code support in Warp * [Codex in Warp](https://warp.dev/agents/codex) — overview of Codex support in Warp * [Gemini CLI in Warp](https://warp.dev/agents/gemini-cli) — overview of Gemini CLI support in Warp * [OpenCode in Warp](https://warp.dev/agents/opencode) — overview of OpenCode support in Warp * [Third-party CLI agents](/agent-platform/cli-agents/overview/) — all supported agents and universal agent features * [Vertical tabs](/terminal/windows/vertical-tabs/) — full reference for tab features # How to use voice and images to prompt coding agents > Use voice and image context to prompt coding agents faster in Warp — works with Claude Code, Codex, and any CLI agent. Typing detailed prompts for coding agents can be slow. Describing a bug from a screenshot, dictating a complex refactoring plan, or explaining a UI change from a design mockup are examples of tasks that are faster with voice and images than with text alone. This guide shows you how to use multimodal input with any CLI coding agent running in Warp in about 5 minutes. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Warp** — Voice and image input are built into Warp’s agent interface. Download from [warp.dev](https://warp.dev). * **A CLI coding agent** — Voice and image input work with any supported agent: [Claude Code](/guides/external-tools/how-to-set-up-claude-code/), [Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/), OpenCode, Gemini CLI, Amp, or Droid. See [Third-party CLI agents](/agent-platform/cli-agents/overview/) for the full list. * **A working microphone** (for voice) — Built-in or external, including Bluetooth audio devices. ## 1. Enable voice input [Section titled “1. Enable voice input”](#1-enable-voice-input) Voice transcription is available in Warp’s agent input. To use it: 1. Click the **microphone icon** in the input area, or use the voice input keyboard shortcut. ![Warp input area showing the microphone icon for voice transcription](/_astro/voice-input-microphone.Yza9wwE0_224C7g.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The microphone icon appears in the input area for voice transcription. 2. Speak your prompt naturally. Warp transcribes your speech and places the text in the input field. 3. Review the transcription, edit if needed, then submit your prompt. Voice input works for both Warp’s built-in agent and third-party CLI agents when the agent utility bar is active. Note You can configure the voice input keybinding in the Warp app under **Settings** > **Agents** > **Warp Agent** > **Voice**. The default uses the `fn` key. ## 2. Prompt with voice instead of typing [Section titled “2. Prompt with voice instead of typing”](#2-prompt-with-voice-instead-of-typing) Voice is fastest for prompts that are easy to say but tedious to type, such as complex descriptions, multi-step plans, or explanations that reference what you’re looking at. Try prompts like: ```plaintext Refactor the authentication middleware to handle three cases: valid token, expired token, and missing token. For expired tokens, return a 401 with a refresh token hint. For missing tokens, return a 403. Add unit tests for each case. ``` The transcription appears in your input field where you can review and edit before submitting. ## 3. Attach screenshots as context [Section titled “3. Attach screenshots as context”](#3-attach-screenshots-as-context) Paste (`⌘+V`) or drag images directly into the input area to give the agent visual context. This is useful for: * **Bug reports** — Screenshot the error in your browser and ask the agent to fix it. * **Design mockups** — Paste a Figma screenshot and ask the agent to implement the UI. * **Error messages** — Screenshot a stack trace instead of copying and reformatting it. * **Visual diffs** — Show the agent what the UI looks like now vs. what it should look like. ![Image attached as context in the Warp input area alongside a text prompt](/_astro/image-as-context.Bh2Oa2Jy_Z1Om4M5.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Attaching images as agent context. ## 4. Combine voice and images for design-to-code workflows [Section titled “4. Combine voice and images for design-to-code workflows”](#4-combine-voice-and-images-for-design-to-code-workflows) The most powerful use of multimodal input is combining voice and images. For example: 1. Take a screenshot of a design mockup from Figma. 2. Paste it into the input area. 3. Use voice to describe what you want: ```plaintext This is the login page design. Implement it using React and Tailwind. Match the spacing and colors exactly. The form should validate email format on blur and show inline error messages. ``` The agent sees the design and hears your implementation requirements at the same time — much faster than writing a detailed specification by hand. ## 5. Use voice and images with third-party agents [Section titled “5. Use voice and images with third-party agents”](#5-use-voice-and-images-with-third-party-agents) Voice and image input work with any CLI agent that Warp detects, not just the built-in agent. When you run Claude Code, Codex, or another supported agent, Warp shows the **agent utility bar** with controls for voice, images, and files. To use with a third-party agent: 1. Start the agent in your terminal (e.g., `claude` or `codex`). 2. The agent utility bar appears automatically when Warp detects the agent session. 3. Use the microphone icon for voice input or paste images as context. 4. Press `Ctrl+G` to open the rich input editor for composing complex prompts with attached images. The voice transcription and image context are sent to the running agent session just as if you had typed and pasted them manually. Note If you don’t see the utility bar, make sure you’re on the latest Warp version and that the agent is running inside Warp (not an external terminal). ## Productivity tips [Section titled “Productivity tips”](#productivity-tips) * **Use voice for code review feedback** — Instead of typing inline comments, use voice to describe what needs to change while looking at the diff in the [Code Review panel](/code/code-review/). * **Screenshot UI issues** — When you want to change a UI component, just screenshot it, send it to the agent, and describe what you want changed. * **Dictate commit messages** — After reviewing your changes, use voice to describe what you did. The agent can format it as a proper commit message. * **Use with Rules for consistent results** — Combine image context with [Rules](/agent-platform/capabilities/rules/) that define your project’s UI patterns. The agent will match the mockup while following your existing design system. ## Next steps [Section titled “Next steps”](#next-steps) You can now prompt coding agents using voice transcription and image context — whether you’re using Claude Code, Codex, or any other CLI agent in Warp. Voice and images make complex prompts faster to create and more accurate, especially for design-to-code workflows, bug reproduction, and multi-step refactoring plans. Explore related guides and features: * [Set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) or [Set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) to start using third-party agents * [How to review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code/) — review the code your agents produce * [Run multiple agents at once](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) — combine voice/image prompting with parallel agents * [Voice input](/agent-platform/local-agents/interacting-with-agents/voice/) — full reference for voice features * [Images as context](/agent-platform/local-agents/agent-context/images-as-context/) — full reference for image input * [Third-party CLI agents](/agent-platform/cli-agents/overview/) — all supported agents and universal features # Running Multiple Agents At Once With Warp > Run multiple agent tasks simultaneously in Warp — revert PRs, edit shortcuts, and add tests across repos without losing context. ![YouTube video](https://i.ytimg.com/vi/w0bJFC0u0pE/sddefault.jpg) ### 1. Why Multiple Agents Matter [Section titled “1. Why Multiple Agents Matter”](#1-why-multiple-agents-matter) Sometimes you need to work on several coding tasks at once — fix a PR, add a feature, debug a build — without losing context.\ \ Warp lets you run multiple agent tasks simultaneously, all within one workspace. *** ### 2. How It Works [Section titled “2. How It Works”](#2-how-it-works) Each agent runs in its own thread, complete with: * Progress tracking * Notifications when blocked or completed * Separate command histories Because Warp is a desktop app, it can send system notifications to alert you when an agent finishes or when it needs review. *** ### 3. Example: Reverting a PR and Editing a Shortcut [Section titled “3. Example: Reverting a PR and Editing a Shortcut”](#3-example-reverting-a-pr-and-editing-a-shortcut) Ben uses voice mode to quickly start tasks. Prompt Example:\ “Find the PR where we added the keyboard shortcut to the UDI input and revert it.” He pastes in the PR number, and the agent: * Locates the relevant diff * Reverts the change automatically * Pushes it to the correct branch Warp notifies him when the task completes. Then, he runs another prompt: Prompt Example:\ “Change the keyboard shortcut to `Cmd + Shift + I`.” Warp modifies `input.rs`, previews the diff, and Ben applies the change directly from Warp. *** ### 4. Managing Multiple Tasks [Section titled “4. Managing Multiple Tasks”](#4-managing-multiple-tasks) You can switch between concurrent agents: * Each task appears in a Task List panel * Completed, canceled, and running tasks are color-coded * Toast notifications appear when tasks are blocked You can even fast-forward agents to auto-approve all code diffs once you trust their trajectory. *** ### 5. Parallel Contexts [Section titled “5. Parallel Contexts”](#5-parallel-contexts) In another repo, Ben adds a new Eval test via a different agent: Prompt Example:\ “Create a Python hello world function and verify it prints ‘Hello World.’” Warp’s second agent: * Locates the correct file * Writes the test code * Verifies execution Meanwhile, the first agent continues working on the keyboard shortcut task. *** ### 6. Reviewing All Active Agents [Section titled “6. Reviewing All Active Agents”](#6-reviewing-all-active-agents) Open the Agent Mode Dashboard to see: * Active tasks * Completed tasks * Logs and outputs You can refine or cancel tasks mid-run if needed, or switch back to manual commands. # Understanding Your Codebase > Use Warp's Codebase Context to search across client and server repos, generate architecture summaries, and onboard to unfamiliar features fast. ![YouTube video](https://i.ytimg.com/vi/pohnoRZas-E/sddefault.jpg) ### 1. The Challenge [Section titled “1. The Challenge”](#1-the-challenge) Kevin, who worked on Warp’s Windows and Linux builds, wanted to jump into a feature he hadn’t touched before: Block Sharing.\ \ This feature spans two codebases — Warp’s client (Rust) and server (Go) — making onboarding tough. That’s where Codebase Context comes in. *** ### 2. What Is Codebase Context? [Section titled “2. What Is Codebase Context?”](#2-what-is-codebase-context) Warp’s Codebase Context uses semantic search to understand your code.\ It doesn’t rely on exact function or variable names — instead, it searches based on meaning. You can use it through a shared workflow in Warp Drive. This prompt tells Warp to: * Search across both client and server codebases * Summarize how a feature works end-to-end * Include clickable links to relevant files *** ### 3. Real Example: Block Sharing [Section titled “3. Real Example: Block Sharing”](#3-real-example-block-sharing) Kevin types `block sharing` into Warp’s shared workflow.\ Warp: 1. Searches the client codebase for the rendering logic 2. Searches the server codebase for GraphQL handlers 3. Generates a summary combining both perspectives The output includes: * Architecture overview * Linked file paths * Function and module summaries No more manual onboarding or guessing file names. *** ### 4. Incremental Syncing [Section titled “4. Incremental Syncing”](#4-incremental-syncing) Whenever you change a file in an indexed repo: * Warp detects the update automatically * Re-embeds just that file * Keeps your code context fresh That means agents never reference stale code. *** ### 5. Why It’s Game-Changing [Section titled “5. Why It’s Game-Changing”](#5-why-its-game-changing) Codebase Context helps teams: * Understand large or unfamiliar codebases * Onboard faster * Jump between client and server logic seamlessly * Generate accurate, clickable documentation > “This saved us hours of one-on-one walkthroughs.” — Lucy # Using Images As Context With Warp > Attach screenshots and design mockups as context for Warp's agent to generate UI code, debug visual issues, and match Figma designs. ![YouTube video](https://i.ytimg.com/vi/_Pc7bL0zAoM/sddefault.jpg) ### 1. Why Images Matter [Section titled “1. Why Images Matter”](#1-why-images-matter) Humans process visuals much faster than text — and the same applies to AI.\ \ When you’re trying to explain a UI issue (“this button is off by a few pixels”), describing it with words can be clunky.\ \ That’s why Warp supports images as context — letting you attach screenshots directly to your prompts. > 🧠 “An image is worth a thousand words” — especially when debugging UI or building frontend components. *** ### 2. What Image Context Does [Section titled “2. What Image Context Does”](#2-what-image-context-does) Image Context allows you to: * Attach one or more screenshots to an agent query * Give visual references for bugs, designs, or features * Let the agent visually interpret what you mean This is especially useful for frontend tasks like: * Rebuilding a design from Figma * Identifying layout misalignments * Debugging visual bugs *** ### 3. Building an MCP Marketplace from Figma [Section titled “3. Building an MCP Marketplace from Figma”](#3-building-an-mcp-marketplace-from-figma) Taking a Figma mock of an MCP Server Marketplace and using it as input for Warp. #### Step 1. Capture the Mock [Section titled “Step 1. Capture the Mock”](#step-1-capture-the-mock) Take a screenshot of your design (e.g., the MCP Marketplace layout). #### Step 2. Attach the Image [Section titled “Step 2. Attach the Image”](#step-2-attach-the-image) In Warp: 1. Click the 📎 image icon in the input bar 2. Select your screenshot 3. Confirm it’s attached to the query *** ### 4. Running the Task [Section titled “4. Running the Task”](#4-running-the-task) Once attached, Warp’s agent: 1. Detects the attached image 2. Searches your repo (e.g., `collection.rs`) 3. Generates diffs that recreate the UI from the mock 4. Creates corresponding components and layout logic You can view and edit these diffs in the Code Diff Viewer, similar to GitHub’s diff interface. > 💡 Warp recommends smaller, focused diffs — agents perform better when working iteratively. *** ### 5. Reviewing the Results [Section titled “5. Reviewing the Results”](#5-reviewing-the-results) The agent built: * A UI component for the MCP Marketplace * Static data for three MCP servers (`Linear`, `GitHub`, `Stripe`) * Proper rendering logic and styling Verify the UI in Warp: > “It matched the mock almost perfectly — something that would’ve taken me two days was done in 20 minutes.” *** ### 6. Optimizing for Performance [Section titled “6. Optimizing for Performance”](#6-optimizing-for-performance) Because images can consume tokens quickly, Warp automatically: * Resizes images client-side * Compresses them intelligently before sending * Minimizes token usage without losing clarity # 5 AI agent workflows for product managers > Five agent workflows that automate status updates, documentation, Slack search, and meeting prep for product managers. Most PM work breaks down into three activities: gathering information, synthesizing it, and communicating the result. These five workflows use Warp’s agents and MCP integrations to automate the gathering and speed up the synthesis, so you spend less time switching between tools and more time making decisions. Each workflow takes 5–10 minutes to set up. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Warp** — installed and signed in. See [Installation and setup](/getting-started/quickstart/installation-and-setup/) to get started. * **MCP servers (optional but recommended)** — Slack, Linear, and Notion all have documented MCP configs in Warp. See [MCP](https://docs.warp.dev/agent-platform/capabilities/mcp/) for setup instructions. Each workflow below notes which MCP servers it uses and includes a fallback for users without MCP. Note These workflows work with Warp’s built-in agent or any third-party CLI agent running in Warp, including Claude Code, Codex, OpenCode, and Gemini CLI. See [Third-party CLI agents](https://docs.warp.dev/agent-platform/cli-agents/overview/) for the full list. ## 1. Pull cross-project status updates [Section titled “1. Pull cross-project status updates”](#1-pull-cross-project-status-updates) Compiling a status update across multiple projects usually means opening Slack, Linear, Notion, and email in separate tabs, reading through each one, and manually synthesizing a summary. With MCP-connected agents, you can pull context from all of these tools in a single prompt. 1. Tell the agent which projects, tools, and time range to cover. Be specific about the audience and format you need. 2. Submit a prompt that queries your connected tools. For example: ```plaintext Pull updates from the last week across #project-atlas and #project-beacon in Slack, any Linear tickets that moved to Done or In Review, and the latest entries in our Notion launch tracker. Summarize into a status update for my skip-level, organized by project. Use bullet points. Flag anything blocked or at risk. ``` 3. Review the output and iterate. Ask the agent to adjust the tone (more concise, more formal), reorder sections, or add context for a specific stakeholder. The result is a formatted status update ready to paste into Slack or email. **MCP servers used** — Slack, Linear, Notion. Note **Without MCP**: Copy relevant updates from each tool and paste them into your prompt. Ask the agent to synthesize and format the summary. The workflow is the same; MCP just automates the gathering step. ## 2. Draft documents from the terminal [Section titled “2. Draft documents from the terminal”](#2-draft-documents-from-the-terminal) Writing a rollout doc, product brief, or strategy doc usually starts with a blank page in Google Docs or Notion. Instead, describe what you need to the agent and iterate on a draft without leaving Warp. 1. Describe the document type, audience, and structure. For example: ```plaintext Draft a product brief for a new onboarding flow redesign. The audience is engineering and design leads. Include sections for problem statement, proposed solution, success metrics, and open questions. The problem is that 40% of new users drop off before completing setup. ``` 2. Review the draft and iterate. Ask the agent to expand a section, tighten the language, add a competitor comparison, or restructure the outline. 3. Copy the finished draft into Google Docs, Notion, Confluence, or wherever your team keeps docs. If you have Notion MCP connected, ask the agent to push the content directly. The result is a structured first draft, grounded in your specific context, ready for review. **MCP servers used** — Notion (optional, for pushing content directly). Note **Without MCP**: Copy the finished draft and paste it into your docs tool manually. ## 3. Search Slack for meeting prep [Section titled “3. Search Slack for meeting prep”](#3-search-slack-for-meeting-prep) Before a meeting or project check-in, you often need to catch up on activity across multiple Slack channels. Manually reading through 10+ channels is slow. With the Slack MCP server, you can search and summarize in one prompt. 1. Tell the agent which channels and time range to search. For example: ```plaintext Search #eng-backend, #design-reviews, #project-atlas, and #incidents for the last 3 days. Summarize the key decisions, open questions, and anything that was escalated. I have a project sync in 30 minutes and need to be caught up. ``` 2. Review the structured summary the agent returns, grouped by topic or channel. 3. Ask follow-up questions to drill into specific threads. For example: “What was the resolution on the API rate limiting discussion in #eng-backend?” The result is a briefing doc summarizing recent activity across channels, ready in minutes. **MCP servers used** — Slack. Note **Without MCP**: Copy key messages or thread summaries from Slack and paste them into your prompt. Ask the agent to organize and summarize. This works well for a smaller number of channels. ## 4. Run parallel workstreams in tabs [Section titled “4. Run parallel workstreams in tabs”](#4-run-parallel-workstreams-in-tabs) PM work often involves juggling multiple threads at once: researching a competitor while drafting a brief while reviewing a doc from a teammate. Warp’s vertical tabs let you run separate agent sessions side by side, each focused on a different task. 1. To enable vertical tabs, in the Warp app go to **Settings** > **Appearance** > **Tabs** and toggle on **Use vertical tab layout**. 2. Open a separate tab for each workstream. For example: * **Tab 1** — researching competitor pricing via web search * **Tab 2** — drafting a product brief based on the research * **Tab 3** — summarizing Slack threads for a stakeholder update 3. Each tab shows which agent is running and its current status. Warp sends notifications when an agent needs your input, so you don’t need to watch each tab. This “thought threads” pattern keeps your workstreams isolated and lets you context-switch without losing progress. For a deeper walkthrough of multi-agent tab setups, including tab configs and Git worktrees, see [Run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/). ## 5. Use voice to draft strategy docs [Section titled “5. Use voice to draft strategy docs”](#5-use-voice-to-draft-strategy-docs) When thinking through a brief, strategy doc, or stakeholder update, talking is often faster than typing. Warp’s voice input lets you dictate a rough draft, then ask the agent to clean it up. 1. Click the **microphone icon** in the input area or press the voice input key (default: `fn` key) to start recording. 2. Talk through your document naturally. Describe the problem, your proposed approach, open questions, and next steps. Don’t worry about structure or polish. 3. After the transcription appears, submit a follow-up prompt: ```plaintext Clean up that transcription into a structured strategy doc. Add an executive summary at the top, organize the body into Problem, Approach, Risks, and Next Steps sections, and tighten the language for a leadership audience. ``` The result is a structured first draft from a stream-of-consciousness recording. For full setup details and more use cases, see [Use voice and images to prompt agents](/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents/). ## Productivity tips [Section titled “Productivity tips”](#productivity-tips) * **Save Rules for recurring formats** — Save a Rule with your team’s status update format, doc templates, or project list so agents start with the right context every time. See [Rules](https://docs.warp.dev/agent-platform/capabilities/rules/). * **Create Saved Prompts for recurring workflows** — Turn your weekly status prompt or meeting prep prompt into a reusable Saved Prompt so you can run it with one click. See [Trigger reusable actions with Saved Prompts](/guides/configuration/trigger-reusable-actions-with-saved-prompts/). * **Use `Ctrl+G` for complex prompts** — Open the rich input editor for click-to-edit prompt composition instead of navigating with arrow keys. Works with any CLI agent running in Warp. See [Rich Input Editor](https://docs.warp.dev/agent-platform/cli-agents/rich-input/). * **Save tab configs for recurring setups** — If you regularly run a research + drafting + review tab layout, save it as a tab config for one-click workspace setup. See [Tab Configs](https://docs.warp.dev/terminal/windows/tab-configs/). ## Next steps [Section titled “Next steps”](#next-steps) You now have five workflows for automating the information gathering, synthesis, and communication that make up most PM work: cross-project status updates, document drafting, Slack search for meeting prep, parallel workstreams in tabs, and voice-to-text for rough drafts. To go deeper on any of the tools used in these workflows, explore the related guides below. You can also customize how agents behave across your team with Rules, Saved Prompts, and MCP integrations. * [Connect agents to MCP servers](/guides/external-tools/using-mcp-servers-with-warp/) — set up Slack, Linear, Notion, and other MCP integrations * [Use voice and images to prompt agents](/guides/agent-workflows/how-to-use-voice-and-images-to-prompt-coding-agents/) — full setup and use cases for multimodal input * [Run multiple AI coding agents](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) — multi-tab workflows, tab configs, and Git worktrees * [MCP](https://docs.warp.dev/agent-platform/capabilities/mcp/) — full reference for MCP server configuration * [Rules](https://docs.warp.dev/agent-platform/capabilities/rules/) — save persistent context so agents follow your team’s conventions * [Voice input](/agent-platform/local-agents/interacting-with-agents/voice/) — full reference for voice transcription features # Warp vs Claude Code > Compare Warp and Claude Code across setup, diff review, model selection, configuration, and performance. ![YouTube video](https://i.ytimg.com/vi/NUVftxAqZQo/sddefault.jpg) ### 1. Overview [Section titled “1. Overview”](#1-overview) This walkthrough compares Claude Code and Warp’s built-in coding agent — two tools built for AI-assisted development.\ Both can: * Read and edit files * Generate code diffs * Plan multi-step tasks\ \ But they differ in experience, configurability, and performance. *** ### 2. Setup and Interface [Section titled “2. Setup and Interface”](#2-setup-and-interface) #### Claude Code [Section titled “Claude Code”](#claude-code) * Runs as a CLI tool, requiring a terminal and the `claude` CLI installed. * You type prompts directly into a command box. * Supports file reading, search, and diff generation. #### Warp [Section titled “Warp”](#warp) * Built directly into the Warp terminal. * No installation needed — type a natural-language query or click the Agent button to enter Agent Mode. * Handles the same operations as Claude Code but integrated into the environment you already use. *** ### 3. Reviewing Diffs [Section titled “3. Reviewing Diffs”](#3-reviewing-diffs) In Claude Code: * You manually review diffs via CLI or external editors like VS Code. * You can hit Shift + Tab to auto-accept all edits. In Warp: * You get a visual diff view built in. * Accept, reject, or manually edit diffs inline using Warp’s lightweight editor. * The agent automatically updates its context to avoid overwriting your changes. *** ### 4. Planning & Context Gathering [Section titled “4. Planning & Context Gathering”](#4-planning--context-gathering) Both support planning mode for complex tasks: * Claude Code uses a Markdown-style plan view. * Warp can either show a similar plan or skip planning for short tasks. For context: * Both allow file references with `@filename`. * Warp extends this with symbol referencing (`@functionName`) and a file tree explorer, letting you pull in specific lines and symbols as context. *** ### 5. Model Selection [Section titled “5. Model Selection”](#5-model-selection) Claude Code lets you pick between Claude 3 models (`Sonnet`, `Opus`, `Haiku`) via the `/model` menu. Warp supports multiple ecosystems: * Claude (Sonnet, Opus) * GPT-5 (various reasoning levels) * Gemini series Switch models from the dropdown or directly in the agent menu. *** ### 6. Configuration [Section titled “6. Configuration”](#6-configuration) In Claude Code: * Everything is configured via `/commands` in the CLI. * Includes model switching, tool permissions, and sub-agent creation. In Warp: * Configure from Settings → AI & Agents. * Add MCP servers, prompts, and global rules. * Define Agent Profiles for read/write permissions, autonomy, and planning behavior. * Maintain a global rules directory for consistent behavior across projects. Warp also supports codebase indexing, which creates embeddings for faster semantic search across your repos. *** ### 7. Managing Agents Over Time [Section titled “7. Managing Agents Over Time”](#7-managing-agents-over-time) Claude Code: * Shows progress directly in the CLI tab. * Displays the current task name in the terminal tab title. Warp: * Adds visual indicators for agent status, progress, and toast notifications when blocked. * Optional desktop notifications keep you informed when you’re multitasking. *** ### 8. Performance Comparison [Section titled “8. Performance Comparison”](#8-performance-comparison) Ben ran both tools on the same coding task — fixing a bug in the `renderKeyboardShortcut` function from a Sentry issue. Claude Code results: * Took \~2–4 minutes with Claude 3 Sonnet. * Found the right issue and produced working code, though some redundant logic remained. Warp results: * With GPT-5, average time was \~1 minute 20 seconds. * Consistent, high-quality output. * Produced concise solutions with fewer redundant checks. * Supported multiple models for experimentation. *** ### 9. Conclusions [Section titled “9. Conclusions”](#9-conclusions) | Criteria | Claude Code | Warp | | --------------- | ----------------- | ------------------------ | | Environment | CLI tool | Integrated into terminal | | Diff Review | External / Manual | Built-in panel | | Planning | Markdown mode | Inline or Opus-assisted | | Model Options | Claude only | Claude, GPT-5, Gemini | | Configurability | CLI-based | UI + Profiles + Rules | | Performance | 2–4 min avg | \~1.2 min avg (GPT-5) | **TL;DR:**\ If you prefer the Claude model suite and CLI workflow — go with Claude Code.\ If you want richer diff editing, context referencing, and model flexibility — Warp is the better fit. > “Claude Code gives you an AI terminal. Warp gives you an AI development environment.” # Building a Chrome Extension (D3.js + Javascript + HTML + CSS) > Build a D3.js Sankey diagram Chrome extension using Warp — scaffold, debug, coordinate multiple agents, and publish to the Chrome Web Store. Tip This educational module teaches you step-by-step how to replicate the process shown in the video — building a **Sankey diagram Chrome extension** using **D3.js**, debugging, coordinating **multiple agents**, and deploying to the **Chrome Web Store**. ![YouTube video](https://i.ytimg.com/vi/xbvE_aoZ508/sddefault.jpg) 1. #### Set up your environment and create a new Chrome Extension project [Section titled “Set up your environment and create a new Chrome Extension project”](#set-up-your-environment-and-create-a-new-chrome-extension-project) Our goal: build a Chrome extension called **“Sankey Stone”** that visualizes flows using **D3.js**. Files created during setup * `manifest.json` * `popup.html` * `popup.css` * `popup.js` * Icon images (`icon16.png`, `icon32.png`, `icon48.png`, etc.) Enable Developer Mode in Chrome and load the project: chrome://extensions → Developer Mode → Load unpacked → Select your project folder Caution If you see errors like “Failed to load extension” or “Could not load icon 16.png,” double‑check your manifest paths and icon filenames. The transcript explicitly shows these initial debugging steps. 2. #### Test the initial D3.js rendering [Section titled “Test the initial D3.js rendering”](#test-the-initial-d3js-rendering) After fixing missing icons, the extension loads but initially shows only “Loading diagram.”\ \ Debug this by taking a screenshot and feeding it to an agent for context by asking: ```plaintext It says loading diagram — why isn’t the chart appearing? ``` An agent reviews the error and regenerates the `popup.js` so the Sankey chart appears using **D3.js**. Result: a working, interactive diagram rendered inside the extension popup. 3. #### Version control and GitHub setup [Section titled “Version control and GitHub setup”](#version-control-and-github-setup) Initialize a Git repository and commit: ```bash git init git add . git commit -m "Initial Sankey Stone extension" ``` The developer asks the agent to create a GitHub repo and push the code.\ \ The agent handles authentication, creates the remote repo, and pushes all files automatically. 4. #### Add a local test page and dynamic data [Section titled “Add a local test page and dynamic data”](#add-a-local-test-page-and-dynamic-data) Launch a simple local web server with a test page that outputs traffic flow data. The extension reads this data and updates the Sankey diagram dynamically. Transcript example prompt: ```plaintext Update the test data page so that it generates random labels and different contexts when I hit the regenerate button. ``` The agent edits the test page so that clicking the **Regenerate Test Page** button updates the diagram in real time. 5. #### Coordinate multiple agents in parallel [Section titled “Coordinate multiple agents in parallel”](#coordinate-multiple-agents-in-parallel) The video demonstrates running **multiple agents** in parallel. Each agent receives a different task: | Agent | Task | | ----- | ----------------------------------------------------------------------------- | | #1 | `Update the test data page to randomize labels and values` | | #2 | `Change the refresh page button to regenerate the chart in a different style` | | #3 | `Generate a useful README file for the project` | You can approve actions automatically by enabling **Auto‑approve all agent actions** so background updates run without manual confirmation. Note Running multiple agents in parallel mirrors having a small team: one agent focuses on data generation, another on UI changes, and a third on documentation. 6. #### Refine styles and interactions [Section titled “Refine styles and interactions”](#refine-styles-and-interactions) After the data layer works, now you can iterate on appearance: ```plaintext Apply new color themes and improve the layout. ``` Changes applied: * Support for multiple color themes and improved node layout. * Hovering over links highlights connected nodes. * Users can drag nodes to rearrange the layout. * Added a “Switch Style” button to cycle between themes. To support exporting diagrams, you can ask: ```plaintext Add a button to download this image as a PNG. ``` The Warp agent writes the JS logic for PNG export and verifies that clicking the button saves a screenshot of the diagram. 7. #### Add an API key setup screen [Section titled “Add an API key setup screen”](#add-an-api-key-setup-screen) Create a settings page where users can store API keys: ```plaintext Add a settings page to enter the Anthropic API key and test it. ``` * The page allows testing the key to ensure it works. * API keys are stored locally in the browser, not sent to a server. 8. #### Publish to the Chrome Web Store [Section titled “Publish to the Chrome Web Store”](#publish-to-the-chrome-web-store) Package and submit the extension: ```bash zip -r sankey_stone.zip * ``` Upload the ZIP file to and follow the prompts. Note The review may take a few weeks. *** ### Summary [Section titled “Summary”](#summary) By following these transcript‑based steps, you can recreate the same workflow: * Scaffold a Chrome extension with D3.js. * Debug manifest and icon issues. * Use agents to generate and refine code. * Introduce multi‑agent parallel tasks for UI, data, and docs. * Add interactivity, themes, and export options. * Create an API key setup screen. * Package and publish to the Chrome Web Store. Tip You can follow this same pattern with your own idea: start small, scaffold with AI prompts, iterate using parallel agents, and deploy to production all from within Warp. # Building a Real-time Chat App (Github MCP + Railway ) > Build and deploy a real-time chat app with Python, FastAPI, and JavaScript — from idea to production, all inside Warp. Note In this tutorial, we’ll follow along with Tech With Tim’s *Advanced Vibe Coding Tutorial w/ Warp* video.\ \ You’ll learn how to use **Warp**, the *agentic development environment*, to build and deploy a fullstack AI-driven app from scratch — including setup, debugging, and deployment using **GitHub MCP servers**. ![Advanced Vibe Coding Tutorial w/ Warp (Build & Deploy Apps)](https://i.ytimg.com/vi/Pxp9mB51U-A/sddefault.jpg) ### Overview [Section titled “Overview”](#overview) This video shows how to go from **idea → working web app → production deployment**, all inside Warp.\ The project: a **real-time chat application** built with **Python (FastAPI)** and a **JavaScript frontend**, deployed through **Railway**, and integrated with **GitHub** via **MCP (Model Context Protocol)**. 1. #### Setup & Installation [Section titled “Setup & Installation”](#setup--installation) Note Warp is free for Mac, Linux, and Windows. Download it from [https://warp.dev](https://warp.dev/) and sign in with an account. Once you open Warp, you’ll see three core modes: * **Auto Mode** – Detects whether you’re typing a command or an AI prompt * **Terminal Mode** – For standard shell commands only (`ls`, `pwd`, etc.) * **Agent Mode** – For conversational AI prompts (`build me an app`, `add feature X`, etc.) You can switch modes using the top-bar buttons. Pro tip: Enable voice input for natural prompting or attach screenshots when debugging UI issues. 2. #### Generate an App Idea [Section titled “Generate an App Idea”](#generate-an-app-idea) Warp supports *planning models*, where the AI generates a detailed roadmap before coding. ```plaintext I would like to make something of simple to medium complexity that I could finish in about 30 minutes. I want this to be web based. I want to have some kind of interface and some kind of backend. Can you give me a fun idea that's not going to be too complicated to build out and to eventually deploy? ``` The AI suggested several projects, like a personal mood tracker, quick poll creator, recipe randomizer, and more.\ \ Chosen idea we went with: **a real-time chat application**. 3. #### Create a Development Plan [Section titled “Create a Development Plan”](#create-a-development-plan) Prompt: ```bash I like idea one. Can you come up with a detailed plan on how to build this? ``` Warp’s agent generated a plan for: * A **frontend** (UI for chat rooms and messages) * A **backend** (FastAPI server for real-time communication) * Database integration and planned deployment steps You can refine or expand the plan interactively by prompting: ```plaintext Make this more detailed. ``` And get back something like this: ```plaintext Here's your development roadmap: 🏗️ Architecture Decisions Frontend Options: • React + Socket.IO Client (recommended for rich UI) • Vue.js + Socket.IO Client • Vanilla JS + WebSockets (simpler but limited) Backend Options: • Node.js + Socket.IO + Express (most popular for real-time) • Python + Flask-SocketIO • Go + Gorilla WebSocket Database: • MongoDB (flexible for chat messages) • PostgreSQL (structured data with JSON fields) • Redis (for session management and caching) 🚀 Recommended Tech Stack 📋 Core Features to Implement 1. Real-time messaging (Socket.IO) 2. User authentication (JWT) 3. Multiple chat rooms 4. Online user presence 5. Message history 6. Typing indicators 7. File/image sharing (optional) 🛠️ Development Steps 1. Create project in ~/Documents/Coding_Projects/realtime-chat 2. Set up Node.js backend with Socket.IO 3. Create React frontend with real-time connection 4. Implement user auth and room management 5. Add message persistence and history 6. Style UI and add advanced features ``` At any point, you can go into the plan and start directly modifying it. And when you’re ready, you can tell Warp to: ```bash Please execute this plan. ``` 4. #### Allow Autonomous Execution [Section titled “Allow Autonomous Execution”](#allow-autonomous-execution) Once Warp starts executing, you can let Warp run commands automatically: 1. Go to **Settings → AI → Agents** 2. Change **“Always Ask”** → **“Always Allow”** 3. Ensure restricted commands (e.g., `rm -rf`) remain blocked This enables autonomous execution for safe, fast iteration. Warp will run shell commands, create directories, initialize files, and write code. 5. #### Running the App [Section titled “Running the App”](#running-the-app) First, you can click into any file, like `main.py` to edit it directly in Warp. Warp displays your file directly in the app for easy editing, similar to any regular IDE experience. ![Editing main.py directly in Warp's built-in code editor](/_astro/Screenshot-2025-10-07-at-10.44.14-AM.c7uUira4_Z8RrCz.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) You can also ask Warp to run the app and test locally: ```plaintext Can you run this app for me so I can test it? Tell me how to view it. ``` It’s possible (like in the video) for an error to occur (e.g., Internal Server Error). If that happens, y you can simply debug conversationally: ```bash I’m getting an internal server error. Can you fix this? ``` And Warp can fix the issue and rerun the app automatically. 6. #### Adding New Features [Section titled “Adding New Features”](#adding-new-features) To enhance the app, request features conversationally: ```plaintext Can you add emoji reactions to the messages? ``` Warp will modify frontend and backend code, updating WebSocket logic for real-time reactions. After testing, multiple users can now react to messages in the chat interface. 7. #### Preparing for Deployment [Section titled “Preparing for Deployment”](#preparing-for-deployment) Warp integrates directly with version control and cloud deployers via **MCP servers**. Connect GitHub MCP: 1. Go to **Settings → AI → MCP Servers → Add** 2. Add a JSON block for GitHub MCP: ```json { "github": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${}" } } } ``` 3. Generate a GitHub personal access token (Settings → Developer Settings → Tokens) * Enable scopes for: `repo`, `workflow`, `secrets`, `pull_request`, and `environments`. Save and restart Warp. Then tell the agent: ```plaintext Can you make a new remote repo for me and upload my code? ``` Warp uses Git commands automatically: ```bash git init git add . git commit -m "Initial commit" git remote add origin ... git push ``` 8. #### Deploying via Railway [Section titled “Deploying via Railway”](#deploying-via-railway) Prompt: ```plaintext I have a FastAPI application built with Python. I want to deploy this. It just has an integrated frontend with JavaScript, HTML, and CSS. What’s the easiest way to do that? Can you assist me? ``` Warp recommends **Railway** and walks through: * Creating a Railway account * Connecting your GitHub repo * Deploying directly from GitHub * Generating a public domain Once deployed, test it in your browser — you’ll see your live chat app with emoji reactions working in real time. ### Appendix [Section titled “Appendix”](#appendix) * [Github MCP Server](https://github.com/github/github-mcp-server) * [Docker Desktop download](https://www.docker.com/products/docker-desktop/) * [Railway](https://railway.com/) # Building a Slackbot > Set up a self-hosted Warp Slackbot that answers repo questions and opens PRs directly from Slack using Docker and GitHub integration. This guide shows you how to spin up a [Warp Slackbo**t**](https://github.com/warpdotdev/warp-slackbot-public) you can mention in Slack to answer questions about your repositories and even open pull requests. It runs securely in Docker and connects directly to your Slack workspace. The setup takes just a few steps — clone, configure, and run — and requires minimal setup beyond providing your own Slack, GitHub, and Warp credentials. ## Why this is useful [Section titled “Why this is useful”](#why-this-is-useful) * Run a self-hosted Slack bot that connects your team’s repos and Warp agents. * Provide your team with a coding assistant that can answer repo questions or help with PRs directly in Slack. ## Quickstart Setup [Section titled “Quickstart Setup”](#quickstart-setup) 1. #### Clone the repository [Section titled “Clone the repository”](#clone-the-repository) Clone the public repo and navigate into it: ```bash git clone https://github.com/warpdotdev/warp-slackbot-public.git cd warp-slackbot-public ``` This repository includes all required configuration templates, the Docker setup, and the app manifest you’ll use to create your Slack bot. 2. #### Configure environment variables [Section titled “Configure environment variables”](#configure-environment-variables) Copy the provided example environment file and fill in your credentials: ```bash cp .env.example .env ``` Then open `.env` and fill in the following values: * `SLACK_BOT_TOKEN` – Your bot token from Slack, which starts with `xoxb-`. You can find this under your Slack app’s **OAuth & Permissions** page. * `SLACK_APP_TOKEN` – Your app-level token from Slack, which starts with `xapp-`. Create this in your Slack app’s **Basic Information → App-Level Tokens**, and ensure it has the `connections:write` scope (required for Socket Mode). * `GITHUB_PAT` – Your GitHub Personal Access Token (PAT) with `repo` access, so the bot can read and clone your repositories. * `WARP_API_KEY` – Your Warp API key that allows the bot to connect to Warp’s agentic environment and execute prompts. You only need to create these once — after saving your `.env` file, Docker will automatically read them when you run the bot. 3. #### Configure repositories [Section titled “Configure repositories”](#configure-repositories) Copy the provided repository configuration template: ```bash cp repos.yaml.template repos.yaml ``` Then open `repos.yaml` and list the repositories you want the bot to monitor, for example: ```yaml repositories: - url: "myorg/backend" branch: "main" - url: "myorg/frontend" branch: "develop" ``` This file tells the bot which repositories to clone locally and keep up to date. It’s how the bot knows where to pull context from when you ask it repo-related questions. What’s happening behind the scenes: * The bot will use your GitHub PAT to clone each listed repo. * It stores the repositories in a persistent Docker volume so you don’t have to re-clone each time. * The bot indexes those repos for context so it can respond intelligently when mentioned in Slack. 4. #### Understand the Slack App Manifest [Section titled “Understand the Slack App Manifest”](#understand-the-slack-app-manifest) The file `slack_app_manifest.json` defines everything needed to create your Slack app quickly — including permissions, event subscriptions, and bot scopes. When creating your Slack app, you can paste the contents of this file directly into the **Slack App → Create from Manifest** interface. It configures the bot to: * Listen for mentions and thread replies (`app_mention` events) * Run via Socket Mode (secure WebSocket connection) * Send and receive messages in channels where it’s invited 5. #### Run the bot in Docker [Section titled “Run the bot in Docker”](#run-the-bot-in-docker) Once your `.env` and `repos.yaml` files are ready, start the bot: ```bash docker-compose up --build ``` This builds the container, authenticates with Slack and GitHub, and starts listening for messages. It will log all activity in your terminal so you can confirm it’s running. 6. #### Test in Slack [Section titled “Test in Slack”](#test-in-slack) * Invite your bot to a channel in Slack. * Mention it directly or in a thread to trigger it — for example: ```plaintext @Warp analyze the recent changes in the main branch @Warp help me review this PR ``` * The bot will pull context from your configured repositories and reply with AI-assisted insights using Warp’s agentic platform. ## What happens on startup [Section titled “What happens on startup”](#what-happens-on-startup) * Reads `.env` and `repos.yaml`. * Authenticates to Slack (Socket Mode and Web API). * Authenticates to GitHub and clones the listed repos. * Starts listening for `app_mention` events and threaded messages. * Routes context and commands to Warp’s agent backend. You can stop the bot anytime with `Ctrl + C` or run it persistently with: ```bash docker-compose up -d ``` # Building Warp's Input - With Warp > Watch how a Warp designer uses Warp's own agent to locate, modify, and test a UI component change in a large Rust codebase. *Speaker: Dave, Product Design Lead at Warp* ![YouTube video](https://i.ytimg.com/vi/ySzUj7kMZ64/sddefault.jpg) ### The Challenge [Section titled “The Challenge”](#the-challenge) Redesigning the input was tricky because it’s the primary interface developers use all day, every day.\ Everyone had opinions — and expectations — about how it should look and behave. So, Peter (a product designer on my team) and I iterated on multiple designs using Figma. Once we landed on a version we liked, we shared it internally.\ Most people were excited, but engineering resources were stretched thin — focused on improving agent-mode quality and prepping the Agentic Development Environment. So I thought: *“What if I just Warp it?”* #### Step 1. Locating the Git Diff Chip Code [Section titled “Step 1. Locating the Git Diff Chip Code”](#step-1-locating-the-git-diff-chip-code) Inside the universal input, there’s a small Git Diff chip — it shows your current branch and open changes. It was one pixel too tall. That tiny visual bug drove me nuts, so I used Warp to find where it lived. Warp searched across the entire codebase and found references inside: * `displaychip.rs` * Related render and configuration files It used a combination of semantic search, code indexing, and traditional grep to pinpoint the exact implementation. *** #### Step 2. Modifying the Font Size [Section titled “Step 2. Modifying the Font Size”](#step-2-modifying-the-font-size) Once Warp located the implementation, I asked it to reduce the font size by 1 pixel. Warp automatically edited the relevant lines: * Found the current setting (`system_font_size - 1`) * Adjusted it to (`system_font_size - 2`) I reviewed the diffs to confirm everything looked good. *** #### Step 3. Building and Testing the Change [Section titled “Step 3. Building and Testing the Change”](#step-3-building-and-testing-the-change) Next, I rebuilt the app using: ```bash cargo run ``` # Creating Rules For Agents > Create reusable Rules in Warp to encode team conventions — like Dockerfile patterns or dependency management — so agents follow your standards. *Speaker: Maggie — Engineer at Warp* ![YouTube video](https://i.ytimg.com/vi/OyrpkeL6WNY/sddefault.jpg) ### 1. Starting with Agent Mode Evals [Section titled “1. Starting with Agent Mode Evals”](#1-starting-with-agent-mode-evals) I’m currently adding **Evals** (short for evaluations) to test a new feature I’ve been building. Warp quickly surfaces helpful context — like notebooks and internal docs — written by teammates on how to run Evals.\ \ This makes onboarding onto new tasks fast and collaborative. *** ### 2. Adding a Rust Syntax Eval [Section titled “2. Adding a Rust Syntax Eval”](#2-adding-a-rust-syntax-eval) Next, I want to add an Eval that tests for Rust syntax errors.\ So I ask Warp to update the Dockerfile to include Rust. However, the generated Dockerfile installs Rust differently than I wanted.\ It also includes `gcc` and `python` via a single `apt-get` line, which doesn’t follow our internal conventions. *** ### 3. Stashing Changes & Creating a Rule [Section titled “3. Stashing Changes & Creating a Rule”](#3-stashing-changes--creating-a-rule) Instead of fixing this manually every time, I decide to stash the current changes and create a reusable Rule that encodes our convention: > Rule Example:\ > “Always use `apt-get` to install packages and follow the same pattern used for installing Python and GCC.” This way, future sessions — and even other teammates — can automatically apply the same standard. *** ### 4. Applying the Rule [Section titled “4. Applying the Rule”](#4-applying-the-rule) Now, I just ask Warp’s Agent Mode to try again! Warp re-runs the request, follows the new rule, and correctly adds Rust with the right syntax. The code now matches our conventions. # How To: Configure YOLO and Strategic Agent Profiles > Configure custom agent profiles in Warp to control planning depth, autonomy, and execution speed — demonstrated with YOLO and Strategic examples. Note This tutorial explains how **Agent Profiles** in Warp influence behavior, autonomy, and planning when coding with AI — demonstrated through the NFL Predictor app example. ![YouTube video](https://i.ytimg.com/vi/iD0R-8fY-tY/sddefault.jpg) 1. #### Define the Project [Section titled “Define the Project”](#define-the-project) I want to create an app that scrapes **NFL data** from the past decade, processes stats like team scores and player performance, and predicts future wins. The prompt specifies: * Data sources and constraints * Dependencies and CLI commands * Implementation details and deliverables ```plaintext Role & Goal You are my AI coding copilot inside Warp. Create a production-ready Python project that ingests 2015–2025 NFL data to power future win projections. Specifically: acquire week-level player and team stats, acquire game schedules + final scores (to determine weekly winners), and assemble a clean analytics dataset I can build models on later. Prefer stable/public data sources over brittle HTML scraping. Where scraping is unavoidable, respect robots.txt, add rate-limiting, and make scraping pluggable/optional. Primary data sources: nflverse/nflreadr static files for weekly player stats and schedules (CSV/Parquet over HTTPS). Tech constraints: Python 3.11+, no notebooks in the main flow. Deterministic, idempotent pipelines. Strong typing (pydantic) + docstrings. Parquet as the storage format; small sample CSVs for quick checks. CLI via Typer (warp run … friendly). Logging (structlog), retry/backoff (tenacity), polite rate-limits. Zero secrets required for core pipeline. Deliverables: A fully initialized repo with the scaffold above. Implemented CLI + modules to download/ingest 2015–2025 data, compute/normalize fantasy PPR, produce winners by week, and write Parquet outputs. One sample run in the README showing commands and example output counts. If successful, run full 2015–2025. Print a summary table (by season: games, players, weeks) at the end. ``` 2. #### Configure the Strategic Agent [Section titled “Configure the Strategic Agent”](#configure-the-strategic-agent) **Base Model:** GPT‑5 (for reasoning)\ **Planning Model:** Claude 4 Opus (for detailed breakdowns) | Action | Permission | | ---------------- | ------------- | | Apply code diffs | Agent decides | | Read files | Agent decides | | Create plans | Always allow | | Execute commands | Always ask | Behavior: * The agent starts by asking clarifying questions: > “Do you want me to scrape both player stats and schedules or just one first?”\ > “Where should raw data be stored — locally or in a database?” * It builds a **14-step plan** covering setup, dependencies, validation modules, and pipelines. * When the agent requests NFL schedule URLs, the chosen source returns 404 errors. * Execution halts — showing that the **Strategic** profile prioritizes verification over progress. 3. #### Configure the YOLO Agent [Section titled “Configure the YOLO Agent”](#configure-the-yolo-agent) **Permissions:** | Action | Permission | | ------------------------ | ------------ | | Apply diffs / read files | Always allow | | Create plans | Never | | Execute commands | Always allow | Behavior: * The YOLO agent skips detailed planning. * It produces a **10-step plan** that covers essentials only: * Initialize project * Build CLI * Ingest player data * Compute scores and transformations * Instead of using unstable schedule URLs, it focuses on reliable player endpoints — completing a functional data pipeline. 4. #### Compare Outcomes [Section titled “Compare Outcomes”](#compare-outcomes) | Aspect | Strategic Agent | YOLO Agent | | ----------- | ----------------------- | -------------------------------------- | | Planning | Detailed (14 steps) | Minimal (10 steps) | | Interaction | Clarifications required | Autonomous | | Speed | Slower due to checks | Faster iteration | | Output | Stalled on invalid URLs | Working player dataset + summary table | # How To: Create Project Rules for an Existing Project > Create and maintain an AGENTS.md project rules file so coding agents always understand your project's setup, commands, architecture, and conventions. Note This educational module is built **only** from the transcript. It shows how to create and maintain a `Warp.md` file so Warp agents always understand your project’s setup, commands, architecture, and structure. ![YouTube video](https://i.ytimg.com/vi/SCYovBn4TnM/sddefault.jpg) *** ## What Project Rules Are [Section titled “What Project Rules Are”](#what-project-rules-are) A **Project Rules** file (`Warp.md`) acts as your project’s AI onboarding guide. Instead of re‑explaining your setup on every prompt, you document it once and Warp will always have that context. The transcript demo walks through creating the file, opening it in a side editor, and organizing it with standard Markdown headings for clear sections. *** ## Generate `Warp.md` [Section titled “Generate Warp.md”](#generate-warpmd) Run the following **verbatim** prompts in Warp to create and verify your rules file, then open it in the editor: ```plaintext /init ``` ```plaintext /open-project-rules ``` * `/init` generates a starter `Warp.md` in your project root. * `/open project rules` opens it in a side editor where you can scroll and edit the content. You’ll get something that looks like this: WARP.md ````markdown This file provides guidance to WARP (warp.dev) when working with code in this repository. ## Project Overview Share Your Brewfiles is an Astro-based website that allows developers to share and discover their Homebrew package lists (Brewfiles). The platform generates personality profiles based on package usage patterns and provides a leaderboard of popular packages. ## Core Architecture * **Frontend**: Astro 4 with React 18 components, TypeScript, and Tailwind CSS * **Backend**: Astro API routes with Firebase integration * **Database**: Firebase Firestore for storing brewfiles, user data, and personality summaries * **Deployment**: Vercel with serverless functions * **Styling**: Custom Tailwind configuration with dark theme and gradient animations ## Key Components ### API Routes (`src/pages/api/`) * `getBrewfiles.json.ts` - Retrieves all brewfiles or a specific brewfile by ID, triggers personality generation * `uploadBrewfile.ts` - Handles brewfile uploads with GitHub OAuth integration * `getRankedPackages.json.ts` - Generates leaderboard data for popular packages * `updatePersonality.ts` - Updates personality summaries for users * `exchangeCodeForAccessToken.ts` - GitHub OAuth token exchange * `logSearch.json.ts` - Analytics for search functionality ### Core Library Functions (`src/lib/`) * `generatePersonality.ts` - Complex algorithm that analyzes brewfile packages and assigns personality types (15 different personalities) * `personalityBuckets.ts` - Defines personality type metadata and descriptions * `validateBrewfileData.ts` - Data validation for brewfile uploads * `totalBrewData.ts` - Aggregates package statistics for leaderboards ### Type System (`src/types/`) * `brews.ts` - Main data structures for brewfiles, users, and entries * `personality.ts` - Personality analysis types and enums * `packageEntry.ts` - Package metadata structures ## Development Commands ### Setup ```bash # Install dependencies npm install # Set up environment (Firebase config is public but consider security) # No additional env setup needed for development # Development server npm run dev ``` ### Development Workflow ```bash # Start development server with Astro npm run dev # Build for production npm run build # Preview production build npm run preview # Run Astro CLI commands npm run astro ``` ### Testing API Endpoints ```bash # Test brewfile retrieval curl "http://localhost:4321/api/getBrewfiles.json" # Test specific brewfile by ID curl "http://localhost:4321/api/getBrewfiles.json?id=DOCUMENT_ID" # Test package rankings curl "http://localhost:4321/api/getRankedPackages.json" ``` ## Architecture Notes ### Personality Generation System The core feature analyzes brewfile packages against a curated dictionary (`labelledBrewfiles.ts`) that categorizes packages by: - Developer type (Backend, Frontend, DevOps, Security, Data, General) - Package characteristics (AI tools, organization tools, customization, popularity rank) - Legacy/modern status The system calculates percentage distributions and applies complex rules to assign one of 15 personality types (Minimalist, Golden Retriever, Pragmatist, Trendy, AI, Architect, Artist, Traditionalist, Retro, Bob the Builder, Marie Kondo, Crazy Scientist, Trailblazer, Security, Wallflower). ### Firebase Integration - Uses Firestore for data persistence - Collection: `brewfiles` stores user brewfiles with personality summaries - Real-time personality generation happens asynchronously after uploads - GitHub OAuth integration for user authentication ### Path Alias System Uses TypeScript path mapping with `@/*` pointing to `./src/*` for clean imports. ### Astro Configuration - Server-side rendering with Vercel adapter - React integration for interactive components - Sitemap generation for SEO - Prefetch enabled for performance ## Development Environment Setup ### Prerequisites - Node.js (version compatible with Astro 4) - Access to Firebase project (config is in source but consider security implications) - GitHub OAuth app for testing upload functionality ### Local Development Notes - The site uses server-side rendering so API routes work in development - Firebase config is currently in source code - be aware of security implications - GitHub OAuth integration requires valid access tokens for uploads - Personality generation is computationally expensive with large datasets ### Custom Tailwind Configuration - Dark theme with custom color palette (`bkg: #111111`) - Custom accent colors (teal, orange, green, pink, blue variants) - Marquee animations for scrolling elements - Responsive typography with fluid scaling - Container queries support ## File Structure Navigation - src/ - pages/ - api/ Astro API routes (serverless functions) - index.astro Homepage with hero and marquee - brewfiles.astro Search and browse brewfiles - leaderboard.astro Package popularity rankings - components/ Astro and React components - lib/ Core business logic and utilities - types/ TypeScript type definitions - data/ Static data and package dictionaries - firebase/ Firebase configuration ## Common Development Tasks ### Adding New Personality Types 1. Update `DeveloperPersonalityType` enum in `src/types/personality.ts` 2. Add detection function in `src/lib/generatePersonality.ts` 3. Update `personalityBuckets.ts` with new personality metadata 4. Add corresponding image to `public/images/` ### Modifying Package Analysis - Update `labelledBrewfiles.ts` to modify package categorization - Adjust percentage thresholds in personality detection functions - Test with different brewfile compositions ### API Route Development - All routes in `src/pages/api/` become serverless functions on Vercel - Use `export const prerender = false;` for dynamic routes - Handle errors consistently with try/catch blocks ```` *** ## Keep the File Lean and Intentional [Section titled “Keep the File Lean and Intentional”](#keep-the-file-lean-and-intentional) 1. #### Start Lean [Section titled “Start Lean”](#start-lean) Everything in `warp.md` is **prepended to your prompt**. A longer file consumes more tokens and can increase compute cost. Keep only what truly matters. 2. #### Iterate and Maintain [Section titled “Iterate and Maintain”](#iterate-and-maintain) Start with `/init` boilerplate, then treat the file as a **living document**. Add the rules that help your team ship faster (e.g., branching, PR guidelines) and prune anything redundant. Caution If the file grows large (e.g., **500+ lines**), run it through a **prompt optimizer** to catch duplication, remove overlaps, and slim it down — exactly as advised in the transcript. *** ## Use Sub‑directory Rules for Monorepos [Section titled “Use Sub‑directory Rules for Monorepos”](#use-subdirectory-rules-for-monorepos) For large repos, you can generate localized rule files in sub‑trees. Navigate into a subfolder and run `/init` again to create a **directory‑scoped `Warp.md`** tailored to that area: Tip Going forward, when you give Warp a task, it will carry this context automatically — no re‑explaining needed. # How To: Set Coding Best Practices > Use Warp Rules to enforce coding style, TypeScript conventions, and documentation quality across AI-generated code. Learn how to use Warp’s Rules to enforce coding style, documentation quality, and consistency across projects. ![YouTube video](https://i.ytimg.com/vi/AuM2OIvXlnY/sddefault.jpg) *** ## Intro [Section titled “Intro”](#intro) This tutorial teaches you how to create coding Rules that make AI follow your team’s **best practices** automatically.\ \ By specifying formatting, style preferences, and documentation standards, Warp ensures consistent, high-quality code across your repositories. *** 1. #### The Problem [Section titled “The Problem”](#the-problem) Developers often have different habits — formatting styles, TypeScript conventions, or comment quality.\ Without clear rules, AI-generated code can be inconsistent or hard to maintain. 2. #### The Rule Setup [Section titled “The Rule Setup”](#the-rule-setup) Define Rules that enforce formatting, type preferences, and doc quality. **Example Rule** ```plaintext Rule: Code Authoring Standards - Always format and check work before returning results. - Prefer `types` over `interfaces` in TypeScript. - Apply concise, human-readable JS Docs using the Hemingway test. ``` Note The **Hemingway test** ensures code comments are simple and clear — short sentences, active voice, and no unnecessary complexity. 3. #### Benefits [Section titled “Benefits”](#benefits) * Encourages readable, maintainable code * Improves documentation clarity * Prevents style drift across AI contributions # How To: Set Coding Preferences with Rules > Store your package manager, environment tool, and CLI preferences as Warp Rules so agents automatically use pnpm, miniconda, or your preferred tools. Learn how to use Warp’s Rules feature to define your personal environment and tool preferences for every coding session. ![YouTube video](https://i.ytimg.com/vi/zWvRB2zWr-4/sddefault.jpg) This tutorial teaches you how to customize your development setup using **Warp’s Rules** — ensuring agents always work in your preferred environment. Instead of constantly reminding them which package manager or environment to use, you can **store those preferences as persistent Rules** that apply automatically across projects. 1. #### The Problem [Section titled “The Problem”](#the-problem) When using AI tools to write or modify code, they often default to outdated or undesired tools.\ For example, many agents still use **npm** instead of **pnpm** — or **pip** instead of **miniconda**. Warp fixes this by letting you define your preferences once, and then applying them automatically whenever your agent runs commands. 2. #### The Rule Setup [Section titled “The Rule Setup”](#the-rule-setup) You can set Rules for how you want the AI to handle environments, dependencies, and commands. **Example Rule** ```plaintext Rule: Environment Preferences - Always use pnpm for Node.js projects unless the project already uses npm. - Default to miniconda for Python environments. - Use the Tauri CLI when building desktop apps. ``` This ensures the agent automatically chooses the right package manager or environment — no extra prompts required. 3. #### Supported Use Cases [Section titled “Supported Use Cases”](#supported-use-cases) You can apply Rules to: * Package managers (e.g., npm → pnpm) * Environment tools (e.g., virtualenv → miniconda) * Framework defaults (e.g., Next.js over React) * CLI utilities or custom build tools # How To: Set Tech Stack Preferences with Rules > Define your preferred frameworks and tech stack in Warp Rules so agents consistently use Astro, SvelteKit, Vite, or your tools of choice. Learn how to guide Warp’s AI to use your favorite tech stack when scaffolding new apps or generating code. ![YouTube video](https://i.ytimg.com/vi/W5B6MhZsZ_4/sddefault.jpg) *** ## Intro [Section titled “Intro”](#intro) This tutorial walks you through teaching Warp’s AI your **preferred technologies** so it consistently uses the frameworks and stacks you care about. By setting up tech stack Rules, you make sure every new project follows your conventions — whether you prefer **Astro**, **SvelteKit**, **Next.js**, or something else. *** ## The Problem [Section titled “The Problem”](#the-problem) When you ask AI to scaffold a new web app, it often defaults to **React** and **Express**, or other older stacks.\ This creates friction when your workflow is based on modern tools or opinionated frameworks. Warp solves this by letting you **store your stack preferences** directly as Rules. *** ## The Rule Setup [Section titled “The Rule Setup”](#the-rule-setup) Create a simple Rule that defines your favorite frameworks for each project type. ### Example Rule [Section titled “Example Rule”](#example-rule) ```plaintext Rule: Tech Stack Preferences - Use Astro for websites. - Use SvelteKit for desktop apps. - Prefer Vite for build tooling. - Avoid legacy stacks like Create React App or Express. ``` Once added, Warp’s AI automatically applies these defaults when generating new projects or updating existing ones. Note Think of it like setting a default coding personality for your agent. *** ## Why It Matters [Section titled “Why It Matters”](#why-it-matters) Tip Defining your stack preferences helps the AI: * Generate **consistent boilerplates** * Follow your **current tech standards** * Skip outdated or irrelevant dependencies # How to set up self-serve data analytics with Skills > Set up a self-serve data analytics workflow in Warp using two community Skills that map questions to dbt models and structure reproducible analyses. Self-serve data analytics means anyone on your team can ask a data question and get a trustworthy answer, without pinging the data team. This guide sets up that workflow using two community Skills that chain together: one resolves vague questions to the right BigQuery tables, and the other structures deep-dive analyses into reproducible folders. Plan on about 10 minutes for initial setup, plus time to customize the model index for your warehouse. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **Warp** — Install from [warp.dev](https://www.warp.dev/download) if you don’t already have it. * **A BigQuery data warehouse with dbt models** — The Skills as published assume BigQuery and dbt. You can adapt them to Snowflake, Redshift, Databricks, or a non-dbt setup. See [Adapting to your stack](#adapting-to-your-stack). * **The BigQuery CLI (`bq`)** — Installed as part of the [Google Cloud SDK](https://cloud.google.com/sdk/docs/install). Agents call it directly to query the warehouse, so no MCP server is required. * **A Git repository where the Agent will work** — Warp auto-discovers Skills from `.agents/skills/` in your current working directory up through the repo root. See [Skills](https://docs.warp.dev/agent-platform/capabilities/skills/) for the full list of supported directories and how discovery works. ## Walkthrough video [Section titled “Walkthrough video”](#walkthrough-video) In this 40-minute livestream, Warp’s data team demonstrates the workflow end-to-end, including the two Skills you’ll install below and a third pattern (running the same Skills from Slack via an Oz cloud agent). Feel free to skip ahead if you prefer to follow the written steps. ![YouTube video](https://i.ytimg.com/vi/WyMTjXSplRU/sddefault.jpg) ## 1. Install the two Skills [Section titled “1. Install the two Skills”](#1-install-the-two-skills) Warp automatically discovers any Skill stored under `.agents/skills/` in your repo, so committing the two directories makes them available to every teammate’s Agent runs. Clone the public [warpdotdev/oz-skills](https://github.com/warpdotdev/oz-skills) repo and copy the two Skill directories into your own dbt repo: ```bash cd /path/to/your/dbt-repo mkdir -p .agents/skills git clone https://github.com/warpdotdev/oz-skills.git /tmp/oz-skills cp -r /tmp/oz-skills/.agents/skills/dbt-model-index .agents/skills/ cp -r /tmp/oz-skills/.agents/skills/analysis-artifacts .agents/skills/ ``` Verify both Skills landed: ```bash ls .agents/skills/ # analysis-artifacts dbt-model-index ``` Commit the Skills. Once committed to your repo, they are available to the whole team: ```bash git add .agents/skills && git commit -m "Add self-serve analytics skills" ``` ## 2. Customize the dbt model index [Section titled “2. Customize the dbt model index”](#2-customize-the-dbt-model-index) The [`dbt-model-index`](https://github.com/warpdotdev/oz-skills/blob/main/.agents/skills/dbt-model-index/SKILL.md) Skill is a template that you will need to fill in with details about your own models. This Skill teaches the Agent which tables answer which question types, so it’s important to spend time on customization. Detailed “Useful for” descriptions make the Skill most effective. Open `.agents/skills/dbt-model-index/SKILL.md` and replace the template placeholders with real models. For each one, include: * The table name (backtick-formatted) * A 1- to 2-sentence description of its grain * “Useful for:” bullets covering the question types it answers A filled-in entry might look like this: ```markdown ### `users_daily` One row per user per day, with activity signals and plan type. **Useful for:** - Daily, weekly, or monthly active user counts - Retention and churn by plan tier - Joining to revenue models as the canonical user dimension ``` Fill in the domains that cover your most common questions first (typically Users, Activity, and Revenue). You can expand the index over time as you notice the Agent guessing at tables. Don’t skip the **Important Notes** section at the bottom of the Skill. Documenting your standard filters (e.g., `where not is_internal_user`), your fully-qualified project path, your partition fields, and any plan or tier values prevents the Agent from accidentally fanning out joins, scanning entire partitioned tables, or returning numbers polluted by test accounts. After you complete this step, the Agent has a curated map from question to table and will consult it before writing any BigQuery SQL. ## 3. Review the analysis-artifacts Skill [Section titled “3. Review the analysis-artifacts Skill”](#3-review-the-analysis-artifacts-skill) The [`analysis-artifacts`](https://github.com/warpdotdev/oz-skills/blob/main/.agents/skills/analysis-artifacts/SKILL.md) Skill is workflow scaffolding. It tells the Agent how to structure a deep-dive analysis: plan first, save every material SQL query to `assets/queries/`, save visualizations to `assets/visualizations/`, and write a readable README with a Problem Statement, TL;DR, Cohorts Definition, per-step sections, and Key Takeaways. No customization is needed to start using it. When the Agent invokes it, you’ll end up with a directory like: ```plaintext analyses/ └── 2026-04-ai-usage-by-os/ ├── README.md └── assets/ ├── queries/ │ └── ai_requests_by_os.sql └── visualizations/ ├── os_trend.py └── os_trend.png ``` That structure is what makes the analysis shareable. A teammate can read the README, click through to any SQL file, and reproduce or extend the work. ## 4. Ask a simple data question [Section titled “4. Ask a simple data question”](#4-ask-a-simple-data-question) With both Skills in place, start with a concrete lookup prompt. This exercises `dbt-model-index` without pulling in the deep-dive workflow. Open an Agent conversation inside your dbt repo and ask: ```plaintext How many unique users made AI requests yesterday? ``` The Agent will: 1. Consult `dbt-model-index` to find the right activity table. 2. Write a BigQuery query, applying any standard filters you documented (e.g., excluding internal users). 3. Run the query via the `bq` CLI. 4. Return a single number along with the SQL it ran. Verify the result by reviewing the query. If it used the wrong table or skipped a standard filter, your `dbt-model-index` entries for that domain need more detail. Update the Skill and try again. ## 5. Run a deep-dive analysis [Section titled “5. Run a deep-dive analysis”](#5-run-a-deep-dive-analysis) Now try a prompt that goes beyond a single lookup. The Agent recognizes this as a deep dive and invokes `analysis-artifacts`. ```plaintext Tell me about any recent trends in AI usage across different operating systems in the last month. ``` The Agent will: 1. Use `dbt-model-index` to resolve the right activity and OS dimensions. 2. Invoke `analysis-artifacts`, propose a plan, and wait for your approval. 3. Execute the plan step by step, saving queries and visualizations as artifacts. 4. Write a README summarizing the analysis end to end. The resulting README follows a consistent shape, roughly: ```markdown # AI usage trends by operating system (last 30 days) Author: Your Name Date: 2026-04-22 ## TL;DR One or two sentences capturing the headline finding. ## Problem Statement What the analysis set out to answer and why. ## Cohorts Definition Explicit definition of the groups being compared, including tenure, plan type, and observation windows. ## Step 1: Baseline volume by OS Narrative, embedded chart, and a link to the query in assets/queries/. ## Step 2: Week-over-week trend ... ## Key Takeaways Bulleted summary of what was learned and any follow-up questions. ``` Commit the new `analyses//` directory to your repo so it’s reviewable alongside your code. Anyone on the team can read it, verify the queries, or pick up where you left off. ## Adapting to your stack [Section titled “Adapting to your stack”](#adapting-to-your-stack) Both Skills were written for BigQuery and dbt, but the pattern generalizes. Here’s what to change: * **Non-BigQuery warehouse (Snowflake, Redshift, Databricks)** — Update the **Important Notes** section of `dbt-model-index/SKILL.md` with your warehouse’s fully-qualified table reference format, partition or clustering conventions, and standard filters. Replace `bq` references with your warehouse’s CLI (e.g., `snowsql`, `redshift-data`). * **No dbt** — The `dbt-model-index` Skill works for any warehouse schema, not just dbt. Rename it if you like, and treat the entries as a map over raw tables, views, or your semantic layer. * **Different modeling conventions** — Document your grain, tier or plan values, and internal-user filters explicitly in the Skill. Agents are good at following documented rules and bad at guessing them. The `analysis-artifacts` Skill is largely stack-agnostic. It structures outputs, not queries, so it works the same regardless of warehouse. ## Next steps [Section titled “Next steps”](#next-steps) You installed two community Skills, customized the model index for your warehouse, and ran both a simple lookup and a full deep-dive analysis. **Extend to Slack.** Wire the same two Skills into an Oz cloud agent configured with your dbt repo, and your teammates can ask data questions by @-mentioning Oz in a Slack channel, without opening a terminal. The Agent clones the repo, picks up the Skills from `.agents/skills/`, and replies in-thread. See the [Slack integration docs](https://docs.warp.dev/agent-platform/cloud-agents/integrations/slack/) and [Skills as Agents](https://docs.warp.dev/agent-platform/cloud-agents/skills-as-agents/) for setup. Explore related guides and features: * [Trigger reusable actions with saved prompts](/guides/configuration/trigger-reusable-actions-with-saved-prompts/) — another reusable Agent primitive, useful for scaffolding frequent data questions * [Create project rules](/guides/configuration/how-to-create-project-rules-for-an-existing-project-astro-typescript-tailwind/) — pair Skills with Rules to steer Agent behavior across your repo * [Skills](https://docs.warp.dev/agent-platform/capabilities/skills/) — full reference on Skills, discovery, arguments, and slash-command invocation * [warpdotdev/oz-skills](https://github.com/warpdotdev/oz-skills) — public repo with these two Skills and more # How To: Sync Your Monorepos > Define global Rules in Warp to keep monorepo schemas, server types, and client types automatically synchronized across repositories. Learn how to use Warp’s Rules system to connect interrelated repositories and automate type updates across your stack. ![YouTube video](https://i.ytimg.com/vi/bndY6opaA7w/sddefault.jpg) *** ## Intro [Section titled “Intro”](#intro) This tutorial teaches you how to define **global Rules** in Warp so your coding agent understands how your projects relate to one another. By linking monorepos (e.g., server, client, and shared API schemas), Warp automatically updates types and schemas across repos when you make a change in one place. Although this example uses Warp’s internal repos, the same workflow applies to any multi-repo setup. *** ## The Problem [Section titled “The Problem”](#the-problem) When projects are split into multiple repos — like backend, client, and shared schema — developers often forget to synchronize type changes manually. That’s error-prone and time-consuming. Warp solves this by teaching your **agent** the relationships between your repos through a global Rule. *** ## The Rule Setup [Section titled “The Rule Setup”](#the-rule-setup) Describe each repository and its connection to the others. ### Example Rule [Section titled “Example Rule”](#example-rule) ```plaintext We have three inter-related projects in ~/Repos: warp-internal (client-side application) warp-server (server application) warp-proto-apis (shared API schemas for each) When you update the schema types, push to git and update the installed types in the server and client by the commit hash. ``` Once defined, Warp automatically follows these instructions when a schema file is changed. 1. #### When the schema updates — update server types [Section titled “When the schema updates — update server types”](#when-the-schema-updates--update-server-types) `cd` into the server repository and run the appropriate commands to regenerate/update server-side types based on the changed schema. 2. #### When the schema updates — update client types [Section titled “When the schema updates — update client types”](#when-the-schema-updates--update-client-types) `cd` into the client repository and run the appropriate commands to regenerate/update client-side types so the client stays in sync with the schema changes. *** Tip Benefits * Keeps your **schema, server, and client** perfectly in sync * Reduces merge conflicts and version drift * Saves manual steps when committing or deploying # How To: Use Agent Profiles Efficiently > Compare Strategic and YOLO agent profiles side-by-side to choose the right balance of planning, safety, and speed for your project. Agent Profiles control how your coding agents behave in different contexts.\ They define what the agent can read, plan, or execute — and how much autonomy it has. To show how profiles change workflow, we’ll build an NFL Predictor App using two profiles: * Strategic Agent * YOLO Agent ![YouTube video](https://i.ytimg.com/vi/iD0R-8fY-tY/sddefault.jpg) *** ### Strategic Agent [Section titled “Strategic Agent”](#strategic-agent) Base Model: GPT-5\ Planning Model: Claude 4 Opus Configuration: * Apply code diffs → *agent decides* * Read files → *always allow* * Create plans → *always allow* * Execute commands → *ask first* When run: 1. The agent asks clarifying questions (e.g., *Do you want to scrape players and schedules?*) 2. Builds a detailed 14-step plan 3. Requests user input for environment variables It’s thorough and safe — but pauses often if you miss setup details. *** ### YOLO Agent [Section titled “YOLO Agent”](#yolo-agent) Configuration: * Apply code diffs → *always allow* * Read files → *always allow* * Create plans → *never* * Execute commands → *always allow* This agent skips long planning.\ It builds the project quickly, skipping over optional validation and focusing on essentials: * Data ingestion * Player stats * Scoring calculation It avoids brittle endpoints and produces a working dataset fast — though with fewer checks. *** ### Comparing the Two [Section titled “Comparing the Two”](#comparing-the-two) | Trait | Strategic Agent | YOLO Agent | | --------- | ------------------- | ------------------ | | Planning | Detailed (14 steps) | Minimal (10 steps) | | Safety | High | Low | | Speed | Moderate | Very fast | | Ideal For | Production projects | Quick prototypes | # Trigger Reusable Actions With Saved Prompts > Save and share prompts in Warp Drive to automate commits, code reviews, and PR creation across your team. ![YouTube video](https://i.ytimg.com/vi/pE15zjJmB4E/sddefault.jpg) ### 1. Automating Commits [Section titled “1. Automating Commits”](#1-automating-commits) When working on a PR, instead of typing long commit messages, you can use a saved prompt. Warp’s agent: * Runs a `git diff` and summarizes the change * Generates a clean commit message * Pushes it automatically to your branch You can view the saved prompt in Warp Drive → Team Prompts, where it shows: * Who created it * When it was last used * How many times it’s been run Because it’s saved in your team drive, anyone can reuse it. *** ### 2. Reviewing Code with Prompts [Section titled “2. Reviewing Code with Prompts”](#2-reviewing-code-with-prompts) Before creating a PR, you can run another saved prompt. This agent: * Reads your current branch * Reviews the diffs * Highlights logical or stylistic issues * Suggests improvements Example output: > “Logic bug detected — potential race condition in async handler.” Warp automatically surfaces real issues before you even open a PR — saving time and reducing back-and-forth with reviewers. *** ### 3. Opening a Pull Request Automatically [Section titled “3. Opening a Pull Request Automatically”](#3-opening-a-pull-request-automatically) Once your code looks clean, trigger your final saved prompt. Warp will: * Generate a PR title and description * Push the branch * Open the PR on GitHub * Even link related issues if found in commit messages *** ### 4. Sharing and Team Usage [Section titled “4. Sharing and Team Usage”](#4-sharing-and-team-usage) All saved prompts live in your Team Warp Drive, meaning: * Anyone can discover and run them * You can parameterize or modify them * Usage history and creator info are visible This makes it easy for teams to standardize common actions like code reviews, deployments, or build runs. # How to: Analyze Cloud Run Logs (gcloud) > Use Warp to pull, organize, and analyze Cloud Run production logs by severity with natural language prompts and automated Python scripts. Learn how to use Warp to retrieve, organize, and analyze production logs from your cloud servers — all with natural language prompts. ![YouTube video](https://i.ytimg.com/vi/GJ0NepZmmv8/sddefault.jpg) 1. #### Setting the Context [Section titled “Setting the Context”](#setting-the-context) Open Warp and enable **voice input** (optional) for hands-free prompting. Note Voice input is optional — only enable it if you prefer hands-free prompting. **Prompt** ```plaintext Use the warp-server-staging gcloud project and pull logs for the last 10 minutes from the warp-server Cloud Run instance. Organize them by info, warning, and error levels. Create a histogram across message types, and highlight the most concerning errors to investigate. ``` 2. #### Warp’s Agent in Action [Section titled “Warp’s Agent in Action”](#warps-agent-in-action) After you hit Enter: * Warp detects the command as an **Agent Mode** request. * It gathers project context (`warp-server-staging`). * Executes the necessary `gcloud` logging queries automatically. * Writes retrieved data to a temporary file for processing. 3. #### Automated Analysis [Section titled “Automated Analysis”](#automated-analysis) Warp’s agent generates a **Python script** on the fly to: * Parse logs * Count messages by severity * Output summary metrics Example output: ```plaintext 1,000 log entries total 980 info 11 warning 9 errors ``` You can view or fast-forward execution, or stop the process at any point. 4. #### Reviewing Results [Section titled “Reviewing Results”](#reviewing-results) Warp outputs a readable histogram and highlights anomalies.\ For example: > “Gemini AI error messages detected — worth reviewing.” You can expand each log group interactively or inspect the temporary Python code for debugging. # How To: Create a Production Ready Docker Setup > Use Agents in Warp to generate optimized Dockerfiles, docker-compose configs, and .dockerignore files for multi-stage production deployments. Learn how to use Warp’s AI to automatically build a clean, multi-stage Docker setup for both development and production. ![YouTube video](https://i.ytimg.com/vi/zdQdEauSF6Q/sddefault.jpg) This tutorial shows how to create a **complete Docker environment** in minutes using Warp.\ Warp’s AI can analyze your entire codebase, generate **Dockerfiles**, **.dockerignore**, and **docker-compose.yml** — all optimized for small image size and multi-service orchestration. Although this example uses a generic web app, the same pattern applies to **Python**, **Node.js**, **Go**, and other ecosystems. 1. #### The Challenge [Section titled “The Challenge”](#the-challenge) You’ve built your app and suddenly realize — it should have been containerized from the start.\ Manually configuring Docker files, image sizes, and environment variables takes time and breaks flow. 2. #### The Prompt [Section titled “The Prompt”](#the-prompt) Use this prompt inside Warp’s AI input: ```plaintext "Analyze my entire project directory structure, package files, and configuration to generate a complete production-ready Docker setup. I need: A multi-stage Dockerfile optimized for my specific language/framework with proper layer caching, security best practices, and minimal image size A docker-compose.yml for both development and production environments with all necessary services, networks, volumes, and environment variable handling A comprehensive .dockerignore file that excludes unnecessary files but keeps what's needed for the build Startup scripts and health check configurations Documentation explaining each Docker command and why specific choices were made Please detect my project type automatically and configure everything accordingly. Include comments explaining the optimization decisions." ``` Warp will detect frameworks, infer services, and produce a ready-to-run setup. 3. #### Review and Customize [Section titled “Review and Customize”](#review-and-customize) Warp outputs: * Optimized base images * Cached build layers * Correct dependency stages * Unified environment management You can easily adjust service names or ports in the generated compose file. # How To: Create Priority Matrix for Database Optimization > Prompt Warp to audit SQL queries, analyze execution plans, and generate a priority matrix ranking database optimizations by impact and effort. Learn how to generate a data-driven optimization matrix that ranks database issues by impact, risk, and effort. ![YouTube video](https://i.ytimg.com/vi/VgE5wgtDSnk/sddefault.jpg) 1. #### Intro [Section titled “Intro”](#intro) This tutorial teaches you how to prompt Warp to audit and optimize your **database performance** automatically. It analyzes SQL queries, identifies common inefficiencies, and generates a **priority matrix** for improvements. 2. #### The Problem [Section titled “The Problem”](#the-problem) When you tell AI to “optimize a query,” that could mean *anything* — faster, safer, or simpler.\ Instead, use Warp to clarify intent and return measurable outcomes. 3. #### The Prompt [Section titled “The Prompt”](#the-prompt) Paste this into Warp’s AI input: ````plaintext # **Comprehensive Database Query Analysis and Optimization Guide** This guide provides a structured, repeatable approach for analyzing, profiling, and optimizing database performance within your application. --- ## **PHASE 1: Query Discovery & Cataloging** ### **Step 1 — Identify All Queries** Scan the entire codebase and locate every SQL or ORM-based query. This includes: - All **raw SQL queries**, including stored procedures - **ORM-generated queries** (capture the actual SQL being produced) - **Dynamic query builders** and their permutations - **Background job queries** that may run at scale - **Admin or reporting queries** that could lock tables ### **Step 2 — Document Key Details** For each query discovered, record the following: - **File location and function name** - **Frequency of execution** (per request, batch job, or cron schedule) - **Typical data volume processed** --- ## **PHASE 2: Performance Analysis** For each identified query, generate and analyze a detailed **execution plan**. ### **Execution Plan Commands** ```sql -- PostgreSQL EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON); -- MySQL EXPLAIN FORMAT=JSON; ``` ### **Extract the Following Metrics** - Total execution time - Rows examined vs. rows returned ratio - Index usage (full table scans, index scans, seeks) - Join methods (nested loop, hash, merge) - Memory usage and temporary file creation - Buffer pool hit ratio --- ## **PHASE 3: Identify Specific Problems** ### **1. N+1 Query Detection** **Problem:** Loading users and their posts separately **Found in:** `/api/users/controller.js:45` **Impact:** 100 queries for 100 users instead of one batched query #### **Current Implementation** ```js const users = await db.query('SELECT * FROM users'); for (const user of users) { user.posts = await db.query('SELECT * FROM posts WHERE user_id = ?', [user.id]); } ``` #### **Optimized Version** ```js const usersWithPosts = await db.query(` SELECT u.*, COALESCE(json_agg(p.*) FILTER (WHERE p.id IS NOT NULL), '[]') AS posts FROM users u LEFT JOIN posts p ON p.user_id = u.id GROUP BY u.id; `); ``` --- ### **2. Missing Index Analysis** **Finding:** Full table scan on `orders` table (2M rows) **Query:** ```sql SELECT * FROM orders WHERE status = 'pending' AND created_at > ?; ``` **Recommendation:** ```sql CREATE INDEX idx_orders_status_created ON orders(status, created_at); ``` **Impact:** Query time reduced from **3.2s → 0.045s** --- ### **3. Inefficient JOIN Patterns** **Problem:** Queries join through unnecessary intermediate tables. **Solution:** Simplify relationships using direct joins or indexed subqueries where possible. --- ### **4. Subquery Optimization** **Inefficient Query:** ```sql SELECT * FROM products WHERE price > (SELECT AVG(price) FROM products WHERE category_id = p.category_id); ``` **Optimized (Using Window Function):** ```sql WITH product_stats AS ( SELECT *, AVG(price) OVER (PARTITION BY category_id) AS avg_category_price FROM products ) SELECT * FROM product_stats WHERE price > avg_category_price; ``` --- ## **PHASE 4: Advanced Optimizations** ### **Caching Strategies** Use caching for: - User-specific data with low update frequency - Expensive aggregations that can be pre-computed #### **Implementation** ```js // Add caching layer with TTL const getCachedOrQuery = async (key, query, ttl = 3600) => { const cached = await redis.get(key); if (cached) return JSON.parse(cached); const result = await db.query(query); await redis.setex(key, ttl, JSON.stringify(result)); return result; }; ``` --- ### **Recommended Connection Configuration** ```json { "connectionLimit": 50, "queueLimit": 100, "acquireTimeout": 30000, "waitForConnections": true, "idleTimeout": 300000, "enableKeepAlive": true, "keepAliveInitialDelay": 10 } ``` --- ### **Batch Operation Optimization** **Problem:** Records are inserted one by one **Found in:** `/jobs/import-data.js` **Current Implementation:** 1000 individual `INSERT` statements **Optimized:** ```sql INSERT INTO users (name, email, created_at) VALUES ($1, $2, $3), ($4, $5, $6), ... -- batch in groups of 1000 ``` --- ### **Pagination Optimization** ```sql SELECT * FROM posts WHERE created_at < $cursor ORDER BY created_at DESC LIMIT 20; ``` --- ## **PHASE 5: Monitoring & Maintenance** ### **1. Slow Query Logging Setup** #### **PostgreSQL** ```sql ALTER SYSTEM SET log_min_duration_statement = '1000'; -- Log queries over 1s ALTER SYSTEM SET log_statement = 'all'; ALTER SYSTEM SET log_duration = on; ``` #### **MySQL** ```sql SET GLOBAL slow_query_log = 'ON'; SET GLOBAL long_query_time = 1; SET GLOBAL log_output = 'TABLE'; ``` --- ### **2. Query Performance Testing** ```js describe('Query Performance', () => { test('User listing should complete under 100ms', async () => { const start = Date.now(); await db.query('SELECT * FROM users LIMIT 1000'); expect(Date.now() - start).toBeLessThan(100); }); }); ``` --- ## **PHASE 6: Deliverables** ### **Deliverable Outputs** - **Optimization Script:** A single SQL file with all index creations, ordered by performance impact. - **Code Changes PR:** Includes all query optimizations with before/after comparison results. ### **Performance Report** - Baseline metrics vs. optimized metrics - Expected resource savings (CPU, memory, I/O) - Risk assessment for each change ### **Monitoring Dashboard** Define recurring queries to track query performance over time. --- ## **PRIORITY MATRIX** Rank each optimization by: - **Impact:** Query frequency × time saved - **Risk:** Low / Medium / High - **Effort:** Quick fix / Moderate / Complex refactor > Focus on **high-impact**, **low-risk**, **low-effort** items first. --- ### **Summary** This workflow ensures the AI: 1. Systematically identifies all queries 2. Analyzes them using database-specific profiling tools 3. Provides **actionable, tested solutions** 4. Considers the full application context 5. Delivers **implementation-ready optimizations** ```` Warp will locate all SQL usage, test each query, and score them using explain-plan data. 4. #### Review the Matrix [Section titled “Review the Matrix”](#review-the-matrix) The output includes: * Query locations * Performance metrics * Recommended fixes * A **graph** mapping impact vs effort Caution A well-tuned database is the heart of your web stack — don’t skip it. # How to: Generate Unit and Security Tests to Debug Faster > Prompt Warp to generate comprehensive unit and security tests for REST APIs, including SQL injection, XSS, and auth validation checks. Learn how to prompt Warp’s AI to generate useful unit and security tests — helping you debug faster and deploy with confidence. ![YouTube video](https://i.ytimg.com/vi/YzZmrusN8Cw/sddefault.jpg) *** 1. #### The Problem [Section titled “The Problem”](#the-problem) Building REST APIs involves a lot of overhead: validation, testing, and security.\ Most “auto-generated tests” from AI end up generic and incomplete — leaving gaps in reliability. To solve this, Warp lets you run **precise, context-aware test generation** using better-structured prompts. 2. #### The Prompt [Section titled “The Prompt”](#the-prompt) Paste this into Warp’s AI input: prompt.txt ```text After implementing this API code, generate comprehensive unit tests and security tests to verify everything works correctly and securely: 1. Unit tests for each function / method Core functionality - Happy path with valid inputs -> expected output - Each edge case (empty inputs, nulls, boundary values) - Error handling for invalid inputs - Return value types and structure - Edge cases: empty strings, null/undefined, max values, special characters 2. SECURITY TESTS FOR EACH ENDPOINT For every API endpoint, create security tests that check: Input validation Test with these malicious payloads in every user input field: SQL Injection: " ' OR '1' = '1', "1; DROP TABLE users--", "admin'--" NoSQL Injection: {"$gt": ""}, {"$ne": null} Command Injection: "; ls -la", "| whoami", "$(cat /etc/passwd)" Path Traversal: "../../../etc/passwd", "..\..\..\windows\system32" XSS: "", "javascript:alert(1)" XXE (for XML): "]>" Authentication Tests: - No token/credentials → Must return 401 - Invalid token → Must return 401 - Expired token → Must return 401 - Valid token for wrong user → Must return 403 - Token with insufficient permissions → Must return 403 Authorization Tests: - User A trying to access User B's data → 403 - Regular user accessing admin endpoints → 403 - Deleted/disabled user token → 401 - Verify all role-based access controls work Additional Security Checks: - Rate limiting works (spam 100 requests → 429 response) - Large payloads are rejected (>1MB unless specified) - Sensitive data not exposed in errors - Headers don't leak server info - CORS properly configured 3. After running all tests, ensure: ✓ All unit tests pass ✓ 100% of functions have tests ✓ All security tests pass ✓ No SQL/NoSQL injection vulnerabilities ✓ Authentication is properly enforced ✓ Authorization rules are working ✓ Input validation catches malicious data ✓ Error messages don't expose sensitive info 4. Output Format Generate 2 test files: 1. Unit_tests.[ext] - all functional tests 2. security_tests.[ext] - all security tests Use simple assertions that clearly show: - What is being tested - What the expected behavior is - Why this test matters Keep these tests simple and focused - each test should verify ONE thing ``` 3. #### Add to Rules File [Section titled “Add to Rules File”](#add-to-rules-file) Once you’ve validated the prompt, add it to your Warp Rules file so Warp can automatically reuse it. ```plaintext Name: Run tests after writing Rule: run pytest mapp/tests to validate if the code you inserted works ``` Warp will then run these tests as a source of truth — deciding whether new AI-generated code is safe to merge or deploy. 4. #### Recap [Section titled “Recap”](#recap) Tip You’ve learned how to: * Prompt for **specific test coverage** * Automate your **unit and security tests** * Use Warp’s **Rules** feature for validation Small change in prompt structure — big jump in reliability. # How To: Prevent Secrets from Leaking > Use Warp Rules and built-in secret reduction to prevent API keys and credentials from leaking in agent output, demos, and shared sessions. Learn how to safeguard credentials and sensitive data using Warp’s secret-reduction and Rule system. ![YouTube video](https://i.ytimg.com/vi/2ECPFKtQpVk/sddefault.jpg) This tutorial shows how to use Warp’s **Rules** to prevent agents or collaborators from exposing sensitive information while coding or sharing output. Whether you’re pair-programming, streaming, or reviewing code, Warp can automatically redact secrets before they’re ever seen by an agent. 1. #### The Problem [Section titled “The Problem”](#the-problem) AI assistants often echo API keys, tokens, or credentials in generated code blocks.\ When collaborating or screen-sharing, that can expose secrets publicly. 2. #### The Rule Setup [Section titled “The Rule Setup”](#the-rule-setup) Define a simple Rule in Warp that instructs the agent to **never display secrets** in outputs or commands. ```plaintext Rule: Protect Secrets Behavior: - Never include or reveal secrets when generating code or commands. - Automatically redact sensitive strings before showing output. ``` Note Enable Warp’s built-in Secret Reduction: Settings → AI → Enable Secret Reduction This automatically masks sensitive values before the agent or output logs can access them. 3. #### Benefits [Section titled “Benefits”](#benefits) * Protects API keys and credentials from exposure * Keeps live streams and demos safe * Works seamlessly with pair-programming or AI debugging # How To: Write SQL Commands inside a Postgres REPL > Use Agents in Warp inside a Postgres REPL to translate natural language into SQL queries — works with Node.js, Python, and MySQL too. Note This tutorial teaches you how to use **Warp’s AI input** to run natural-language prompts inside an interactive **Postgres REPL**, turning plain English into SQL commands.\ \ Although the example uses **PostgreSQL**, the same workflow applies to **Node.js**, **Python**, **MySQL**, and other interactive shells. ![YouTube video](https://i.ytimg.com/vi/guXQSMq_Yss/sddefault.jpg) *** ### 🧠 Overview [Section titled “🧠 Overview”](#-overview) You’ll learn how to: * Start a Postgres REPL in Warp. * Use **Command + I** (or **Ctrl + I**) to open Warp’s AI input. * Speak or type natural-language requests and let Warp translate them into SQL. * Run the generated queries directly inside your REPL session. 1. #### Open a Postgres REPL in Warp [Section titled “Open a Postgres REPL in Warp”](#open-a-postgres-repl-in-warp) Open Warp and connect to your Postgres database (or a test instance): ```bash psql -U postgres -d my_database ``` You’ll enter the interactive `psql` prompt, where you normally type SQL commands. 2. #### Invoke Warp’s AI Input [Section titled “Invoke Warp’s AI Input”](#invoke-warps-ai-input) Inside the running REPL, press: ```plaintext Command + I (macOS) Ctrl + I (Windows/Linux) ``` This opens the **Generate Input** box. You can **type or speak** in plain English — Warp will translate your request into valid SQL or shell syntax, depending on the REPL you’re in. 3. #### Ask Warp in Natural Language [Section titled “Ask Warp in Natural Language”](#ask-warp-in-natural-language) Start with a simple request: ```plaintext Show me all tables. ``` Warp translates this to the Postgres command: ```sql \dt ``` Then try a more specific query, as shown in the video: ```plaintext Show me our users table and our teams table. ``` Warp generates: ```sql SELECT * FROM users; SELECT * FROM teams; ``` You can run both within your REPL to display the tables. 4. #### Observe How Warp Learns from Context [Section titled “Observe How Warp Learns from Context”](#observe-how-warp-learns-from-context) As you continue issuing prompts, Warp’s agent **learns the structure of your database** by observing what’s printed in the REPL output. This means you can ask progressively more complex questions, and Warp will tailor the SQL accordingly. ```plaintext Show me all of the users who have joined Warp in the last 90 days from public email accounts (like Gmail, Yahoo, Hotmail) and are on teams of more than two people. ``` Warp generates a multi-clause SQL query such as: ```sql SELECT * FROM users WHERE email LIKE '%gmail.com%' OR email LIKE '%yahoo.com%' OR email LIKE '%hotmail.com%' AND joined_at > NOW() - INTERVAL '90 days' AND team_size > 2; ``` Running this query in `psql` filters users accordingly. 5. #### Apply the Same Workflow to Other REPLs [Section titled “Apply the Same Workflow to Other REPLs”](#apply-the-same-workflow-to-other-repls) This feature works **not just in Postgres** but also in: * Node.js * Python * MySQL * GDB (GNU Debugger) For any of these environments: 1. Launch the REPL inside Warp. 2. Press **Command + I** to bring up AI input. 3. Describe what you want in natural language. 4. Warp translates it into the correct syntax for that environment. Note Warp automatically detects the active REPL, so you don’t need to specify “SQL” or “Python” — it knows which language to generate. 6. #### Experiment and Iterate [Section titled “Experiment and Iterate”](#experiment-and-iterate) Try varying your natural-language prompts: ```plaintext List all databases. ``` ```sql \l ``` ```plaintext Count how many users signed up this month. ``` ```sql SELECT COUNT(*) FROM users WHERE joined_at > date_trunc('month', NOW()); ``` The more you experiment, the more context Warp gathers, improving its translations. *** ### 🏁 Key Takeaways [Section titled “🏁 Key Takeaways”](#-key-takeaways) * **Command + I** activates Warp’s AI input within any interactive shell. * Warp understands natural language and produces valid commands for the current REPL. * It **learns from context** — subsequent prompts become more accurate. * Works beyond Postgres: Node, Python, MySQL, and others. * A fast way to query or explore systems without memorizing syntax. Tip Next time you’re stuck remembering a command in Postgres or Python, hit **Command + I** and just ask Warp in plain English. # Improve Your Kubernetes Workflow (kubectl + helm) > Streamline kubectl and Helm workflows with Warp's AI assistance, active suggestions, custom workflows, and synchronized panes. Discover how Warp’s modern terminal features streamline Kubernetes workflows through AI assistance, automation, and intuitive design. ![YouTube video](https://i.ytimg.com/vi/64TECXZiFb0/sddefault.jpg) ## Overview [Section titled “Overview”](#overview) This guide covers 6 key Warp features that enhance Kubernetes productivity: 1. #### AI Integration in the Terminal [Section titled “AI Integration in the Terminal”](#ai-integration-in-the-terminal) Warp’s **Agent Mode** (`Cmd + I`) lets you run complex Kubernetes operations with plain-English prompts. **Examples** ```plaintext When does my wildcard TLS certificate expire? ``` Warp auto-detects namespaces, runs `kubectl` commands, and outputs expiration details. ```plaintext Generate a command to identify all pods running as root across all namespaces. ``` Warp builds and runs the corresponding `kubectl` + `grep` query, returning a security report. Note Ideal for on-the-fly debugging or compliance checks without leaving your terminal. 2. #### Building AI-Aided Context [Section titled “Building AI-Aided Context”](#building-ai-aided-context) You can attach any command’s output as context for follow-up prompts.\ For instance, right-click log output → “Attach as Agent Context,” then run: ```plaintext I’m sending anonymous usage data in Traefik. How can I disable it? ``` Warp detects the Helm chart and outputs the required YAML config to disable stats reporting. 3. #### Active AI Suggestions [Section titled “Active AI Suggestions”](#active-ai-suggestions) Warp automatically suggests next actions.\ Examples of suggested actions: * After `kubectl describe pod` it might propose: > “Check the logs of this pod.” * When running `sudo apt update` it detects available upgrades and offers: > “Run sudo apt upgrade to update packages.” 4. #### Custom Workflows [Section titled “Custom Workflows”](#custom-workflows) Create reusable, parameterized commands for common operations like: ```bash helm upgrade --namespace -f ``` Accessible from the **Command Palette (`Cmd + P`)**, workflows make repetitive Kubernetes tasks fast and standardized. 5. #### Synchronized Panes and Tabs [Section titled “Synchronized Panes and Tabs”](#synchronized-panes-and-tabs) Link multiple terminal panes or tabs (e.g., master + worker nodes).\ When synchronization is active, running: ```bash sudo apt update ``` executes simultaneously across all linked sessions. 6. #### Modern Text Editing [Section titled “Modern Text Editing”](#modern-text-editing) Warp supports **click-to-edit** for commands — no more arrow key gymnastics.\ Hovering shows inline **tooltips** explaining flags and subcommands (e.g., Helm, kubectl, etc.), with autocompletions for 400+ CLI tools. # Context7 MCP: Update Astro Project with Best Practices > Use the Context7 MCP server to give Warp agents real-time access to framework documentation for automated project upgrades. Note This tutorial shows how the **Context7 MCP Server** gives Warp agents real‑time access to documentation for upgrading frameworks and codebases automatically. ![YouTube video](https://i.ytimg.com/vi/rrxfS9u1XRA/sddefault.jpg) *** ## 🧠 Overview [Section titled “🧠 Overview”](#-overview) The **Context7 MCP Server** lets Warp fetch live documentation from across the web.\ \ In the example, the agent updates an older **Astro** project to align with the latest version (Astro 5). *** 1. #### Add the Context7 Server [Section titled “Add the Context7 Server”](#add-the-context7-server) * Open Warp’s **MCP Panel** via the Command Palette. * Add the **Context7 JSON config** and click **Save**. ```json { "Context7": { "command": "npx", "args": [ "-y", "@upstash/context7-mcp" ], "env": {}, "working_directory": null } } ``` * This enables the endpoint `getLibraryDocs`, which retrieves live documentation directly from the official sources. 2. #### Run the Update Prompt [Section titled “Run the Update Prompt”](#run-the-update-prompt) The developer issues this prompt: ```plaintext Create a new git branch called update and in that branch update this Astro project to follow all the latest best practices based on all Astro and developer documentation. ``` 3. #### Review the Automatic Code Changes [Section titled “Review the Automatic Code Changes”](#review-the-automatic-code-changes) The transcript shows that Warp automatically: * Updates Tailwind import syntax * Improves TypeScript configuration * Optimizes build settings * Enhances accessibility rules These edits happen across multiple files — without manually searching docs or changelogs. 4. #### Best Use Cases [Section titled “Best Use Cases”](#best-use-cases) * Migrating old Astro, React, or Vue projects * Refreshing codebases to reflect recent standards * Saving time otherwise spent reading version notes Tip Context7 MCP automates documentation lookups — letting Warp update your project intelligently based on live references. # Figma Remote MCP: Create a Website from a Figma File > Connect Warp to Figma's remote MCP server via OAuth and generate front-end code directly from your design files. Learn how to connect Warp to Figma’s remote MCP server to generate code directly from your design files — complete with screenshots, metadata, and design system context. ![YouTube video](https://i.ytimg.com/vi/PsM_Y8Pt-1Q/sddefault.jpg) *** ## Overview [Section titled “Overview”](#overview) This guide covers how to: * Connect Warp to the **remote Figma MCP server** * Log in securely using OAuth * Use the server to pull live context (components, variables, and assets) from your Figma designs * Generate front-end code based on your UI files * Iterate and refine output directly in Warp *** 1. #### What Is a Remote MCP Server? [Section titled “What Is a Remote MCP Server?”](#what-is-a-remote-mcp-server) A **remote MCP server** runs outside your local machine — Warp connects to it through a secure network call.\ \ This means you don’t have to manage processes, ports, or tokens manually. Warp handles setup, authentication, and communication for you. 2. #### Connect Figma MCP to Warp [Section titled “Connect Figma MCP to Warp”](#connect-figma-mcp-to-warp) * Copy the Figma MCP configuration JSON ```plaintext { "Figma": { "url": "https://mcp.figma.com/mcp" } } ``` * In Warp, paste the JSON — Warp will automatically open an OAuth login window. * Log in once with your **Figma account** credentials. Note You will need a Figma Dev account for this to work. 3. #### What the Figma MCP Server Provides [Section titled “What the Figma MCP Server Provides”](#what-the-figma-mcp-server-provides) Once connected, the server enables Warp’s AI to understand your design context by fetching: | Type | Description | | -------------------------------- | -------------------------------------------------------------------- | | **`get_screenshot`** | Helps the AI visualize layout and relationships between elements. | | **`create_design_system_rules`** | Components, variables, and styles for consistent, reusable code. | | **`get_code`** | Extracts code from your Figma design for direct use in projects. | | **`get_metadata`** | Includes text, images, and layer names for more realistic mock data. | 4. #### Generate a Website from a Figma File [Section titled “Generate a Website from a Figma File”](#generate-a-website-from-a-figma-file) Basic flow: * Copy your **Figma file link**: * Right-click → *Copy / Paste As → Copy Link to Selection* * In Warp, paste a prompt to create a website based on that design. Prompt: ```plaintext Create a website from this Figma file: Follow the design layout and use these guidelines: - Match spacing and typography from the design - Use Tailwind CSS and TypeScript - Make components reusable ``` Warp uses the Figma MCP server to pull all necessary context and begin generating code diffs. 5. #### Iterating on Output [Section titled “Iterating on Output”](#iterating-on-output) * In under five minutes, Warp generates a working site structure based on the Figma layout. * Missing assets (e.g., logos or images) are automatically referenced in an `assets/` folder. * Warp prompts you to add any missing files before continuing. 6. #### Persistent Input Feature [Section titled “Persistent Input Feature”](#persistent-input-feature) Warp’s **persistent input** allows mid-process updates.\ If you forget an image (e.g., the Misho logo), simply upload it and notify Warp: ```plaintext I’ve uploaded the Misho logo to the assets folder. ``` Warp will automatically detect and use it during the same generation session. 7. #### Recap [Section titled “Recap”](#recap) * Warp now supports **remote MCP servers** for Figma (and others like GitHub, Sentry, and Linear). * OAuth login streamlines setup and removes manual token handling. * The Figma MCP integration enables rapid, context-aware code generation. * Persistent input and real-time iteration make design-to-code workflows seamless. Tip In under 20 minutes, you can go from Figma design to a functioning website — all powered by Warp’s AI coding environment. # Github MCP: Summarizing Open PRs & Creating GH Issues > Connect the GitHub MCP server to Warp to summarize open PRs, create issues from TODO comments, and automate repo management. ![YouTube video](https://i.ytimg.com/vi/rrxfS9u1XRA/sddefault.jpg) The GitHub MCP Server lets Warp agents read, write, and automate tasks in your GitHub repositories directly — no manual tab-switching required. *** ### 2. Setup [Section titled “2. Setup”](#2-setup) #### Step 1. Get a GitHub Personal Access Token [Section titled “Step 1. Get a GitHub Personal Access Token”](#step-1-get-a-github-personal-access-token) 1. Go to **GitHub → Settings → Developer Settings → Personal Access Tokens** 2. Create a new token and enable: * ✅ `repo` * ✅ `read:user` *** #### Step 2. Add the Server in Warp [Section titled “Step 2. Add the Server in Warp”](#step-2-add-the-server-in-warp) 1. Open the **MCP Panel** via Command Palette (`Cmd + P`) 2. Click **Add Server** 3. Paste in your JSON config and the access token 4. Save — and you’ll see the available endpoints immediately *** ### 3. Workflow 1 — Summarize All Open PRs [Section titled “3. Workflow 1 — Summarize All Open PRs”](#3-workflow-1--summarize-all-open-prs) Use Warp’s agent to summarize pull requests: Behind the scenes, the MCP server: * Lists PRs * Fetches comments and reviews * Compiles summaries with clickable links Perfect for daily PR triage or stand-ups. *** ### 4. Workflow 2 — Create GitHub Issues from TODOs [Section titled “4. Workflow 2 — Create GitHub Issues from TODOs”](#4-workflow-2--create-github-issues-from-todos) Use a saved prompt to automate issue creation. Warp: 1. Scans your codebase for TODO comments 2. Calls `create_issue` for each one via MCP 3. Generates a linked list of new issues This turns scattered notes into trackable tickets instantly. *** ### 5. Why It’s Useful [Section titled “5. Why It’s Useful”](#5-why-its-useful) * Save 20–30 minutes per session * Keep repos synchronized automatically * Enable PR summaries, issue tracking, and automation — all inside Warp. # How to set up Claude Code > Set up Claude Code in Warp, configure it for your project, and learn productivity tips — from voice prompting to visual code review. Claude Code is Anthropic’s AI coding agent. It reads your codebase, writes and edits code, runs commands, and handles complex refactors using natural language prompts. This guide takes you from zero to a working Claude Code session in Warp in about 5 minutes, then shows you how to get the most out of it. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **A Claude account with CLI access** — Claude Code requires a paid plan or API credits. See [Claude Code requirements](https://docs.anthropic.com/en/docs/claude-code/setup) for eligible plans. * **macOS 13+, Windows 10+, or Ubuntu 20.04+** — See [Claude Code system requirements](https://docs.anthropic.com/en/docs/claude-code/setup) for full platform details. * **Git** — Claude Code works best inside a Git repository. On Windows, [Git for Windows](https://git-scm.com) is required. ## 1. Install Claude Code [Section titled “1. Install Claude Code”](#1-install-claude-code) Follow Anthropic’s [official installation guide](https://docs.anthropic.com/en/docs/claude-code/quickstart) to install Claude Code. The native installer (recommended) requires no dependencies and auto-updates in the background. When you launch Claude Code inside Warp, Warp auto-detects the agent session and surfaces integrated controls, including rich input, code review, vertical tab metadata, and more. ## 2. Authenticate [Section titled “2. Authenticate”](#2-authenticate) The first time you run Claude Code, it opens your browser for login. ```bash claude ``` Sign in with your Claude account. Once authenticated, the token is stored locally and you won’t need to log in again. For headless environments or CI/CD, set an API key instead: ```bash export ANTHROPIC_API_KEY=YOUR_API_KEY ``` ## 3. Start your first session [Section titled “3. Start your first session”](#3-start-your-first-session) Navigate to any project directory and launch Claude Code: ```bash cd ~/your-project claude ``` Try giving it a task, for example: ```plaintext Explain the architecture of this project ``` Or something more hands-on: ```plaintext Add input validation to the user registration endpoint ``` Claude Code will find the relevant files, show you the proposed changes, and ask for confirmation before modifying anything. ## 4. Configure for your project [Section titled “4. Configure for your project”](#4-configure-for-your-project) Create a `CLAUDE.md` file at your project root to teach Claude Code your project’s conventions. Claude Code reads this file at the start of every session. ```markdown # My Project ## Stack - Backend: Python 3.12, FastAPI, SQLAlchemy - Frontend: React, TypeScript, Vite - Database: PostgreSQL 16 ## Commands - `npm run dev` starts the dev server - `pytest -v` runs the test suite - `npm run lint` checks code style ## Conventions - Use async/await for all database operations - Type hints on all function signatures - ESM imports only (no require()) ``` This prevents Claude Code from guessing your conventions and ensures it follows your team’s standards from the first prompt. ## 5. Choose a model and permissions [Section titled “5. Choose a model and permissions”](#5-choose-a-model-and-permissions) Claude Code uses the latest Claude model by default. To use a specific model: ```bash claude --model MODEL_NAME ``` By default, Claude Code asks for permission before every file write and command execution. You can pre-approve safe operations in `.claude/settings.json`: ```json { "permissions": { "allow": [ "Read", "Glob", "Grep", "Bash(pytest*)", "Bash(npm run lint)" ] } } ``` This lets Claude read files and run your test/lint commands without prompting, while still asking before writing files. ## 6. Set up agent notifications [Section titled “6. Set up agent notifications”](#6-set-up-agent-notifications) Warp supports agent notifications for Claude Code through a plugin. When you run Claude Code in Warp without the plugin installed, a notification chip appears offering one-click installation. Once installed, Warp surfaces in-app and desktop alerts when Claude Code needs your input. For manual installation steps, troubleshooting, and SSH/remote setup, see [Claude Code in Warp (docs)](/agent-platform/cli-agents/claude-code/#setting-up-notifications). ## Productivity tips [Section titled “Productivity tips”](#productivity-tips) * **Use voice to prompt Claude Code** — Instead of typing complex instructions, dictate them. Warp supports [voice transcription](/agent-platform/local-agents/interacting-with-agents/voice/) that works with any CLI agent, including Claude Code. Press the microphone icon or the `fn` key to start recording. * **Attach images as context** — Paste screenshots of bug reports, design mockups, or error messages directly into your prompt. Warp’s [images as context](/agent-platform/local-agents/agent-context/images-as-context/) feature lets Claude Code see what you see. * **Review diffs visually** — After Claude Code makes changes, open Warp’s [Code Review panel](/code/code-review/) (`⌘+Shift++`) to see a visual diff of every file changed. You can leave inline comments and send them back to Claude Code for corrections. * **Run multiple Claude Code sessions in parallel** — Use [vertical tabs](/terminal/windows/vertical-tabs/) to run different Claude Code tasks side by side, one session fixing bugs while another writes tests. Each tab shows which agent is running and its current status. * **Compose richer prompts** — Press `Ctrl+G` to open Warp’s rich input editor for Claude Code. This gives you a full text editor experience for composing prompts — click to position your cursor, select text, and edit naturally instead of navigating with arrow keys. ## Next steps [Section titled “Next steps”](#next-steps) You installed Claude Code, authenticated, started your first session, configured it for your project, and learned the key productivity features that make it faster to use in Warp. Explore related guides and features: * [Set up Codex CLI](/guides/external-tools/how-to-set-up-codex-cli/) to run a second agent alongside Claude Code * [How to review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code/) — a structured workflow for reviewing and refining agent output * [Run multiple agents at once](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) — use Claude Code and Codex side by side * [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/quickstart) — Anthropic’s official reference * [Claude Code in Warp](https://warp.dev/agents/claude-code) — overview of Claude Code support in Warp * [Claude Code in Warp (docs)](/agent-platform/cli-agents/claude-code/) — full reference for Claude Code’s Warp integration, including notification setup * [Third-party CLI agents](/agent-platform/cli-agents/overview/) — all supported agents and Warp’s universal agent features # How to set up Codex CLI > Set up OpenAI's Codex CLI in Warp, configure it for your project, and learn productivity tips for faster AI-assisted coding workflows in Warp. Codex CLI is OpenAI’s open-source coding agent. It reads your codebase, edits files, and executes commands from natural language prompts. This guide takes you from installation to a working Codex session in Warp in about 5 minutes, then shows you how to get the most out of it. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **A ChatGPT account with Codex access** — Included with paid ChatGPT plans, or use an OpenAI API key. See [Codex CLI documentation](https://developers.openai.com/codex/cli/) for eligible plans. * **Node.js 18+** (for npm install) or **Homebrew** (for macOS) — Choose your preferred package manager. * **macOS or Linux** — Windows support is experimental; for the best Windows experience, use Codex in a WSL workspace. ## 1. Install Codex CLI [Section titled “1. Install Codex CLI”](#1-install-codex-cli) Install Codex CLI globally with npm or Homebrew: **npm:** ```bash npm install -g @openai/codex ``` **Homebrew (macOS):** ```bash brew install codex ``` Verify installation: ```bash codex --version ``` You can also download platform-specific binaries directly from the [GitHub releases](https://github.com/openai/codex/releases). ## 2. Authenticate [Section titled “2. Authenticate”](#2-authenticate) Run Codex for the first time: ```bash codex ``` Select **Sign in with ChatGPT** and authenticate with your ChatGPT account (recommended). Your Codex usage is included in your ChatGPT plan. For API key authentication (useful for CI/CD or automation): ```bash export OPENAI_API_KEY=YOUR_API_KEY ``` ## 3. Start your first session [Section titled “3. Start your first session”](#3-start-your-first-session) Navigate to a project directory and launch Codex: ```bash cd ~/your-project codex ``` Codex starts an interactive terminal session. Try giving it a task, for example: ```plaintext Explain the structure of this project ``` Or something more hands-on: ```plaintext Add error handling to the database connection module ``` Codex will read the relevant files, propose changes, and ask for your confirmation before modifying anything. You can review changes in a diff view and accept or reject each one. ## 4. Configure model and approval mode [Section titled “4. Configure model and approval mode”](#4-configure-model-and-approval-mode) Switch between available models during a session with the `/model` command. See [Codex CLI documentation](https://developers.openai.com/codex/cli/) for the current model list. Codex has three [approval modes](https://developers.openai.com/codex/cli/features#approval-modes) that control how much autonomy it has. * **Auto** (the default) lets Codex read, edit, and run commands within your working directory but asks before anything outside that scope. * **Read-only** keeps Codex consultative * **Full Access** grants broader autonomy including network access. Use `/permissions` inside a session to switch modes as your comfort level changes. ## 5. Customize with a configuration file [Section titled “5. Customize with a configuration file”](#5-customize-with-a-configuration-file) Create a `codex.md` or `AGENTS.md` file at your project root to teach Codex your project’s conventions: ```markdown # My Project ## Stack - Backend: Node.js, Express, TypeScript - Database: PostgreSQL with Prisma ORM - Testing: Vitest for unit tests, Playwright for e2e ## Conventions - Use ESM imports (no require()) - All API endpoints need Zod input validation - Run `npm test` before committing ``` Codex reads this file at the start of every session and follows your conventions automatically. Note Warp supports agent notifications for Codex. Add `notification_condition = "always"` under `[tui]` in `~/.codex/config.toml` and restart Codex. See [Codex in Warp (docs)](/agent-platform/cli-agents/codex/#setting-up-notifications) for details. If the config isn’t set, Warp displays a setup chip in the terminal. ## Productivity tips [Section titled “Productivity tips”](#productivity-tips) * **Use voice to prompt Codex** — Dictate complex instructions instead of typing them. Warp supports [voice transcription](/agent-platform/local-agents/interacting-with-agents/voice/) that works with any CLI agent, including Codex. * **Attach images as context** — Paste screenshots of bugs, designs, or error messages into your prompt. Warp’s [images as context](/agent-platform/local-agents/agent-context/images-as-context/) feature lets Codex see what you see. * **Review diffs visually** — After Codex makes changes, open Warp’s [Code Review panel](/code/code-review/) (`⌘+Shift++`) to see a visual diff. You can leave inline comments and send them back to Codex for corrections. * **Run Codex alongside Claude Code** — Use [vertical tabs](/terminal/windows/vertical-tabs/) to run Claude Code and Codex side by side on the same task. Compare their approaches and pick the best output, or combine elements from both. * **Compose richer prompts** — Press `Ctrl+G` to open Warp’s rich input editor for Codex, giving you a full text editor experience instead of raw CLI input. ## Next steps [Section titled “Next steps”](#next-steps) You installed Codex CLI, authenticated, started your first session, and configured it for your project. Codex is now set up as a working AI coding agent in Warp. Explore related guides and features: * [Set up Claude Code](/guides/external-tools/how-to-set-up-claude-code/) to run a second agent alongside Codex * [How to review AI-generated code](/guides/agent-workflows/how-to-review-ai-generated-code/) — a structured workflow for reviewing agent output * [Run multiple agents at once](/guides/agent-workflows/how-to-run-multiple-ai-coding-agents/) — use Codex and Claude Code side by side * [Codex CLI documentation](https://developers.openai.com/codex/cli/) — OpenAI’s official reference * [Codex in Warp](https://warp.dev/agents/codex) — overview of Codex support in Warp * [Codex in Warp (docs)](/agent-platform/cli-agents/codex/) — full reference for Codex’s Warp integration, including notification setup * [Third-party CLI agents](/agent-platform/cli-agents/overview/) — all supported agents and Warp’s universal agent features # How to set up Gemini CLI > Set up Google's Gemini CLI in Warp, configure it for your project, and learn productivity tips for faster AI-assisted coding workflows. Gemini CLI is Google’s open-source coding agent. It brings Gemini directly into your terminal with built-in tools for file operations, shell commands, web search, and MCP support. This guide takes you from installation to a working Gemini CLI session in Warp in about 5 minutes, then shows you how to get the most out of it. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **A Google account** — Gemini CLI’s free tier includes 60 requests per minute and 1,000 requests per day with a personal Google account. Alternatively, use a Gemini API key or Vertex AI. See the [Gemini CLI authentication guide](https://geminicli.com/docs/get-started/authentication/) for all options. * **Node.js 20+** — Required for installation. Check with `node -v`. * **macOS, Linux, or Windows** — See [Gemini CLI system requirements](https://geminicli.com/docs/get-started/installation/) for recommended specifications. ## 1. Install Gemini CLI [Section titled “1. Install Gemini CLI”](#1-install-gemini-cli) Follow Google’s [official installation guide](https://geminicli.com/docs/get-started/installation/) to install Gemini CLI. The two most common methods: **npm:** ```bash npm install -g @google/gemini-cli ``` **Homebrew (macOS/Linux):** ```bash brew install gemini-cli ``` Verify installation: ```bash gemini --version ``` You can also run without installing using `npx @google/gemini-cli`. When you launch Gemini CLI inside Warp, Warp auto-detects the agent session and surfaces integrated controls, including rich input, code review, vertical tab metadata, and more. ## 2. Authenticate [Section titled “2. Authenticate”](#2-authenticate) The first time you run Gemini CLI, it prompts you to choose an authentication method. ```bash gemini ``` Select **Sign in with Google** and complete the browser authentication flow. Once authenticated, the token is stored locally and you won’t need to sign in again. For API key authentication (useful for CI/CD or higher rate limits): ```bash export GEMINI_API_KEY=YOUR_API_KEY ``` For enterprise environments using Vertex AI, the recommended approach is Application Default Credentials (ADC): ```bash export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID export GOOGLE_CLOUD_LOCATION=YOUR_LOCATION export GOOGLE_GENAI_USE_VERTEXAI=true gcloud auth application-default login ``` See the [Gemini CLI authentication guide](https://geminicli.com/docs/get-started/authentication/) for all Vertex AI auth methods. ## 3. Start your first session [Section titled “3. Start your first session”](#3-start-your-first-session) Navigate to any project directory and launch Gemini CLI: ```bash cd ~/your-project gemini ``` Try giving it a task, for example: ```plaintext Explain the architecture of this project ``` Or something more hands-on: ```plaintext Add error handling to the database connection module ``` Gemini CLI reads the relevant files, proposes changes, and asks for confirmation before modifying anything. ## 4. Configure for your project [Section titled “4. Configure for your project”](#4-configure-for-your-project) Create a `GEMINI.md` file at your project root to teach Gemini CLI your project’s conventions. Gemini CLI reads this file at the start of every session. ```markdown # My Project ## Stack - Backend: Node.js, Express, TypeScript - Database: PostgreSQL with Prisma ORM - Testing: Vitest for unit tests, Playwright for e2e ## Commands - `npm run dev` starts the dev server - `npm test` runs the test suite - `npm run lint` checks code style ## Conventions - Use ESM imports (no require()) - All API endpoints need Zod input validation - Run `npm test` before committing ``` This prevents Gemini CLI from guessing your conventions and ensures it follows your team’s standards from the first prompt. ## 5. Choose a model [Section titled “5. Choose a model”](#5-choose-a-model) Gemini CLI defaults to the latest Gemini model. To use a specific model: ```bash gemini -m MODEL_NAME ``` You can also switch models during a session with the `/model` command. See the [Gemini CLI documentation](https://github.com/google-gemini/gemini-cli) for the current model list. Note Gemini CLI does not currently support agent notifications in Warp. You won’t receive desktop alerts when Gemini CLI needs input, so keep the tab visible or check back periodically during longer tasks. All other Warp agent features (rich input, code review, vertical tabs) work fully. ## Productivity tips [Section titled “Productivity tips”](#productivity-tips) * **Use voice to prompt Gemini CLI** — Dictate complex instructions instead of typing them. Warp supports [voice transcription](/agent-platform/local-agents/interacting-with-agents/voice/) that works with any CLI agent, including Gemini CLI. * **Attach images as context** — Paste screenshots of bugs, designs, or error messages into your prompt. Warp’s [images as context](/agent-platform/local-agents/agent-context/images-as-context/) feature lets Gemini CLI see what you see. * **Review diffs visually** — After Gemini CLI makes changes, open Warp’s [Code Review panel](/code/code-review/) (`⌘+Shift++`) to see a visual diff. You can leave inline comments and send them back to Gemini CLI for corrections. * **Run Gemini CLI alongside other agents** — Use [vertical tabs](/terminal/windows/vertical-tabs/) to run Gemini CLI and Claude Code or Codex side by side on the same task. Compare their approaches and pick the best output. * **Compose richer prompts** — Press `Ctrl+G` to open Warp’s rich input editor for Gemini CLI, giving you a full text editor experience instead of raw CLI input. * **Use built-in Google Search** — Gemini CLI can ground responses with real-time web search. Ask it to research current best practices or look up documentation while working on your code. ## Next steps [Section titled “Next steps”](#next-steps) You installed Gemini CLI, authenticated with your Google account, started your first session, and configured it for your project. Gemini CLI is now set up as a working coding agent in Warp. Explore related guides and features: * [Set up Ollama for local models](/guides/external-tools/how-to-set-up-ollama/) to pair Gemini CLI with local model workflows * [Code Review panel](/code/code-review/) — review and refine agent-generated code * [Gemini CLI in Warp](https://warp.dev/agents/gemini-cli) — overview of Gemini CLI support in Warp * [Third-party CLI agents](/agent-platform/cli-agents/overview/) — all supported agents and Warp’s universal agent features * [Gemini CLI documentation](https://github.com/google-gemini/gemini-cli) — Google’s official reference # How To Set Up Ollama > Install Ollama, run LLMs locally, compare model performance, and integrate local models into your apps using Warp. Running AI models locally just got easier — and faster — with Ollama.\ \ In this guide, we’ll walk through how to use Warp to install, profile, and integrate Ollama into your local setup. ![YouTube video](https://i.ytimg.com/vi/Aq8vDxUg4VE/sddefault.jpg) *** ### 1. Check Your System Specs [Section titled “1. Check Your System Specs”](#1-check-your-system-specs) Before running large language models (LLMs) locally, confirm your hardware can handle them. Example setups: * Mac: 64GB unified memory — good for larger models but with lower throughput. * Windows (NVIDIA RTX 5090): 32GB VRAM — excellent performance, but limited by VRAM capacity. > 🧠 Rule of thumb: You’ll need roughly 1GB of VRAM per billion parameters. *** ### 2. Run Your First Model [Section titled “2. Run Your First Model”](#2-run-your-first-model) Run a model locally: > ollama run gpt-oss For example: * Try GPT-OSS 20B (requires ≥16GB VRAM, supports tool calling). * Then try Mistral 8B for a faster, smaller alternative. Compare their performance and quality side-by-side.\ Use Warp to easily monitor GPU usage and model response time. *** ### 3. Understanding Model Terms [Section titled “3. Understanding Model Terms”](#3-understanding-model-terms) Here’s a quick glossary for choosing the right local model: | Term | Meaning | | ---------------- | ------------------------------------------------------------------ | | **Thinking** | The model “thinks” before answering; better for complex reasoning. | | **Tools** | Models can use external utilities (e.g., web search). | | **Vision** | Can process and respond to images. | | **Embedding** | Converts text to numeric form for search or RAG pipelines. | | **Quantization** | Reduces memory use by lowering precision (e.g., 4-bit). | *** ### 4. Integrate Ollama into Your App [Section titled “4. Integrate Ollama into Your App”](#4-integrate-ollama-into-your-app) Most apps use OpenAI-compatible APIs, so integration is simple. 1. Open your app’s code in Warp. 2. Locate the OpenAI client initialization. 3. Replace the base URL with Ollama’s 4. Update your API key and model name. Warp helps you quickly locate, edit, and test the integration directly from the terminal. *** ### 6. Customize Model Behavior [Section titled “6. Customize Model Behavior”](#6-customize-model-behavior) Pull and modify a model. Then save it as a custom model with new settings like temperature or system prompt. Use Warp to generate a model file automatically. This adds a structured system prompt for that task — ready to use instantly. # How to set up OpenCode > Set up OpenCode in Warp, configure it for your project, and learn productivity tips for faster AI-assisted coding workflows. OpenCode is an open-source coding agent that runs in your terminal. It supports 75+ LLM providers, features a built-in terminal UI (TUI), and lets you edit code, execute commands, and manage sessions from natural language prompts. This guide takes you from installation to a working OpenCode session in Warp in about 5 minutes, then shows you how to get the most out of it. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **An LLM provider account** — OpenCode connects to any supported provider (Anthropic, OpenAI, Google, and others) via API key, or use OpenCode Zen for a curated model list. See [OpenCode configuration](https://opencode.ai/docs#configure) for details. * **macOS, Linux, or Windows (via WSL)** — WSL is recommended for the best experience on Windows. See [OpenCode docs](https://opencode.ai/docs) for full platform details. ## 1. Install OpenCode [Section titled “1. Install OpenCode”](#1-install-opencode) Follow the [official OpenCode installation guide](https://opencode.ai/docs#install) to install OpenCode. The install script is the fastest method: ```bash curl -fsSL https://opencode.ai/install | bash ``` You can also install via npm or Homebrew: ```bash npm install -g opencode-ai ``` ```bash brew install anomalyco/tap/opencode ``` See the [OpenCode docs](https://opencode.ai/docs#install) for additional installation methods including Homebrew taps, platform-specific binaries, and Docker. When you launch OpenCode inside Warp, Warp auto-detects the agent session and surfaces integrated controls, including rich input, code review, vertical tab metadata, and more. ## 2. Authenticate [Section titled “2. Authenticate”](#2-authenticate) OpenCode supports multiple LLM providers. Run the `/connect` command inside OpenCode’s TUI to configure a provider, or set API keys as environment variables: ```bash # For Anthropic models export ANTHROPIC_API_KEY=YOUR_API_KEY # For OpenAI models export OPENAI_API_KEY=YOUR_API_KEY # For Google Gemini models export GEMINI_API_KEY=YOUR_API_KEY ``` Outside the TUI, run `opencode auth login` from the command line for interactive provider setup. Credentials are stored locally in `~/.local/share/opencode/auth.json`. ## 3. Start your first session [Section titled “3. Start your first session”](#3-start-your-first-session) Navigate to any project directory and launch OpenCode: ```bash cd ~/your-project opencode ``` OpenCode starts its TUI. Try giving it a task, for example: ```plaintext Explain the architecture of this project ``` Or something more hands-on: ```plaintext Add input validation to the user registration endpoint ``` OpenCode reads the relevant files, proposes changes, and asks for confirmation before modifying anything. Use the `Tab` key to switch between Plan mode (read-only suggestions) and Build mode (applies changes). ## 4. Configure for your project [Section titled “4. Configure for your project”](#4-configure-for-your-project) Initialize OpenCode for your project by running `/init` inside the TUI. This analyzes your codebase and creates an `AGENTS.md` file at your project root: ```plaintext /init ``` The `AGENTS.md` file teaches OpenCode your project’s structure and conventions. You can also create or edit it manually: ```markdown # My Project ## Stack - Backend: Python 3.12, FastAPI, SQLAlchemy - Frontend: React, TypeScript, Vite - Database: PostgreSQL 16 ## Commands - `npm run dev` starts the dev server - `pytest -v` runs the test suite - `npm run lint` checks code style ## Conventions - Use async/await for all database operations - Type hints on all function signatures - ESM imports only (no require()) ``` Commit the `AGENTS.md` file to Git so your team shares the same project context. ## 5. Set up agent notifications [Section titled “5. Set up agent notifications”](#5-set-up-agent-notifications) Warp supports agent notifications for OpenCode through a plugin. If the plugin isn’t installed, Warp displays an installation chip in the terminal when you run OpenCode, with setup steps you can follow directly. For manual installation and configuration, see [OpenCode in Warp (docs)](/agent-platform/cli-agents/opencode/#setting-up-notifications). ## Productivity tips [Section titled “Productivity tips”](#productivity-tips) * **Use voice to prompt OpenCode** — Dictate complex instructions instead of typing them. Warp supports [voice transcription](/agent-platform/local-agents/interacting-with-agents/voice/) that works with any CLI agent, including OpenCode. * **Attach images as context** — Paste screenshots of bugs, designs, or error messages into your prompt. Warp’s [images as context](/agent-platform/local-agents/agent-context/images-as-context/) feature lets OpenCode see what you see. * **Review diffs visually** — After OpenCode makes changes, open Warp’s [Code Review panel](/code/code-review/) (`⌘+Shift++`) to see a visual diff. You can leave inline comments and send them back to OpenCode for corrections. * **Run OpenCode alongside other agents** — Use [vertical tabs](/terminal/windows/vertical-tabs/) to run OpenCode and Claude Code or Codex side by side on the same task. Compare their approaches and pick the best output. * **Compose richer prompts** — Press `Ctrl+G` to open Warp’s rich input editor for OpenCode, giving you a full text editor experience instead of raw CLI input. ## Next steps [Section titled “Next steps”](#next-steps) You installed OpenCode, authenticated with a provider, started your first session, and configured it for your project. OpenCode is now set up as a working coding agent in Warp. Explore related guides and features: * [Set up Ollama for local models](/guides/external-tools/how-to-set-up-ollama/) to run OpenCode with local models * [Code Review panel](/code/code-review/) — review and refine agent-generated code * [OpenCode in Warp](https://warp.dev/agents/opencode) — overview of OpenCode support in Warp * [OpenCode in Warp (docs)](/agent-platform/cli-agents/opencode/) — full reference for OpenCode’s Warp integration, including notification setup * [Third-party CLI agents](/agent-platform/cli-agents/overview/) — all supported agents and Warp’s universal agent features * [OpenCode documentation](https://opencode.ai/docs) — official reference * [opencode-warp plugin](https://github.com/warpdotdev/opencode-warp) — notification plugin source and updates # Linear MCP: Retrieve issue data > Add the Linear MCP server to Warp and query your issues, tasks, and assignments directly from the terminal. Learn how to connect the Linear MCP server in Warp so your agents can access live data — like issues, tickets, and user assignments — directly from your Linear workspace. ![YouTube video](https://i.ytimg.com/vi/jxeMfuS1pXk/sddefault.jpg) *** #### Overview [Section titled “Overview”](#overview) This tutorial covers how to: * Add and configure a Linear MCP server in Warp * Use MCP to query and retrieve issue data ### 1. Adding the Linear MCP Serve [Section titled “1. Adding the Linear MCP Serve”](#1-adding-the-linear-mcp-serve) #### Add a new server in Warp [Section titled “Add a new server in Warp”](#add-a-new-server-in-warp) * In Warp, open Warp Drive → Personal → MCP Servers.\ Alternatively, press `⌘P` and type **MCP servers** to open the palette. * Click **Add New Server**. * Paste in this JSON ```json { "linear": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"], "env": {}, "working_directory": null } } ``` * Click Save. * Warp will immediately start the server. * You should now see Linear MCP listed as Running. *** ### 2. Testing the Connection [Section titled “2. Testing the Connection”](#2-testing-the-connection) After saving, retry your earlier query: ```plaintext Show me all Linear tasks assigned to me. ``` Warp’s agent will now call the Linear MCP server to fetch your data. You can click inside the response panel to inspect the **raw API response** — ideal for debugging or understanding what’s being fetched. If the server can’t find your user, it may be due to your Linear login address. Try querying a teammate to confirm the connection: ```plaintext Show tasks assigned to [teammate name]. ``` Once verified, the agent can display a full list of tasks. # Linear MCP: Updating Tickets with a Lean Build Approach > Use Warp's Linear MCP integration to update ticket descriptions, propagate changes to subtasks, and maintain a lean build strategy. Learn how to use Warp’s Linear MCP integration to update tickets programmatically while maintaining a lean build strategy. ![YouTube video](https://i.ytimg.com/vi/hqleW6jDCbY/sddefault.jpg) *** ## Overview [Section titled “Overview”](#overview) This walkthrough demonstrates: * Updating Linear tickets via Warp’s MCP integration * Structuring tasks around a lean development stack * Observing real-time synchronization of ticket data * Testing agent autonomy when editing related subtasks 1. #### Setting Up the Scenario [Section titled “Setting Up the Scenario”](#setting-up-the-scenario) The goal is to use Warp’s agent to update a Linear epic with a new, leaner build approach and reflect the changes in related subtasks. First, open your Linear project and locate the target epic.\ Copy the **ticket ID** (e.g. “Empty Studio 36”). 2. #### Define the Update Prompt [Section titled “Define the Update Prompt”](#define-the-update-prompt) Within Warp, run the MCP command to edit the Linear issue. **Prompt** ```plaintext Use the warp-server-staging gcloud project and pull logs for the last 10 minutes from the warp-server Cloud Run instance. Organize them by info, warning, and error levels. Create a histogram across message types, and highlight the most concerning errors to investigate. ``` Warp parses the issue context and updates the ticket’s fields accordingly. 3. #### Observing the Changes [Section titled “Observing the Changes”](#observing-the-changes) After execution: * The Linear ticket reflects the new **Next.js + Supabase** stack. * Tasks like *Build Foundation*, *Implement AI-powered PRD Generation*, and *Set up Development Environment* are updated. * Time estimates automatically adjust from *4–6 weeks* to *2–3 weeks*. * Complex integrations (AI and Linear App) are deferred to a future phase. 4. #### Propagating Updates to Child Tasks [Section titled “Propagating Updates to Child Tasks”](#propagating-updates-to-child-tasks) Warp’s agent can cascade changes to linked subtasks.\ If it begins editing other epics unexpectedly, you can constrain its scope by specifying task IDs in the prompt: ```plaintext Only update the ticket with ID . Do not modify other epics or related tickets. ``` 5. #### Review and Verification [Section titled “Review and Verification”](#review-and-verification) Re-open the Linear epic to confirm updates: * **Frontend specs** reflect the lean stack. * **Child tasks** align with phase 1 deliverables. * **Deferred features** (e.g., advanced integrations) are pushed to phase 2. Note This demonstrates Warp’s ability to *maintain and modify tickets intelligently*, not just create them. # Puppeteer MCP: Scraping Amazon Web Reviews > Configure the Puppeteer MCP server in Warp to automate browser tasks like navigating sites, scraping product data, and analyzing reviews. Note This tutorial demonstrates how to configure and use the **Puppeteer MCP server** inside Warp to scrape Amazon web reviews. ![YouTube video](https://i.ytimg.com/vi/rrxfS9u1XRA/sddefault.jpg) *** ### 🧠 Overview [Section titled “🧠 Overview”](#-overview) **Puppeteer MCP** integrates Warp’s agents with the browser, letting you automate tasks such as navigation, form filling, screenshotting, and scraping content.\ \ Once configured, Warp can issue Puppeteer commands directly from prompts, enabling full **browser automation** without manual scripting. You’ll learn how to: * Set up the Puppeteer MCP server. * Use Warp’s voice input and AI to describe automation tasks. * Execute browser workflows hands-free. * Capture, scrape, and analyze web data programmatically. *** 1. #### Configure the Puppeteer MCP Server [Section titled “Configure the Puppeteer MCP Server”](#configure-the-puppeteer-mcp-server) Open the MCP panel in Warp: * Press **Cmd + Shift + P** (Mac) or **Ctrl + Shift + P** (Windows/Linux) to open the **Command Palette**. * Search for `MCP` and open the **MCP Panel**. Add the Puppeteer MCP config: * Click **Add**, then paste in the provided JSON configuration for Puppeteer: ```json { "puppeteer": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-puppeteer" ], "env": {}, "working_directory": null } } ``` Save your configuration. Available endpoints will include: * `puppeteer.navigate` * `puppeteer.fill` * `puppeteer.screenshot` * `puppeteer.evaluate` These represent actions Warp can call automatically through its agents. 2. #### Use Voice Input to Trigger Automation [Section titled “Use Voice Input to Trigger Automation”](#use-voice-input-to-trigger-automation) Enable **voice input** by clicking the microphone icon in Warp. Then speak your automation prompt naturally. ```plaintext Can you go to Amazon search for "white t-short women?" Scrape the results so the titles, prices, and links are extracted. Then open each product link and summarize the product reviews. Finally, give me a recommendation for which shirt to buy based on the combination of the pricing and review quality. ``` #### Watch Puppeteer Automate the Workflow [Section titled “Watch Puppeteer Automate the Workflow”](#watch-puppeteer-automate-the-workflow) Behind the scenes, Puppeteer: * Navigates to Amazon. * Fills the search bar with “white t-shirt woman.” * Scrapes the product results — capturing titles, prices, and product links. * Clicks into each product and extracts review data using JavaScript selectors. * Takes screenshots of the pages for reference. You can see the browser (Amazon) and Warp side-by-side as Puppeteer performs these steps autonomously. Note Puppeteer runs fully headless or in visible browser mode — you don’t need to touch your mouse or keyboard. #### Analyze and Summarize Results [Section titled “Analyze and Summarize Results”](#analyze-and-summarize-results) Once the scrape is complete, Warp compiles the data and provides a ranked list of products. Example output (from transcript): | Product | Price | Rating | Summary | | ---------------- | ----- | ------ | --------------------- | | Cozy T-Shirt | $8 | ⭐ 4.5 | Soft fabric, good fit | | Comfy Cotton Tee | $10 | ⭐ 4.2 | Slightly looser fit | | Basic White Top | $6 | ⭐ 3.8 | Mixed quality reviews | Warp’s recommendation: > “The Cozy T‑Shirt — $8, 4.5 stars, good fit, and soft fabric.” #### Apply Puppeteer MCP to Other Scenarios [Section titled “Apply Puppeteer MCP to Other Scenarios”](#apply-puppeteer-mcp-to-other-scenarios) The same setup works for: * Product research – Compare reviews or specs across multiple sites. * Competitive analysis – Scrape competitors’ pricing or product data. * Web testing – Automate user flows like login or checkout. * Repetitive data tasks – Periodic scraping or screenshot capture. Tip Puppeteer MCP lets Warp act like your hands in the browser — navigating, scraping, and summarizing data while you focus on analysis. # Sentry MCP: Fix Sentry Error in Empower Website > Connect the Sentry MCP server to Warp, fetch live error data, diagnose stack traces, and auto-generate fixes for production issues. Note This tutorial is based solely on the provided transcript. It teaches how to use the **Sentry MCP Server** within Warp to fetch live error data from Sentry, analyze stack traces, and automatically generate fixes for issues in your codebase. ![YouTube video](https://i.ytimg.com/vi/rrxfS9u1XRA/sddefault.jpg) ### Overview [Section titled “Overview”](#overview) The **Sentry MCP server** gives Warp’s agents access to authenticated Sentry error data.\ This enables detailed diagnostics and automated fixes that would otherwise be impossible using AI alone. You’ll learn how to: * Connect the Sentry MCP server inside Warp. * Trigger live error retrieval from Sentry. * Diagnose code issues and generate patches automatically. * Integrate Sentry debugging into your daily development loop. 1. #### Set Up the Sentry MCP Server [Section titled “Set Up the Sentry MCP Server”](#set-up-the-sentry-mcp-server) Open the MCP panel in Warp: * Mac: Cmd + Shift + P * Windows/Linux: Ctrl + Shift + P\ Search for “MCP” and select the **MCP Panel**. Click **Add**, then paste your configuration: ```json { "sentry": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://mcp.sentry.dev/mcp" ], "env": {}, "working_directory": null } } ``` Save the configuration and ensure it appears in the MCP panel. 2. #### Run Your App and Trigger an Error [Section titled “Run Your App and Trigger an Error”](#run-your-app-and-trigger-an-error) We’re using the [**Empower Plant** repository](https://github.com/sentry-demos/empower) — Sentry’s official demo project. This fake e-commerce app includes a React frontend and multiple backends, each containing intentional bugs for testing. Run the app locally: ```bash npm install npm start ``` Open the site in your browser and trigger a few known errors. 3. #### Capture the Error in Sentry [Section titled “Capture the Error in Sentry”](#capture-the-error-in-sentry) 1. Go to your **Sentry Dashboard**. 2. Locate the triggered issue (for example, a `TypeError`). 3. Copy the issue’s URL from the Sentry interface. Example: ```plaintext https://sentry.io/organizations/demo/issues/12345/ ``` 4. #### Diagnose the Error Using Warp [Section titled “Diagnose the Error Using Warp”](#diagnose-the-error-using-warp) Back in Warp, prompt the agent to fetch and analyze the issue: ```plaintext Diagnose this Sentry error and show where it’s coming from in my code. Create a fix. ``` The Sentry MCP calls `getIssueDetails`, fetching the stack trace and error metadata directly from Sentry. Warp then scans your local codebase, cross-references the error location, and identifies the root cause. From this example: > The issue was caused by calling `.toUpperCase()` on an array instead of a string. Warp’s agent automatically writes a fix — changing the code to handle the array properly. 5. #### Apply the Generated Fix [Section titled “Apply the Generated Fix”](#apply-the-generated-fix) Warp produces a suggested code change inline. Review the diff and apply it automatically with one click. 6. #### Integrate Into Your Workflow [Section titled “Integrate Into Your Workflow”](#integrate-into-your-workflow) Use Sentry MCP whenever you encounter production or staging errors. Warp can pull the latest issues, analyze them, and suggest patches. Ideal for: * Debugging live production errors. * Triaging complex stack traces. * Creating immediate hot-fixes without switching tools. Tip With Sentry MCP, Warp becomes a live debugging console — connecting your code editor, terminal, and Sentry into a single intelligent feedback loop. # SQLite and Stripe MCP: Basic Queries You Can Make After Set Up > Connect SQLite and Stripe MCP servers to Warp and run conversational queries against your local database and payment data. This tutorial teaches you how to use **MCP servers** to connect Warp to **Stripe** and **SQLite**, showing how AI transforms the command line into a connected, conversational workspace. 1. #### Enabling MCP in Warp [Section titled “Enabling MCP in Warp”](#enabling-mcp-in-warp) Warp now supports configuring any MCP server directly from the terminal. To set it up: * Open **Settings → AI → MCP Servers** in Warp. * Click **Add Server**, and choose from a list of available MCP configurations. * Once added, Warp automatically connects and authorizes the agent to use those tools. In this demo, two MCP servers were enabled: * **SQLite Server** – for running local database queries * **Stripe Server** – for retrieving and analyzing payment data 2. #### Querying Stripe [Section titled “Querying Stripe”](#querying-stripe) Once configured, you can issue conversational prompts to the terminal — no manual API calls required. Example — Querying Stripe ```plaintext How many customers do I have in Stripe? ``` Warp connects to the Stripe MCP server, confirms the action, and returns: > “You have 3 customers.” You can continue naturally: ```plaintext List the payments made by the first customer. ``` The agent retrieves seven payment intents — one successful, six canceled — all live from your Stripe test account. Note: MCP’s confirmation prompts can be disabled once you trust a given server or agent. 3. #### Querying SQLite [Section titled “Querying SQLite”](#querying-sqlite) The same workflow applies to databases. Example — Querying SQLite ```plaintext What SQL tables do I have access to? ``` Warp lists all available tables from the local SQLite database. ```plaintext Break down female penguins by island. ``` Warp translates this into a structured SQL query and executes it, returning: > “Bisco Island — 51 female penguins; Dream Island — …” Follow-up prompts work contextually: ```plaintext Do the same with male penguins. ``` Warp runs the updated SQL query and displays results inline. 4. #### Why This Matters [Section titled “Why This Matters”](#why-this-matters) This demo highlights how Warp’s AI and MCP support combine to make your terminal: * **Connected** — Access cloud APIs, local data, or enterprise tools instantly. * **Conversational** — Run natural language prompts for structured data retrieval. 5. Note “Even two years ago, no one could’ve imagined a terminal capable of this. Warp has officially redefined what a terminal can be.” — Santiago # Using MCP Servers with Warp > Connect MCP servers to Warp's agent, add Rules for automatic tool selection, and resolve tickets using external systems like Linear. ![YouTube video](https://i.ytimg.com/vi/8vn2brhJrF8/sddefault.jpg) ### 1. What Are MCP Servers? [Section titled “1. What Are MCP Servers?”](#1-what-are-mcp-servers) MCP (Model Context Protocol) servers let Warp agents connect to external systems like GitHub, Linear, or Jira — so they can read, write, and reason about those systems natively. Each MCP server adds its own “tools” to Warp’s agent.\ For example: * The Linear MCP Server handles tickets. * The GitHub MCP Server handles pull requests and issues. *** ### 2. Problem Setup [Section titled “2. Problem Setup”](#2-problem-setup) Andrew starts with Warp’s universal input, but it doesn’t yet know what a “ticket” is. > Prompt Example:\ > “Help me solve this ticket.” At this point, Warp can’t find or interpret the ticket, because no MCP server is connected. *** ### 3. Adding the Linear MCP Server [Section titled “3. Adding the Linear MCP Server”](#3-adding-the-linear-mcp-server) To connect Linear: 1. Open the **MCP Panel** in Warp 2. Click **Add Server** 3. Paste in the JSON configuration for the Linear MCP Server Once added, Warp: * Starts the MCP server * Loads its tools (e.g., `get_ticket`, `update_ticket`, `create_ticket`) * Makes them available to the agent instantly *** ### 4. Using Rules with MCP Servers [Section titled “4. Using Rules with MCP Servers”](#4-using-rules-with-mcp-servers) Andrew adds a rule called **check-linear**, which helps the agent automatically associate “tickets” with the Linear MCP Server. > **Rule Example:**\ > “When the user says ‘ticket,’ check Linear.” Rules make context switching between systems seamless — the agent doesn’t need reminders. *** ### 5. Dynamic Context Loading [Section titled “5. Dynamic Context Loading”](#5-dynamic-context-loading) Warp’s MCP support is **dynamic**: * You can start a conversation without any connected MCPs * Add one mid-session * The agent automatically updates its context on the next message No need to restart Warp or reset your session. *** ### 6. Running the Task [Section titled “6. Running the Task”](#6-running-the-task) After adding Linear, Andrew runs: > “Help me solve this ticket.” Now the agent: * Queries Linear for the ticket * Pulls all related context * Reads the codebase for linked references * Generates the appropriate fix He verifies the output by running: ```bash cargo run ``` # How To: Code UI That Matches Your Mockup > Prompt Warp to generate pixel-perfect React + Tailwind code from design mockups, with structured specs and iterative refinement. Learn how to prompt Warp’s AI to produce accurate, design-faithful UI code using your preferred framework. ![YouTube video](https://i.ytimg.com/vi/GA0OO_1o8LA/sddefault.jpg) *** ## Intro [Section titled “Intro”](#intro) This tutorial walks you through generating pixel-perfect front-end code using Warp.\ \ By treating the AI like a **UI engineer**, you can get closer to real implementation fidelity — especially when working from design mockups. Although this example uses **React** and **Tailwind**, the same method applies to **Vue**, **Next.js**, or **Svelte**. *** 1. #### The Problem [Section titled “The Problem”](#the-problem) When designing UI with AI, your intended design often gets lost in translation.\ AI struggles with visual fidelity — but structured prompts can help fix that. 2. #### The Prompt [Section titled “The Prompt”](#the-prompt) Step — Generate full specifications: ```plaintext Analyze this web design mockup as a senior UI engineer would. Create a complete technical specification: 1. DESIGN SYSTEM TOKENS: - Extract the color palette with semantic naming (primary, secondary, surface, text) - Identify the type scale (heading levels, body text sizes) - Document the spacing scale pattern (4px, 8px, 16px, etc.) - List border radius values used consistently 2. LAYOUT ARCHITECTURE: - Describe the overall page structure using semantic HTML5 elements - Identify CSS Grid vs Flexbox usage for each section 3. COMPONENT SPECIFICATIONS: For each unique component, provide: - Semantic HTML structure - CSS layout method - All visual states (default, hover, focus, active, disabled) - Exact dimensions and spacing - Animation/transition properties 4. RESPONSIVE BEHAVIOR: - Describe how the layout adapts (even if only desktop is shown) - Note which elements stack, hide, or resize - Identify touch targets that need enlarging on mobile 5. ACCESSIBILITY REQUIREMENTS: - Color contrast ratios for text/background combinations - Interactive element sizes (minimum 44x44px touch targets) - Focus indicator styles - Screen reader considerations for decorative elements Format as a structured spec that includes both the visual description AND implementation notes. Flag any ambiguous design decisions that need clarification. ``` Next, give Warp the right prompt to start the code implementation: ```plaintext Using this design specification, build a responsive React component with Tailwind CSS: Requirements: - Create reusable components for each element in the spec - Use CSS variables for the design tokens - Implement all interactive states - Ensure mobile-first responsive design - Add proper semantic HTML and ARIA labels - Include Framer Motion for any animations mentioned - Match the spacing system exactly using Tailwind's spacing scale Create a pixel-perfect implementation that matches the original design. ``` 3. #### Validate and Iterate [Section titled “Validate and Iterate”](#validate-and-iterate) Warp outputs component files and layout structure.\ You can review spacing, font weights, and responsive behavior directly in preview. If details feel off, prompt again with clarifications like: ```plaintext Tighten vertical spacing between header and subtext. ``` 4. #### Recap [Section titled “Recap”](#recap) You’ve learned how to: * Prompt AI for structured UI specs * Generate React + Tailwind implementations * Iterate visually for design parity > Treating the AI like a teammate — not a tool — yields interfaces that finally match your vision. # How To: Replace A UI Element in Warp (Rust Codebase) > Use Agent Mode in Warp to plan and execute icon replacements across a large Rust codebase — with live diffs, auto-compilation, and self-correction. Learn how to use Warp’s AI coding features to make live code changes — in this example, replacing an icon throughout Warp’s massive Rust codebase using an agentic workflow. ![YouTube video](https://i.ytimg.com/vi/V2pwBN6Vt7k/sddefault.jpg) Note This demo showcases Warp’s ability to safely make intelligent code changes within a multi-million-line codebase by providing structured prompts, reviewing diffs in real time, and letting the agent compile and self-correct. 1. #### Define the Task [Section titled “Define the Task”](#define-the-task) The goal here is to replace all instances of the **sparkle icon** with the new **agent icon**, especially within the history menu. Open your project in Warp and start by prompting the agent directly (either by typing or speaking): ```plaintext Please create a new branch for me according to the format in the attached Linear URL. I’ve attached screenshots of what the Agent Mode and sparkle icons look like. I would like you to understand those icons, search for their use in the code, and wherever we’re using sparkles, replace them with the Agent Mode icon. Specifically, make sure this happens in the history menu. Please give me a plan before making any coding changes. ``` Attach any relevant Linear issue links or screenshots to help the agent identify assets accurately. 2. #### Review the Plan [Section titled “Review the Plan”](#review-the-plan) Warp’s agent parses your request and generates a plan for code edits.\ It identifies files and functions where the sparkle icon is used. If the plan looks correct, approve it to proceed. Follow-up prompt example: ```plaintext Yes, proceed — and please rename the function from renderAISparklesIcon to something like renderAgentModeIcon. ``` Warp automatically updates function names, asset references, and component usage. 3. #### View AI Diffs in Real Time [Section titled “View AI Diffs in Real Time”](#view-ai-diffs-in-real-time) Warp lets you view live diffs as the agent edits your files. * Diffs show changes to both render logic and function naming. * You can choose to auto-accept or manually review diffs. * These settings can be adjusted under AI Settings → Apply Changes Automatically. Note Note: The demo runs with “auto-accept” enabled, allowing Warp to apply diffs as soon as they’re validated. 4. #### Compilation and Fixes [Section titled “Compilation and Fixes”](#compilation-and-fixes) After editing, Warp’s agent runs: ```bash cargo check ``` to verify compilation. If compilation fails (e.g., missing imports), the agent automatically corrects and retries — mimicking a human debugging process. 5. #### Testing the Change [Section titled “Testing the Change”](#testing-the-change) Once compiled: * Run your project locally to confirm visual changes. * Check that the agent icon now replaces the sparkle icon in all targeted locations. 6. #### Recap [Section titled “Recap”](#recap) Warp’s agent completed the full flow: 1. Understood a Linear ticket and visual context 2. Created a new branch 3. Planned and executed the icon replacement 4. Auto-fixed compile issues 5. Verified the final result in-app # 10 Coding Features You Should Know > Discover 10 essential coding features in Warp — file search, tabbed editor, find and replace, syntax highlighting, code review panel, and more. ## 10 Coding Features You Should Know in Warp [Section titled “10 Coding Features You Should Know in Warp”](#10-coding-features-you-should-know-in-warp) If you didn’t already know, you can code directly in Warp. Warp includes a full set of features that make editing, reviewing, and navigating your codebase far easier than in a traditional dev tool. ![YouTube video](https://i.ytimg.com/vi/oeonZ-jtzhA/sddefault.jpg) Let’s walk through the 10 core features you need to know to get started. *** ### 1. Search for Files [Section titled “1. Search for Files”](#1-search-for-files) Open the **Command Palette**: * **Mac:** `Cmd + P` * **Windows/Linux:** `Ctrl + Shift + P` Then press: * **Mac:** `Cmd + O` * **Windows/Linux:** `Ctrl + O` From here, you can search and open any file in your project — no need to `cd` around or remember long paths. *** ### 2. Tabbed File Viewer [Section titled “2. Tabbed File Viewer”](#2-tabbed-file-viewer) When you open files, Warp shows them in **tabs** rather than split panes.\ This keeps your workspace clean while still allowing you to switch quickly between multiple files. *** ### 3. Full Editor Support [Section titled “3. Full Editor Support”](#3-full-editor-support) You can edit code directly inside Warp — just like any modern editor. No need for memorized shortcuts: * Click and type normally * Highlight, copy, paste, or undo using familiar shortcuts *** ### 4. Find and Replace [Section titled “4. Find and Replace”](#4-find-and-replace) Warp supports full **find and replace** with: * Regular expressions * Multi-cursor editing * Replace-all * Preserve-case rules These features make renaming variables or refactoring code fast and consistent. *** ### 5. Syntax Highlighting [Section titled “5. Syntax Highlighting”](#5-syntax-highlighting) Warp supports syntax highlighting for **dozens of languages and frameworks**.\ It appears both in: * Agent-generated diffs * The file editor view This makes it easy to visually scan code at a glance. *** ### 6. Linked File References [Section titled “6. Linked File References”](#6-linked-file-references) When Warp’s agent references a file, it automatically **links to the exact line of code**.\ Clicking the link opens that file at that line inside Warp — perfect for tracing logic or verifying changes. > ⚙️ **Tip:** In **Settings → Features**, set Warp as your default editor for these file links so they open directly in Warp. *** ### 7. Code Review Panel [Section titled “7. Code Review Panel”](#7-code-review-panel) Warp provides a **dedicated review panel** summarizing all files and diffs touched by an agent.\ You can: * Review and approve changes * Edit them inline * Reference diffs in your next prompt This reduces hallucinations and keeps agents grounded in your actual code. *** ### 8. Code Snippet References [Section titled “8. Code Snippet References”](#8-code-snippet-references) When Warp explains something about your codebase, it surfaces the **exact code snippet**.\ You can attach that snippet as fresh context for your next prompt. This keeps token usage lean and the agent’s focus sharp. *** ### 9. Codebase Indexing [Section titled “9. Codebase Indexing”](#9-codebase-indexing) Warp can automatically **index your repositories** for faster, more context-aware responses.\ This makes it easier for agents to: * Summarize large codebases * Fix bugs * Handle refactors intelligently *** ### 10. File Tree View [Section titled “10. File Tree View”](#10-file-tree-view) Click the file-tree icon in Warp to **browse your entire repo** and open any file with a single click. # How to: Customize Warp's Appearance > Customize Warp's themes, input placement, AI settings, codebase indexing, team collaboration, and visual appearance to fit your workflow. ![YouTube video](https://i.ytimg.com/vi/fzb1JcZ0fFA/sddefault.jpg) Warp is highly customizable — from appearance and keyboard shortcuts to agent behavior and autonomy.\ \ Here’s a quick walkthrough of how to make Warp feel like *your* development environment. *** ### 1. Changing Themes [Section titled “1. Changing Themes”](#1-changing-themes) Open the **Command Palette** with: * `Cmd + P` (Mac) * `Ctrl + Shift + P` (Windows/Linux) Type **“themes”** to open the theme picker. You can preview and apply any theme instantly — for example, switching from the default theme to *Phenomenon*. *** ### 2. Adjusting Input Placement [Section titled “2. Adjusting Input Placement”](#2-adjusting-input-placement) Warp’s **input bar** can live in three different positions: 1. **Bottom-pinned** — chat-style; commands flow upward. 2. **Scrolling input** — traditional terminal style; input stays near the bottom as output moves up. 3. **Top-pinned** *(Warp-exclusive)* — input stays fixed at the top; results appear below. *** ### 3. Managing AI & Agent Settings [Section titled “3. Managing AI & Agent Settings”](#3-managing-ai--agent-settings) Open **Settings → AI** to control: * Which **model** Warp uses (e.g., Claude 3.5 for code generation, GPT-4o for planning). * How much **autonomy** agents have for: * Reading files * Generating diffs * Running commands * Planning tasks You can also allowlist or block specific commands that always require confirmation. *** ### 4. Indexing Your Codebases [Section titled “4. Indexing Your Codebases”](#4-indexing-your-codebases) Warp prompts you to index your codebase the first time you `cd` into it.\ Indexing enables faster: * Code navigation * Summaries and searches * Refactors and bug fixes You can also manually re-index a folder from the sidebar anytime. *** ### 5. Team Collaboration [Section titled “5. Team Collaboration”](#5-team-collaboration) In the Teams tab, you can: * Invite teammates * Share Warp Drive assets like prompts, templates, and environment variables This makes Warp a shared, contextual workspace — not just an individual tool. *** ### 6. Look & Feel [Section titled “6. Look & Feel”](#6-look--feel) Under Appearance, you can tweak: * Fonts * App icons * Padding and editor density * VIM mode for command editing * Custom key bindings # How to Make Warp’s UI More Minimal > Reduce visual noise in Warp by disabling UI elements, switching to a minimal theme, using the classic prompt, and hiding the tab bar. ![YouTube video](https://i.ytimg.com/vi/1GKsIT8FSsE/sddefault.jpg) ### 1. Start with the Command Palette [Section titled “1. Start with the Command Palette”](#1-start-with-the-command-palette) Open the Command Palette: * Mac: `Cmd + P` * Windows/Linux: `Ctrl + Shift + P` From here, type “Disable” to see a full list of UI toggles.\ Warp will surface options that let you quickly hide features and visual elements. *** ### 2. Key UI Toggles to Disable [Section titled “2. Key UI Toggles to Disable”](#2-key-ui-toggles-to-disable) #### Inline & AI Features [Section titled “Inline & AI Features”](#inline--ai-features) * Disable Auto Suggestions → removes inline code hints. * Disable Active AI → hides the ghost prompt that suggests agent queries. * Disable Completion Menu → prevents popup completions from appearing. * Disable Voice Input → hides the microphone icon. #### Interface & Layout [Section titled “Interface & Layout”](#interface--layout) * Disable Block Dividers → removes the horizontal lines between commands. * Disable Tab Indicators → hides the colored status markers across your tab bar. * Disable Dimming Inactive Panes → keeps all split panes at equal brightness. * Disable VIM Status Bar → removes the VIM indicator if you’re not using VIM mode. *** ### 3. Choose a Simpler Theme [Section titled “3. Choose a Simpler Theme”](#3-choose-a-simpler-theme) Visual noise can come from colors too.\ Try switching to a calmer theme from the Command Palette: 1. Open the palette again (`Cmd + P`) 2. Type “Theme” 3. Pick one with softer tones — for example: * Adeberry → calm, gray, minimal aesthetic * Classic Dark → familiar and focused A consistent neutral palette makes Warp feel lighter and easier on the eyes. *** ### 4. Switch to the Classic Prompt [Section titled “4. Switch to the Classic Prompt”](#4-switch-to-the-classic-prompt) Warp’s Universal Prompt is great for AI workflows — it supports: * Slash commands * Voice input * Image context * Agent Mode But if you just want a terminal that behaves like a classic shell, switch to the Classic Prompt: 1. Open the Command Palette → search “Prompt” 2. Choose Classic Prompt 3. (Optional) Open the Prompt Customizer to toggle chips: * Keep only what you need (e.g., file path) * Hide everything else (branch name, context icons, etc.) This instantly gives Warp a retro, text-first look — no clutter, no distractions. *** ### 5. Reduce Tab Bar Visibility [Section titled “5. Reduce Tab Bar Visibility”](#5-reduce-tab-bar-visibility) You can make the tab bar appear only when you hover: * Open the Settings → Appearance * Enable “Show Tabs on Hover” This keeps your workspace focused while still letting you access tabs when needed. # How To Master Warp's Code Review Panel > Use Warp's Code Review Panel to view file diffs, edit code inline, componentize changes, and commit directly — all without leaving the terminal. ![YouTube video](https://i.ytimg.com/vi/4JlN0rvoZA8/sddefault.jpg) ### 1. Why Use the Code Review Panel [Section titled “1. Why Use the Code Review Panel”](#1-why-use-the-code-review-panel) Warp’s Code Review Panel helps you stay focused while coding by showing all active file diffs, additions, and deletions — without leaving your workspace. *** ### 2. Start with a Coding Task [Section titled “2. Start with a Coding Task”](#2-start-with-a-coding-task) The app has a UI issue: the hover text is black on dark gray, making it unreadable. Warp’s agent generates diffs with proposed fixes — but for larger projects, scrolling through them is inefficient. *** ### 3. Opening the Code Review Panel [Section titled “3. Opening the Code Review Panel”](#3-opening-the-code-review-panel) Click: * View Changes (top-left), or * The Dirty Chip in your input bar This opens the Code Review Panel — available only when inside a Git repo. The panel shows: * Changed files * Lines added/deleted * File-by-file diff summaries *** ### 4. Editing and Reviewing Code [Section titled “4. Editing and Reviewing Code”](#4-editing-and-reviewing-code) You can open any file directly from the panel in Warp’s **built-in editor**: * Syntax highlighting * Find & replace * Inline editing Save changes — and they’ll reflect instantly in the diff view. *** ### 5. Componentizing Changes [Section titled “5. Componentizing Changes”](#5-componentizing-changes) Want that same hover fix across the app?\ Prompt Warp to componentize the hover style. Attach the recent diff as context so Warp can generalize it.\ The agent then creates a `Tooltip` component that reuses your schema everywhere. *** ### 6. Reviewing and Committing [Section titled “6. Reviewing and Committing”](#6-reviewing-and-committing) Once the fix looks correct: * Review in the code panel * Commit directly from Warp * Watch the panel reset to its “no changes” state You can also click to compare your branch against `main` instantly. # Welcome to Warp > Get oriented with Warp's agentic terminal. Learn the basics of prompt-based coding, blending terminal and agent workflows, and navigating the interface. ![YouTube video](https://i.ytimg.com/vi/O5E6ze3vqeo/sddefault.jpg) ### 1. Welcome to Warp [Section titled “1. Welcome to Warp”](#1-welcome-to-warp) When you open Warp, you’ll see something familiar — a command line interface — but it’s much more than a traditional terminal.\ \ Warp is an Agentic Development Environment (ADE), meaning it’s a space where your primary mode of interaction is through prompts to an agent. You can still use Warp just like any terminal: ```bash ls pwd ``` Warp executes those commands exactly as you’d expect.\ \ But when you type natural language — like *“describe my open git changes”* — Warp interprets it as a prompt to launch the agent. *** ### 2. Prompt-Based Coding [Section titled “2. Prompt-Based Coding”](#2-prompt-based-coding) When you ask something in plain English, Warp’s agent automatically: * Gathers relevant context (your repo, files, or command output) * Runs whatever commands are needed * Returns a structured answer or takes the requested action Example: > “Describe my open git changes.” Warp’s agent will review your current branch, run git commands in the background, and summarize what’s pending. *** ### 3. Blending Terminal and Agentic Workflows [Section titled “3. Blending Terminal and Agentic Workflows”](#3-blending-terminal-and-agentic-workflows) The beauty of Warp is in how seamlessly it blends traditional CLI workflows with AI-driven automation.\ You can: * Type commands like a normal shell * Or prompt an agent to do things like debugging, code review, or environment setup No context-switching between apps — it’s all one environment. # Team Admin Panel > Centralized management for team administrators to configure workspace settings enforced across all team members. ## What is the Admin Panel? [Section titled “What is the Admin Panel?”](#what-is-the-admin-panel) The [Admin Panel](https://app.warp.dev/admin/) provides team administrators with centralized control over organization-wide settings in Warp. It allows you to manage workspace settings that are enforced across all members of your team. Note Admin Panel access is restricted to team administrators. Right now, only the creator of a team is the designated admin. If your admin has setup styles that override user preferences, you will not be able to control them inside of Warp, and you’ll see a note that your admin has configured this setting. **Key features:** * **AI Settings** - Control agent autonomy, permissions, and allowlists across your team * **Privacy Controls** - Configure data collection and enterprise secret redaction * **Billing Management** - Set spending limits and manage usage-based pricing * **Code Settings** - Control codebase indexing and context features * **Sharing Policies** - Manage link sharing and collaboration permissions ## Accessing the Admin Panel [Section titled “Accessing the Admin Panel”](#accessing-the-admin-panel) Team administrators can access the Admin Panel directly at ![Admin Panel main interface with sections for AI, privacy, billing, code, and sharing settings](/_astro/admin-panel-overview.DwOcO89f_Z1BJwa7.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Admin Panel main interface. ## How settings enforcement works [Section titled “How settings enforcement works”](#how-settings-enforcement-works) The Admin Panel uses a tier-based policy system to determine which settings administrators can control: ### Toggleable vs. fixed settings [Section titled “Toggleable vs. fixed settings”](#toggleable-vs-fixed-settings) **Toggleable settings** can be modified by team administrators. These appear as dropdown menus with options like: * Enabled/Disabled for boolean settings * Specific autonomy levels for AI settings * Respect User Setting to allow individual control **Fixed settings** are determined by your billing tier and cannot be changed. These appear with a message: “Configuring this setting is not available on your plan.” ### Setting Inheritance [Section titled “Setting Inheritance”](#setting-inheritance) When administrators configure organization-wide settings: 1. **Organization enforced** - Setting applies to all team members regardless of individual preferences 2. **Respect user setting** - Allows individual team members to control the setting themselves 3. **Tier restricted** - Setting is locked to default values based on billing plan ### User Experience [Section titled “User Experience”](#user-experience) Note Any changes made in the Admin Panel can take effect immediately for all team members. Consider testing settings in Warp before applying organization-wide policies. When organization settings override individual preferences: * Users see their personal settings grayed out * A message indicates “your organization has configured this setting” * Users cannot modify settings that are organizationally enforced ## Plan Limitations [Section titled “Plan Limitations”](#plan-limitations) The features available in the Admin Panel vary by billing tier: **Free Tier** * Most settings are fixed and non-toggleable * Limited Codebase Context and sharing features **Business Plans** * Most settings become toggleable by administrators * Enhanced AI autonomy control * Advanced sharing and privacy features **Enterprise Plans** * Full admin control over all settings * Enterprise secret redaction * Custom LLM integration * Advanced compliance features For complete details about what’s included in each plan, visit [warp.dev/pricing](https://www.warp.dev/pricing). ## Admin Panel sections [Section titled “Admin Panel sections”](#admin-panel-sections) The Admin Panel is organized into five main sections, each focused on a specific area of team management: ### AI Settings [Section titled “AI Settings”](#ai-settings) Configure how Agents behave across your organization, including autonomy levels and command permissions. #### General AI Settings [Section titled “General AI Settings”](#general-ai-settings) **AI in Remote Sessions** Controls whether AI features are available during SSH sessions and remote connections. Enterprise plans can toggle this setting, while Free tier teams have it enabled by default. **Prompt Summarization Caching** When conversations become long enough to require summarization, this setting allows the summary to be cached temporarily by the LLM provider to improve performance. #### Autonomy Settings [Section titled “Autonomy Settings”](#autonomy-settings) Configure how much independence Agents have when performing different actions: **Apply Code Diffs** * Agent Decides - Prompt for review before applying code diffs (currently behaves the same as Always Ask) * Always Ask - Require explicit approval before applying any code changes * Always Allow - Apply code diffs without confirmation * Respect User Setting - Allow individual users to control this setting **Create Plans** Controls whether Agents can create structured task plans without user approval. **Execute Commands** Manages Agent’s ability to run terminal commands autonomously. **Read Files** Controls Agent access to reading files in the codebase. #### Directory and Command Control [Section titled “Directory and Command Control”](#directory-and-command-control) **Directory Allowlist** Specify directories where Agents can read files without restriction. Use paths like `~/git/repo1` to grant access to specific project folders. **Command Allowlist** Regular expressions matching commands that Agent Mode can execute without asking permission. Common examples: * `grep .*` - Text search commands * `ls(\\s.*)?` - Directory listing * `which .*` - Finding executable locations **Command Denylist** Regular expressions for commands that always require explicit user approval, even if they would normally be allowed. Examples: * `rm -rf.*` - Recursive file deletion * `sudo.*` - Administrative commands * `curl.*` - Network requests Caution Command denylist rules take precedence over allowlist rules and agent autonomy settings. If a command matches the denylist, user permission will always be required. ### Privacy Settings [Section titled “Privacy Settings”](#privacy-settings) Manage data collection and security policies for your organization. **UGC Data Collection** Controls how Warp collects and uses user-generated content to improve the service: * Disabled - No UGC data collection * Enabled - Allow data collection for service improvement * Respect User Setting - Let individual users decide **Enterprise Secret Redaction** When enabled, applies regex patterns to prevent secrets from being sent to Warp servers or LLM providers. This feature is available on Enterprise plans and includes: * Automatic detection of common secret patterns * Custom regex patterns for organization-specific secrets * Unconditional application across all team members ### Code Settings [Section titled “Code Settings”](#code-settings) Control codebase indexing and AI code features for your team. **Codebase Context** Determines whether Warp indexes your team’s Git repositories to provide context for AI features: * Disabled - No codebase indexing * Enabled - Index codebases for improved AI responses * Respect User Setting - Allow individual control Higher tier plans support more indexed repositories and larger file limits per codebase. ### Billing Settings [Section titled “Billing Settings”](#billing-settings) Configure billing preferences and spending controls. **Usage Based Pricing** Enable pay-as-you-go billing for credits beyond your plan’s included quota. When enabled, you can set: **Monthly Spending Limit** Set a maximum monthly overage spending limit to control costs. The system displays current overage usage including: * Total overage credits used * Current month’s overage costs ### Sharing Settings [Section titled “Sharing Settings”](#sharing-settings) Control how team members can share Warp Drive objects and collaborate. **Direct Link Sharing** Allow team members to share Notebooks, Workflows, and other objects via direct links. **Anyone with Link Sharing** Enable public access to shared objects - anyone with the link can view the content without being a team member. # Session Sharing > Share terminal sessions with teammates for collaboration, debugging, and knowledge sharing. Session sharing documentation has moved to the Agent Platform section. See the articles below for details on sharing sessions: * **[Agent Session Sharing](/agent-platform/local-agents/session-sharing/)** - Share agent sessions with your team for review and collaboration. * **[Viewing Cloud Agent Runs](/agent-platform/cloud-agents/viewing-cloud-agent-runs/)** - Share session context from cloud agent runs. # Team management > Create or join a team to collaborate with others in Warp. ## What is a team? [Section titled “What is a team?”](#what-is-a-team) A team is a group of Warp users who can collaborate on the command line together. Warp teams can share a dedicated workspace in Warp Drive. [Learn about pricing](https://www.warp.dev/pricing) and see our [Pricing FAQ](/support-and-community/plans-and-billing/pricing-faqs/). Note Currently, each Warp user can only be an admin or member of one team at a time. ![Teams Demo](https://i.ytimg.com/vi/8UmreUTTrkg/sddefault.jpg) ## Creating a team [Section titled “Creating a team”](#creating-a-team) You can create a new team in the following ways: * Warp Drive, + Create a team * **Settings** > **Teams** Before you can invite team members, you will need to give your team a meaningful name. We suggest using a name to represent your organization, company, or project. Note You can rename the team by going to **Settings** > **Teams** and clicking on the team name, entering the new name, and pressing `ENTER` to accept. ![Teams settings panel with a team name input field and Create button](/_astro/team-creation-settings.B5mqDnRv_ZccBus.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) If you create a team, you become the team’s admin and will be the only person who can delete the team. Reference [Team roles and permissions](/knowledge-and-collaboration/teams/#team-roles-and-permissions) for more info. ### Inviting new team members [Section titled “Inviting new team members”](#inviting-new-team-members) Under **Settings** > **Teams** you can copy the invite link for your Warp team and paste it to your clipboard. Caution If you’re on a paid plan, upgrading will automatically include all team members in your billing. Adding new members after upgrading will also add them as paid seats. For more details on how team member billing works, please see our [billing FAQs](/support-and-community/plans-and-billing/pricing-faqs/#what-counts-as-a-team-member-and-how-does-billing-work-for-members). ![Teams settings panel](/_astro/teams-invite-demo.DVj00gNK_Z1FHIpp.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Teams settings panel. When you share this link with your teammates directly (we suggest using a secure channel like Slack or email), they will be able to join your team in Warp. ## Restricting team invites by domain [Section titled “Restricting team invites by domain”](#restricting-team-invites-by-domain) Sometimes you may want to control your team so that people can only join if they also authenticate with a specific email domain, such as your company’s email domain. Toggle on Restrict by domain to set an explicit allowlist. If you share an invite link with somebody who’s using Warp with a domain that does not match your allowlist, they will be prompted to authenticate from an emailed link sent to a matching domain to join your team. ## Joining a team [Section titled “Joining a team”](#joining-a-team) If you have received an invite link, you can use that link to sign up or log in and join your team in Warp. If your team is using domain restriction, you will need to authenticate you have access to a specific domain before you can join your team. ## Leaving and deleting teams [Section titled “Leaving and deleting teams”](#leaving-and-deleting-teams) If you’re a member of a team, you can visit **Settings** > **Teams** to leave a team at any time. Team admins (who created teams) may delete a team only after removing all team members. ## Team discoverability [Section titled “Team discoverability”](#team-discoverability) Team admins can make their teams discoverable to colleagues from the same email domain. This feature is available under **Settings** > **Teams** > **Make team discoverable**. Note While discoverability is enabled, any new user who joins the team will add a prorated charge to the team’s next month’s bill. See more in our [pricing docs](/support-and-community/plans-and-billing/pricing-faqs/#what-counts-as-a-team-member-and-how-does-billing-work-for-members). ## Transferring team admin [Section titled “Transferring team admin”](#transferring-team-admin) Team admins can transfer their role to another team member by going to **Settings** > **Teams** > **Transfer admin** and selecting the member to whom you’d like to transfer the admin role. ## Team roles and permissions [Section titled “Team roles and permissions”](#team-roles-and-permissions) Caution If you’re a Team admin, and you choose to [delete your Warp](/support-and-community/privacy-and-security/privacy/#manage-your-data) account, the deletion flow will require that you assign a team member as the new admin. | | Admin | Member | | --------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------- | | | This is the Warp user who created a team. There can only be one. | All team members who belong to a team. | | Create a team | ✓ | | | Restrict by domain | ✓ | | | Invite members | ✓ | ✓ | | Remove team members | ✓ | | | Leave a team | | ✓ | | Delete a team | ✓ | | | Transfer admin | ✓ | | | [Manage billing](/support-and-community/plans-and-billing/plans-pricing-refunds/) | ✓ | | # Warp Drive overview > Warp Drive is a workspace in your terminal where you can save Workflows, Notebooks, Prompts, and Environment Variables for personal use or to share with a team. ## What is Warp Drive? [Section titled “What is Warp Drive?”](#what-is-warp-drive) All objects stored in Warp Drive sync immediately as they’re updated, so you and your team will always have access to the latest versions. ![Warp Drive Overview](https://i.ytimg.com/vi/AGL0YcRj5-o/sddefault.jpg) ## How to access it [Section titled “How to access it”](#how-to-access-it) * macOS Warp Drive is accessible from the status bar in Warp or you can toggle the Warp Drive side panel with `CMD-\`. * Windows Warp Drive is accessible from the status bar in Warp or you can toggle the Warp Drive side panel with `CTRL-SHIFT-\`. * Linux Warp Drive is accessible from the status bar in Warp or you can toggle the Warp Drive side panel with `CTRL-SHIFT-\`. ![Warp Drive icon on top left corner of Warp](/_astro/Open_Warp_Drive.CdkFmU8u_Z1B1uF6.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Warp Drive icon in the top-left corner. ## Workspaces in Warp Drive [Section titled “Workspaces in Warp Drive”](#workspaces-in-warp-drive) When you open the Warp Drive panel, you will find a personal workspace where you can store your Workflows, Notebooks, Prompts, and Environment Variables and organize them into folders. ![Personal workspace zero state in Warp Drive, showing where Workflows, Notebooks, Prompts, and Environment Variables are saved.](/_astro/Warp_Drive_Zero_State.ChcuOCHL_U7Smd.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) If you are a member of a team using Warp Drive, your team’s workspace will also be available in the side panel. ![Warp Drive side panel showing both a personal workspace and a team workspace.](/_astro/Warp_Drive_with_Team.DL2nCgiJ_1R1Ujq.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ## Organizing objects in Warp Drive with your team [Section titled “Organizing objects in Warp Drive with your team”](#organizing-objects-in-warp-drive-with-your-team) * Objects (e.g. Workflows, Notebooks, Prompts, and Environment Variables) and folders in Warp Drive can be sorted alphabetically and by the last updated * Any objects moved from your personal workspace into a team’s workspace will be shared with all members of your team * It is not currently possible to move an item back from a team’s workspace into a personal workspace; if you shared something inadvertently, you should copy the contents of the object to your clipboard, recreate it in your personal workspace, and then delete the object from your team workspace * It is not currently possible to drag a folder of personal Workflows into a team workspace; you will need to move objects one at a time ## Using Warp Drive offline [Section titled “Using Warp Drive offline”](#using-warp-drive-offline) In offline mode, some files will be read-only. You can still create and edit files while offline in your personal space. They will only be saved locally and will not be synced. They cannot be moved into a team or deleted until you are back online. ![Warp Drive offline mode](/_astro/warp_drive_offline.Dk_THLBq_UDHRI.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Warp Drive operating in offline mode. ## Navigating Warp Drive with your keyboard [Section titled “Navigating Warp Drive with your keyboard”](#navigating-warp-drive-with-your-keyboard) To avoid going back and forth between your mouse and keyboard, you can use your keyboard to navigate through Warp Drive once you have either opened Warp Drive or switched focus to the Warp Drive panel. (You can also click on a blank area within Warp Drive.) The object you are navigating with your keyboard will be highlighted in an accented color. You can take these keyboard actions within Warp Drive: * macOS * Press `UP`/`DOWN` or `j`/`k` to navigate to the object you want. * Press `Enter` to 1) execute an object, 2) open/collapse a workspace or folder, or 3) open the trash. * Press `CMD-ENTER` to open an object’s context menu. * Press `CMD-SHIFT-(` and `CMD-SHIFT-)` to switch focus between the terminal and Warp Drive. * Press `LEFT-ARROW` to collapse a workspace or folder * Press `RIGHT-ARROW` to open a workspace or folder * Press `Esc` to return to Warp Drive from your trash. * Windows * Press `UP`/`DOWN` or `j`/`k` to navigate to the object you want. * Press `Enter` to 1) execute an object, 2) open/collapse a workspace or folder, or 3) open the trash. * Press `CTRL-ENTER` to open an object’s context menu. * Press `CTRL-SHIFT-(` and `CTRL-SHIFT-)` to switch focus between the terminal and Warp Drive. * Press `LEFT-ARROW` to collapse a workspace or folder * Press `RIGHT-ARROW` to open a workspace or folder * Press `Esc` to return to Warp Drive from your trash. * Linux * Press `UP`/`DOWN` or `j`/`k` to navigate to the object you want. * Press `Enter` to 1) execute an object, 2) open/collapse a workspace or folder, or 3) open the trash. * Press `CTRL-ENTER` to open an object’s context menu. * Press `CTRL-SHIFT-(` and `CTRL-SHIFT-)` to switch focus between the terminal and Warp Drive. * Press `LEFT-ARROW` to collapse a workspace or folder * Press `RIGHT-ARROW` to open a workspace or folder * Press `Esc` to return to Warp Drive from your trash. ![Warp Drive navigation states](/_astro/warp_drive_nav1.G4ohbL2t_Z1eI9XM.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Navigation states in the Warp Drive sidebar. To switch between panels using your keyboard, you can use the “Switch Focus to Left Panel” and “Switch Focus to Right Panel” commands in the [Command Palette](/terminal/command-palette/). ![Switching focus between the terminal and Warp Drive panels via the Command Palette.](/_astro/warp_drive_nav2.DU2Qf42i_Z2aSJfp.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ## Import and Export [Section titled “Import and Export”](#import-and-export) Every object in Warp Drive can be exported to or imported from a file. When importing or exporting, objects are converted as follows: * [Workflows](/knowledge-and-collaboration/warp-drive/workflows/) import from and export to YAML (.yaml, .yml) * [Prompts](/knowledge-and-collaboration/warp-drive/prompts/) import isn’t supported at this time, but you can export to YAML (.yaml, .yml) * [Notebooks](/knowledge-and-collaboration/warp-drive/notebooks/) import from and export to MARKDOWN (.md) * [Environment Variables](/knowledge-and-collaboration/warp-drive/environment-variables/) import isn’t supported at this time, but you can export to DOTENV (.env) ### Importing files into Warp Drive [Section titled “Importing files into Warp Drive”](#importing-files-into-warp-drive) To import a local file or directory, `RIGHT-CLICK` on a folder or click **+** on a workspace and choose “Import.” If importing a directory, supported files in the directory and its sub-directories will be imported into a matching folder structure. ![Import modal](/_astro/notebook-import-modal.PuHOYH25_25L0Jf.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The import dialog for adding local files to Warp Drive. ### Exporting files from Warp Drive [Section titled “Exporting files from Warp Drive”](#exporting-files-from-warp-drive) To export a single Warp Drive object, `RIGHT-CLICK` on an object and choose “Export” from the menu, then select a directory for export. To export all Warp Drive objects, Open the [Command Palette](/terminal/command-palette/#how-to-access-it), search for and select “Export all Warp Drive objects”, then select a directory for export. ## Sharing your drive objects [Section titled “Sharing your drive objects”](#sharing-your-drive-objects) Every object in Warp Drive can be shared. There are three ways to share objects: * **Teams:** All members of a Warp team have full access to the objects in its Drive. * **Direct Sharing:** Objects can be shared directly with individuals by email. * **Link-based Sharing:** You can make an object public to anyone with the link, including those without Warp accounts. ### Sharing a drive object using links [Section titled “Sharing a drive object using links”](#sharing-a-drive-object-using-links) To share a Drive object, navigate to the object’s overflow menu, and choose “Copy link”. Once the link is successfully copied to your clipboard, you can share it with teammates and reference your object in your codebase, documentation, or communication channels like Slack. Note To access an object, link-followers must have permission to open it through one of the sharing methods above. If they do not have permission, they can automatically request access from the object owner or team admin. ![Copy link Menu Item](/_astro/wd-copy-link-menu.DNZWOZjs_Z2vhSVb.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Copy link option in the right-click menu. ### Managing permissions [Section titled “Managing permissions”](#managing-permissions) To manage a Drive object’s permissions, navigate to its overflow menu and choose “Share”. If the object is open, you can also use the [Command Palette](/terminal/command-palette/#how-to-access-it) and search for “Share pane”, or click the share button in the pane header: ![The pane header for a notebook, with the share button circled](/_astro/wd-share-button.DIhkQZMX_1CpquR.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The share button in the pane header. This opens a dialog that lists the current sharing settings and allows you to change them: ![A sharing dialog showing that anyone with the link can view, the owner has full access, and another user can edit.](/_astro/wd-share-dialog.CwC_VxXm_tmSRU.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Warp Drive sharing dialog. In this dialog, you can: * Invite other users directly using the email input at the top. * Change or remove the public link-based access level. * Update the access level for individual users, or remove their access. Permissions are inherited from parent folders. For example, if a folder was shared with edit permissions, then the user would also be able to edit all objects inside the folder or its subfolders. Owners and their teammates always have full access. When sharing an object, you can choose between view and edit access. | | Can view | Can edit | Full access | | ----------------------------------- | -------- | -------- | ----------- | | Read a notebook | ✓ | ✓ | ✓ | | Execute a Workflow | ✓ | ✓ | ✓ | | Use env vars | ✓ | ✓ | ✓ | | Edit contents | | ✓ | ✓ | | Create objects in a folder | | ✓ | ✓ | | Trash or untrash | | ✓ | ✓ | | Delete permanently | | | ✓ | | Modify permissions | | | ✓ | | Move to a different folder or drive | | | ✓ | ## Troubleshooting Warp Drive [Section titled “Troubleshooting Warp Drive”](#troubleshooting-warp-drive) * If you were previously using Warp on your own and were later invited to join a team, you may need to exit, update, and restart the Warp app to gain access to your team’s shared drive and commands * Navigating to Settings > Teams in Warp should also force a metadata update for you, which will ensure you have access to the latest versions of Workflows in your team’s drive # Agent Mode Context > Agents use your Warp Drive content—Workflows, Notebooks, Rules, MCP Servers, and Environment Variables—for context-aware responses. [Agent Mode](/agent-platform/local-agents/interacting-with-agents/) can leverage your [Warp Drive](/knowledge-and-collaboration/warp-drive/) contents to tailor responses to your personal and team developer workflows and environments. ## Objects used as context [Section titled “Objects used as context”](#objects-used-as-context) Agents can automatically pull in relevant context from: * **Workflows** - Saved commands and scripts * **Notebooks** - Documentation and notes * **Environment Variables** - Configuration values * **Rules** - Guidelines that shape agent behavior (see [Rules](/agent-platform/capabilities/rules/)) * **MCP Servers** - External tools and data sources (see [MCP](/agent-platform/capabilities/mcp/)) When a Warp Drive object is pulled as context, it will be displayed in the conversation as a citation under “References” or “Derived from”. ## Settings [Section titled “Settings”](#settings) Enabled by default, this can be toggled in **Settings** > **Agents** > **Knowledge** > **Warp Drive as Agent Mode Context**. ## Related [Section titled “Related”](#related) * [AI-Integrated Objects](/knowledge-and-collaboration/warp-drive/ai-objects/) - Overview of all AI-related objects in Warp Drive # AI-Integrated Objects > Access Rules, MCP Servers, Skills, and Prompts in Warp Drive to give agents personalized context. Warp Drive includes several object types that integrate with Warp’s agents to provide personalized, context-aware assistance. These objects help agents understand your coding standards, connect to external tools, and follow your preferred workflows. ## Rules [Section titled “Rules”](#rules) Rules are reusable guidelines that inform how agents respond to your prompts. They help tailor responses to match your coding standards, project conventions, and personal preferences. **Access from Warp Drive:** **Personal** > **Rules** Warp supports two types of rules: * **Global Rules** - Apply across all projects and contexts * **Project Rules** - Live in your codebase (as `AGENTS.md` or `WARP.md` files) and apply automatically when working within that project Note For complete documentation on creating and managing rules, see [Rules](/agent-platform/capabilities/rules/). ## MCP Servers [Section titled “MCP Servers”](#mcp-servers) MCP (Model Context Protocol) servers extend Warp’s agents with custom tools and data sources through a standardized interface. They act as plugins that let agents access external services like GitHub, Sentry, Linear, Slack, and more. **Access from Warp Drive:** **Personal** > **MCP Servers** MCP servers can be: * **CLI-based** - Local commands that Warp launches and manages * **URL-based** - Remote endpoints using Streamable HTTP or SSE Note For complete documentation on configuring and using MCP servers, see [Model Context Protocol (MCP)](/agent-platform/capabilities/mcp/). ## Skills [Section titled “Skills”](#skills) Skills are reusable instruction sets that teach agents how to perform specific tasks. Unlike Rules (which provide guidelines), Skills define complete workflows that agents can invoke when relevant. Skills are file-based (stored as `SKILL.md` files in your project or home directory) rather than cloud-synced objects, but they integrate closely with Warp Drive workflows. * **Project Skills** - Live in `.agents/skills/`, `.warp/skills/`, or similar directories in your repository * **Global Skills** - Live in `~/.agents/skills/` or similar directories in your home folder Note For complete documentation on creating and using skills, see [Skills](/agent-platform/capabilities/skills/). ## Prompts [Section titled “Prompts”](#prompts) Prompts are parameterized natural language queries you can save and reuse with Agent Mode. They allow you to save complex AI workflows and execute them quickly from the Command Palette. **Access from Warp Drive:** Click **+** and select “Prompt”, or browse existing prompts in your personal or team workspace. Note For complete documentation on Prompts, see [Prompts](/knowledge-and-collaboration/warp-drive/prompts/). ## How agents use these objects [Section titled “How agents use these objects”](#how-agents-use-these-objects) When you start an agent conversation, Warp automatically provides relevant context from your Warp Drive objects: * **Rules** guide agent behavior and responses based on your preferences * **MCP Servers** give agents access to external tools and data sources * **Skills** provide task-specific instructions agents can invoke * **Prompts** let you trigger predefined workflows quickly When an object is used as context, it appears in the conversation under “References” or “Derived from.” Note For more details on how Warp Drive content serves as agent context, see [Warp Drive as Agent Mode Context](/knowledge-and-collaboration/warp-drive/agent-mode-context/). ## Related [Section titled “Related”](#related) * [Rules](/agent-platform/capabilities/rules/) - Create guidelines for agent behavior * [MCP Servers](/agent-platform/capabilities/mcp/) - Connect external tools and data sources * [Skills](/agent-platform/capabilities/skills/) - Define reusable task workflows * [Prompts](/knowledge-and-collaboration/warp-drive/prompts/) - Save and reuse parameterized agent prompts * [Agent Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/) - Control agent autonomy and tool access # Environment variables > Save or sync environment variables to load into your terminal sessions. ## What are environment variables in Warp? [Section titled “What are environment variables in Warp?”](#what-are-environment-variables-in-warp) Environment variables in Warp are similar to .env files, except you can: * Load them into your terminal session with a click. * Use them in parameterized workflows. * Dynamically reference secrets from external managers. ## How to create and edit environment variables [Section titled “How to create and edit environment variables”](#how-to-create-and-edit-environment-variables) You can create new environment variables through: * [Warp Drive](/knowledge-and-collaboration/warp-drive/), + → Environment variable * [Command Palette](/terminal/command-palette/), create new team or personal environment variables Any of these entry points will open the environment variables editor where you can name and describe your environment variables. ![Environment variable editor in Warp Drive showing fields for name and description.](/_astro/env-var-create.Dvr5P5yi_bmo4S.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ## Managing individual environment variables [Section titled “Managing individual environment variables”](#managing-individual-environment-variables) Warp supports two types of environment variables: static variables and dynamic variables. ### Static variables [Section titled “Static variables”](#static-variables) Static variables are similar to .env files. You create the variables by entering raw strings of text. Each variable has a variable name and a corresponding value. ![Saving a static environment variable with name and value pairs.](/_astro/env-var-static-variable-save.DEikx-Hy_rQPet.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) After you save the environment variable, you can click it to load it into your terminal session. ![Loading a saved static environment variable into the current terminal session.](/_astro/env-var-static-variable-load.CwOi2SYo_VDUzv.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) When you use static variables, Warp stores them securely in Warp Drive.\ \ Note: Static variables should not be used to replace a secret manager. Please use dynamic variables for any sensitive information. ### Dynamic variables [Section titled “Dynamic variables”](#dynamic-variables) Note Warp never stores secrets used in dynamic variables. Warp only stores the command used to dynamically retrieve the secrets at runtime. Dynamic variables let you reference secrets that are stored securely outside of Warp in external secret managers, such as 1Password or LastPass. You can use custom commands to create dynamic variables for any system with a public API or CLI, such as AWS or Hashicorp Vault. ### **How to create and edit dynamic environment variables** [Section titled “How to create and edit dynamic environment variables”](#how-to-create-and-edit-dynamic-environment-variables) To create a new dynamic variable: 1. Open the environment variable editor. 2. Use the key icon to reveal the dynamic variable menu. 3. Select an integrated password manager or “Command” to write your own custom integration. ![Opening the dynamic environment variable menu via the key icon in the editor.](/_astro/env-var-dynamic-variables.O4at8Gp7_n6WQP.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### **Integrated password managers** [Section titled “Integrated password managers”](#integrated-password-managers) Before you get started, please ensure you have the CLI installed for your tool of choice and follow the instructions to enable the CLI: * [1Password CLI](https://developer.1password.com/docs/cli/get-started/) * [LastPass CLI](https://github.com/lastpass/lastpass-cli) Then, you can click the key icon and select your manager from the dropdown menu. ![Selecting an integrated password manager from the dynamic variable dropdown.](/_astro/env-var-password-mgrs.CUonFfOA_goyUz.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The CLI will require you to authenticate and then provide you with a list of available secrets. Note Selecting a secret name never stores the actual secret. Warp uses your selection to generate a command that dynamically pulls in your selected secret at runtime. ![Selecting a secret name from the password manager CLI's available list of secrets.](https://lh7-rt.googleusercontent.com/docsz/AD_4nXcqiazhpRvaHxxSW5n3Ql6nFRDDRkyVdlRB9E-Q6HE0lpL2KFgwLM1P1PPrJG_i0KIHWuEKp2PMFq4T1auWvQOxXrpuERpLRZG1h2V4DDYmNRZRqShxjPzWyqGR2VfXYNhttAK0HT2-aQNjAt3xdCA9MwE?key=q_xMyXgvJVA02ysqZAH4Jw) ### **How to write a custom secret command** [Section titled “How to write a custom secret command”](#how-to-write-a-custom-secret-command) Reference the documentation for your external secret manager. Then, write a custom command to retrieve secrets. Note Your custom command should return the exact string you want loaded into your environment. Please make sure that you are selecting the exact field you want loaded as many secret manager CLIs provide additional formatting by default. For example, you can write a command using the [Hashicorp Vault CLI](https://developer.hashicorp.com/vault/docs/commands) to retrieve and load the password field for the staging server. When using secret commands, Warp stores the command but never the actual secrets. The secrets are referenced and loaded into a terminal session at runtime. ```plaintext // vault kv get -field=password secret/staging/app/server/creds ``` ![Custom command using the Hashicorp Vault CLI to retrieve a password field at runtime.](https://lh7-rt.googleusercontent.com/docsz/AD_4nXcltckpSwesjA1O84nzZhUKc0Wuie0OH3iN6g0WPBojhtY5pckPSZgOZxqIjiV12ppe9t0jtF9z2Yf7d-fIZJhSu8-tLIT8CoG_Xh_NvCzFbrJgD5FA2ounNtHurq9nDLALiOekjPeVoru-FzeYOWkfm9PN?key=q_xMyXgvJVA02ysqZAH4Jw) ### Using environment variables [Section titled “Using environment variables”](#using-environment-variables) There are three ways to invoke your environment variables and load them into a terminal session: 1. [Click to load into a current section](/knowledge-and-collaboration/warp-drive/environment-variables/#click-to-load-into-a-current-session) 2. [Click to load into a subshell](/knowledge-and-collaboration/warp-drive/environment-variables/#click-to-load-into-a-subshell) 3. [Select to load in with a workflow](/knowledge-and-collaboration/warp-drive/environment-variables/#select-to-load-with-a-workflow) #### Click to load into a current session [Section titled “Click to load into a current session”](#click-to-load-into-a-current-session) First, click your environment variable from Warp Drive or the Command Palette. Then, review the confirmation block. If your environment variables are correct, hit enter to load them into your session. ![Confirmation block prompting to load environment variables into the current session.](/_astro/env-var-load-to-input-1.BBRIj7me_Z1lOgJV.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ![Environment variables successfully loaded into the current terminal session.](/_astro/env-var-load-in-session.B5k-C33J_1KEWM7.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) These environment variables will now be present for the remainder of your session. #### Click to load into a subshell [Section titled “Click to load into a subshell”](#click-to-load-into-a-subshell) To load environment variables into a subshell, you will need to open [Warp Drive](/knowledge-and-collaboration/warp-drive/) and locate your environment variable in the Warp Drive index. You can then use the overflow menu to select “Load in subshell.” Loading an environment into a subshell reduces the risk of your environment variables accidentally contaminating your workspace. The subshell is clearly defined and once you exit it, any environment variables set by Warp Environment Variables will be cleared, unless they are already present in the parent session. ![Selecting Load in subshell from an environment variable's overflow menu in Warp Drive.](https://lh7-rt.googleusercontent.com/docsz/AD_4nXeqhj2saz5AJTYUCx-PClwCLX421mKEzXelcnnkeHkqvDexelvBDmPpESHOmV_SjAOEuLKk8YgYaIodX-cOuXm1Nm05wUU88zcIv3otd1HRvXO455EiKEfs5tTB5ft9OoW7qxMK9BV1OPAVIc9AhMqsgweK?key=q_xMyXgvJVA02ysqZAH4Jw) ![Environment variables loaded into a subshell, isolated from the parent terminal session.](https://lh7-rt.googleusercontent.com/docsz/AD_4nXeeXyJEMxJV2DpOBJS7pKOEpBSm6aypAIKd4ygJKT13opDBxeS5k0S5NtM8Cr_Z_lafyj-cn1T-hJ-93AkZhpWTrbvYHYIRs96_V7dr3mfiM3lPx6-kMS_eLjINPHIr6Ex0NaMr-TRCkNQ1fdVv8cApJ0QJ?key=q_xMyXgvJVA02ysqZAH4Jw) #### Select to load with a workflow [Section titled “Select to load with a workflow”](#select-to-load-with-a-workflow) Any time you run a workflow, you can select from existing environment variables. This allows you to dynamically inject environment variables into a parameterized workflow so you can use a single workflow command in multiple environments, such as production and staging. For example, you may have a workflow to create a new team that uses the environment variable $SERVER\_URL. By using the environment variables dropdown in the workflow card, you can dynamically inject the necessary variables. This ensures the workflow references the appropriate values so the command runs with the relevant environment-specific information. These environment variables will now be present for the remainder of your session until you clear them or overwrite them with a different environment. ![Selecting environment variables from the dropdown when running a parameterized workflow.](https://lh7-rt.googleusercontent.com/docsz/AD_4nXcuOxH8UeVLSvWRpZwvdoVBgbpFhb2rXKbDw2CnZ5BQCTWSgzjwERe-fzKLEYBQZGKzjV-Pdd_z6tB9BTSWYos9ADRaDbChskSg-MZpjaKme0kG8UwWsJ2HBJk7iBu4SKbGZCobZy0uD2nFkrNoVjNZEEOW?key=q_xMyXgvJVA02ysqZAH4Jw) ### Import and export environment variables in Warp Drive [Section titled “Import and export environment variables in Warp Drive”](#import-and-export-environment-variables-in-warp-drive) Please see our [Warp Drive Import and Export](/knowledge-and-collaboration/warp-drive/#import-and-export) instructions. # Warp Drive Notebooks > Save interactive playbooks to simplify onboarding and development. ### What is a Notebook? [Section titled “What is a Notebook?”](#what-is-a-notebook) Notebooks are runnable documentation consisting of markdown text and list elements, code blocks, and runnable shell snippets that can be automatically executed in your terminal session. Notebooks are searchable and accessible through the [Command Palette](/terminal/command-palette/) so you can access and run your documentation without ever leaving the terminal. You can also export Notebooks in .md format at any time. ### How to save and edit notebooks [Section titled “How to save and edit notebooks”](#how-to-save-and-edit-notebooks) You can create a new notebook from various entry points in Warp * macOS * From Warp Drive, + > New notebook * From the [Command Palette](/terminal/command-palette/), create a new team or personal notebook. * Windows * From Warp Drive, + > New notebook * From the [Command Palette](/terminal/command-palette/), create a new team or personal notebook. * Linux * From Warp Drive, + > New notebook * From the [Command Palette](/terminal/command-palette/), create a new team or personal notebook. Any of these entry points will open the notebook editor where you can: * Title your notebook. * Start adding text and code elements. Note Note: The notebook will not be saved until either title or body text is added. ![Editing a Notebook](/assets/terminal/notebooks_editor.gif) Editing a Notebook. ### Working with Notebooks [Section titled “Working with Notebooks”](#working-with-notebooks) #### Adding new elements [Section titled “Adding new elements”](#adding-new-elements) Notebook elements (text, code, list items) can be added in several ways: * Using the appropriate markdown shortcut (e.g. ### for Heading 3). * Typing /, which will open up a selection menu of supported elements. * Pressing the + icon which appears when hovering over a line and selecting from the menu of supported elements. ![Markdown element types](/_astro/markdown-element-types.CTLJx7pw_Zcgi1B.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Available Markdown element types in the Notebook editor. #### Styling existing elements [Section titled “Styling existing elements”](#styling-existing-elements) Existing notebook elements can be styled in several ways: * Selecting an existing element and selecting text decorations (like bold, italics, or inline code) from the hover menu. * Using markdown syntax for text stylings like \*\*bold\*\* or \*italic\*. * Selecting an existing element and changing the overall type of the element via the dropdown element menu. ![Styling menu](/_astro/styling-menu.C8WyUNfM_Z1TEpp0.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### Using Command and Code Blocks [Section titled “Using Command and Code Blocks”](#using-command-and-code-blocks) Command and code blocks have several unique properties such as syntax highlighting and quick actions that make working with code-based documentation simple. You can create a code or command block by either: * Selecting Command or Code from the new element menu * Typing ` ``` ` (triple backticks) Once you’ve inserted your code block you can select the language at the bottom of the block from numerous options which will apply the appropriate syntax highlighting if available (or default to Code if your language is not found). All code and command blocks will apply syntax highlighting and provide a quick copy button for easy access. ![Example code block](/_astro/notebook-code-block.BzAcc2Oq_Vvxqk.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) A code block with syntax highlighting in a Notebook. #### Special properties of command blocks [Section titled “Special properties of command blocks”](#special-properties-of-command-blocks) If you insert a Command block or specify the language as “Shell”, Warp provides extra functionality to simplify terminal work. #### Executing Command Blocks [Section titled “Executing Command Blocks”](#executing-command-blocks) Developers can execute shell command blocks by: * macOS * Using the insert button at the bottom of the block * Pressing `CMD-ENTER` while the block is selected (a blue highlight will appear) * Windows * Using the insert button at the bottom of the block * Pressing `CTRL-ENTER` while the block is selected (a blue highlight will appear) * Linux * Using the insert button at the bottom of the block * Pressing `CTRL-ENTER` while the block is selected (a blue highlight will appear) The command text will be inserted into the developer’s active terminal session, or a new session if none are active. ![Run option for command block](/_astro/notebook-cmd-block-run.C-jOs0Zk_ZNOywX.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The run button on a command block in a Notebook. #### Adding arguments to Command Blocks [Section titled “Adding arguments to Command Blocks”](#adding-arguments-to-command-blocks) Command blocks accept parameters in the same format as [Workflows](/knowledge-and-collaboration/warp-drive/workflows/). To add an argument to your command block, use `{{double_curly_brackets}}` to specify your argument term. ![Command block with parameters](/_astro/notebook-cmd-with-params.C4qN63Ng_Zdbua9.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) A command block with editable parameters. #### Navigating command blocks with the keyboard [Section titled “Navigating command blocks with the keyboard”](#navigating-command-blocks-with-the-keyboard) Command Blocks also support keyboard navigation. There are two ways to enter the keyboard navigation mode: * macOS * Clicking on a shell block. * Pressing `CMD-UP` or `CMD-DOWN.` Once a command block is selected, press `CMD-ENTER` to insert it into the terminal input. You can also use `UP, DOWN, CMD-UP`, and `CMD-DOWN` to navigate between command blocks. While the Notebook is focused, press `CMD-L` to switch focus back to the terminal without inserting a command. * Windows * Clicking on a shell block. * Pressing `CTRL-UP` or `CTRL-DOWN.` Once a command block is selected, press `CTRL-ENTER` to insert it into the terminal input. You can also use `UP, DOWN, CTRL-UP,` and `CTRL-DOWN` to navigate between command blocks. While the Notebook is focused, press `CTRL-L` to switch focus back to the terminal without inserting a command. * Linux * Clicking on a shell block. * Pressing `CTRL-UP` or `CTRL-DOWN.` Once a command block is selected, press `CTRL-ENTER` to insert it into the terminal input. You can also use `UP, DOWN, CTRL-UP,` and `CTRL-DOWN` to navigate between command blocks. While the Notebook is focused, press `CTRL-L` to switch focus back to the terminal without inserting a command. #### Adding existing Workflows to notebooks [Section titled “Adding existing Workflows to notebooks”](#adding-existing-workflows-to-notebooks) If you have existing [Workflows](/knowledge-and-collaboration/warp-drive/workflows/) that you’d like to insert into your notebook rather than duplicating their content, you can select Embedded Workflow from the new element menu and select from the available Workflows. Once embedded in a notebook, the workflow will be executable like a regular command block. To edit the content of the embedded workflow, you will need to edit the source workflow which can be found by searching for the title in the [Command Palette](/terminal/command-palette/). ![Embedding an existing workflow in a notebook.](/_astro/embedding-a-workflow.CIgUXFwn_1C2gaq.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Embedding an existing workflow in a notebook. ### Working with Notebooks in a team [Section titled “Working with Notebooks in a team”](#working-with-notebooks-in-a-team) If the notebook is shared with a team, all team members will have access to edit the notebook and updates will sync immediately for all members of the team. Note Note that only one editor is allowed at a given time. Opening the notebook while there is an active editor will open the notebook in Viewing mode. Your mode (view vs edit) can be toggled above the notebook’s title. ![View mode example](/_astro/notebook-view-mode.Bguvl8rp_ZOI8y8.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) A Notebook displayed in view mode. ### Import and export notebooks in Warp Drive [Section titled “Import and export notebooks in Warp Drive”](#import-and-export-notebooks-in-warp-drive) Please see our [Warp Drive Import and Export](/knowledge-and-collaboration/warp-drive/#import-and-export) instructions. # Warp Drive prompts > Save and reuse parameterized Agent Mode prompts to run on-demand. ## What is a prompt? [Section titled “What is a prompt?”](#what-is-a-prompt) A prompt is a parameterized natural language query you can name and save in Warp to use with [Agent Mode](/agent-platform/local-agents/interacting-with-agents/). Prompts are searchable and easily accessed from the [Command Palette](/terminal/command-palette/) so you can find and execute them without switching context. They allow you to save and reuse specific and complex AI workflows, making it easier to repeat multi-step tasks with Agent Mode. ![View of a Prompt in Warp Drive showing the command view interface](/_astro/prompts-command-view.jXp_5xkt_Z1K5x3L.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Command view of a Prompt in Warp Drive. ### Demo: Trigger reusable actions with saved prompts [Section titled “Demo: Trigger reusable actions with saved prompts”](#demo-trigger-reusable-actions-with-saved-prompts) Here’s an example from [Warp Guides](/guides/), where Zach walks through what prompts he uses for PRs and Git commits: ![YouTube video](https://i.ytimg.com/vi/pE15zjJmB4E/sddefault.jpg) There are other great examples of prompts on [Do Things](https://dothings.warp.dev/) and [Warp Guides](/guides/). ## How to save and edit prompts [Section titled “How to save and edit prompts”](#how-to-save-and-edit-prompts) You can create a new prompt from Warp Drive by clicking the + button and selecting “Prompt”. * Name your prompt * Edit the natural language query along with any arguments (also known as parameters) * Add a meaningful description that will be indexed for search (optional) * Add arguments, descriptions for arguments, and default values (optional) ![View of the Prompt editor interface showing the edit form with fields for name, query, description, and arguments](/_astro/prompts-edit-view.DVg3_fLB_ZDVQCa.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Edit view of a Prompt in Warp Drive. Once a prompt has been created, you can edit it at any time, as long as you have access to an internet connection. ### Working with arguments [Section titled “Working with arguments”](#working-with-arguments) In the prompt editor, you can add arguments manually with “New argument” or by typing in double curly braces (`{{argument}}`) within the command field. If you select “New argument” while you have text selected, Warp will wrap that text in curly braces to create an argument. There are some rules for creating valid arguments: * Argument names can only include characters `A-Za-z0-9`, hyphens `-` and underscores `_` * The first character of an argument cannot be a number Arguments can be one of two types: text or enum. By default, all new arguments are text type. #### Enum type arguments [Section titled “Enum type arguments”](#enum-type-arguments) Enums allow you to specify expected inputs to a prompt argument. When you insert a prompt with enums into the input editor, you will be prompted with suggestions for filling in the argument. You can open the suggestions menu by pressing `SHIFT-TAB` while selecting an argument. For detailed information about creating and using enum type arguments, please see the [Enum type arguments section in Workflows documentation](/knowledge-and-collaboration/warp-drive/workflows/#enum-type-arguments). ### Editing prompts with a team [Section titled “Editing prompts with a team”](#editing-prompts-with-a-team) If the prompt is shared with a team, all team members will have access to edit it and updates will sync immediately for all members of the team. If a prompt in the Warp Drive has been edited by another team member or a user on another device while you are attempting to edit the same prompt, you will not be able to save changes; you will need to check out the latest version and try again. ## How to execute prompts [Section titled “How to execute prompts”](#how-to-execute-prompts) You can execute a prompt in several ways: * From Warp Drive, click the prompt * From the [Command Palette](/terminal/command-palette/) or [Command Search](/terminal/entry/command-search/), search for a prompt by name or type “prompts:” to see all available prompts and your prompt history * When a prompt is selected, you can use `SHIFT-TAB` to cycle through the arguments. ![Command Palette interface showing a search for Prompts with results displayed](/_astro/prompts-command-palette.CX2MSXQx_2anvXP.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Searching for Prompts in the Command Palette. ![Command Search interface showing a search for Prompts with results displayed](/_astro/prompts-command-search.D5Cd5OOx_qfY9K.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Searching for Prompts in Command Search. These options will paste the prompt into your active terminal input. Prompt names and any relevant descriptions and arguments will be displayed in a dialog, so you can understand how to use the prompt. You can make any adjustments you need to the arguments before running the prompt in your input editor. ### Import and export prompts in Warp Drive [Section titled “Import and export prompts in Warp Drive”](#import-and-export-prompts-in-warp-drive) Please see our [Warp Drive Import and Export](/knowledge-and-collaboration/warp-drive/#import-and-export) instructions. # Warp Drive on the web > Access your Warp Drive objects and shared sessions from any browser or touch screen device, including mobile phones, tablets, and touch-enabled laptops. ## What is Warp on the web? [Section titled “What is Warp on the web?”](#what-is-warp-on-the-web) Warp Drive on the Web lets you view and edit your Warp Drive objects and shared sessions directly in the browser, on any device. ![A web-based rendering of a Team Workflow](/_astro/wd-web-team-workflow.D19PEo6u_ZzPG95.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) A web-based rendering of a Team Workflow. ## How to access Warp on the web [Section titled “How to access Warp on the web”](#how-to-access-warp-on-the-web) Warp’s web-based viewing experience can currently be accessed via: * The [`app.warp.dev/app` homepage](https://app.warp.dev/app) * [Drive Object](/knowledge-and-collaboration/warp-drive/#sharing-your-drive-objects) Links * [Session Sharing](/knowledge-and-collaboration/session-sharing/#how-to-allow-access-to-collaborators-in-your-session) Links Caution You can edit and view web-based objects and sessions as normal. The one exception is executing a command from a workflow or notebook since there is no shell session running on the web. ## Managing your view preferences - web or desktop [Section titled “Managing your view preferences - web or desktop”](#managing-your-view-preferences---web-or-desktop) If the Warp app is installed, links will open on the desktop by default. You can manage whether Warp links open in Warp’s desktop app or the browser in multiple ways: Note The desktop option is only presented if Warp’s web service is able to detect the Warp app installed locally. Warp desktop opens localhost port 9277 to accomplish this detection. This is done in a separate process that does not have access to your terminal contents.\ \ If you would like to use Warp locally and do not have it installed, please visit our [installation guide.](/getting-started/quickstart/installation-and-setup/) 1. The first time you follow a link, if Warp is not installed, you will be prompted to download it. You can dismiss the popup to stay on the web. ![Popup prompting to download Warp Desktop when viewing a Drive object on the web](/_astro/wd-popup-message.CLNdzM5N_wcirX.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) 2. This preference can be changed at any point in **Settings** > **Features** > **General** > **Open links in desktop app** Note that this setting is only available while on the web-based version of Warp. ![Setting managing how to open links](/_astro/wd-open-links-preference.BVpnHS6M_1t2Poo.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Setting managing how to open links. 3. You can always switch between web and desktop views on a case-by-case basis. 1. To switch from a web-view to Desktop for a given object, open the *overflow menu > Open link on Desktop.* ![Overflow menu on a web-based Drive object with the Open on Desktop option highlighted](/_astro/wd-switch-viewer.D41reL3S_u1Prn.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) 2. To stay on the web for a given object despite a global Desktop preference, follow the *View on the web* option that is part of the redirect screen to Desktop. ![Redirect screen with Open Warp and View on the web options](/_astro/wd-view-on-web.CaUmkF6I_Z1Tnyvt.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ## Supported Browsers [Section titled “Supported Browsers”](#supported-browsers) Warp on the web supports all modern browsers, including: **Desktop** * Chrome * Firefox * Safari **Mobile** * iOS Safari 15+ * Android Chrome 58+ * Samsung Internet 7.2+ Note These mobile browser versions are the minimum required for WebGL 2.0 support. Most up-to-date devices meet these requirements. ## Touch screen and mobile support [Section titled “Touch screen and mobile support”](#touch-screen-and-mobile-support) Warp supports all touch screen devices, including mobile phones, tablets, and touch-enabled laptops. Touch input works on both the web and the desktop app. ### Supported gestures [Section titled “Supported gestures”](#supported-gestures) * **Touch and scroll** - Vertical and horizontal scrolling work as expected * **Double tap** - Select text or elements * **Long press (hold)** - Open context menu (equivalent to right-click) ## Related features [Section titled “Related features”](#related-features) * [Warp Drive](/knowledge-and-collaboration/warp-drive/) - Store and share workflows, prompts, and environment variables * [Session Sharing](/knowledge-and-collaboration/session-sharing/) - Collaborate with others in real-time terminal sessions # Warp Drive Workflows > Save parameterized commands as Workflows and execute them on-demand from Warp Drive. ## What is a workflow? [Section titled “What is a workflow?”](#what-is-a-workflow) A workflow is a parameterized command you can name and save in Warp with descriptions and arguments. Workflows are searchable and easily accessed from the [Command Palette](/terminal/command-palette/) so you can find and execute them without switching contexts. ## How to save and edit workflows [Section titled “How to save and edit workflows”](#how-to-save-and-edit-workflows) You can create a new workflow from various entry points in Warp: * From Warp Drive, + > New workflow * Using Block Actions, Save as Workflow * From Oz agent results, Save as Workflow * From the [Command Palette](/terminal/command-palette/), Create a New Personal Workflow Any of these entry points will open the workflow editor where you can: * Name your workflow * Edit the command along with any arguments (also known as parameters) * Add a meaningful description that will be indexed for search (optional) * Add arguments, descriptions for arguments, and default values (optional) ![Workflows save and edit modal](/_astro/edit-workflow-pane.BbMcWUyb_Z1SG4WO.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Workflows save / edit pane. ![Save Workflow Demo](https://i.ytimg.com/vi/8UmreUTTrkg/sddefault.jpg) ### Working with arguments [Section titled “Working with arguments”](#working-with-arguments) In the workflow editor, you can add arguments manually with “New argument” or by typing in double curly braces (`{{argument}}`) within the command field. If you select “New argument” while you have text selected, Warp will wrap that text in curly braces to create an argument. There are some rules for creating valid arguments: * Argument names can only include characters `A-Za-z0-9`, hyphens `-` and underscores `_` * The first character of an argument cannot be a number Arguments can be one of two types: text or enum. By default, all new arguments are text type. #### Enum type arguments [Section titled “Enum type arguments”](#enum-type-arguments) Enums allow you to specify expected inputs to a workflow argument. When you insert a workflow with enums into the input editor, you will be prompted with suggestions for filling in the argument. You can open the suggestions menu by pressing `SHIFT-TAB` while selecting an argument. [Enum Input Suggestions Demo](https://www.loom.com/embed/b2f54eeef2f247a8bbcf87698b2a4287) To create an enum type argument: 1. Navigate to the “default value” field of an argument. 2. Select the “Enum” type. 3. Click “New” to create a new enum, or select an existing one from the dropdown menu. 4. If you selected “New”, you can choose to create a “Static” enum or “Dynamic” enum. Dynamic enums are associated with a shell command whose output is parsed to determine the set of valid values for that argument. [Enum Creation Demo](https://www.loom.com/embed/b429ab7f7014418e9591e505fd71af83) ### Working with aliases [Section titled “Working with aliases”](#working-with-aliases) Workflow aliases allow you to create personalized shortcuts and custom configurations for your frequently used workflows. These aliases provide enhanced flexibility in how you use and configure workflows. Aliases are personal to your account, not shared with everyone who has the workflow. If settings sync is enabled, they’ll be synced across devices logged in to your account. Aliases can set default values for each [argument](/knowledge-and-collaboration/warp-drive/workflows/#working-with-arguments), but don’t have to. Aliases can have [Environmental Variables](/knowledge-and-collaboration/warp-drive/environment-variables/) associated with them. Note Workflow aliases are not compatible with [YAML Workflows](/terminal/entry/yaml-workflows/). They can only be used with Workflows created in [Warp Drive](/knowledge-and-collaboration/warp-drive/). ### Editing workflows [Section titled “Editing workflows”](#editing-workflows) Once a workflow has been created, you can edit it at any time, as long as you have access to an internet connection. ![Edit workflow menu](/_astro/Edit_Workflow.CcJ7p5oy_SdnH2.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The edit menu for a Workflow in Warp Drive. #### AI Autofill [Section titled “AI Autofill”](#ai-autofill) Workflows also have the option to use an [Oz agent](/agent-platform/local-agents/overview/) to automatically generate a title, descriptions, or parameters. * Create or edit a Workflow, in the edit view you should see the option to AutoFill. * Warp will fill in the fields based on the Workflow you’re creating. [![](/assets/terminal/Edit-workflows-autofill.poster.jpg)](/assets/terminal/Edit-workflows-autofill.mp4) ### Editing workflows with a team [Section titled “Editing workflows with a team”](#editing-workflows-with-a-team) If the workflow is shared with a team, all team members will have access to edit the workflow and updates will sync immediately for all members of the team. If a workflow in the Warp Drive has been edited by another team member or a user on another device while you are attempting to edit the same workflow, you will not be able to save changes; you will need to check out the latest version and try again. ## How to execute workflows [Section titled “How to execute workflows”](#how-to-execute-workflows) You can execute a workflow in several ways: * From Warp Drive, click the workflow * From the [Command Palette](/terminal/command-palette/), search for a workflow you’d like to execute, click or select, and enter * From [Command Search](/terminal/entry/command-search/), search for a workflow you’d like to execute, click or select, and enter. * When a workflow is selected, you can use `SHIFT-TAB` to cycle through the arguments. Note When you create two or more arguments with the same name, Warp automatically selects and puts multiple cursors over the arguments in the input editor so they are synced.\ \ Also, tailor your Command Search experience by toggling off “Show Global Workflows” in **Settings** > **Features**. When disabled, your search will exclusively encompass YAML and Warp Drive Workflows. ![Search for any workflow in the Command Palette with CMD + P](/_astro/search-workflow-command-palette.BJt4WVWQ_P4X3v.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Searching for Workflows in the Command Palette. These options will paste the workflow into your active terminal input. Workflow names and any relevant descriptions and arguments will be displayed in a dialog, so you can understand how to use the workflow. ![Execute a Workflow](/_astro/execute-a-workflow.DGX2Uhbc_Z1gWnOl.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Executing a Workflow from Warp Drive. You make any adjustments you need to the arguments (or the command itself) before running the command in your input editor. ![Running Workflow Demo](https://i.ytimg.com/vi/8UmreUTTrkg/sddefault.jpg) ## Support for YAML Workflows [Section titled “Support for YAML Workflows”](#support-for-yaml-workflows) Warp will indefinitely support the [YAML Workflows](/terminal/entry/yaml-workflows/), which includes personal and community workflows sourced from an open-source repository. If needed, you can continue to access your `.yaml` file workflows using [Command Search](/terminal/entry/command-search/) or the [Command Palette](/terminal/command-palette/). However, these file-based workflows will not be available to access, organize, or share in Warp Drive. ### Import and export workflows in Warp Drive [Section titled “Import and export workflows in Warp Drive”](#import-and-export-workflows-in-warp-drive) Please see our [Warp Drive Import and Export](/knowledge-and-collaboration/warp-drive/#import-and-export) instructions. # Warp quickstart > Get up and running with Warp in about 10 minutes. Install, run your first commands, talk to an agent, and discover what makes Warp different. This guide walks you through installing Warp, trying the terminal features you’ll use every day, and firing off your first agent prompt. After completing the steps in this guide, you’ll have a working Warp setup and a clear picture of how terminal commands and agents work together. *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **macOS, Windows, or Linux** - See [Installation and setup](/getting-started/quickstart/installation-and-setup/) for minimum requirements per platform. *** ## 1. Install Warp [Section titled “1. Install Warp”](#1-install-warp) Download Warp from [warp.dev](https://www.warp.dev/download) and follow the installer for your platform. * macOS Download and drag Warp into your Applications folder, or install with Homebrew: ```bash brew install --cask warp ``` * Windows Download and run the installer, or install with WinGet: ```powershell winget install Warp.Warp ``` * Linux Download the package for your distribution from [warp.dev/download](https://www.warp.dev/download). For Debian/Ubuntu: ```bash sudo apt install ./warp-terminal.deb ``` See [Installation and setup](/getting-started/quickstart/installation-and-setup/) for all Linux options. When you launch Warp, you’ll see a terminal session ready for input. You can optionally sign up for an account (top right), or skip and start using Warp immediately. ## 2. Run a command and see Blocks [Section titled “2. Run a command and see Blocks”](#2-run-a-command-and-see-blocks) Run any command you’d normally use, for example: ```bash ls -la ``` You’ll notice the output looks different from a traditional terminal. Every command and its output is grouped into a **Block** — a contained unit you can copy, search, filter, and navigate independently. Blocks are the foundation of how Warp organizes your terminal. **What you can do with Blocks:** * Click a Block to select it, then press `⌘C` (macOS) or `Ctrl+Shift+C` (Windows/Linux) to copy the output * Use `⌘↑`/`⌘↓` (macOS) or `Ctrl+↑`/`Ctrl+↓` (Windows/Linux) to navigate between Blocks * Click the filter icon on a Block to search within its output Learn more about navigating, selecting, and acting on output in [Block basics](/terminal/blocks/block-basics/). ## 3. Try the input editor [Section titled “3. Try the input editor”](#3-try-the-input-editor) Warp’s input isn’t a standard terminal prompt, it’s a real text editor. Try the following functionality: * **Multi-line editing** - Press `Shift+Enter` to add a new line. Try typing three separate `echo` lines, pressing `Shift+Enter` between each, then `Enter` to run them all at once. * **Click to place your cursor** - Click anywhere in your input to move the cursor, just like a text editor. * **Select and edit** - Click and drag to select text, then type to replace it. All three commands run in sequence, and each produces its own Block. No need to run commands one at a time. Learn more about cursor movement, selections, and multi-line input in [Modern text editing](/terminal/editor/). ## 4. See autosuggestions and completions [Section titled “4. See autosuggestions and completions”](#4-see-autosuggestions-and-completions) Start typing a command you’ve run before. You’ll see a faded suggestion appear inline based on your shell history. Press `→` to accept it instantly. Press `Tab` while typing to see completions for commands, flags, and file paths. Warp provides enhanced completions beyond what your shell offers natively. If you mistype a command, Warp detects the error and suggests a correction. Accept the fix or dismiss it and continue. Learn more about [Autosuggestions](/terminal/command-completions/autosuggestions/) and [Tab completions](/terminal/command-completions/completions/). ## 5. Ask your first agent question [Section titled “5. Ask your first agent question”](#5-ask-your-first-agent-question) Everything you’ve done so far has been in **terminal mode**, running shell commands the way you normally would. Warp also has **Agent Mode**, a dedicated conversation view where you interact with Oz, Warp’s built-in agent, using natural language. Start an agent conversation by pressing `⌘↩` (macOS) or `Ctrl+Shift+Enter` (Windows/Linux). Then type a prompt: ```plaintext Explain the architecture of this project ``` Oz reads your codebase, understands its structure, and responds with a context-aware explanation. From here you can ask follow-up questions, have Oz write or refactor code, debug errors, or run commands on your behalf — all within the same conversation. Note You don’t always need to switch modes manually. If you type a natural-language prompt in terminal mode, Warp auto-detects it and offers to send it to an agent. Warp also works with third-party CLI agents like Claude Code and Codex. Learn more about [third-party CLI agents](/agent-platform/cli-agents/overview/). To learn more about switching between modes, see [Terminal and Agent modes](/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes/). *** ## What to explore next [Section titled “What to explore next”](#what-to-explore-next) Now that you have the basics, check out the features that make Warp a full development environment: * **[Customizing Warp](/getting-started/quickstart/customizing-warp/)** — Pick a theme, configure your prompt, choose your AI model, and import keybindings from another terminal. * **[Codebase Context](/agent-platform/capabilities/codebase-context/)** — Index your Git repositories so agents understand your code and give context-aware answers across large, multi-repo systems. * **[Oz cloud agents](/agent-platform/cloud-agents/overview/)** — Run agents in the background for PR review, issue triage, dependency updates, and other tasks that don’t need your immediate attention. * **[Keyboard shortcuts](/getting-started/keyboard-shortcuts/)** — The full shortcut reference for power users. # Technical reference > Technical reference documentation for the Oz CLI, API, and SDK. This section covers the programmatic interfaces for running and managing Oz agents in CI pipelines, scripts, backend services, and custom tooling. ## CLI [Section titled “CLI”](#cli) The [Oz CLI](/reference/cli/) lets you run and configure agents from any environment — locally, in CI pipelines, or on remote machines. * [API Keys](/reference/cli/api-keys/) - Create and manage API keys to authenticate the Oz CLI without human interaction, ideal for CI pipelines, headless servers, and containers. * [Agent Profiles](/reference/cli/agent-profiles/) - Use agent profiles to control what the agent can access, how it behaves, and where it can act, including file access, command execution, and MCP server usage. * [MCP Servers](/reference/cli/mcp-servers/) - Pass MCP server configuration to agent runs using the `--mcp` flag, by UUID, inline JSON, or file path. * [Skills](/reference/cli/skills/) - Run agents from reusable instruction sets stored in your repositories using the `--skill` flag. * [Warp Drive Context](/reference/cli/warp-drive/) - Reference saved prompts, notebooks, workflows, and rules from Warp Drive directly in CLI agent commands. * [Integration Setup](/reference/cli/integration-setup/) - Configure environments and connect external tools like Slack and Linear so you can trigger Oz agents from outside the terminal. * [Troubleshooting](/reference/cli/troubleshooting/) - Find solutions to common CLI errors, including authentication issues, agent failures, environment problems, and Docker image issues. ## API & SDK [Section titled “API & SDK”](#api--sdk) The [Oz API](/reference/api-and-sdk/) lets you create and monitor cloud agent runs over HTTP. Official SDKs for [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) provide typed clients with built-in retries and error handling. * [Demo: Sentry monitoring with SDK](/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/) - example integration # Oz API & SDK reference > Create and inspect cloud agent runs over HTTP with the Oz API, or use the Python and TypeScript SDKs for typed requests, retries, and error handling. ### Oz API [Section titled “Oz API”](#oz-api) The Oz API lets you create and inspect [Cloud Agent](/agent-platform/cloud-agents/overview/) runs over HTTP from any system (CI, cron, backend services, internal tools), without requiring the Warp desktop app. **With the API you can:** * Run an agent by submitting a prompt plus optional config (model, environment, MCP servers, base prompt, etc.) * Monitor execution by listing runs and tracking state transitions over time (queued → in progress → succeeded/failed) * Inspect results and provenance by fetching a run’s full details, including the original prompt, source/creator metadata, session link, and resolved agent configuration Caution This page is a high-level overview.\ \ For full API endpoint details, please refer to the [**Agents API Reference**](/api)**.** For schema definitions, see the SDK repos: [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) and [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript). ### Oz Agent SDK [Section titled “Oz Agent SDK”](#oz-agent-sdk) Oz provides official [Python](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript) SDKs that wrap the Oz API with: * **Typed requests and responses** (editor autocomplete, fewer schema mistakes) * **Built-in retries and timeouts** (with per-request overrides) * **Consistent error type**s that map to API status codes * **Helpers for raw responses** when you need headers/status or custom parsing If you’re building an integration (CI, Slack bots, internal tooling, orchestrators), the SDKs are typically the quickest and safest starting point. ![YouTube video](https://i.ytimg.com/vi/0cf7383MZSk/sddefault.jpg) **SDK vs raw REST** * Use the SDK when you want strong typing, standardized error handling, and easy concurrency patterns. * Use raw REST when you want minimal dependencies or full control over your HTTP client (the SDKs also support calling undocumented endpoints when needed). Caution For the full SDK surface area and latest usage, refer to the GitHub repos: [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) and [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript). *** ## Oz API [Section titled “Oz API”](#oz-api-1) ### REST API Base URL [Section titled “REST API Base URL”](#rest-api-base-url) All endpoints are served over HTTPS: ```http https://app.warp.dev/api/v1 ``` ### Core Concepts [Section titled “Core Concepts”](#core-concepts) #### **Agent runs** [Section titled “Agent runs”](#agent-runs) An agent run represents a single execution of a cloud agent, created with a prompt and optional configuration. Each run has: * A unique `run_id` * A human-readable `title` * A `prompt` that the agent executes * A `state` (for example `QUEUED`, `INPROGRESS`, `SUCCEEDED`, `FAILED`) * Timestamps (`created_at`, `updated_at`) * Optional session information (`session_id`, `session_link`) * Optional resolved configuration (`agent_config`) See the [**Agents API Reference**](/api) for details on how runs are created and listed. #### **Agent configuration** [Section titled “Agent configuration”](#agent-configuration) You can influence how an agent runs using AmbientAgentConfig, including: * `name` — a human-readable label for grouping, filtering, and traceability. When you run an agent from a [skill](/agent-platform/capabilities/skills/), `name` is automatically set to the skill name. You can also set `name` explicitly via the API, SDK, or CLI (`--name`) to categorize runs by intent — for example, grouping all runs of a particular workflow regardless of how they were triggered. Use the `name` query parameter on `GET /agent/runs` to filter runs by config name. * `model_id` for LLM selection * `base_prompt` to shape behavior * `environment_id` to choose a `CloudEnvironment` * `skill_spec` to use a [skill](/agent-platform/capabilities/skills/) as the base prompt (format: `owner/repo:skill-name` or `owner/repo:path/to/SKILL.md`) * `mcp_servers` to enable specific tools via MCP See the [**Python SDK**](https://github.com/warpdotdev/oz-sdk-python) or [**TypeScript SDK**](https://github.com/warpdotdev/oz-sdk-typescript) for the full configuration schema. *** ### Key Endpoints [Section titled “Key Endpoints”](#key-endpoints) **The Agents API exposes three primary endpoints:** * `POST /agent/run` Create a new agent run with a prompt and optional config and title. Returns run\_id and initial state. * `GET /agent/runs` List runs with pagination and filters for state, config\_name, model\_id, creator, source, and creation time. * `GET /agent/runs/{runId}` Fetch full details for a single run, including session link and resolved configuration. All endpoint semantics, query parameters, and error codes are documented on the [Agents API Reference](/api). *** #### Models Reference [Section titled “Models Reference”](#models-reference) The API shares a set of reusable models across endpoints. Detailed JSON schemas, types, and enums are available in the SDK repos ([Python](https://github.com/warpdotdev/oz-sdk-python), [TypeScript](https://github.com/warpdotdev/oz-sdk-typescript)). Key models include: * `RunAgentRequest` * `RunAgentResponse` * `ListRunsResponse` * `RunItem` * `PageInfo` * `RunStatusMessage` * `RunCreatorInfo` * `RunState` * `RunSourceType` * `AmbientAgentConfig` * `MCPServerConfig` * `Error` *** ## Oz Agent SDKs [Section titled “Oz Agent SDKs”](#oz-agent-sdks) ### Python SDK [Section titled “Python SDK”](#python-sdk) The Python SDK is the recommended way to call the Oz API from Python services and scripts. It provides: * Sync + async clients * Typed request/response models * Configurable retries/timeouts and structured errors See the [**Python SDK GitHub repo**](https://github.com/warpdotdev/oz-sdk-python) for installation, full API reference (api.md), and up-to-date examples. ### TypeScript SDK [Section titled “TypeScript SDK”](#typescript-sdk) The TypeScript SDK is the recommended way to call the Oz API from Node.js services and modern TS/JS runtimes. It provides: * Fully typed params/responses * First-class error handling, retries/timeouts * Support across common runtimes where fetch is available or polyfilled See the [**TypeScript SDK GitHub repo**](https://github.com/warpdotdev/oz-sdk-typescript) for installation, full API reference (api.md), and up-to-date examples. # Demo: Sentry monitoring with SDK > Build a Sentry webhook handler that triggers Oz agents to investigate errors and create draft PRs. ### Turn Production Errors into Draft PRs with Cloud Agents + TypeScript SDK [Section titled “Turn Production Errors into Draft PRs with Cloud Agents + TypeScript SDK”](#turn-production-errors-into-draft-prs-with-cloud-agents--typescript-sdk) ![YouTube video](https://i.ytimg.com/vi/fHQXLg9ybi4/sddefault.jpg) Note Example repository: [**https://github.com/warpdotdev/warp-agents-sdk-demo-sentry-monitor**](https://github.com/warpdotdev/warp-agents-sdk-demo-sentry-monitor) In this demo, Ben builds a small TypeScript “Sentry monitor” service that listens for specific Sentry alerts (like a Go nil pointer dereference) and triggers a Warp cloud agent to investigate. The server validates the webhook, extracts the stack trace, and injects it into an agent run inside a Warp Environment so the agent can inspect the repo and propose a fix. He also covers the task lifecycle basics in the TypeScript SDK (running an agent, polling task state to fetch a session link for debugging), and shows the end result: a draft GitHub pull request created from the Sentry event for a maintainer to review. **What Ben covers** * Using Warp’s TypeScript SDK to trigger agent runs and retrieve run details. * Handling run lifecycle states (queued → running) to reliably fetch a session link. * Running agents inside a Warp Environment so they can investigate real code, run tests, and validate fixes. * Building a lightweight Sentry webhook server that filters, validates, and routes only the right errors to an agent. * Creating a workflow that results in draft PRs for human review, instead of silent autonomous changes. # API & SDK quickstart > Create and monitor your first cloud agent run via the Oz API or SDK in ~5 minutes. The Oz API lets you run and manage cloud agents from anywhere — CI/CD pipelines, backend services, scripts, or custom tooling — without the Warp desktop app. This quickstart walks you through creating your first run and checking its status. Watch this short demo of how the REST API can power agent-backed apps like [PowerFixer](https://github.com/warpdotdev/power-fixer-setup), an issue triage bot built by the Warp team: ![YouTube video](https://i.ytimg.com/vi/N6qMe641K34/sddefault.jpg) *** ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * **A Warp API key** - In the Warp app, click your profile photo, then go to **Settings** > **Cloud platform** > **Oz Cloud API Keys** to create a key and copy the raw value. See [API Keys](/reference/cli/api-keys/) for step-by-step instructions. * **An Oz cloud environment** - Agents run inside a configured environment that includes repos and other dependencies. If you don’t have an environment yet, follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/) first. *** ## 1. Set your API key [Section titled “1. Set your API key”](#1-set-your-api-key) Export your API key so the API can authenticate your requests automatically — all commands in this guide reference the `WARP_API_KEY` environment variable. ```bash export WARP_API_KEY="wk-..." ``` Replace `wk-...` with the key you created earlier. ## 2. Create your first run [Section titled “2. Create your first run”](#2-create-your-first-run) Submit a prompt to start an agent run: ```bash curl -X POST https://app.warp.dev/api/v1/agent/run \ -H "Authorization: Bearer $WARP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Scan the repo for outdated dependencies and summarize the findings.", "config": { "environment_id": "" } }' ``` Replace `` with your environment ID. Find it with `oz environment list` on the Oz CLI or in the [Oz web app](https://oz.warp.dev). Note Prefer typed requests? The official [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) wrap the same API with typed models, retries, and error handling. The API returns a `run_id` immediately. The agent starts asynchronously — you can check its status at any time using the run ID. ## 3. Check run status [Section titled “3. Check run status”](#3-check-run-status) Fetch the current state of the run with the following command. Replace `` with the `run_id` from step 2. ```bash curl "https://app.warp.dev/api/v1/agent/runs/" \ -H "Authorization: Bearer $WARP_API_KEY" ``` The `state` has the following possible values: * `QUEUED` - The run is waiting to start. * `INPROGRESS` - The agent is actively running. * `SUCCEEDED` - The run completed successfully. * `FAILED` - The run encountered an error. Check the `status_message` field in the response for details. These are the most common states. See the [full API reference](/reference/api-and-sdk/) for all possible values. To list all recent runs: ```bash curl "https://app.warp.dev/api/v1/agent/runs" \ -H "Authorization: Bearer $WARP_API_KEY" ``` ## 4. View the results [Section titled “4. View the results”](#4-view-the-results) Once the run reaches `SUCCEEDED`, the response includes a `session_link` — a direct URL to the full run transcript, including commands executed, files changed, and agent output. You can also view and manage all runs in the [Oz dashboard](https://oz.warp.dev/runs). *** ## Next steps [Section titled “Next steps”](#next-steps) * **Read the full API reference** - [Oz API](/reference/api-and-sdk/) documents all endpoint parameters, query filters, and response schemas. * **Explore the SDKs** - [Python SDK](https://github.com/warpdotdev/oz-sdk-python) and [TypeScript SDK](https://github.com/warpdotdev/oz-sdk-typescript) include typed request/response models, retries, and error handling. * **See a real-world example** - [Demo: Sentry monitoring with SDK](/reference/api-and-sdk/demo-sentry-monitoring-with-sdk/) shows how to build a webhook handler that triggers agents from production errors. * **Schedule and automate** - See [Scheduled Agents Quickstart](/agent-platform/cloud-agents/triggers/scheduled-agents-quickstart/) to run agents on a cron, or [Integrations Quickstart](/agent-platform/cloud-agents/integrations/quickstart/) to trigger agents from Slack or Linear. # API Troubleshooting > Troubleshooting resources for the Oz API and SDK, including a full reference for all platform error codes. When the Oz platform API encounters an error, it returns a structured response following [RFC 7807 (Problem Details for HTTP APIs)](https://datatracker.ietf.org/doc/html/rfc7807) with a machine-readable error code, HTTP status, and actionable resolution steps. ## Resources [Section titled “Resources”](#resources) * [**Errors**](/reference/api-and-sdk/troubleshooting/errors/) — Full reference for all API error codes, including causes, example responses, and resolution steps # Errors Overview > Reference for all error codes returned by the Oz platform API. Each error includes an HTTP status, machine-readable code, and actionable resolution steps. When the Oz platform API encounters an error, it returns a structured JSON response following [RFC 7807 (Problem Details for HTTP APIs)](https://datatracker.ietf.org/doc/html/rfc7807). Every error response includes a machine-readable error code, a human-readable message, and metadata to help you diagnose and resolve the issue. *** ## Response format [Section titled “Response format”](#response-format) All error responses share this structure: ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/invalid-request/", "title": "The request contains invalid or missing parameters.", "status": 400, "detail": "schedule_id is required", "instance": "/api/v1/agent/tasks", "error": "The request contains invalid or missing parameters. (schedule_id is required)", "retryable": false, "trace_id": "abc123def456..." } ``` Error responses use the `application/problem+json` content type per RFC 7807. ### Field reference [Section titled “Field reference”](#field-reference) * **`type`** — A URI identifying the error type. Links to the documentation page for that error. * **`title`** — A short, human-readable summary of the problem. * **`status`** — The HTTP status code for this response. * **`detail`** — Additional context specific to this occurrence of the error. Not always present. * **`instance`** — The request path that produced the error. * **`error`** — A backward-compatible field combining `title` and `detail` (for older clients). When `detail` is present, formatted as `"title (detail)"`. * **`retryable`** — Whether this request can be retried. If `true`, the platform may automatically retry the operation. * **`trace_id`** — An OpenTelemetry trace ID, included when available. Reference this when contacting support. Some errors include additional metadata fields (for example, `auth_url`, `provider`, or `inaccessible_repos`). These are documented on each error’s page. *** ## Error categories [Section titled “Error categories”](#error-categories) Errors are split into two categories based on what caused the failure: ### User errors [Section titled “User errors”](#user-errors) These indicate something the caller needs to fix. When a cloud agent task encounters a user error, the task transitions to the **FAILED** state. * [`insufficient_credits`](/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/) — Team has no remaining Add-on Credits * [`feature_not_available`](/reference/api-and-sdk/troubleshooting/errors/feature-not-available/) — Feature not included in your current plan * [`external_authentication_required`](/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/) — External service authorization needed * [`not_authorized`](/reference/api-and-sdk/troubleshooting/errors/not-authorized/) — Insufficient permissions for the operation * [`invalid_request`](/reference/api-and-sdk/troubleshooting/errors/invalid-request/) — Malformed request or invalid parameters * [`resource_not_found`](/reference/api-and-sdk/troubleshooting/errors/resource-not-found/) — Referenced resource does not exist * [`budget_exceeded`](/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/) — Spending budget limit reached * [`integration_disabled`](/reference/api-and-sdk/troubleshooting/errors/integration-disabled/) — Integration is disabled * [`integration_not_configured`](/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/) — Integration setup is incomplete * [`operation_not_supported`](/reference/api-and-sdk/troubleshooting/errors/operation-not-supported/) — Operation not supported for this resource or state * [`environment_setup_failed`](/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/) — Cloud agent environment failed to initialize * [`content_policy_violation`](/reference/api-and-sdk/troubleshooting/errors/content-policy-violation/) — Task flagged by content policy checks * [`conflict`](/reference/api-and-sdk/troubleshooting/errors/conflict/) — Request conflicts with the current resource state (retryable) ### Platform errors [Section titled “Platform errors”](#platform-errors) These indicate a Warp-side issue. When a cloud agent task encounters a platform error, the task transitions to the **ERROR** state. Retryable errors are automatically retried before the task is marked as failed. * [`authentication_required`](/reference/api-and-sdk/troubleshooting/errors/authentication-required/) — Invalid or expired API key * [`resource_unavailable`](/reference/api-and-sdk/troubleshooting/errors/resource-unavailable/) — Transient infrastructure issue (retryable) * [`internal_error`](/reference/api-and-sdk/troubleshooting/errors/internal-error/) — Unexpected server-side error (retryable) *** ## Using the `trace_id` [Section titled “Using the trace\_id”](#using-the-trace_id) When an error response includes a `trace_id`, you can include it when [contacting Warp support](/support-and-community/troubleshooting-and-support/sending-us-feedback/) to help the team locate the specific request in internal logs. This is especially useful for `internal_error` and `resource_unavailable` errors. *** ## Related [Section titled “Related”](#related) * [Oz API & SDK](/reference/api-and-sdk/) — API reference for creating and managing agent tasks * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — How cloud agents work * [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) — Plan requirements and billing details # authentication_required > The API key in the request is invalid, expired, or missing. Generate a new key and update your client configuration. The `authentication_required` error occurs when the API request lacks valid authentication credentials. Note This is classified as a **platform error** (task state → ERROR) rather than a user error, because it typically indicates a configuration issue with the API key rather than a problem with the task itself. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `401 Unauthorized` * **Retryable:** No * **Task State:** ERROR *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * The `Authorization` header is missing from the request * The API key has been revoked or has expired * The API key is malformed or invalid *** ## Example response [Section titled “Example response”](#example-response) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/authentication-required/", "title": "Your API key is invalid or has expired. Please generate a new key and try again.", "status": 401, "instance": "/api/v1/agent/tasks", "error": "Your API key is invalid or has expired. Please generate a new key and try again.", "retryable": false } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) 1. Generate a new API key from the [Oz web app](https://oz.warp.dev) or via the Oz CLI. 2. Update your client configuration with the new key. 3. Retry the request. *** ## Related [Section titled “Related”](#related) * [Oz API & SDK](/reference/api-and-sdk/) — API authentication * [Oz Platform](/agent-platform/cloud-agents/platform/) — API key management # budget_exceeded > Your team's configured spending budget limit has been reached. Increase the budget or wait for the budget period to reset. The `budget_exceeded` error occurs when your team has reached the spending budget limit configured in team settings. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `403 Forbidden` * **Retryable:** No * **Task State:** FAILED *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * Your team has set a spending budget cap, and the current period’s usage has reached that cap * A cloud agent task, scheduled run, or integration-triggered run attempts to start but would exceed the budget The `title` field in the response will describe the specific budget constraint. *** ## Example response [Section titled “Example response”](#example-response) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/budget-exceeded/", "title": "Monthly spending budget of $50 has been reached.", "status": 403, "instance": "/api/v1/agent/tasks", "error": "Monthly spending budget of $50 has been reached.", "retryable": false } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) 1. Go to your team settings and increase the spending budget, or 2. Wait for the budget period to reset (for example, at the start of the next billing cycle). If you are not a team admin, contact your team admin to adjust the budget. *** ## Related [Section titled “Related”](#related) * [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) — Budget configuration and billing details # Error: conflict (409) > The request conflicts with the current state of the resource. Wait for the resource to reach the expected state and retry. The `conflict` error occurs when a request cannot be completed because the resource is in a state that conflicts with the requested operation. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `409 Conflict` * **Retryable:** Yes * **Task State:** FAILED *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * You attempt to cancel a task that is still in the **pending** state (the task has not yet been claimed by a worker) The operation can typically succeed once the resource transitions to the expected state. *** ## Example response [Section titled “Example response”](#example-response) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/conflict/", "title": "Pending agent runs cannot be cancelled, retry after a moment.", "status": 409, "instance": "/api/v1/agent/tasks/abc123/cancel", "error": "Pending agent runs cannot be cancelled, retry after a moment.", "retryable": true } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) 1. Wait a moment for the resource to transition to the expected state. 2. Retry the request. For task cancellation specifically, wait until the task moves from **pending** to **in progress** before attempting to cancel. *** ## Related [Section titled “Related”](#related) * [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) — Viewing and managing agent tasks * [Oz API & SDK](/reference/api-and-sdk/) — API reference for managing agent tasks # content_policy_violation > The task prompt or environment setup commands were flagged by the platform's automated content policy checks. The `content_policy_violation` error occurs when the task prompt or environment setup commands are flagged by the platform’s automated content policy checks. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `403 Forbidden` * **Retryable:** No * **Task State:** FAILED *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * The task prompt contains content that violates Warp’s usage policies * The environment setup commands contain patterns flagged as potentially harmful * The automated content classifier determines the task should be blocked Note For security reasons, the error message is intentionally generic and does not describe what specifically was flagged. *** ## Example response [Section titled “Example response”](#example-response) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/content-policy-violation/", "title": "Unable to start cloud agent. Please try again or contact support if the issue persists.", "status": 403, "instance": "/api/v1/agent/tasks", "error": "Unable to start cloud agent. Please try again or contact support if the issue persists.", "retryable": false, "trace_id": "abc123..." } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) 1. Review your task prompt and environment setup commands to ensure they comply with [Warp’s usage policies](https://www.warp.dev/terms-of-service). 2. If you believe this was flagged in error, contact [Warp support](/support-and-community/troubleshooting-and-support/sending-us-feedback/) and include the `trace_id` from the error response. *** ## Related [Section titled “Related”](#related) * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — How cloud agent tasks work * [Environments](/agent-platform/cloud-agents/environments/) — Configuring setup commands # environment_setup_failed > The cloud agent's environment failed to initialize. Check repo URLs, setup commands, and working directory paths. The `environment_setup_failed` error occurs when the cloud agent’s runtime environment could not be initialized. This covers failures during any phase of environment setup, including repository cloning, setup command execution, working directory resolution, and MCP server startup. Note Although this returns HTTP 500, it is classified as a **user error** (task state → FAILED) because the failure is caused by the environment configuration, not by Warp’s infrastructure. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `500 Internal Server Error` * **Retryable:** No * **Task State:** FAILED *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when any part of the environment initialization process fails: * **Git clone failed** — The repository URL is incorrect, the branch does not exist, or the agent does not have access to the repository * **Setup command failed** — A command in the environment’s setup commands list exited with an error (for example, missing dependencies, script errors) * **Working directory not found** — The configured working directory does not exist after cloning * **MCP server startup failed** — An MCP server configured for the environment could not start The `title` field in the response will describe the specific setup failure. *** ## Example response [Section titled “Example response”](#example-response) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/environment-setup-failed/", "title": "Failed to clone repository: branch 'main' not found in acme/backend", "status": 500, "instance": "/api/v1/agent/tasks", "error": "Failed to clone repository: branch 'main' not found in acme/backend", "retryable": false } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) 1. **Check repository configuration** — Verify the repository URL and branch name in your [environment settings](/agent-platform/cloud-agents/environments/). Ensure the repository exists and is accessible. 2. **Check setup commands** — Run the setup commands locally to confirm they work. Look for missing dependencies, incorrect paths, or syntax errors. 3. **Check working directory** — Ensure the working directory path exists relative to the cloned repository root. 4. **Check MCP server configuration** — Verify MCP server startup commands and that any required dependencies or credentials are available. See [MCP Servers for Agents](/reference/cli/mcp-servers/). 5. **Check secrets** — If setup commands reference environment variables from [secrets](/agent-platform/cloud-agents/secrets/), verify the secrets are configured and in scope. *** ## Related [Section titled “Related”](#related) * [Environments](/agent-platform/cloud-agents/environments/) — Configuring cloud agent environments * [Secrets](/agent-platform/cloud-agents/secrets/) — Managing credentials for agent environments * [MCP Servers for Agents](/reference/cli/mcp-servers/) — Configuring MCP servers # external_authentication_required > The task requires access to an external service (GitHub, Slack, Linear, etc.) that hasn't been authorized. Follow the auth_url to grant access. The `external_authentication_required` error occurs when a cloud agent task needs access to an external service that the user hasn’t authorized, or when the Warp GitHub App doesn’t have access to the required repositories. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `401 Unauthorized` * **Retryable:** No * **Task State:** FAILED *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * **GitHub not connected** — Your Warp account is not linked to a GitHub account, but the task’s environment includes GitHub repositories * **Repository inaccessible** — The Warp GitHub App is not installed on, or does not have access to, one or more repositories required by the task’s environment * **Account matching failed** — A Slack or Linear user who triggered the task cannot be matched to a Warp account *** ## Additional metadata fields [Section titled “Additional metadata fields”](#additional-metadata-fields) This error includes extra fields beyond the standard response format: * **`provider`** — The external service name (for example, `"github"`, `"slack"`, `"linear"`) * **`auth_url`** — A URL to complete the authorization flow (when available) * **`inaccessible_repos`** — A list of repository names the agent cannot access (when applicable) *** ## Example responses [Section titled “Example responses”](#example-responses) ### GitHub user not connected [Section titled “GitHub user not connected”](#github-user-not-connected) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/", "title": "User is not connected to GitHub", "status": 401, "instance": "/api/v1/agent/tasks", "error": "User is not connected to GitHub. Authorize access here: https://...", "retryable": false, "provider": "github", "auth_url": "https://github.com/login/oauth/authorize?..." } ``` ### Repository inaccessible [Section titled “Repository inaccessible”](#repository-inaccessible) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/", "title": "User does not have access to the following repositories in the environment: acme/backend", "status": 401, "detail": "inaccessible repos: acme/backend", "instance": "/api/v1/agent/tasks", "error": "User does not have access to the following repositories in the environment: acme/backend (inaccessible repos: acme/backend)", "retryable": false, "provider": "github", "auth_url": "https://github.com/apps/warp-dev/installations/new", "inaccessible_repos": ["acme/backend"] } ``` ### Account matching failed (Slack/Linear) [Section titled “Account matching failed (Slack/Linear)”](#account-matching-failed-slacklinear) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/external-authentication-required/", "title": "Unable to locate your Warp account", "status": 401, "instance": "/api/v1/agent/tasks", "error": "Unable to locate your Warp account", "retryable": false, "provider": "slack" } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) ### GitHub not connected [Section titled “GitHub not connected”](#github-not-connected) 1. Follow the `auth_url` in the response to connect your GitHub account to Warp. 2. Complete the OAuth authorization flow. 3. Retry the task. ### Repository inaccessible [Section titled “Repository inaccessible”](#repository-inaccessible-1) 1. Follow the `auth_url` to install or reconfigure the Warp GitHub App. 2. Ensure the app has access to all repositories listed in `inaccessible_repos`. 3. Retry the task. If you are using a **team API key** (service account), ensure the Warp GitHub App is installed on the organization that owns the repositories. ### Account matching failed [Section titled “Account matching failed”](#account-matching-failed) 1. Ensure your Slack or Linear account is associated with the same email as your Warp account. 2. If using Slack, verify the Warp Slack integration is installed in your workspace. 3. Contact your team admin if the issue persists. *** ## Related [Section titled “Related”](#related) * [Environments](/agent-platform/cloud-agents/environments/) — Configuring GitHub repositories for cloud agent environments * [Integrations](/agent-platform/cloud-agents/integrations/) — Setting up Slack and Linear integrations # feature_not_available > The requested feature is not included in your current plan. Upgrade your team's plan to access this capability. The `feature_not_available` error occurs when you attempt to use a feature or capability that is not included in your team’s current plan. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `403 Forbidden` * **Retryable:** No * **Task State:** FAILED *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * You attempt to use a feature that requires a higher-tier plan (for example, certain integrations, advanced capabilities, or self-hosted execution) * A cloud agent or integration trigger tries to access a feature gated behind a plan upgrade The `title` field in the response will describe the specific feature that is unavailable. *** ## Example response [Section titled “Example response”](#example-response) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/feature-not-available/", "title": "Slack integration requires a Build plan or higher.", "status": 403, "instance": "/api/v1/agent/tasks", "error": "Slack integration requires a Build plan or higher.", "retryable": false } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) 1. Check which plan your team is on in your team’s billing settings. 2. Upgrade to a plan that includes the required feature. 3. Retry the operation. For plan comparisons and feature availability, see [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/). *** ## Related [Section titled “Related”](#related) * [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) — Plan requirements and feature availability * [Integrations](/agent-platform/cloud-agents/integrations/) — Integration requirements by plan # insufficient_credits > Your team has exhausted all Add-on Credits for cloud agent usage. Purchase more credits from your team's billing settings to continue. The `insufficient_credits` error occurs when your team has no remaining Add-on Credits to run cloud agents or integrations. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `403 Forbidden` * **Retryable:** No * **Task State:** FAILED *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * Your team’s Add-on Credits balance has reached zero * A cloud agent task, scheduled run, or integration-triggered run (Slack, Linear) attempts to start but cannot be billed Cloud agent runs consume credits based on usage. When credits are depleted, no new runs can start until credits are replenished. *** ## Example response [Section titled “Example response”](#example-response) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/", "title": "Your team has run out of Add-on Credits. Purchase more credits in your team's billing settings to continue.", "status": 403, "instance": "/api/v1/agent/tasks", "title": "Your team has run out of add-on credits. Purchase more credits in your team's billing settings to continue.", "status": 403, "instance": "/api/v1/agent/tasks", "error": "Your team has run out of add-on credits. Purchase more credits in your team's billing settings to continue.", "retryable": false } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) 1. Go to your team’s billing settings in the [Oz web app](https://oz.warp.dev) or Warp desktop app. 2. Purchase additional Add-on Credits. 3. Retry the failed operation. If you are not a team admin, contact your team admin to purchase credits. *** ## Related [Section titled “Related”](#related) * [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) — Credit billing and plan requirements * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — Billing and plan requirements for cloud agents # integration_disabled > The integration (Slack, Linear, etc.) is currently disabled in the Oz settings. Enable it to continue. The `integration_disabled` error occurs when a task targets an integration that is currently disabled in the Oz settings. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `403 Forbidden` * **Retryable:** No * **Task State:** FAILED *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * A Slack message, Linear issue, or other integration event triggers a cloud agent, but the corresponding integration has been disabled in the Oz settings * The integration was previously active but has been turned off by a team admin *** ## Example response [Section titled “Example response”](#example-response) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/integration-disabled/", "title": "This integration is disabled. Please enable it in Oz.", "status": 403, "instance": "/api/v1/agent/tasks", "error": "This integration is disabled. Please enable it in Oz.", "retryable": false } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) 1. Go to the [Oz integrations page](https://oz.warp.dev/integrations). 2. Enable the integration that was disabled. 3. Retry the triggering event or task. *** ## Related [Section titled “Related”](#related) * [Integrations](/agent-platform/cloud-agents/integrations/) — Configuring Slack, Linear, and GitHub integrations * [Oz Web App](/agent-platform/cloud-agents/oz-web-app/) — Managing integrations via the web interface # integration_not_configured > The integration's setup is incomplete. Visit the setup URL to finish configuring the integration. The `integration_not_configured` error occurs when a task requires an integration whose setup has not been completed (for example, missing OAuth tokens or unfinished configuration steps). *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `400 Bad Request` * **Retryable:** No * **Task State:** FAILED *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * An integration (Slack, Linear, etc.) was partially set up but the configuration was not completed * Required OAuth tokens or credentials for the integration are missing or expired * The integration was installed but additional setup steps were not finished *** ## Additional metadata fields [Section titled “Additional metadata fields”](#additional-metadata-fields) This error includes extra fields beyond the standard response format: * **`integration_name`** — The name of the integration that needs configuration * **`setup_url`** — A URL to the integration setup page where you can complete configuration *** ## Example response [Section titled “Example response”](#example-response) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/integration-not-configured/", "title": "Slack integration is not configured", "status": 400, "instance": "/api/v1/agent/tasks", "error": "Slack integration is not configured", "retryable": false, "integration_name": "slack", "setup_url": "https://oz.warp.dev/integrations" } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) 1. Visit the `setup_url` provided in the response metadata (or go to the [Oz integrations page](https://oz.warp.dev/integrations)). 2. Complete all setup steps for the integration. 3. Retry the triggering event or task. *** ## Related [Section titled “Related”](#related) * [Integrations](/agent-platform/cloud-agents/integrations/) — Integration setup guides * [Slack Integration](/agent-platform/cloud-agents/integrations/slack/) — Slack-specific setup * [Linear Integration](/agent-platform/cloud-agents/integrations/linear/) — Linear-specific setup # internal_error > An unexpected server-side error occurred. The platform will automatically retry. Contact support if the issue persists. The `internal_error` is a catch-all for unexpected server-side errors. The platform automatically retries these errors before marking the task as failed. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `500 Internal Server Error` * **Retryable:** Yes (automatic) * **Task State:** ERROR *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * An unexpected condition occurred on the server that does not match any specific error category * An internal service dependency failed or timed out * An unclassified error occurred during task processing *** ## Example response [Section titled “Example response”](#example-response) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/internal-error/", "title": "An unexpected error occurred. Please try again later. If the issue persists, contact support.", "status": 500, "instance": "/api/v1/agent/tasks", "error": "An unexpected error occurred. Please try again later. If the issue persists, contact support.", "retryable": true, "trace_id": "abc123..." } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) No action is typically needed — the platform will automatically retry the task. If the error persists: 1. Wait a few minutes and try again. 2. Contact [Warp support](/support-and-community/troubleshooting-and-support/sending-us-feedback/) and include the `trace_id` from the error response. *** ## Related [Section titled “Related”](#related) * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — How cloud agent tasks work * [Cloud Agents FAQs](/agent-platform/cloud-agents/faqs/) — Common questions about cloud agents # invalid_request > The request body is malformed, missing required fields, or contains invalid parameter values. The `invalid_request` error occurs when the API request is malformed or contains invalid parameters. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `400 Bad Request` * **Retryable:** No * **Task State:** FAILED *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * Required fields are missing from the request body (for example, `prompt` or `schedule_id`) * Parameter values are invalid or out of range * The request body cannot be parsed (malformed JSON) * A referenced identifier is in the wrong format * A team-owned task references a personal environment (team tasks require team-scoped environments) The `detail` field in the response will describe the specific validation issue. *** ## Example response [Section titled “Example response”](#example-response) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/invalid-request/", "title": "The request contains invalid or missing parameters.", "status": 400, "detail": "schedule_id is required", "instance": "/api/v1/agent/tasks", "error": "The request contains invalid or missing parameters. (schedule_id is required)", "retryable": false } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) 1. Check the `detail` field for the specific validation issue. 2. Correct the request parameters according to the [API documentation](/reference/api-and-sdk/). 3. Retry the request. *** ## Related [Section titled “Related”](#related) * [Oz API & SDK](/reference/api-and-sdk/) — API request format and parameters # not_authorized > The authenticated user or API key does not have permission to perform the requested operation. The `not_authorized` error occurs when the authenticated principal (user or API key) does not have sufficient permissions to perform the requested operation. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `403 Forbidden` * **Retryable:** No * **Task State:** FAILED *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * You attempt to access a resource owned by another team or user * Your API key does not have the required scope for the operation * You try to perform an admin-level operation without admin privileges * A team-level operation is attempted by a user who is not a member of the team *** ## Example response [Section titled “Example response”](#example-response) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/not-authorized/", "title": "You do not have permission for this operation.", "status": 403, "detail": "user is not a member of the team", "instance": "/api/v1/agent/tasks/abc123", "error": "You do not have permission for this operation. (user is not a member of the team)", "retryable": false } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) 1. Verify that the API key or user account belongs to the correct team. 2. Check that your role has the necessary permissions for the operation. 3. Contact a team admin if you need elevated access. *** ## Related [Section titled “Related”](#related) * [Access, Billing, and Identity](/agent-platform/cloud-agents/team-access-billing-and-identity/) — Permission model and identity * [Oz API & SDK](/reference/api-and-sdk/) — API authentication and authorization # operation_not_supported > The requested operation is not supported for this resource or its current state. The `operation_not_supported` error occurs when you attempt an operation that is not currently supported for the given resource or its current state. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `422 Unprocessable Entity` * **Retryable:** No * **Task State:** FAILED *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * You attempt to cancel a **self-hosted** agent run via the API (self-hosted runs must be cancelled through the hosting infrastructure) * You attempt to cancel a **local** agent run via the API (local runs must be cancelled from the source client) * You attempt to cancel a run triggered via **GitHub Actions** (these must be cancelled through the GitHub Actions workflow view) *** ## Example response [Section titled “Example response”](#example-response) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/operation-not-supported/", "title": "Self-hosted agent runs cannot be cancelled with the API.", "status": 422, "instance": "/api/v1/agent/tasks/abc123/cancel", "error": "Self-hosted agent runs cannot be cancelled with the API.", "retryable": false } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) 1. Check the error message to understand which operation is unsupported and why. 2. Use the appropriate method for the operation: * **Self-hosted runs** — Cancel through your hosting infrastructure. * **Local runs** — Cancel from the Warp desktop app or terminal session. * **GitHub Actions runs** — Cancel via the GitHub Actions workflow view. *** ## Related [Section titled “Related”](#related) * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — How cloud agent tasks work * [Self-Hosting](/agent-platform/cloud-agents/self-hosting/) — Self-hosted agent configuration * [Oz API & SDK](/reference/api-and-sdk/) — API reference for managing agent tasks # resource_not_found > The requested resource (task, environment, schedule, agent, etc.) does not exist or has been deleted. The `resource_not_found` error occurs when a referenced resource cannot be found. This typically means the resource ID is incorrect, the resource has been deleted, or it belongs to a different team. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `404 Not Found` * **Retryable:** No * **Task State:** FAILED *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * A task ID, environment UID, schedule ID, or other resource identifier does not match any existing resource * The referenced resource has been deleted * The resource exists but belongs to a different team or user (and you don’t have access) The `detail` field in the response will describe which resource was not found. *** ## Example response [Section titled “Example response”](#example-response) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/resource-not-found/", "title": "The requested resource was not found.", "status": 404, "detail": "environment abc123 not found", "instance": "/api/v1/agent/tasks", "error": "The requested resource was not found. (environment abc123 not found)", "retryable": false } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) 1. Verify the resource ID is correct and properly formatted. 2. Check that the resource has not been deleted (for example, via the [Oz web app](https://oz.warp.dev) or CLI). 3. Confirm the resource belongs to your team or that you have access to it. *** ## Related [Section titled “Related”](#related) * [Environments](/agent-platform/cloud-agents/environments/) — Managing cloud agent environments * [Managing Cloud Agents](/agent-platform/cloud-agents/managing-cloud-agents/) — Viewing and managing agent tasks # resource_unavailable > A transient infrastructure issue prevented the task from running. The platform will automatically retry. No action is needed. The `resource_unavailable` error indicates a transient infrastructure issue that prevented the cloud agent task from running. This is automatically retried by the platform. *** ## Details [Section titled “Details”](#details) * **HTTP Status:** `429 Too Many Requests` or `500 Internal Server Error` * **Retryable:** Yes (automatic) * **Task State:** ERROR *** ## When does this occur? [Section titled “When does this occur?”](#when-does-this-occur) This error is returned when: * **Capacity full (429)** — Cloud agent capacity is temporarily saturated. Your task will be queued and retried automatically. * **Sandbox creation failed (500)** — A sandbox instance could not be created for the agent. This is typically a transient issue. *** ## Example responses [Section titled “Example responses”](#example-responses) ### Capacity full [Section titled “Capacity full”](#capacity-full) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/resource-unavailable/", "title": "Agent capacity is temporarily full. Your task will be retried automatically, or you can try again later.", "status": 429, "instance": "/api/v1/agent/tasks", "error": "Agent capacity is temporarily full. Your task will be retried automatically, or you can try again later.", "retryable": true, "trace_id": "abc123..." } ``` ### Sandbox creation failed [Section titled “Sandbox creation failed”](#sandbox-creation-failed) ```json { "type": "/reference/api-and-sdk/troubleshooting/errors/resource-unavailable/", "title": "Failed to create a sandbox instance for your agent. This is typically a transient issue — your task will be retried automatically.", "status": 500, "instance": "/api/v1/agent/tasks", "error": "Failed to create a sandbox instance for your agent. This is typically a transient issue — your task will be retried automatically.", "retryable": true, "trace_id": "abc123..." } ``` *** ## How to resolve [Section titled “How to resolve”](#how-to-resolve) No action is typically needed — the platform will automatically retry the task. If the error persists after retries: 1. Try again later when capacity has freed up. 2. Contact [Warp support](/support-and-community/troubleshooting-and-support/sending-us-feedback/) and include the `trace_id` from the error response. *** ## Related [Section titled “Related”](#related) * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) — How cloud agent execution works * [Deployment Patterns](/agent-platform/cloud-agents/deployment-patterns/) — Execution models and infrastructure # Oz CLI reference > Use the Oz CLI to run, configure, and manage agents from the terminal. Note **`warp-cli` is deprecated and has been replaced by `oz`.** If you have `warp-cli` installed, it will auto-update to `oz`. All the same commands are available, just replace `warp-cli` with `oz` in your scripts and workflows. ## What is the Oz CLI? [Section titled “What is the Oz CLI?”](#what-is-the-oz-cli) The Oz CLI is the command-line tool that lets you run [Cloud Agents](/agent-platform/cloud-agents/overview/) from anywhere, including terminals, scripts, automated systems, or services. It’s the standard runtime entry point that turns a **prompt** plus **configuration** into an **executable agent task** that runs on either a **Warp-hosted or [self-hosted](/agent-platform/cloud-agents/self-hosting/) runner**. With the Oz CLI, you can: * Run agents locally for development and debugging * Run agents on remote machines * Connect agents to MCP servers like GitHub and Linear * Configure integrations that connect agents to Slack, Linear, and other trigger surfaces ## Installing the CLI [Section titled “Installing the CLI”](#installing-the-cli) You can install the Oz CLI as part of the Warp desktop app, or as a standalone package. ### Bundled with Warp [Section titled “Bundled with Warp”](#bundled-with-warp) The Oz CLI is automatically distributed with the Warp desktop app and can be used right away in Warp. To make the CLI globally available, add it to your `PATH`. * macOS To add the Oz CLI to your `PATH`: 1. Open the [Command Palette](/terminal/command-palette/) (`CMD+P` ) 2. In the search field, find and select the **Install Oz CLI Command** action. Note **Note:** Administrator permissions are required to install the CLI into `/usr/local/bin` . * Windows In the Warp installer, select **Add Warp to PATH**. If you are installing for all users, this will put the CLI on the system path. Otherwise, the CLI is only added to the path for your account. * Linux To run the Oz CLI on Linux, use the same command that you’d use to start Warp normally. If you installed Warp via a package manager, it should already be on the system `PATH`. ### Standalone package [Section titled “Standalone package”](#standalone-package) Warp provides standalone packages for the CLI on macOS and Linux, without the Warp app. * macOS On macOS, we recommend that you install and update the standalone CLI with [Homebrew](https://brew.sh/), using the [`warpdotdev/warp` tap](https://github.com/warpdotdev/homebrew-warp): ```sh $ brew tap warpdotdev/warp $ brew update $ brew install --cask oz ``` If you’re using Warp Preview, install the preview version of the CLI instead: ```sh brew install --cask oz@preview ``` *** You can also download the CLI directly from these URLs: * [Apple Silicon](https://app.warp.dev/download/cli?os=macos\&package=tar\&arch=aarch64) * [Intel](https://app.warp.dev/download/cli?os=macos\&package=tar\&arch=x86_64) * [Apple Silicon, Warp Preview](https://app.warp.dev/download/cli?os=macos\&channel=preview\&package=tar\&arch=aarch64) * [Intel, Warp Preview](https://app.warp.dev/download/cli?os=macos\&channel=preview\&package=tar\&arch=x86_64) Note **Note:** These builds do not auto-update. * Linux On Linux, we recommend that you install and update the standalone CLI through your distribution’s package manager. We support `apt`, `yum`, and `pacman`. 1. Add the Warp package repository for your distribution (see the [installation instructions](/getting-started/quickstart/installation-and-setup/)). 2. Install either the stable or Preview package (replace `apt` with `yum` or `pacman` as needed): ```sh # Stable sudo apt install oz-stable # Preview (beta/early-access) sudo apt install oz-preview ``` Note **Note:** The package name (`oz-stable`) differs from the CLI command executable (`oz`). After installation, use the CLI via `oz` commands. *** You can also install the CLI by downloading a package directly. These installers automatically add the Warp repository, so future updates come through your package manager: * x86-64: [`.deb`](https://app.warp.dev/download/cli?os=linux\&package=deb\&arch=x86_64), [`.rpm`](https://app.warp.dev/download/cli?os=linux\&package=rpm\&arch=x86_64), [pacman](https://app.warp.dev/download/cli?os=linux\&package=pacman\&arch=x86_64) * aarch64: [`.deb`](https://app.warp.dev/download/cli?os=linux\&package=deb\&arch=aarch64), [`.rpm`](https://app.warp.dev/download/cli?os=linux\&package=rpm\&arch=aarch64), [pacman](https://app.warp.dev/download/cli?os=linux\&package=pacman\&arch=aarch64) * Windows A standalone CLI package is not currently available on Windows. To use the Oz CLI on Windows, install the Warp app, which bundles the CLI. You can install Warp using [WinGet](https://learn.microsoft.com/en-us/windows/package-manager/winget/): ```powershell winget install Warp.Warp ``` After installation, see [Bundled with Warp](#bundled-with-warp) for instructions on adding the CLI to your `PATH`. ## Running the CLI [Section titled “Running the CLI”](#running-the-cli) Regardless of your OS or installation method, the CLI command is `oz`. If you’re using [Warp Preview](/support-and-community/community/warp-preview-and-alpha-program/), use `oz-preview` instead. ## Logging in [Section titled “Logging in”](#logging-in) The Oz CLI supports two authentication methods, depending on where and how you’re running agents. * **Interactive login —** best for local machines where you have Warp installed and can authenticate through a browser. * **API keys** — best for automated or remote environments that need to authenticate without human interaction. ### Interactive login (local machines) [Section titled “Interactive login (local machines)”](#interactive-login-local-machines) Use interactive login when you’re working on a machine where you already use the Warp app, or when you can open a browser to complete authentication. If you use the CLI on a host where you’re already signed in to Warp, it automatically reuses your existing credentials. To authenticate interactively: ```bash oz login ``` The CLI prints out a URL that you can open in any browser to login to Warp. ### API key authentication [Section titled “API key authentication”](#api-key-authentication) Use an API key when the environment must authenticate on its own, such as CI pipelines, headless servers, VMs, Codespaces, or containers. API keys let the CLI authenticate non-interactively. For detailed instructions on creating, managing, and using API keys, see [API Keys](/reference/cli/api-keys/). **Quickstart:** ```sh $ export WARP_API_KEY="wk-xxx..." $ oz agent run --prompt "analyze this codebase" ``` *** ## Running agents [Section titled “Running agents”](#running-agents) The Oz CLI offers two ways to run agents, depending on where you want the work to happen: **Use `oz agent run` when:** * You’re developing locally and want immediate feedback * You need the agent to work with files in your current directory * You want to inspect and modify the agent’s work in real time * You’re debugging or iterating on prompts **Use `oz agent run-cloud` when:** * You want the agent to run on a remote machine or standardized environment * You’re triggering agent work from CI/CD or automated systems * You need the agent to run independently of your local session * You’re delegating work that doesn’t require your immediate attention ### Running locally: \`oz agent run\` [Section titled “Running locally: \`oz agent run\`”](#running-locally-oz-agent-run) To start an agent, use the `oz agent run` subcommand. You’ll need to specify a prompt and, optionally, the [MCP servers](/agent-platform/capabilities/mcp/) and [agent profile](/agent-platform/capabilities/agent-profiles-permissions/) to use. ```sh oz agent run --prompt "set up a new Rust crate named warp-cli" I'll run a few terminal commands to: - Check if this is a Git repo and Cargo workspace - Create a new binary crate named warp-cli ``` **Key flags:** * `--cwd ` (`-C`) — run from a different directory. * `--name ` (`-n`) — label the run for grouping and traceability. * `--share` — share the session with teammates (see [Collaboration](/reference/cli/#collaboration)). * `--profile ` — use a specific agent profile (see [Using Agent Profiles](/reference/cli/#using-agent-profiles)). * `--model ` — override the default model (see [Model Choice](/agent-platform/capabilities/model-choice/)). * `--skill ` — use a skill as the base prompt (see [Using Skills](/reference/cli/#using-skills)). * `--mcp ` — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated. * `--environment ` (`-e`) — run in a specific cloud environment. * `--file ` (`-f`) — load run configuration from a YAML or JSON file. The agent will automatically carry out the task you gave it, printing out tool calls and responses as it works. By default, the agent runs in your current working directory. To run from a different directory, use the `-C/--cwd` flag. ### Running agents remotely: \`oz agent run-cloud\` [Section titled “Running agents remotely: \`oz agent run-cloud\`”](#running-agents-remotely-oz-agent-run-cloud) Cloud runs dispatch tasks to remote environments. Use cloud runs for: * Background processing * Standardized team configurations * Remote execution on servers you don’t directly access ```sh oz agent run-cloud \ --environment \ --name "Repo summary" \ --prompt "Summarize this repo and list the top 5 risky areas" \ --open ``` **Key flags** * `--environment ` (`-e`) — select the environment to run in. * `--no-environment` — run without an environment (not recommended). * `--open` — view the agent’s session in Warp once it’s available. * `--name ` (`-n`) — label the run for grouping and traceability (see [Naming runs](/reference/cli/#naming-runs) below). * `--mcp ` — start one or more MCP servers before execution (UUID, JSON file path, or inline JSON). Can be repeated. * `--model ` — override the default model. * `--skill ` — use a skill from the environment’s repository as the base prompt (see [Using Skills](/reference/cli/#using-skills)). * `--host ` — run on a specific self-hosted worker instead of Warp-hosted infrastructure. * `--attach ` — attach an image file to the agent query. Can be repeated (maximum 5). * `--computer-use` / `--no-computer-use` — enable or disable [Computer Use](/agent-platform/capabilities/computer-use/) for this run. * `--file ` (`-f`) — load run configuration from a YAML or JSON file. **Key differences from `run`** * No `--cwd` — the environment determines the working directory. * No `--share` — sharing options are on `run`, not `run-cloud`. * No `--profile` — cloud runs do not use agent profiles. #### Naming runs [Section titled “Naming runs”](#naming-runs) The `--name` flag assigns a config name to the run. Use it to group related runs under a shared label so you can filter, search, and track them later. **How names work:** * **Skill-based runs** — When you run an agent from a [skill](/agent-platform/capabilities/skills/), the name is automatically set to the skill name. You don’t need to pass `--name` explicitly. * **Custom runs** — When you build your own automation (via the CLI, API, or SDK), set `--name` to a consistent value that describes the workflow’s intent. **Why naming matters:** When your team runs many agents across schedules, integrations, and ad-hoc triggers, `name` lets you answer questions like “how many distinct workflows are we running?” and “how often does this particular workflow run?” You can filter runs by name using the `name` query parameter on `GET /agent/runs` in the [Oz API](/reference/api-and-sdk/). **Examples:** ```sh # Name a recurring workflow for easy tracking oz agent run-cloud \ --environment \ --name "nightly-dependency-check" \ --prompt "Check for outdated dependencies and open a PR with updates" # Skill-based runs are named automatically oz agent run-cloud \ --environment \ --skill "myorg/backend:code-review" \ --prompt "review the latest PR" ``` **When cloud runs fail** * Verify your environment has the correct repository and context. * Check that your profile allows the commands and MCP servers needed. * Ensure environment variables are set in the environment, not your local shell. #### Reusing saved prompts and Warp Drive objects [Section titled “Reusing saved prompts and Warp Drive objects”](#reusing-saved-prompts-and-warp-drive-objects) You can reuse saved prompts with `--saved-prompt`, and reference notebooks, workflows, and rules inline in any `--prompt` string. See [Referencing Warp Drive objects](/reference/cli/warp-drive/) for details. ## Using agent profiles [Section titled “Using agent profiles”](#using-agent-profiles) Agent profiles control what the agent can do, how it behaves, and where it can act. Use the `--profile` flag with `oz agent run` to apply a specific profile. See [Agent profiles](/reference/cli/agent-profiles/) for how to find profile IDs and apply them. ## Using MCP servers [Section titled “Using MCP servers”](#using-mcp-servers) MCP servers connect agents to external systems like GitHub, Linear, or Sentry. Use the `--mcp` flag with any of three formats: a Warp MCP server UUID, inline JSON, or a path to a JSON config file. See [MCP Servers](/reference/cli/mcp-servers/) for full details, including how to find UUIDs, combine multiple servers, and handle environment variables on remote machines. ## Using skills [Section titled “Using skills”](#using-skills) [Skills](/agent-platform/capabilities/skills/) are reusable instruction sets that teach agents how to perform specific tasks. Use the `--skill` flag to run an agent from a skill stored in a repository. See [Skills](/reference/cli/skills/) for supported spec formats and examples for both local and cloud agent runs. ## Collaboration [Section titled “Collaboration”](#collaboration) In addition to text-based output, the CLI can share the agent’s session for you to access on other devices or in a browser. To enable [Agent Session Sharing](/agent-platform/local-agents/session-sharing/), use the `--share` flag. By default, the session is only accessible to the user running the CLI, but you can also share with [Teams](/knowledge-and-collaboration/teams/) or other Warp users: ```sh # Share the agent's session with yourself: $ oz agent run --share --prompt "fix the compiler error" # Give specific users view-only access to a session: $ oz agent run --share firstuser@example.com --share otheruser@example.com --prompt "fix the compiler error" # Let any user on your team edit the session: $ oz agent run --share team:edit --prompt "fix the compiler error" ``` The `--share` flag can be repeated, and uses the following syntax: * `--share user@email.com` or `--share user@email.com:view` — gives specified user read-only access to the session. * `--share user@email.com:edit` — gives specified user `user@email.com` read/write access to the session. * `--share team` or `--share team:view` — gives all members of your team read-only access to the session. * `--share team:edit` — gives all members of your team read/write access to the session. ## Additional commands [Section titled “Additional commands”](#additional-commands) The following commands are available for managing and inspecting Oz resources. ### `oz agent list` [Section titled “oz agent list”](#oz-agent-list) List all available skills discovered from your environments. Optionally filter by repository: ```sh oz agent list oz agent list --repo owner/repo ``` ### `oz run list` / `oz run get` [Section titled “oz run list / oz run get”](#oz-run-list--oz-run-get) List and inspect cloud agent runs: ```sh # List recent runs (default: 10) oz run list oz run list --limit 20 # Get details for a specific run oz run get ``` ### `oz model list` [Section titled “oz model list”](#oz-model-list) List all available models: ```sh oz model list ``` ### `oz environment image list` [Section titled “oz environment image list”](#oz-environment-image-list) List suggested base images for cloud environments: ```sh oz environment image list ``` *** ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) For built-in CLI help commands and solutions to common errors — including authentication issues, agent failures, environment problems, and Docker image issues — see [Troubleshooting](/reference/cli/troubleshooting/). # Agent profiles > Use agent profiles with the Oz CLI to control what the agent can access, how it behaves, and where it can act. Agent profiles control three things: * **What the agent can do** — file access, command execution, and MCP server usage * **How the agent works** — model selection, autonomy level, and response style * **Where the agent can act** — directory allowlists and denylists You can create and configure agent profiles in the Warp app. For detailed instructions, see [Agent Profiles & Permissions](/agent-platform/capabilities/agent-profiles-permissions/). Agent profiles are automatically synced to each host where you have Warp installed, so you can use them remotely as well. Note **Tip:** For CLI usage, create a dedicated profile. The CLI will fail if the agent tries to execute a prohibited action, so make sure your profile allows the directories, commands, and MCP servers you plan to use. Caution The default profile for CLI usage is broadly permissive and gives the agent the ability to read and write files, apply code diffs, and execute commands (with a default denylist). The agent does not have the ability to use MCP servers by default. ## Using a profile with the CLI [Section titled “Using a profile with the CLI”](#using-a-profile-with-the-cli) 1. Find the profile ID using `oz agent profile list`: ```sh $ oz agent profile list +--------------+------------------------+ | Name | ID | +=======================================+ | Default | AnTb02PZfrkVC9l4V15eH1 | |--------------+------------------------| | Coding | CWhozDJPdPCsjJ1pSG0HCN | |--------------+------------------------| | Command Line | hV6n5dNm7ThQVlOiPF8DLS | +--------------+------------------------+ ``` 2. Pass that ID using the `--profile` flag: ```sh $ oz agent run --profile CWhozDJPdPCsjJ1pSG0HCN --prompt "update my CI pipeline to use nextest" ``` Note The `--profile` flag is available on `oz agent run` only. Cloud runs (`oz agent run-cloud`) do not use agent profiles. # API keys for the Oz CLI > Create and manage API keys for authenticating the Oz CLI and cloud agents. API keys let the Oz CLI and cloud agents authenticate without human interaction. Use API keys for CI pipelines, headless servers, VMs, Codespaces, containers, and other automated environments. ## Creating API keys [Section titled “Creating API keys”](#creating-api-keys) You can create an API key from your settings in Warp: 1. Click your profile photo in the top-right corner, then click **Settings**. 2. In the sidebar, expand **Cloud platform** and click **Oz Cloud API Keys**. 3. In the API Keys section, click **+ Create API Key**. 4. Name the key and choose an expiration (1 day, 30 days, 90 days, or never). 5. Select the key type: * `Personal` - Tied to your individual Warp account * `Team` - Tied to your team, not any individual user Note When an agent needs to make code changes (e.g., opening pull requests, pushing branches, or writing to a repository), you have two options: * Use a **personal API key** to authenticate as you. The agent runs with your GitHub permissions, and code changes are attributed to your GitHub account. * Use a **team API key** with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) configured. The agent authenticates with the Oz by Warp GitHub App, and code changes are not attributed to any individual user. Note Team keys without GitHub App authorization are the right fit for automated workflows that don’t require writing to GitHub, such as analysis, monitoring, or triage. 6. Click **Create key**. 7. Copy the raw API key and store it securely. **You won’t be able to see it again after closing the dialog.** ![API key management interface in Warp settings](/_astro/api-key-management.Dmood7_K_18YMaG.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) API key management interface in Warp settings. ## Personal vs team API keys [Section titled “Personal vs team API keys”](#personal-vs-team-api-keys) Warp supports two types of API keys, each with different billing and identity behavior: * **Personal API keys** - Cloud agent runs authenticate as you. These runs can use your personal base credits before drawing from team Add-on Credits, just like running an agent from the Warp app or triggering one via Slack or Linear. * **Team API keys** - Cloud agent runs are not tied to any individual user. These runs can only draw from your team’s pool of Add-on Credits. They cannot use any individual’s base credits. When [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured, team key runs can also clone repositories and open pull requests using the Oz by Warp GitHub App. Team API keys are useful for fully automated workflows, CI/CD pipelines, and scheduled tasks where no specific user context is needed. For billing details, see [Access, Billing, and Identity Permissions](/agent-platform/cloud-agents/team-access-billing-and-identity/). ## Authenticating with API keys [Section titled “Authenticating with API keys”](#authenticating-with-api-keys) You can authenticate with an API key in the CLI using either an environment variable or command flag. We recommend environment variables for security and easier reuse across multiple commands. **Via environment variable (recommended):** ```sh $ export WARP_API_KEY="wk-xxx..." $ oz agent run --prompt "analyze this codebase" ``` **Via command flag:** ```sh $ oz agent run --api-key "wk-xxx..." --prompt "analyze this codebase" ``` Note API keys start with the prefix `wk-`. If your key doesn’t have this prefix, it may be invalid or from an older format. ## Managing API keys [Section titled “Managing API keys”](#managing-api-keys) The API Keys section in **Settings** > **Cloud platform** > **Oz Cloud API Keys** displays all your active keys with the following information: * **Name** - The name you assigned when creating the key * **Key** - A masked suffix (`wk-**xxxx`) to help identify the key * **Scope** - Whether the key is Personal or Team * **Created** - When the key was created * **Last used** - When the key was last used for authentication * **Expires at** - The key’s expiration date, or “Never” if it doesn’t expire ### Deleting API keys [Section titled “Deleting API keys”](#deleting-api-keys) To delete an API key: 1. Go to **Settings** > **Cloud platform** > **Oz Cloud API Keys**. 2. Find the key you want to delete in the API Keys list. 3. Click the delete icon next to the key. Deleted keys are immediately invalidated and cannot be recovered. Any services or scripts using the deleted key will lose access. ## Best practices [Section titled “Best practices”](#best-practices) * **Use environment variables** - Avoid passing API keys directly in commands where they may be logged or visible in shell history. * **Set appropriate expiration** - Use shorter expiration times for development and testing; consider longer durations for stable production workflows. * **Use team keys for automation** - For CI/CD and scheduled tasks, team keys provide cleaner billing attribution and don’t depend on any individual user’s account. * **Use personal keys or configure team GitHub authorization when agents need to write to GitHub** - Personal keys authenticate as you; team keys can also write to GitHub when [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) is configured via the Admin Panel. * **Rotate keys periodically** - Create new keys and retire old ones on a regular schedule to limit exposure from compromised credentials. * **Store securely** - Use secret managers (like 1Password CLI, HashiCorp Vault, or cloud provider secret services) rather than plain text files. # Integration setup > Learn how to set up environments and integrations so you can trigger Oz agents from external tools. This article describes the environment and integration setup that is required before you can trigger agents from external tools, like Slack or Linear. You will learn how to: * Create and configure the environment needed to run agents * Connect that environment to your team * Trigger agents using Slack or Linear Note **You only need to complete this setup once per Warp team**. After an integration exists, anyone on the team can use it. For example, the first time a teammate triggers an agent from Slack or Linear, they’ll be prompted to authorize GitHub with their own account in order for the agent to write back to repos. Note: While cloud agents can be run individually via CLI without a team, integrations (Slack, Linear) require team membership. Note For a quickstart guide to Warp integrations, see the [Integrations overview](/agent-platform/cloud-agents/integrations/). ## How integrations and environments work [Section titled “How integrations and environments work”](#how-integrations-and-environments-work) Warp integrations connect external tools, like Slack or Linear, to agents that run your code in the background. There are three main components to know: * **Triggers** provide the context that tells Warp *what* to run. A trigger could be a Slack message where you tag @Oz, or a Linear issue or comment. * [**Integrations**](/agent-platform/cloud-agents/integrations/) are what connect the trigger surface (Slack, Linear) to Warp. An integration links the trigger to your [Warp team](/knowledge-and-collaboration/teams/) and handles posting results to the original tool, for example, replying in Slack. * **Environments** define how and where agents run your code. When an agent is triggered, Warp uses the environment to spin up a container, clone repositories, and execute the agent’s workflow. ```plaintext Slack or Linear (trigger) → Warp Integration (connects tools to Warp) → Environment (Docker image + repos + setup) → Agent (runs workflow, opens PRs, posts results) ``` Setting up an integration consists of three steps. 1. **Create an environment** for the agent to run your code. 2. **Authorize GitHub** so Warp can clone repositories, write code, debug issues, open pull requests, and more. 3. **Configure** the Oz app with an integration. *** ## Step 1: Creating an environment [Section titled “Step 1: Creating an environment”](#step-1-creating-an-environment) Before you can trigger agents from Slack or Linear, you need an environment. The environment defines how and where Warp runs your code. At a minimum, an environment includes: * A Docker image * One or more GitHub repositories * Optional setup commands Typically, you’ll create **one environment per codebase** (or closely related set of repos) and reuse it across integrations. You can create environments using a guided Agent flow, or directly through the CLI. #### Before you begin [Section titled “Before you begin”](#before-you-begin) Make sure you have: * A GitHub repository (or repositories) that the agent can work in. * A publicly-accessible Docker image that can build and run your code. Official images like `node`, `python`, or `rust` work for many projects. Note You only need to create an environment once. It can be reused across Slack, Linear, and terminal triggers. ### Option 1: Guided environment setup (recommended) [Section titled “Option 1: Guided environment setup (recommended)”](#option-1-guided-environment-setup-recommended) The fastest way to get started is to use the guided environment setup. Use the `/create-environment` [slash command](/agent-platform/capabilities/slash-commands/) if you want Warp to analyze your repos and suggest an environment configuration. You can run the command inside a Git repo directory with no argument, or with one or more repo paths or URLs. For example, from Warp: owner/repo ```bash # File paths /create-environment ./warp-internal ./warp-server /create-environment warpdotdev/warp-internal warpdotdev/warp-server # GitHub URLs /create-environment https://github.com/warpdotdev/warp-internal.git ``` The guided flow will: 1. Detect the repositories you want the agent to work with and identify languages, frameworks, and tools 2. Look for an existing Dockerfile, recommend an official base image, or help build a custom image (if needed) 3. Suggest setup commands based on your scripts and package managers 4. Create the environment through the CLI and return an environment ID This produces a ready-to-use environment that can immediately be connected to [Slack](/agent-platform/cloud-agents/integrations/slack/) or [Linear](/agent-platform/cloud-agents/integrations/linear/). ### Option 2: Create an environment with the CLI [Section titled “Option 2: Create an environment with the CLI”](#option-2-create-an-environment-with-the-cli) If you already know how you want to configure your environment, you can create it directly with the CLI. **Use this approach when:** * You already have a custom Docker image * You want full control over repos and setup commands * You’re scripting or automating environment creation From Warp: ```sh oz environment create \ --name \ --docker-image \ --repo \ --repo \ --setup-command "" \ --setup-command "" \ --description "Optional description" ``` Key flags: * `--name` (`-n`) – human-readable label for the environment. * `--docker-image` (`-d`) – image name on Docker Hub. If not specified, you’ll be prompted to select from available images (see `oz environment image list`). * `--repo` (`-r`) – can be repeated for each repo. * `--setup-command` (`-c`) – can be repeated; commands run in the order provided. * `--description` – optional description (max 240 characters). You can inspect existing environments with `oz environment list`. To delete an environment, use `oz environment delete `. Add `--force` to skip confirmation checks for environments used by integrations. For more details about environment configuration, see the [Slack](/agent-platform/cloud-agents/integrations/slack/) and [Linear](/agent-platform/cloud-agents/integrations/linear/) articles. #### Example environments [Section titled “Example environments”](#example-environments) | Project type | Docker image | Repos | Example setup commands | | --------------- | ----------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------- | | Web dev project | `node:20-bullseye` | your-org/frontend-react your-org/backend-api | `npm install -g pnpm``cd frontend-react && pnpm install``cd backend-api && pnpm install` | | Python project | Custom image based on `python:3.11` | your-org/cool\_python\_project | `cd cool_python_project && pip install -r requirements.txt` | *** ## Step 2: Authorizing GitHub [Section titled “Step 2: Authorizing GitHub”](#step-2-authorizing-github) Warp needs GitHub access so agents can clone your repositories and, when permitted, write code and open pull requests. #### How GitHub Authorization works [Section titled “How GitHub Authorization works”](#how-github-authorization-works) When you create an environment or integration, Warp will prompt you to: * Install or update the Warp GitHub app * Grant access to the repositories in your environment This authorization enables agents to clone repositories into the environment, create branches and commits, and open pull requests. **Public vs private repos** * **Public repos:** Agents can read code without authorization, but cannot write or open PRs. * **Private repos:** The Warp GitHub App must have access and the triggering user must have write permissions. #### Ongoing permissions [Section titled “Ongoing permissions”](#ongoing-permissions) Depending on how the GitHub app is installed in your organization: * You may need to grant access to new repositories over time * An organization admin may need to update the app’s permissions You typically only need to handle this once per team, unless your repo access changes. #### Team-level GitHub authorization [Section titled “Team-level GitHub authorization”](#team-level-github-authorization) For automated workflows that use a [team API key](/reference/cli/api-keys/) (CI/CD pipelines, scheduled agents, SDK-triggered runs), you can configure team GitHub authorization so the agent authenticates with the Oz by Warp GitHub App instead of an individual’s personal token. This requires a Warp team admin to enable the GitHub organization in the Admin Panel (**Settings** > **Admin Panel** > **Platform**). Once configured, tasks initiated with a team API key can clone repos and open pull requests using the GitHub App installation token. For full setup instructions, see [Team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization). Note **Using API keys:** Personal API keys authenticate as you, so the agent runs with your GitHub permissions and code changes are attributed to your account. Team API keys with [team GitHub authorization](/agent-platform/cloud-agents/team-access-billing-and-identity/#team-github-authorization) configured use the GitHub App token instead. *** ## Step 3: Setting up an integration [Section titled “Step 3: Setting up an integration”](#step-3-setting-up-an-integration) Once you have set up at least one environment, you can create integrations that connect it to Slack or Linear. Note For easier setup, use the [Oz web app](https://oz.warp.dev) to configure integrations with a guided flow. Alternatively, use the CLI where `` is your environment ID: ```bash oz integration create slack --environment # or oz integration create linear --environment ``` Note If you omit `--environment`, the CLI will show a list of environments and prompt you to choose one. The CLI then: 1. Links the integration to your Warp team and environment. 2. Opens a browser flow to install the Oz app into your Slack workspace or Linear workspace. 3. Generates an **integration ID** you can later list or delete. **Additional `integration create` flags:** * `--prompt` — custom instructions applied to all runs for this integration. * `--mcp ` — attach MCP servers (inline JSON, file path, or UUID). Can be repeated. * `--model ` — override the default model. * `--host ` — run on a specific self-hosted worker. * `--file ` (`-f`) — load configuration from a YAML or JSON file. **Example with a custom prompt:** ```bash oz integration create slack \ --environment \ --prompt "Always prefix PR titles with [WARP-AGENT] and add detailed test steps." ``` ### Updating an integration [Section titled “Updating an integration”](#updating-an-integration) You can modify an existing integration using `oz integration update`: ```bash oz integration update slack \ --environment \ --prompt "Updated instructions for the integration." ``` **Update-specific flags:** * `--environment ` — change the environment. * `--remove-environment` — remove the environment from the integration. * `--prompt` — update the custom instructions. * `--mcp ` — add MCP servers to the integration. * `--remove-mcp ` — remove an MCP server by name. * `--model ` — update the default model. * `--host ` — update the execution host. Note For more details, see the dedicated pages for [Slack](/agent-platform/cloud-agents/integrations/slack/) and [Linear](/agent-platform/cloud-agents/integrations/linear/) integrations. ## How are environments used at runtime? [Section titled “How are environments used at runtime?”](#how-are-environments-used-at-runtime) When you trigger an agent from Slack or Linear, Warp follows a consistent, repeatable execution process using your environment. At a high level, each run works like this: 1. **Warp receives the trigger**\ Warp captures the message content (for example, a Slack thread or Linear issue), along with any linked context. 2. **Warp creates an execution container**\ Warp spins up a fresh container from the Docker image defined in your environment. 3. **Repositories are cloned**\ The GitHub repositories associated with the environment are cloned into the container. 4. **Setup commands are run**\ Any setup commands you configured, like installing dependencies, are executed. 5. **The agent workflow runs**\ The agent executes the task using the provided context, tools, and permissions. 6. **Results are posted back**\ Progress updates, summaries, and results are posted back to Slack or Linear. 7. **The container is destroyed**\ After the run completes, the container is torn down. Each run starts from a clean, isolated environment. ## Next steps [Section titled “Next steps”](#next-steps) You now have everything needed to trigger agents from your team’s tools. From here, you can: * Add or adjust setup commands * Switch to a custom Docker image * Include additional repositories * Add custom prompts for consistent agent behavior * Create separate environments for different workflows or teams **Additional reading** * [Cloud Agents Overview](/agent-platform/cloud-agents/overview/) * [Oz Platform](/agent-platform/cloud-agents/platform/) * [Slack](/agent-platform/cloud-agents/integrations/slack/), [Linear](/agent-platform/cloud-agents/integrations/linear/), and [GitHub Actions](/agent-platform/cloud-agents/integrations/github-actions/) integrations * [Troubleshooting](/reference/cli/troubleshooting/) # MCP servers (CLI reference) > Connect agents to external tools like GitHub, Linear, and Sentry by passing MCP servers to the --mcp flag as a UUID, inline JSON, or file path. MCP servers connect agents to external systems like GitHub, Linear, or Sentry. To use a [Model Context Protocol (MCP)](/agent-platform/capabilities/mcp/) server from the CLI, use the `--mcp` flag with `oz agent run` or `oz agent run-cloud`. For a conceptual overview of MCP with cloud agents — including configuration schema, full agent config examples, and limitations — see [MCP Servers](/agent-platform/cloud-agents/mcp/) in the Cloud Agents docs. *** ## Using the `--mcp` flag [Section titled “Using the --mcp flag”](#using-the---mcp-flag) The `--mcp` flag accepts three formats: * **UUID** — reference a Warp-shared MCP server by its UUID (find UUIDs with `oz mcp list`) * **Inline JSON** — pass a full MCP JSON configuration directly as a string * **File path** — path to a JSON file containing the MCP configuration You can repeat `--mcp` to include multiple servers. ### Passing MCP servers by UUID [Section titled “Passing MCP servers by UUID”](#passing-mcp-servers-by-uuid) 1. Locate the MCP server UUID using `oz mcp list`. This command lists all MCP servers configured in your Warp account, including team-shared ones: ```sh $ oz mcp list +--------------------------------------+--------+ | UUID | Name | +===============================================+ | 1deb1b14-b6e5-4996-ae99-233b7555d2d0 | github | |--------------------------------------+--------| | 65450c32-9eb1-4c57-8804-0861737acbc4 | linear | |--------------------------------------+--------| | d94ade64-0e73-47a6-b3ee-14e5afec3d90 | Sentry | +--------------------------------------+--------+ ``` Alternatively, copy the UUID from Warp in **Settings** > **Agents** > **MCP servers**. ![MCP servers page, showing a server with its UUID](/_astro/mcp-server-id.L5Kbd7FO_Z2wXS2o.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) MCP servers page, showing a server with its UUID. 2. Pass the UUID to `--mcp`: ```sh $ oz agent run --mcp "1deb1b14-b6e5-4996-ae99-233b7555d2d0" --prompt "who last updated the README?" ``` ### Passing MCP servers as inline JSON or a file [Section titled “Passing MCP servers as inline JSON or a file”](#passing-mcp-servers-as-inline-json-or-a-file) You can pass MCP configuration inline or via a file: ```sh # Inline JSON $ oz agent run --mcp '{"github": {"url": "https://api.githubcopilot.com/mcp/"}}' --prompt "list open issues" # From a file $ oz agent run --mcp ./my-mcp-config.json --prompt "list open issues" ``` The file must contain a valid MCP JSON object. For example: ```json { "github": { "url": "https://api.githubcopilot.com/mcp/" }, "sentry": { "command": "npx", "args": ["-y", "mcp-remote@latest", "https://mcp.sentry.dev/mcp"] } } ``` ### Combining multiple servers [Section titled “Combining multiple servers”](#combining-multiple-servers) Pass `--mcp` multiple times to combine UUID references, inline JSON, and file-based configs in a single run: ```sh $ oz agent run \ --mcp "1deb1b14-b6e5-4996-ae99-233b7555d2d0" \ --mcp '{"sentry": {"url": "https://mcp.sentry.dev/sse"}}' \ --prompt "open a PR that fixes the top Sentry error" ``` *** ## Environment variables on remote machines [Section titled “Environment variables on remote machines”](#environment-variables-on-remote-machines) Warp syncs MCP server configuration between machines logged in with your Warp account, but **does not** sync the environment variables used in that configuration. When running on a remote machine, set any required secrets manually before running the agent: ```sh export MY_MCP_SERVER_ACCESS_TOKEN="..." $ oz agent run --mcp "904a8936-fa82-4571-b1d6-166c26197981" --prompt "use my MCP server to check for errors" ``` Note For cloud agent workflows, use [Oz-managed secrets](/agent-platform/cloud-agents/secrets/) to store and inject credentials safely — secrets are stored in the cloud and referenced by name in your config. For local runs, a secrets manager CLI such as [`op`](https://developer.1password.com/docs/cli/get-started/), [`pass`](https://www.passwordstore.org/), or [`gcloud secrets versions access`](https://cloud.google.com/secret-manager/docs/create-secret-quickstart#secretmanager-quickstart-gcloud) can fetch secrets on remote hosts without exposing them in your shell history. *** ## Learn more [Section titled “Learn more”](#learn-more) * [MCP Servers (cloud agents)](/agent-platform/cloud-agents/mcp/) — configuration schema, full agent config file examples, and cloud agent limitations * [Model Context Protocol (MCP)](/agent-platform/capabilities/mcp/) — configuring MCP servers in Warp for local agents * [Secrets](/agent-platform/cloud-agents/secrets/) — store credentials in Warp so agents can access them at run time without exposing them in config files # CLI quickstart > Set up and run your first cloud agent via the Oz CLI in less than 5 minutes. This guide walks you through the essentials to get up and running with the Oz CLI in less than 5 minutes: installing the CLI, authenticating, running your first local agent, and optionally connecting MCP servers to give the agent access to external tools. Watch this short demo of the Oz CLI workflow: ![YouTube video](https://i.ytimg.com/vi/WpcChBNDCXQ/sddefault.jpg) ## 1. Install the CLI [Section titled “1. Install the CLI”](#1-install-the-cli) If you already have the [Warp desktop app installed](/getting-started/quickstart/installation-and-setup/), the **CLI is included** and available in Warp. If not, see [Installing the CLI](/reference/cli/#installing-the-cli) for installation options for all platforms. ## 2. Authenticate [Section titled “2. Authenticate”](#2-authenticate) For local development and first-time setup, authenticate interactively using the `oz login` command. **For example, on macOS:** ```sh oz login ``` This command prints a sign-in URL in your terminal. Open the URL in your browser to login to Warp. Your credentials will be stored securely for future CLI use. Interactive login works on both **local** and **remote** machines, and does not require API keys. Note **Running in CI or a headless environment?** Use an API key instead of `oz login`. Export it before running any `oz` command: ```sh export WARP_API_KEY="wk-..." ``` In the Warp app, create an API key in **Settings** > **Cloud platform** > **Oz Cloud API Keys**. See [API Keys](/reference/cli/api-keys/) for guidance on personal vs. team keys and security best practices. ## 3. Run an agent [Section titled “3. Run an agent”](#3-run-an-agent) From any directory, run: ```sh oz agent run --prompt "summarize this directory" ``` This uses the default agent profile, loads any available MCP servers, and executes the run locally. The output appears directly in your terminal. What happens: * The agent runs locally in your current working directory. * The session is tracked on Warp’s backend for observability and collaboration. * The agent autonomously executes commands and streams output to your terminal. ## 4. Run a cloud agent (optional) [Section titled “4. Run a cloud agent (optional)”](#4-run-a-cloud-agent-optional) Cloud agents run in a remote environment with your repositories cloned and dependencies installed, making them useful for tasks that need full codebase access. If you haven’t already created an environment, run `/create-environment` in Warp or follow the [Cloud Agents Quickstart](/agent-platform/cloud-agents/quickstart/). Then run the following command: ```sh oz agent run-cloud --environment --prompt "Scan this repo for outdated dependencies" ``` Replace `` with your environment ID, which you can find by running `oz environment list` on the Oz CLI. ## 5. Add MCP context (optional) [Section titled “5. Add MCP context (optional)”](#5-add-mcp-context-optional) You can connect MCP servers to give the agent access to external tools like GitHub or Linear. Pass MCP configuration inline or from a file using the `--mcp` flag: ```sh oz agent run --mcp '{"github": {"url": "https://api.githubcopilot.com/mcp/"}}' --prompt "Open a pull request that fixes TODOs in this repo" ``` See [MCP Servers](/reference/cli/mcp-servers/) for all supported formats, including UUID references and multi-server configurations. ## Next steps [Section titled “Next steps”](#next-steps) Once you’ve successfully set up and run your agent, explore other configurations and workflows with the Oz CLI: * Customize behavior with [agent profiles](/reference/cli/agent-profiles/). * [Reuse prompts](/reference/cli/warp-drive/) with `--saved-prompt`. * Connect agents to external systems using [MCP Servers](/reference/cli/mcp-servers/). * Authenticate with [API keys](/reference/cli/api-keys/) for automated environments or workflows. * Get up-to-date information about the Oz CLI using the [`oz help` command](/reference/cli/troubleshooting/#getting-help). * Run agents in CI with the [GitHub Actions quickstart](/agent-platform/cloud-agents/integrations/quickstart-github-actions/). Continue reading the [Oz CLI reference](/reference/cli/) to learn how to install the CLI on different platforms, authenticate in different environments, and configure agents for real-world workflows. # Skills via the Oz CLI > Use skills with the Oz CLI to run agents from reusable skill definitions stored in your repositories. [Skills](/agent-platform/capabilities/skills/) are reusable instruction sets that teach agents how to perform specific tasks. Use the `--skill` flag to run an agent from a skill in a repository accessible to your environment. ## Skill spec format [Section titled “Skill spec format”](#skill-spec-format) The `--skill` flag accepts a skill specification that identifies which skill to use: ```sh # Fully qualified (recommended) oz agent run-cloud -e --skill "owner/repo:skill-name" --prompt "deploy to staging" # With full path oz agent run-cloud -e --skill "warpdotdev/warp-server:.warp/skills/deploy/SKILL.md" --prompt "deploy to staging" ``` Supported formats: * `owner/repo:skill-name` — skill by name in a specific repository (recommended) * `owner/repo:path/to/SKILL.md` — skill by full path in a repository * `repo:skill-name` — skill by name (only works when the repo is configured in your environment) ## Using skills with cloud agents [Section titled “Using skills with cloud agents”](#using-skills-with-cloud-agents) Skills are particularly useful with cloud agents (`oz agent run-cloud`) because they define reusable workflows that run consistently across environments: ```sh # Run a deploy skill from a specific repo oz agent run-cloud \ --environment SVhg783GBFQHk1OfdPfFU9 \ --skill "myorg/backend:.warp/skills/deploy/SKILL.md" \ --prompt "deploy to staging" # Run a code review skill oz agent run-cloud \ --environment SVhg783GBFQHk1OfdPfFU9 \ --skill "myorg/backend:code-review" \ --prompt "review the latest PR" ``` Note When you specify a skill, it provides the base instructions for the agent. The `--prompt` adds additional context or parameters for that specific run. When you run an agent from a skill, the run `name` is automatically set to the skill name — no need to pass `--name` explicitly. ## Using skills with local agents [Section titled “Using skills with local agents”](#using-skills-with-local-agents) For local agent runs, skills from your current repository are automatically discovered. You can also explicitly specify a skill: ```sh oz agent run --skill "owner/repo:skill-name" --prompt "additional context" ``` For more information about creating and managing skills, see [Skills](/agent-platform/capabilities/skills/). # CLI Troubleshooting > Solutions for common Oz CLI errors — including authentication issues, agent failures, environments, GitHub access, and Docker image issues. ## Getting help [Section titled “Getting help”](#getting-help) The CLI includes built-in documentation for all commands: ```bash # See all available commands oz help # Get details on a specific command oz help agent run # Explore MCP-related commands oz help mcp ``` ## Common errors [Section titled “Common errors”](#common-errors) **Command not found / CLI not installed correctly**\ Verify your installation path and confirm the CLI version: ```bash oz --version ``` **Authentication issues** * Interactive login: ensure you’ve completed the browser-based flow with `oz login`. * API keys: confirm the key is valid, not expired, and exported correctly. **Agent or MCP errors**\ Ensure your agent profile and [MCP servers](/agent-platform/capabilities/mcp/) are configured properly, with correct permissions. See [MCP Servers](/reference/cli/mcp-servers/) and [Agent profiles](/reference/cli/agent-profiles/) for details. *** ## Environments [Section titled “Environments”](#environments) #### How do I see what environment my integration is using? [Section titled “How do I see what environment my integration is using?”](#how-do-i-see-what-environment-my-integration-is-using) List your integrations: ```plaintext oz integration list ``` This shows each integration, its ID, and the environment it’s linked to. Use this to confirm which environment to inspect or update before making changes. #### How do I see what’s inside that environment? [Section titled “How do I see what’s inside that environment?”](#how-do-i-see-whats-inside-that-environment) Once you know the environment ID, run: ```plaintext oz environment get ``` This prints the full configuration, including: * The **environment ID** (used in other commands) * The **name** * The **Docker image** * Associated **repos** This is the most reliable way to verify what the agent will see when it runs. #### How do I add or remove repos and setup commands? [Section titled “How do I add or remove repos and setup commands?”](#how-do-i-add-or-remove-repos-and-setup-commands) Use `oz environment` update. You can modify environments incrementally without recreating them. **Add a repo:** ```plaintext oz environment update --repo owner/repo ``` **Remove a repo:** ```plaintext oz environment update --remove-repo owner/repo ``` **Add a setup command:** ```plaintext oz environment update --setup-command "your command" ``` **Remove a setup command (must match exactly):** ```plaintext oz environment update --remove-setup-command "exact command" ``` Notes: * Warp may prompt you to adjust GitHub app permissions when adding repos. * Setup commands run in the order they are defined. #### **How do I delete an environment?** [Section titled “How do I delete an environment?”](#how-do-i-delete-an-environment) If an environment is no longer needed: ```plaintext oz environment delete ``` Add `--force` to skip confirmation checks for environments used by integrations. Only do this once you’ve confirmed no active integrations are relying on that environment. If an integration points to a deleted environment, requests from Slack/Linear will fail until you create a new integration with a valid environment. ### Integrations [Section titled “Integrations”](#integrations) #### **How do I figure out what environment my integration is using?** [Section titled “How do I figure out what environment my integration is using?”](#how-do-i-figure-out-what-environment-my-integration-is-using) List your integrations: ```plaintext oz integration list ``` This shows each integration, its ID, and the environment it’s attached to. Use this when you’re unsure which environment to update or delete. #### **I created a new environment, but don’t see it when running oz integration create** [Section titled “I created a new environment, but don’t see it when running oz integration create”](#i-created-a-new-environment-but-dont-see-it-when-running-oz-integration-create) Check: 1. Environment exists and is healthy: `oz environment list` 2. You’re on the correct Warp team. Make sure your local CLI is logged into the same team where the environment was created. 1. If both look correct and the environment still doesn’t appear, recreate it and confirm there were no errors during creation. ## GitHub & repo access issues [Section titled “GitHub & repo access issues”](#github--repo-access-issues) #### **I’m being asked to authorize GitHub when creating/using an environment** [Section titled “I’m being asked to authorize GitHub when creating/using an environment”](#im-being-asked-to-authorize-github-when-creatingusing-an-environment) This happens when: * You add a repo that Warp doesn’t have access to yet, or * You personally haven’t granted the Warp GitHub app permissions for that repo. Follow the GitHub popup flow to install/adjust the Warp GitHub app. #### **The agent can’t open PRs or push changes to my repo** [Section titled “The agent can’t open PRs or push changes to my repo”](#the-agent-cant-open-prs-or-push-changes-to-my-repo) Check the following: 1. **Repo is part of your environment**. 1. Make sure the repo is listed in: `oz environment get ` 2. **Warp GitHub app has access to that repo** 1. In GitHub’s settings, confirm the Warp app is installed and that the repo is selected. 3. **You have write access** 1. The agent inherits your GitHub permissions. If you only have read access, Warp can’t open PRs or push branches on your behalf. ### Docker image & environment failures [Section titled “Docker image & environment failures”](#docker-image--environment-failures) #### **I see errors like “pull access denied” or “repository does not exist”** [Section titled “I see errors like “pull access denied” or “repository does not exist””](#i-see-errors-like-pull-access-denied-or-repository-does-not-exist) Check: 1. The Docker image name and tag are correct. 2. The image is public on Docker Hub. 3. You can pull it locally: `docker pull ` If local docker pull fails, fix the image visibility/name first, then recreate or update the environment with a working image. #### **The agent can’t find tools or runtimes inside the environment** [Section titled “The agent can’t find tools or runtimes inside the environment”](#the-agent-cant-find-tools-or-runtimes-inside-the-environment) This usually means the Docker image is missing required dependencies. Fix by either: * Updating the Dockerfile used to build the image, then pushing a new version to Docker Hub and updating the environment with the new image, or * Adding additional setup commands to install the missing tools: `oz environment update --setup-command "apt-get update && apt-get install -y "` #### **I see “VM failed before the agent could run. This is likely an issue with your Docker image”** [Section titled “I see “VM failed before the agent could run. This is likely an issue with your Docker image””](#i-see-vm-failed-before-the-agent-could-run-this-is-likely-an-issue-with-your-docker-image) This typically means your Docker image uses musl libc instead of glibc. Alpine Linux and other musl-based images are not compatible with the agent runtime. Fix: * Switch to a glibc-based image such as Debian, Ubuntu, or the default (non-Alpine) variants of official Docker Hub images (e.g. `node`, `python`, `rust`). * If you’re using an Alpine variant like `node:20-alpine`, replace it with the default tag (e.g. `node:20`). # Warp Drive context > Use saved prompts, notebooks, workflows, and rules from Warp Drive as context in CLI agent commands. ## Reusing saved prompts [Section titled “Reusing saved prompts”](#reusing-saved-prompts) When you find prompts that work well, save them in [Warp Drive](/knowledge-and-collaboration/warp-drive/) to reuse across sessions, share with teammates, and integrate into automated workflows. For more information, see [Prompts](/knowledge-and-collaboration/warp-drive/prompts/). To reuse a saved prompt, find its ID. The ID is the last segment of its Warp Drive sharing link. For example, in the URL: ```plaintext https://warp.dev/drive/prompt/Fix-compiler-error-sgNpbUgDkmp2IImUVDc8kR ``` …the ID is `sgNpbUgDkmp2IImUVDc8kR`. Then pass the ID using the `--saved-prompt` flag: ```bash $ oz agent run --saved-prompt sgNpbUgDkmp2IImUVDc8kR ``` ## Referencing Warp Drive objects as context [Section titled “Referencing Warp Drive objects as context”](#referencing-warp-drive-objects-as-context) Use ``, ``, or `` in prompts to attach [Warp Drive objects](/knowledge-and-collaboration/warp-drive/) and [rules](/agent-platform/capabilities/rules/) as context for the agent. Note **Tip:** Use the [@ context menu](/agent-platform/local-agents/agent-context/using-to-add-context/) in Warp to construct a prompt with the right references, then copy it into your CLI command. ```bash $ oz agent run --prompt "Follow the instructions in " ``` # Support & Community > Connect with the developers and engineers building with Warp. Share what you've built, shape what we build next, and get help when you're stuck. ## Find your space [Section titled “Find your space”](#find-your-space) ### Join the community [Section titled “Join the community”](#join-the-community) Our Slack community is where workflows get shared, bugs get squashed, and ideas turn into features. Talk directly with Warp engineers and other developers. Tip [**Join the Warp community on Slack**](https://go.warp.dev/join-preview) Built something with Warp? An agent workflow, a CLI tool, a creative terminal setup? Drop it in `#how-do-you-warp` — we spotlight community projects regularly. ### Build with us on GitHub [Section titled “Build with us on GitHub”](#build-with-us-on-github) Bugs, feature requests, and what’s shipping next. Your upvotes decide what we prioritize. [**Open an issue**](https://github.com/warpdotdev/warp/issues) Warp’s client is open source. See [Contributing to Warp](/support-and-community/community/contributing/) for the full set of contribution paths, including opening pull requests, contributing themes and workflows, and sharing Warp Drive objects. ### Attend events [Section titled “Attend events”](#attend-events) We host [live events](https://luma.com/warpdotdev) year-round — product demos, launch celebrations, community Q\&As, and more. One recurring favorite: Note **Warp 101 livestreams** — A live walkthrough of Warp features, tips, and Q\&A with the team, held every two weeks. [**Register for upcoming events on Luma**](https://luma.com/warpdotdev) ### Follow along [Section titled “Follow along”](#follow-along) * [**X**](https://x.com/warpdotdev) - What we’re shipping and what the community is building * [**YouTube**](https://www.youtube.com/@warpdotdev) - Tutorials, demos, and product deep dives * [**LinkedIn**](https://www.linkedin.com/company/warpdotdev) - Engineering deep dives and company news * [**Reddit**](https://www.reddit.com/r/warpdotdev/) - Unfiltered discussions, feature debates, and Q\&A ## Programs [Section titled “Programs”](#programs) * [**Warp Preview**](/support-and-community/community/warp-preview-and-alpha-program/) — Try experimental features before anyone else. Your feedback directly shapes what ships. * [**Refer a Friend**](/support-and-community/community/refer-a-friend/) — Send Warp to a developer you think would love it. Earn themes, swag, and gift cards. * [**Oz Open Source Partnership**](/support-and-community/community/open-source-partnership/) — Free Oz agent credits for high-impact open source projects. Note **Ambassador program** We’re building an Ambassador program for developers who want to lead and grow the Warp community. Join the [community Slack](https://go.warp.dev/join-preview) to hear when applications open. ## Get help [Section titled “Get help”](#get-help) * [Sending us feedback](/support-and-community/troubleshooting-and-support/sending-us-feedback/) * [Known issues](/support-and-community/troubleshooting-and-support/known-issues/) * [Plans, pricing, and refunds](/support-and-community/plans-and-billing/plans-pricing-refunds/) * [Privacy](/support-and-community/privacy-and-security/privacy/) # Contributing to Warp > Contribute to Warp's open source client by filing issues, opening pull requests, building themes, and sharing workflows. Warp’s client is open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE) at [`warpdotdev/warp`](https://github.com/warpdotdev/warp), and there’s room for every kind of contribution — from a one-line bug report to a full feature PR, a new theme, or a workflow that ships to every Warp user. For the full code contribution flow, see [`CONTRIBUTING.md`](https://github.com/warpdotdev/warp/blob/master/CONTRIBUTING.md). ## Ways you can contribute [Section titled “Ways you can contribute”](#ways-you-can-contribute) * **Report a bug or request a feature** - [File an issue](https://github.com/warpdotdev/warp/issues/new/choose) in [`warpdotdev/warp`](https://github.com/warpdotdev/warp), or [explore existing issues](https://github.com/warpdotdev/warp/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc) to comment on or upvote ones that matter to you. Clear reproductions and upvotes help Warp prioritize. * **Contribute code** - Claim any issue labeled `ready-to-spec` or `ready-to-implement`, then open a spec or code PR. [`CONTRIBUTING.md`](https://github.com/warpdotdev/warp/blob/master/CONTRIBUTING.md) covers the spec format, tests, `./script/presubmit`, and the PR template. * **Build a theme** - Submit a new color scheme or improve an existing one at [`warpdotdev/themes`](https://github.com/warpdotdev/themes). * **Share a workflow** - Add reusable command patterns to [`warpdotdev/workflows`](https://github.com/warpdotdev/workflows). Merged workflows ship to every Warp user. * **Publish Warp Drive objects** - Share Workflows, Notebooks, Rules, and Prompts publicly from [Warp Drive](/knowledge-and-collaboration/warp-drive/). * **Find an issue to pick up** - Browse [`build.warp.dev`](https://build.warp.dev), a live dashboard of the work Warp’s agents are tackling across `warpdotdev/warp`. Use it to spot gaps, avoid duplicate work, and surface issues that haven’t been claimed yet. * **Help others in the community** - Answer questions in the [Warp community Slack](https://go.warp.dev/join-preview) or [Discord](https://discord.com/invite/warpdotdev), and join conversations in [GitHub Discussions](https://github.com/warpdotdev/warp/discussions). ## Send feedback and bug reports [Section titled “Send feedback and bug reports”](#send-feedback-and-bug-reports) The fastest way to file a bug or feature request is the [`/feedback`](/support-and-community/troubleshooting-and-support/sending-us-feedback/#using-feedback-in-warp) slash command inside Warp. It drafts and files a GitHub issue without leaving the terminal. Other channels: * File an issue directly in [`warpdotdev/warp`](https://github.com/warpdotdev/warp/issues/new/choose). * Press `⌘+Shift+F` (macOS) or `Ctrl+Shift+F` (Windows/Linux) to open the in-app feedback dialog. On macOS, you can also use the **Send Feedback** option in Warp’s Help menu. * Email for privacy questions. For logs, crash reports, CPU samples, and AI conversation IDs, see [Sending feedback and logs](/support-and-community/troubleshooting-and-support/sending-us-feedback/). ## Reporting security issues [Section titled “Reporting security issues”](#reporting-security-issues) Danger Do not file public issues for security vulnerabilities. Email with reproduction steps, impact, and any proof of concept. We’ll acknowledge receipt and coordinate a fix and disclosure. Full guidance is in [`CONTRIBUTING.md`](https://github.com/warpdotdev/warp/blob/master/CONTRIBUTING.md#reporting-security-issues). ## Code of conduct [Section titled “Code of conduct”](#code-of-conduct) Warp’s open source repositories follow the [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. Read the [full text](https://github.com/warpdotdev/warp/blob/master/CODE_OF_CONDUCT.md), or report violations to . # Oz Open Source Partnership > Warp supports high-impact open source projects with free Oz agent credits through the Oz Open Source Partnership program. Warp is committed to supporting the open source community. Through the Oz Open Source Partnership program, we offer free Oz agent usage credits to high-impact open source projects, helping maintainers and contributors accelerate their development workflows. ## What you get [Section titled “What you get”](#what-you-get) * **Free Oz credits** - Receive complimentary credits to run Oz agents on your open source project * **Oz agent access** - Use cloud agents to automate tasks like code review, bug triage, documentation, and more across your repositories * **Ongoing support** - Warp partners with accepted projects to ensure they get the most value from Oz agents ## Who can apply [Section titled “Who can apply”](#who-can-apply) The Oz Open Source Partnership program is designed for actively maintained, high-impact open source projects. When reviewing applications, we consider factors like community size, project activity, and the potential impact of Oz agents on your workflow. Note Have questions about the program? Reach out to us at . ## How to apply [Section titled “How to apply”](#how-to-apply) Tell us about your open source project by filling out the [application form](https://tally.so/r/LZWxqG). We’ll review your submission and follow up with next steps. Note The Oz Open Source Partnership program provides free Oz agent credits for open source projects. This is separate from Warp’s open source client — the Warp client is published under AGPL v3 at [`warpdotdev/warp`](https://github.com/warpdotdev/warp); see [Contributing to Warp](/support-and-community/community/contributing/). For sponsorship opportunities for your project, reach out to . # Refer a friend and earn rewards > Think Warp would be the ideal product for someone you know? You can invite your team or friends within the app and earn rewards. Note Go to **Settings** > **Referrals** to open the invite a friend referral dialog. **There are two ways you can invite a friend:** 1. Send them an invite link. They will be directed to our product download page. 2. Input their email address, which we’ll use to email them with your referral link. ## Referral rewards program [Section titled “Referral rewards program”](#referral-rewards-program) We give out themes, swag, and other perks as thanks for helping to grow our community. The tiers are as follows: | Referrals | Reward | Digital Gift Card Alternative | | --------- | -------------------- | :---------------------------: | | 1 | Exclusive Theme | $0 | | 5 | Stickers and Keycaps | $5 | | 10 | T-Shirt | $10 | | 20 | Moleskin Notebook | $20 | | 35 | Baseball Hat | $35 | | 50 | Hoodie | $50 | | 75 | Hydroflask | $75 | | 100 | North Face Backpack | $100 | By participating in Warp’s referral program, you agree to the [Referral program terms and conditions](/support-and-community/community/refer-a-friend/#referral-program-terms-and-conditions). ### Your friend gets a theme [Section titled “Your friend gets a theme”](#your-friend-gets-a-theme) If your friend joins and activates their Warp account after clicking your invite link, they will receive a unique theme. ## Referral program terms and conditions [Section titled “Referral program terms and conditions”](#referral-program-terms-and-conditions) > **Last Updated:** November 27, 2024 ### 1 referral: An exclusive theme [Section titled “1 referral: An exclusive theme”](#1-referral-an-exclusive-theme) When someone joins Warp with your referral code, the referral theme will become available in your theme picker after you restart the app. We also send an email alerting you. This reward is available to all users worldwide. ### All other referral tiers [Section titled “All other referral tiers”](#all-other-referral-tiers) Once you’ve hit the other referral tiers, we’ll email you with details on how to claim your reward. Physical rewards are available to users residing in the United States, and Warp will cover shipping costs for these users. International users can also claim physical rewards; however, they will be responsible for any customs fees. For all users, there’s an option to claim a digital reward (gift card) instead of physical Warp swag. ### International users [Section titled “International users”](#international-users) International users who choose physical rewards are responsible for paying any customs fees associated with shipping. Estimated costs are provided in the [approximate customs fees by region](/support-and-community/community/refer-a-friend/#approximate-customs-fees-by-region) section below. Please note that once the package leaves the United States, Warp no longer has visibility or control over the shipment process, including any customs-related issues or fees that may arise. Alternatively, international users may opt to receive a digital gift card instead of a physical reward. Note: for users who qualified for referral rewards before October 15th, 2024, Warp will cover all shipping and customs costs. Starting from that date onwards, international users receiving referral rewards will be responsible for paying any customs fees associated with shipping. ### Shipping time frame [Section titled “Shipping time frame”](#shipping-time-frame) Physical rewards may take 2 to 3 weeks to arrive for users located in the United States, and 4 to 12 weeks for international users. After claiming your order, you will receive an email with a shipping confirmation and a tracking link from Printfection, our swag vendor. If you have any questions about the status of your shipment or order, please reach out to with your order number. ### General terms and conditions [Section titled “General terms and conditions”](#general-terms-and-conditions) Referrals must be valid and confirmed by Warp to count towards rewards. This means the referred user must accept the referral via the referral link and log into Warp’s desktop application. Warp reserves the right, at its sole discretion, to disqualify any referrals deemed fraudulent. Any users who refer fake emails or users will be disqualified at the sole discretion of Warp. Warp reserves the right to modify or terminate the referral rewards program at any time without prior notice. Participation in the swag program constitutes acceptance of these terms and conditions. If you have any questions about the referral program, please contact . ### Digital gift card rewards [Section titled “Digital gift card rewards”](#digital-gift-card-rewards) All amounts are listed in USD. Rewards are based on the number of valid referrals. | Number of referrals | Gift card amount | | :-----------------: | :--------------: | | 1 | $0 | | 5 | $5 | | 10 | $10 | | 20 | $20 | | 35 | $35 | | 50 | $50 | | 75 | $75 | | 100 | $100 | ### Approximate customs fees by region [Section titled “Approximate customs fees by region”](#approximate-customs-fees-by-region) All amounts are listed in USD. Fees are estimates and may vary regardless of package size. | Country / region | Approximate customs fees | | :-------------------------------------------------: | :----------------------: | | Canada & Mexico | $40 to $70 | | Europe | $40 to $80 | | Others (Asia, South America, Africa, Oceania, etc.) | $50 to $120 | \*Note: The approximate customs fees provided are estimates and may vary based on your country’s specific import regulations, taxes, and duties. Actual fees can differ due to factors such as package contents, declared value, and current customs policies. We recommend checking with your local customs office or postal service for precise information relevant to your situation. ## Referral rewards program FAQs [Section titled “Referral rewards program FAQs”](#referral-rewards-program-faqs) #### **”I have referred people but have not received an email.”** [Section titled “”I have referred people but have not received an email.””](#i-have-referred-people-but-have-not-received-an-email) Please allow a few hours for the referral system to process and send email updates. If you still haven’t received an email after a reasonable amount of time, contact us at and we’ll look into it. #### **”I’ve claimed my physical reward but have issues receiving my package.”** [Section titled “”I’ve claimed my physical reward but have issues receiving my package.””](#ive-claimed-my-physical-reward-but-have-issues-receiving-my-package) If you experience issues with your shipment, please respond to the shipping notification email you should have received from Printfection. For further assistance, contact our swag vendor’s operations team at with your order number. #### **”I’ve referred friends, but they didn’t use the link. Does it still count?”** [Section titled “”I’ve referred friends, but they didn’t use the link. Does it still count?””](#ive-referred-friends-but-they-didnt-use-the-link-does-it-still-count) Unfortunately, any referrals who didn’t use your link will not count towards the rewards, and we have no way of modifying the referral count. #### **”I’ve referred friends, but they joined anonymously. Does it still count?”** [Section titled “”I’ve referred friends, but they joined anonymously. Does it still count?””](#ive-referred-friends-but-they-joined-anonymously-does-it-still-count) For a referral to count, new users must sign up and actively use Warp. Unfortunately, we’re unable to associate anonymous users with specific referral links at this time. We’re actively working on solutions to make the referral process more seamless and reliable for anonymous users. Stay tuned for updates as we improve this experience. #### **”The reward tiers recently changed with the new swag items. I previously qualified for X. What happens now, and are the new swag items retroactive?”** [Section titled “”The reward tiers recently changed with the new swag items. I previously qualified for X. What happens now, and are the new swag items retroactive?””](#the-reward-tiers-recently-changed-with-the-new-swag-items-i-previously-qualified-for-x-what-happens-now-and-are-the-new-swag-items-retroactive) Our referral program was updated on November 21, 2024, with new reward tiers and exciting swag options. To ensure a smooth transition, we will honor previous reward tiers alongside the updated program until December 15, 2024. If you’re unsure how these changes impact your previous qualifications or eligibility for the new swag items, feel free to reach out to us at for assistance. # Warp Preview program > Warp Preview is an early-access build of Warp with experimental features. Try what's next before it ships. Warp Preview is an early-access program that allows you to explore Warp’s newest and most experimental features. It’s independent from the stable build, so you can always revert to a reliable version of Warp whenever you need it. ### Key Warp Preview features [Section titled “Key Warp Preview features”](#key-warp-preview-features) * **Early access** - Try out experimental features before they’re officially released. * **Faster updates** - Enjoy frequent updates and patches as we refine new capabilities. * **Direct impact** - Your feedback plays a critical role in shaping Warp’s future. To learn more about Warp Preview, check out our [launch blog post](https://warp.dev/blog/warp-preview). ### Getting started with Warp Preview [Section titled “Getting started with Warp Preview”](#getting-started-with-warp-preview) 1. **Download**: Get the Warp Preview build from [warp.dev/download-preview](https://warp.dev/download-preview). 2. **Sign in**: [Log in](/getting-started/quickstart/installation-and-setup/#log-in-to-warp-optional) with your Warp account (not optional for Warp Preview). 3. **Run side-by-side**: You can keep Warp Preview alongside your stable Warp installation. ### Important notes [Section titled “Important notes”](#important-notes) * **Experimental build** - Expect occasional bugs or incomplete features. * **Login required** - You must sign in to use Warp Preview. This helps us gather feedback, quickly diagnose critical issues, and ensure we can reach out if you need support. * **Flexibility** - Switch between Preview and Stable builds at any time. * **Distinct icon** - Warp Preview uses a unique icon to help distinguish it from the stable version. ### Providing Warp Preview feedback [Section titled “Providing Warp Preview feedback”](#providing-warp-preview-feedback) Share feedback, report bugs, and discuss Preview features in the [community Slack](https://go.warp.dev/join-preview). You can also [send feedback directly from the app](/support-and-community/troubleshooting-and-support/sending-us-feedback/#sending-warp-feedback). # Plans and billing > Understand your Warp plan options, how credits work, and how to manage billing settings. Warp offers flexible plans designed for individual developers, teams, and enterprises. Learn about pricing, credits, and billing options. * [**Plans & Pricing**](/support-and-community/plans-and-billing/plans-pricing-refunds/) - Compare plans, pricing tiers, and refund policies * [**Credits**](/support-and-community/plans-and-billing/credits/) - How credits are used and calculated across AI features * [**Add-on Credits**](/support-and-community/plans-and-billing/add-on-credits/) - Purchase additional credits or enable automatic reloads * [**Bring Your Own API Key**](/support-and-community/plans-and-billing/bring-your-own-api-key/) - Connect your own model provider API keys * [**Overages (Legacy)**](/support-and-community/plans-and-billing/overages-legacy/) - Information for users on legacy plans with overages * [**Pricing FAQs**](/support-and-community/plans-and-billing/pricing-faqs/) - Answers to common questions about plans and billing # Add-on Credits > Purchase Add-on Credits to keep using premium AI models after reaching your monthly credit limit. Add-on credits replace Warp’s old [pay-as-you-go Overages](/support-and-community/plans-and-billing/overages-legacy/). They let you continue using premium AI models even after you’ve reached your monthly credit limit — at lower rates and with more control over spending. You can manage and purchase Add-on credits directly in **Settings** > **Billing and usage**. ![Add-on Credits management surface under Settings > Billing and usage.](/_astro/reload-credits.Du_W4Ml7_Z1LbUoj.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ### How do Add-on credits work? [Section titled “How do Add-on credits work?”](#how-do-add-on-credits-work) Add-on credits extend your AI usage beyond the included monthly quota in your plan. Once your plan’s credits are used up, Warp will automatically begin drawing from your available Add-on credits. If you’ve enabled **Auto reload**, new credits will be added automatically and billed based on your selected configuration of monthly spending limit and selected purchase amount. Add-on credits are available for Build, Business, and Enterprise plans (with custom pricing for Enterprise). These credits **roll over across billing cycles** and remain valid for **12 months from the purchase date**. Caution **Legacy plans (Pro, Turbo, Lightspeed) do not support Add-on Credits.** If you’re on a legacy plan, you cannot purchase or auto-reload Add-on Credits. To access Add-on Credits, upgrade to the [Build plan](https://app.warp.dev/upgrade). For additional usage on legacy plans, see [Overages (Legacy)](/support-and-community/plans-and-billing/overages-legacy/). ### Purchasing Add-on credits [Section titled “Purchasing Add-on credits”](#purchasing-add-on-credits) You have two options for purchasing more credits: #### 1. Buy on-demand [Section titled “1. Buy on-demand”](#1-buy-on-demand) You can purchase additional Add-on credits at any time directly within the app under **Settings** > **Billing and usage**. Buying more credits upfront provides a larger discount. The table below shows the available credit denominations, their prices, and corresponding discounts: | Credits | Price (USD) | Price per Credit | Discount | | ------- | ----------- | ---------------- | --------- | | 400 | $10 | $0.025 | Base rate | | 1,000 | $20 | $0.020 | 20% off | | 3,000 | $50 | $0.016 | \~35% off | | 6,500 | $100 | $0.0153 | \~40% off | #### 2. Enable auto-reload [Section titled “2. Enable auto-reload”](#2-enable-auto-reload) Auto reload automatically purchases more credits whenever your balance reaches **100 credits**, ensuring uninterrupted access to premium AI features. By default, **Auto reload is disabled for new subscribers**. When you turn it on, it starts with a **$200 monthly spend limit**, which you can adjust anytime in **Settings** > **Billing and usage**. Auto reload uses the same denominations and discounts as manual purchases. The denomination you select (e.g., 400, 1,000, 3,000, or 6,500 credits) will repeat each time your balance is depleted, up to your monthly spending limit. Larger denominations offer up to \~40% off per credit. Note You can opt in and choose your reload amount when subscribing to a paid plan at [app.warp.dev/upgrade](https://app.warp.dev/upgrade), or change your configuration anytime in **Settings** > **Billing and usage**. Caution Add-on credit auto reload will be enabled by default for some legacy plan users when they transition to the Build plan. Please see more in our [Pricing FAQs](/support-and-community/plans-and-billing/pricing-faqs/#what-happens-to-my-current-plan-pro-turbo-lightspeed). #### **Configuring a monthly spend limit** [Section titled “Configuring a monthly spend limit”](#configuring-a-monthly-spend-limit) Your monthly spend limit sets the maximum amount you can spend on Add-on credits in a single calendar month. This ensures you have full control over your AI usage costs while still allowing flexibility for automatic top-ups when needed, keeping your workflow uninterrupted. * The default limit is $200, but you can increase or decrease it anytime in **Settings** > **Billing and usage**. * **If a credit purchase would exceed your limit, it won’t process** — you’ll need to either raise your limit or choose a smaller Add-on credit amount. * Once your limit is reached, no additional Add-on Credit purchases (manual or automatic) will occur until: * The next calendar month begins, or * You update your limit in settings. Caution Your monthly spend limit is separate from your billing cycle (which determines when your subscription renews).\ \ The limit resets automatically at the start of each calendar month, so you can manage recurring AI usage with predictable spending and clear visibility into your costs. ### Billing and credit usage [Section titled “Billing and credit usage”](#billing-and-credit-usage) When your monthly credit balance renews: 1. Warp first consumes your included monthly plan credits (e.g., Build plan credits). 2. After those are used, Warp continues to draw from any available Add-on Credits. 3. If your Add-on Credits run out and Auto reload is enabled, Warp will automatically purchase more up to your monthly limit. You can track your remaining credits and spending in the credits transparency footer and in **Settings** > **Billing and usage**. #### Teams using Add-on Credits [Section titled “Teams using Add-on Credits”](#teams-using-add-on-credits) For teams on Build or Business plans, **Add-on Credits are shared across all members.** All team credit settings can be managed in `Settings → Billing and usage` by the admin of the team. Team admins can manage: * Enabling or disabling Auto reload * Adjusting monthly spend limits * Choosing Add-on credit increments * Viewing usage and spending breakdowns Each user on the team has their own monthly credit limit, **but any usage beyond that personal quota draws from the shared team credits**. These shared credits are tracked and billed collectively at the team level. For example, if your plan includes 1,500 credits per team member: * If **User A** reaches their 1,500 limit, any further usage will draw from shared Add-on Credits. * If **User B** has only used 200 credits, their remaining quota is unaffected, but User A will consume the team’s shared credits. ### Plan changes and cancellations [Section titled “Plan changes and cancellations”](#plan-changes-and-cancellations) Any purchased Add-on Credits remain in your account and can continue to be used for up to 12 months after purchase, as long as you have an active subscription. If you move to the Free plan, you’ll lose access to any previously purchased Add-on Credits and won’t be able to use them. You also can’t buy additional Add-on Credits until you’re subscribed again. Note All unused Add-on Credits remain valid for 12 months from purchase, as long as you have an active subscription. # Bring Your Own API Key > Warp's paid plans include the ability to bring your own API keys (BYOK) for OpenAI, Anthropic, and Google AI models. Warp supports **Bring Your Own Key (BYOK)** for users who want to connect Warp’s agent to their own Anthropic, OpenAI, or Google API accounts. This lets you use your own API keys to access models directly, giving you full control over model selection, billing, and data routing. See [Model Choice](/agent-platform/capabilities/model-choice/) for a list of supported models. BYOK provides greater flexibility in model access and ensures Warp **never consumes your** [credits](/support-and-community/plans-and-billing/credits/) for requests routed through your own keys. Note BYOK is currently only available on Warp’s paid plans, starting with Build. Learn more about plans and pricing [warp.dev/pricing](https://www.warp.dev/pricing). ## How does BYOK work? [Section titled “How does BYOK work?”](#how-does-byok-work) When you add your own model API keys in Warp, those keys are stored **locally on your device** and are **never synced to the cloud**. Warp uses these API keys to directly route your agent requests to the model provider you’ve configured. Caution BYOK does not apply to [Oz Cloud Agents](/agent-platform/cloud-agents/overview/). Because your API keys are stored locally on your device, they are not available to cloud-hosted agent runs. Cloud agent runs always consume [Warp credits](/support-and-community/plans-and-billing/credits/). When a model is selected using your own key: * Warp **does not consume** any of your [credits](/support-and-community/plans-and-billing/credits/). * Costs are billed directly through your model provider account. * Warp does not retain or store your API key on any of its servers. ![Diagram showing how Warp routes BYOK agent requests directly through your provider API key, bypassing Warp credits.](/_astro/Pricing-Blog-BYOK.q5h2NgFR_Z1SI2Xb.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ## Enabling BYOK [Section titled “Enabling BYOK”](#enabling-byok) To enable and configure your API keys: 1. Open **Settings** and search for `API keys` to jump to the BYOK configuration. 2. Add your API key(s) for Anthropic, OpenAI, or Google. 3. Once added, you’ll see a **key icon** next to supported models in the model picker. Note The BYOK configuration widget doesn’t currently live on a dedicated sidebar subpage; searching from the **Settings** window is the quickest way to reach it. We’re tracking a follow-up to surface it under a persistent sidebar entry. ![Key icon shown next to supported models in the model picker after BYOK API keys are configured.](/_astro/byok-keys.CM7Y_wy4_Z1d1VpD.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) When you explicitly select a model with a key icon, Warp routes requests through your own API key instead of consuming Warp’s credits. ## BYOK usage and billing behavior [Section titled “BYOK usage and billing behavior”](#byok-usage-and-billing-behavior) ### Auto Model [Section titled “Auto Model”](#auto-model) Warp’s **Auto** models dynamically route requests across different models based on context and performance. Because this routing logic depends on Warp’s infrastructure, **Auto always consumes Warp’s credits**, even if you’ve configured your own API keys. To use your own key, select a specific provider model (for example, Claude Sonnet 4.5, GPT-5, or Gemini 2.5 Pro) directly from the model picker with a key icon. ### Credit usage [Section titled “Credit usage”](#credit-usage) When you select a model with the key icon in your model picker, Warp routes the request through your API key. In this case: * No Warp credits are consumed. * The cost of the request is billed directly through your provider account. * Core Agent Mode always **prioritizes BYOK usage** over any available credits. The credit transparency footer will show “0 credits used”, and the `Billing & Usage` page will reflect no deductions from your monthly credit total. **Other AI features in Warp** Some AI-powered features are not affected by BYOK and are included as part of Warp’s paid plans. | Feature | Uses Warp’s credits | Description | | -------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------------- | | [Active AI Recommendations](/agent-platform/local-agents/active-ai/) | No | Always included with Build and higher plans. | | [Codebase Context](/agent-platform/capabilities/codebase-context/) | Yes | Uses Warp’s AI infrastructure and consumes credits. | | [Oz Cloud Agents](/agent-platform/cloud-agents/overview/) | Yes | BYOK keys are stored locally and not available to cloud-hosted runs. | These features will continue to function normally regardless of whether you’ve configured BYOK. ### Failover and fallback behavior [Section titled “Failover and fallback behavior”](#failover-and-fallback-behavior) If Warp detects an issue with your API key, you’ll see a clear error message corresponding with the AI request. If your key: * Is invalid: Warp notifies you and halts the request. * Hits usage or rate limits: Warp will not retry using credits. * You can update or replace your keys anytime by opening **Settings** and searching for `API keys`. **Failover and fallback:** By default, Warp does not fall back to your credits when a BYOK (Bring Your Own Key) request fails. You can choose to enable **Warp credit fallback**. When enabled, if an agent request fails with your BYOK model (for example, due to an API error or quota limit), Warp will automatically route the request to one of Warp’s provided models. Warp always prioritizes your API keys first and only uses Warp credits when necessary. ![Setting to enable Warp credit fallback when a BYOK request fails.](/_astro/fallback.CtVc3TDR_ZuvxIy.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ### Zero Data Retention (ZDR) and BYOK [Section titled “Zero Data Retention (ZDR) and BYOK”](#zero-data-retention-zdr-and-byok) Warp is **SOC 2 compliant** and has **Zero Data Retention (ZDR)** policies with all of its contracted LLM providers. No customer AI data is retained, stored, or used for training by the model providers. However, when you use your own API key: * Data retention policies depend on your provider’s account settings. * Warp cannot enforce ZDR for requests sent through your API keys. * If your Anthropic, OpenAI, or Google account does not have ZDR enabled, your requests may be retained by the provider according to their terms. Warp itself never stores your LLM API keys. ### BYOK on Enterprise and Business plans [Section titled “BYOK on Enterprise and Business plans”](#byok-on-enterprise-and-business-plans) Currently, BYOK is configured at the **user level**, not the team or admin level: * Each team member can add and manage their own API keys locally. * Team admins cannot yet enforce or share API keys across members. * There is currently no organization-level Admin Panel for BYOK management. If your organization has specific needs for managed keys or enterprise-level control, please contact us at [warp.dev/contact-sales](https://warp.dev/contact-sales). # Warp credits and billing > Details on Warp credits and how they are calculated. ### What are Warp credits? [Section titled “What are Warp credits?”](#what-are-warp-credits) Any interaction with Warp’s Agent consumes credits. Credits are primarily based on AI usage — the number of credits a task consumes varies based on the size and complexity of your codebase, the size of the task, the model you’re using, the amount of context the agent needs to gather, and more. Credits also include a small hosting fee, charged only when running agents in the cloud, hosted on Warp’s infrastructure. For details on cloud agent credits, see [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits). Each interaction consumes **at least one credit**, though more complex interactions may use **multiple credits**. Because of factors such as codebase size, model choice, number of tool calls, and the nature of LLMs, credit usage is **non-deterministic** — two similar prompts can still use a different number of credits. Note For a general breakdown of what factors contribute to how many credits are consumed, please refer to: [How are Warp credits calculated?](/support-and-community/plans-and-billing/credits/#how-are-warp-credits-calculated) Since there’s no exact formula for predicting usage, we recommend building an intuitive understanding by experimenting with different prompts, models, and tracking how many credits they consume. **Tracking your credit usage** In an Agent conversation, a **turn** represents a single exchange (a response from the LLM). To see how many credits a turn consumed, hover over the **credit count chip** at the bottom of the Agent’s response: ![The conversation usage footer shows how many credits a conversation has consumed, and breaks down the usage by credits, tool calls, context window, files changed, diffs applied, and more.](/_astro/inline-credit-usage-footer.CwfMU23t_1kOyjX.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Conversation usage footer. Note You can view your total credit usage, along with other billing details, in **Settings** > **Billing and usage**. #### Credit **limits and billing** [Section titled “Credit limits and billing”](#credit-limits-and-billing) * **Seat-level allocation**: On team plans, credit limits apply per seat — each team member has their own allowance. Individual users (not on a team) also have their own credit allocation. * **Cloud Agent Credits**: Individual users can run cloud agents via CLI/API using their normal Warp credits, [Cloud Agent Credits](/support-and-community/plans-and-billing/credits/#cloud-agent-credits), or a Build plan with available credits. Integrations (Slack, Linear) require team membership. * **Hitting the credit limits**: Once you hit your monthly credit limit, your access will depend on your plan. On the Free plan, AI access stops until your next billing cycle. On paid plans, you can continue using AI with usage-based billing via [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/). #### **Other features that use credits** [Section titled “Other features that use credits”](#other-features-that-use-credits) In addition to direct Agent conversations, the following features also consume credits: * [Generate](/agent-platform/local-agents/overview/) helps you look up commands and suggestions as you type. As you refine your input, multiple credits may be used before you select a final suggestion. * [AI Autofill in Workflows](/knowledge-and-collaboration/warp-drive/workflows/#ai-autofill) counts as a credit each time it is run. Tip Regular shell commands in Warp do not consume or count towards credits. ### How are Warp credits calculated? [Section titled “How are Warp credits calculated?”](#how-are-warp-credits-calculated) A **credit** in Warp is a unit of work representing the total processing required to complete an interaction with an Agent. It is **not** the same as “one user message” — instead, it scales with the number of tokens processed during the interaction. In short: **the more tokens used, the more credits consumed**. Several factors influence how many credits are counted for a single interaction: #### **1. The LLM model used** [Section titled “1. The LLM model used”](#1-the-llm-model-used) Generally, smaller, faster models typically consume fewer credits than larger, reasoning-based models. For example, **Claude Opus 4.6** and **Claude Opus 4.5** tend to consume the most tokens and credits in Warp, followed by **Claude Sonnet 4.6, GPT-5.4, GPT-5.3 Codex, Gemini 3 Pro**, and others in roughly that order. This generally correlates with model pricing as well. Note **Tip**: If your task doesn’t require deep reasoning, planning, or multi-step problem solving, choose a more lightweight model to reduce credit usage. #### 2. Tool calls triggered by the Agent [Section titled “2. Tool calls triggered by the Agent”](#2-tool-calls-triggered-by-the-agent) Warp’s Agents make a variety of tool calls, including: * Searching for files (grep) * Retrieving and reading files * Making and applying code diffs * Gathering web or documentation context * Running other utilities Some prompts require only a couple of tool calls, while others may trigger many — especially if the Agent needs to explore your development environment, navigate a large codebase, or apply complex changes. **More tool calls = more credits**. #### 3. Task complexity and number of steps [Section titled “3. Task complexity and number of steps”](#3-task-complexity-and-number-of-steps) Some tasks are straightforward and may require only a single quick response, without much thinking or reasoning. Others can involve multiple stages—such as planning, generating intermediate outputs, verifying results, applying changes, and self-correcting—each of which can add to the credits count. Note **Tip**: Keep tasks that you give to the Agent well-scoped, work incrementally, and break large changes into smaller, contained steps. #### 4. Amount of context passed to the model [Section titled “4. Amount of context passed to the model”](#4-amount-of-context-passed-to-the-model) Prompts that include large amounts of context (such as [attached blocks](/agent-platform/local-agents/agent-context/blocks-as-context/), long user query messages, etc.) or file attachments like [images](/agent-platform/local-agents/agent-context/images-as-context/) may also increase the number of credits used due to increased token consumption. Note **Tip**: When sharing logs, code, or other large pieces of content, attach only the most relevant portions instead of full outputs. #### 5. Prompt caching (hits and misses) [Section titled “5. Prompt caching (hits and misses)”](#5-prompt-caching-hits-and-misses) Many model prompts include repeated content, like system instructions: * **Cache hits**: if the model provider can match a prefix or a part of the prompt from a past request, it can reuse results from the cache, reducing both tokens consumed and latency. * **Cache misses**: if no match is found, the full prompt may be processed again, which can increase credit consumption. Because cache results depend on model provider behavior and timing, two similar prompts may still have different credit counts, depending on when you run the commands. Note **Tip**: Work in a continuous session when possible to improve cache hit rates. These are the most common factors affecting credit usage, though there are others. Understanding them can help you manage your credits more efficiently and get the most from your plan. ### Cloud Agent Credits [Section titled “Cloud Agent Credits”](#cloud-agent-credits) Cloud Agent Credits are a type of credit consumed only by cloud agent runs — AI requests that run on Warp-hosted compute. #### Eligible for Cloud Agent Credits [Section titled “Eligible for Cloud Agent Credits”](#eligible-for-cloud-agent-credits) The following scenarios use Cloud Agent Credits: * **First-party integrations** — Running agents through Slack or Linear integrations * **Cloud agent runs** — Using `oz agent run-cloud` via the CLI * **Oz API** — Running agents through Warp’s Oz API * **Cloud Mode** — Running an agent from Cloud Mode in the Warp app #### Not eligible for Cloud Agent Credits [Section titled “Not eligible for Cloud Agent Credits”](#not-eligible-for-cloud-agent-credits) The following scenarios do **not** use Cloud Agent Credits: * **Local agent runs** — Using `oz agent run` on your local machine * **Self-hosted compute** — Using `oz agent run` on GitHub Actions, CI/CD pipelines, or other self-hosted infrastructure # Overages (Legacy) > Pay-as-you-go access to premium AI models after reaching your monthly credits quota on Warps plans. Warp offers usage-based pricing for Subscribers, allowing continued access to premium AI models even after reaching the monthly credits limit included in the plan (billed at $0.04 per additional credit). You can manage usage-based pricing directly in Warp under **Settings** > **Billing and usage**. ![Billing and usage tab in settings, where admins can manage premium model usage overages](/_astro/overages-settings.lsCK8_6t_ZxttuQ.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Billing and usage settings. ### Enabling overages [Section titled “Enabling overages”](#enabling-overages) **Team admins** can enable or disable “premium model overages” and set a monthly spending limit from the settings dashboard. Individual subscribers can manage their own overage settings directly in the settings dashboard. Note Usage-based pricing only applies after you’ve reached the credit limit on your plan — you won’t be charged for any overages until that point, even if overages are enabled. ### How overages work [Section titled “How overages work”](#how-overages-work) Overages are managed **at the team level**, even if your team only has one member (i.e. individual users). Once overages are enabled, any team member who reaches their monthly credit quota can continue to have access to premium models — with **additional usage billed at cost ($0.04 per credit)**. Each user on the team has their **own credit limit**, but only **credits made beyond that personal quota** are considered overages. These charges are tracked and billed **collectively** at the team level. For example, if your plan includes 10,000 credits per team member: * If **User A** reaches their 10,000 limit, any further usage by them counts towards overages. * If **User B** has only used 2,000 credits, they still have 8,000 included credits left. * User A’s overages **do not** consume User B’s remaining quota. Overages are **billed monthly**, or when your team accumulates **$20 worth of charges**, whichever comes first. ### Plan upgrades and cancellations [Section titled “Plan upgrades and cancellations”](#plan-upgrades-and-cancellations) If you upgrade from lower to a higher plan, your monthly credit limit will update immediately to match the higher plan. (For exact limits, see our [pricing page](https://www.warp.dev/pricing).) However, **any overages incurred while on the lower plan will still be billed** — upgrading does not retroactively remove or reduce existing overage charges. If you cancel your subscription, you’ll retain access to premium features until the end of your current billing period. Any usage-based overages accrued during that period will be charged at the time your plan ends.\\ # Plans, pricing, and refunds > Learn about Warp's plans and pricing tiers. Get started for free. ## Warp plans and pricing [Section titled “Warp plans and pricing”](#warp-plans-and-pricing) Warp offers flexible, pay-as-you-go plans designed for individual developers, teams, and enterprises. You only pay for what you use—each plan includes a monthly allowance of credits that power features such as code generation, debugging, and multi-agent workflows. Note Visit [warp.dev/pricing](https://warp.dev/pricing) to see the latest plans and what’s included in each offering. **Explore the following sections for more details:** * [Credits](/support-and-community/plans-and-billing/credits/) — learn how credits are used and calculated across AI features. * [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) — purchase additional credits or enable automatic reloads at discounted rates. * [Bring Your Own API Key](/support-and-community/plans-and-billing/bring-your-own-api-key/) — connect your own model provider API keys for custom usage and billing. * [Overages (Legacy)](/support-and-community/plans-and-billing/overages-legacy/) — information for users on legacy plans with overages enabled. * [Pricing FAQs](/support-and-community/plans-and-billing/pricing-faqs/) — answers to common questions about plans, billing, and usage. Don’t have Warp yet? [Download Warp](https://warp.dev/download) and get started for free today. ### Warp’s refund policies [Section titled “Warp’s refund policies”](#warps-refund-policies) Please review the details of our refund policies below. To request a refund, email [**billing@warp.dev**](mailto:billing@warp.dev) with information about your situation — the more context you provide, the faster we can resolve your request. Caution In case of product defect, we require [Conversation ID](/support-and-community/troubleshooting-and-support/sending-us-feedback/#gathering-ai-conversation-id), [Logs](/support-and-community/troubleshooting-and-support/sending-us-feedback/#gathering-warp-logs), and “[Help improve Warp](/support-and-community/privacy-and-security/privacy/#how-to-disable-telemetry-and-crash-reporting)” must be enabled in order for us to identify the issue before we can provide any refunds or credits. #### Subscription refund policy [Section titled “Subscription refund policy”](#subscription-refund-policy) **Monthly plans** If you signed up for a monthly Warp subscription by mistake, we can issue a full refund if you cancel or downgrade within 24 hours of being charged and no credits have been used during that billing cycle. After 24 hours, or if credits have been used, we will cancel your subscription so that no future charges occur, and you can continue to use your plan through the end of the current billing cycle. **Annual plans** If you signed up for an annual Warp subscription by mistake, we can issue a full refund if you cancel or downgrade within 15 days of being charged and no credits have been used during that billing period. After 15 days, we will refund you for the remaining full months on your subscription, excluding the first month. #### Add-on Credits | Overages refund policy [Section titled “Add-on Credits | Overages refund policy”](#add-on-credits--overages-refund-policy) * If you purchased [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) by mistake, you can receive a refund **as long as none of the credits have been used**. Warp cannot refund Add-on Credits if there has been any usage. Add-on Credits remain available for up to **12 months** from the date of purchase, as long as you have an active subscription — if you move to the Free plan, you’ll lose access to any remaining Add-on Credits. * All [Overages (Legacy)](/support-and-community/plans-and-billing/overages-legacy/) credits are **non-refundable**. Because Overages are charges for credits that were already consumed, we cannot refund resources that have already been used. Caution Warp does not offer a formal guaranteed uptime Service Level Agreement (SLA). Live incidents can be monitored on our [**Status Page**](https://status.warp.dev/), and open issues are tracked on our [**GitHub Issues**](https://github.com/warpdotdev/Warp/issues). # Pricing and billing FAQs > Frequently asked questions about upgrading, managing billing, refunds, and invoicing with Warp's paid plans. ### How can I upgrade and subscribe to a Warp plan? [Section titled “How can I upgrade and subscribe to a Warp plan?”](#how-can-i-upgrade-and-subscribe-to-a-warp-plan) All paid Warp plans come with higher monthly credit limits than the Free plan. When you upgrade from Free to a paid plan, your credit usage resets. If you’re switching between paid plans, any AI usage you’ve already accumulated will carry over. You can subscribe to a Warp paid plan as an individual or as part of a team. To upgrade: * In the app: Go to **Settings** > **Billing and usage**, then click the Upgrade link * Online: Visit [warp.dev/pricing](https://www.warp.dev/pricing) After entering your payment details, you’ll receive an invoice and confirmation via email. ### How can I get the most out of my Warp plan? [Section titled “How can I get the most out of my Warp plan?”](#how-can-i-get-the-most-out-of-my-warp-plan) Caution Warp’s legacy paid plans included Pro, Turbo, and Lightspeed. After **Oct 30, 2025**, we have rolled out the new Build plan to replace them. Existing subscribers will start to roll over onto the Build plan starting **Dec 1st, 2025**. For questions related to the new pricing changes, please refer to [Warp’s pricing change FAQs](/support-and-community/plans-and-billing/pricing-faqs/#warps-pricing-change-faqs-oct-30-2025). To see more details on the latest plan, please visit [**warp.dev/pricing**](https://www.warp.dev/pricing). Warp’s plans are designed for developers who rely on AI to code, debug, and move faster with their team. * **Build**, one usage-based plan with a set of credits, ability to Bring Your Own API Key (BYOK), and access to [Add-on credits](/support-and-community/plans-and-billing/add-on-credits/) with volume-based discounts. See more on [Bring Your Own API Key](/support-and-community/plans-and-billing/bring-your-own-api-key/). * **Business** includes everything in Build, with advanced features like automatically enforced team-wide Zero Data Retention, SAML-based SSO, and support for teams up to 50 seats. Legacy plans: * **Pro** included higher credit limits than the Free plan, support for larger codebases with [Codebase Context](/agent-platform/capabilities/codebase-context/), and access to premium models with optional pay-as-you-go overages. * **Turbo** included even higher credit limits, larger Codebase Context indexing, and the option to pay for additional usage beyond included credits via [Overages (Legacy)](/support-and-community/plans-and-billing/overages-legacy/). Add-on Credits were not available on this plan. * **Pro** included higher credit limits than the Free plan, support for larger codebases with [Codebase Context](/agent-platform/capabilities/codebase-context/), and access to premium models with optional pay-as-you-go [Overages (Legacy)](/support-and-community/plans-and-billing/overages-legacy/). * **Turbo** included even higher credit limits, larger Codebase Context indexing, and the option to pay for additional usage beyond included credits via [Overages (Legacy)](/support-and-community/plans-and-billing/overages-legacy/). Add-on Credits were not available on this plan. * **Lightspeed** was Warp’s most powerful legacy plan, offering the highest credit limits, expanded codebase indexing, access to top-tier models, and pay-as-you-go [Overages (Legacy)](/support-and-community/plans-and-billing/overages-legacy/) so you could keep working without interruption. For the most up-to-date feature and usage details, visit [**warp.dev/pricing**](https://www.warp.dev/pricing). ### How can I subscribe to a Warp Enterprise plan? [Section titled “How can I subscribe to a Warp Enterprise plan?”](#how-can-i-subscribe-to-a-warp-enterprise-plan) Warp offers two options for larger teams and organizations: * **Business Plan**: Supports up to 50 seats and is available for immediate upgrade. It includes automatically enforced team-wide Zero Data Retention by default and admin-controlled SAML-based SSO. * **Enterprise Plan**: Offers custom pricing, credit limits, and terms. Along with support for larger engineering orgs or teams with advanced security, compliance, or support needs. Tip If you’d like to explore Enterprise, [contact our sales team](https://warp.dev/contact-sales) and someone from Warp will follow up. ### What counts as a team member and how does billing work for members? [Section titled “What counts as a team member and how does billing work for members?”](#what-counts-as-a-team-member-and-how-does-billing-work-for-members) In Warp, a *team member* is any seat with access to your Team — including the shared Warp Drive, Notebooks, Workflows, and other team resources. All plans allow you to invite unlimited users, but to unlock higher limits and advanced features, you’ll need to upgrade your team to a plan. Upgrading applies to your entire team, including your own account and all active members. On the Free plan, you can share a limited number of Notebooks and Workflows with other Free users. If your team exceeds that limit, you’ll be prompted to [upgrade to a plan](https://app.warp.dev/upgrade).\ \ Once you upgrade, you’ll receive email notifications as team members accept invites. Billing is **prorated**, meaning you’re only charged for the days each member has access during your billing cycle. If a member leaves mid-cycle, Warp automatically applies a credit for the unused time to your next invoice. **There are differences in how members are billed based on your payment schedule:** * **Monthly plans**: New members are billed immediately for the remaining time in the month. * **Annual plans**: New members are billed immediately for the remaining time in the year. For example, if a member joins your monthly plan halfway through the month, you will be charged just half of the monthly fee ($25.00 out of $50). Similarly, if a member joins with four months remaining in an annual plan, you will be charged for those four months only, which amounts to $160 (4/12 of the annual $480). If a member leaves part way through the billing cycle, Warp will issue a prorated credit based on the unused portion of their membership. This credit is applied to your team’s next invoice, regardless of whether you’re on a monthly or annual plan. Caution All members of the team will have the same subscription plan, you can’t mix and match plans for each member of a team. To have different plans, you currently must have separate teams. ### What is the value of joining or creating a team on Warp? [Section titled “What is the value of joining or creating a team on Warp?”](#what-is-the-value-of-joining-or-creating-a-team-on-warp) Team members have access to your shared [Warp Drive](/knowledge-and-collaboration/warp-drive/) objects and limited access to Warp’s collaboration features, including Session Sharing and Warp Drive storage. **Upgrading the team to a plan unlocks powerful collaboration and knowledge-sharing tools to help your team move faster, together:** * Create unlimited [Notebooks](/knowledge-and-collaboration/warp-drive/notebooks/) and [Workflows](/knowledge-and-collaboration/warp-drive/workflows/) in Warp Drive to organize and share knowledge across your team. * Use Unlimited [Session Sharing](/knowledge-and-collaboration/session-sharing/) to collaborate in real time through live, shared terminal sessions. ### My co-workers are using Warp but we’re not on a Team together yet. How does billing work? [Section titled “My co-workers are using Warp but we’re not on a Team together yet. How does billing work?”](#my-co-workers-are-using-warp-but-were-not-on-a-team-together-yet-how-does-billing-work) Individual users with either personal or work email domains may continue to use Warp independently without incurring billing. The benefit of joining together on a Warp Team is that you get access to a shared Team Drive and collaboration features. When you’re ready to use Warp more collaboratively, we suggest you nominate an Admin to [create a Team](/knowledge-and-collaboration/teams/) and invite members to join. When your Team exceeds the Warp Drive limits, you will be prompted to upgrade to a plan. ### How does usage work if logged into the same account on multiple devices? [Section titled “How does usage work if logged into the same account on multiple devices?”](#how-does-usage-work-if-logged-into-the-same-account-on-multiple-devices) When you use the account to sign into Warp on different devices, for example Linux on one computer and Windows on another, your usage of metered features like credits is tracked at the account level, not the device level. You can use your Warp account on multiple personal computers. Warp is designed to provide a consistent experience across devices. When you log in with the same account on different computers, your settings and preferences can be synced through the [Settings Sync](/terminal/more-features/settings-sync/) feature. ### What happens when I downgrade during a billing cycle? [Section titled “What happens when I downgrade during a billing cycle?”](#what-happens-when-i-downgrade-during-a-billing-cycle) Caution Note this only applies when switching between legacy plans (Pro, Turbo, Lightspeed, or the Old Business) or switching the new plans (Build, New Business). When switching between legacy to new plans, the change is immediate, prorated, and the credits are reset. See more in [What happens when I change from my legacy plan to the new Build or Business plans?](/support-and-community/plans-and-billing/pricing-faqs/#what-happens-when-i-change-from-my-legacy-plan-to-the-new-build-or-business-plans). The subscription will downgrade to the lower plan limits at the end of the billing cycle. If you’re switching between paid plans, any AI usage you’ve already accumulated will carry over.\ \ You can downgrade at any point throughout your subscription through the billing portal by going to **Settings** > **Billing and usage** > **Manage billing**. ### What happens when I cancel during a billing cycle? [Section titled “What happens when I cancel during a billing cycle?”](#what-happens-when-i-cancel-during-a-billing-cycle) You can cancel at any point throughout your subscription through the billing portal by going to **Settings** > **Billing and usage** > **Manage billing**. The subscription will be canceled at the **end of your billing cycle**, monthly or yearly. **You can continue to use your Warp paid plan features until the cycle end date**. Any additional team members added to your team will be invoiced at the end of your billing cycle. ### What happens if I upgrade from monthly to annual billing? [Section titled “What happens if I upgrade from monthly to annual billing?”](#what-happens-if-i-upgrade-from-monthly-to-annual-billing) When upgrading from a monthly to annual billing cycle the billing is prorated, meaning you only pay for the annual portion of the year you haven’t paid for yet. You will be billed for the remaining part of the billing year with the discounted rate. You can upgrade at any point throughout your subscription through the billing portal by going to **Settings** > **Billing and usage** > **Manage billing**. ### What happens to unused credits? [Section titled “What happens to unused credits?”](#what-happens-to-unused-credits) Unused credits do not rollover to the next cycle and can’t be transferred to other accounts. You see when your credits will reset in the **Settings** > **Billing and usage** menu. ### What happens if my payment fails? [Section titled “What happens if my payment fails?”](#what-happens-if-my-payment-fails) If a payment fails, you will receive an email from Stripe and your Warp Team Settings will show a past-due alert. Certain paid plan features and the ability to invite new members will be locked down while your Team is in a past-due state. Paying the most recent invoice through the billing portal by going to **Settings** > **Billing and usage** > **Manage billing** will fully re-enable your paid plan features. ### What counts as a credit? [Section titled “What counts as a credit?”](#what-counts-as-a-credit) Each time you submit a prompt in Warp, whether to generate code, suggest a command, or accomplish a task, you initiate an interaction with the Agent. Please see more details in our [credits](/support-and-community/plans-and-billing/credits/) page. ### What counts as an AI token? [Section titled “What counts as an AI token?”](#what-counts-as-an-ai-token) Tokens are chunks of text, such as words, parts of code, or characters, that large language models (LLMs) break down to analyze and generate responses. LLMs have a maximum number of tokens they can process at once. Credits and suggestions are not the same as tokens, which are limited separately regardless of which plan you’re on. Note Warp now abstracts away token usage, so you don’t need to manage or track it directly. You only need to monitor your **credit usage**, which is what’s measured against your plan limits. If you’re curious, you can read the [OpenAI article on tokens](https://help.openai.com/en/articles/4936856-understanding-tokens), or refer to the pricing page for plan-level credit allocations. If you reach your monthly credit limits on a paid plan, premium models will be temporarily disabled until your quota resets at the start of your next billing cycle. If you’d like to continue using premium models beyond your included quota, purchase [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) in **Settings** > **Billing and usage** (users still on legacy Pro, Turbo, or Lightspeed plans continue to use [Overages (Legacy)](/support-and-community/plans-and-billing/overages-legacy/) until their first renewal after December 1, 2025). ### How often do my credits reset? [Section titled “How often do my credits reset?”](#how-often-do-my-credits-reset) Allotted credits refill every 30 days from your signup date. When you upgrade to a [paid plan](https://www.warp.dev/pricing), you will be given more credits immediately. You can follow along with your refill period by referencing **Settings** > **Billing and usage**. Alternatively, purchase [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/), or enable auto reload with a monthly spend limit, to continue using premium models beyond your included quota. Users still on legacy Pro, Turbo, or Lightspeed plans continue to use [Overages (Legacy)](/support-and-community/plans-and-billing/overages-legacy/) until their first renewal after December 1, 2025. Note Unused credits do not rollover to the next cycle and can’t be transferred to other accounts. ### Can I use a Free plan if I’m a developer at a large company or organization? [Section titled “Can I use a Free plan if I’m a developer at a large company or organization?”](#can-i-use-a-free-plan-if-im-a-developer-at-a-large-company-or-organization) Yes. Developers at any company size are welcome to use Warp’s Free plan. If you need access to advanced collaboration features or higher limits, you may benefit from upgrading to a plan, but Warp does not require large organizations to upgrade. ### Are there any Warp discounts for students, non-profits, or open-source teams? [Section titled “Are there any Warp discounts for students, non-profits, or open-source teams?”](#are-there-any-warp-discounts-for-students-non-profits-or-open-source-teams) Warp doesn’t currently offer discounts for students or non-profits. We recommend exploring the Free plan, which includes all core terminal features and is a great starting point for individual or community use. For open source teams, two paths are available: * The [Oz Open Source Partnership](/support-and-community/community/open-source-partnership/) program offers free Oz agent credits to high-impact open source projects. * Warp’s client itself is open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE), so you can build, run, and contribute to it directly. See [Contributing to Warp](/support-and-community/community/contributing/) for the flow. ### Where is Warp Drive data for my team stored? [Section titled “Where is Warp Drive data for my team stored?”](#where-is-warp-drive-data-for-my-team-stored) Warp Drive data is securely stored on Google Cloud Platform servers located in the United States. All data is encrypted in transit and at rest. For more details, please [visit the Security Overview](https://www.warp.dev/legal/security) or contact . ### What happened to the Lite model? [Section titled “What happened to the Lite model?”](#what-happened-to-the-lite-model) Over time, the Lite model—originally designed as a fallback when premium models ran out—began to deliver inconsistent results, especially for users running complex, multi-step prompts. For credit-efficient usage, we encourage you to try our new **Auto (cost-efficiency) model**, which automatically selects the optimal model based on task complexity to help extend your credits. To continue AI usage please either add [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) or consider [using your own API key](/support-and-community/plans-and-billing/bring-your-own-api-key/). If you have any questions or feedback, please connect with us in our [community Slack](/support-and-community/#sending-warp-feedback). ### What payment options are available for Warp’s self-service plans? [Section titled “What payment options are available for Warp’s self-service plans?”](#what-payment-options-are-available-for-warps-self-service-plans) Warp uses Stripe as our payments processor and currently accepts the following payment methods: credit card, debit card, Link, Apple Pay, Google Pay. We don’t support ACH, checks, PayPal, cryptocurrency, or other alternative payment methods at this time. Note To checkout with Apple Pay, use the Safari browser on an Apple device.\ To checkout with Google Pay, use Chrome, make sure you’re logged into your Google Wallet account in the browser, and that “Save and fill payment methods” is enabled in the browser settings. ### How do I cancel my subscription? [Section titled “How do I cancel my subscription?”](#how-do-i-cancel-my-subscription) You can cancel at any point throughout your subscription through the billing portal by going to **Settings** > **Billing and usage** > **Manage billing**. Cancelled subscriptions will remain active until the end of the billing cycle. ### How do I get a refund? [Section titled “How do I get a refund?”](#how-do-i-get-a-refund) For monthly subscriptions, we can issue a full refund if you cancel within 24 hours of being charged and no credits have been used. For annual subscriptions, we can issue a full refund within 15 days if no credits have been used, or a prorated refund for remaining months after that. Please see [Warp’s Refund Policy](/support-and-community/plans-and-billing/plans-pricing-refunds/#warps-refund-policies) for full details and exceptions. ### Why doesn’t my promo code work or why was it disabled? [Section titled “Why doesn’t my promo code work or why was it disabled?”](#why-doesnt-my-promo-code-work-or-why-was-it-disabled) Warp’s promotions are a way to try Warp before committing to a subscription, not get unlimited free or inexpensive AI. To prevent abuse, we’re limiting promotion codes to first-time redemptions only, so each account can only use one promotion code.\ \ In addition certain promo codes we issue are only valid for specific plans (not all plans) and expire after a certain time. If you apply a promo code for a certain plan, then upgrade to another plan, the promotion doesn’t transfer to the new plan so you will end up paying full price for the upgrade. Caution Warp reserves the right to disable any promotion codes at any time, and cancel the associated subscriptions if we find that the code was being abused. ### How can I subscribe to Warp as tax exempt? [Section titled “How can I subscribe to Warp as tax exempt?”](#how-can-i-subscribe-to-warp-as-tax-exempt) Warp does allow tax exempt organizations to subscribe, but there are some additional steps that you need to take. 1. Create a Warp account, login, and go to the [upgrade page](https://app.warp.dev/upgrade), and select a plan, but **don’t checkout or pay yet.** This will only setup your billing account in the system that will be used in the later steps. 2. E-mail with your proof of your organization tax exempt status and your Warp account email. 3. Warp’s team will verify your tax exempt status and will change your account to tax exempt. 4. Finally, subscribe to your plan of choice. You will see no taxes applied to the bill. ### Why can’t I subscribe to Warp? [Section titled “Why can’t I subscribe to Warp?”](#why-cant-i-subscribe-to-warp) There are certain prohibited and restricted businesses in which Stripe and major credit card networks will not process payments. For the most updated information, please see the full list [here](https://stripe.com/legal/restricted-businesses). ### I have a question and need help. How can I reach a human at Warp? [Section titled “I have a question and need help. How can I reach a human at Warp?”](#i-have-a-question-and-need-help-how-can-i-reach-a-human-at-warp) The team at Warp is standing by and ready to help. For subscribers technical issues email , for subscribers billing issues email , for security concerns email , and for questions about privacy email . *** ### Warp’s pricing change FAQs (Oct 30, 2025) [Section titled “Warp’s pricing change FAQs (Oct 30, 2025)”](#warps-pricing-change-faqs-oct-30-2025) For more details, see this blog post on [Warp’s plan changes](https://www.warp.dev/blog/warp-new-pricing-flexibility-byok). #### How do I change from my current plan to the new Build or Business plan? [Section titled “How do I change from my current plan to the new Build or Business plan?”](#how-do-i-change-from-my-current-plan-to-the-new-build-or-business-plan) You can switch to the new Warp Build or Business plan anytime from **Settings** > **Billing and usage** > **Manage billing** > **Update subscription** in the Warp app or at [app.warp.dev/upgrade](https://app.warp.dev/upgrade). Select Change plan, then choose the plan that fits your needs. If you take no action, your Pro, Turbo, Lightspeed, or legacy Business plan will automatically move to the new structure on your first renewal after **December 1, 2025**. You’ll receive an email before your renewal with details to make the transition easier. #### What happens when I change from my legacy plan to the new Build or Business plans? [Section titled “What happens when I change from my legacy plan to the new Build or Business plans?”](#what-happens-when-i-change-from-my-legacy-plan-to-the-new-build-or-business-plans) If you move from Warp’s legacy Pro, Turbo, Lightspeed, or old Business plans to the new Build or Business plans: * You’ll receive a prorated credit balance on Stripe for your current plan, based on how far you are into your billing cycle. This balance can be applied toward monthly Build fees or any Add-on Credits you purchase. * You can view your credit balance by going to **Settings** > **Billing and usage** > **Manage Account**. You can also view your credit balance on the Stripe invoice that was sent when your plan changed to Build or Business. * Your credit balance will reset to **0/1,500** when you switch to the Build or Business plan. If you switched immediately after the rollout, before a subsequent update was applied, we’ll retroactively reset your credit balance to 0/1,500. * You should see this reflected in **Settings** > **Billing and usage**. If you experience any issues, please contact us at ****. Note We recommend you use all the credits on your legacy plan before you switch over to the new plans. This way you can make best use of them before they are reset to the new plan limits. Caution Add-on credit auto reload will be enabled by default for some legacy plan users when they transition to the Build plan. Please see more in our [Pricing FAQs](/support-and-community/plans-and-billing/pricing-faqs/#what-happens-to-my-current-plan-pro-turbo-lightspeed). #### What should I keep in mind about this change? [Section titled “What should I keep in mind about this change?”](#what-should-i-keep-in-mind-about-this-change) * **BYOK and Add-on credits**: These are only available on the new Build and Business plans. Switching early gives you immediate access. * **Pricing differences**: Depending on your usage, your monthly cost may increase or decrease. You’ll now pay based on what you actually use. * **Renewal timing**: You’ll stay on your current plan until your renewal date after December 1. No interruptions to service will occur. * **Transparency**: You can view your credit balance, monthly spend limit, and Add-on settings anytime in **Settings** > **Billing and usage**. For full details, see [warp.dev/pricing](https://www.warp.dev/pricing) or reach out to if you have questions about your transition. #### For existing paid users: when will the new pricing take effect for my account? [Section titled “For existing paid users: when will the new pricing take effect for my account?”](#for-existing-paid-users-when-will-the-new-pricing-take-effect-for-my-account) For **new customers**, the new pricing and packaging take effect immediately on Oct 30, 2025. For **existing monthly subscribers**, changes will apply on your first renewal after **December 1, 2025**; most likely during the month of December 2025. For **annual subscribers**, the new plan and pricing will take effect on your next renewal after December 1, 2025. If you have any questions, please reach out to us at ****. #### **What happens to my current plan (Pro, Turbo, Lightspeed, Business)?** [Section titled “What happens to my current plan (Pro, Turbo, Lightspeed, Business)?”](#what-happens-to-my-current-plan-pro-turbo-lightspeed-business) You will retain your current plan and credits until the first renewal after December 1, 2025. At renewal, all current Pro, Turbo, Lightspeed, and Business plans will transition to the new Warp Build and Business plans. The Build and new Business plans include 1,500 monthly credits, the ability to purchase [Add-on Credits](/support-and-community/plans-and-billing/add-on-credits/) that roll over for 12 months, and the ability to bring your own API key. Learn more at [warp.dev/pricing](https://www.warp.dev/pricing). In addition, [Add-on credit auto reload](/support-and-community/plans-and-billing/add-on-credits/#id-2.-enable-auto-reload) will be automatically enabled for some legacy plan users in the following ways (but can be opted out of or modified at any time). Our goal is to maintain the same maximum monthly spend in line with your legacy plan subscription plus any Overages: * **Pro:** Will transition to the Build plan. Auto-reload ***will not***** be enabled by default**. * **Turbo:** Will transition to the Build plan. Auto-reload ***will***** be enabled by default**. It will default to $30 auto-reload monthly spending limit for monthly subscribers and $22 for yearly subscribers. A handful of Turbo subscribers received a bulk discount for teams of 3 or more—please check your email for details on the default spending limits for your account. * **Lightspeed:** Will transition to the Build plan. Auto-reload ***will***** be enabled by default**. It will default to $205 auto-reload monthly spending limit for monthly subscribers and $182 for yearly subscribers. * **Business:** Will transition to the new Business plan. Auto-reload ***will***** be enabled by default**. It will default to $10 auto-reload monthly spending limit for both monthly and yearly subscribers. In any of the above cases, if Overages were enabled, we will set the monthly auto-reload spending limit equal to your Overage spending limit plus any of the amounts listed above.\ \ If your total auto-reload monthly spend limit is $80 or above, we will set the Add-on credit denomination to $20 / 1000 credits by default. If your total auto reload monthly spending limit is below $80, we will set the Add-on credit denomination to $10 / 400 credits by default. #### Can I continue to use Warp as my primary terminal? [Section titled “Can I continue to use Warp as my primary terminal?”](#can-i-continue-to-use-warp-as-my-primary-terminal) Yes, the terminal features of Warp will continue to be free to use for developers. Learn more at [Plans And Pricing](/support-and-community/plans-and-billing/plans-pricing-refunds/). #### How are Add-on credits different from overages? [Section titled “How are Add-on credits different from overages?”](#how-are-add-on-credits-different-from-overages) Add-on credits replace overages with a simpler, prepaid system. They’re up to \~40% cheaper than the old overage rates, roll over month-to-month, and remain valid for 12 months. They also come with Warp’s full SOC 2 / Zero Data Retention protection. #### Do credits rollover? [Section titled “Do credits rollover?”](#do-credits-rollover) For existing users on legacy plans, plan credits on Pro, Turbo, and Lightspeed do not rollover. For the Build plan, credits will not rollover but Add-on credits will rollover and be valid for 12 months from the date of purchase. #### Can I purchase Add-on Credits on legacy plans (Pro, Turbo, Lightspeed)? [Section titled “Can I purchase Add-on Credits on legacy plans (Pro, Turbo, Lightspeed)?”](#can-i-purchase-add-on-credits-on-legacy-plans-pro-turbo-lightspeed) No. Add-on Credits (including auto-reload) are only available on the Build, Business, and Enterprise plans. If you attempt to purchase Add-on Credits on a legacy plan, the purchase will not go through. To access Add-on Credits, switch to the Build plan at any time from **Settings** > **Billing and usage** or at [app.warp.dev/upgrade](https://app.warp.dev/upgrade). If you need additional usage while on a legacy plan, you can use [Overages (Legacy)](/support-and-community/plans-and-billing/overages-legacy/) instead. #### Can I bring my own key on legacy plans (Pro, Turbo, Lightspeed)? [Section titled “Can I bring my own key on legacy plans (Pro, Turbo, Lightspeed)?”](#can-i-bring-my-own-key-on-legacy-plans-pro-turbo-lightspeed) No, Bring-your-own API key for OpenAI, Anthropic, and Gemini is only available to users on the Warp Build plan. You can choose to switch your existing plan to Warp Build at any time before your applicable renewal date to access BYOK. #### How does the monthly spend limit on Add-on Credits work? [Section titled “How does the monthly spend limit on Add-on Credits work?”](#how-does-the-monthly-spend-limit-on-add-on-credits-work) You set a monthly spend limit that applies to your AI usage for each calendar month. This limit acts as the maximum amount you can spend on credits during that period. If a purchase would exceed your limit, it won’t go through—you’ll need to either increase your limit or choose a smaller purchase amount. **For auto reload settings:** * New users who enable auto reload will start with a $200 spend limit. * Existing paid plan users who enable auto reload will have their limit match their existing Overages spend limit (if previously configured, otherwise $200). #### I’m an individual developer and need more than 1,500 credits per month. What’s the right plan for me? [Section titled “I’m an individual developer and need more than 1,500 credits per month. What’s the right plan for me?”](#im-an-individual-developer-and-need-more-than-1500-credits-per-month-whats-the-right-plan-for-me) If you regularly use more than 1,500 credits per month, the Build plan is designed for you. It includes 1,500 monthly credits and gives you the flexibility to scale further with Add-on Credits, which you can purchase at discounted rates directly under **Settings** > **Billing and usage**. Add-on Credits roll over month to month, remain valid for 12 months, and offer up to \~40% savings for larger denominations. You can also enable auto reload to automatically top up your credits when your balance runs low. If you’re part of a team that needs shared credit management, SSO, or enforced Zero Data Retention (ZDR), the Business plan provides all the same AI capabilities plus advanced security and administrative features. #### Should I subscribe to the Build plan or the Business plan? [Section titled “Should I subscribe to the Build plan or the Business plan?”](#should-i-subscribe-to-the-build-plan-or-the-business-plan) If you’re an individual developer or part of a small team, the Build plan is the best fit. It includes 1,500 monthly credits, discounted Add-on Credits for additional usage, and the ability to bring your own API key (BYOK) for OpenAI, Anthropic, or Google models. You’ll also get unlimited Warp Drive objects, collaboration tools, and the highest codebase indexing limits. If you’re part of a larger team (up to 50 members) that needs advanced administrative and security controls, choose the Business plan. It includes everything in Build, plus SSO, enforced Zero Data Retention (ZDR), shared Add-on Credits that can be used by all team members, and centralized billing – ideal for organizations that need stronger security, compliance, and team-wide management. #### How do credits work for multi-seat teams? [Section titled “How do credits work for multi-seat teams?”](#how-do-credits-work-for-multi-seat-teams) For teams on the Build or Business plans, credits are managed at two levels: * **Included monthly credits**: Each seat on a paid plan receives 1,500 individual credits per month. These credits are tied to the user and reset every 30 days based on their subscription or renewal date. * **Add-on Credits**: Once individual plan credits are used up, team members draw from a shared Add-on Credit balance that can be topped up and managed by team admins. This shared model gives teams the flexibility to handle variable AI usage – heavy users can consume more when needed, while the entire team benefits from shared value and volume-based discounts. # Warp network log > Logs for all network traffic (both requests and responses) originating from the current terminal session. ## What is it [Section titled “What is it”](#what-is-it) You can use Warp’s network log to help debug issues or simply use it to understand when information is sent or received over the network throughout a Warp session. Each log item is a timestamped Debug format string for either a request or response object handled by Warp. Messages are logged via pre-request and post-response hooks in Warp’s internal HTTP client. ## How to use it [Section titled “How to use it”](#how-to-use-it) 1. To access the network log, select the Input in a session and open the [Command Palette](/terminal/command-palette/), then search for “Show Warp Network Log”. 2. That will insert a command into your Input editor - it should look something like this: `tail -f "some/path/to/warp_network.log"`. 3. Press Enter to run this command. You’ll then see the corresponding requests and responses logged in the network log. ## How it Works [Section titled “How it Works”](#how-it-works) [Network Log Demo](https://www.loom.com/embed/0d9eaeb8715846f3a96d557abe23e7ac) ## Known issues with Network Log [Section titled “Known issues with Network Log”](#known-issues-with-network-log) At the moment, network traffic originating from crash reports and error messages is not captured in the network log. This is due to our use of the Sentry SDK, which encapsulates all network logic and doesn’t currently expose a hook for handling requests and responses directly. The team is actively investigating a solution to include such traffic in the log in a future release. You may also disable Crash Reporting entirely in Warp’s **Settings** > **Privacy** tab. # Privacy and data control > Warp's approach to privacy and your control over your data Note If you have questions, reach out at . For security-related issues, email . ## Transparency and control [Section titled “Transparency and control”](#transparency-and-control) Our philosophy is complete transparency and control over any data leaving your machine. This means you can: * Read a complete list of [all the telemetry events](/support-and-community/privacy-and-security/privacy/#exhaustive-telemetry-table) that get sent for app analytics * Monitor telemetry in real-time with Warp’s native [Network Log](/support-and-community/privacy-and-security/network-log/) * [Opt out](/support-and-community/privacy-and-security/privacy/#how-to-disable-telemetry-and-crash-reporting) of telemetry at any time * Read and audit Warp’s client source code at [`warpdotdev/warp`](https://github.com/warpdotdev/warp), open source under [AGPL v3](https://github.com/warpdotdev/warp/blob/master/LICENSE) ## What telemetry data does Warp collect and why? [Section titled “What telemetry data does Warp collect and why?”](#what-telemetry-data-does-warp-collect-and-why) Warp collects high-level telemetry and usage data to discover product quality issues and guide feature prioritization. If you haven’t opted out of “Help improve Warp”, we may collect: 1. High level product usage and analytics data to analyze feature uptake and usage patterns. See the full list of tracked events in the [exhaustive telemetry table](/support-and-community/privacy-and-security/privacy/#exhaustive-telemetry-table) below. These are all high level metrics and do not include any user generated content. 2. AI interactions and console inputs that power our [AI features](/agent-platform/local-agents/overview/). Warp unconditionally applies [Secret Redaction](/support-and-community/privacy-and-security/secret-redaction/) in all AI interactions to ensure that any sensitive data is *never* collected or sent to third parties. Note Telemetry must be enabled to use AI features on the Free plan, while paid plans can opt out at any time and continue using Warp, including AI. Caution Business and Enterprise plans are covered by our Zero Data Retention (ZDR) agreement. No AI interaction or console data is ever collected. Selling usage data will never be part of Warp’s business model. This data is used solely to improve the end-user experience. Warp uses Sentry for crash reporting and Rudderstack for app analytics. You can read our [full privacy policy](https://www.warp.dev/legal/privacy-policy) as well as [how Warp handles security](https://www.warp.dev/legal/security). ### How to disable telemetry and crash reporting [Section titled “How to disable telemetry and crash reporting”](#how-to-disable-telemetry-and-crash-reporting) 1. Navigate to **Settings** > **Privacy**, or open the [Command Palette](/terminal/command-palette/) and search for “privacy” 2. Toggle off “Help improve Warp”, “Send crash reports”, or both ![Privacy Settings](/_astro/privacy-settings-after-signup-1.D3c_g7rp_aQ9wH.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) With telemetry disabled, no console interactions are ever persisted on Warp’s servers. Each request contains a `X-Warp-Telemetry-Enabled` header to specify whether telemetry is disabled, and even if this is missing from the request, our server assumes it’s disabled. ### Delete your account and data [Section titled “Delete your account and data”](#delete-your-account-and-data) Warp provides a convenient way for you to delete your account and data. Any active Warp subscriptions associated with the account will also be cancelled when deleted. You can delete your Warp account and data in the following ways: * From Warp, go to **Settings** > **Privacy** > **“Visit the data management page”** Click the “Delete” button on the Data Management page to go through the data deletion flow. * From the web, log in to your warp account at , then go to the data management page at and click the “Delete” button to go through the data deletion flow. Note Deletion jobs run every 24 hours, so if you deleted your account and want to sign up again with the same email, you won’t be able to do so until that deletion job completes. Caution If you’re a [Team](/knowledge-and-collaboration/teams/) admin, the deletion flow will require that you assign a team member as the new admin. ### Exhaustive Telemetry Table [Section titled “Exhaustive Telemetry Table”](#exhaustive-telemetry-table) | Event Name | Description | | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AI Command Search opened` | Opened the modal for AI Command Search, where you can use natural language to search for commands | | `AI Execution Profile Created` | A new AI execution profile was created | | `AI Execution Profile Deleted` | An AI execution profile was deleted | | `AI Execution Profile: Added To Allowlist` | An item was added to an AI execution profile allowlist | | `AI Execution Profile: Added To Denylist` | An item was added to an AI execution profile denylist | | `AI Execution Profile: Context Window Selected` | Selected a context window limit for an execution profile’s base model | | `AI Execution Profile: Model Selected` | An AI model was selected for an AI execution profile | | `AI Execution Profile: Removed From Allowlist` | An item was removed from an AI execution profile allowlist | | `AI Execution Profile: Removed From Denylist` | An item was removed from an AI execution profile denylist | | `AI Execution Profile: Setting Updated` | An AI execution profile setting was updated | | `AI Input Not Sent` | The AI input was not sent | | `AI Suggested Rule Added` | Clicked the Add Suggested Rule button in the AI blocklist | | `AI Suggested Rule Content Changed` | Content changed by the user in the suggested rule dialog | | `AI Suggested Rule Edited` | Clicked the Edit Suggested Rule button in the AI blocklist | | `AIAutonomy.AutoexecutedRequestedCommand` | Autoexecuted an Agent Mode requested command | | `AIAutonomy.ChangedAgentModeCodingPermissions` | Changed Agent Mode permissions for coding tasks | | `AIAutonomy.ToggledAutoexecuteReadonlyCommandsSetting` | Toggled setting to autoexecute readonly Agent Mode requested commands | | `Add Added Subshell Command` | Added a command to be automatically Warpified via Warp’s subshell wrapper | | `Add Denylisted SSH Tmux Wrapper Host` | Added a SSH host to the denylist for prompting for Tmux Wrapper | | `Add Denylisted Subshell Command` | Explicitly prevent a command from being Warpified via Warp’s subshell wrapper | | `Add Tab With Shell` | Added a tab with specific shell | | `Added Workflow Alias` | Added an alias to a Warp Drive workflow | | `Agent Management View Copied Session Link` | User copied a session link from the Agent Management View | | `Agent Management View Opened Session` | User opened a session from the Agent Management View | | `Agent Management View Toggled` | User toggled the Agent Management View open or closed | | `Agent Mode Query Suggestion Accepted` | Prompt Suggestion accepted | | `Agent Mode Query Suggestions Banner Shown` | Prompt Suggestions banner shown | | `Agent Mode Setup Banner Accepted` | Agent Mode setup banner accepted | | `Agent Mode Setup Banner Dismissed` | Agent Mode setup banner dismissed | | `Agent Mode Setup Project Scoped Rules Action` | User clicked a button in the Agent Mode setup project scoped rules step | | `Agent Mode.Setup Codebase Context Action` | User clicked a button in the Agent Mode setup codebase context step | | `Agent Predict` | Completed an Agent Predict prediction | | `Agent Toolbar Dismissed` | User dismissed the use-agent toolbar | | `AgentManagement.AgentTypeSelectorOpened` | User opened the agent type selector from agent management | | `AgentManagement.ArtifactClicked` | User clicked an artifact button | | `AgentManagement.CloudRunCancelled` | User cancelled a cloud run | | `AgentManagement.CloudRunOpened` | User opened a cloud run | | `AgentManagement.ConversationForked` | User forked a conversation | | `AgentManagement.ConversationLinkCopied` | User copied a conversation link | | `AgentManagement.ConversationOpened` | User opened a conversation | | `AgentManagement.DetailsPanelContinueLocally` | User clicked Continue locally in the details panel | | `AgentManagement.DetailsViewed` | User clicked View details | | `AgentManagement.DismissSetupGuide` | User dismissed the ambient agent setup guide | | `AgentManagement.FilterChanged` | User changed a filter in the management view | | `AgentManagement.OpenSetupGuide` | User opened the ambient agent setup guide | | `AgentManagement.SessionLinkCopied` | User copied a session link | | `AgentManagement.SetupGuideDocsLink` | User clicked a docs URL in the setup guide | | `AgentManagement.SetupGuideStepCopy` | User copied a workflow step from the setup guide | | `AgentManagement.SetupGuideStepRun` | User ran a workflow step from the setup guide | | `AgentManagement.SlashCommandContinueLocally` | User invoked /continue-locally to fork a cloud conversation locally | | `AgentManagement.SpawnNewCloudAgent` | User spawned a new cloud agent from agent management | | `AgentManagement.SpawnNewLocalAgent` | User spawned a new local agent from agent management | | `AgentManagement.TombstoneArtifactClicked` | User clicked an artifact in the tombstone view | | `AgentManagement.TombstoneContinueInCloud` | User clicked Continue in the tombstone to start a cloud follow-up | | `AgentManagement.TombstoneContinueLocally` | User clicked Continue locally in the tombstone | | `AgentManagement.ViewToggled` | User toggled the agent management view open or closed | | `AgentMode.AttachedContext` | Attached block as context to an Agent Mode query | | `AgentMode.AttachedImages` | Attached images to an Agent Mode query | | `AgentMode.ChangedInputType` | The input type was changed from shell -> AI or AI -> shell | | `AgentMode.ClickedEntrypoint` | Clicked on an Agent Mode entrypoint | | `AgentMode.Code.DiffHunksNavigated` | Agent Mode Code diff hunks navigated | | `AgentMode.Code.DiffMatchFailed` | Failed to match code diff | | `AgentMode.Code.FileExceededContextLimit` | File from AI exceeded context limit | | `AgentMode.Code.FilesNavigated` | Agent Mode Code files navigated | | `AgentMode.Code.InvalidFile` | File(s) in code diff could not be found | | `AgentMode.Code.MalformedFinalLineProxy` | Suggested code diff likely required malformed trailing line correction (heuristic) | | `AgentMode.Code.MissingLineNumbers` | Code diff was missing line numbers | | `AgentMode.Code.SuggestedCodeEditedByUser` | Agent Mode Code suggestion edited by user | | `AgentMode.Code.SuggestedEditAcceptAndContinueClicked` | User selected Accept and start conversation for a code diff suggestion in Agent Mode | | `AgentMode.Code.SuggestedEditAcceptClicked` | User selected Accept for a code diff suggestion in Agent Mode | | `AgentMode.Code.SuggestedEditReceived` | Agent Mode suggested a code edit | | `AgentMode.Code.SuggestedEditResolved` | Agent Mode pending code edit suggestion resolved | | `AgentMode.CreatedAIBlock` | Created an AI block in Agent Mode | | `AgentMode.Error` | Received an error when getting Agent Mode response | | `AgentMode.ExecutedWarpDrivePrompt` | Executed a saved prompt. | | `AgentMode.ExitedShellProcess` | An agent-requested command caused the shell process to exit | | `AgentMode.FileGlob.Failed` | The file glob tool failed to complete | | `AgentMode.FileGlob.Succeeded` | The file glob tool completed successfully | | `AgentMode.Grep.Failed` | The grep tool failed to complete | | `AgentMode.Grep.Succeeded` | The grep tool completed successfully | | `AgentMode.NaturalLanguageDetection.InputBufferSubmitted` | Input buffer submitted | | `AgentMode.OpenedCitation` | Opened a citation that was surfaced in Agent Mode | | `AgentMode.Orchestration.TeamAgentCommunicationFailed` | Failed to send an orchestration message or lifecycle event for a TeamAgent | | `AgentMode.PotentialAutoDetectionFalsePositive` | Manually toggled input to shell mode after input was auto-detected as natural language. | | `AgentMode.QueryAttemptAtLImit` | Tried to send an Agent Mode query but they already reached the query limit | | `AgentMode.RequestRetrySucceeded` | Agent Mode request succeeded after retrying following an initial error | | `AgentMode.SetupCreateEnvironmentAction` | User clicked a button in the Agent Mode setup create environment step | | `AgentMode.SurfacedCitations` | Agent Mode used and cited external sources that were used in its response | | `AgentMode.ToggleAutoDetectionSetting` | Toggled the setting that enables or disables natural language auto-detection in the input. | | `AgentNotification.Shown` | An agent notification was shown to the user (toast or mailbox) | | `AgentTip Clicked` | User clicked a link or action in an Agent Tip | | `AgentTip Shown` | Selected an Agent Tip to show in the Agent Mode status bar | | `AgentView.Entered` | User entered the Agent View | | `AgentView.Exited` | User exited the Agent View | | `AgentView.InlineConversationMenuItemSelected` | User selected an item from the inline conversation menu | | `AgentView.InlineConversationMenuOpened` | User opened the inline conversation menu in Agent View | | `AgentView.ShortcutsViewToggled` | User toggled the shortcuts view in Agent View | | `AgenticOnboarding.BlockSelected` | Selected an agentic onboarding block to execute | | `AmbientAgent.CloudMode.Entered` | User entered cloud agent view | | `AmbientAgent.CloudMode.EnvironmentSelector.Opened` | User opened the environment selector menu | | `AmbientAgent.CloudMode.EnvironmentSelector.Selected` | User selected an environment from the selector | | `AmbientAgent.CloudMode.EnvironmentSettings.GitHubAuth` | User started GitHub authentication from the environment form | | `AmbientAgent.CloudMode.EnvironmentSettings.LaunchedAgent` | User launched an environment setup agent from the environment form | | `AmbientAgent.ConcurrencyModal.Dismissed` | User dismissed the cloud agent capacity modal | | `AmbientAgent.ConcurrencyModal.Opened` | User opened the cloud agent capacity modal | | `AmbientAgent.ConcurrencyModal.UpgradeClicked` | User clicked the upgrade button in the cloud agent capacity modal | | `AmbientAgent.DispatchFailed` | Ambient agent failed to dispatch or encountered an error | | `AmbientAgent.EnvironmentSettings.CreatedEnvironment` | User created a new environment | | `AmbientAgent.EnvironmentSettings.DeletedEnvironment` | User deleted an environment | | `AmbientAgent.EnvironmentSettings.Image.Suggested` | Docker image was suggested for an environment | | `AmbientAgent.EnvironmentSettings.Image.SuggestionFailed` | Docker image suggestion failed | | `AmbientAgent.EnvironmentSettings.Opened` | User opened the environment management pane | | `AmbientAgent.EnvironmentSettings.UpdatedEnvironment` | User updated an existing environment | | `Anonymous User Attempted Login-Gated Feature` | Anonymous user attempted to access a login-gated feature | | `Anonymous User Expiration Lockout` | An anonymous user opened Warp after their conversion deadline and was locked out | | `Anonymous User Hit Cloud Object Limit` | Anonymous user attempted to create a cloud object past their personal object limit | | `Anonymous User Initiated Signup` | An anonymous user initiated the sign up flow | | `Anonymous User Linked from Browser` | Received an auth payload from anonymous user after linking in browser | | `App Download Source` | Whether the Warp was installed from the home page or through homebrew | | `App Startup` | App is launched | | `Attached Workflow Alias Environment Variables` | Added or removed environment variables for a Warp Drive workflow alias | | `Attempting to Relaunch for Update` | Attempted to relaunch the app after installing an update | | `Auth Common Question Clicked in App` | Clicked on “Common Question” when logging in | | `Auth: Open Privacy Settings Overlay` | Privacy settings are open during sign-in | | `Auth: Toggle Common Questions` | Toggled FAQ Page when logging in | | `Autosuggestion Inserted` | Accepted autosuggestion | | `Background Block Started` | Warp created a background-output Block (whenever a processes has been backgrounded and yields some output) | | `BaselineCommand Latency` | Command execution time | | `Block Creation` | Created Block | | `Block Filter Toolbelt Button Clicked` | Clicked the block filter icon in the top-right of a block | | `Block Selection` | Selected Block | | `Bootstrap Slow Contents` | Contents of the bootstrap block if bootstrapping is slow | | `Bootstrapping Slow` | Slow bootstrap on session startup | | `Bootstrapping Succeeded` | Successful bootstrap for session | | `CLI Subagent Action Executed` | User approved a blocked action from the CLI subagent | | `CLI Subagent Action Rejected` | User rejected a blocked action from the CLI subagent | | `CLI Subagent Control State Changed` | Control state changed in CLI subagent (agent in control, agent blocked, user in control, or agent tagged in) | | `CLI Subagent Input Dismissed` | User dismissed the input in the CLI subagent | | `CLI Subagent Responses Toggled` | User toggled the visibility of agent responses in CLI subagent | | `CLI.Execute.Agent.List` | Listed agents from the Warp CLI | | `CLI.Execute.Agent.Profile.List` | Listed agent profiles from the Warp CLI | | `CLI.Execute.Agent.Run` | Ran an agent from the Warp CLI | | `CLI.Execute.Agent.RunAmbient` | Ran an ambient agent from the Warp CLI | | `CLI.Execute.Artifact.Download` | Downloaded an artifact from the Warp CLI | | `CLI.Execute.Artifact.Get` | Got artifact metadata from the Warp CLI | | `CLI.Execute.Artifact.Upload` | Uploaded an artifact from the Warp CLI | | `CLI.Execute.Conversation.Get` | Got conversation by ID from the Warp CLI | | `CLI.Execute.Environment.Create` | Created a cloud environment from the Warp CLI | | `CLI.Execute.Environment.Delete` | Deleted a cloud environment from the Warp CLI | | `CLI.Execute.Environment.Get` | Got cloud environment details from the Warp CLI | | `CLI.Execute.Environment.Image.List` | Listed available base images from the Warp CLI | | `CLI.Execute.Environment.List` | Listed cloud environments from the Warp CLI | | `CLI.Execute.Environment.Update` | Updated a cloud environment from the Warp CLI | | `CLI.Execute.Federate.IssueGcpToken` | Issued a GCP federated identity token from the Warp CLI | | `CLI.Execute.Federate.IssueToken` | Issued a federated identity token from the Warp CLI | | `CLI.Execute.Integration.Create` | Created an integration from the Warp CLI | | `CLI.Execute.Integration.List` | Listed integrations from the Warp CLI | | `CLI.Execute.Integration.Update` | Updated an integration from the Warp CLI | | `CLI.Execute.Login` | Logged in via the Warp CLI | | `CLI.Execute.Logout` | Logged out via the Warp CLI | | `CLI.Execute.MCP.List` | Listed MCP servers from the Warp CLI | | `CLI.Execute.Model.List` | Listed models from the Warp CLI | | `CLI.Execute.Provider.List` | Listed providers from the Warp CLI | | `CLI.Execute.Provider.Setup` | Set up a provider via the Warp CLI | | `CLI.Execute.Run.Conversation.Get` | Got run conversation from the Warp CLI | | `CLI.Execute.Schedule.Create` | Created a scheduled agent from the Warp CLI | | `CLI.Execute.Schedule.Delete` | Deleted a scheduled agent from the Warp CLI | | `CLI.Execute.Schedule.Get` | Got scheduled agent configuration from the Warp CLI | | `CLI.Execute.Schedule.List` | Listed scheduled agents from the Warp CLI | | `CLI.Execute.Schedule.Pause` | Paused a scheduled agent from the Warp CLI | | `CLI.Execute.Schedule.Unpause` | Unpaused a scheduled agent from the Warp CLI | | `CLI.Execute.Schedule.Update` | Updated a scheduled agent from the Warp CLI | | `CLI.Execute.Secret.Create` | Created a secret from the Warp CLI | | `CLI.Execute.Secret.Delete` | Deleted a secret from the Warp CLI | | `CLI.Execute.Secret.List` | Listed secrets from the Warp CLI | | `CLI.Execute.Secret.Update` | Updated a secret from the Warp CLI | | `CLI.Execute.Task.Get` | Got status of task from the Warp CLI | | `CLI.Execute.Task.List` | Listed tasks from the Warp CLI | | `CLI.Execute.Whoami` | Printed current user info from the Warp CLI | | `CLIAgentFooter.ImageAttached` | User attached an image from the CLI agent footer | | `CLIAgentFooter.SettingToggled` | User toggled the CLI agent footer setting | | `CLIAgentFooter.Shown` | CLI agent footer was shown to the user | | `CLIAgentFooter.VoiceInputUsed` | User used voice input from the CLI agent footer | | `CLIAgentPlugin.ChipClicked` | User clicked the plugin install or update chip | | `CLIAgentPlugin.ChipDismissed` | User dismissed the plugin install or update chip | | `CLIAgentPlugin.Detected` | A CLI agent plugin was detected via a SessionStart event | | `CLIAgentPlugin.OperationFailed` | Auto plugin install or update failed | | `CLIAgentPlugin.OperationSucceeded` | Auto plugin install or update completed successfully | | `CLIAgentRichInput.Closed` | CLI agent Rich Input was closed | | `CLIAgentRichInput.Opened` | User opened CLI agent Rich Input | | `CLIAgentRichInput.Submitted` | User submitted a prompt via CLI agent Rich Input | | `Changed invite view option` | Toggled between link and invite for invite | | `Clicked Continue Conversation Button` | User clicked the Continue Conversation button in a block footer | | `Clicked Reset to Defaults Button in Settings Import` | Reset the imported settings in the settings import onboarding block | | `Clone Repo Prompt Submitted` | User submitted a repository URL from the clone repo view | | `Code Pane Opened` | Opened the code editor pane from various sources | | `CodePanels.FileOpened` | Opened a file from code review, project explorer, or global search | | `CodeReview.AddToContext` | Content added to AI context from code review | | `CodeReview.BaseChanged` | Diff base changed in code review | | `CodeReview.CalculateDiffMetadataFailed` | Failure when calculating diff metadata | | `CodeReview.CommentAdded` | Inline code review comment added | | `CodeReview.CommentDeleted` | Inline code review comment deleted | | `CodeReview.CommentEdited` | Inline code review comment edited | | `CodeReview.CommentEditorOpened` | Inline code review comment editor opened | | `CodeReview.CommentListExpanded` | Inline code review comment list expanded | | `CodeReview.CommentListItemClicked` | Inline code review comment list item clicked | | `CodeReview.CommentRelocationFailed` | Inline code review comment relocation fell back to approximate line | | `CodeReview.CommentResolved` | Inline code review comment resolved | | `CodeReview.CommentsAttached` | Newly-imported comments relocated against editor lines | | `CodeReview.CommentsReceived` | Agent insert\_code\_review\_comments tool call received and processed | | `CodeReview.FileSaved` | File saved in code review pane | | `CodeReview.FindBarModeChanged` | Search mode changed in code review find bar | | `CodeReview.FindBarToggled` | Code review find bar opened or closed | | `CodeReview.FindNavigated` | Navigated to next or previous match in code review find bar | | `CodeReview.GitButtonTriggered` | User clicked a git operation button in the code review header | | `CodeReview.GitDialogCompleted` | Git operation dialog reached a terminal state (succeeded, failed, or cancelled) | | `CodeReview.LoadDiffFailed` | Failure when loading diff content | | `CodeReview.PaneOpened` | Code review pane opened | | `CodeReview.PaneStateChanged` | Code review pane minimized or maximized | | `CodeReview.RevertHunkClicked` | Revert hunk button clicked | | `CodeReview.ReviewSubmitted` | Inline code review submitted to agent | | `CodeView.SelectionAddedAsContext` | Added selected code as context from the code editor | | `CodexModal.Opened` | User opened the Codex modal | | `CodexModal.UseCodexClicked` | User clicked ‘Use Codex’ in the Codex modal | | `Command Correction Event` | Accepted command correction | | `Command File Run` | Opened a .cmd or unix executable file and ran it directly in Warp | | `Command Palette Search Accepted` | Accepted a command palette search result | | `Command Palette Search Exited` | Exited command palette search without accepting a result | | `Command Search Async Query Completed` | Finished searching for a command in the background | | `Command Search Exited` | Exited command search (universal search panel to search) without accepting a result | | `Command Search Filter Changed` | Changed command search filter | | `Command Search Opened` | Opened command search (universal search panel to search) | | `Command Search Result Accepted` | Accepted command search result | | `Complete Welcome Tip` | Completed all welcome tips items | | `Completed Settings Import` | Imported a terminal’s settings via the settings import onboarding block | | `ComputerUse.Approved` | A RequestComputerUse action was approved (manually or auto-executed) | | `ComputerUse.Cancelled` | A RequestComputerUse action was cancelled/rejected | | `Confirm Suggestion` | Accepted tab completion suggestion | | `Context Menu Copy` | Clicked “Copy” in context menu | | `Context Menu Copy Prompt` | Clicked “Copy Prompt” in context menu | | `Context Menu Copy Selected Text` | Clicked “Copy selected text” in context menu | | `Context Menu Insert Selected Text into Input` | Clicked “insert into input” in context menu | | `Context Menu Toggle Git Prompt Dirty Indicator` | Toggled indicator of dirty git prompt | | `Context Menu: Find Within Blocks` | Clicked “find within blocks” in context menu | | `Context Menu: Initiate Block Sharing` | Opened “Share” modal via context menu | | `Context Menu: Reinput Commands` | Clicked “reinput commands” in context menu | | `ConversationList.ItemDeleted` | Deleted a conversation from the conversation list | | `ConversationList.ItemOpened` | Opened a conversation from the conversation list | | `ConversationList.LinkCopied` | Copied a conversation link from the conversation list | | `ConversationList.Opened` | Opened the conversation list view in the left panel | | `Copied Shared Session Link` | Copied a shared session link | | `Copy Block Sharing Link` | Clicked “Share block…” in context menu | | `Copy Invite Link` | Clicked “Copy Link” on Referral Modal | | `Copy Obfuscated Secret` | Copied a secret’s obfuscated contents to clipboard | | `Copy Object To Clipboard` | Copied an object to the user’s keyboard | | `Create Custom Theme` | Created a custom theme using the built-in theme creator | | `Create Project Prompt Submitted` | User submitted a prompt from the create project view | | `Create Project Prompt Submitted Content` | User submitted custom prompt content from the create project view | | `Custom Secret Regex Added` | Custom Secret Regex Added | | `Database Read Error` | Database read error when trying to get app state for session restoration | | `Database Startup Error` | Failed to initialize sqlite upon startup | | `Database Write Error` | Database write error when trying to write app state for session restoration | | `Decline Subshell Bootstrap` | Developer declined the Warp banner to Warpify the current session | | `Delete Custom Theme` | Deleted a custom theme using the built-in theme creator | | `Deleted Notebook` | Deleted notebook from Warp Drive team | | `Deleted Workflow` | Deleted workflow from Warp Drive team | | `Disable Input Sync Inputs` | Disabled / turn off the Input Synchronization (across editors) | | `Dismiss Alias Expansion Banner` | Dismissed the banner to enable automatic alias expansion within the Input Editor | | `Dismiss Welcome Tips` | Dismissed Welcome tips | | `Don't Show Sharer Grant Modal Again` | When you check don’t show again on the confirmation modal for granting a role | | `Drag and Drop Tab` | Tab dragged and dropped | | `Duplicate Object` | Cloned a Warp Drive object | | `Edited Input Before Precmd` | Input edited before precmd hook completes | | `Edited Workflow Alias Argument` | Edited an argument in a Warp Drive workflow alias | | `Enable Alias Expansion From Banner` | Enabled automatic alias expansion within the Input Editor from the banner | | `Executed Conversation Rewind` | User executed a rewind to a previous conversation state | | `Expanded Code Suggestion` | Expanded the passive code diff suggestion | | `Export Object` | Exported a Warp Drive object | | `Features Page Action` | Changed settings in Features Page | | `File Tree Toggled` | Opened the file tree/project explorer | | `FileTree.AttachedAsContext` | Attached a file or directory as context from the file tree | | `FileTree.ItemCreated` | Created a new file from the file tree | | `Find Option Toggled` | Changed settings in Find Toggle | | `Focused Config in Settings Import` | Selected a terminal in the settings import onboarding block | | `FreeTierLimitHitInterstitial.Closed` | User closed the free tier limit hit interstitial | | `FreeTierLimitHitInterstitial.Displayed` | The free tier limit hit interstitial was displayed | | `FreeTierLimitHitInterstitial.UpgradeButtonClicked` | User clicked the ‘Upgrade’ button in the free tier limit hit interstitial | | `Generate Block Sharing Link` | Generated Block sharing link | | `Generate Metadata For Workflow Error` | Failed to generate metadata for a workflow using Warp AI | | `Generate Metadata For Workflow Success` | Successfully generated metadata for a workflow using Warp AI | | `Get Started Skip to Terminal` | User clicked skip to terminal from get started view | | `Global Search Opened` | Opened the global search view | | `Global Search Query Started` | Started a global search (warp\_ripgrep) search | | `ITerm Profile has Multiple Hotkeys` | Attempted to import an iTerm profile that contained multiple hotkey window bindings | | `Identified Antivirus Software` | Identified running antivirus software on the user’s machine | | `Image Received` | Received an image through an image protocol over the pty | | `InitialWorkingDirectoryConfigurationChanged` | Replaced the default working directory with a different path | | `Initiate Reauth` | Started the flow to re-authenticate the client | | `Input Mode Changed` | Changed the Input Editor Mode (Pinned to Bottom, Pinned to Top, Classic / Waterfall Mode) | | `Input.AtMenuInteracted` | Interacted with the @ menu | | `Input.ContextChipInteracted` | Interacted with a context chip | | `Input.InputUXModeChanged` | Changed the input UX mode | | `Input.VoiceInputUsed` | Used voice input | | `InputBoxAICommandSearch` | Opened AI Command Search via the Input Editor’s context menu (right clicking the buffer) | | `InputBoxAskWarpAI` | Clicked “Ask Warp AI” from the Input Editor’s context menu | | `InputBoxCommandSearch` | Opened Command Search via the Input Editor’s context menu (right clicking the buffer) | | `InputBoxCutSelectedText` | Copied selected text from Input Editor | | `InputBoxPaste` | Pasted text into the Input Editor’s via its context menu (right clicking the buffer) | | `InputBoxSelectAll` | Selected all the text in the Input Editor via its context menu (right clicking the buffer) | | `Invited Teammates` | Sent emails to invite teammates to join Warp Drive team | | `Invoked Environment Variables` | Invoked an environment variables object | | `Isolation.DetectedIsolationPlatform` | Detected that Warp is running in an isolated sandbox | | `Joined Shared Session` | When you join another instance of Warp using shared sessions | | `Jumped to Bookmark Block` | Jumped to bookmarked Block | | `Jumped to Bottom of Block Button Clicked` | Used the button to jump to the bottom of a Block | | `Jumped to Previous Command` | Jumped to a previous command | | `Jumped to Shared Session Participant` | Clicked on a shared session participant avatar to jump to their location in the session | | `Keybinding Changed` | Edited a custom keybinding | | `Keybinding Removed` | Removed / cleared a keybinding | | `Keybinding Reset to Default` | Reset a custom keybinding to its default | | `Knowledge Pane Opened` | Knowledge Pane Opened | | `Linear.IssueLinkOpened` | User opened a warp\://linear deeplink to work on an issue | | `Log In Button Clicked in App` | Clicked on “Log in” button | | `Log Out` | Logged out of the Warp client | | `Log Out Modal Cancel Pressed` | Escaped the log out flow by canceling the log out modal | | `Log Out Modal Shown` | When the log out modal is displayed | | `Logged in to native app` | Login is successful | | `Logged-out App Startup` | Started Warp in the logged-out / signed-out state | | `Login Later Button Clicked` | Clicked “Login later” button | | `Login Later Confirmation Button Clicked` | Clicked “Yes, skip login” confirmation button | | `Lsp.ControlAction` | User performed an LSP control action from the footer menu | | `Lsp.FindReferencesShown` | Find references card displayed via LSP | | `Lsp.GotoDefinition` | User triggered goto definition via LSP | | `Lsp.HoverShown` | Hover tooltip displayed with LSP content or diagnostics | | `Lsp.ServerEnabled` | User enabled an LSP server for a workspace | | `Lsp.ServerEnablementSkipped` | User skipped LSP enablement during /init | | `Lsp.ServerFailed` | LSP server failed to start | | `Lsp.ServerInstallCompleted` | An LSP server installation finished | | `Lsp.ServerRemoved` | User removed an LSP server | | `Lsp.ServerStarted` | LSP server successfully started and is available | | `MCP Server Added` | MCP Server Added | | `MCP Server Collection Pane Opened` | MCP Server Collection Pane Opened | | `MCP Server Spawned` | MCP Server Spawned | | `MCP Template Created` | MCP Template Created | | `MCP Template Installed` | MCP Template Installed | | `MCP Template Shared` | MCP Template Shared | | `MCP Tool Call Accepted` | MCP Tool Call Accepted | | `Move Active Tab` | Move active tab left or right | | `Move Tab` | Move tab left or right | | `Needs Reauth` | User needs to re-authenticate | | `New Session From Directory` | Dragged a file, folder, etc. into Warp to start a session | | `Notebook Action` | Took an action on a notebook: edit, delete, modified font size, etc. | | `Notebook Edited` | Edited a notebook | | `Notebook Opened` | Opened a notebook | | `Notification Clicked` | Clicked desktop notification sent from Warp | | `Notification Failed to Send` | Failed to send desktop notification | | `Notification Permissions Requested` | Requested permission for desktop notification permissions | | `Notification Request Permissions Outcome` | Recorded outcome of attempting to request desktop notification permissions | | `Notification Sent` | Sent desktop notification | | `Notifications Discovery Banner Action` | Showed banner introducing the notifications feature | | `Notifications Error Banner Action` | Showed error banner for notifications feature | | `Object Link Copied` | The web link to an object has been copied. | | `Open Context Menu` | Opened context menu (such as right clicking, clicking on ellipses in the top right of a Block, etc.) | | `Open Launch Config` | Opened launch config for a session | | `Open Launch Config File` | Opened the launch config YAML file from modal once saved successfully | | `Open Palette` | Opened the palette | | `Open Quake Mode Window` | Toggled quake mode window when previously hidden or closed | | `Open Repo Folder Submitted` | User selected a folder to open as a repo from the “Open repository” button | | `Open Save Config Modal` | Opened save launch configuration modal | | `Open Slash Menu` | Opened the slash commands menu | | `Open Suggestions Menu` | Opened a suggestion menus, such as with up arrow or tab | | `Open Team from URI` | Showed settings view of their newly joined team within the app | | `Open Theme Chooser` | Opened theme chooser (list of different themes and visualizations of those themes) | | `Open Theme Creator Modal` | Opened theme creator modal (modal to create a new theme) | | `Open Welcome Tips` | Opened welcome tips in app | | `Open Workflows Search` | Opened workflows search in command search pane | | `OpenAndWarpifyDockerSubshell` | Warpifying a docker subshell from using the docker extension | | `OpenInputBoxContextMenu` | Opened the Input Editor’s context menu | | `Opened Changelog Link` | Opened the changelog link within the App | | `Opened Link` | Opened a highlighted link within input or output | | `Opened Rewind Confirmation Dialog` | User opened the rewind confirmation dialog | | `Opened Save As Workflow Modal` | Opened the modal to create a new workflow using a Block’s context—command, etc. | | `Opened Sharing Dialog` | Opened the sharing settings dialog for a session or Warp Drive object | | `Opened Warp AI` | Activated Warp AI | | `Opened alt screen find bar` | Opened the Find bar in the Alt Screen | | `Page Up/Down In Editor Pressed` | Pressed `PAGE-UP` or `PAGE-DOWN` within the Input Editor | | `Pane Drag Ended` | Ended dragging a pane via the pane header | | `Pane Drag Inititiated` | Initiated dragging a pane via the header | | `Parameterized Workflow With Environment Variables` | Selected from environment variables dropdown to parameterize workflow | | `Parsed Config in Settings Import` | Parsed a terminal’s settings as part of settings import | | `Preview Pane Promoted` | Promoted a preview code tab to a normal tab | | `Prompt Edited` | Edited the prompt using the built-in prompt editor | | `Prompt Editor Opened` | Opened the prompt editor | | `Pty Spawned` | Tracks the manner by which we create a new shell process (new codepath vs. old codepath). Used to ensure nothing breaks as we change parts of our infrastructure. | | `Quit Modal Cancel Pressed` | `Cancel` button on the alert modal was pressed | | `Quit Modal Disabled` | The quit modal dialog has been disabled and will not popup when a user closes Warp while a session is running | | `Quit Modal Shown` | Showed an alert modal to warn the user about closing the app/window with a running process | | `Received Subshell RC File DCS` | Spawned a subshell to be automatically Warpified | | `Recent Menu Item Selected` | User selected an item from the recents list on the new tab zero state | | `RemoteServer.BinaryCheck` | Remote server binary check completed (found, not found, or error) | | `RemoteServer.ClientRequestError` | A client request to the remote server failed | | `RemoteServer.Disconnection` | An established remote server connection was dropped | | `RemoteServer.HostUnsupported` | Preinstall check classified the remote host as unsupported, falling back to the legacy SSH flow | | `RemoteServer.Initialization` | Remote server connection and initialization completed (success or failure) | | `RemoteServer.Installation` | Remote server binary installation completed (success or failure) | | `RemoteServer.MessageDecodingError` | A server message could not be decoded (no parseable request\_id) | | `RemoteServer.SetupDuration` | End-to-end duration of the remote server setup flow | | `Remove Added Subshell Command` | Removed a command from the list of commands to automatically Warpify via Warp’s subshell wrapper | | `Remove Denylisted SSH Tmux Wrapper Host` | Removed an SSH host from the denylist from prompting for Tmux Wrapper | | `Remove Denylisted Subshell Command` | Removed a command from the list of commands to IGNORE when trying to Warpify via Warp’s subshell wrapper | | `Removed Workflow Alias` | Removed an alias from a Warp Drive workflow | | `Removed user from team` | Remove user from Warp Drive team | | `RepoMetadata.BuildTree.Failed` | Failed to build file tree for repo metadata | | `Resource Center Keybindings Page Opened` | Opened the keybinding page within the resource center | | `Resource Center Opened` | Opened Resource Center pane | | `Resource Center Tips Completed` | Completed resource center tips | | `Resource Center Tips Skipped` | Skipped welcome tips for new users | | `SSH Bootstrap Attempt` | Attempted bootstrapping for an SSH session | | `SSH ControlMaster Error` | Encountered a ControlMaster error during an SSH session | | `SSH Install Tmux Block Accepted` | User accepted an ssh install tmux block | | `SSH Install Tmux Block Dismissed` | User dismissed an ssh install tmux block | | `SSH Install Tmux Block Displayed` | Displayed an ssh install tmux block | | `SSH Interactive Session Detected` | An interactive SSH session was detected | | `SSH Remote Server Choice Do Not Ask Again Toggled` | Toggled the ‘Don’t ask me this again’ checkbox on the SSH remote-server choice block | | `SSH Tmux Warpification Error Block` | Ssh tmux warpification errored out | | `SSH Tmux Warpification Succeeded` | Ssh tmux warpification succeeded | | `SSH Tmux Warpify Block Accepted` | User accepted an ssh tmux warpify block | | `SSH Tmux Warpify Block Dismissed` | User dismissed an ssh tmux warpify block | | `Save Launch Config` | Saved current launch configuration of windows, tabs, and panes | | `Select App Icon` | Selected app icon | | `Select Command Palette Option` | Selected option from command palette (i.e. CMD-P) | | `Select Cursor Type` | Selected cursor type | | `Select Navigation Palette Item` | Selected session from the Session Navigation Palette (search across panes, tabs, and windows) | | `Select Theme` | Selected theme | | `Sent email invites` | Sent email invites for Warp Drive team | | `Session Abandoned Before Bootstrap` | Abandoned session before the bootstrapping completes | | `Set Line Height` | Set line height through Settings -> Appearance | | `Set New Windows at Custom Size` | Set new windows at custom size through Settings -> Appearance | | `Set SSH Extension Install Mode` | Changed the SSH extension install mode (always ask / always allow / always skip) | | `Set Window Blur Radius` | Changed the blur radius from the `Settings -> Appearance` dialog | | `Set Window Opacity` | Changed the opacity (window transparency) from the `Settings -> Appearance` dialog | | `Settings Import Initiated` | Started the import settings flow for new users | | `Settings.Environments.PageOpened` | User opened the Environments settings page | | `Shared Object Limit Hit Banner View Plans Button Clicked` | Clicked the ‘View Plans’ button on the persistent drive banner | | `Sharer Cancelled Grant Role` | When you cancel granting a role to a shared session participant | | `Shell Terminated Prematurely` | The shell process terminated prematurely | | `Show Alias Expansion Banner` | Displayed the banner asking whether Warp should automatically expand aliases within the Input Editor | | `Show Subshell Banner` | Displayed the banner asking whether Warp should Warpify the current session via Warp’s subshell wrapper | | `Show Warpify SSH Banner` | Displayed the banner asking whether Warp should Warpify the current SSH session via Warp’s SSH Wrapper | | `ShowNotificationsDiscoveryBanner` | Showed notifications discovery banner in the block list | | `ShowNotificationsErrorBanner` | Showed error banner for notifications feature | | `Showed File in File Explorer` | Opened a file in Finder by using “Show in Finder” | | `Sign Up Button Clicked in App` | Clicked “Sign Up” button | | `Skill.Opened` | A skill was opened from an ‘open skill’ button or /edit-skill command | | `Skill.Read` | A skill was read via the ReadSkill tool call | | `Skip Onboarding Survey` | Skipped onboarding survey as a whole | | `Slash Command Accepted` | User accepted a slash command | | `Split Pane` | Split tab into multiple panes | | `Static Prompt Suggestion Accepted` | Static Prompt Suggestion accepted | | `Static Prompt Suggestions Banner Shown` | Static Prompt Suggestions banner shown | | `Suggested Code Diff Banner Shown` | Suggested Code Diff banner shown | | `Suggested Code Diff Failed` | Suggested Code Diff Failed | | `Suggested Prompt Accepted` | Suggested prompt accepted | | `Suggested Prompt Cancelled` | Suggested prompt cancelled | | `Suggested Prompt Shown` | Suggested prompt shown | | `Tab Creation` | Created a tab | | `Tab Operations` | Took operation on a tab: change color, close tab, close adjacent tabs, etc. | | `Tab Renamed` | Changed tab title | | `Tab Single Result Autocompletion` | Accepted tab completion and inserted into Input Editor | | `TabConfigs.ExistingConfigOpened` | User opened an existing saved tab config | | `TabConfigs.GuidedModalOpened` | User opened the guided Create a tab config modal | | `TabConfigs.GuidedModalSubmitted` | User submitted the guided Create a tab config modal | | `TabConfigs.MenuCreateNewTabConfigClicked` | User clicked the New tab config entry from the tab configs menu | | `TabConfigs.NewWorktreeConfigOpened` | User opened a new worktree config from the submenu or new worktree modal | | `Team Created` | Created a Warp Drive team | | `Team Joined` | Joined a Warp Drive team | | `Team Left` | Left a Warp Drive team | | `Team Link Copied` | Copied a Warp Drive team link | | `Thin Strokes Setting Changed` | Changed thin strokes setting in settings -> Appearance | | `Tier Limit Hit` | User hit the tier limit for a feature | | `Toggle Active AI Enablement` | Toggled active AI enablement. | | `Toggle Agent Mode Codebase Context` | Toggled on/off the enablement of codebase context usage for Agent Mode. | | `Toggle Agent Mode Query Suggestions Setting` | Toggled on/off the prompt suggestions setting | | `Toggle Approvals Modal` | Opened or closed teams modal | | `Toggle Block Filter Case Sensitivity` | Toggled on/off case sensitivity within the block filter editor | | `Toggle Block Filter Invert` | Toggled on/off invert within the block filter editor | | `Toggle Block Filter Query` | Toggled on/off a block filter query | | `Toggle Block Filter Regex` | Toggled on/off regex within the block filter editor | | `Toggle Code Suggestions Setting` | Toggled on/off the code suggestions setting | | `Toggle Codebase Context Autoindexing` | Toggled on/off the enablement of autoindexing for codebase context. | | `Toggle Dim Inactive Panes` | Whether the dim inactive panes feature has been toggled | | `Toggle Focus Pane On Hover` | Toggled on/off focus pane on hover feature, which causes panes to automatically focus when hovering over them | | `Toggle Git Operations Autogen Setting` | Toggled on/off the git operations autogen setting | | `Toggle Global AI Enablement` | Toggled global AI enablement. | | `Toggle Intelligent Autosuggestions Setting` | Toggled on/off the intelligent autosuggestions setting | | `Toggle Jump to Bottom of Block Button` | Enabled or disabled the Jump to Bottom of Block Button | | `Toggle Ligature Rendering` | Toggled ligature rendering | | `Toggle New Windows at Custom Size` | Whether the new windows at custom size feature has been toggled | | `Toggle Obfuscate Secret` | Revealed or hid a secret | | `Toggle Preserve Active Tab Color` | Enabled or disabled preserving the active tab color | | `Toggle Restore Session` | Toggled session restoration (“Restore windows, tabs, panes, on startup”) | | `Toggle SSH Tmux Wrapper` | Changed the setting for SSH sessions to prompt for Tmux Wrapper | | `Toggle SSH Warpification` | Changed the setting for SSH sessions to be warified | | `Toggle Same Line Prompt` | Toggled on/off same line prompt | | `Toggle Secret Redaction` | Toggled on/off the setting for Secret Redaction - attempts to redact secrets and sensitive information | | `Toggle Settings Sync` | Toggle Settings Sync | | `Toggle SharedBlock Title Generation` | Toggled on/off the shared block title generation setting | | `Toggle Show Agent Tips` | Toggled the Show Agent Tips setting in AI settings | | `Toggle Show Block Dividers` | Enabled or disabled the Show Block Dividers Button | | `Toggle Sticky Command Header in Active Pane` | Expanded or collapsed the sticky command header in the active pane | | `Toggle Sync Inputs Across All Panes in All Tabs` | Enable the synchronization of the Input Editor’s buffer to all the panes in all the tabs | | `Toggle Sync Inputs Across All Panes in Current Tab` | Enable the synchronization of the Input Editor’s buffer to all the panes in the current tab | | `Toggle Tab Indicators` | Enabled or disabled the tab indicators (failed command, etc.) | | `Toggle Voice Input Setting` | Toggled on/off the voice input setting | | `Toggle Warp AI` | Toggled Warp AI—an AI assistant to help you debug errors, look up forgotten commands and more | | `Toggled Bookmark Block` | Bookmarked or unbookmarked Block | | `Toggled Tab Bar Visibility` | Toggled when to display the tab bar | | `Tried to Execute Before Precmd` | Attempted to execute command before precmd, a shell stage that has metadata on a command such as ssh, prompt info, etc. | | `Trigger Subshell Bootstrap` | Attempted to Warpify the current session via Warp’s subshell wrapper | | `Triggered Command XRay` | Triggered Command X-Ray (hovering over a command for explanation) | | `Unable to Update To New Version` | Update available but not authorized to install | | `Undo Close` | Re-opened a closed tab or window (undo closing a tab or window) | | `Unhandled Editor Modifier Key` | Used modifier keybinding keystroke which is not currently supported | | `Unsupported Shell` | Booted Warp with a shell that isn’t supported | | `Update Block Filter Query` | When a new filter is applied to a block | | `Update Block Filter Query With Context Lines` | When the number of context lines for a block filter query is updated | | `Update Tab Close Button Position` | Updated the tab close button position | | `Updated Alt Screen Padding Mode` | Updated the custom padding setting for the alt-screen | | `Updated Sorting Choice` | Modified the sorting scheme for Warp Drive objects | | `UseAgentToolbar.SettingToggled` | User toggled the Use Agent footer setting | | `Used Warp AI Prepared Prompt` | Used one of the Warp-provided prompts, like “Show examples” | | `User Initiated Closing Something` | Attempted to either quit the app or close a window | | `User Initiated Log Out` | Confirms a user has explicitly logged out of the application | | `User Menu Upgrade Clicked` | Clicked the ‘Upgrade’ menu item in the user menu | | `VerticalTabs.DiffStatsChipClicked` | User clicked a diff stats chip in the vertical tabs panel or detail sidecar | | `VerticalTabs.DisplayOptionChanged` | User updated a display option in the vertical tabs settings popup | | `VerticalTabs.PrChipClicked` | User clicked a GitHub PR chip in the vertical tabs panel or detail sidecar | | `Vim Keybindings Banner Dismissed` | Dismissed the banner to enable Vim keybindings in the Input Editor | | `Vim Keybindings Banner Displayed` | Displayed the banner asking whether Warp should enable Vim keybindings in the Input Editor | | `Vim Keybindings Enabled from Banner` | Enabled Vim keybindings in the Input Editor from the banner | | `Warp AI Action` | Executed a Warp AI action: Restart, Copy, Insert into terminal | | `Warp AI Character Limit Exceeded` | Attempted to ask a question longer than 1k chars to Warp AI | | `Warp AI Request Issued` | Issued a question to Warp AI | | `Warp Drive Opened` | Opened Warp Drive panel | | `Warp Drive Sharing onboarding block shown` | Showed onboarding block for Warp Drive sharing | | `Warp Drive object opened on desktop` | Warp Drive object on the web was opened on the desktop | | `Warpify Footer Accepted Warpify` | User clicked Warpify in the warpify footer | | `Warpify Footer Shown` | Displayed the warpify footer for a detected subshell or SSH session | | `Web session opened on desktop` | Shared session viewed on the web was opened on the desktop | | `Workflow Executed` | Executed workflow | | `Workflow Selected` | Selected workflow and populated into the Input Editor | | `Zero State Prompt Suggestion Used` | Used a zero state prompt suggestion | | `experiments.client.enroll_client` | Client assigned to A/B test | | `onboarding_agent_slide_upgrade_clicked` | User clicked the Upgrade button on the Customize your agent slide | | `onboarding_callout_completed` | User completed the callout flow | | `onboarding_callout_displayed` | A callout was displayed to the user | | `onboarding_callout_next` | User clicked next on a callout | | `onboarding_folder_selected` | User selected a folder | | `onboarding_folder_selection_started` | User started folder selection | | `onboarding_free_user_no_ai_upgrade_clicked` | User clicked the upgrade button on the free-user no-AI experiment slide | | `onboarding_get_started_clicked` | User clicked the Get Started button | | `onboarding_setting_changed` | User changed a setting during onboarding | | `onboarding_slide_navigated_back` | User navigated to the previous slide | | `onboarding_slide_navigated_next` | User navigated to the next slide | | `onboarding_slide_viewed` | User viewed a slide in the onboarding flow | | `onboarding_slides_completed` | User completed the onboarding slides | | `onboarding_started` | User started the onboarding flow | | `onboarding_welcome_login_clicked` | User clicked the Log in link on the welcome/intro slide | | `perf_metrics.memory_usage_high` | Total application memory usage exceeded a significant threshold | | `perf_metrics.resource_usage` | Periodic report on application resource usage statistics | | `revenue.AutoReloadModalClosed` | User closed the auto-reload modal (either dismissed or enabled auto-reload) | | `revenue.AutoReloadToggledFromBillingSettings` | User toggled auto-reload in Billing & Usage settings | | `revenue.OutOfCreditsBannerClosed` | User closed the ‘Out of credits’ banner (dismissed or purchased credits) | # Secret Redaction > Secret Redaction detects and redacts secrets, passwords, API keys, and PII in your terminal output before sending data to servers. ## How to access it [Section titled “How to access it”](#how-to-access-it) Disabled by default, to enable Secret Redaction open **Settings** > **Privacy** > **Secret redaction** or type in “Secret Redaction” to toggle it in the [Command Palette](/terminal/command-palette/). ## How it works [Section titled “How it works”](#how-it-works) Secret Redaction attempts to detect sensitive data (including secrets, passwords, API keys, and PII) using your list of regex patterns. Any identified secret will be redacted instead of being sent to our servers or any LLM provider. Additionally, Warp Drive will prevent you from saving any secrets in plain text (workflows, MCP servers, prompts, etc.).\ \ Warp ships with a [list of recommended regex](/support-and-community/privacy-and-security/secret-redaction/#secret-regex-list) you can easily add to the list. Additionally you can add custom regex for secrets you want to include in **Settings** > **Privacy** > **Secret redaction** > **Custom secret redaction**. ## Visually hiding secrets [Section titled “Visually hiding secrets”](#visually-hiding-secrets) By default, identified secrets will be displayed with a strikethrough visual treatment, i.e. ` echo`` `` `~~`password`~~. If instead you’d prefer to visually hide the secrets as well, i.e. `echo ********`, the setting to obfuscate secrets with asterisks can be found in **Settings** > **Privacy** > **Secret redaction** > **Hide secrets in blocklist**. Clicking on a secret will display a tooltip that lets you reveal the secret or copy the secret’s contents. When trying to copy terminal output containing secrets, it will be copied as asterisks (e.g. `echo password` becomes `echo ********`) unless revealed or copied from the tooltip. Secret redaction is not applied in [Session Sharing](/knowledge-and-collaboration/session-sharing/). ## Case sensitivity [Section titled “Case sensitivity”](#case-sensitivity) Secret redaction regexes are case-sensitive by default (i.e. the regex `password` will not match the text `Password`). If you want a regex to be case-sensitive, you can prepend `(?i)` like so: `(?i)password` to ensure that `PASSWORD`, `Password`, and `password` would all match. ## Secret regex list [Section titled “Secret regex list”](#secret-regex-list) Here is a list of the recommended regular expressions that Warp uses to identify secrets: | Secret Type | Regex Pattern | | ----------------------------------------- | ----------------------------------------------------------------------------------------- | | IP V4 Address | `\b((25[0-5]\|(2[0-4]\|1\d\|[1-9]\|)\d)\.?\b){4}\b` | | IP V6 Address | `\b((([0-9A-Fa-f]{1,4}:){1,6}:)\|(([0-9A-Fa-f]{1,4}:){7}))([0-9A-Fa-f]{1,4})\b` | | Slack App Token | `\bxapp-[0-9]+-[A-Za-z0-9_]+-[0-9]+-[a-f0-9]+\b` | | Phone Number | `\b(\+\d{1,2}\s)?$?\d{3}$?[\s.-]\d{3}[\s.-]\d{4}\b` | | AWS Access ID | `\b(AKIA\|A3T\|AGPA\|AIDA\|AROA\|AIPA\|ANPA\|ANVA\|ASIA)[A-Z0-9]{12,}\b` | | MAC Address | `\b((([a-zA-z0-9]{2}[-:]){5}([a-zA-z0-9]{2}))\|(([a-zA-z0-9]{2}:){5}([a-zA-z0-9]{2})))\b` | | Google API Key | `\bAIza[0-9A-Za-z-_]{35}\b` | | Google OAuth ID | `\b[0-9]+-[0-9A-Za-z_]{32}\.apps\.googleusercontent\.com\b` | | GitHub Classic Personal Access Token | `\bghp_[A-Za-z0-9_]{36}\b` | | GitHub Fine Grained Personal Access Token | `\bgithub_pat_[A-Za-z0-9_]{82}\b` | | GitHub OAuth Access Token | `\bgho_[A-Za-z0-9_]{36}\b` | | GitHub User to Server Token | `\bghu_[A-Za-z0-9_]{36}\b` | | GitHub Server to Server Token | `\bghs_[A-Za-z0-9_]{36}\b` | | Stripe Key | `\b(?:r\|s)k_(test\|live)_[0-9a-zA-Z]{24}\b` | | Firebase Auth Domain | `\b([a-z0-9-]){1,30}(\.firebaseapp\.com)\b` | | JSON web token | `\b(ey[a-zA-z0-9_\-=]{10,}\.){2}[a-zA-z0-9_\-=]{10,}\b` | | OpenAI API Key | `\bsk-[a-zA-Z0-9]{48}\b` | | Anthropic API Key | `\bsk-ant-api\d{0,2}-[a-zA-Z0-9\-]{80,120}\b` | | Fireworks API Key | `\bfw_[a-zA-Z0-9]{24}\b` | # Known issues and workarounds > Known Warp issues with workarounds, including SSH, shells, and incompatible tools. Note To see a complete list of Warp issues and feature requests, please visit our [GitHub issues page](https://github.com/warpdotdev/Warp/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-desc). Please note that there are tools that are incompatible with Warp, as listed [below](/support-and-community/troubleshooting-and-support/known-issues/#list-of-incompatible-tools). You can find debugging information in this [section](/support-and-community/troubleshooting-and-support/known-issues/#debugging). ## General [Section titled “General”](#general) ### SSH [Section titled “SSH”](#ssh) To enable Blocks over SSH, Warp uses an SSH Wrapper function; navigate to settings > features if you need to disable it. Please see [Troubleshooting Legacy SSH](/terminal/warpify/ssh-legacy/#troubleshooting-ssh) for more info on workarounds to SSH issues, or see the [new SSH Page](/terminal/warpify/ssh/) for more on the upcoming features. ### Online features don’t work [Section titled “Online features don’t work”](#online-features-dont-work) There is a known issue that can occur that causes online features to break ([Oz agent](/agent-platform/local-agents/overview/), [Generate](/agent-platform/local-agents/overview/), [Block Sharing](/terminal/blocks/block-sharing/), [Refer a Friend](/support-and-community/community/refer-a-friend/) ). This is due to the login token going stale, typically due to a password change, and can be resolved by the following steps: * macOS 1. Remove Warp user login with the following command: ```bash sudo security delete-generic-password -l "dev.warp.Warp-Stable" $HOME/Library/Keychains/login.keychain ``` 2. [Login to Warp](/getting-started/quickstart/installation-and-setup/#log-in-to-warp-optional) * Windows 1. Remove any user files with the following command: ```powershell Remove-Item $env:LOCALAPPDATA\warp\Warp\data\*-User ``` 2. [Login to Warp](/getting-started/quickstart/installation-and-setup/#log-in-to-warp-optional) * Linux 1. Remove Warp user login with your keychain manager (gnome-keyring, kwallet, etc.). Search for `dev.warp.Warp` and delete the `User` password/secret. 2. Remove any user files with the following command: ```bash rm -f ${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/*-User ``` 3. [Login to Warp](/getting-started/quickstart/installation-and-setup/#log-in-to-warp-optional) ### English-only UI [Section titled “English-only UI”](#english-only-ui) Nov 2021: We have added character support for Chinese, Korean, and Japanese, but our UI currently only supports English. ### Abnormal rendering of Chinese characters [Section titled “Abnormal rendering of Chinese characters”](#abnormal-rendering-of-chinese-characters) If you notice issues with the terminal rendering Chinese characters (i.e. [#3366](https://github.com/warpdotdev/Warp/issues/3366)). Please try adding the following lines to your rc file. ```plaintext export LC_ALL=zh_CN.UTF-8 export LANG=zh_CN.UTF-8 ``` ### Warp fails to render a window [Section titled “Warp fails to render a window”](#warp-fails-to-render-a-window) This can likely occur due to some corruption in the local sqlite db. You may see a similar error your [logs](/support-and-community/#gathering-warp-logs): ```plaintext [WARN] SQLite error 283 (A WAL mode database file was recovered): recovered 383 frames from WAL file /home/xxxxx/.local/state/warp-terminal/warp.sqlite-wal ``` To try and resolve the issue of Warp not rendering a window, rename the SQLite database found in the [following locations](/terminal/sessions/session-restoration/#session-restoration-database). ### Misc. [Section titled “Misc.”](#misc) * When you [SSH](/support-and-community/troubleshooting-and-support/known-issues/#ssh), we start a bash shell on the remote host. We built a wrapper around SSH to make Warp features possible. * If your default shell is zsh, your aliases typically do not transfer over. Other shells are unsupported for now. * When you open a [non-shell-based subshell (REPL)](https://github.com/warpdotdev/Warp/issues/4082), Warp does not modify the environment — it behaves like a standard terminal session. * Warp may become unresponsive if it doesn’t have permission to access the folders. * [No touch input support](https://github.com/warpdotdev/Warp/issues/5347) ## Agent Mode [Section titled “Agent Mode”](#agent-mode) * Note that Agent Mode blocks are not shareable during [session sharing](/knowledge-and-collaboration/session-sharing/). Participants will be able to share regular shell commands that are run, but will not be able to share AI interactions (requested commands, AI blocks, etc.). * Block actions such as [Block Sharing](/terminal/blocks/block-sharing/) are not available on Agent Mode AI blocks. * Agents do not have up-to-date information on several commands’ completion specs * Agent Mode works better with Warp’s default prompt settings, where the prompt starts on a new line, than it does with a same-line prompt. If you are using the same-line prompt, the cursor will jump from the end of the single line to the start of the input box when you switch to Agent Mode. ## Shells [Section titled “Shells”](#shells) ### fish shell `read` command [Section titled “fish shell read command”](#fish-shell-read-command) There is an issue in fish shell version 3.6 and below that causes the `read` built-in command to break Warp’s integration with fish. This means that using `read` directly or any fish scripts that call `read` will not work as expected in Warp. That issue is resolved in the fish repository and so should be fixed in the next release of fish itself. We recommend upgrading fish to the most recent version to resolve this issue. ### Warp shell loads slowly due to EDR [Section titled “Warp shell loads slowly due to EDR”](#warp-shell-loads-slowly-due-to-edr) If you comment out the rc files (i.e. `~/.zshrc`, `~/.bashrc`, `~/.config/fish/config.fish`), and still notice a slowdown on loading the shell, it is likely due to an Endpoint Detection and Response or EDR (i.e. Sentinel One, CrowdStrike, Carbon Black) causing the issue. Please restart your system and see if the issue persists. If so, please [Send us Feedback](/support-and-community/) and provide details of your EDR, OS, shell, etc. ### Configuring and debugging your RC files [Section titled “Configuring and debugging your RC files”](#configuring-and-debugging-your-rc-files) To support Blocks ([custom hooks](https://blog.warp.dev/how-warp-works/#implementing-blocks)), a native Input Editor experience, AI blocks, etc. we have built custom support for a subset of shell functionality (decouple functionality from the shell and move to the terminal). This leads to Warp being incompatible with various tools and plugins. Please see the [list of incompatible](/support-and-community/troubleshooting-and-support/known-issues/#list-of-incompatible-tools) tools to find the tools that are known not to work with Warp. Unlike typical terminals which are essentially continuous character grids, each section of Warp is its own (separate) UI element. Please see our [Prompt](/terminal/appearance/prompt/) page for more information on custom prompts. #### Debugging [Section titled “Debugging”](#debugging) If Warp is not working with your dotfile configuration, you can run your shell in Warp with a clean configuration using examples below: * bash You can set up clean configs for Bash (Bourne Again SHell) by moving or commenting out your `.bashrc`\ \ If Warp starts working correctly then Warp is incompatible with something in the current dotfiles. We can isolate what is incompatible by iteratively disabling sections of our dotfiles with the `WarpTerminal` flag until we find the culprit. See the list of incompatible tools below and comment them out just for Warp with the following conditionals: ```bash # bash (See ~/.bashrc) if [[ $TERM_PROGRAM != "WarpTerminal" ]]; then ##### WHAT YOU WANT TO DISABLE FOR WARP - BELOW # Unsupported plugin/prompt code here, i.e. ##### WHAT YOU WANT TO DISABLE FOR WARP - ABOVE fi ``` * zsh You can set up clean configs for Zsh (Z SHell) by moving or commenting out your `.zshrc`\ \ If Warp starts working correctly then Warp is incompatible with something in the current dotfiles. We can isolate what is incompatible by iteratively disabling sections of our dotfiles with the `WarpTerminal` flag until we find the culprit. See the list of incompatible tools below and comment them out just for Warp with the following conditional: ```bash # zsh (See ~/.zshrc) if [[ $TERM_PROGRAM != "WarpTerminal" ]]; then ##### WHAT YOU WANT TO DISABLE FOR WARP - BELOW # Unsupported plugin/prompt code here ##### WHAT YOU WANT TO DISABLE FOR WARP - ABOVE fi ``` * fish You can set up clean configs for Fish (Friendly Interactive SHell) by moving or commenting out your `config.fish`\ \ If Warp starts working correctly then Warp is incompatible with something in the current config file. We can isolate what is incompatible by iteratively disabling sections of our config file with the `WarpTerminal` flag until we find the culprit. See the list of incompatible tools below and comment them out just for Warp with the following conditional: ```bash # fish (see ~/.config/fish/config.fish) if test "$TERM_PROGRAM" != "WarpTerminal" ##### WHAT YOU WANT TO DISABLE FOR WARP - BELOW # Unsupported plugin/prompt code here ##### WHAT YOU WANT TO DISABLE FOR WARP - ABOVE end ``` * pwsh You can set up clean configs for pwsh (PowerShell) by moving or commenting out your `$PROFILE` If Warp starts working correctly then Warp is incompatible with something in the current profile. We can isolate what is incompatible by iteratively disabling sections of our profile with the WarpTerminal flag until we find the culprit. See the list of incompatible tools below and comment them out just for Warp with the following conditional: ```powershell # pwsh (see $PROFILE) if ($env:TERM_PROGRAM -ne "WarpTerminal") { ##### WHAT YOU WANT TO DISABLE FOR WARP - BELOW # Unsupported plugin/prompt code here ##### WHAT YOU WANT TO DISABLE FOR WARP - ABOVE } ``` #### List of incompatible tools [Section titled “List of incompatible tools”](#list-of-incompatible-tools) The following non-exhaustive list of plugins, prompts, or tools can cause potential issues in Warp: * oh-my-fish, oh-my-bash, or other unsupported shell prompts. See our [Custom Prompt Compatibility Table](/terminal/appearance/prompt/#custom-prompt-compatibility-table). * [iterm shell integration](https://iterm2.com/documentation-shell-integration.html) * `test -e "${HOME}/.iterm2_shell_integration.zsh" && source "${HOME}/.iterm2_shell_integration.zsh" || true` * [Termium](https://codeium.com/blog/termium-codeium-in-terminal-launch) * `eval "$(termium shell-hook show pre)"` * `eval "$(termium shell-hook show post)"` * [thefuck experimental instant mode](https://github.com/nvbn/thefuck?tab=readme-ov-file#experimental-instant-mode) * `eval $(thefuck --alias --enable-experimental-instant-mode)` * [fubectl](https://github.com/kubermatic/fubectl) * `[ -f ${HOME}/bin/fubectl.source ] && source ${HOME}/bin/fubectl.source` * [BIND keys](https://github.com/warpdotdev/Warp/issues/537) * `bindkey '^j' down-line-or-beginning-search`, which causes users to have to hit ENTER twice to run a command. * `bindkey 'tab' autosuggest-accept`, which causes incorrect behavior with autocompletion. * `z`, `compdef`, `compinit`, [prezto utility module](https://github.com/sorin-ionescu/prezto/blob/master/modules/utility/README.md), [bash-it](https://github.com/Bash-it/bash-it), CodeWhisperer or other [shell-based completion](https://github.com/warpdotdev/Warp/discussions/434) plugins. * OH-MY-ZSH Themes * e.g. avit, spaceship, maybe more … * OH-MY-ZSH Plugins * e.g. zsh-autosuggestions, zsh-autocomplete, maybe more … * Oh-My-Tmux * zsh4h (ZSH for Humans) * znap * FZF * `[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && "/usr/local/etc/profile.d/bash_completion.sh"` * `eval "$(rbenv init -)"` * `grml-zsh-config` * Python virtual environment PS1 [settings](https://github.com/warpdotdev/Warp/issues/2713#issuecomment-1447129449) * [Starship settings](/terminal/appearance/prompt/#starship-settings) * `zle-line-init` * Potentially more — this is a non-exhaustive list. If you find an incompatible tool, please email us at ## Operating systems [Section titled “Operating systems”](#operating-systems) * macOS **SSH to local network device is denied on macOS** On macOS, you may be [denied permission to SSH](https://github.com/warpdotdev/Warp/issues/5550) from Warp into other devices in your local network and see an error like: `ssh: connect to host port 22: Undefined error: 0`.\ To resolve this issue, go to  > **System Settings** > **Privacy & Security** > **Local Network** and add Warp. ![macOS SSH permission error](/_astro/mac-ssh-permission.L2O2J4WZ_TXOSL.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) An SSH permission error on macOS. **Unexpected loss of permission on macOS** On macOS, you may see an `Operation not permitted` error when trying to run commands in directories that have already been granted macOS permissions (Documents, Downloads, Desktop, etc). The best workaround at this time is to [apply any pending updates](/support-and-community/troubleshooting-and-support/updating-warp/) so that the new Warp binary has the correct permissions. We are tracking this issue [here](https://github.com/warpdotdev/Warp/issues/3009). ![Permission error on macOS](/_astro/permission-error-macos.BCgx93R3_2k1uwX.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) A file permission error dialog on macOS. **Auto-Update error on macOS** Warp may have an error opening after auto-update on macOS Ventura. This issue has been resolved for current and future releases of Warp. To avoid the issue, [update Warp](/support-and-community/troubleshooting-and-support/updating-warp/) *before* you upgrade to macOS Ventura.\ \ If you experience an error opening Warp, please try the following: * Go to the macOS Applications folder, right-click on Warp, choose Open, then the ‘“Warp” is damaged’ dialog will have the option to click the Open button. [![](/assets/support-and-community/open-warp-mac.poster.jpg)](/assets/support-and-community/open-warp-mac.mp4) * If the above doesn’t work, [uninstall Warp](/support-and-community/troubleshooting-and-support/logging-out-and-uninstalling/), then [re-install Warp](/getting-started/quickstart/installation-and-setup/). **Running x86 commands with macOS** In some cases, CLI applications only work on x86, so you can run Warp with Rosetta on macOS to be able to use them by doing the following. * Go to **Finder** > **Applications** and search for Warp. * Right-click and select Get Info. * Then check the box on Open with Rosetta. * Windows **Unsupported in Warp on Windows** The following features are not supported in Warp on Windows. Please track the relevant GitHub issues linked below for any changes: * [cmd.exe](https://github.com/warpdotdev/Warp/issues/5882) or [fish](https://github.com/warpdotdev/Warp/issues/6060) shells **Warp won’t run on Windows** We’re tracking some issues on Windows where [Warp crashes on startup](https://github.com/warpdotdev/Warp/issues/5840) or doesn’t render, with some possible workarounds below. If none of the workarounds help, please open a [new GitHub issue](https://github.com/warpdotdev/warp/issues/new/choose) and include [logs](/support-and-community/#gathering-warp-logs), installation (Baremetal or VM, x86\_64 or ARM64), and the issue you had. * Graphics * You can select the graphics backend used to render new Warp windows in the Settings menu, under **Features** > **System** > **Preferred graphics backend**. * You can also opt to render new Warp windows with an integrated GPU, under **Features** > **System** > **Prefer rendering new windows with integrated GPU (low power)**. **Crash on opening a Launch configuration or doesn’t become transparent on Windows** When a user has an Nvidia 572.xx or AMD 23.10.x drivers or above, Warp may [crash when trying to open a Launch Configuration](https://github.com/warpdotdev/Warp/issues/5875), or [Warp fails to become transparent](https://github.com/warpdotdev/Warp/issues/5903) (opacity setting doesn’t work). These are known limitations of the graphics drivers. We’re investigating the issues and will update the GitHub issues above. You can workaround this by forcing the graphics backend to Vulkan or OpenGL by running the following from another terminal and setting your GPU driver Vulkan/OpenGL render method setting to “Prefer Native”, or using the [DX12 backend](/support-and-community/troubleshooting-and-support/known-issues/#warp-wont-run-or-render-on-windows): ```powershell # Run if Warp on Windows is installed for a single user $env:WGPU_BACKEND="vulkan,gl"; & "$env:LOCALAPPDATA\Programs\Warp\warp.exe" # Run if Warp on Windows is installed for all users $env:WGPU_BACKEND="vulkan,gl"; & "$env:PROGRAMFILES\Warp\warp.exe" ``` * Linux **Warp won’t run on Linux** We’re tracking some issues on Linux where a [Warp window doesn’t show/render](https://github.com/warpdotdev/Warp/issues/4215) and won’t run in [Virtual Machines](https://github.com/warpdotdev/Warp/issues/4476), over [remote desktops](https://github.com/warpdotdev/Warp/issues/4435), or on [WSL](https://github.com/warpdotdev/Warp/issues/4240). Some possible workarounds are below. If none of the workarounds help, please open a [new GitHub issue](https://github.com/warpdotdev/warp/issues/new/choose) and include [logs](/support-and-community/#gathering-warp-logs) with your Linux distro, installation (WSL, Baremetal or VM, x86\_64 or ARM64), and the issue you had. Note * Many package install examples are for Ubuntu using `apt`, your distro may use different commands (`dnf`, `pacman`, `zypper`) or package names. * GPU Drivers and Default GPU / Graphics API environment variables are system-dependent, e.g. AMD vs NVIDIA and OpenGL vs Vulkan. - System * Installing or Updating [Xorg](https://www.x.org/wiki/) / [Wayland](https://wayland.freedesktop.org/): `sudo apt install xserver-xorg` / `sudo apt install wayland` * Installing [Hack font](https://sourcefoundry.org/hack/) on WSL and VMs: `sudo apt install fonts-hack` * Install [WSL utilities](https://github.com/wslutilities/wslu): `sudo apt install wslu` * Install Mesa utilities: `sudo apt install mesa-utils` * Install Mesa Vulkan drivers: `sudo apt install mesa-vulkan-drivers` * If unable to use the file picker: `sudo apt install xdg-desktop-portal xdg-desktop-portal-gtk zenity` * If unable to copy-paste: `sudo apt install wl-clipboard` - Graphics * Install or Update your GPU driver: e.g. [NVIDIA](https://github.com/warpdotdev/Warp/issues/4215#issuecomment-1969750786) 535.x or below drivers * For Ubuntu: `sudo ubuntu-drivers install` * For Fedora: `sudo dnf install akmod-nvidia` * For Arch Linux: `sudo pacman -S nvidia` * For openSUSE: `sudo zypper install x11-video-nvidiaG05` * Use [Low Power (integrated) GPU](https://github.com/warpdotdev/Warp/issues/4215#issuecomment-1967500574) in `~/.config/warp-terminal/user_preferences.json` file: `{"prefs":{"PreferLowPowerGPU": "true",}}`. The low-power workaround is particularly helpful if you see [`Unrecognized device error ERROR_INITIALIZATION_FAILED` in warp.log](https://github.com/warpdotdev/Warp/issues/4390#issuecomment-1989493913). - Environmental Variables * Prefix `warp-terminal` with the variables (multiple can be used), and once you confirm they work, `export` them in your `.profile`/`.zprofile` to [load on startup](https://github.com/warpdotdev/Warp/issues/4240#issuecomment-1968228029): * [Default to Wayland](https://github.com/warpdotdev/Warp/issues/4240#issuecomment-1961993281): `WARP_ENABLE_WAYLAND=1` * Set [Default GPU](https://docs.mesa3d.org/drivers/d3d12.html#utilities) for WSL: e.g. `MESA_D3D12_DEFAULT_ADAPTER_NAME=NVIDIA` * Set [Graphics APIs](https://github.com/gfx-rs/wgpu?tab=readme-ov-file#environment-variables): e.g. `WGPU_BACKEND=gl` **Update fails after upgrading Linux** Some Linux distros may modify Warp’s package repository during the OS upgrades. We’re aware of this on Ubuntu, but this may affect other Linux distros. We’re tracking this issue on GitHub [here](https://github.com/warpdotdev/Warp/issues/5201).\ \ To workaround this issue, manually add the repository to update Warp. The Ubuntu example is below: ```plaintext sudo apt-get install wget gpg wget -qO- https://releases.warp.dev/linux/keys/warp.asc | gpg --dearmor > warpdotdev.gpg sudo install -D -o root -g root -m 644 warpdotdev.gpg /etc/apt/keyrings/warpdotdev.gpg sudo sh -c 'echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/warpdotdev.gpg] https://releases.warp.dev/linux/deb stable main" > /etc/apt/sources.list.d/warpdotdev.list' rm warpdotdev.gpg sudo apt update && sudo apt install warp-terminal ``` See the instructions for other Linux distros on our [quickstart guide](/getting-started/quickstart/installation-and-setup/#linux). # Logging out & uninstalling > How to log out from Warp, and how to uninstall Warp. ## Logging out [Section titled “Logging out”](#logging-out) You can log out of Warp through: * **Settings** > **Account**, with the “Log out” button * [Command Palette](/terminal/command-palette/), with the “Log out” item. [![](/assets/support-and-community/logout.poster.jpg)](/assets/support-and-community/logout.mp4) ### Known issues: [Section titled “Known issues:”](#known-issues) 1. When you log out, you will lose all running processes and all unsaved objects. 2. When you log out and log in to Warp with another account, the following preferences will be preserved from the original account: 1. Theme 2. Keybindings 3. Settings (e.g. autosuggestion, notifications, font size, welcome tips status) 3. Whenever you log in to Warp, you will receive the onboarding survey. ## Uninstalling Warp [Section titled “Uninstalling Warp”](#uninstalling-warp) Removing Warp from your computer involves uninstalling Warp and then removing any files or data. Note If you’re using Warp Preview, replace “Warp-Stable” with “Warp-Preview” in the commands below (e.g., `defaults delete dev.warp.Warp-Preview`). * macOS **Uninstalling Warp by dmg** * Remove Warp with `sudo rm -r /Applications/Warp.app` * Open **Finder** > **Applications**, right-click on Warp, and select “Move to Trash” **Uninstalling Warp by Homebrew** * Remove Warp with `brew uninstall warp` **Removing Warp settings, files, logs, and database** ```bash # Remove Warp settings defaults defaults delete dev.warp.Warp-Stable # Remove Warp logs sudo rm -r $HOME/Library/Logs/warp.log # Remove Warp database, Codebase Context, and MCP logs sudo rm -r "$HOME/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Stable" # Remove Warp user files, themes, and launch configurations sudo rm -r $HOME/.warp # Note: Removing $HOME/.warp will delete files for both Stable and Preview. # If you wish to delete it all, then: sudo rm -r $HOME/.warp ``` **For Warp Preview users:** ```bash # Remove Warp Preview settings defaults defaults delete dev.warp.Warp-Preview # Remove Warp Preview logs sudo rm -r $HOME/Library/Logs/warp_preview.log # Remove Warp Preview database, Codebase Context, and MCP logs sudo rm -r "$HOME/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Preview" # Note: Removing $HOME/.warp will delete files for both Preview and Stable. # If you wish to delete it all, then: sudo rm -r $HOME/.warp ``` * Windows **Uninstalling Warp by WinGet** ```powershell winget uninstall Warp.Warp ``` **Uninstalling Warp installed by Installer** * Search for “Installed apps” section of the Control Panel. * Search for and Uninstall the Warp application **Removing Warp settings, files, logs, and database** ```powershell # Remove Warp settings in the Windows Registry Remove-Item -Path "HKCU:\Software\Warp.dev\Warp" -Recurse -Force # Remove Warp user files, logs, database, Codebase Context, and MCP logs Remove-Item -Path "$env:LOCALAPPDATA\warp\Warp" -Recurse -Force # Remove Warp themes and launch configurations Remove-Item -Path "$env:APPDATA\warp\Warp" -Recurse -Force ``` **For Warp Preview users:** ```powershell # Remove Warp Preview settings in the Windows Registry Remove-Item -Path "HKCU:\Software\Warp.dev\Warp-Preview" -Recurse -Force # Remove Warp Preview user files, logs, database, Codebase Context, and MCP logs Remove-Item -Path "$env:LOCALAPPDATA\warp\Warp-Preview" -Recurse -Force # Remove Warp Preview themes and launch configurations Remove-Item -Path "$env:APPDATA\warp\Warp-Preview" -Recurse -Force ``` * Linux **Uninstalling Warp by package manager** ```bash # apt uninstall sudo apt remove warp-terminal # dnf uninstall sudo dnf remove warp-terminal # zypper uninstall sudo zypper remove warp-terminal # pacman uninstall sudo pacman -R warp-terminal ``` * Uninstall Warp using the same package manager that you used to [install](/getting-started/quickstart/installation-and-setup/) it. **Removing Warp settings, files, logs, and database** ```bash # Remove Warp settings files rm -r ${XDG_CONFIG_HOME:-$HOME/.config}/warp-terminal # Remove Warp user files, logs, database, Codebase Context, and MCP logs rm -r ${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal # Remove Warp themes and launch configurations rm -r ${XDG_STATE_HOME:-$HOME/.local/share}/warp-terminal ``` **For Warp Preview users:** ```bash # apt uninstall sudo apt remove warp-terminal-preview # dnf uninstall sudo dnf remove warp-terminal-preview # zypper uninstall sudo zypper remove warp-terminal-preview # pacman uninstall sudo pacman -R warp-terminal-preview ``` * Uninstall Warp Preview using the same package manager that you used to install it. ```bash # Remove Warp Preview settings files rm -r ${XDG_CONFIG_HOME:-$HOME/.config}/warp-terminal-preview # Remove Warp Preview user files, logs, database, Codebase Context, and MCP logs rm -r ${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal-preview # Remove Warp Preview themes and launch configurations rm -r ${XDG_STATE_HOME:-$HOME/.local/share}/warp-terminal-preview ``` # Sending feedback and logs > Send Warp feedback, bug reports, and feature requests, and gather logs, crash reports, CPU samples, and AI conversation IDs to attach to them. ### Sending Warp feedback [Section titled “Sending Warp feedback”](#sending-warp-feedback) * Use the [`/feedback`](#using-feedback-in-warp) slash command inside Warp to draft and file a GitHub issue without leaving the terminal. * Open a new bug or feature request in our [GitHub repository](https://github.com/warpdotdev/warp/issues/new/choose). * Join our [Warp Community Slack](https://go.warp.dev/join-preview) and share feedback in **#feedback-general**, or **#feedback-preview** if it is specific to [Warp Preview](/support-and-community/community/warp-preview-and-alpha-program/). * For security issues or questions, email . * For questions about privacy, email . #### Subscriber and Enterprise [Section titled “Subscriber and Enterprise”](#subscriber-and-enterprise) * For subscriber technical issues or questions (bugs, credits, etc.), email . * For subscriber billing issues or questions (refunds, cancellation, etc.), email . * For enterprise, please direct all feedback and issues to your designated Slack channel. [![](/assets/support-and-community/send-feedback-demo.poster.jpg)](/assets/support-and-community/send-feedback-demo.mp4) ## Using `/feedback` in Warp [Section titled “Using /feedback in Warp”](#using-feedback-in-warp) The `/feedback` [slash command](/agent-platform/capabilities/slash-commands/) is the fastest way to report a Warp bug, flag a regression, or file a feature request from inside the terminal. It files issues against [`warpdotdev/warp`](https://github.com/warpdotdev/warp) so the Warp team can triage reports quickly. `/feedback` has two flows, and Warp picks the right one automatically based on whether AI is enabled for your account: * **AI enabled** — the Agent drafts and files the issue for you. * **AI disabled** — Warp opens the GitHub new-issue picker in your browser so you can write and submit the report yourself. ### With AI enabled [Section titled “With AI enabled”](#with-ai-enabled) When AI is enabled, `/feedback` hands your report to the Agent, which polishes and files your issue in a single turn. The Agent: 1. **Classifies** your report by type (bug, regression, UX issue, or feature request). 2. **Asks clarifying questions** only when the report is too vague to draft responsibly. For example, when expected behavior, reproduction steps, or the affected platform aren’t clear. 3. **Checks for duplicates** in `warpdotdev/warp` and, if a likely duplicate exists, links you to that issue instead of filing a new one. 4. **Files the issue** in `warpdotdev/warp`, either directly or by opening a prefilled new-issue page in your browser. Note This flow uses the Agent to draft your issue, so it consumes [credits](/support-and-community/plans-and-billing/credits/) like any other Agent conversation. #### Attaching screenshots [Section titled “Attaching screenshots”](#attaching-screenshots) You can attach screenshots to your `/feedback` request the same way you attach images to any other Agent prompt (drag-and-drop into the input, paste from the clipboard, or use the attach button). When one or more images are attached, the Agent: * Includes a short caption for each screenshot in the drafted issue body, so the report stays coherent even if an image never makes it to the final GitHub issue. * Opens the prefilled new-issue page in your browser with placeholder lines (for example, `_Paste screenshot 1 here_`) indicating exactly where to drop each image. Screenshots have to be added in the browser because GitHub doesn’t yet support attaching images to issues over its API. * Reminds you in its final reply that the issue is drafted but not filed. To complete filing, drop your screenshots into the placeholder lines and click **Submit new issue**. ### With AI disabled [Section titled “With AI disabled”](#with-ai-disabled) When AI is disabled for your account, `/feedback` (and the **Feedback** button in Warp Essentials) skips the Agent and opens the GitHub new-issue picker for `warpdotdev/warp` directly in your browser, with your current Warp version and operating system prefilled as query parameters. No Agent is invoked and no credits are consumed. You write and submit the issue yourself through GitHub’s web UI. If you’re unsure whether AI is enabled for your account, open the Warp app and go to **Settings** > **Agents** > **Warp Agent**. ### What to include [Section titled “What to include”](#what-to-include) Whether you use the `/feedback` slash command or file an issue manually, a good feedback report answers these questions up front: * **What happened?** Describe the observed behavior in one or two sentences. * **What did you expect?** Describe the behavior you expected instead. * **How do we reproduce it?** List numbered steps when possible. If you can’t reproduce the issue reliably, mention that too. * **What version of Warp are you on?** `/feedback` fills this in automatically; for manual reports, copy it from **Settings** > **Account**. * **Logs, screenshots, or conversation IDs.** See [Gathering Warp Logs](#gathering-warp-logs), [Collecting crash reports on macOS](#collecting-crash-reports-on-macos), or [Gathering AI conversation ID](#gathering-ai-conversation-id) below. See the [Slash Commands reference](/agent-platform/capabilities/slash-commands/) for the full list of commands available in Warp. ## Gathering Warp Logs [Section titled “Gathering Warp Logs”](#gathering-warp-logs) Retrieve Warp’s logs by following the instructions for your platform below. Locate the log file and attach it to your GitHub issue or email. Note Warp’s logs and crash reports ***do not*** contain any console input or output. See more on how we handle [Crash Reports and Telemetry](/support-and-community/privacy-and-security/privacy/#what-telemetry-data-are-you-collecting-and-why). * macOS The Warp log files are located at `~/Library/Logs/`. **Warp logs on macOS** Run the following to zip the Warp logs to your Desktop: ```bash zip -j ~/Desktop/warp-logs.zip ~/Library/Logs/warp.log* ``` **Warp Preview logs on macOS** Run the following to zip the Warp Preview logs to your Desktop: ```bash zip -j ~/Desktop/warp_preview-logs.zip ~/Library/Logs/warp_preview.log* ``` Caution If your issue is graphical (e.g. no display of windows) or a crash, please run Warp with the following command to capture more log information: ```bash # Run if Warp on macOS is installed RUST_LOG=wgpu_core=info,wgpu_hal=info /Applications/Warp.app/Contents/MacOS/stable # Run if Warp Preview on macOS is installed RUST_LOG=wgpu_core=info,wgpu_hal=info /Applications/WarpPreview.app/Contents/MacOS/preview ``` * Windows The Warp log files are located at `$env:LOCALAPPDATA\warp\Warp\data\logs\`. **Warp logs on Windows** Close Warp and run the following from another terminal to zip the logs to your Desktop: ```powershell Compress-Archive -Path "$env:LOCALAPPDATA\warp\Warp\data\logs\warp.log*" -DestinationPath "$([Environment]::GetFolderPath('Desktop'))\warp-logs.zip" ``` **Warp Preview logs on Windows** Close Warp Preview and run the following from another terminal to zip the logs to your Desktop: ```powershell Compress-Archive -Path "$env:LOCALAPPDATA\warp\WarpPreview\data\logs\warp_preview.log*" -DestinationPath "$([Environment]::GetFolderPath('Desktop'))\warp_preview-logs.zip" ``` Caution If your issue is graphical (e.g. no display of windows) or a crash, please run Warp with the following command to capture more log information: ```powershell # Run if Warp on Windows is installed for a single user $env:RUST_LOG="wgpu_core=info,wgpu_hal=info"; & "$env:LOCALAPPDATA\Programs\Warp\warp.exe" # Run if Warp on Windows is installed for all users $env:RUST_LOG="wgpu_core=info,wgpu_hal=info"; & "$env:PROGRAMFILES\Warp\warp.exe" # Run if Warp Preview on Windows is installed for a single user $env:RUST_LOG="wgpu_core=info,wgpu_hal=info"; & "$env:LOCALAPPDATA\Programs\WarpPreview\preview.exe" # Run if Warp Preview on Windows is installed for all users $env:RUST_LOG="wgpu_core=info,wgpu_hal=info"; & "$env:PROGRAMFILES\WarpPreview\preview.exe" ``` * Linux The Warp log files are located at `~/.local/state/warp-terminal/`. **Warp logs on Linux** Run the following to zip the Warp logs to your home directory: ```bash (cd ~/.local/state/warp-terminal && tar -czf ~/warp-logs.tar.gz warp.log*) ``` **Warp Preview logs on Linux** Run the following to zip the Warp Preview logs to your home directory: ```bash (cd ~/.local/state/warp-terminal-preview && tar -czf ~/warp_preview-logs.tar.gz warp_preview.log*) ``` Caution If your issue is graphical (e.g. no display of windows) or a crash, please run Warp with the following command to capture more log information: ```bash # Run if Warp on Linux is installed RUST_LOG=wgpu_core=info,wgpu_hal=info MESA_DEBUG=1 EGL_LOG_LEVEL=debug warp-terminal # Run if Warp Preview on Linux is installed RUST_LOG=wgpu_core=info,wgpu_hal=info MESA_DEBUG=1 EGL_LOG_LEVEL=debug warp-terminal-preview ``` ## Collecting crash reports on macOS [Section titled “Collecting crash reports on macOS”](#collecting-crash-reports-on-macos) If Warp crashes, macOS may generate `.ips` crash report files in `~/Library/Logs/DiagnosticReports/`. Run the following to collect all Warp crash reports into a zip on your Desktop: ```bash files=$(find ~/Library/Logs/DiagnosticReports -name "*.ips" -exec grep -l "dev\.warp" {} + 2>/dev/null) && [ -n "$files" ] && echo "$files" | xargs zip -j ~/Desktop/warp-crash-logs.zip || echo "No Warp crash reports found." ``` Attach the resulting `warp-crash-logs.zip` to your [bug report](/support-and-community/troubleshooting-and-support/sending-us-feedback/#sending-warp-feedback). Note This command searches crash report files for Warp’s bundle identifier, so it works across all Warp channels (Stable, Preview). ## Collecting debug info on Windows [Section titled “Collecting debug info on Windows”](#collecting-debug-info-on-windows) Occasionally, the Warp team may ask you to provide debugging information on Windows OS in particular with one of the following: ```powershell # If Warp is in your PATH, Run: warp --dump-debug-info # Otherwise you may need to use an absolute path and ... # Warp on Windows is installed for a single user, Run: & $env:LOCALAPPDATA\programs\Warp\warp.exe --dump-debug-info # Warp on Windows is installed for all users, Run: & $env:PROGRAMFILES\Warp\warp.exe --dump-debug-info ``` ## Collecting CPU samples [Section titled “Collecting CPU samples”](#collecting-cpu-samples) Certain conditions can cause Warp to use more CPU than expected or become unresponsive. Collecting a CPU sample while the issue is happening is the best way to report it. The sample provides the information the Warp team needs to identify and fix the root cause. Collect a sample using the steps for your platform and attach it to a new [GitHub issue](https://github.com/warpdotdev/warp/issues/new/choose). * macOS 1. Reproduce the high CPU usage or unresponsiveness in Warp. 2. While the issue is occurring, open **Activity Monitor**, select the **Warp** process, and click **Sample Process**. ![Sampling the Warp process in Activity Monitor](/_astro/activity-monitor-sample-process.BkM5Xn6C_Z2alsFU.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Sampling a Warp process in Activity Monitor. 3. Save the resulting sample and attach it to your GitHub issue. * Windows Install [`samply`](https://github.com/mstange/samply) to record a CPU trace: ```powershell powershell -ExecutionPolicy Bypass -c "irm https://github.com/mstange/samply/releases/download/samply-v0.13.1/samply-installer.ps1 | iex" ``` 1. Find the Warp process ID: ```powershell Get-Process *warp* ``` 2. Start recording, replacing `` with the process ID from the previous step: ```powershell samply record -p ``` 3. Reproduce the issue that causes high CPU usage or unresponsiveness. 4. Press `Ctrl+C` to stop recording. `samply` opens the profile in the Firefox Profiler in your browser. Click the upload icon in the top-right corner to generate a shareable link, then paste it into your GitHub issue. * Linux Install [`samply`](https://github.com/mstange/samply) to record a CPU trace: ```bash curl --proto '=https' --tlsv1.2 -LsSf https://github.com/mstange/samply/releases/download/samply-v0.13.1/samply-installer.sh | sh ``` Caution `samply` requires access to Linux perf events. If you get a permission error, run: ```bash echo '-1' | sudo tee /proc/sys/kernel/perf_event_paranoid ``` 1. Start recording the Warp process: ```bash samply record -p $(pgrep -f warp-terminal) ``` 2. Reproduce the issue that causes high CPU usage or unresponsiveness. 3. Press `Ctrl+C` to stop recording. `samply` opens the profile in the Firefox Profiler in your browser. Click the upload icon in the top-right corner to generate a shareable link, then paste it into your GitHub issue. Note If you prefer not to install `samply`, you can use the built-in `perf` tool instead: ```bash perf record -g -p $(pgrep -f warp-terminal) -- sleep 30 ``` Attach the resulting `perf.data` file from your current directory to your GitHub issue. ## Gathering AI conversation ID [Section titled “Gathering AI conversation ID”](#gathering-ai-conversation-id) To gather the conversation ID, `RIGHT-CLICK` on the AI conversation block in question and select “Copy conversation ID”, then paste that into the [bug report](/support-and-community/troubleshooting-and-support/sending-us-feedback/#sending-warp-feedback) that you submit so that our team can investigate the issue. Whenever there is an error in the Agent Conversation, there will also be an option to directly copy the conversation ID for the bug report. ![Agent Mode error message with Send Feedback button and debug information containing request and conversation IDs](/_astro/send-feedback-debugging-information.BLTgHC0V_ZRJ1Vz.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) # Troubleshooting Login > Fix common login issues including SSO, proxies, ad blockers, and auth tokens. ## Can’t sign up for or log into Warp [Section titled “Can’t sign up for or log into Warp”](#cant-sign-up-for-or-log-into-warp) Clicking it should open a signup or login pop-up. If clicking the button opens a blank pop-up window, try using a proxy. Your ISP or Firewall may be blocking the app’s call to `*.googleapis.com`. Note In some older Ruby development environments, `.dev` domains do not resolve properly and you may need to delete the `/etc/resolver/dev`, see more [here](https://superuser.com/questions/1374892/dev-domains-dont-resolve). ## All browsers [Section titled “All browsers”](#all-browsers) This error could occur if you installed an ad blocker or have stale browser cookies, including our Firebase auth pop-up. **To fix it:** 1. Disable your ad blocker for `app.warp.dev` 2. Clear any cookies and cache, or open an incognito / private browser window 3. Try again ### Safari [Section titled “Safari”](#safari) If you are using Safari, you may see the following messages in your console: 1. `Unable to access localStorage` 2. And every time you click the “Sign Up” button, you get `Unhandled Promise Rejection: Error: This operation is not supported in the environment the application is running on. "location.protocol" must be http, https, or chrome-extension and web storage must be enabled.` This error likely occurs because you are blocking all cookies in Safari’s security settings, but Firebase Auth requires the cookie to record whether the user is logged in. **To fix it:** 1. Go to Safari Preferences > Privacy 2. Uncheck the “Block all cookies” checkbox ## Proxies [Section titled “Proxies”](#proxies) When behind a proxy, a possible workaround is to disable QUIC in the browser. It will then fall back to TCP and likely allow login. * In Chrome, or Chromium-based browsers like Edge, Opera, and Arc, type `chrome://flags` into the address bar. 1. In the search bar on the flags page, type `Experimental QUIC protocol`. 2. Locate the “Experimental QUIC protocol” flag and click on the drop-down menu next to it. 3. Select “Disabled” from the options. 4. Relaunch Chrome for the changes to take effect. * In Firefox, type `about:config` into the address bar. 1. You will see a warning message. Click on the “Accept the Risk and Continue” button. 2. In the search bar, type `network.http.http3.enable`. 3. Double-click on the `network.http.http3.enable` preference to set its value to `false`. This will disable QUIC in Firefox. 4. Restart Firefox for the changes to take effect. * In Safari, unfortunately, there is no built-in option to disable QUIC in Safari. Safari uses QUIC as its default transport protocol and does not provide a user-accessible setting to disable it. ## SSO login [Section titled “SSO login”](#sso-login) ### Can’t open Warp from SSO [Section titled “Can’t open Warp from SSO”](#cant-open-warp-from-sso) When directly launching Warp from Okta or other SSO providers’, you may see an error message like “`Unable to process request due to missing initial state...`”. This is due to a limitation with Warp authentication APIs. Instead, do the following: 1. Go to [app.warp.dev/login](http://app.warp.dev/login) 2. Choose “Continue with SSO” 3. Login with your normal SSO credentials ### I logged in with another method before and now can’t use SSO [Section titled “I logged in with another method before and now can’t use SSO”](#i-logged-in-with-another-method-before-and-now-cant-use-sso) In cases where you logged in with another method, please do the following to fix SSO login: 1. Go to [app.warp.dev/login](http://app.warp.dev/login) 2. Login with the original method that you used to create your Warp account (email, Google, GitHub). 3. Once logged in, go to [app.warp.dev/link\_sso](https://app.warp.dev/link_sso) 4. This should link your login to SSO. You can now proceed to login with “Continue with SSO”. ## Flagged as fraudulent [Section titled “Flagged as fraudulent”](#flagged-as-fraudulent) If you received the message “This account has been flagged as fraudulent.”, this means that you have failed one or more checks in our fraud detection system, and you will be unable to authenticate to Warp or leverage AI features. Please note that creating multiple accounts or using throwaway emails is against our [Terms of Service](https://www.warp.dev/terms-of-service) and increases the chance of triggering this system significantly. ### False positives [Section titled “False positives”](#false-positives) At times, ad-blockers or systems like Pi-hole may falsely trigger this system. You may be able to remediate this error by temporarily disabling these and attempting login again. ### Requesting an appeal [Section titled “Requesting an appeal”](#requesting-an-appeal) If you are still unable to authenticate, you may email to request an appeal. Please include the email of the account you are experiencing the issue on so a member of our support team can investigate. This may take 5-10 days. If you have an active subscription and continue to have login issues, please see the rest of the recommendations on [this page](/support-and-community/troubleshooting-and-support/troubleshooting-login-issues/#get-help-with-login-issues). ## How to get an Auth token to login [Section titled “How to get an Auth token to login”](#how-to-get-an-auth-token-to-login) If the browser does not open from Warp directly when you click “Sign up” or “Sign in”. Please go to the [Signup](https://app.warp.dev/signup) page to create an account or [Login](https://app.warp.dev/login) page if you already have one, then copy the auth token from the “here” link on the logged\_in page and paste it into Warp. If nothing happens when you click “Take me to Warp” on the logged-in page. If this happens to you, copy the “here” link on the web logged-in page ([https://app.warp.dev/logged\\\_in](https://app.warp.dev/logged%5C_in)) to copy the authentication token, then paste it into the app as shown below. Caution On Linux and Windows, the default copy-and-paste [Keyboard shortcuts](/getting-started/keyboard-shortcuts/) are `CTRL+SHIFT+C` and `CTRL+SHIFT+V` respectively.\ \ On Linux and WSL you should install and set your default `$BROWSER` to `brave-browser` to workaround any copy-paste issues. Please see the workaround guide below. [![](/assets/support-and-community/auth-token-demo.poster.jpg)](/assets/support-and-community/auth-token-demo.mp4) ![Authentication Token macOS](/_astro/auth-token-flow.BUL_fP4c_1qoLtE.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) If “Take me to Warp” is still not working it may be due to a [proxy issue](/support-and-community/troubleshooting-and-support/troubleshooting-login-issues/#proxies), please see this article for more information on a workaround [here](https://embiid.blog/post/WARP-does-not-work-after-submitting-an-invite-code/). ## Get help with login issues [Section titled “Get help with login issues”](#get-help-with-login-issues) If Sign Up or Login does not work after trying the steps above, please [contact us](https://www.warp.dev/contact) for support. # Updating Warp > Check for updates, troubleshoot auto-update permissions, and refresh signing keys. Warp automatically checks for updates on startup, and periodically while running, by connecting to `releases.warp.dev`. A notification will appear in the top right corner of the Warp window when a new update is available. ![Update Available](/_astro/update-available.DT9XqMJi_Zq9uvO.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) To check for updates, search for “update” in the [Command Palette](/terminal/command-palette/) or go to **Settings** > **Account** and click “Check for Update”. [![](/assets/support-and-community/check-for-update.poster.jpg)](/assets/support-and-community/check-for-update.mp4) If nothing happens, it means you already have the latest stable build. ## macOS: Auto-update permissions issues [Section titled “macOS: Auto-update permissions issues”](#macos-auto-update-permissions-issues) Warp cannot auto-update if it does not have the correct permissions to replace the running version of Warp. If this is the case, a banner will prompt you to manually update Warp. ![Update Available](/_astro/update-available-bar.Ch4XRZOu_Zf4jSL.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) There are 2 main causes of this: 1. You opened Warp directly from the mounted volume instead of dragging it into your Applications directory. If this is the case, the easiest fix is to quit Warp, drag the application into /Applications, and restart Warp. 2. You are a non-Admin user. This can happen if you use a computer with multiple profiles. If you have admin access on the computer, opening the app with the admin user should fix the auto-update issues. Note (Oct 2022): There is a known issue with [auto-update on macOS Ventura](/support-and-community/troubleshooting-and-support/known-issues/#auto-update-on-macos-ventura). ## Linux: Refreshing the package signing key [Section titled “Linux: Refreshing the package signing key”](#linux-refreshing-the-package-signing-key) If you encounter signature verification errors when trying to update Warp on Linux, you may need to refresh the package signing key. This can happen if the key on your system has expired. ### Debian / Ubuntu (apt) [Section titled “Debian / Ubuntu (apt)”](#debian--ubuntu-apt) You may see an error like the following: ```plaintext W: GPG error: https://releases.warp.dev/linux/deb stable Release: The following signatures were invalid: EXPKEYSIG 31F4254AFE49E02E Warp Linux Maintainers (Package Signing Authority) E: The repository 'https://releases.warp.dev/linux/deb stable Release' is not signed. ``` To fetch the updated signing key, run: ```bash curl -fsSL https://releases.warp.dev/linux/keys/warp.asc | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/warpdotdev.gpg > /dev/null ``` Then retry your update: ```bash sudo apt update && sudo apt install warp-terminal ``` ### Fedora / RHEL / CentOS (dnf/yum) [Section titled “Fedora / RHEL / CentOS (dnf/yum)”](#fedora--rhel--centos-dnfyum) You may see an error like the following: ```plaintext OpenPGP check for package "warp-terminal-v0.2026.01.28.08.14.stable_04-1.x86_64" (/var/cache/libdnf5/warpdotdev-4ac10ef632833104/packages/warp-terminal-v0.2026.01.28.08.14.stable_04-1.x86_64.rpm) from repo "warpdotdev" has failed: Problem occurred when opening the package. ``` To fetch the updated signing key, run: ```bash sudo rpm --import https://releases.warp.dev/linux/keys/warp.asc ``` Then retry your update: ```bash sudo dnf upgrade warp-terminal # or for older systems: sudo yum upgrade warp-terminal ``` ### Arch Linux (pacman) [Section titled “Arch Linux (pacman)”](#arch-linux-pacman) You may see an error like the following: ```plaintext error: warpdotdev: signature from "Warp Linux Maintainers (Package Signing Authority) " is expired ``` To fetch the updated signing key, run: ```bash sudo pacman-key --recv-keys "linux-maintainers@warp.dev" --keyserver hkp://keys.openpgp.org:80 sudo pacman-key --lsign-key "linux-maintainers@warp.dev" ``` Then retry your update: ```bash sudo pacman -Syu warp-terminal ``` # Using Warp Offline > Using Warp offline and what features are supported. The first time you download and open Warp, you will need to be online for the initial setup. After the initial setup Warp’s core terminal features will work as expected when you’re offline, regardless of whether you are logged in or logged out. Requiring all users, logging in or logged out, to be online when first accessing Warp is required to allow use of Warp’s AI and cloud features. When you first open the app, we create a unique user-ID to meter AI-usage and attach cloud objects to specific accounts. If you opt to use Warp logged-out, this unique ID is attached to an anonymous user account. Note Warp is “Offline” when you aren’t connected to the internet, or if you’re blocking calls `app.warp.dev` on your network. There is no explicit Offline Mode in Warp. ### Cloud-based features require online access [Section titled “Cloud-based features require online access”](#cloud-based-features-require-online-access) Warp’s cloud-based features which require an internet connection will not work in offline mode. Those features include: * [Warp Drive](/knowledge-and-collaboration/warp-drive/#using-warp-drive-offline) (Some files may be read-only in offline mode) * [Oz agent](/agent-platform/local-agents/overview/) * [Agent Mode](/agent-platform/local-agents/interacting-with-agents/) * [Generate](/agent-platform/local-agents/overview/) * [AI Autofill](/knowledge-and-collaboration/warp-drive/workflows/#warp-ai-autofill) * [Prompts](/knowledge-and-collaboration/warp-drive/prompts/) * [Active AI Recommendations](/agent-platform/local-agents/active-ai/) * [Voice](/agent-platform/local-agents/interacting-with-agents/voice/) * [Rules](/agent-platform/capabilities/rules/) * [Model Context Protocol](/agent-platform/capabilities/mcp/) * [Teams](/knowledge-and-collaboration/teams/) * [Session Sharing](/knowledge-and-collaboration/session-sharing/) * [Block Sharing](/terminal/blocks/block-sharing/) * [Refer a Friend](/support-and-community/community/refer-a-friend/) # Terminal appearance overview > Customize Warp's visual appearance, including themes, fonts, prompts, app icons, input position, and pane behavior. # Custom app icons > Choose from a palette of built-in app icons to customize Warp's dock appearance on macOS. Note App icons are only available for Warp on macOS. The feature doesn’t support custom dock icons. ## How to change the app icon [Section titled “How to change the app icon”](#how-to-change-the-app-icon) * Navigate to **Settings** > **Appearance** > **Icon** > **Customize your app icon** * Select the desired dock icon from the drop down menu ![Icon customization drop-down menu](/_astro/custom-dock-icon-dropdown.CeH-wSu5_1H03WO.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Icon customization drop-down menu. ## Dock icons [Section titled “Dock icons”](#dock-icons) By default, Warp ships with these dock icons: ![Default preview](/_astro/moody-dev-default-icon.BPaCa3Tc.png) Default ![Warp 1.0 preview](/_astro/default-icon.B48Et-I7.png) Warp 1.0 ![Aurora preview](/_astro/aurora-icon.Bg6ukMrS.png) Aurora ![Classic 1 preview](/_astro/classic1-icon.B_kzNUF0.png) Classic 1 ![Classic 2 preview](/_astro/classic2-icon.Bgb4qqP1.png) Classic 2 ![Classic 3 preview](/_astro/classic3-icon.MsZKzt4W.png) Classic 3 ![Comets preview](/_astro/comets-icon.DuZalz1k.png) Comets ![Glass Sky preview](/_astro/glass-sky-icon.Y_YYSHti.png) Glass Sky ![Glitch preview](/_astro/glitch-icon.Bn7GOnVM.png) Glitch ![Glow preview](/_astro/glow-icon.iyXrzh38.png) Glow ![Holographic preview](/_astro/holographic-icon.MbSlbiPs.png) Holographic ![Mono preview](/_astro/mono-icon.CTeI0bQ6.png) Mono ![Neon preview](/_astro/neon-icon.Bp3jTFXP.png) Neon ![Original preview](/_astro/original-icon.Yf8Vowkb.png) Original ![Starburst preview](/_astro/starburst-icon.3pbHhTw0.png) Starburst ![Sticker preview](/_astro/sticker-icon.DD_Dg6if.png) Sticker # Blocks Behavior > Customize Block spacing with Compact mode and toggle Block dividers for a cleaner layout. ## Compact Mode [Section titled “Compact Mode”](#compact-mode) Warp offers the option to enable Compact mode, which condenses the spacing between [Blocks](/terminal/blocks/), enabling more content to be in view. ### How to enable Compact Mode [Section titled “How to enable Compact Mode”](#how-to-enable-compact-mode) Compact mode is disabled by default, but can be toggled in the following ways: * Navigate to **Settings** > **Appearance** > **Blocks** > **Compact Mode**. * Utilize the [Command Palette](/terminal/command-palette/), then search for “Compact mode” to toggle. Note Warp will open with the same compact settings in future sessions. [![](/assets/terminal/compact_mode.poster.jpg)](/assets/terminal/compact_mode.mp4) ## Block Dividers [Section titled “Block Dividers”](#block-dividers) Warp [Blocks](/terminal/blocks/) are divided by horizontal lines that separate individual command input and output, they create a visual break between different commands that you run in a session. ### How to toggle block dividers [Section titled “How to toggle block dividers”](#how-to-toggle-block-dividers) Block dividers are enabled by default, but can be toggled in the following ways: * Navigate to **Settings** > **Appearance** > **Blocks** > **Show block dividers**. * Utilize the [Command Palette](/terminal/command-palette/), then search for “Block Dividers”. [![](/assets/terminal/block-divider-demo.poster.jpg)](/assets/terminal/block-divider-demo.mp4) # Custom Themes > Warp supports Custom Themes which can be created manually or downloaded from our repo. Note Examples and a collection of themes can be found in the [Warp themes repository](https://github.com/warpdotdev/themes). ## Warp’s custom theme repository [Section titled “Warp’s custom theme repository”](#warps-custom-theme-repository) We have a [repository of themes hosted on GitHub.](https://github.com/warpdotdev/themes) Each theme has a preview generated in the README. The main difference between “standard” and “base16” themes is that “standard” themes follow the typical color setup, while “base16” themes follow the framework suggested by [@chriskempson](https://github.com/chriskempson/base16). There are 2 ways to install a theme from this repo. 1. Download a single file and follow the steps in the section below. 2. Clone the entire repo into the appropriate location based on your OS below: * macOS ```bash mkdir -p $HOME/.warp cd $HOME/.warp/ git clone https://github.com/warpdotdev/themes.git ``` * Windows ```powershell New-Item -Path "$env:APPDATA\warp\Warp\data\" -ItemType Directory Set-Location -Path $env:APPDATA\warp\Warp\data\ git clone https://github.com/warpdotdev/themes.git ``` * Linux ```bash mkdir -p ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal cd ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/ git clone https://github.com/warpdotdev/themes.git ``` Here is a step-by-step YouTube video that goes through these 2 steps for an example theme. Note the location for the files is based on macOS. ![Adding a Custom Theme to Warp](https://i.ytimg.com/vi/UTYgwD-cLbk/sddefault.jpg) ## How do I use a custom theme in Warp? [Section titled “How do I use a custom theme in Warp?”](#how-do-i-use-a-custom-theme-in-warp) 1. To start, create the following directory: * macOS ```bash mkdir -p $HOME/.warp/themes/ ``` * Windows ```powershell New-Item -Path "$env:APPDATA\warp\Warp\data\themes\" -ItemType Directory ``` * Linux ```bash mkdir -p ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/themes/ ``` Note It may take several minutes for Warp to initially discover the new themes directory. You can either wait or restart Warp. After that step, all future changes to the directory will be reflected within seconds. 2. Add your new custom theme yaml file to this directory: ```bash cp ~/Downloads/my_awesome_theme.yaml {{path_to_your_themes_directory_from_step1}} ``` Your new theme should now be visible on the list of available themes. ## Create your custom theme, manually [Section titled “Create your custom theme, manually”](#create-your-custom-theme-manually) Warp supports creating custom themes using .yaml files. The format is subject to change, but we do our best to avoid breaking changes and maintain forward compatibility. We also plan to support sharing and creating custom themes directly within Warp. A custom theme in Warp has the following `.yaml` structure: ```yaml name: Custom Theme # Name for the theme accent: '#268bd2' # Accent color for UI elements cursor: '#95D886' # Input cursor color (optional; defaults to accent color if omitted) background: '#002b36' # Terminal background color foreground: '#839496' # The foreground color details: darker # Whether the theme is lighter or darker terminal_colors: # Ansi escape colors bright: black: '#002b36' blue: '#839496' cyan: '#93a1a1' green: '#586e75' magenta: '#6c71c4' red: '#cb4b16' white: '#fdf6e3' yellow: '#657b83' normal: black: '#073642' blue: '#268bd2' cyan: '#2aa198' green: '#859900' magenta: '#d33682' red: '#dc322f' white: '#eee8d5' yellow: '#b58900' ``` Note Each color is represented in hex and must start with `#`. * `name`: Name for the theme, will show up in the Theme picker. * `accent`: Color used for highlights in Warp’s UI * `cursor`: Color for the input cursor (optional; defaults to accent color if omitted) * `background`: Color of background * `foreground`: Color of foreground * `details`: Color used for detailing options * `darker`: Color used for dark theme * `lighter`: Color used for light-mode theme * `terminal_colors`: Collection of normal & bright colors (16 total) known for other terminal themes (ANSI colors) ## Create your custom theme, automatically [Section titled “Create your custom theme, automatically”](#create-your-custom-theme-automatically) Automatically create new themes based on a background image. Click the **+** button in the theme picker **Settings** > **Appearance** > **Themes** or search `Open Theme Picker` within the [Command Palette](/terminal/command-palette/). ## Browse themes and use the theme creator [Section titled “Browse themes and use the theme creator”](#browse-themes-and-use-the-theme-creator) Browse Warp’s [theme repository](https://github.com/warpdotdev/themes) for ready-made themes, or use the in-app theme creator to generate the appropriate RGB values for your custom theme. Once the YAML file is created, you can edit the file to add the background images or gradients. ## Background images and gradients [Section titled “Background images and gradients”](#background-images-and-gradients) To add a background image you can use this attribute: `background_image:` with the name of the image you want to use as the background. Note Note: Warp currently only supports images with the *.jpg* file format: * `.jpeg` * `.jpg` * `.JPEG` A `.yaml` config looks like this: ```yaml name: Custom Theme accent: '#268bd2' cursor: '#95D886' background: '#002b36' details: darker foreground: '#839496' ############################################################### SEE BELOW background_image: # the path is relative to ~/.warp/themes/ # the full path to the picture is: ~/.warp/themes/warp.jpg path: warp.jpg # the opacity value is required and can range from 0-100 opacity: 60 ############################################################### SEE ABOVE terminal_colors: bright: black: '#002b36' blue: '#839496' cyan: '#93a1a1' green: '#586e75' magenta: '#6c71c4' red: '#cb4b16' white: '#fdf6e3' yellow: '#657b83' normal: black: '#073642' blue: '#268bd2' cyan: '#2aa198' green: '#859900' magenta: '#d33682' red: '#dc322f' white: '#eee8d5' yellow: '#b58900' ``` To set up a gradient, create a sublevel under accent with two key-value pairs: * “left” and “right” or * “top” and “bottom”. ```yaml accent: top: '#abcdef' bottom: '#fedcba' ``` ```yaml accent: left: '#abcdef' right: '#fedcba' ``` Warp also supports setting a gradient for the background. ```yaml # accent has a gradient accent: left: '#474747' right: '#ffffff' # background has a gradient background: top: '#474747' bottom: '#ffffff' ``` ### Contributing [Section titled “Contributing”](#contributing) Contributions to this repo are greatly appreciated! 1. Fork the project 2. Create your branch with `git checkout -b theme/AwesomeTheme` 3. Regenerate thumbnails 4. Commit and open a pull request Run this script to generate the thumbnails. ```bash # Assuming you're adding the theme to the `standard` directory: python3 ./scripts/gen_theme_previews.py standard ``` Note Note: We cannot accept pull requests that include custom background images because: * Licensing restrictions * Trying to keep the binary size of the repo as small as possible (only the yaml files) If your theme has an intended custom background image, include a comment in the yaml with a link to where people should download it. ## Community [Section titled “Community”](#community) All other Warp-related things can be discussed, please [contact us](/support-and-community/troubleshooting-and-support/sending-us-feedback/). ## Open source dependencies [Section titled “Open source dependencies”](#open-source-dependencies) We’d like to call out a few of the open-source themes and repositories that helped bootstrap the set of themes for Warp: * [iTerm colors pencil](https://github.com/mattly/iterm-colors-pencil) * [Alacritty-theme](https://github.com/eendroroy/alacritty-theme) * [base16-Alacritty](https://github.com/aarowill/base16-alacritty) * [base16](https://github.com/chriskempson/base16) * [Solarized](https://ethanschoonover.com/solarized/) * [Dracula](https://draculatheme.com/) * [Gruvbox](https://github.com/morhetz/gruvbox) # Input position > Warp gives you the ability to configure the position of your input, which includes both the prompt and the command line. You can select from three different input positions, which each have different modes of behavior for the flow of input/output Blocks. | Input position | Behavior | | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | Start at the top (Classic mode) | When you select “start at the top,” the prompt with input will initiate at the top of the view and move down in the view as you enter commands. Blocks of input/output will stack above the prompt and command input. You can scroll up or navigate up to visit past commands. You can enter `CTRL-L` or the `clear` command at any time to return the input to the top of the screen while still maintaining your scroll history. | | | Pin to the top (Reverse mode) | When you select “pin to the top,” the prompt with input will display pinned to the top of your terminal view. Blocks of grouped input/output will flow down the view in reverse order with your latest results at the top. You can scroll down or navigate down to visit past commands. For long-running commands, you can also click “Lock scrolling at bottom of block” to continue to follow the stdout. | | | Pin to the bottom (Warp mode) | Warp mode starts with input pinned to the bottom of your terminal view. Blocks of grouped input/output flow up and out of view. You can scroll up or navigate up to visit past commands. | | ## How to access it [Section titled “How to access it”](#how-to-access-it) * You can configure your input position by navigating to **Settings** > **Appearance** > **Input**. * You can also choose and set modes from the [Command Palette](/terminal/command-palette/). Note Changes to the Input position take place immediately and apply to all open panes. ### Related commands [Section titled “Related commands”](#related-commands) * macOS * `CMD-K` will clear the entire list of input/output blocks for a clean view * `CTRL-L` will move the list of input/output blocks outside of the view and past the scroll so you have a clean view and the ability to easily visit past commands * For long Blocks, you can press `SHIFT-CMD-UP`/`SHIFT-CMD-DOWN` to Scroll to the top/bottom the selected block. * Windows * `CTRL-SHIFT-K` will clear the entire list of input/output blocks for a clean view * `CTRL-L` will move the list of input/output blocks outside of the view and past the scroll so you have a clear view and the ability to easily visit past commands * For long Blocks, you can press `CTRL-SHIFT-UP`/`CTRL-SHIFT-DOWN` to Scroll to the top/bottom of the selected block. * Linux * `CTRL-SHIFT-K` will clear the entire list of input/output blocks for a clean view * `CTRL-L` will move the list of input/output blocks outside of the view and past the scroll so you have a clear view and the ability to easily visit past commands * For long Blocks, you can press `CTRL-SHIFT-UP`/`CTRL-SHIFT-DOWN` to Scroll to the top/bottom of the selected block. ## How it works [Section titled “How it works”](#how-it-works) ![Input Position Demo](https://i.ytimg.com/vi/z1rDVPxaNCo/sddefault.jpg) # Pane Dimming & Focus > Warp supports dimming inactive Panes as well as allowing the focus to follow the mouse. This helps you easily see which pane is active and maintain focus. ## How to use it [Section titled “How to use it”](#how-to-use-it) ### Inactive pane dimming [Section titled “Inactive pane dimming”](#inactive-pane-dimming) The panes that aren’t active will be dimmed to better indicate which pane is active. To access it, go to **Settings** > **Appearance** > **Panes** * Toggle on **Dim inactive panes** to enable the feature. Note Split panes show a triangle indicator on the top left corner of the active pane. ### Mouse focus [Section titled “Mouse focus”](#mouse-focus) The pane with the mouse over it will become active. To access it, go to **Settings** > **Appearance** > **Panes** * Toggle on **Focus follows mouse** to enable the feature. ## How it works [Section titled “How it works”](#how-it-works) [Inactive Pane Dimming Demo](https://www.loom.com/embed/62b84d3c60b34cdbaa340fbe8ce8b1d1) # Terminal prompt > Configure Warp's native prompt with context chips or use your own Shell prompt (PS1). Warp supports two prompt types: the **Warp prompt** and the **Shell prompt (PS1)**. ## Choosing your prompt type [Section titled “Choosing your prompt type”](#choosing-your-prompt-type) To switch your prompt type: 1. Open **Settings** > **Appearance**. 2. Under **Input**, set **Input type** to **Warp** or **Shell (PS1)**. When using the Warp prompt, you can right-click the prompt area to copy the entire prompt, working directory, current git branch, git uncommitted file count, and more. When using a Shell prompt, you can right-click the prompt area to copy the entire prompt, or select any part of the prompt in previously run blocks in your session. ## Warp prompt [Section titled “Warp prompt”](#warp-prompt) Warp has a native prompt that displays context chips showing information such as your current working directory, git branch, svn status, Kubernetes context, pyenv, date, and time. The Warp prompt is the default when **Input type** is set to **Warp**. To customize which context chips your Warp prompt displays: 1. Right-click the prompt area and select **Edit prompt**. ![Right-click context menu showing the Edit prompt option](/_astro/edit-prompt-modal.D4XullzS_15Uoj7.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Prompt editing via right-click. 2. Select **Warp Prompt**. 3. Drag and drop context chips to configure which pieces of information your prompt displays. ### Git and Subversion [Section titled “Git and Subversion”](#git-and-subversion) Git and Subversion context chips show which branch you are on locally, as well as the number of uncommitted changed files. This includes any new files, modified files, and deleted files that are staged or unstaged. ### Kubernetes [Section titled “Kubernetes”](#kubernetes) The Kubernetes context chip shows relevant information when you’re using one of the following commands: `kubectl|helm|kubens|kubectx|oc|istioctl|kogito|k9s|helmfile|flux|fluxctl|stern|kubeseal|skaffold|kubent|kubecolor|cmctl|sparkctl|etcd|fubectl` Note Warp respects the `KUBECONFIG` environment variable. Make sure you set it to your preferred configuration file location if it’s not the default path of `~/.kube/config`. ## Shell prompt (PS1) [Section titled “Shell prompt (PS1)”](#shell-prompt-ps1) You can use a Shell prompt instead of the Warp prompt by configuring the **PS1** variable or installing a supported shell prompt plugin (see [Shell Prompt Compatibility Table](/terminal/appearance/prompt/#shell-prompt-compatibility-table)). To enable the Shell prompt: 1. Open **Settings** > **Appearance**. 2. Under **Input**, set **Input type** to **Shell (PS1)**. 3. Configure your PS1 variable in your shell’s RC file, or install a supported prompt plugin. Note The PS1 is a variable used by the shell to generate the prompt, it represents the primary prompt string (hence the “PS”) - which the terminal typically displays before typing new commands. ### Multi-line and right-sided prompts [Section titled “Multi-line and right-sided prompts”](#multi-line-and-right-sided-prompts) The Shell prompt supports multi-line or right-sided prompts in zsh and fish, not bash. However, you can’t have a multiline right-side prompt, only a multiline left prompt. Note If you want to add a new line to your Shell prompt, run the following based on your shell or prompt: ```sh # Bash echo -e '\nPS1="${PS1}"$'\''\\n'\''' >> ~/.bashrc # Zsh echo -e '\nPROMPT="${PROMPT}"$'\''\\n'\''' >> ~/.zshrc # Fish echo -e '\nfunctions --copy fish_prompt fish_prompt_orig; function fish_prompt; fish_prompt_orig; echo; end' >> ~/.config/fish/config.fish # Powershell $rawString = @' $originalPrompt = Get-Item Function:\prompt Set-Item -Path Function:\prompt_original -Value $originalPrompt function prompt { "$(& prompt_original)`n" } '@ Add-Content -Path $PROFILE -Value "`n$rawString`n" # Powerlevel10k p10k configure # Starship Prompt echo '[line_break]\ndisabled = false' >> ~/.config/starship.toml ``` ## How it works [Section titled “How it works”](#how-it-works) [![](/assets/terminal/warp-custom-prompt-demo.poster.jpg)](/assets/terminal/warp-custom-prompt-demo.mp4) ### Shell prompt compatibility table [Section titled “Shell prompt compatibility table”](#shell-prompt-compatibility-table) | Shell | Tool | Does it work? | | --------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------- | | bash \| zsh | [PS1](https://www.warp.dev/blog/whats-so-special-about-ps1) | Working | | bash \| zsh \| fish \| pwsh | [Starship](https://github.com/starship/starship) | [Working\*](/terminal/appearance/prompt/#starship) | | bash \| zsh \| fish \| pwsh | [oh-my-posh](https://github.com/JanDeDobbeleer/oh-my-posh) | Working | | zsh | [Powerlevel10k](https://github.com/romkatv/powerlevel10k) | [Working\*](/terminal/appearance/prompt/#powerlevel10k) | | zsh | [Spaceship](https://github.com/spaceship-prompt/spaceship-prompt) | [Working\*](/terminal/appearance/prompt/#spaceship) | | zsh | [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh) | Working | | zsh | [prezto](https://github.com/sorin-ionescu/prezto) | [Working\*](/terminal/appearance/prompt/#prezto) | | ssh | | Working | | bash | [oh-my-bash](https://github.com/ohmybash/oh-my-bash) | Not supported | | bash | [bash-it](https://github.com/Bash-it/bash-it) | Not supported | | bash | [SBP](https://github.com/brujoand/sbp) | Not supported | | bash | [synth-shell-prompt](https://github.com/andresgongora/synth-shell-prompt) | Not supported | | bash \| zsh | [Powerline-shell](https://github.com/b-ryan/powerline-shell) | Not supported | | zsh | [zplug](https://github.com/zplug/zplug) | Not supported | | fish | [tide](https://github.com/IlanCosman/tide) | [Not supported](https://github.com/warpdotdev/Warp/issues/3358) | | fish | [oh-my-fish](https://github.com/oh-my-fish/oh-my-fish) | [Not supported](https://github.com/warpdotdev/Warp/issues/3796) | ## Known incompatibilities [Section titled “Known incompatibilities”](#known-incompatibilities) If you’re having issues with prompts, please see below or our [Known Issues](/support-and-community/troubleshooting-and-support/known-issues/#configuring-and-debugging-your-rc-files) for more troubleshooting steps. ### Starship [Section titled “Starship”](#starship) #### Starship Settings [Section titled “Starship Settings”](#starship-settings) Some `~/.config/starship.toml` settings are known to cause errors in Warp. `#` or `DEL` the following lines to resolve known errors: ```plaintext # Get editor completions based on the config schema '' = 'https://starship.rs/config-schema.json' # Disables the custom module [custom] disabled = false ``` For `fish` shell, optional for `bash|zsh`, disable the multi-line prompt in Starship by putting the following in your `~/.config/starship.toml`: ```plaintext [line_break] disabled = true ``` You may also see an error relating to timeout. You can set the `command_timeout` variable in your `~/.config/starship.toml` to fix this. See more in the [starship docs](https://starship.rs/config/#prompt). #### Starship + bash [Section titled “Starship + bash”](#starship--bash) Starship prompt may not render properly if your [default shell](/getting-started/supported-shells/#changing-what-shell-warp-uses) is `/bin/bash`. To [workaround](https://github.com/warpdotdev/Warp/issues/3066#issuecomment-1548643121) the issue, we recommend you upgrade bash, find the path with `echo $(which bash)`, then put the path in **Settings** > **Features** > **Session** > **“Startup shell for new sessions”**. #### Starship + zsh [Section titled “Starship + zsh”](#starship--zsh) If you want to restore the additional line after the Starship prompt on `zsh`, add the following to the bottom of your `~/.zshrc` file: `PROMPT="${PROMPT}"$'\n'` ### Powerlevel10k [Section titled “Powerlevel10k”](#powerlevel10k) When installing the Powerlevel10k (P10k) prompt, we recommend you use the [Meslo Nerd Font](https://github.com/romkatv/powerlevel10k/blob/master/font.md).\ \ P10K may display the arrow dividers as grey instead of color. The color for those chars is rendered grey due to Warp’s minimum contrast setting. To [workaround](https://github.com/warpdotdev/Warp/issues/2851#issuecomment-1605005256) this issue, go to **Settings** > **Appearance** > **Text** > **Enforce minimum contrast** and set it to “Never”. ![Example of the grey dividers in p10k](/_astro/p10k-grey-arrow-prompt.CLDVVaeR_2kKrBP.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Example of the grey dividers in p10k. Warp does support [p10k](https://github.com/romkatv/powerlevel10k#installation) version 1.19.0 and above. Ensure you have the latest version installed and restart Warp after the installation/update of p10k. Then enable the custom prompt as stated [above](/terminal/appearance/prompt/#choosing-your-prompt-type) and it should work. Note Warp still doesn’t fully support some p10k features like transient prompt and visual features like gradients. ![Installing Powerlevel10k](https://i.ytimg.com/vi/dIV9Cso4Mi8/sddefault.jpg) Caution Please note the Installing Powerlevel10k video mentions enabling a custom prompt in **Settings** > **Features** > **Honor users custom prompt (PS1)**, but it’s now in **Settings** > **Appearance** > **Input** > **Classic** > **Current prompt** > **Shell Prompt (PS1)** . ### Spaceship [Section titled “Spaceship”](#spaceship) This prompt can cause an issue with typeahead in Warp’s input editor. To [workaround](https://github.com/warpdotdev/Warp/issues/1973#issuecomment-1340150521) the issue, run `echo "SPACESHIP_PROMPT_ASYNC=FALSE" >>! ~/.zshrc`. ### Prezto [Section titled “Prezto”](#prezto) Although Warp does have support for prezto’s prompt, enabling the [prezto utility module](https://github.com/sorin-ionescu/prezto/blob/master/modules/utility/README.md) in the `.zpreztorc` is not supported as with many other autocompletion [plugins that are incompatible](/support-and-community/troubleshooting-and-support/known-issues/#list-of-incompatible-tools). ### Disabling unsupported prompts for Warp [Section titled “Disabling unsupported prompts for Warp”](#disabling-unsupported-prompts-for-warp) We advise using Warp’s default prompt or installing one of the supported tools, see [Compatibility Table](/terminal/appearance/prompt/#shell-prompt-compatibility-table). You can disable unsupported prompts for Warp as such: ```plaintext if [[ $TERM_PROGRAM != "WarpTerminal" ]]; then ##### WHAT YOU WANT TO DISABLE FOR WARP - BELOW # Unsupported Custom Prompt Code ##### WHAT YOU WANT TO DISABLE FOR WARP - ABOVE fi ``` #### iTerm2 [Section titled “iTerm2”](#iterm2) The iTerm2 shell integration breaks Warp and your custom prompt will not be able to be visible with this on. If you’re coming from iTerm2 please check your dotfiles for it. We advise disabling the integration for Warp like so: ```plaintext if [[ $TERM_PROGRAM != "WarpTerminal" ]]; then ##### WHAT YOU WANT TO DISABLE FOR WARP - BELOW test -e "${HOME}/.iterm2_shell_integration.zsh" && source "${HOME}/.iterm2_shell_integration.zsh" ##### WHAT YOU WANT TO DISABLE FOR WARP - ABOVE fi ``` # Size, Opacity, & Blurring > Configure window size, opacity, and background blurring to match your visual preferences. ## How to use it [Section titled “How to use it”](#how-to-use-it) ### Window Size [Section titled “Window Size”](#window-size) To access size settings, go to **Settings** > **Appearance** > **Window**. * Enable “Open new windows with custom size”, Then configure your preferred columns and rows. Note If [Session Restoration](/terminal/sessions/session-restoration/) is enabled, Warp will restore the size of the last window closed when you quit the app. Either make sure the custom-sized window is the last one closed, or disable Session Restoration to ensure Warp launches with the custom-sized window. ### Window Opacity [Section titled “Window Opacity”](#window-opacity) To access it, go to **Settings** > **Appearance** > **Window** * The slider supports setting the opacity value between `1` and `100` where `100` is completely opaque or solid. ### Window Blurring [Section titled “Window Blurring”](#window-blurring) After decreasing Opacity (moving the slider to a value less than `100`), you can also blur the background. * On macOS, this is done using the blur slider. Increasing the slider increases the blur radius that’s applied to the background image. * On Windows, this is done by toggling the Acrylic background texture on or off. Caution On macOS, large blur radiuses may affect performance, especially on Retina displays. On Linux, window blurring is not supported. On Windows, some graphics drivers may not support rendering transparent or translucent windows. See below for troubleshooting tips. ## How it works [Section titled “How it works”](#how-it-works) [![](/assets/terminal/window_size_demo.poster.jpg)](/assets/terminal/window_size_demo.mp4) [Window Opacity and Blurring Demo](https://www.loom.com/embed/22c9ef25392e4a5e80f9e01394c84dc4) ### Troubleshooting transparency on Windows [Section titled “Troubleshooting transparency on Windows”](#troubleshooting-transparency-on-windows) Note At the moment, window opacity in Warp on Windows **does not work** in the following circumstances: * When using DirectX 12 as the rendering backend * When using any rendering backend with an Nvidia GPU when “Auto” or “Prefer layered” is selected as the value for “Vulkan/OpenGL present method” in NVIDIA Control Panel > Manage 3D Settings Some graphics drivers and rendering backends may not support rendering transparent windows. You can select the Vulkan or OpenGL graphics backend to render new Warp windows in the Settings menu, under `Features` > `System` > `Preferred graphics backend`. You can also opt to render new Warp windows with an integrated GPU, under `Features` > `System` > `Prefer rendering new windows with integrated GPU (low power)`. # Tabs Behavior > Customize tab behavior in Warp, including tab indicators, tab bar visibility, and close button position. ## Tab indicators [Section titled “Tab indicators”](#tab-indicators) Tab indicators provide visual cues in the tab bar under certain specific conditions: When the current pane is maximized, when panes or tabs are synchronized, and when a command exits with an error. These indicators serve as quick references. ### How to toggle tab indicators [Section titled “How to toggle tab indicators”](#how-to-toggle-tab-indicators) * Navigate to **Settings** > **Appearance** > **Tabs**, and switch the “Show tab indicators” option. * Utilize the [Command Palette](/terminal/command-palette/), then search for “Tab indicators” to toggle the tab indicators. [![](/assets/terminal/tab-indicator-demo.poster.jpg)](/assets/terminal/tab-indicator-demo.mp4) ## Tab bar [Section titled “Tab bar”](#tab-bar) The tab bar provides easy navigation between open tabs. By default, the tab bar is visible in windowed mode but hides in fullscreen. To access the tab bar when hidden, hover near the top of the window. You can customize its visibility based on your preferences. ### How to configure the tab bar [Section titled “How to configure the tab bar”](#how-to-configure-the-tab-bar) * Navigate to **Settings** > **Appearance** > **Tabs** > **Show the tab bar** to toggle the visibility of the tab bar. Choose from the following options: * Always – Keeps the tab bar visible at all times. * Only on hover – Hides the tab bar in both modes. * When windowed – Displays the tab bar only in windowed mode. * Block dividers Note On macOS, traffic lights will not be shown when in windowed mode if the tab bar is set to show only on hover. [![](/assets/terminal/tab-bar-demo.poster.jpg)](/assets/terminal/tab-bar-demo.mp4) ## Tab close button [Section titled “Tab close button”](#tab-close-button) You can configure the position of the tab close button to be either on the left or right side of the tab. ### How to configure the tab close button [Section titled “How to configure the tab close button”](#how-to-configure-the-tab-close-button) Navigate to **Settings** > **Appearance** > **Tabs** > **Tab close button position**, then choose from the following options: * Left - the close button will be on the left side of the tab (macOS style) * Right – the close button will be on the right side of the tab (Windows | Linux style)\\ [![](/assets/terminal/tab-close-button-demo.poster.jpg)](/assets/terminal/tab-close-button-demo.mp4) # Text, Fonts, & Cursor > Warp supports customizing the font and how text is displayed. This can help improve readability and usability. Warp also supports disabling the blinking cursor. Note Once a new font is installed in your system, you need to restart Warp for it to show on the list of options. You may also need to check “View all available system fonts” to see the new font. ## How to use it [Section titled “How to use it”](#how-to-use-it) ### Text and Fonts [Section titled “Text and Fonts”](#text-and-fonts) To access it, go to **Settings** > **Appearance** > **Text** From there you can customize: * Font type * Font weight * Font size * Line height * Use thin strokes * The default setting prevents text from being blurry on low-DPI displays. Caution On Linux, Warp does not support the “Use thin stroke” feature. * Enforce minimum contrast * The default setting tweaks named colors to meet accessibility standards. * Show ligatures in terminal Note Enabling ligatures can reduce performance. Warps default font, Hack, doesn’t yet have ligature support. We recommend font that supports ligatures (e.g. [Fira Code](https://github.com/tonsky/FiraCode)) as a stopgap. ### Cursor [Section titled “Cursor”](#cursor) To access it, go to **Settings** > **Appearance** > **Cursor** From there you can customize: * Select the Cursor type to Bar, Block, or Underline. * Toggle the Blinking cursor or from the [Command Palette](/terminal/command-palette/), type “Cursor blink” and toggle the setting. Note Cursor type preference is disabled while [Vim keybindings](/terminal/editor/vim/) (vim mode) is active. ## How it works [Section titled “How it works”](#how-it-works) [Text and Fonts Demo](https://www.loom.com/embed/be2fa6ab10a3494a8c57a5431966905b) [Cursor Demo](https://www.loom.com/embed/6ce3218472894763bb80a26b6c632c4d) # Terminal themes > Warp includes several themes (out-of-box) and also supports setting custom themes. ### Theme Picker [Section titled “Theme Picker”](#theme-picker) The Theme Picker can be accessed by: 1. Navigating to **Settings** > **Appearance**. 2. Clicking the Custom Themes (shaded) box. 3. Upon selecting a theme, Warp’s appearance will update accordingly. 4. Press the checkmark to save the selection, or the X to revert. Note The Theme setting persists, meaning Warp will open with the same settings in the next session. ### Theme Creator [Section titled “Theme Creator”](#theme-creator) Automatically create new themes based on a background image. 1. Go to **Settings** > **Appearance** > **Themes** or search “Open theme picker” within the [Command Palette](/terminal/command-palette/). 2. Click the **+** button in the theme picker. 3. Upload the image and select the background color. 4. Click “Create Theme” to save and accept the new theme. ### OS Theme Sync [Section titled “OS Theme Sync”](#os-theme-sync) Warp supports synchronizing your theme with the OS’s light and dark themes. To enable this: 1. Open the **Settings** > **Appearance** dialog. 2. Click the toggle “Sync with OS”. 3. You will then be able to select a specific theme for when the OS is in light mode and dark mode. ## How it works [Section titled “How it works”](#how-it-works) [![](/assets/terminal/theme-picker.poster.jpg)](/assets/terminal/theme-picker.mp4) [![](/assets/terminal/theme-creator.poster.jpg)](/assets/terminal/theme-creator.mp4) [![](/assets/terminal/theme-sync-demo.poster.jpg)](/assets/terminal/theme-sync-demo.mp4) ## Default Themes [Section titled “Default Themes”](#default-themes) By default, Warp ships with these themes: ![Warp Dark preview](/_astro/warp-dark.ChkG3STe.png) Warp Dark ![Warp Light preview](/_astro/warp-light.BJhCEM8w.png) Warp Light ![Dracula preview](/_astro/dracula.D2M7cqfj.png) Dracula ![Solarized Dark preview](/_astro/solarized-dark.B7i4l0kN.png) Solarized Dark ![Solarized Light preview](/_astro/solarized-light.D7L_VEbd.png) Solarized Light ![Gruvbox Dark preview](/_astro/gruvbox-dark.CsMDOdsk.png) Gruvbox Dark ![Gruvbox Light preview](/_astro/gruvbox-light.YQpLlxHx.png) Gruvbox Light ![Jellyfish preview](/_astro/jellyfish.Ctx0a8qM.png) Jellyfish ![Koi preview](/_astro/koi.m6-Db-JP.png) Koi ![Leafy preview](/_astro/leafy.rANSmkX_.png) Leafy ![Marble preview](/_astro/marble.BvKR7Nk5.png) Marble ![Pink City preview](/_astro/pink-city.CdzkjY2B.png) Pink City ![Snowy preview](/_astro/snowy.n14nix7B.png) Snowy ![Dark City preview](/_astro/dark-city.BSEZ8GyA.png) Dark City ![Red Rock preview](/_astro/red-rock.DlslQa3M.png) Red Rock ![Cyber Wave preview](/_astro/cyber-wave.CeSV9L25.png) Cyber Wave ![Willow Dream preview](/_astro/willow-dream.Dgv_HIfQ.png) Willow Dream ![Fancy Dracula preview](/_astro/fancy-dracula.C1KCaClF.png) Fancy Dracula ![Phenomenon preview](/_astro/phenomenon.CdWIXjcu.png) Phenomenon ![Solar Flare preview](/_astro/solar-flare.D0CWAIXi.png) Solar Flare ![Adeberry preview](/_astro/adeberry.YSTsWaYZ.png) Adeberry # Terminal Blocks overview > A Block groups commands and outputs into one atomic unit. ## What are Blocks? [Section titled “What are Blocks?”](#what-are-blocks) Blocks enable us to easily: * Copy a command * Copy a command’s output * Scroll directly to the start of a command’s output * Re-input commands * Share both a command and its output (with formatting!) * Bookmark commands Note Interested in how we differentiate input and output, or how we implement blocks? Check out our blog post: [How Warp Works.](https://blog.warp.dev/how-warp-works/#implementing-blocks) ![Intro to Blocks](https://i.ytimg.com/vi/PH1u0TZ5Lf0/sddefault.jpg) ![Blocks](/_astro/annotated_blocks-1.CLvjDB1C_bRTPh.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) # Background Blocks > How Blocks interact with background process output. ## What is it [Section titled “What is it”](#what-is-it) Commands can start background processes that continue even after they exit. You can also start a background process directly from the shell, such as by running it with `&`. If Warp receives output that is likely from a background process, the output goes into a *background block*. Background blocks act like regular blocks, except that they don’t have an associated command. This lets you use all of Warp’s block features with background output, such as sharing and bookmarking. ## How to use it [Section titled “How to use it”](#how-to-use-it) Background blocks are automatically created as needed, in between regular blocks running. If you run commands while a background process is still producing output, that output gets split into multiple blocks interleaved with your commands. ## How it works [Section titled “How it works”](#how-it-works) [Create Background Blocks](https://www.loom.com/embed/55bbbd9a8cbf495189260756c717cfb2) ## Troubleshooting background blocks [Section titled “Troubleshooting background blocks”](#troubleshooting-background-blocks) There are some limitations, because Warp doesn’t know *which* process any given output came from: * If a background process writes output while a foreground command is running in a regular block, the output goes into that block. * If there are multiple background processes running at the same time, their output may be mixed together. In addition, if you start entering a command while another one is running (typeahead), in some cases Warp will mistake the partial command for background output. The most common cause is editing typeahead when using bash versions older than 4.0 (for example, deleting and re-typing part of it). # Block Actions > Copy, bookmark, share, search, and filter Blocks using built-in actions. ## Accessing block actions [Section titled “Accessing block actions”](#accessing-block-actions) There are 2 ways you can access Block actions. 1. Hover over a Block and click the kebab (three dots) button on the right-hand side. 2. Right-click a Block. [Accessing Block Actions](https://www.loom.com/embed/3dec25e548d4484aa3dd6437869e2bbf) ## Copy input / output of block [Section titled “Copy input / output of block”](#copy-input--output-of-block) For command blocks, you can `RIGHT-CLICK` on a Block or click the context menu and copy the Block command, output, or both. For AI blocks, you can `RIGHT-CLICK` to copy the prompt, output, both or the entire conversation. [Copy Block Actions](https://www.loom.com/embed/9ad67eca0a8d47afb82cc1acba617f3c) ## Sharing a block [Section titled “Sharing a block”](#sharing-a-block) Share a block easily with coworkers or teammates by creating a web permalink. This preserves formatting and makes debugging and sharing output easy. [See Block Sharing Page.](/terminal/blocks/block-sharing/) ## Bookmarking a block [Section titled “Bookmarking a block”](#bookmarking-a-block) Quickly navigate to important Blocks despite where they are in the terminal history. * macOS Ways to bookmark a Block: 1. Select **Toggle bookmark** in the block context menu 2. Use `CMD-B` keybinding to bookmark a selected block Navigate to a bookmarked Block, by: * Clicking on the indicator.\ The indicator position reflects the approximate position of the Block in the Block history. Hovering over the indicator will give a snapshot of the Block including its prompt, command, and the last two lines of output. * Pressing `OPTION-UP` and `OPTION-DOWN` * Windows There are Ways to bookmark a Block: 1. Select **Toggle bookmark** in the block context menu 2. Use `CTRL-SHIFT-B` keybinding to bookmark a selected block Navigate to a bookmarked Block, by: * Clicking on the indicator.\ The indicator position reflects the approximate position of the Block in the Block history. Hovering over the indicator will give a snapshot of the Block including its prompt, command, and the last two lines of output. * Pressing `ALT-UP` and `ALT-DOWN` * Linux Ways to bookmark a Block: 1. Click on the bookmark icon in the top right corner of a Block 2. Select **Toggle bookmark** in the block context menu 3. Use `CTRL-SHIFT-B` keybinding to bookmark a selected block Navigate to a bookmarked Block, by: * Clicking on the indicator.\ The indicator position reflects the approximate position of the Block in the Block history. Hovering over the indicator will give a snapshot of the Block including its prompt, command, and the last two lines of output. * Pressing `ALT-UP` and `ALT-DOWN` Note Bookmarks only persist while the session is open, once you close the session they are lost. If you want to save the command and output for later use, [Share the Block](/terminal/blocks/block-sharing/). [![](/assets/terminal/block-bookmarks.poster.jpg)](/assets/terminal/block-bookmarks.mp4) ## Search within a block [Section titled “Search within a block”](#search-within-a-block) Quickly find important information within a Block. [See Find page](/terminal/blocks/find/) * macOS With a Block selected, press “Find Within Block” or use `CMD-F` to search within a Block. * Windows With a Block selected, Press “Find Within Block” or use `CTRL-SHIFT-F` to search within a Block. * Linux With a Block selected, Press “Find Within Block” or use `CTRL-SHIFT-F` to search within a Block. [Search within a Block](https://www.loom.com/embed/7dda0e7a6ec144cfb6410d29a586ddd0) ## Filtering a block [Section titled “Filtering a block”](#filtering-a-block) Filter the output lines of a block natively in Warp to quickly focus on a subset of the block. [See Block Filtering Page](/terminal/blocks/block-filtering/). * macOS * Using the keybinding `OPT-SHIFT-F` by default to toggle filtering on the selected or latest block * Selecting `Toggle Block Filter` in the block context menu * Windows * Using the keybinding `ALT-SHIFT-F` to toggle filtering on the selected or latest block * Selecting `Toggle Block Filter` in the block context menu * Linux * Using the keybinding `ALT-SHIFT-F` to toggle filtering on the selected or latest block * Selecting `Toggle Block Filter` in the block context menu # Terminal Block Basics > The basics of creating, selecting, and navigating between Blocks. ## The basics [Section titled “The basics”](#the-basics) * Blocks group your command and command output * The Input Editor can pin to the bottom, pin to the top, or start at the top. * Blocks grow from the bottom to the top. * Blocks are color-coded. Blocks that quit with a non-zero exit code have a red background and red sidebar. Note Try it yourself!\ Type `xyz` (or some other command that doesn’t exist) and hit `ENTER` ## Create a block [Section titled “Create a block”](#create-a-block) 1. Execute a command (type `ls` and hit `ENTER`) in the Input Editor at the bottom of the screen. 2. Your command and output are grouped into a Block. 3. Try executing a different command (type `echo hello` and hit `ENTER`). 4. Warp adds your newly created Block to the bottom (directly above the input editor). [Create a Block](https://www.loom.com/embed/4b435c78344d4dc0bb92af5d1da5e219) ## Select a single block [Section titled “Select a single block”](#select-a-single-block) * macOS * Using your mouse: click on a Block. * Or using your keyboard: hit `CMD-UP` (or `CMD-DOWN` if input as pinned up top) to select the most recently executed Block and use the `UP ↑` and `DOWN ↓` arrow keys to navigate to the desired Block. * For long Blocks: * You can click “Jump to the bottom of this block”. * You can press `SHIFT-CMD-UP`/`SHIFT-CMD-DOWN` to Scroll to the top/bottom of the selected block. * From the [Command Palette](/terminal/command-palette/), you can also “Scroll to the top/bottom of selected block”. * Windows * Using your mouse: Click on a Block. * Or using your keyboard: hit `CTRL-UP` (or `CTRL-DOWN` if input as pinned up top) to select the most recently executed Block and use the `UP ↑` and `DOWN ↓` arrow keys to navigate to the desired Block. * For long Blocks: * You can click “Jump to the bottom of this block”. * You can press `CTRL-SHIFT-UP`/`CTRL-SHIFT-DOWN` to Scroll to the top/bottom of the selected block. * From the [Command Palette](/terminal/command-palette/), you can also “Scroll to the top/bottom of selected block”. * Linux * Using your mouse: Click on a Block. * Or using your keyboard: hit `CTRL-UP` (or `CTRL-DOWN` if input as pinned up top) to select the most recently executed Block and use the `UP ↑` and `DOWN ↓` arrow keys to navigate to the desired Block. * For long Blocks: * You can click “Jump to the bottom of this block”. * You can press `CTRL-SHIFT-UP`/`CTRL-SHIFT-DOWN` to Scroll to the top/bottom of the selected block. * From the [Command Palette](/terminal/command-palette/), you can also “Scroll to the top/bottom of selected block”. [Select a Single Block](https://www.loom.com/embed/1cf8546daad548fbbe056c35edb23cdc) ## Select multiple blocks [Section titled “Select multiple blocks”](#select-multiple-blocks) * macOS * Click another Block while holding `CMD` to toggle the selection of that Block, or * Click another Block while holding `SHIFT` to select a range of Block, or * Use `SHIFT-UP ↑` or `SHIFT-DOWN ↓` to expand the active selection (the Block with the thicker border) up or down, respectively. * Windows * Click another Block while holding `CTRL-SHIFT` to toggle the selection of that Block, or * Click another Block while holding `SHIFT` to select a range of Block, or * Use `SHIFT-UP ↑` or `SHIFT-DOWN ↓` to expand the active selection (the Block with the thicker border) up or down, respectively. * Linux * Click another Block while holding `CTRL-SHIFT` to toggle the selection of that Block, or * Click another Block while holding `SHIFT` to select a range of Block, or * Use `SHIFT-UP ↑` or `SHIFT-DOWN ↓` to expand the active selection (the Block with the thicker border) up or down, respectively. [Select Multiple Blocks](https://www.loom.com/embed/5058ab0dc3d244d4a2ce576331440821) ## Navigate blocks [Section titled “Navigate blocks”](#navigate-blocks) * macOS * **Mouse or scrollbar** - Scroll using your mouse, trackpad, or the scrollbar. * **Arrow keys** - Select a Block and use `UP ↑` and `DOWN ↓` to move between Blocks. * **Page scrolling** - Press `PAGE UP` or `PAGE DOWN` to scroll by one page. * **Jump to top or bottom** - Press `HOME` or `END` to scroll to the top or bottom of terminal output. * **Scroll within a selected Block** - Press `SHIFT-CMD-UP` or `SHIFT-CMD-DOWN` to scroll to the top or bottom of the selected Block. * **Scroll one line at a time** - “Scroll Terminal output up/down one line” can be configured with a keyboard shortcut in Settings > Keyboard shortcuts or accessed from the [Command Palette](/terminal/command-palette/). * When the output of a command is cut off, Warp keeps the [Sticky Command Header](/terminal/blocks/sticky-command-header/) pinned at the top that displays the command the Block corresponds to. Clicking the header will scroll the screen to the start of the Block. * Windows * **Mouse or scrollbar** - Scroll using your mouse, trackpad, or the scrollbar. * **Arrow keys** - Select a Block and use `UP ↑` and `DOWN ↓` to move between Blocks. * **Page scrolling** - Press `PAGE UP` or `PAGE DOWN` to scroll by one page. * **Jump to top or bottom** - Press `HOME` or `END` to scroll to the top or bottom of terminal output. * **Scroll within a selected Block** - Press `CTRL-SHIFT-UP` or `CTRL-SHIFT-DOWN` to scroll to the top or bottom of the selected Block. * **Scroll one line at a time** - “Scroll Terminal output up/down one line” can be configured with a keyboard shortcut in Settings > Keyboard shortcuts or accessed from the [Command Palette](/terminal/command-palette/). * When the output of a command is cut off, Warp keeps the [Sticky Command Header](/terminal/blocks/sticky-command-header/) pinned at the top that displays the command the Block corresponds to. Clicking the header will scroll the screen to the start of the Block. * Linux * **Mouse or scrollbar** - Scroll using your mouse, trackpad, or the scrollbar. * **Arrow keys** - Select a Block and use `UP ↑` and `DOWN ↓` to move between Blocks. * **Page scrolling** - Press `PAGE UP` or `PAGE DOWN` to scroll by one page. * **Jump to top or bottom** - Press `HOME` or `END` to scroll to the top or bottom of terminal output. * **Scroll within a selected Block** - Press `CTRL-SHIFT-UP` or `CTRL-SHIFT-DOWN` to scroll to the top or bottom of the selected Block. * **Scroll one line at a time** - “Scroll Terminal output up/down one line” can be configured with a keyboard shortcut in Settings > Keyboard shortcuts or accessed from the [Command Palette](/terminal/command-palette/). * When the output of a command is cut off, Warp keeps the [Sticky Command Header](/terminal/blocks/sticky-command-header/) pinned at the top that displays the command the Block corresponds to. Clicking the header will scroll the screen to the start of the Block. Note During long-running or full-screen commands, `PAGE UP`, `PAGE DOWN`, `HOME`, and `END` are forwarded to the running program. See the full list of scrolling shortcuts on the [Keyboard Shortcuts](/getting-started/keyboard-shortcuts/) page. [Navigate between Blocks](https://www.loom.com/embed/21ebb0a79c1248a98846cba12a4b7020) # Block Filtering > Filter Block output by text, regex, or case to focus on specific matching lines. Filter the output lines of a block in Warp to quickly focus on a subset of the block. You can filter by plaintext, regex, invert, or make your filter case-sensitive. You can also add context lines to view output around matches. Filtering does not delete any output lines, so you can clear the filter to go back to the original output. ## How to filter a block [Section titled “How to filter a block”](#how-to-filter-a-block) To apply a filter to a block: 1. Click on the filter icon in the top right corner of a block. A filter editor will appear with a large input field with two buttons on the left and a smaller input field on the right. 2. Type in the input to filter the block in the left input field. Only lines containing text that matches the filter query will be shown. 3. (Optional) Click on the regex, case sensitive search, or invert filter buttons to enable. 4. (Optional) Type a number in the right input field to add context lines around matched lines. [![](/assets/terminal/block_filtering_with_context_lines.poster.jpg)](/assets/terminal/block_filtering_with_context_lines.mp4) * macOS You can also toggle a filter by: * Using the keybinding `OPT-SHIFT-F` by default to toggle filtering on the selected or latest block * Selecting `Toggle Block Filter` in the block context menu * Windows You can also toggle a filter on/off by: * Using the keybinding `ALT-SHIFT-F` to toggle filtering on the selected or latest block * Selecting `Toggle Block Filter` in the block context menu * Linux You can also toggle a filter on/off by: * Using the keybinding `ALT-SHIFT-F` to toggle filtering on the selected or latest block * Selecting `Toggle Block Filter` in the block context menu Note Toggling a filter on a block without a filter applied will open the filter editor. If you toggle a filter off, the same filter will be applied if you toggle filtering on again. [![](/assets/terminal/block_filtering_toggle.poster.jpg)](/assets/terminal/block_filtering_toggle.mp4) # Block Sharing > Share Blocks with your team as permalinks or embeddable HTML snippets. Note This action sends command information to our server and is explicitly opt-in. Read more about privacy at Warp on [our privacy page](https://www.warp.dev/privacy). Share your blocks with a permalink or HTML embed. You can get started with shared blocks by opening the context menu and copying the command, output, or prompt. ## How to share blocks [Section titled “How to share blocks”](#how-to-share-blocks) * macOS To share your blocks, follow these steps: 1. On a finished block, click the context menu and select **Share…** or select the block and hit `CMD-SHIFT-S`. 2. A modal will pop up that lets you title your block and customize it by selecting which parts of the block you want to share (e.g. command, output, prompt, etc.). 3. Click either “Create link” or “Get embed” depending on how you want to share your block. 4. The link or embed snippet will be copied to your clipboard. * Windows To share your blocks, follow these steps: 1. On a finished block, click the context menu and select **Share…** or by setting up a key bind for Share Block in **Settings** > **Keyboard shortcuts**. 2. A modal will pop up that lets you title your block and customize it by selecting which parts of the block you want to share (e.g. command, output, prompt, etc.). 3. Click either “Create link” or “Get embed” depending on how you want to share your block. 4. The link or embed snippet will be copied to your clipboard. * Linux To share your blocks, follow these steps: 1. On a finished block, click the context menu and select **Share…** or by setting up a key bind for Share Block in **Settings** > **Keyboard shortcuts**. 2. A modal will pop up that lets you title your block and customize it by selecting which parts of the block you want to share (e.g. command, output, prompt, etc.). 3. Click either “Create link” or “Get embed” depending on how you want to share your block. 4. The link or embed snippet will be copied to your clipboard. Note If you experience any issues with block sharing, please see our known issues for [troubleshooting steps](/support-and-community/troubleshooting-and-support/known-issues/#online-features-dont-work). [![](/assets/terminal/block-sharing-embed.poster.jpg)](/assets/terminal/block-sharing-embed.mp4) ## Permalink [Section titled “Permalink”](#permalink) Create and share a permalink to your blocks to collaborate with teammates. Here is the [web permalink](https://app.warp.dev/block/vzFATak939iqGWfNh7wsAP) of the block depicted below. ![Shared Block](/_astro/shared_block.D2IReJPD_Z1Qe5lH.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ## Embedded blocks [Section titled “Embedded blocks”](#embedded-blocks) Create and embed your blocks on web pages to help your readers follow along with technical writing. Readers can interact with an embedded block as they would with a block in Warp, with a context menu and styling. When you click “Get embed”, Warp will copy an `iframe` to your clipboard. Here’s an example `iframe`: ```html ``` #### Embedded block example on web page [Section titled “Embedded block example on web page”](#embedded-block-example-on-web-page) ![Embedded Block Example](/_astro/embed.Bsc43pKr_Z2isyMy.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ## Managing shared blocks [Section titled “Managing shared blocks”](#managing-shared-blocks) You can unshare a block by navigating to **Settings** > **Shared blocks**. Currently, shared blocks are accessible to anyone with the link. ## Link previews [Section titled “Link previews”](#link-previews) Shared permalinks will also display a preview of your code for quick context on each link. Note Compatible with any platform that supports Open Graph or Twitter meta tags. For example Slack, Twitter, Facebook, Telegram, Notion, and more … [Share and Unfurl a Block Preview](https://www.loom.com/embed/a78147fee8804c00b08a1decbc0d4e72) # Terminal Block Find > Search across Blocks from the bottom up, with regex, case-sensitive, and per-Block filtering options. ## What is it [Section titled “What is it”](#what-is-it) Find searches for matches in all your Blocks from the bottom up and can even be isolated to a specific Block. Note Since command outputs are contained within Blocks, you can still use the input editor when invoking find. ## How to access it [Section titled “How to access it”](#how-to-access-it) * macOS 1. Hitting `CMD-F` opens the find view which searches across the terminal (scoped within the current pane). 2. Within the find modal, you can also enable the regex toggle, find on a selected Block, and or toggle case sensitive search. * Windows 1. Hitting `CTRL-SHIFT-F` opens the find view which searches across the terminal (scoped within the current pane). 2. Within the find modal, you can also enable the regex toggle, find on a selected Block, and or toggle case sensitive search. * Linux 1. Hitting `CTRL-SHIFT-F` opens the find view which searches across the terminal (scoped within the current pane). 2. Within the find modal, you can also enable the regex toggle, find on a selected Block, and or toggle case sensitive search. ## How it works [Section titled “How it works”](#how-it-works) [![](/assets/terminal/find.poster.jpg)](/assets/terminal/find.mp4) # Sticky Command Header > Pin the running command at the top of the screen when scrolling through large Block outputs. Note For long-running commands that take up the full screen, the sticky header only shows after you start scrolling up. This is to prevent the header from blocking the top part of the output for commands like `git log` that simulate full-screen apps. ## How to access Sticky Command Header [Section titled “How to access Sticky Command Header”](#how-to-access-sticky-command-header) * macOS * Sticky Command Header is enabled by default. * Toggle Sticky Command Header by going to **Settings** > **Features** > **General** > toggle “Show sticky command header”. * Toggle by searching for “Sticky Command Header” within the [Command Palette](/terminal/command-palette/) or by pressing `CTRL-CMD-S`. * You can also “Toggle Sticky Command Header in Active Pane” with `CTRL-S`. This won’t disable the feature entirely, only minimize it on the active session. * Windows * Sticky Command Header is enabled by default. * Toggle the Sticky Command Header by going to **Settings** > **Features** > **General** > toggle “Show sticky command header”. * Toggle by searching for “Sticky Command Header” within the [Command Palette](/terminal/command-palette/) or by setting up a key bind in **Settings** > **Keyboard shortcuts**. * You can also “Toggle Sticky Command Header in Active Pane” in the Command Palette or by setting up a key bind in **Settings** > **Keyboard shortcuts**. This won’t disable the feature entirely, only minimize it on the active session. * Linux * Sticky Command Header is enabled by default. * Toggle the Sticky Command Header by going to **Settings** > **Features** > **General** > toggle “Show sticky command header”. * Toggle by searching for “Sticky Command Header” within the [Command Palette](/terminal/command-palette/) or by setting up a key bind in**Settings** > **Keyboard shortcuts**. * You can also “Toggle Sticky Command Header in Active Pane” in the Command Palette or by setting up a key bind in**Settings** > **Keyboard shortcuts**. This won’t disable the feature entirely, only minimize it on the active session. ## How to use Sticky Command Header [Section titled “How to use Sticky Command Header”](#how-to-use-sticky-command-header) * If a Block has a large output ( e.g. `seq 1 1000`), the header of the Block will show on the top of the active Window, Tab, or Pane. * Click on the Sticky Command Header to quickly jump to the top of the Block. * While active you can also minimize the Sticky Command Header on the active pane by clicking the UP/DOWN arrow in the middle of the header. ## How Sticky Command Header works [Section titled “How Sticky Command Header works”](#how-sticky-command-header-works) [Sticky Command Header Demo](https://www.loom.com/embed/a86967c057e44ab4bee4860ba80538b9) ![Toggle active header and Jump to bottom of block demo](/assets/terminal/sticky-header-toggle-active-demo.gif) Toggle active header and Jump to bottom of block demo. # Command completions overview > Warp's main features for command completions and autosuggestions. 1. [Completions](/terminal/command-completions/completions/) will suggest commands, option names, and path parameters for you. 2. [Autosuggestions](/terminal/command-completions/autosuggestions/) will automatically suggest commands as you type based on shell history and possible completions. ## Completions [Section titled “Completions”](#completions) [Completions Demo](https://www.loom.com/embed/92594c821ae341f69d5d1c1af56f2c69) ## Autosuggestions [Section titled “Autosuggestions”](#autosuggestions) [Autosuggestion Demo](https://www.loom.com/embed/5e87c52ae855486ab88ffb2f89aeaf73) # Autosuggestions > Warp will automatically suggest commands as you type based on shell history and possible completions. ## How to access it [Section titled “How to access it”](#how-to-access-it) * From the [Command Palette](/terminal/command-palette/), type in “Autosuggestions” to toggle. Note **Terminal Tip** You can change the keybinding for accepting autosuggestions to `Tab`. Configure this in the “Tab key behavior” setting under **Settings** > **Features** > **Terminal Input**. *Note: This will update the keybinding for opening the completions menu to `CTRL-SPACE`. You can also enable the “Open completions menu as you type” in **Settings** > **Features** > **Terminal Input** so that the completions menu opens automatically.* ## How to use it [Section titled “How to use it”](#how-to-use-it) * macOS There are several ways to accept autosuggestions, either completely or partially: * Complete an autosuggestion using the `RIGHT` arrow or `CTRL-F`. * `CTRL-E` also, completes the autosuggestion when your cursor is at the end of the buffer. * `CTRL-RIGHT` can be used to partially complete the autosuggestion one component at a time. * Windows There are several ways to accept autosuggestions, either completely or partially: * Complete an autosuggestion using the `RIGHT` arrow or `CTRL-F`. * `END` jumps to the last character in the Input Editor, then `RIGHT` completes the autosuggestion. * `CTRL-SHIFT-RIGHT` can be used to partially complete the autosuggestion one component at a time. * Linux There are several ways to accept autosuggestions, either completely or partially: * Complete an autosuggestion using the `RIGHT` arrow or `CTRL-F`. * `CTRL-E` jumps to the last character in the Input Editor, then `RIGHT` completes the autosuggestion. * `CTRL-SHIFT-RIGHT` can be used to partially complete the autosuggestion one component at a time. ## How it works [Section titled “How it works”](#how-it-works) [Autosuggestion Demo](https://www.loom.com/embed/5e87c52ae855486ab88ffb2f89aeaf73) # Tab completions > Get fuzzy-matched suggestions for commands, options, and paths by pressing Tab anywhere. ## What is it [Section titled “What is it”](#what-is-it) Completions feature fuzzy search capability that provides you with [approximate matches](https://en.wikipedia.org/wiki/Approximate_string_matching) for your queries. If you’re unsure about the exact syntax or spelling, you’ll be provided with suggestions based on your input, even if it’s not an exact match. ## How to access it [Section titled “How to access it”](#how-to-access-it) * Type out the beginning of your command, then press `TAB`. * To search for options and flags, you must type and press `TAB`. * Forgo `TAB` by enabling “Open completions menu as you type” in **Settings** > **Features** > **Terminal Input** ## How to use it [Section titled “How to use it”](#how-to-use-it) ### Completions [Section titled “Completions”](#completions) 1. Type `git checkout` (note the space) and then press `TAB` 2. A menu will show all of your local branches. You can select one using your mouse or the `UP ↑`/`DOWN ↓` arrow keys ### Completions on Aliases [Section titled “Completions on Aliases”](#completions-on-aliases) * Shell aliases - This is an alias for an entire command. For example, if you have `gc=git checkout` in alias, typing `gc` and hitting `TAB` should give you the same completion options as for `git checkout` . * Command aliases - This is an alias for a subcommand. For example, this could be setting `git status` to `git st`. With completions support, we could now suggest completions for `git status` even if you typed in `git st`. Note **Terminal Tip**\ The “Tab key behavior” setting under **Settings** > **Features** > **Terminal Input** can change the action that `Tab` is bound to. If `Tab` is not bound to open the completions menu, `ctrl-space` will be assigned as the default keybinding. *Note: You can also enable the “Open completions menu as you type” in **Settings** > **Features** > **Terminal Input** so that the completions menu opens automatically.* ## How it works [Section titled “How it works”](#how-it-works) [Completions Demo](https://www.loom.com/embed/92594c821ae341f69d5d1c1af56f2c69) ### Supported completion specs [Section titled “Supported completion specs”](#supported-completion-specs) | Command Name | Level of Support | | ----------------------- | ---------------- | | act | Partial | | adb | Partial | | afplay | Partial | | aftman | Partial | | ag | Partial | | agrippa | Partial | | amplify | Partial | | ansible | Partial | | ansible-config | Partial | | ansible-doc | Partial | | ansible-galaxy | Partial | | ansible-lint | Partial | | ansible-playbook | Partial | | appwrite | Partial | | arch | Partial | | asdf | Partial | | assimp | Partial | | atlas | Partial | | autojump | Partial | | aws | Partial | | babel | Partial | | banner | Partial | | base32 | Partial | | base64 | Partial | | basename | Partial | | basenc | Partial | | bat | Partial | | bazel | Partial | | bc | Partial | | black | Partial | | blitz | Partial | | bosh | Full | | brew | Full | | build-storybook | Partial | | bun | Partial | | bundle | Partial | | bw | Partial | | caffeinate | Partial | | cargo | Full | | cat | Partial | | cd | Partial | | cdk | Partial | | checkov | Partial | | chmod | Partial | | chown | Partial | | circleci | Partial | | clang | Partial | | clear | Partial | | clojure | Partial | | cloudflared | Partial | | cmake | Partial | | code | Partial | | code-insiders | Partial | | command | Partial | | composer | Partial | | conda | Full | | copilot | Partial | | cordova | Partial | | cosign | Partial | | cot | Partial | | cp | Partial | | create-completion-spec | Partial | | create-next-app | Partial | | create-nx-workspace | Partial | | create-react-app | Partial | | create-react-native-app | Partial | | create-remix | Partial | | create-t3-app | Partial | | create-video | Partial | | create-web3-frontend | Partial | | croc | Partial | | curl | Partial | | cut | Partial | | dart | Partial | | date | Partial | | dateseq | Partial | | datree | Partial | | dbt | Partial | | dd | Partial | | defaults | Full | | degit | Partial | | deno | Partial | | deployctl | Partial | | deta | Partial | | df | Partial | | diff | Partial | | dig | Partial | | direnv | Partial | | dirname | Partial | | django-admin | Partial | | do | Partial | | docker | Full | | docker-compose | Partial | | doctl | Partial | | dog | Partial | | doppler | Partial | | dotenv | Partial | | dotnet | Partial | | dotslash | Partial | | drush | Partial | | dtm | Partial | | du | Partial | | eb | Partial | | echo | Partial | | electron | Partial | | eleventy | Partial | | elif | Partial | | elixir | Partial | | elm | Partial | | elm-review | Partial | | else | Partial | | emacs | Partial | | esbuild | Partial | | eslint | Partial | | exa | Partial | | exec | Partial | | exercism | Partial | | expo | Partial | | expo-cli | Partial | | export | Partial | | fastlane | Partial | | fastly | Partial | | fd | Partial | | ffmpeg | Partial | | fig-teams | Partial | | file | Partial | | find | Partial | | firebase | Full | | fisher | Partial | | flutter | Full | | fly | Partial | | flyctl | Partial | | fmt | Partial | | fnm | Partial | | fold | Partial | | for | Partial | | forge | Partial | | fvm | Partial | | fzf | Partial | | fzf-tmux | Partial | | ganache-cli | Partial | | gatsby | Partial | | gcc | Partial | | gcloud | Partial | | gh | Full | | git | Full | | git-flow | Partial | | github | Partial | | gltfjsx | Partial | | go | Full | | goctl | Partial | | googler | Partial | | goreleaser | Partial | | gpg | Partial | | gradle | Partial | | graphcdn | Partial | | grep | Partial | | grex | Partial | | hardhat | Partial | | hasura | Partial | | hb-service | Partial | | head | Partial | | helm | Partial | | heroku | Full | | hexo | Partial | | hostname | Partial | | htop | Partial | | http | Partial | | https | Partial | | httpy | Partial | | hub | Partial | | hugo | Partial | | hx | Partial | | hyper | Partial | | id | Partial | | iex | Partial | | if | Partial | | ignite-cli | Partial | | install | Partial | | ionic | Partial | | j | Partial | | java | Partial | | jest | Partial | | join | Partial | | jq | Partial | | julia | Partial | | jupyter | Partial | | just | Partial | | keytool | Partial | | kill | Partial | | killall | Full | | kitty | Partial | | knex | Partial | | kool | Partial | | kubecolor | Partial | | kubectl | Full | | kubectx | Full | | kubens | Full | | laravel | Partial | | lerna | Partial | | less | Partial | | lima | Partial | | limactl | Partial | | ln | Partial | | lp | Partial | | lpass | Partial | | ls | Partial | | lsd | Partial | | mackup | Partial | | make | Full | | man | Full | | mas | Partial | | mask | Partial | | mdfind | Partial | | meteor | Partial | | micro | Partial | | mikro-orm | Partial | | minikube | Partial | | mix | Partial | | mkdir | Partial | | mkfifo | Partial | | mknod | Partial | | mob | Partial | | molecule | Partial | | mongocli | Partial | | mongosh | Partial | | more | Partial | | mosh | Partial | | mv | Partial | | mvn | Partial | | mysql | Partial | | n | Partial | | nano | Partial | | nativescript | Partial | | nc | Partial | | nest | Partial | | netlify | Partial | | networkQuality | Partial | | newman | Partial | | next | Partial | | ng | Full | | nginx | Partial | | ngrok | Partial | | nhost | Partial | | ni | Partial | | nl | Partial | | nocorrect | Partial | | node | Full | | noglob | Partial | | npm | Full | | npx | Partial | | nr | Partial | | nrm | Partial | | ns | Partial | | nu | Partial | | nuxi | Partial | | nuxt | Partial | | nvim | Partial | | nvm | Partial | | nx | Full | | nylas | Partial | | od | Partial | | oh-my-posh | Partial | | okta | Partial | | okteto | Partial | | omz | Partial | | onboardbase | Partial | | op | Partial | | opa | Partial | | open | Partial | | osascript | Partial | | pageres | Partial | | pandoc | Partial | | pass | Partial | | paste | Partial | | pathchk | Partial | | pdfunite | Partial | | pgcli | Partial | | php | Partial | | phpunit-watcher | Full | | ping | Partial | | pip | Full | | pip3 | Partial | | pipenv | Partial | | pm2 | Partial | | pmset | Partial | | pnpm | Partial | | pnpx | Partial | | pod | Partial | | poetry | Partial | | pre-commit | Partial | | preset | Partial | | prettier | Partial | | prisma | Partial | | projj | Partial | | ps | Partial | | pscale | Partial | | psql | Partial | | publish | Partial | | pulumi | Partial | | pushd | Partial | | pwd | Partial | | pyenv | Full | | python | Partial | | python3 | Partial | | qodana | Partial | | quickmail | Partial | | r | Partial | | rails | Partial | | railway | Partial | | rake | Partial | | rancher | Partial | | rbenv | Partial | | rclone | Partial | | react-native | Full | | readlink | Partial | | redwood | Partial | | remix | Partial | | remotion | Partial | | repeat | Partial | | rg | Partial | | rm | Partial | | rmdir | Partial | | robot | Partial | | rollup | Partial | | rscript | Partial | | rsync | Partial | | ruby | Partial | | rush | Partial | | rushx | Partial | | rustc | Partial | | rustup | Partial | | sam | Partial | | scc | Partial | | scp | Partial | | screen | Partial | | sed | Partial | | sequelize | Partial | | serve | Partial | | serverless | Partial | | sfdx | Partial | | sftp | Partial | | shopify | Partial | | shortcuts | Partial | | shred | Partial | | sips | Partial | | softwareupdate | Partial | | source | Partial | | splash | Partial | | split | Partial | | spotify | Partial | | sqlite3 | Partial | | src | Partial | | ssh | Full | | st2 | Partial | | start-storybook | Partial | | stat | Partial | | steadybit | Partial | | stepzen | Partial | | stripe | Partial | | su | Partial | | subl | Partial | | sudo | Partial | | swc | Partial | | swift | Partial | | sysctl | Partial | | tac | Partial | | tail | Partial | | tailscale | Partial | | tailwindcss | Partial | | tangram | Partial | | tar | Full | | task | Partial | | tccutil | Partial | | tee | Partial | | terraform | Full | | terragrunt | Partial | | tfenv | Partial | | tfsec | Partial | | then | Partial | | time | Partial | | tldr | Partial | | tmux | Full | | tmuxinator | Full | | tns | Partial | | tokei | Partial | | top | Partial | | touch | Partial | | tr | Partial | | traceroute | Partial | | trash | Partial | | trex | Partial | | trivy | Partial | | truffle | Partial | | truncate | Partial | | trunk | Partial | | ts-node | Partial | | tsc | Partial | | tsh | Partial | | turbo | Partial | | twiggy | Partial | | twilio | Partial | | typeorm | Partial | | uname | Partial | | uniq | Partial | | until | Partial | | until | Partial | | unzip | Partial | | vale | Partial | | valet | Partial | | vapor | Partial | | vault | Partial | | vela | Partial | | vercel | Partial | | vi | Partial | | vim | Partial | | vimr | Partial | | vite | Partial | | vite | Partial | | volta | Partial | | vr | Partial | | vsce | Partial | | vtex | Partial | | vue | Partial | | vue | Partial | | vultr-cli | Partial | | w | Partial | | w | Partial | | wasm-bindgen | Partial | | wasm-pack | Partial | | watson | Partial | | wc | Partial | | wc | Partial | | wd | Partial | | webpack | Partial | | wget | Partial | | whence | Partial | | where | Partial | | which | Partial | | while | Partial | | who | Partial | | whois | Partial | | wifi-password | Partial | | wifi-password | Partial | | wp | Partial | | wrangler | Partial | | wrk | Partial | | wscat | Partial | | xargs | Partial | | xcode-select | Partial | | xcodebuild | Partial | | xcodeproj | Partial | | xcrun | Partial | | xed | Partial | | yank | Partial | | yarn | Partial | | yo | Partial | | youtube-dl | Partial | | z | Partial | | z | Partial | | zapier | Partial | | zapier | Partial | | zip | Partial | | zoxide | Partial | # Command Palette > Command Palette is a global search to quickly locate Workflows, Notebooks, keyboard shortcuts, or other actions within Warp. ![Command Palette Panel](/_astro/command-palette-panel.BAKqteQC_1yrFa8.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Command Palette Panel. ## How to access it [Section titled “How to access it”](#how-to-access-it) * macOS You can access the Command Palette with the keyboard shortcut `CMD-P`. * Windows You can access the Command Palette with the keyboard shortcut `CTRL-SHIFT-P`. * Linux You can access the Command Palette with the keyboard shortcut `CTRL-SHIFT-P`. ## How it works [Section titled “How it works”](#how-it-works) * Start typing to search for workflows, notebooks, keyboard shortcuts, actions, toggles, etc. * Activate a specific filter, by clicking on the filter buttons or prepending your search with the following: * `workflows:` or `w:` will filter for [Workflows](/knowledge-and-collaboration/warp-drive/workflows/). * `prompts:` or `p:` will filter for [Prompts](/knowledge-and-collaboration/warp-drive/prompts/). * `notebook:` or `n:` will filter for [Notebooks](/knowledge-and-collaboration/warp-drive/notebooks/). * `env_vars:` will filter for [Environment Variables](/knowledge-and-collaboration/warp-drive/environment-variables/). * `files:` will filter for local files. * `drive:` will filter for [Warp Drive](/knowledge-and-collaboration/warp-drive/). * `actions:` will filter for Warp-specific actions like settings and features. * `sessions:` will filter for active sessions with [Session Navigation](/terminal/sessions/session-navigation/). * `launch_configs:` will filter for [Launch Configurations](/terminal/sessions/launch-configurations/). [Command Palette Demo](https://www.loom.com/embed/0e6108b295234637a0bb20cc941976e9) # Terminal comparisons overview > Compare Warp's performance and terminal feature support against other popular terminal emulators like iTerm2, Alacritty, and WezTerm. Warp is a modern terminal built in Rust with GPU rendering, agent support, and a code-editor-style input. Use this section to see how Warp stacks up against other popular terminals on raw performance and feature coverage. ## How Warp differs [Section titled “How Warp differs”](#how-warp-differs) * **Open source under AGPL v3** — Warp’s client lives at [`warpdotdev/warp`](https://github.com/warpdotdev/warp). You can read the code, build from source, and contribute. See [Contributing to Warp](/support-and-community/community/contributing/) for the flow. * **Built-in agents** — Warp ships with Warp Agent (powered by Oz) and supports third-party CLI agents like Claude Code, Codex, and Gemini CLI from the same terminal. * **Modern editing** — Cursor placement, multi-line input, block-based output, and integrated code review work like a text editor instead of a traditional terminal emulator. * **Cross-platform Rust core** — Warp ships on macOS, Linux, and Windows from a single Rust + GPU-rendered codebase. ## Benchmarks [Section titled “Benchmarks”](#benchmarks) * [Performance benchmarks](/terminal/comparisons/performance/) — VTE and Termbench results comparing Warp against Terminal.app, iTerm2, Alacritty, and WezTerm. # Performance benchmarks > This is a short comparison of different terminals and their performance. ## Terminal apps selected for these benchmarks [Section titled “Terminal apps selected for these benchmarks”](#terminal-apps-selected-for-these-benchmarks) We chose to benchmark Warp against 4 other terminal emulator applications, based on their popularity as well as language and principles. Here is the list of the applications we chose for this comparison together with the explanation as to why we decided to include it in our comparison: * Terminal.app - the default terminal app available on the macOS; * ITerm2 - one of the most popular terminal emulators used by macOS users; * Alacritty & WezTerm - both of those terminals are written in Rust and are well-known for their speed and overall performance, things that Warp is aiming for. ### Versions & settings used during the comparison [Section titled “Versions & settings used during the comparison”](#versions--settings-used-during-the-comparison) | Terminal | Version | Terminal size (cols / rows, window is identical pixel-wise) | | ------------ | ------------------------------ | ----------------------------------------------------------- | | Warp | v0.2022.04.01.01.37.stable\_03 | 208 cols / 54 rows | | Terminal.app | Version 2.11 (440) | 188 cols / 72 rows | | iTerm2 | Build 3.4.15 | 211 cols / 78 rows | | Alacritty | alacritty 0.10.1 (2844606) | 286 cols / 102 rows | | Wezterm | 20220319-142410-0fcdea07 | 243 cols / 80 rows | ### About benchmarks [Section titled “About benchmarks”](#about-benchmarks) We link the source code of each benchmark used, so you can easily reproduce the tests with other terminal apps. Please, note that those benchmarks are not exhaustive. Comparing terminal emulators with each other is not an easy task - right now we’re checking how each of the apps behaves when dealing with lots of input and/or output. Ideally, the benchmarks would also cover the latency (time between pressing a key and the character showing on the screen, but also a delay between the user’s input and communication with the shell). We may include tests that account for that in the future. ## VTE benchmark [Section titled “VTE benchmark”](#vte-benchmark) Benchmark code can be found [here](https://github.com/alacritty/vtebench) with the specific commit we used in our comparison: `93bcc32b6e0f7560e9b1a5a8b0998c04fbf9b50d`. Results in milliseconds. ### Average time for each of the benchmark tests [Section titled “Average time for each of the benchmark tests”](#average-time-for-each-of-the-benchmark-tests) | | Warp avg (ms) | Terminal.app avg (ms) | iTerm avg | Alacritty avg | WezTerm avg | | -------------------------------- | ------------- | --------------------- | --------- | ------------- | ----------- | | dense\_cells | 43.88 | 24.91 | 144.84 | 7.25 | 28.15 | | scrolling | 30.06 | 283.34 | 1257.57 | 31.75 | 687.77 | | scrolling\_bottom\_region | 117.34 | 257.23 | 1294.25 | 29.1 | 672.67 | | scrolling\_bottom\_small\_region | 114.52 | 227.75 | 1251 | 25.98 | 669.93 | | scrolling\_fullscreen | 37.4 | 307.03 | 1565.17 | 37.36 | 1205 | | scrolling\_top\_region | 120.63 | 209.29 | 2212.2 | 84.42 | 682.6 | | scrolling\_top\_small\_region | 114.64 | 205.59 | 1216.33 | 21.91 | 663.44 | | unicode | 66.47 | 34.45 | 93.01 | 16.78 | 1279.25 | ![VTEbench average results (logarithmic scale )](/_astro/vtebench_avg.DWyIP7Kx_1YLczf.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ### P90 of the results [Section titled “P90 of the results”](#p90-of-the-results) | | Warp p90 | Terminal.app p90 | iTerm p90 | Alacritty p90 | WezTerm p90 | | -------------------------------- | -------- | ---------------- | --------- | ------------- | ----------- | | dense\_cells | 52 | 28 | 189 | 8 | 32 | | scrolling | 32 | 266.76 | 1336 | 32 | 707 | | scrolling\_bottom\_region | 170 | 243 | 1398 | 30 | 686 | | scrolling\_bottom\_small\_region | 167 | 224 | 1331 | 30 | 679 | | scrolling\_fullscreen | 38 | 327 | 1593 | 41 | 1208 | | scrolling\_top\_region | 178 | 222 | 2243 | 85 | 686 | | scrolling\_top\_small\_region | 167 | 222 | 1314 | 30 | 666 | | unicode | 77 | 39 | 90 | 20 | 3883 | ![VTEbench p90 results (logarithmic scale )](/_astro/vtebench_p90.Dub4mk1f_2fkOAF.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ## Termbench [Section titled “Termbench”](#termbench) Benchmark code can be found [here](https://github.com/cmuratori/termbench) with the specific commit we used in our comparison: `82afbc69256b4e22de913f0f02f82e0480f3dac5`. Below you’ll find results for small and regular test sizes. Note that Terminal.app only participated in the small test. Results in seconds. ### Small test sizes [Section titled “Small test sizes”](#small-test-sizes) | | Warp small (s) | Terminal.app small (s) | iTerm small (s) | Alacritty small | WezTerm small | | -------------- | -------------- | ---------------------- | --------------- | --------------- | ------------- | | ManyLine | 6.7854 | 2.6789 | 8.7057 | 1.2532 | 8.9436 | | LongLine | 9.0033 | 1.6473 | 9.0849 | 0.8179 | 11.4587 | | FGPerChar | 1.3716 | 453.9888 | 2.6625 | 0.2788 | 0.6487 | | FGBGPerChar | 2.8403 | 908.894 | 4.5881 | 0.5931 | 0.7283 | | overall result | 20.0006 | 1367.209 | 25.0413 | 2.943 | 21.7793 | ![Termbench small results (logarithmic scale )](/_astro/termbench_small.BU2jelB2_1vn9r.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ### Regular test size [Section titled “Regular test size”](#regular-test-size) | | Warp regular (s) | iTerm regular (s) | Alacritty regular (s) | WezTerm regular | | -------------- | ---------------- | ----------------- | --------------------- | --------------- | | ManyLine | 113.76 | 132.4975 | 19.8802 | 150.8175 | | LongLine | 155.0937 | 126.7561 | 12.7859 | 207.3647 | | FGPerChar | 21.8928 | 39.3352 | 4.2925 | 9.4265 | | FGBGPerChar | 46.312 | 50.5369 | 8.418 | 13.5142 | | overall result | 337.0585 | 349.1258 | 45.3767 | 381.1229 | ![Termbench results (logarithmic scale)](/_astro/termbench_regular.Bp79nbrM_HwDez.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) # Terminal features > Below you'll find a table showcasing different terminal features (such as text attribution) and information about which one of those are supported in Warp. To make it more transparent & useful, we also show the results for 4 other popular macOS terminal emulators. | Feature | Warp | Terminal.app | Iterm | Alacritty | Wezterm | | --------------------------------------------------------- | ---- | ------------ | ----- | --------- | ------- | | 24-bit (true color) | YES | NO | YES | YES | YES | | Bold | YES | YES | YES | YES | YES | | Dim | NO | YES | YES | YES | YES | | Italic | NO | YES | YES | YES | YES | | Underline | YES | YES | YES | YES | YES | | Underline (alt) | YES | NO | YES | YES | YES | | Double underline | NO | NO | NO | NO | YES | | Double underline (alt) | YES | NO | YES | YES | YES | | Curly underline | NO | NO | YES | NO | YES | | Colored underline | NO | NO | NO | NO | YES | | Blink | NO | YES | NO | NO | NO | | Reverse | YES | YES | YES | YES | YES | | Invisible (but copy-paste-able) | NO | YES | NO | YES | NO | | Strikethrough | YES | NO | YES | YES | YES | | Overline | NO | NO | NO | NO | YES | | [Magic string](https://en.wikipedia.org/wiki/Unicode#Web) | YES | YES | YES | YES | YES | | Emojis | YES | YES | YES | YES | YES | | Right-to-left | NO | YES | NO | NO | NO | | Sixel graphics | NO | NO | YES | NO | NO | Based on the [terminal-testdrive.sh](https://gist.github.com/hellricer/e514d9615d02838244d8de74d0ab18b3). # Modern text editing overview > Unlike other terminals, Warp’s input editor operates out of the box like a modern IDE and the text editors we’re used to. Note Text Editor Input also works for [SSH sessions](/terminal/warpify/ssh/). ### Soft Wrapping [Section titled “Soft Wrapping”](#soft-wrapping) Warp supports soft wrapping in the input editor. If an autosuggestion goes off-screen, the input editor will be horizontally scrollable to make it visible. Some operations treat soft-wrapped lines like a logical line (`TRIPLE-CLICK`) while other operations treat soft wrapped lines like visible different lines (`UP`/`DOWN`, `SHIFT-UP`/`SHIFT-DOWN`). ### Copy on Select [Section titled “Copy on Select”](#copy-on-select) Warp supports copy on select for selectable text within [Blocks](/terminal/blocks/). * Toggle this feature **Settings** > **Features** > **Terminal** or search for “Copy on select” in the [Command Palette](/terminal/command-palette/). ### Autocomplete quotes, parentheses, and brackets [Section titled “Autocomplete quotes, parentheses, and brackets”](#autocomplete-quotes-parentheses-and-brackets) Warp can automatically complete quotes, brackets, and parentheses like you’re used to in IDEs. * Toggle this feature **Settings** > **Features** > **Text Editing** or search for “Autocomplete quotes” in the [Command Palette](/terminal/command-palette/). ## How to use it [Section titled “How to use it”](#how-to-use-it) * macOS | Keyboard binding | Shortcut description | | ---------------------------------------------------- | ------------------------------------------------------ | | `ESCAPE` | Closes the input suggestions or history menu | | `CTRL-L` | Clears the terminal | | `CTRL-H` | Backspace | | `CTRL-C` | Clear the entire editor buffer | | `CTRL-U` | Copy and Clear the current line | | `CMD-SHIFT-K` | Clear selected lines | | `CMD-C`, `CMD-X`, `CMD-V` | Copy, cut, paste | | `CTRL-W` / `OPT-D` | Cut the word to the left / right of the cursor | | `OPT-BACKSPACE` / `OPT-D` | Delete the word to the left / right of the cursor | | `CTRL-K CMD-DELETE` | Delete everything to the right of the cursor | | `OPT-LEFT` / `OPT-RIGHT` | Move to the beginning of the previous / next word | | `CTRL-OPT-LEFT` / `CTRL-OPT-RIGHT` | Move backward / forward by one subword | | `CMD-LEFT` `CTRL-A`/ `CTRL-E` `CMD-DOWN` `CMD-RIGHT` | Move the cursor to the start / end of the line | | `SHIFT-LEFT` / `SHIFT-RIGHT` | Select the character to the left / right of the cursor | | `OPT-SHIFT-LEFT` / `OPT-SHIFT-RIGHT` | Select the word to the left / right of the cursor | | `CMD-SHIFT-LEFT` / `CMD-SHIFT-RIGHT` | Select everything to the left / right of the cursor | | `SHIFT-UP` / `SHIFT-UP` | Select everything above / below the cursor | | `CMD-A` | Select the entire editor buffer | | `SHIFT-ENTER` `CTRL-ENTER` `OPT-ENTER` | Insert newline | | `CTRL-R` | Command Search | | `CMD-D` | Split pane | * Windows | Keyboard binding | Shortcut description | | -------------------------------------- | ------------------------------------------------------ | | `ESCAPE` | Closes the input suggestions or history menu | | `CTRL-L` | Clears the terminal | | `CTRL-H` | Backspace | | `CTRL-C` | Clear the entire editor buffer | | `CTRL-U` | Copy and Clear the current line | | `CTRL-SHIFT-K` | Clear selected lines | | `CTRL-C`, `CTRL-X`, `CTRL-V` | Copy, cut, paste | | `CTRL-W` / `ALT-D` | Cut the word to the left / right of the cursor | | `ALT-BACKSPACE` / `ALT-D` | Delete the word to the left / right of the cursor | | `CTRL-K` | Delete everything to the right of the cursor | | `ALT-LEFT` / `ALT-RIGHT` | Move to the beginning of the previous / next word | | `CTRL-LEFT` / `CTRL-RIGHT` | Move backward / forward by one subword | | `CTRL-A`/ `CTRL-E` | Move the cursor to the start / end of the line | | | Select the character to the left / right of the cursor | | `META-SHIFT-B` / `META-SHIFT-F` | Select the word to the left / right of the cursor | | | Select everything to the left / right of the cursor | | `SHIFT-UP` / `SHIFT-UP` | Select everything above / below the cursor | | `CTRL-A` | Select the entire editor buffer | | `SHIFT-ENTER` `CTRL-ENTER` `ALT-ENTER` | Insert newline | | `CTRL-R` | Command Search | | `CTRL-SHIFT-D` | Split pane | * Linux | Keyboard binding | Shortcut description | | -------------------------------------- | ------------------------------------------------------ | | `ESCAPE` | Closes the input suggestions or history menu | | `CTRL-L` | Clears the terminal | | `CTRL-H` | Backspace | | `CTRL-C` | Clear the entire editor buffer | | `CTRL-U` | Copy and Clear the current line | | `CTRL-SHIFT-K` | Clear selected lines | | `CTRL-C`, `CTRL-X`, `CTRL-V` | Copy, cut, paste | | `CTRL-W` / `ALT-D` | Cut the word to the left / right of the cursor | | `ALT-BACKSPACE` / `ALT-D` | Delete the word to the left / right of the cursor | | `CTRL-K` | Delete everything to the right of the cursor | | `ALT-LEFT` / `ALT-RIGHT` | Move to the beginning of the previous / next word | | `CTRL-LEFT` / `CTRL-RIGHT` | Move backward / forward by one subword | | `CTRL-A`/ `CTRL-E` | Move the cursor to the start / end of the line | | | Select the character to the left / right of the cursor | | `META-SHIFT-B` / `META-SHIFT-F` | Select the word to the left / right of the cursor | | | Select everything to the left / right of the cursor | | `SHIFT-UP` / `SHIFT-UP` | Select everything above / below the cursor | | `CTRL-A` | Select the entire editor buffer | | `SHIFT-ENTER` `CTRL-ENTER` `ALT-ENTER` | Insert newline | | `CTRL-R` | Command Search | | `CTRL-SHIFT-D` | Split pane | ## How it Works [Section titled “How it Works”](#how-it-works) [Text Editor Input Demo](https://www.loom.com/embed/1517049fefc34227bf1abaf19cc7e6ea) ![soft wrapping text in Warp input editor](/_astro/soft-wrapping.BKVrRDtB_lpNoy.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Soft wrapping applied to long lines in the editor. # Alias Expansion > Warp will automatically expand your aliases as you type in the input editor. ## How to use it [Section titled “How to use it”](#how-to-use-it) * macOS When Alias Expansion is enabled, type an alias and then hit `SPACE` will expand the alias. To insert a space without expanding an alias, the default keybinding is `OPT-SPACE`. * Windows When Alias Expansion is enabled, type an alias and then hit `SPACE` will expand the alias. To insert a space without expanding an alias, the default keybinding is `ALT-SPACE`. * Linux When Alias Expansion is enabled, type an alias and then hit `SPACE` will expand the alias. To insert a space without expanding an alias, the default keybinding is `ALT-SPACE`. Note Aliases will not be expanded when the command in the expanded form is the same as the alias itself. e.g. if you have an alias `ls='ls -G'`, `ls` will not be expanded in the input editor. ## How to access it [Section titled “How to access it”](#how-to-access-it) Alias expansion is disabled by default. There are two ways to toggle this on and off: * From Settings: Navigate to **Settings** > **Features** > **Terminal Input** and toggle “Expand aliases as you type”. * From the [Command Palette](/terminal/command-palette/#windows): Search for the “Enable/disable alias expansion” option and hit `ENTER`. ## How it works [Section titled “How it works”](#how-it-works) [Alias Expansion Demo](https://www.loom.com/embed/2267657c033e482890eea75a8a6c5373) # Command Inspector > Command Inspector (also known as Command X-Ray) surfaces documentation for sub-parts of your command, directly in Warp's Input Editor. ## How to access it [Section titled “How to access it”](#how-to-access-it) * macOS Hover over the part of the command you want to inspect with your mouse or press `CMD-SHIFT-I` to inspect the cursor’s current location. * Windows Hover over the part of the command you want to inspect with your mouse or press `CTRL-SHIFT-I` to inspect the cursor’s current location. * Linux Hover over the part of the command you want to inspect with your mouse or press `CTRL-SHIFT-I` to inspect the cursor’s current location. ## How it works [Section titled “How it works”](#how-it-works) [Command Inspector Demo](https://www.loom.com/embed/a00259927ada41b2895fd5c4072a3dcc) # Syntax & Error Highlighting > Color-code commands and underline errors in real time as you type in Warp's input editor. ## What is syntax highlighting [Section titled “What is syntax highlighting”](#what-is-syntax-highlighting) Warp supports Syntax Highlighting in the [Input Editor.](/terminal/editor/) It colors each part of a command to help differentiate between sub-commands, options/flags, arguments, and variables. Caution Newly installed apps or newly created aliases will not trigger syntax highlighting until you open a new Warp session (new window, tab, or pane), even if you `source` the RC files in the current session. ### How to access syntax highlighting [Section titled “How to access syntax highlighting”](#how-to-access-syntax-highlighting) When Syntax Highlighting is enabled, Warp’s [Input Editor](/terminal/editor/) automatically recognizes each part of the command as you type it into the Input Editor, and syntactically highlight them. ### How to enable/disable syntax highlighting [Section titled “How to enable/disable syntax highlighting”](#how-to-enabledisable-syntax-highlighting) Syntax highlighting is enabled by default, to toggle it: * Through the [Command Palette](/terminal/command-palette/), search for the “Syntax Highlighting” option and click it (or press enter) to enable/disable. * Through **Settings** > **Features** > **Terminal Input** , toggle “Syntax highlighting for commands” ### How syntax highlighting works [Section titled “How syntax highlighting works”](#how-syntax-highlighting-works) [Syntax Highlighting Demo](https://www.loom.com/embed/87b15de13ee9407b98a24f1a31835784) ## What is error underlining [Section titled “What is error underlining”](#what-is-error-underlining) Warp highlights errors in commands that are typed within the [Input Editor](/terminal/editor/) e.g. if the binary for the command you’ve typed does not exist. Caution Newly installed apps or newly created aliases will trigger error underlining until you open a new Warp session (new window, tab, or pane), even if you `source` the RC files in the current session. ### How to access error underlining [Section titled “How to access error underlining”](#how-to-access-error-underlining) When Error Underlining is enabled, Warp automatically underlines any invalid commands with a dashed red underline. ### How to enable/disable error underlining [Section titled “How to enable/disable error underlining”](#how-to-enabledisable-error-underlining) Error underlining is enabled by default, to toggle it: * Through the [Command Palette](/terminal/command-palette/), search for the “Syntax Highlighting” option and click it (or press enter) to enable/disable. * Through **Settings** > **Features** > **Terminal Input** , toggle “Error underlining for commands” ### How error underlining works [Section titled “How error underlining works”](#how-error-underlining-works) [Error Underlining Demo](https://www.loom.com/embed/7721e06ed4aa4e1380abae4f5827ef6f) # Input editor Vim keybindings > Use input editor Vim keybindings (also known as Vim mode) to edit commands quickly in Warp. ## About Vim keybindings [Section titled “About Vim keybindings”](#about-vim-keybindings) The Vi family of programs (including Vim and Neovim) are modal text editors that allow for keyboard-driven text editing. Several shells, including `bash` and `zsh`, implement vi-style keybindings. Warp’s input editor was built natively to support more modern text editing experiences, which means it replaces the shell’s editor capabilities. Warp has its implementation of Vim keybindings (also known as Vim mode) you can use. ### How to enable Vim keybindings [Section titled “How to enable Vim keybindings”](#how-to-enable-vim-keybindings) Note With `bash` and `zsh`, Warp attempts to detect the shell’s keybinding settings. If a shell vi mode is detected, Warp may suggest enabling Vim keybindings (also known as Vim mode). To manually toggle Vim keybindings in Warp’s input editor: * Through the [Command Palette](/terminal/command-palette/), search for “Vim Keybindings”. * Through **Settings** > **Features** > **Text Editing**, toggle “Edit commands with Vim keybindings”. As in `bash` and `zsh`’s vi mode implementations, the editor starts in insert mode. Pressing `CTRL-C` or `ENTER` clears any pending command state. ### Customizing Keybindings [Section titled “Customizing Keybindings”](#customizing-keybindings) At the moment, Warp only supports default Vim keybindings. One exception is the keyboard shortcut for exiting insert mode, which can be rebound under**Settings** > **Keyboard shortcuts** > **Exit Vim Insert Mode**, or through the [Command Palette](/terminal/command-palette/) search for “Exit Vim Insert Mode”. ## Supported Keybindings [Section titled “Supported Keybindings”](#supported-keybindings) Below is a list of the vim functionality implemented in Warp so far. ### Movement [Section titled “Movement”](#movement) See [Vim docs: motion](https://vimdoc.sourceforge.net/htmldoc/motion.html) for more information. #### Basic [Section titled “Basic”](#basic) | Command(s) | Description | | ---------------------------- | --------------------------------------------------- | | `h`, `j`, `k`, `l` | single-char movement | | ``, `` | single-char movement with line wrap | | `w`, `W`, `b`, `B`, `e`, `E` | word movement | | `ge`, `gE` | end of previous word | | `$` | end of line | | `0` | beginning of line | | `^` | first non-whitespace character of line | | `%` | jump to matching bracket | | `[`, `]` | prev/next unmatched bracket | | `_` | beginning of the current line | | `+` | first non-whitespace character of the next line | | `-` | first non-whitespace character of the previous line | #### Multi-line-related [Section titled “Multi-line-related”](#multi-line-related) | Command(s) | Description | | ---------- | ----------------------- | | `gg`, `G` | jump to first/last line | ### Editing [Section titled “Editing”](#editing) | Command(s) | Description | | ---------- | ----------------------------------------------------------- | | `r` | replace character under cursor | | `d`, `D` | delete a range or object | | `c`, `C` | change a range or object (delete, then go to insert mode) | | `s`, `S` | substitute (like change, but can only delete at the cursor) | | `x`, `X` | delete under cursor | | `y`, `Y` | yank (copy) into the clipboard | | `p`, `P` | paste from the clipboard | | `u`, `⌃r` | undo, redo | | `~` | toggle upper/lowercase under cursor | | `gu` | lowercase under cursor (`u` in visual mode) | | `gU` | uppercase under cursor (`U` in visual mode) | | `J` | join current and following lines | | `.` | repeat last edit | See [Vim docs: editing](https://vimdoc.sourceforge.net/htmldoc/editing.html) for more information. #### Text Objects [Section titled “Text Objects”](#text-objects) | Command(s) | Description | | ---------------- | ------------------------------------------ | | `i` | inner (exclude delimiters in text object) | | `a` | around (include delimiters in text object) | | `w`, `W` | whitespace-delimited string (word) | | `"`, `'`, \`\`\` | quote-delimited string | | `(`, `{`, `[` | parenthesized/bracketed string | See [Vim docs: text objects](https://vimdoc.sourceforge.net/htmldoc/motion.html#text-objects) for more information. ### Search [Section titled “Search”](#search) #### Character Search [Section titled “Character Search”](#character-search) | Command(s) | Description | | ------------------ | ------------------------------------------------------ | | `t`, `T`, `f`, `F` | find next/prev matching character on line | | `;` | repeat last character search in the same direction | | `,` | repeat last character search in the opposite direction | See [Vim docs: left-right motions](https://vimdoc.sourceforge.net/htmldoc/motion.html#f) for more information. #### General Search [Section titled “General Search”](#general-search) Unlike Vim, general search commands don’t search within the buffer. Instead, they open Warp’s native command search. | Command(s) | Description | | ------------------ | ------------------------ | | `/`, `?`, `*`, `#` | open Warp command search | ### Mode Switching [Section titled “Mode Switching”](#mode-switching) | Command(s) | Description | | ---------- | ----------------------------------------------------------------- | | `i` | insert text before the cursor | | `I` | insert text before the first non-whitespace character in the line | | `a` | append text after the cursor | | `A` | append text at the end of the line | | `o` | begin new line below the cursor and insert text | | `O` | begin new line above the cursor and insert text | | `v` | visual character mode | | `V` | visual line mode | See [Vim docs: insert](https://vimdoc.sourceforge.net/htmldoc/insert.html#insert) and [Vim docs: visual mode](https://vimdoc.sourceforge.net/htmldoc/visual.html#visual-mode) for more information. ### Registers [Section titled “Registers”](#registers) | Command(s) | Description | | ---------- | --------------- | | `"` | register prefix | Warp currently supports the following registers: | Register name | Description | | ---------------- | ---------------------------------------------------------------- | | `a`–`z`, `A`–`Z` | named registers | | `+` | system clipboard | | `*` | system clipboard | | `"` | unnamed register, containing the text of the last delete or yank | See [Vim docs: registers](https://vimdoc.sourceforge.net/htmldoc/change.html#registers) for more information. ## Feedback [Section titled “Feedback”](#feedback) The best way to report bugs and request features is through Warp’s [GitHub Issues](https://github.com/warpdotdev/Warp/issues) page. Please note that the issue or request is for Vim Keybindings. # Command entry overview > Warp's main features for Command Entry, History, Synchronized Inputs, YAML Workflows and More! 1. [Command Corrections](/terminal/entry/command-corrections/) provides auto-correct suggestions on previously run commands to catch typos, and forgotten flags, and fix general console errors. 2. [Command Search](/terminal/entry/command-search/) is a 3-in-1 panel that allows you to search across Command History, Workflows, Notebooks, and AI Command Search all at once. 3. [Command History](/terminal/entry/command-history/) allows Warp to isolate the history of each shell session to make previously run commands easily accessible. 4. [Synchronized Inputs](/terminal/entry/synchronized-inputs/) allow you to easily run the same command in multiple sessions at the same time. 5. [YAML Workflows](/terminal/entry/yaml-workflows/) are easier to execute and share parameterized and searchable commands within Warp. ## Command Corrections [Section titled “Command Corrections”](#command-corrections) [Command Corrections Demo](https://www.loom.com/embed/180e1dc8d1504ec39c00694d9fd71b7c) ## Command Search [Section titled “Command Search”](#command-search) [Command Search Demo](https://www.loom.com/embed/21a6f58a33754ee7913edbff6d33d8d1) ## Command History [Section titled “Command History”](#command-history) [Command History Demo](https://www.loom.com/embed/8119beca8d794b06859c5dea1b1377bb) ## YAML Workflows [Section titled “YAML Workflows”](#yaml-workflows) [![](/assets/terminal/yaml_workflows_demo.poster.jpg)](/assets/terminal/yaml_workflows_demo.mp4) # Command Corrections > Command Corrections provides auto-correct suggestions on previously run commands to catch typos and forgotten flags, and fix general console errors. ## What is it [Section titled “What is it”](#what-is-it) This feature was built on top of the open-source project [nvdn/thefuck](https://github.com/nvbn/thefuck). Here are some examples that the Warp team usually finds Command Corrections useful for: * Misspelled commands * `gti checkout myBranchName` -> `git checkout myBranchName` * `cd ap/sorce/executtor` -> `cd app/source/executor` * Missing flags * `git push` -> `git push –set-upstream myBranchName` * Add permissions * `./script` -> `chmod +x ./script && ./script` ## How to access it [Section titled “How to access it”](#how-to-access-it) * Command Corrections is enabled by default. You can disable Command Corrections by going to **Settings** > **Features** > **Terminal Input** > toggle “Suggest corrected commands”. * After an incorrect command is run, a panel with the corrected command suggestion appears above the Input Editor. `CLICK` or press the `RIGHT` arrow to insert the suggestion. ## How it works [Section titled “How it works”](#how-it-works) [Command Corrections Demo](https://www.loom.com/embed/180e1dc8d1504ec39c00694d9fd71b7c) #### Command correction rules: [Section titled “Command correction rules:”](#command-correction-rules) | Command | | ------------------------------------------------------------- | | brew | | cargo | | cat | | cd | | chmod | | conda | | cp | | docker | | generic (command agnostic, e.g. mis-spelling executable name) | | git | | go | | grep | | java | | ls | | mkdir | | npm | | pip | | python | | sed | | sudo | | yarn | # Command History > Command History helps you quickly find previously run commands. ## What is it [Section titled “What is it”](#what-is-it) While running, Warp isolates the history of each shell session e.g. if you have two Split Panes open, commands created in one pane do not populate the history of the other. Warp combines the history upon closing. Command History also provides rich information like exit code, directory, thread, time to finish running, last run, etc. ![Command History rich information](/_astro/command-history-rich.B01m8neh_Z1iuWsY.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Command history with rich metadata. ## How to access it [Section titled “How to access it”](#how-to-access-it) * Hitting `UP` in the [Input Editor](/terminal/editor/) brings up your history and performs a prefix search based on input. * Pressing `CTRL-R` opens the [Command Search](/terminal/entry/command-search/) panel and initiates a search of your Command History. To navigate the Command Search panel: * Start typing and Warp will automatically filter using fuzzy search. Warp bolds matching text when filtering with fuzzy search. ## How it works [Section titled “How it works”](#how-it-works) [Command History Demo](https://www.loom.com/embed/8119beca8d794b06859c5dea1b1377bb) # Command Search > Search command history, Workflows, Prompts, and agent conversations with fuzzy matching. The Command Search panel provides unified search across all your terminal inputs, saved commands, and [Terminal and Agent modes](/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes/) conversation history. Use it to quickly find and reuse commands, workflows, or past agent interactions. ![Command Search Panel](/_astro/command-search-panel.BfFjgrU7_1Aeuhb.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Note Tailor your Command Search experience by toggling off “Show Global Workflows” in **Settings** > **Features** > **Workflows**. When disabled, your search will exclusively encompass YAML and Warp Drive Workflows. ## Quickstart [Section titled “Quickstart”](#quickstart) 1. Press `CTRL-R` to open the Command Search Panel 2. Type your search query in the input box 3. Press `ENTER` to input the selected command into Warp’s Input Editor ## Search Filters [Section titled “Search Filters”](#search-filters) You can filter your search results by prepending your search term with any of the following: | Filter | Shortcuts | | --------------------------------------------------------------------------- | ------------------------------- | | Command History | `history:`, `h:`, or `H-TAB` | | Prompts | `prompts:`, `p:`, or `P-TAB` | | [Agent Mode](/agent-platform/local-agents/interacting-with-agents/) History | `ai_history:`, `a:`, or `A-TAB` | Note When a filter is activated, it will be bolded and italicized in the search panel. ## Additional Features [Section titled “Additional Features”](#additional-features) * You can expand the menu horizontally by dragging the right edge * The panel supports fuzzy search and ranks results by relevance ## How it works [Section titled “How it works”](#how-it-works) [Command Search Demo](https://www.loom.com/embed/21a6f58a33754ee7913edbff6d33d8d1) # Synchronized Inputs > Type a command once and sync it to multiple panes simultaneously. ### Synchronized inputs vs. broadcast input [Section titled “Synchronized inputs vs. broadcast input”](#synchronized-inputs-vs-broadcast-input) Synchronized inputs in Warp work similarly to “broadcast input” settings in other terminals, but there are some differences. With Warp’s synchronized inputs, whatever command you enter in one session will sync to the other sessions in its entirety. Whereas, “broadcast input” typically allows you to “broadcast” individual keystrokes, which may be more suitable for editing parts of commands. ## How to access it [Section titled “How to access it”](#how-to-access-it) There are three ways to access controls to synchronize inputs: * [Command Palette](/terminal/command-palette/) in Warp: Search for “synchronize” * macOS menus for the Warp app: `Edit > Synchronize Input` ## How to use it [Section titled “How to use it”](#how-to-use-it) * macOS There are two modes available to scope how input is synchronized and one to stop any synchronization: * Synchronize All Panes in All Tabs * Synchronize All Panes in Current Tab `OPT-CMD-I` * Stop Synchronizing Any Panes `OPT-CMD-I` * Windows There are two modes available to scope how input is synchronized and one to stop any synchronization: * Synchronize All Panes in All Tabs * Synchronize All Panes in Current Tab `CTRL-ALT-I` * Stop Synchronizing Any Panes `CTRL-ALT-I` * Linux There are two modes available to scope how input is synchronized and one to stop any synchronization: * Synchronize All Panes in All Tabs * Synchronize All Panes in Current Tab `CTRL-ALT-I` * Stop Synchronizing Any Panes `CTRL-ALT-I` When inputs are synchronized, you can start typing in one input editor and that same input will be entered into all of the input editors for all panes in your current tab or all tabs, depending on the scope you selected. If you are working in an alternative editor mode (like vim), synchronized inputs will only apply to all tabs with that same editor type running. When you get done, you can select “Stop Synchronizing Any Panes” to end the synchronization. ## How it works [Section titled “How it works”](#how-it-works) # YAML Workflows > Workflows are an easier way to execute and share commands within Warp. Danger You can continue to use YAML-based workflows, but we recommend using new [workflows in Warp Drive](/knowledge-and-collaboration/warp-drive/workflows/) instead for a better editing experience. ## What is it [Section titled “What is it”](#what-is-it) Workflows are easily parameterized and searchable by name, description, or command arguments. [Common Workflows](https://github.com/warpdotdev/workflows) sourced by the Warp team and community are readily available within the app. Additionally, you can create and scope Workflows locally or to a Git repository. ## How to use it [Section titled “How to use it”](#how-to-use-it) * Open the [Command Search](/terminal/entry/command-search/) or Workflow Search `CTRL-SHIFT-R` panel to find Workflows. * Once inside the menu, start typing in the search bar to filter the existing Workflows. (e.g. git, android, npm, etc.) * When a Workflow is selected with `ENTER`, you can use `SHIFT-TAB` to cycle through the arguments. * You can also expand the menu horizontally with the mouse by dragging it on the right edge. Note Tailor your [Command Search](/terminal/entry/command-search/) experience by toggling off “Show Global Workflows” in **Settings** > **Features** > **Workflows**. When disabled, your search will exclusively encompass YAML and Warp Drive Workflows. ## How it works [Section titled “How it works”](#how-it-works) [![](/assets/terminal/yaml_workflows_demo.poster.jpg)](/assets/terminal/yaml_workflows_demo.mp4) ### How is this different from aliases? [Section titled “How is this different from aliases?”](#how-is-this-different-from-aliases) Workflows solve some major pain points with aliases, specifically the: 1. need to context switch 1. leave vim, source dotfiles, or reset shell 2. difficulty with attaching documentation 3. inability to easily search or share 4. inability to easily parameterize ## Creating custom workflows [Section titled “Creating custom workflows”](#creating-custom-workflows) ### How to create a workflow with YAML [Section titled “How to create a workflow with YAML”](#how-to-create-a-workflow-with-yaml) You can store local workflows (scoped to your machine) in: * macOS ```bash $HOME/.warp/workflows/ ``` * Windows ```powershell $env:APPDATA\warp\Warp\data\workflows\ ``` * Linux ```bash ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/workflows/ ``` Or, you can share them with your team by saving them in `{{path_to_git_repo}}/.warp/workflows/`. Local and repository Workflows can be accessed under the “My Workflows” and “Repository Workflows” tab of the Workflows menu, respectively. See the existing Workflow spec within the [Workflows repo](https://github.com/warpdotdev/Workflows/tree/main/specs) for examples. Additionally, we outline the file format below: [Workflow File Format](https://github.com/warpdotdev/Workflows/blob/main/FORMAT.md) The Workflow file format is a [yaml](https://yaml.org/) file and must have either a \`.yml \` or \`yaml\` extension. If you’re new to YAML and want to learn more, see [Learn YAML in Y minutes](https://learnxinyminutes.com/docs/yaml/). *** **`name`** The name of the Workflow. Required. **`command`** The command that is executed when the Workflow is selected. Required. **`tags`** An array of tags that are useful to categorize the Workflow. Optional. ```yaml tags: ["git", "GitHub"] ``` **`description`** The description of the Workflow and what it does. Optional. **`source_url`** The URL from where the Workflow was originally generated from. This is surfaced in [commands.dev](https://www.commands.dev/) for attribution purposes. Optional. **`author`** The original author of the Workflow. For example, if this Workflow was generated from StackOverflow, the `author` would be the `author` of the StackOverflow post. This is surfaced in [commands.dev](https://www.commands.dev/) for attribution purposes. Optional. **`author_url`** The URL of original author of the Workflow. For example, if this Workflow was generated from StackOverflow, the `author_url` would be the StackOverflow author’s profile page. This is surfaced in [commands.dev](https://www.commands.dev/) for attribution purposes. Optional. **`shells`** The list of shells where this Workflow is valid. If not specified, the Workflow is assumed to be valid in all shells. This must be one of `zsh`, `bash`, or `fish`. **`arguments`** A Workflow can have parameterized arguments to specify pieces of the Workflow that need to be filled in by the user. You can specify which part of the Workflow command maps to an argument by surrounding it with two curly braces (`{{}}`). For example the Workflow command: ```bash for {{variable}} in {{sequence}}; do {{command}} done ``` Includes 3 arguments: `variable`, `sequence`, and `command`. **`arguments.name`** The name of the argument. The argument name is used within the command to specify the ranges of the argument. Required. ```yaml name: Example Workflow command: echo {{string}} arguments: - name: string description: The value to echo ``` **`arguments.description`** The description of the argument. This is surfaced in both [commands.dev](https://www.commands.dev/) and Warp to help users fill in Workflow arguments. Optional **`arguments.default_value`** The default value for the argument. If specified, the `default_value` replaces the argument name within the command. Optional *** ### Where to save workflows [Section titled “Where to save workflows”](#where-to-save-workflows) Local Workflows are scoped to your machine. Repository Workflows are scoped to a Git repository and can be accessed by anyone who has cloned the repo. * macOS ```bash # Local Workflow Path $HOME/.warp/workflows/ # Repository Workflow Path {{path_to_git_repo}}/.warp/workflows ``` * Windows ```powershell # Local Workflow Path $env:APPDATA\warp\Warp\data\workflows\ # Repository Workflow Path {{path_to_git_repo}}\.warp\workflows ``` * Linux ```bash # Local Workflow Path ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/workflows/ # Repository Workflow Path {{path_to_git_repo}}/.warp/workflows ``` #### Local Workflows [Section titled “Local Workflows”](#local-workflows) To start, create a Workflow subdirectory within * macOS ```bash mkdir -p $HOME/.warp/workflows/ ``` * Windows ```powershell New-Item -Path "$env:APPDATA\warp\Warp\data\workflows\" -ItemType Directory ``` * Linux ```bash mkdir -p ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/workflows/ ``` Add your Workflow’s `.yaml` file to this directory; if the file format is valid Warp should automatically load it into the Workflows menu. `cp ~/path/to/my_awesome_workflow.yaml {{path_to_local_workflow_folder}}` #### Repository Workflows [Section titled “Repository Workflows”](#repository-workflows) You can add a repository Workflow similarly to how you added a local Workflow. Create a Workflows folder in a repository’s root directory and save your `.yaml` file like so: ```plaintext cd {{repository_path}} mkdir -p .warp/workflows/ cp ~/path/to/my_awesome_workflow.yaml {{path_to_local_workflow_folder}} ``` #### Global Workflows [Section titled “Global Workflows”](#global-workflows) You can contribute Workflows that will be made available to other Warp users by forking the [Workflows repo](https://github.com/warpdotdev/workflows/tree/main/specs) and opening a pull request. See the [Contributing](https://github.com/warpdotdev/workflows#contributing) section for more details. # Classic Input > Classic Input lets you use Warp with an editor that resembles a traditional terminal, offering full terminal features and Agent Mode support out of the box. Classic Input corresponds to the **Shell (PS1)** option under **Settings** > **Appearance** > **Input**. It provides a traditional terminal experience with support for shell customizations like PS1 prompts, oh-my-zsh themes, same-line prompts, and more. Warp’s default input uses [Terminal and Agent modes](/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes/), which provide a clean terminal by default and a dedicated conversation view for agent interactions. Classic Input is an alternative for users who prefer a more traditional terminal. [Agent Mode](/agent-platform/local-agents/interacting-with-agents/) works in Classic Input with some minor differences from the default input. ## Features [Section titled “Features”](#features) Classic Input supports all of Warp’s core terminal features, including the following and more: * [Prompt](/terminal/appearance/prompt/) — Use a fully customizable Warp prompt or your shell prompt, with support for PS1 and same-line prompts. * [Input Position](/terminal/appearance/input-position/) — Choose where the input appears in Warp, including both the prompt and the command line. * [Modern Text Editing](/terminal/editor/) — Warp’s input editor works like a modern IDE, with rich editing capabilities not found in most terminals. * [Command Entry](/terminal/entry/) — Access Warp’s features for command history, synchronized inputs, YAML workflows, and more. * [Text Selection](/terminal/more-features/text-selection/) — Use smart selection or rectangular (column) selection to highlight text precisely without tedious cleanup. ## How to enter Agent Mode [Section titled “How to enter Agent Mode”](#how-to-enter-agent-mode) You can enter Agent Mode in a few ways: * macOS * Type any natural language, like a task or a question, in the terminal input. Warp will recognize natural language with a local auto-detection feature and prepare to send your query to an Oz agent. * Use the keyboard shortcut `⌘+I` to toggle into Agent Mode, or type `*+Space`. * Click the “AI” sparkles icon in the menu bar, and this will open a new terminal pane that starts in Agent Mode. * From a block you want to ask an Oz agent about, you can click the sparkles icon in the toolbelt, or click on its block context menu item “Attach block(s) to AI query”. * Windows * Type any natural language, like a task or a question, in the terminal input. Warp will recognize natural language with a local auto-detection feature and prepare to send your query to an Oz agent. * Use the keyboard shortcut `Ctrl+I` to toggle into Agent Mode, or type `*+Space`. * Click the “AI” sparkles icon in the menu bar, and this will open a new terminal pane that starts in Agent Mode. * From a block you want to ask an Oz agent about, you can click the sparkles icon in the toolbelt, or click on its block context menu item “Attach block(s) to AI query”. * Linux * Type any natural language, like a task or a question, in the terminal input. Warp will recognize natural language with a local auto-detection feature and prepare to send your query to an Oz agent. * Use the keyboard shortcut `Ctrl+I` to toggle into Agent Mode, or type `*+Space`. * Click the “AI” sparkles icon in the menu bar, and this will open a new terminal pane that starts in Agent Mode. * From a block you want to ask an Oz agent about, you can click the sparkles icon in the toolbelt, or click on its block context menu item “Attach block(s) to AI query”. This opens an agent conversation where you can write questions and tasks in an ongoing conversation with Warp’s agent. When you are in Agent Mode, a ✨ sparkles icon will display in line with your terminal input. ![The sparkles on the command line indicate Agent Mode is active.](/_astro/undo_my_git_commit.vvAGQRUY_Z2olnOY.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Agent Mode active indicator in Classic Input. ## Auto-detection for natural language and configurable settings [Section titled “Auto-detection for natural language and configurable settings”](#auto-detection-for-natural-language-and-configurable-settings) The feature Warp uses to detect natural language automatically is completely local. None of your input is sent to AI unless you press `Enter` in Agent Mode. If you find that certain shell commands are falsely detected as natural language, you can fix the model by adding those commands to a denylist in **Settings** > **Agents** > **Warp Agent** > **Natural language denylist**. You can also turn autodetection off from **Settings** > **Agents** > **Warp Agent** > **Autodetect agent prompts in terminal input**. The first time you enter Agent Mode, you will be served a banner with the option to disable auto-detection for natural language on your command line: ![Warp displays an option to toggle natural language detection on / off](/_astro/banner_for_auto-detection_first_experience.0XzEtt_S_Z20rkvO.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Natural language detection toggle. ## Input hints [Section titled “Input hints”](#input-hints) Warp input occasionally shows hints within the input editor in a light grey text that helps users learn about features. It’s enabled by default. * Toggle this feature **Settings** > **Agents** > **Warp Agent** > **Show input hint text** or search for “Input hint text” in the [Command Palette](/terminal/command-palette/) or Right-click on the input editor. ## How to exit Agent Mode [Section titled “How to exit Agent Mode”](#how-to-exit-agent-mode) * macOS You can quit Agent Mode at any point with `Esc` or `Ctrl+C`, or toggle out of Agent Mode with `⌘+I`. * Windows You can quit Agent Mode at any point with `Esc` or `Ctrl+C`, or toggle out of Agent Mode with `Ctrl+I`. * Linux You can quit Agent Mode at any point with `Esc` or `Ctrl+C`, or toggle out of Agent Mode with `Ctrl+I`. ## How to run commands in Agent Mode [Section titled “How to run commands in Agent Mode”](#how-to-run-commands-in-agent-mode) Once you have typed your question or task in the input, press `Enter` to execute your AI query. Agent Mode will send your request to Oz and begin streaming output in the form of an AI block. Unlike a chat panel, Agent Mode can complete tasks for you by running commands directly in your session. #### Agent Mode command suggestions [Section titled “Agent Mode command suggestions”](#agent-mode-command-suggestions) If Agent Mode finds a suitable command that will accomplish your task, it will describe the command in the AI block. It will also fill your terminal input with the suggested command so you can press `Enter` to run the command. When you run a command suggested by Agent Mode, that command will work like a standard command you’ve written in the terminal. No data will be sent back to the AI. If the suggested command fails and you want to resolve the error, you can start a new AI query to address the problem. ![Agent Mode makes a suggestion to run a command.](/_astro/agent-mode-suggestion-1.CQ2ApVmL_Zl7uM1.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### Agent Mode requested commands [Section titled “Agent Mode requested commands”](#agent-mode-requested-commands) If Agent Mode doesn’t have enough context to assist with a task, it will ask permission to run a command and read the output of that command. You must explicitly agree and press `Enter` to run the requested command. When you hit enter, both the command input and the output will be sent to Oz. If you do not wish to send the command or its output to AI, you can click Cancel or press `Ctrl+C` to exit Agent Mode and return to the traditional command line. ![Oz asks permission to run a command and read the output.](/_astro/warp-ai-permissions.COh_yOkN_2syGFW.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Agent command approval prompt. Once a requested command is executed, you can click to expand the output and view command details. ![Viewing command details](/_astro/warp-ai-viewing-commands.B2v_8NWk_Z1chqX3.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Viewing command details. If a requested command fails, Oz detects it. Agent Mode is self-correcting. It will request another command until it completes the task for you. Warp lets you choose from a curated list of LLMs for use in Agent Mode. By default, Warp uses **Auto (Responsive)**, which routes to the highest-quality, fastest available model. You can switch to other supported models — see [Model choice](/agent-platform/capabilities/model-choice/) for the full list. # Universal Input (Legacy) > Universal Input was the previous default input interface for Warp, replaced by Terminal and Agent modes. Caution **This is legacy documentation.** Universal Input has been replaced by [Agent Modality](/agent-platform/local-agents/interacting-with-agents/terminal-and-agent-modes/), which provides a cleaner terminal experience with a dedicated conversation view for agent interactions. The **Universal Input** was the main input interface for using Warp. ![The Universal Input with an Agent prompt and multiple contextual chips active.](/_astro/universal-input-header.BCP1j4eH_dgmPa.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Universal Input with contextual chips. ![Using the Universal Input](https://i.ytimg.com/vi/4c05OEqzQIA/sddefault.jpg) ### Breaking down the Universal Input [Section titled “Breaking down the Universal Input”](#breaking-down-the-universal-input) The Universal Input brings together all of Warp’s input features into one streamlined editor: * **Natural language auto-detection**: Warp can automatically detect when you’re writing in plain English, as opposed to a shell command, and switch you into [Agent Mode](/agent-platform/local-agents/interacting-with-agents/#what-is-agent-mode). * **Contextual chips**: See your current directory, previous conversations, Git status, node version, and more, all inline with your input. * [**Modern text editing**](/terminal/editor/): Enjoy IDE-like editing features such as [completions](/terminal/command-completions/), [syntax highlighting](/terminal/editor/syntax-error-highlighting/), mouse support, [rectangular selection](/terminal/more-features/text-selection/), and [Next Command](/agent-platform/local-agents/active-ai/) predictions. * **Input toolbelt**: Quickly access [@-context](/agent-platform/local-agents/agent-context/using-to-add-context/), [Slash Commands](/agent-platform/capabilities/slash-commands/), [voice input](/agent-platform/local-agents/interacting-with-agents/voice/), [image attachments](/agent-platform/local-agents/agent-context/images-as-context/) as context, and other AI features. If you prefer a more traditional terminal input experience, you can switch to [Classic Input](/terminal/input/classic-input/) in **Settings** > **Appearance** > **Input**. Classic input also supports oh-my-posh, PS1 customizations, and [same line prompt.](/terminal/appearance/prompt/#same-line-prompt) ## Input Modes [Section titled “Input Modes”](#input-modes) The Universal Input supports three modes, shown in the input switcher: #### 1. Agent Mode (natural language) [Section titled “1. Agent Mode (natural language)”](#1-agent-mode-natural-language) Ask Warp’s agent to build, debug, or run tasks in natural language. Warp uses leading LLMs to interpret your request, run the right commands, surface code diffs, and stream results directly into your session. *Indicator:* Agent icon is highlighted in the switcher. ![Universal Input locked in Agent Mode.](/_astro/agent-mode-locked-universal-input.D884HvO0_ZFkPuH.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Universal Input locked in Agent Mode. #### 2. Terminal Mode (shell commands) [Section titled “2. Terminal Mode (shell commands)”](#2-terminal-mode-shell-commands) Enter shell commands just like any terminal, with the benefit of Warp’s modern editor features—completions, syntax highlighting, error underlining, and more included. *Indicator*: Terminal icon highlighted in the switcher ![Universal Input locked in Terminal Mode.](/_astro/universal-input-terminal-mode.JOIRSu6h_ZlyL2W.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Universal Input locked in Terminal Mode. #### 3. Auto-detection Mode [Section titled “3. Auto-detection Mode”](#3-auto-detection-mode) Warp automatically detects whether your input is natural language or a shell command. You can stay in detection mode or explicitly lock into Terminal or Agent Mode. *Indicator*: Neither mode highlighted. ![Universal Input in an empty / zero state.](/_astro/zero-state-universal-input.8nBe0_zv_cK4P5.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Universal Input in an empty / zero state. When Warp detects an input type, the input switcher softly highlights the corresponding mode. | Agent (natural language) mode detected | Terminal (shell) mode detected | | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | ![Universal Input auto-detecting a natural-language Agent prompt.](../../../../assets/terminal/auto-detection-agent-mode-1.png) | ![Universal Input auto-detecting a shell command.](../../../../assets/terminal/auto-detection-terminal-mode.png) | Note The model Warp uses to detect natural language automatically is completely local. #### Disabling Natural Language Auto-detection [Section titled “Disabling Natural Language Auto-detection”](#disabling-natural-language-auto-detection) By default, auto-detection is enabled. This means Warp decides whether to treat your input as a command or an Agent prompt. * **To turn off auto-detection**: go to **Settings** > **AI** > **Input** > **Natural Language Detection** * When disabled: You’ll explicitly be in either Terminal or Agent Mode. Use the following keyboard shortcuts to switch between modes: * `CMD+I` (macOS) * `CTRL+I` (Windows/Linux) | Agent (natural language) mode enabled | Terminal (shell) mode enabled | | --------------------------------------------------------------------- | ------------------------------------------------------------------ | | ![](../../../../assets/terminal/auto-detection-off-terminal-mode.png) | ![](../../../../assets/terminal/auto-detection-off-agent-mode.png) | ### Entering Agent Mode [Section titled “Entering Agent Mode”](#entering-agent-mode) [Agent Mode](/agent-platform/local-agents/interacting-with-agents/) is how you interact directly with Warp’s AI to ask questions, run tasks, and collaborate in natural language. There are multiple ways to enter Agent Mode depending on where you are in your workflow: * macOS * **Type natural language directly**: If auto-detection is enabled, you can type a task or question into the input, and Warp will recognize it as natural language using its local auto-detection feature. * **Use keyboard shortcuts**: Quickly toggle into Agent Mode with `CMD + I`. * **Attach blocks to a prompt**: From any block you want to use as context, click the ✨ icon in the toolbelt or select “Attach block(s)” to AI query from the block’s context menu. * **Force a mode with special characters**: * `!` at the start of input forces Terminal Mode. * `*` at the start of input forces Agent Mode. * **Switch modes manually**: Click the Agent icon in the input switcher to lock into Agent Mode, or click the terminal icon to switch to Terminal Mode. * Windows * **Type natural language directly**: If auto-detection is enabled, you can type a task or question into the input, and Warp will recognize it as natural language using its local auto-detection feature. * **Use keyboard shortcuts**: Quickly toggle into Agent Mode with `CTRL + I`. * **Attach blocks to a prompt**: From any block you want to use as context, click the ✨ icon in the toolbelt or select “Attach block(s)” to AI query from the block’s context menu. * **Force a mode with special characters**: * `!` at the start of input forces Terminal Mode. * `*` at the start of input forces Agent Mode. * **Switch modes manually**: Click the Agent icon in the input switcher to lock into Agent Mode, or click the terminal icon to switch to Terminal Mode. * Linux * **Type natural language directly**: If auto-detection is enabled, you can type a task or question into the input, and Warp will recognize it as natural language using its local auto-detection feature. * **Use keyboard shortcuts**: Quickly toggle into Agent Mode with `CTRL + I`. * **Attach blocks to a prompt**: From any block you want to use as context, click the ✨ icon in the toolbelt or select “Attach block(s)” to AI query from the block’s context menu. * **Force a mode with special characters**: * `!` at the start of input forces Terminal Mode. * `*` at the start of input forces Agent Mode. * **Switch modes manually**: Click the Agent icon in the input switcher to lock into Agent Mode, or click the terminal icon to switch to Terminal Mode. When you’re in Agent Mode, the **Agent icon** will be highlighted in the \[Universal Input(/terminal/input/universal-input/) ![The Agent icon in the Universal input indicates that Agent Mode is active.](/_astro/using-agents-universal-input.DYJhxQXS_UKpBq.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Agent Mode indicator in Universal Input. In Classic Input, you’ll also see a ✨ sparkles indicator inline. ![The sparkles on the command line indicate Agent Mode is active.](/_astro/undo_my_git_commit.vvAGQRUY_Z2olnOY.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Agent Mode active indicator in Classic Input. By default, entering Agent Mode starts you in *Pair Mode*, where you can continue an ongoing conversation by asking follow-up questions or assigning tasks. From here, you can ask the agent to build, debug, fix, or even deploy code as needed. ### Exiting Agent or Terminal Modes [Section titled “Exiting Agent or Terminal Modes”](#exiting-agent-or-terminal-modes) You can leave Agent or Terminal Modes in several ways: * macOS * **Keyboard shortcuts** * Press `ESC` to quit the current mode. * Toggle modes with `CMD + I` * **Force modes with special characters** * `!` at the start of input forces Terminal Mode. * `*` at the start of input forces Agent Mode. * **Manual switching**: click the Agent icon or Terminal icon in the input switcher to swap modes directly. * Windows * **Keyboard shortcuts** * Press `ESC` to quit the current mode. * Toggle modes with `CTRL + I` * **Force modes with special characters** * `!` at the start of input forces Terminal Mode. * `*` at the start of input forces Agent Mode. * **Manual switching**: click the Agent icon or Terminal icon in the input switcher to swap modes directly. * Linux * **Keyboard shortcuts** * Press `ESC` to quit the current mode. * Toggle modes with `CTRL + I` * **Force modes with special characters** * `!` at the start of input forces Terminal Mode. * `*` at the start of input forces Agent Mode. * **Manual switching**: click the Agent icon or Terminal icon in the input switcher to swap modes directly. ### Natural Language Auto-detection Settings [Section titled “Natural Language Auto-detection Settings”](#natural-language-auto-detection-settings) Warp can automatically detect when you’re writing in plain English and switch you into Agent Mode. If needed, you can customize or disable this behavior. #### Fixing false detections [Section titled “Fixing false detections”](#fixing-false-detections) If certain shell commands are mistakenly detected as natural language, you can add them to the denylist: **Settings** > **AI** > **Input** > **Natural language denylist** #### Turning off auto-detection [Section titled “Turning off auto-detection”](#turning-off-auto-detection) To disable natural language detection entirely, go to: **Settings** > **AI** > **Input Auto-detection** When auto-detection is turned off, you’ll need to explicitly switch between Terminal Mode and Agent Mode using `CMD + I` (macOS) or `CTRL + I` (Windows/Linux). #### First-time setup [Section titled “First-time setup”](#first-time-setup) The first time you enter Agent Mode, Warp will display a banner with the option to disable natural language detection for your command line: ![Warp displays an option to toggle natural language detection on / off](/_astro/banner_for_auto-detection_first_experience.0XzEtt_S_Z20rkvO.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Natural language detection toggle. *** ## Contextual Input Chips [Section titled “Contextual Input Chips”](#contextual-input-chips) ![Universal Input's contextual input chips, from left to right: conversation management, node version, active directory, Git and code diffs, and 2 attached images.](/_astro/universal-input.DMHMEhK9_ZIKfwh.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Universal Input contextual chips. The Universal Input includes **contextual chips** that provide inline information about your current environment. These chips surface relevant details such as directory paths, Git status, conversations, or runtime versions, making it easier to navigate, manage context, and take quick actions without leaving the input. #### Conversation Management chip [Section titled “Conversation Management chip”](#conversation-management-chip) The conversation management chip shows your recent [Agent conversations](/agent-platform/local-agents/interacting-with-agents/), allowing you to reference or reopen them directly. These chips appear in both Agent Mode and Terminal Mode, so you can continue a previous conversation without starting from scratch. For more details, see [Agent Conversations](/agent-platform/local-agents/interacting-with-agents/). ![The Conversation Management chip displays recent Agent conversations and lets you continue or reopen them directly from the input.](/_astro/conversation-management-chip-universal-input.BUKfnIWW_BDfzb.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Conversation Management chip. These chips appear in both Agent Mode and Terminal Mode, helping you continue a previous conversation without starting from scratch. For more details, refer to [Agent Conversations](/agent-platform/local-agents/interacting-with-agents/). #### Active directory chip [Section titled “Active directory chip”](#active-directory-chip) The active directory chip displays your current working directory and enables simple file navigation. Clicking on a folder moves you into that folder, while clicking on a file opens it in [Warp’s native code editor](/code/code-editor/). This makes it possible to move around your workspace seamlessly from within the input. ![The Active Directory chip lets you browse directories and open files directly from the input.](/_astro/active-directory-chip.j1olYA7B_Z1onumr.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Active Directory chip. #### Git Status chip [Section titled “Git Status chip”](#git-status-chip) When you’re in a Git-tracked repository, the Git Status chip displays file- and line-level changes. You can switch branches by clicking on the branch name or review modified files in Warp’s [native Code Review panel](/code/code-review/). The chip updates automatically as files are added, removed, or changed, giving you a real-time view of your repository state. ![The Git Status chip highlights repository changes and provides quick access to code review.](/_astro/git-branch-chip.CESiew0h_1njP2h.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Git Status chip. #### File attachments chips [Section titled “File attachments chips”](#file-attachments-chips) The file attachments chip lets you attach images and other files directly to a prompt. You can upload up to five [images at a time (as Agent Context)](/agent-platform/local-agents/agent-context/images-as-context/) using the upload button in the toolbelt or by dragging and dropping files into the input. This makes it possible to add screenshots, diagrams, PDFs, or other references directly to your query, giving the Agent richer context. ![The File Attachments chip allows you to add images or files as context for your queries.](/_astro/images-as-context-chip.Ctv1nf9b_Z1qJM0E.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The File Attachments chip. **Node version chip** In repositories that include a `package.json`, a Node Version chip appears to show the detected Node.js version. This gives you visibility into your runtime environment without needing to run additional commands. ![The Node Version chip displays the Node.js version detected in your repository.](/_astro/node-version-chip.BbDaGoXu_Z1VPkKG.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Node Version chip. Note At this time, contextual chips are not configurable, but they update automatically based on your workspace and repository state. *** ## Input toolbelt [Section titled “Input toolbelt”](#input-toolbelt) The **Input Toolbelt** provides quick-access controls alongside the Universal Input. These tools allow you to attach context, run shortcuts, and configure Agent behavior without leaving the input field. Depending on the mode you are in, some features are automatically enabled or will place you into Agent Mode. ![The Input Toolbelt in Warp’s Universal Input, showing quick-access controls for context, slash commands, voice input, attachments, profiles, and model selection.](/_astro/input-toolbar.nIryinvl_1DvFQW.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The Input Toolbelt in Universal Input. #### @ - Context [Section titled “@ - Context”](#---context) The [@ context chip](/agent-platform/local-agents/agent-context/using-to-add-context/) is available when you are working in a Git repository. Outside of a Git repo, it appears dimmed. This feature allows you to attach specific files, folders, code symbols, Warp Drive objects, or blocks from other sessions as context for a prompt. Typing **@** inside the input also opens a context menu where you can search for and select files or directories to include. Attaching context with @ works in both Agent Mode (when interacting with Agents) and classic Terminal commands (for referencing file paths). **Slash Commands** [Slash Commands](/agent-platform/capabilities/slash-commands/) are available in Agent Mode and Auto-detection Modes. They allow you to quickly run built-in actions or saved prompts without leaving the input field. Typing / displays a menu of available commands, which can be customized or extended. **Voice Input** [Voice Input](/agent-platform/local-agents/interacting-with-agents/voice/) automatically places you in Agent Mode. Speaking directly into Warp lets you phrase tasks, commands, or queries in natural language, and Warp will interpret them as if you had typed them. This feature is especially useful when you want hands-free interaction or when dictating longer tasks. **Image Attachments** You can [attach images as context](/agent-platform/local-agents/agent-context/images-as-context/) directly to a prompt, which will automatically place you in Agent Mode. This is useful when you want the Agent to reference visual materials such as screenshots, diagrams, or other assets. You can add images using the image upload button in the toolbelt (located at the bottom left or right, depending on your input layout). For additional methods of attaching images, see [Images as Context](/agent-platform/local-agents/agent-context/images-as-context/). **Fast Forward** Fast Forward gives the Agent full autonomy for the remainder of a task or conversation. When enabled, the next prompt you enter allows the Agent to execute commands, read files, and apply code diffs without asking for confirmation each time. This is useful for complex workflows where step-by-step approval would slow things down. #### Profile Picker [Section titled “Profile Picker”](#profile-picker) The Profile Picker allows you to select from different [Agent Profiles](/agent-platform/capabilities/agent-profiles-permissions/), each with its own configuration of autonomy, tools, and default model. If you have only one profile, the picker will not appear in the UI. From the Profile Picker, you can view all available profiles, switch between them, and quickly see the default model attached to each one. Profiles make it possible to tailor Agent behavior for different types of tasks or projects. ### Model Picker [Section titled “Model Picker”](#model-picker) The Model Picker is tied to your current Agent Profile. Each profile has a default model, but you can override it at any time using the picker. Warp curates a selection of top large language models (LLMs) for you to choose from, balancing speed, quality, and reasoning ability depending on your needs. For a full list of supported models and guidance on when to use them, see [Model Choice](/agent-platform/capabilities/model-choice/). # Terminal Integrations > Warp's terminal functionality extends and integrates with popular development tools. ## Docker [Section titled “Docker”](#docker) Note Currently, the Docker extension is only available on macOS. [Warp’s Docker extension](https://hub.docker.com/extensions/warpdotdev/warp) makes it more convenient to open Docker containers in Warp. With the extension, you can click to open any Docker container in a [Warpified subshell](/terminal/warpify/subshells/), without manually running `docker exec` or typing out lengthy container IDs. Select a container from the list and specify a shell type. Note, that only `bash|zsh|fish` are supported shells for docker containers. Then, select a user (optional) and finally click “Open in Warp” to run commands within the Docker container. ![Warp's extension for Docker lists available containers](/_astro/docker-extension.Bx8kznDs_1FTcqg.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Warp’s extension for Docker lists available containers. ## Raycast [Section titled “Raycast”](#raycast) Note Currently, the Raycast extension is only available on macOS. Warp + Raycast extension helps you open new windows, tabs, or Launch Configurations with [ease](https://twitter.com/warpdotdev/status/1678432353461637121). [Warp + Raycast Extension Link](https://www.raycast.com/warpdotdev/warp) Note **Terminal Tip**\ Within `Raycast Settings > Extensions > Apps` search for Warp and assign the alias “terminal” so that it will show up on a search. ![Raycast Terminal Tip](/_astro/raycast-terminal-tip.D_lrDAdd_dct0h.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Warp integration with the Raycast launcher. ## VSCode [Section titled “VSCode”](#vscode) * macOS Press `SHIFT-CMD-C` while in [VSCode](https://code.visualstudio.com/docs/terminal/basics) to open a new session in Warp. [![](/assets/terminal/vscode_new_session.poster.jpg)](/assets/terminal/vscode_new_session.mp4) To configure this, navigate to Settings in VSCode and search for `Terminal › External: Osx Exec`.\ \ Change this to `Warp.app` if you’ve installed Warp in the default location. Otherwise, put in the full path to the executable. * Windows Press `CTRL-SHIFT-C` while in [VSCode](https://code.visualstudio.com/docs/terminal/basics) to open a new session in Warp. To configure this, navigate to Settings in VSCode and search for `Terminal › External: Windows Exec`.\ \ Change this to `%LOCALAPPDATA%\Programs\Warp\warp.exe` if you’ve installed Warp in the default location for a single user or `%PROGRAMFILES%\Warp\warp.exe` if you’ve installed Warp in the default location for all users. Otherwise, put in the full path to the executable. * Linux Press `CTRL-SHIFT-C` while in [VSCode](https://code.visualstudio.com/docs/terminal/basics) to open a new session in Warp. To configure this, navigate to Settings in VSCode and search for `Terminal › External: Linux Exec`.\ \ Change this to `warp-terminal` if you’ve installed Warp with your distribution’s package manager. Otherwise, put in the full path to the executable (e.g. if it is an AppImage). ## JetBrains IDEs [Section titled “JetBrains IDEs”](#jetbrains-ides) Note Currently, the JetBrains IDE configuration is only available on macOS. Press a keyboard shortcut of choice while in a JetBrains IDE to open a new session in Warp. To configure this, use the Apple Menu. Click on **Preferences**, go to `External Tools` , and click **Add**. In this menu, put the following information: * *Name*: Open Warp * *Program*: `/Applications/Warp.app` * *Arguments*: `$ProjectFileDir$` * *Working Directory*: `/Applications` Then press `Ok`. Now you will be able to `Open Warp` from the Apple Menu under `Tools` -> `External Tools`. [![](/assets/terminal/jetbrains_external_terminal_config.poster.jpg)](/assets/terminal/jetbrains_external_terminal_config.mp4) To attach this configuration to a keyboard shortcut, you must go to the Apple Menu -> `Preferences`. Then go to `Keymap` -> `External Tools`. You will find `Open Warp`. Right-click on it, and select **Add Keyboard Shortcut**. Type your desired shortcut and click save! You’re ready to open Warp with a keyboard shortcut. [![](/assets/terminal/jetbrains_external_window_keymap_config.poster.jpg)](/assets/terminal/jetbrains_external_window_keymap_config.mp4) # More features overview > Explore additional Warp terminal features beyond the essentials. # Accessibility > Warp's accessibility features include VoiceOver support, voice input, and configurable verbosity. Note Note that currently, these instructions are for macOS only. Warp doesn’t support screen readers on Linux or Windows and it’s being tracked here: We recognize the need to improve the experience for those visually impaired, as - to our best knowledge - other terminal emulator apps didn’t do a good job in this area. This doc summarizes what we’ve done so far, how Warp works with VoiceOver, and outlines the main changes from the typical workflow. For the features documentation and its keyboard shortcuts, please go to the feature-specific page in the documentation. **Keep in mind that this is a work-in-progress and the current state is not a final state of accessibility in Warp**. ## How to use Warp with Voice Over? [Section titled “How to use Warp with Voice Over?”](#how-to-use-warp-with-voice-over) The best way to start working with Warp & VoiceOver is to install it using Homebrew: `brew install warp` This will ensure that you can receive all future updates automatically, without the need to go through a macOS standard drag-and-drop installation process. From there, Warp should seamlessly work with VoiceOver and start announcing what’s happening on the screen and what actions you can take. This may be a major difference from other apps - as Warp announces stuff on its own, letting you know what’s going on. There’s currently no way to navigate between different UI elements using VO key combinations. Once installed, it will ask you to log in. Warp also sends telemetry that we use to improve the overall user experience. You can find out more about that in the [privacy section](/support-and-community/privacy-and-security/privacy/). The login flow will require you to navigate between the app and your browser. The last step before you can start enjoying our new terminal app is filling up the onboarding survey. The main terminal window is not that different from other terminals - there’s a place to type commands (Command Input) and a list of the previously executed commands and their outputs. Warp groups those together - each command and output create a Block. You can navigate blocks with your keyboard to easily check what was the command, learn whether it was successful or not, and what was the output, as well as more easily copy the command, output, or both for further processing. A main entry point for discovering new features and actions is our Command Palette, which you can access by executing the cmd-p shortcut. ## Differences from the regular VoiceOver workflow [Section titled “Differences from the regular VoiceOver workflow”](#differences-from-the-regular-voiceover-workflow) As you may notice, typical Voice Over navigation keys or settings do not currently work in Warp. In short - it’s related to how our UI Framework is currently implemented and that as of now we don’t yet offer a keyboard-accessible way to navigate the UI elements. Instead, whenever you perform an action and/or something happens in the background, Warp announces it to you, letting you know what’s going on and what possible actions you can take. Since it’s a terminal, we care about all user actions being keyboard accessible from the start, so pretty much all our features have the assigned keybindings already. You can adjust the default keybindings following the guide from this GitHub repository: . You can also always fall back to using cmd-p to check the keybinding or execute the specific action. ### A11y specific actions [Section titled “A11y specific actions”](#a11y-specific-actions) Some a11y-specific settings are available through the Command Palette. For example, you can adjust the verbosity level of messages. Simply enter the [Command Palette](/terminal/command-palette/) and type “a11y” to discover related options and their keybindings. ### Voice Input [Section titled “Voice Input”](#voice-input) Warp supports voice input as an alternative way to interact with your terminal. This can be especially helpful for users who prefer or require voice commands over typing. You can use voice input to: * Issue terminal commands * Ask questions about command usage * Perform complex multi-step operations Voice input can be enabled in **Settings** > **Agents** > **Warp Agent** > **Voice**. For detailed information about voice features and setup, see our [Voice documentation](/agent-platform/local-agents/interacting-with-agents/voice/). ## Future work [Section titled “Future work”](#future-work) While not all Warp features are accessible yet, we’ve implemented a process around releasing new features and changes to the main app, to ensure that all new code provides proper a11y announcements. This is not the ideal and final implementation. We’re happy to hear your thoughts and ideas on how we can improve. The biggest milestone for this work is to add support for navigating the UI elements using the keyboard. Give Warp a try, and please, do not hesitate to [share your feedback](/support-and-community/troubleshooting-and-support/sending-us-feedback/). # Audible terminal bell > Enable an audible terminal bell in Warp that can be triggered by CLI tools like ping. Warp allows you to enable an audible terminal bell (disabled by default) that can be triggered by a variety of CLI tools (for example, `ping -a`). * In Settings, enable an Audible terminal bell in **Settings** > **Features** > **Terminal**. * In [Command Palette](/terminal/command-palette/), “Enable/Disable Audible Terminal Bell”. # Files, Links, & Scripts > Quickly open links and files or run scripts with your mouse. ## Files & Links [Section titled “Files & Links”](#files--links) Warp supports opening files, folders, and URL links that are within Blocks. Multiple URL protocols are supported e.g. `https`, `ftp`, `file`, etc. Warp can open files and folders in a variety of editors and opens web links directly in your default browser. Warp can also open markdown files directly with a [Markdown Viewer](/terminal/more-features/markdown-viewer/). Note Warp also supports iTerm2 and Kitty Image protocols on macOS and Linux. You will need to use a cli tool to view images, in some cases the tools expect `$TERM=kitty`, so you may need to workaround this by setting `TERM=kitty` before the command. We’re working on updating the popular tools to recognize Warp natively. Warp parses relative and absolute file paths. Warp also tries to capture line and column numbers attached to the file path, supported formats include: * `file_name:line_num` * `file_name:line_num:column_num` * `file_name[line_num, column_num]` * `file_name(line_num, column_num)` * `file_name, line: line_num, column: column_num` * `file_name, line: line_num, in` - macOS 1. After hovering over a link, open it directly by holding down `CMD` while clicking it. 2. Clicking a link normally will open a clickable tooltip that says “Open File/Folder/Link”. 3. Right-clicking a link will open a context menu that supports copying the absolute file path or URL to the clipboard. - Windows 1. After hovering over a link, open it directly by holding down `CTRL` while clicking it. 2. Clicking a link normally will open a clickable tooltip that says “Open File/Folder/Link”. 3. Right-clicking a link will open a context menu that supports copying the absolute file path or URL to the clipboard. - Linux 1. After hovering over a link, open it directly by holding down `CTRL` while clicking it. 2. Clicking a link normally will open a clickable tooltip that says “Open File/Folder/Link”. 3. Right-clicking a link will open a context menu that supports copying the absolute file path or URL to the clipboard. * You can also Drag and drop a folder or file onto the Warp dock icon to open a new tab in this directory. * You can also right-click on a folder or file in Finder, then select Services, and “Open new Warp Tab | Window here”. * Configure the default editor to open files by navigating to **Settings** > **Features** > **General** > **Choose an editor to open file links**. * Selecting “Default App” uses your system’s default application for the file type. #### List of supported editors [Section titled “List of supported editors”](#list-of-supported-editors) Non exhaustive list of editors, please submit new ones on our GitHub, see [Sending Feedback](/support-and-community/troubleshooting-and-support/sending-us-feedback/#sending-warp-feedback). 1. `$EDITOR` 2. Visual Studio Code 3. JetBrains IDEs * WebStorm * PhpStorm * GoLand * PyCharm * DataGrip * DataSpell * Rider * RubyMine 4. Zed and Zed Preview 5. Cursor 6. Windsurf 7. Sublime Text 8. Android Studio [![](/assets/terminal/files-links-demo.poster.jpg)](/assets/terminal/files-links-demo.mp4) ## Scripts [Section titled “Scripts”](#scripts) Warp can open `.command` and Unix Executable files from the finder directly. 1. Find a `.command` or Shell script you’d like to open in Finder. 2. Right-click and open the script with Warp. Caution Make sure the file has the appropriate executable permissions before you can run it in Warp. (e.g. `chmod +x script.command`) [![](/assets/terminal/script-demo.poster.jpg)](/assets/terminal/script-demo.mp4) # Full-screen apps > Run Vim, Emacs, and other full-screen apps with configurable mouse reporting and padding. ## Mouse and scroll reporting [Section titled “Mouse and scroll reporting”](#mouse-and-scroll-reporting) Warp supports configuring how to handle mouse and scroll events. They can be sent to the currently running app, e.g. `vim`, or kept and handled by Warp. Note Mouse reporting must be enabled to also toggle scroll reporting. Once mouse reporting is enabled, Warp will use ANSI escape sequences to communicate mouse events to the running app. Note If you want a mouse event to go to Warp instead (for example, for text selection) without disabling mouse reporting, you can hold the `SHIFT` key. ### How to access it [Section titled “How to access it”](#how-to-access-it) * From the Settings panel, **Settings** > **Features** > **Terminal** > **Enable Mouse Reporting** * Scroll Reporting can be enabled after toggling **Enable Mouse Reporting** * From the [Command Palette](/terminal/command-palette/), search for “Toggle Mouse Reporting” * From the macOS Menu, **View** > **Toggle Mouse Reporting** ### How it works [Section titled “How it works”](#how-it-works) [Mouse and Scroll Reporting Demo](https://www.loom.com/embed/a918696b002148d3beafd545b233c1be) ## Padding [Section titled “Padding”](#padding) Warp supports configuring how much padding surrounds full-screen apps. The default is 0 pixel padding, but this can be changed to a custom padding amount or to match the padding in the Blocklist. Note Warp allows you to scale your terminal by fractions of a cell width | height. When your terminal size is not perfectly aligned to a cell width | height, the extra space appears as padding on the right | bottom. ### How to access it [Section titled “How to access it”](#how-to-access-it-1) * Go to **Settings** > **Appearance** > **Full-screen Apps** or from the [Command Palette](/terminal/command-palette/) search for “Appearance” * `Use custom padding in alt-screen` is enabled by default, you can disable it to match the Blocklist padding * Set the desired uniform padding (px) pixels, which is set to 0px by default Caution Some full-screen applications don’t behave well when resizing. If you are experiencing rendering issues with full screen apps, try turning this setting off. This will ensure that full-screen apps don’t need to resize when starting up. ![alt-screen padding setting](/_astro/padding-settings.BTFzXcH0_23m6wi.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) The alt-screen padding setting in appearance preferences. # Warp for Linux > Linux-specific features including native Wayland support and crash recovery. ## Native Wayland [Section titled “Native Wayland”](#native-wayland) Warp Wayland support can be enabled in **Settings** > **Features** > **System**. Enabling Wayland support may fix issues with blurry text if you have fractional scaling enabled in your window manager. Caution When native Wayland is enabled, Global Hotkey support will be disabled. Unlike X11, the Wayland protocol does not expose the configuration necessary to support this feature. ## Wayland crash recovery [Section titled “Wayland crash recovery”](#wayland-crash-recovery) When Wayland support is enabled, Warp uses a custom crash recovery process to detect any crashes that may occur when using Wayland. If there’s a crash, Warp will fallback to use X11 to allow you to continue to use the application. # Markdown Viewer > Open Markdown files in your terminal and run commands. Warp can be used for both editing and viewing rendered Markdown files in a [split pane](/terminal/windows/split-panes/). Any local file with the `.md` or `.markdown` extension is treated as a Markdown file. Remote files are currently not supported. Turning on **Settings** > **Features** > **General** > **Open Markdown files in Warp’s Markdown viewer by default** will make the Markdown viewer default, otherwise Markdown files will open in Warp’s editor. ### Opening a file link within a block [Section titled “Opening a file link within a block”](#opening-a-file-link-within-a-block) * macOS For any link to a Markdown file within a block, you can open the file in Warp by `CMD`-clicking on the link, from the link tooltip, or the right-click context menu on the link. * Windows For any link to a Markdown file within a block, you can open the file in Warp by `CTRL`-clicking on the link, from the link tooltip, or the right-click context menu on the link. * Linux For any link to a Markdown file within a block, you can open the file in Warp by `CTRL`-clicking on the link, from the link tooltip, or the right-click context menu on the link. ![Clicking a Markdown file link in the output of ls to open it in Warp](/assets/terminal/open-markdown-viewer.gif) Opening a Markdown file via link tooltip. ### Markdown-viewing commands [Section titled “Markdown-viewing commands”](#markdown-viewing-commands) If you run a Markdown-viewing command like `cat myfile.md`, Warp will show a banner with a button to open the Markdown file. The following commands are considered Markdown viewers: * `cat` * `glow` * `less` ### Opening a Markdown file from Finder [Section titled “Opening a Markdown file from Finder”](#opening-a-markdown-file-from-finder) From Finder, you can open a Markdown file in Warp from the “Open With” menu that appears when right-clicking on the file. ### Toggling between editor and viewer [Section titled “Toggling between editor and viewer”](#toggling-between-editor-and-viewer) You can toggle between the Markdown editor and viewer via the pane overflow menu. ![Clicking a Markdown file link in the output of ls to open it in Warp](/assets/terminal/markdown-raw-rendered-toggle.gif) Toggling between editor and viewer. ## Shell commands in Markdown files [Section titled “Shell commands in Markdown files”](#shell-commands-in-markdown-files) Warp can run shell commands from Markdown code blocks in your active terminal session. Click the run icon `>_` to insert a command into the terminal input. Note The shell command must be in a code block with three backticks ` ``` ` and not inline code for Warp to treat the code like a runnable command. Markdown shell blocks also support keyboard navigation. There are two ways to enter the keyboard navigation mode: * macOS * Clicking on a shell block. * Pressing `CMD-UP` or `CMD-DOWN`. Once a shell block is selected, press `CMD-ENTER` to insert it into the terminal input. You can also use `UP`, `DOWN`, `CMD-UP`, and `CMD-DOWN` to navigate between shell blocks. While the Markdown file is focused, press `CMD-L` to switch focus back to the terminal without inserting a command. * Windows * Clicking on a shell block. * Pressing `CTRL-UP` or `CTRL-DOWN`. Once a shell block is selected, press `CTRL-ENTER` to insert it into the terminal input. You can also use `UP`, `DOWN`, `CTRL-UP`, and `CTRL-DOWN` to navigate between shell blocks. While the Markdown file is focused, press `CTRL-SHIFT-L` to switch focus back to the terminal without inserting a command. * Linux * Clicking on a shell block. * Pressing `CTRL-UP` or `CTRL-DOWN`. Once a shell block is selected, press `CTRL-ENTER` to insert it into the terminal input. You can also use `UP`, `DOWN`, `CTRL-UP`, and `CTRL-DOWN` to navigate between shell blocks. While the Markdown file is focused, press `CTRL-SHIFT-L` to switch focus back to the terminal without inserting a command. If the command contains any arguments using the curly brace `{{param}}` syntax, they will be treated as Workflow arguments. Learn more about [Workflows](/knowledge-and-collaboration/warp-drive/workflows/). [![](/assets/terminal/run-markdown-file-command.poster.jpg)](/assets/terminal/run-markdown-file-command.mp4) In addition, all shell and code blocks have a copy button to quickly copy the block’s text to the clipboard. Code blocks without a set language, or one of the following languages, are treated as shell commands: `sh`, `shell`, `bash`, `fish`, `zsh`, `warp-runnable-command`. # Desktop Notifications > Receive desktop notifications when long-running commands complete or need your input. ## What is it [Section titled “What is it”](#what-is-it) Notifications can be sent when a command completes after a configurable number of seconds or when a running command needs you to enter a password to proceed. For either of these triggers, Warp will only send you a desktop notification if you are using a different app at the time the trigger is fired. Note For notifications from coding agents (Warp’s built-in Agent and third-party CLI agents like Claude Code and OpenCode), see [Agent Notifications](/agent-platform/capabilities/agent-notifications/). ## Custom notification hooks (OSC 9 / OSC 777) [Section titled “Custom notification hooks (OSC 9 / OSC 777)”](#custom-notification-hooks-osc-9--osc-777) Warp supports pluggable notifications triggered by terminal escape sequences, so scripts and tools can raise desktop notifications without additional dependencies. * OSC 9 (body only): sends a notification with just a body. * Format: `ESC ] 9 ; BEL` * Example (bash/zsh): `printf '\033]9;Build complete\007'` * OSC 777 (title + body): sends a notification with a title and body. * Format: `ESC ] 777 ; notify ; ; <body> BEL` * Example (bash/zsh): `printf '\033]777;notify;Deploy;Success on prod\007'` Notes: * Works on macOS, Windows, and Linux where Warp is allowed to show notifications. * Newlines and semicolons should be avoided or escaped in payloads. * This feature is enabled by default in current releases of Warp. ## How to access it [Section titled “How to access it”](#how-to-access-it) ### Notifications [Section titled “Notifications”](#notifications) * Notifications are enabled by default and require system permissions to appear. * If you’ve turned Notifications off before, toggle it back on by going to **Settings** > **Features** > **Session**, or quickly toggle Notifications with the [Command Palette](/terminal/command-palette/). * Customize Notification triggers for long-running commands or password prompts by going to **Settings** > **Features** > **Notifications**. Note On macOS, you will want to **Allow** or **Accept** the request so that Warp can send you desktop notifications. If you accidentally denied it or would like to re-enable Notifications later, check the [troubleshooting guide below](/terminal/more-features/notifications/#troubleshooting-notifications). ## How it works [Section titled “How it works”](#how-it-works) [Notifications Demo](https://www.loom.com/embed/65967f43a7fa432b98cf3e94766a8e79) ## Troubleshooting Notifications [Section titled “Troubleshooting Notifications”](#troubleshooting-notifications) * macOS Warp requires two distinct notification settings to work. macOS system settings found in > **System Settings** > **Notifications & Focus** and Warp app settings found in **Settings** > **Features** > **Session** must both be enabled for Notifications to show.\ \ If you have Notifications enabled in the system and Warp, but you still aren’t receiving desktop notifications, try the following: * Make sure that you are navigated away from Warp when you expect to receive the notification. * Make sure the **Do Not Disturb** mode is turned off in > **System Settings** > **Notifications** > **Notifications & Focus** > **Focus**. * Go to > **System Settings** > **Notifications & Focus** > **Notifications** and select Warp in the list. Make sure either banner style or alert style notifications are selected, then quit and restart Warp. * To get the macOS notification prompt to show again for Warp, run `defaults delete dev.warp.Warp-Stable Notifications`, then restart Warp and toggle on the **Settings** > **Features** > **Receive desktop notifications from Warp**. * Once all of the above is done, please restart macOS to apply the changes and that should help with restoring notifications in Warp. * Windows Warp requires two distinct notification settings to work. Windows system settings found in **Settings** > **System** > **Notifications** > **Warp** and Warp app settings found in **Settings** > **Features** > **Session** must both be enabled for Notifications to show. If you have Notifications enabled in the system and Warp, but you still aren’t receiving desktop notifications, try the following: * Make sure that you are navigated away from Warp when you expect to receive the notification. * Make sure the **Do Not Disturb** mode or **Focus** is turned off. * Go to **System** > **Notifications** and select Warp in the list. Make sure notifications are turned on, then quit and restart Warp. * Linux Warp requires two distinct notification settings to work. Linux system settings found in **Settings** > **Notifications** > **Warp** and Warp app settings found in **Settings** > **Features** > **Session** must both be enabled for Notifications to show. If you have Notifications enabled in the system and Warp, but you still aren’t receiving desktop notifications, try the following: * Make sure that you are navigated away from Warp when you expect to receive the notification. * Make sure the **Do Not Disturb** mode (if your distribution supports it) is turned off. * Go to **Settings** > **Notifications** and select Warp in the list. Make sure notifications are turned on, then quit and restart Warp. Please [reach out to us](/support-and-community/troubleshooting-and-support/sending-us-feedback/#sending-warp-feedback) if you have any other issues. # Terminal quit warning > Warp's quit warning feature is a valuable precaution to prevent unintentional data loss or lost progress on long-running jobs. ## What is it [Section titled “What is it”](#what-is-it) The quit warning feature ensures that you receive a warning before quitting the app with a running process, allowing you to save your work and avoid any unintended data loss.\ If you quit the app or close a window containing a session with a running process, you’ll see the alert and need to confirm the action before proceeding. If you aren’t sure which processes you have running, there is also an option to show those processes. ## How to access it [Section titled “How to access it”](#how-to-access-it) * Open **Settings** > **Features** > **General**, there you can toggle the “Show warning before quitting”. * You can also toggle the quit warning feature in the [Command Palette](/terminal/command-palette/), by searching for \`Quit Warning’. * If enabled, when you try and close Warp you will see a pop-up window with a few options listed below: * Yes, quit, which will close all the Warps sessions and running processes. * Show running processes, which will bring up the [Session Navigation](/terminal/sessions/session-navigation/) panel with a filter for running processes. * Cancel, which will prevent Warp from closing. * Don’t ask again, which is a box you can check to disable the quit warning feature. ## How it Works [Section titled “How it Works”](#how-it-works) [Quit Warning Modal Demo](https://www.loom.com/embed/bacb9d1c1e3947dca8365e15231cfcd3) # Settings Sync > Keep your Warp settings consistent across devices and sessions with cloud-based sync. ## How to toggle settings sync [Section titled “How to toggle settings sync”](#how-to-toggle-settings-sync) * You can toggle Settings Sync within the **Settings** > **Account** pane * Through the [Command Palette](/terminal/command-palette/) by searching for “Settings Sync” ![Settings Sync in Account pane](/_astro/settings-sync-account.CXPtR0Zh_Z1dUiGF.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Settings Sync in Account pane. ![Settings Sync in Command Palette](/_astro/settings-sync-palette.IHlP0TEp_ZgCkRN.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Settings Sync in Command Palette. ## How settings sync works [Section titled “How settings sync works”](#how-settings-sync-works) **Settings Sync** works by syncing the state of most of your Warp settings to our cloud servers. When you log in to Warp on another device or through the browser with [Session Sharing](/knowledge-and-collaboration/session-sharing/), if you have Settings Sync enabled, most of your settings will be the same as they were when you were logged in before. That means your themes, most features, privacy settings, AI settings, **are all the same everywhere you use Warp**, saving you the time from having to set them up again. When you first enable Settings Sync, the settings from the computer you enabled it on becomes the default settings for all devices. This is true if you toggle Settings Sync off and on as well - the synced settings are always from **the last device you enabled Settings Sync on**, so toggling effectively causes all of your devices to have settings from the current logged in instance. Note Read more about privacy for cloud features in the [privacy overview](https://www.warp.dev/privacy/overview). ### Non-synced settings [Section titled “Non-synced settings”](#non-synced-settings) Not all settings are synced, however. Notably, Warp does not sync: * Custom keybindings (we may in the future). Although, you can set [custom keybinds with a file](/getting-started/keyboard-shortcuts/#custom-keyboard-shortcuts) * Custom themes (we may in the future) * Device specific settings (e.g. what editor you prefer using, startup shell) * Platform-specific settings are synced across devices on the same platform (e.g. your settings for how to interact with the Linux clipboard are synced across all Linux devices, but not on macOS, Windows, or Web). You can tell when a setting is not synced because it will have a special cloud strikethrough icon in the settings panel. ![Settings not synced](/_astro/settings-not-synced.DiTc6z_j_tV6fN.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Indicator showing settings are not synced. # Text selection > Use smart selection and rectangular (column) selection to quickly highlight text in Warp. ## Smart selection [Section titled “Smart selection”](#smart-selection) **Smart selection** goes beyond the typical double-click selection, which only highlights a single word. Instead, it uses semantic rules to treat common patterns (like URLs or file paths) as one unit, even when separated by punctuation or whitespace. ![Using smart selection to select a file path by double clicking.](/_astro/smart-selection.D6-9NXc1_Ze9MX3.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Using smart selection to select a file path by double clicking. Double-click on text in the input or blocklist. The following patterns are recognized: 1. URLs 2. File paths 3. Email addresses 4. IP addresses 5. Floating point numbers, including scientific notation. You can toggle smart selection on the **Settings** > **Features** > **Terminal** > **Double-click smart selection**. If disabled, you can instead manually select specific punctuation characters to be included within word boundaries. ## Rectangular selection [Section titled “Rectangular selection”](#rectangular-selection) **Rectangular selection** lets you highlight text in a clean vertical block (also called *column* or *box* selection). This is especially useful for copying command output, logs, or prefixed text without grabbing unwanted characters. ![Using rectangular selection to select by columns in the block output.](/_astro/rectangular-selection.Cl11DsbL_saXwb.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Using rectangular selection to select by columns in the block output. Hold the modifier keys while dragging your mouse: * macOS: `CMD-OPT` * Windows and Linux: `CTRL-ALT` # Warp URI Scheme > Warps URI scheme enables you to programmatically open new windows, tabs, or launch configurations with ease. ## How to use it [Section titled “How to use it”](#how-to-use-it) There are several ways to use the URI scheme: * Open new window `warp://action/new_window?path=<path_to_folder>` * Open new tab `warp://action/new_tab?path=<path_to_folder>` * Open Launch Configuration `warp://launch/<launch_configuration_path>` Note [Warp Preview](/support-and-community/community/warp-preview-and-alpha-program/) URI scheme begins with `warppreview://` ## How it works [Section titled “How it works”](#how-it-works) Example of Warp [URIs in use in Warp + Raycast Extension](https://github.com/raycast/extensions/blob/74521b70b62355004b0958393a64f9417b1ff3a6/extensions/warp/src/uri.ts). [Warp + Raycast Extension Demo made using URIs](https://twitter.com/i/status/1678432353461637121) # Working Directory > Set a default working directory for new Warp sessions, with options for home directory, previous session, custom path, or per-window/tab/pane configuration. ## What is it [Section titled “What is it”](#what-is-it) Warp’s working directory feature is designed to enhance your workflow by enabling you to set up a default directory for new sessions. This feature helps you save time and quickly access your preferred directories when starting new sessions. You have the flexibility to set up a working directory for all new sessions or customize it individually for Windows, Tabs, and Panes, based on your specific needs. ## How to access it [Section titled “How to access it”](#how-to-access-it) * Open **Settings** > **Features** > **Session** and go to “Working directory for new sessions”. * The drop-down for this feature provides several options discussed below: * Home Directory, is the default option for new sessions and opens new sessions in the currently logged-in users home folder `~/`. * Previous session’s directory, opens new sessions in your active sessions’ current directory. * Custom directory, opens new sessions in a file path you specify. * Advanced, allows you to select from the three options for new sessions in Windows, Tabs, and Panes. ## How to use it [Section titled “How to use it”](#how-to-use-it) [![](/assets/terminal/working-directory-demo.poster.jpg)](/assets/terminal/working-directory-demo.mp4) # Sessions overview > Navigate between sessions and automatically restore windows, tabs, and panes when you relaunch Warp. 1. [Session Navigation](/terminal/sessions/session-navigation/) enables you to easily navigate to any session in Warp. 2. [Session Restoration](/terminal/sessions/session-restoration/) automatically restores the window and tabs from your previous session. For tab layout configuration, see [Tab Configs](/terminal/windows/tab-configs/) and [Launch Configurations (Legacy)](/terminal/sessions/launch-configurations/) under [Windows and Tabs](/terminal/windows/). ## Session Navigation [Section titled “Session Navigation”](#session-navigation) [Session Navigation Demo](https://www.loom.com/embed/2147adc6749c4f4ea5da432eadda7995) ## Session Restoration [Section titled “Session Restoration”](#session-restoration) [![](/assets/terminal/sessions-block_restoration.poster.jpg)](/assets/terminal/sessions-block_restoration.mp4) # Launch Configurations (Legacy) > Launch Configurations (Legacy) let you save a configuration of windows, tabs, and panes. For new setups, use Tab Configs instead. Caution Launch Configurations have been replaced by [Tab Configs](/terminal/windows/tab-configs/). Existing Launch Configurations continue to work, but new features are not being added. For new setups, use [Tab Configs](/terminal/windows/tab-configs/). ## What is it [Section titled “What is it”](#what-is-it) With Launch configurations you can save in the app or by adding a yaml file. ## Creating a Launch Configuration [Section titled “Creating a Launch Configuration”](#creating-a-launch-configuration) ### From the UI [Section titled “From the UI”](#from-the-ui) 1. Set up the configuration of windows, tabs, and panes you would like to save. 2. Open the [Command Palette](/terminal/command-palette/), and type in `Save New Launch Configuration`. 3. Name the configuration file. The name field cannot be empty. 4. Click the Save configuration button. ### With a YAML File [Section titled “With a YAML File”](#with-a-yaml-file) * Launch Configurations files are generated when you create them with the UI and can also be created or modified manually. * Please see the below for [Launch Configuration YAML file locations, format, and examples](/terminal/sessions/launch-configurations/#launch-configuration-yaml-format). ## Using a Launch Configuration [Section titled “Using a Launch Configuration”](#using-a-launch-configuration) * macOS * From the [Command Palette](/terminal/command-palette/), enter `Launch Configuration` to open and select Launch Configuration. * Right-clicking the new Tab **+** button to open a menu and select saved Launch Configuration. * From the macOS menu bar, **File** > **Launch Configurations**, where you can search through and open your saved Launch Configuration. * Single-window launch configs can be launched into the active window from the launch configuration palette using `CMD-ENTER` on macOS. * Windows * From the [Command Palette](/terminal/command-palette/), enter `Launch Configuration` to open and select Launch Configuration. * Right-clicking the new Tab **+** button to open a menu and select saved Launch Configuration. * Single-window launch configs can be launched into the active window from the launch configuration palette using `CTRL-ENTER` on Linux. To open a WSL tab with a Launch Configuration, you must first set WSL as your default shell in Warp: * Go to **Settings** > **Features** > **Session** > **Startup shell for new sessions**. * Select your desired WSL distribution (e.g., Ubuntu) as the default shell. After this, any Launch Configuration you open will use WSL as the shell. * Linux * From the [Command Palette](/terminal/command-palette/), enter `Launch Configuration` to open and select Launch Configuration. * Right-clicking the new Tab **+** button to open a menu and select saved Launch Configuration. * Single-window launch configs can be launched into the active window from the launch configuration palette using `CTRL-ENTER` on Linux. Tip **Terminal Tip**\ You can open saved Launch Configurations via Alfred Workflow or [Raycast](/terminal/integrations-and-plugins/#raycast) Extension. Learn more [here](https://blog.joe.codes/open-warp-launch-configurations-from-raycast-and-alfred). Credit to [@joetannenbaum](https://twitter.com/joetannenbaum/status/1633538768866009115) ## How it works [Section titled “How it works”](#how-it-works) [Launch Configuration Demo](https://www.loom.com/embed/daa2a9e55c27458c8bbf722d90078880) ## Launch Configuration YAML Format [Section titled “Launch Configuration YAML Format”](#launch-configuration-yaml-format) All Launch Configuration yaml files are stored in the following location: * macOS ```bash $HOME/.warp/launch_configurations/ ``` * Windows ```powershell $env:APPDATA\warp\Warp\data\launch_configurations\ ``` * Linux ```bash ${XDG_DATA_HOME:-$HOME/.local/share}/warp-terminal/launch_configurations/ ``` Caution The `cwd:` value in the yaml code must contain an absolute path or `""`. Note that `~` or empty paths will result in the file not being visible on the list of options for Launch Configurations. ### Windows [Section titled “Windows”](#windows) Sample configuration that shows how windows are structured in launch configuration files. ```yaml # Warp Launch Configuration # # This configuration has two windows, # each with one tab in different starting directories. --- name: Example Windows windows: - tabs: - title: Documents layout: cwd: /Users/warp-user/Documents color: blue - tabs: - title: Warp User layout: cwd: /Users/warp-user color: green ``` ### Tabs [Section titled “Tabs”](#tabs) Here’s a sample configuration that shows how tabs are structured in launch configuration files. * Use the `title` field to set a custom tab name * Use the `color` field to set the tab color * We currently support using the terminal colors (ANSI colors): `Red | Green | Yellow | Blue | Magenta | Cyan` The actual color values will be automatically derived from your Warp theme ```yaml # Warp Launch Configuration # # This configuration has two tabs in the same window. --- name: Example Tabs windows: - tabs: - title: Documents layout: cwd: /Users/warp-user/Documents color: blue - title: Warp User layout: cwd: /Users/warp-user color: green ``` ### Panes [Section titled “Panes”](#panes) Launch Configurations support setting split panes in each tab. Note that Warp also supports nesting split panes in launch configuration files. ```yaml # Warp Launch Configuration # # This configuration is two windows, each with split panes. # The first window contains a vertically split tab with two panes. # The second window contains a horizontally split tab, # with a vertically split tab on the right. --- name: Example Panes windows: - tabs: - title: Downloads and Warp User layout: split_direction: vertical panes: - cwd: /Users/warp-user/Downloads - cwd: /Users/warp-user color: blue - tabs: - title: Desktop, Documents, and Warp User layout: split_direction: horizontal panes: - cwd: /Users/warp-user/Desktop - split_direction: vertical panes: - cwd: /Users/warp-user/Documents - cwd: /Users/warp-user color: green ``` ### Active and Focus [Section titled “Active and Focus”](#active-and-focus) Sample configuration that shows how a Window and Tab can be activated with a session in focus. * Use the `active_window_index` and `active_tab_index`fields to set your active Window and Tab. * Use the `is_focused` field to set which Pane is focused in each tab. Caution Note that when you use `- active_tab_index:` the `tabs:` field doesn’t need the `-` prefix, as this can cause syntax issues. ```yaml # Warp Launch Configuration # # This configurations has two tabs, with the second tab active. # Two vertical split panes in the first tab and the top pane focused. # Two horizontal split panes in the second tab and the right pane focused. --- name: Example Active and Focus active_window_index: 0 windows: - active_tab_index: 1 tabs: - title: Tab 1 layout: split_direction: vertical panes: - cwd: /Users/warp-user/Documents is_focused: true - cwd: /Users/warp-user/Documents/Projects - title: Tab 2 layout: split_direction: horizontal panes: - cwd: /Users/warp-user/Downloads - cwd: /Users/warp-user is_focused: true ``` ### Commands [Section titled “Commands”](#commands) Use the `commands` field to define a set of commands to run when a launch configuration in run. Caution You may need to use double quotes for commands with special characters. Commands in separate lines are chained together with `&&` when run, as such commands run after `ssh` commands may not execute. ```yaml # Warp Launch Configuration # # This configuration has two windows, # the first window executes two commands on start, # the second window has a split pane that executes a command on start. --- name: Example Commands windows: - tabs: - title: Documents layout: cwd: /Users/warp-user/Documents commands: - exec: ls - exec: code . color: blue - tabs: - title: Downloads layout: split_direction: vertical panes: - cwd: /Users/warp-user/Downloads commands: - exec: curl http://example.com -o my.file - exec: cp my.file my.file2 - cwd: /Users/warp-user commands: - exec: ssh user@remote.server.com color: green ``` # Session Navigation > Quickly navigate to any terminal session across Warp using the Session Navigation palette. ## How to access Session navigation [Section titled “How to access Session navigation”](#how-to-access-session-navigation) 1. Open the Session Navigation palette with the [Command Palette](/terminal/command-palette/), click on **session >\_** or type in “sessions:”. 2. Jump to a session by using your mouse or the `UP ↑`/`DOWN ↓` arrow keys and `ENTER`. 3. Refine the session results by searching for sessions by prompt, the currently running command, last run command, and command status (ex: “Running…”, “Completed 10 minutes ago”, “Empty Session”). Note Sessions are ordered by recency, so the most recently focused sessions show up first. The Session Navigation palette does not have **PS1** support and can only show Warp’s native prompt. ### CTRL-TAB behavior [Section titled “CTRL-TAB behavior”](#ctrl-tab-behavior) `CTRL-TAB` shortcut defaults to activate the previous / next [Tabs](/terminal/windows/tabs/). You can configure the shortcut to cycle the most recent session, including any [Split Panes](/terminal/windows/split-panes/), in **Settings** > **Features** > **Keys** > **Ctrl-Tab behavior** ## How session navigation works [Section titled “How session navigation works”](#how-session-navigation-works) [Session Navigation Demo](https://www.loom.com/embed/2147adc6749c4f4ea5da432eadda7995) # Session Restoration > Restore your windows, tabs, panes, and recent Blocks automatically when you relaunch Warp. ## What is it [Section titled “What is it”](#what-is-it) Session restoration allows you to quickly pick up where you left off in your previous terminal session. ## How to access Session Restoration [Section titled “How to access Session Restoration”](#how-to-access-session-restoration) * Session Restoration comes enabled by default in Warp. Note On Linux, opening windows at a specific position is not supported in Wayland. * You can disable Session Restoration by going to **Settings** > **Features**, then toggling off `Restore windows, tabs, and panes on startup`. Caution Toggling off Session Restoration will not clear the [SQLite database](/terminal/sessions/session-restoration/#session-restoration-database); however, Warp will stop recording new output. ## How session restoration works [Section titled “How session restoration works”](#how-session-restoration-works) [![](/assets/terminal/sessions-block_restoration.poster.jpg)](/assets/terminal/sessions-block_restoration.mp4) #### Session Restoration database [Section titled “Session Restoration database”](#session-restoration-database) Warp saves the data from your previous session’s windows, tabs, and panes to a SQLite database on your computer, and every time you quit the app, this data is overwritten by your latest session. You can open the database directly and inspect its full contents like so: * macOS ```bash sqlite3 "$HOME/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Stable/warp.sqlite" ``` * Windows ```powershell sqlite3 $env:LOCALAPPDATA\warp\Warp\data\warp.sqlite ``` * Linux ```bash sqlite3 "${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/warp.sqlite" ``` **How to clear the Session Restoration database** Sometimes, you may want to prevent a sensitive Block from being saved on your computer, or you may want to clear blocks from a machine entirely. Note This interferes with the running session’s ability to save content and may require you close Warp before running the database removal commands. Danger The following guidance is destructive and will delete any sessions and block history. There are two ways to do this: * macOS * Clear the blocks from your running Warp session with `CMD-K`. * Delete the SQLite file entirely with the following command: ```bash rm -f "$HOME/Library/Group Containers/2BBY89MBSN.dev.warp/Library/Application Support/dev.warp.Warp-Stable/warp.sqlite" ``` * Windows * Clear the blocks from your running Warp session with `CTRL-SHIFT-K`. * Delete the SQLite file entirely with the following command: ```powershell Remove-Item -Force $env:LOCALAPPDATA\warp\Warp\data\warp.sqlite ``` * Linux * Clear the blocks from your running Warp session with `CTRL-SHIFT-K`. * Delete the SQLite file entirely with the following command: ```bash rm -f "${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/warp.sqlite" ``` # Settings file > Configure Warp with a plain-text TOML settings file. Learn where it lives, how it works with the Settings panel, and see common configuration examples. Warp stores your preferences in a plain-text file called `settings.toml`. You can edit it directly in any text editor, check it into version control, or generate it with a script. Changes take effect immediately — no restart required. The settings file works alongside the graphical Settings panel. Changes you make in either place are reflected in the other. **Key features:** * **Hot-reload** — Warp watches `settings.toml` for changes and applies them instantly when you save the file. * **Error recovery** — If the file contains invalid TOML or an unrecognized value, Warp shows a warning banner and falls back to defaults for the affected settings. Fix the file and the banner clears automatically. * **Automatic migration** — When you upgrade to a version of Warp that includes the settings file, Warp automatically migrates your existing preferences into `settings.toml`. * **Bidirectional sync with Settings UI** — Changes in the Warp **Settings** panel (`⌘+,` on macOS, `Ctrl+,` on Linux/Windows) write to `settings.toml`, and hand-edits to the file are reflected in the panel. * **Agent-powered editing** — Ask Warp’s agent to change settings for you using natural language (for example, “increase my font size to 16”). The bundled `modify-settings` skill handles the file update automatically. ## Opening your settings file [Section titled “Opening your settings file”](#opening-your-settings-file) There are several ways to open `settings.toml`: * In the Warp app, go to **Settings** and click **Open settings file** at the bottom of the panel. * Open the file directly in any editor at the path listed below for your platform and Warp release channel. ## File location [Section titled “File location”](#file-location) Depending on your platform and Warp release channel, `settings.toml` is located at: * **macOS** * Stable — `~/.warp/settings.toml` * Preview — `~/.warp-preview/settings.toml` * **Linux** * Stable — `~/.config/warp-terminal/settings.toml` * Preview — `~/.config/warp-terminal-preview/settings.toml` * **Windows** * Stable — `%LOCALAPPDATA%\warp\Warp\config\settings.toml` * Preview — `%LOCALAPPDATA%\warp\WarpPreview\config\settings.toml` ## Settings file format [Section titled “Settings file format”](#settings-file-format) The file uses [TOML v1.1](https://toml.io/en/v1.1.0) syntax. Settings are organized into **sections** (TOML tables) that group related options — for example, `[appearance.text]` contains font settings and `[agents.profiles]` contains agent permission settings. Here is a minimal example showing the structure: ```toml # Appearance settings [appearance.text] font_name = "JetBrains Mono" font_size = 14.0 line_height_ratio = 1.3 [appearance.themes] theme = "dracula" # Terminal behavior [terminal.input] syntax_highlighting = true honor_ps1 = false # Agent permissions [agents.profiles] agent_mode_execute_readonly_commands = true ``` ### How sections map to TOML tables [Section titled “How sections map to TOML tables”](#how-sections-map-to-toml-tables) Each section in the settings file corresponds to a TOML table header in brackets. Subsections use dot-separated paths: * `[general]` — Top-level general settings like session restoration and tab placement * `[appearance]` — Visual settings, with subsections like `[appearance.text]`, `[appearance.themes]`, `[appearance.cursor]` * `[agents]` — Agent and AI settings, with subsections like `[agents.profiles]`, `[agents.warp_agent.input]` * `[terminal]` — Terminal behavior settings, with subsections like `[terminal.input]` For the complete list of every available setting, see [All settings reference](/terminal/settings/all-settings/). ## How settings are applied [Section titled “How settings are applied”](#how-settings-are-applied) ### Relationship between the Settings panel and the file [Section titled “Relationship between the Settings panel and the file”](#relationship-between-the-settings-panel-and-the-file) The Warp Settings panel (`⌘+,` on macOS, `Ctrl+,` on Linux/Windows) and `settings.toml` represent the same underlying configuration. Changing a toggle in the Settings panel writes the new value to `settings.toml`. Editing `settings.toml` by hand updates the Settings panel the next time it reads the file. ### Error banner [Section titled “Error banner”](#error-banner) When `settings.toml` has errors, Warp displays a dismissible warning banner at the top of the workspace. The banner includes an **Open settings file** button so you can jump directly to the file and fix the issue. Once you save a corrected file, the banner disappears automatically. ## Common configurations [Section titled “Common configurations”](#common-configurations) ### Change theme and font [Section titled “Change theme and font”](#change-theme-and-font) ```toml [appearance.themes] theme = "cyber_wave" [appearance.text] font_name = "Fira Code" font_size = 15.0 ligature_rendering_enabled = true font_weight = "normal" ``` ### Configure agent permissions [Section titled “Configure agent permissions”](#configure-agent-permissions) ```toml [agents.profiles] agent_mode_coding_permissions = "always_allow_reading" agent_mode_execute_readonly_commands = true agent_mode_command_execution_allowlist = [ "cat(\\s.*)?", "echo(\\s.*)?", "find .*", "grep(\\s.*)?", "ls(\\s.*)?", "which .*", ] ``` ### Enable Vim keybindings [Section titled “Enable Vim keybindings”](#enable-vim-keybindings) ```toml [text_editing] vim_mode_enabled = true vim_status_bar = true ``` ## Migrating from previous settings [Section titled “Migrating from previous settings”](#migrating-from-previous-settings) When you upgrade to a version of Warp that includes the settings file, Warp automatically migrates your existing preferences into `settings.toml`. No action is required — your customizations carry over and the file becomes the source of truth for all settings going forward. ## Troubleshooting [Section titled “Troubleshooting”](#troubleshooting) ### ”Your settings file contains an error” banner [Section titled “”Your settings file contains an error” banner”](#your-settings-file-contains-an-error-banner) This banner appears when `settings.toml` has invalid TOML syntax or an unrecognized value. Click **Open settings file** in the banner to open the file and look for: * **Missing quotes** — String values must be wrapped in double quotes: `font_name = "Hack"`, not `font_name = Hack`. * **Missing brackets** — Section headers require square brackets: `[appearance.text]`. * **Wrong value types** — Check that numbers are numbers (`font_size = 13.0`), booleans are `true`/`false`, and enum values are valid strings. ### Resetting to defaults [Section titled “Resetting to defaults”](#resetting-to-defaults) Delete `settings.toml` (or rename it) and restart Warp. Warp falls back to built-in defaults for all settings. The file is re-created the next time you change a setting through the Settings panel. ```bash # Uncomment the two lines that match your platform and Warp release # channel, then run them to back up and delete settings.toml. # Stable (macOS) # cp ~/.warp/settings.toml ~/.warp/settings.toml.bak # rm ~/.warp/settings.toml # Stable (Linux) # cp ~/.config/warp-terminal/settings.toml ~/.config/warp-terminal/settings.toml.bak # rm ~/.config/warp-terminal/settings.toml # Preview (macOS) # cp ~/.warp-preview/settings.toml ~/.warp-preview/settings.toml.bak # rm ~/.warp-preview/settings.toml # Preview (Linux) # cp ~/.config/warp-terminal-preview/settings.toml ~/.config/warp-terminal-preview/settings.toml.bak # rm ~/.config/warp-terminal-preview/settings.toml ``` ### Settings not applying [Section titled “Settings not applying”](#settings-not-applying) Confirm you’re editing the correct file for your platform and Warp release channel (see [File location](#file-location) above). If you run multiple [Warp release channels](/support-and-community/community/warp-preview-and-alpha-program/), each channel has its own settings directory. ## Related pages [Section titled “Related pages”](#related-pages) * [All settings reference](/terminal/settings/all-settings/) — Complete list of every available setting with descriptions, types, and defaults * [Customizing Warp](/getting-started/quickstart/customizing-warp/) — Overview of all customization options * [Custom themes](/terminal/appearance/custom-themes/) — Create and load custom YAML or Base16 themes * [Keyboard shortcuts](/getting-started/keyboard-shortcuts/) — Customize keybindings * [Settings Sync (Beta)](/terminal/more-features/settings-sync/) — Sync settings across machines # All settings reference > Complete reference for every setting available in Warp's settings.toml file, organized by section with descriptions, types, defaults, and examples. This page lists every setting you can configure in [`settings.toml`](/terminal/settings/) organized by TOML section. For an introduction to the settings file, how to open it, and common configuration examples, see [Settings file](/terminal/settings/). Settings are grouped into sections that correspond to TOML table headers (for example, `[appearance.text]`). Only include the settings you want to change — Warp uses built-in defaults for everything else. ## General [Section titled “General”](#general) Top-level settings that control Warp’s startup behavior, session management, and window-level preferences. **Section**: `[general]` * `default_session_mode` — The default mode for new terminal sessions. Type: string. Default: `"terminal"`. Options: `"terminal"`, `"agent"`, `"cloud_agent"`, `"tab_config"`, `"docker_sandbox"`. * `default_tab_config_path` — Path to the tab config used when `default_session_mode` is `"tab_config"`. Type: string. Default: `""`. * `link_tooltip` — Whether to show a tooltip when hovering over links. Type: boolean. Default: `true`. * `login_item` — Whether to launch Warp automatically when you log in. Type: boolean. Default: `true`. * `mouse_scroll_multiplier` — The scroll speed multiplier for mouse scroll events. Type: number. Default: `3.0`. * `new_tab_placement` — Where new tabs are placed in the tab bar. Type: string. Default: `"after_current_tab"`. Options: `"after_current_tab"`, `"after_all_tabs"`. * `quit_on_last_window_closed` — Whether to quit Warp when the last window is closed. Type: boolean. Default: `false`. * `restore_session` — Whether to restore the previous session when Warp starts up. Type: boolean. Default: `true`. * `should_confirm_close_session` — Whether to show a confirmation dialog when closing a session. Type: boolean. Default: `true`. * `show_changelog_after_update` — Whether the changelog is shown after an update. Type: boolean. Default: `true`. * `show_warning_before_quitting` — Whether to show a warning dialog before quitting Warp. Type: boolean. Default: `true`. * `snackbar_enabled` — Whether to show snackbar notifications. Type: boolean. Default: `true`. * `user_native_preference` — Whether to prefer the native desktop app or the web app. Type: string. Default: `"not_selected"`. Options: `"not_selected"`, `"web"`, `"desktop"`. ### Undo close [Section titled “Undo close”](#undo-close) **Section**: `[general.undo_close]` * `enabled` — Whether the undo close feature is enabled. Type: boolean. Default: `true`. * `grace_period` — How long (in seconds) after closing a tab you can still undo the close. Type: integer. Default: `60`. ## Appearance [Section titled “Appearance”](#appearance) Visual settings that control how Warp looks, including themes, fonts, cursor, tabs, window, and layout. **Section**: `[appearance]` * `spacing` — Controls the spacing between terminal blocks. Type: string. Default: `"normal"`. Options: `"normal"`, `"compact"`. ### Themes [Section titled “Themes”](#themes) **Section**: `[appearance.themes]` * `theme` — The color theme. Type: string. Default: `"dark"`. Options: `"adeberry"`, `"phenomenon"`, `"dark"`, `"dracula"`, `"fancy_dracula"`, `"cyber_wave"`, `"solar_flare"`, `"solarized_dark"`, `"willow_dream"`, `"light"`, `"dark_city"`, `"gruvbox_dark"`, `"red_rock"`, `"jelly_fish"`, `"leafy"`, `"koi"`, `"solarized_light"`, `"snowy"`, `"gruvbox_light"`, `"pink_city"`, `"marble"`, or a custom theme object. * `system_theme` — Whether to match the system light/dark theme. Type: boolean. Default: `false`. * `selected_system_themes` — The themes to use for system light and dark modes. Type: object. Default: `{ dark = "dark", light = "light" }`. To use a custom theme: ```toml [appearance.themes] theme = { custom = { name = "My Theme", path = "~/.warp/themes/my-theme.yaml" } } ``` ### Text [Section titled “Text”](#text) **Section**: `[appearance.text]` * `font_name` — The monospace font used in the terminal. Type: string. Default: `"Hack"`. * `font_size` — The size of the monospace font in the terminal. Type: number. Default: `13.0`. * `font_weight` — The weight of the monospace font. Type: string. Default: `"normal"`. Options: `"thin"`, `"extra_light"`, `"light"`, `"normal"`, `"medium"`, `"semibold"`, `"bold"`, `"extra_bold"`, `"black"`. * `line_height_ratio` — The line height ratio for terminal text. Type: number. Default: `1.2`. * `ligature_rendering_enabled` — Whether to render font ligatures in the terminal. Type: boolean. Default: `false`. * `ai_font_name` — The font used for AI-generated content. Type: string. Default: `"Hack"`. * `match_ai_font` — Whether the AI font automatically matches the terminal font. Type: boolean. Default: `false`. * `notebook_font_size` — The font size used in notebooks. Type: number. Default: `14.0`. * `match_notebook_to_monospace_font_size` — Whether the notebook font size matches the terminal font size. Type: boolean. Default: `true`. * `use_thin_strokes` — Whether to use thin font strokes on macOS. Type: string. Default: `"on_high_dpi_displays"`. Options: `"never"`, `"on_low_dpi_displays"`, `"on_high_dpi_displays"`, `"always"`. * `enforce_minimum_contrast` — Whether to enforce minimum contrast for text readability. Type: string. Default: `"only_named_colors"`. Options: `"never"`, `"only_named_colors"`, `"always"`. ### Cursor [Section titled “Cursor”](#cursor) **Section**: `[appearance.cursor]` * `cursor_display_type` — The visual style of the cursor. Type: string. Default: `"bar"`. Options: `"bar"`, `"block"`, `"underline"`. * `cursor_blink` — Whether the cursor blinks. Type: string. Default: `"enabled"`. Options: `"enabled"`, `"disabled"`. ### Blocks [Section titled “Blocks”](#blocks) **Section**: `[appearance.blocks]` * `show_block_dividers` — Whether to show dividers between terminal blocks. Type: boolean. Default: `true`. * `show_jump_to_bottom_of_block_button` — Whether to show the jump-to-bottom button in long command output. Type: boolean. Default: `true`. * `should_show_bootstrap_block` — Whether the bootstrap block is visible in the terminal. Type: boolean. Default: `false`. * `should_show_in_band_command_blocks` — Whether in-band command blocks are visible. Type: boolean. Default: `false`. * `should_show_ssh_block` — Whether the SSH connection block is visible. Type: boolean. Default: `false`. ### Tabs [Section titled “Tabs”](#tabs) **Section**: `[appearance.tabs]` * `workspace_decoration_visibility` — When workspace decorations such as the tab bar are visible. Type: string. Default: `"hide_fullscreen"`. Options: `"always_show"`, `"hide_fullscreen"`, `"on_hover"`. * `tab_close_button_position` — Position of the close button on tabs. Type: string. Default: `"right"`. Options: `"right"`, `"left"`. * `show_indicators_button` — Whether to show activity indicators on tabs. Type: boolean. Default: `true`. * `preserve_active_tab_color` — Whether to preserve the active tab’s color when switching tabs. Type: boolean. Default: `false`. * `header_toolbar_chip_selection` — Configuration for the header toolbar chips in the vertical tab panel header. Type: string or object. Default: `"default"`. ### Vertical tabs [Section titled “Vertical tabs”](#vertical-tabs) **Section**: `[appearance.vertical_tabs]` * `enabled` — Whether to display tabs vertically instead of horizontally. Type: boolean. Default: `false`. * `view_mode` — Display mode for the vertical tab bar. Type: string. Default: `"compact"`. Options: `"compact"`, `"expanded"`. * `primary_info` — The primary information displayed on vertical tabs. Type: string. Default: `"command"`. Options: `"command"`, `"working_directory"`, `"branch"`. * `compact_subtitle` — Subtitle shown on compact vertical tabs. Type: string. Default: `"branch"`. Options: `"branch"`, `"working_directory"`, `"command"`. * `display_granularity` — Granularity of rows displayed in the vertical tabs panel. Type: string. Default: `"panes"`. Options: `"panes"`, `"tabs"`. * `tab_item_mode` — Tab item display mode in vertical tabs. Type: string. Default: `"focused_session"`. Options: `"focused_session"`, `"summary"`. * `show_details_on_hover` — Whether to show a details sidecar when hovering over a vertical tab. Type: boolean. Default: `true`. * `show_diff_stats` — Whether to show diff stats on vertical tabs. Type: boolean. Default: `true`. * `show_pr_link` — Whether to show PR links on vertical tabs. Type: boolean. Default: `true`. * `use_latest_prompt_as_title` — Whether vertical tab names for agent conversations use the latest user prompt. Type: boolean. Default: `false`. ### Panes [Section titled “Panes”](#panes) **Section**: `[appearance.panes]` * `focus_pane_on_hover` — Whether panes are focused when hovered over. Type: boolean. Default: `false`. * `should_dim_inactive_panes` — Whether inactive panes are visually dimmed. Type: boolean. Default: `false`. ### Input position [Section titled “Input position”](#input-position) **Section**: `[appearance.input]` * `input_mode` — The position of the terminal input. Type: string. Default: `"pinned_to_bottom"`. Options: `"pinned_to_bottom"`, `"pinned_to_top"`, `"waterfall"`. ### Full-screen apps [Section titled “Full-screen apps”](#full-screen-apps) **Section**: `[appearance.full_screen_apps]` * `alt_screen_padding` — Controls padding around full-screen terminal applications. Type: string or object. Default: `{ custom = { uniform_padding = 0.0 } }`. ### Icon [Section titled “Icon”](#icon) **Section**: `[appearance.icon]` * `app_icon` — The app icon displayed in the dock. Type: string. Default: `"default"`. Options: `"default"`, `"aurora"`, `"classic1"`, `"classic2"`, `"classic3"`, `"comets"`, `"cow"`, `"glass_sky"`, `"glitch"`, `"glow"`, `"holographic"`, `"mono"`, `"neon"`, `"original"`, `"starburst"`, `"sticker"`, `"warp_one"`. ### Window [Section titled “Window”](#window) **Section**: `[appearance.window]` * `override_opacity` — The opacity of the window background, from 1 to 100 percent. Type: integer. Default: `100`. * `override_blur` — The blur radius applied to the window background. Type: integer. Default: `1`. * `override_blur_texture` — Whether to apply a blur texture to the window background. Type: boolean. Default: `false`. * `zoom_level` — The zoom level for the window, as a percentage. Type: integer. Default: `100`. * `open_windows_at_custom_size` — Whether to open new windows at a custom size instead of the default. Type: boolean. Default: `false`. * `new_windows_num_columns` — The number of columns for new windows when using a custom size. Type: integer. Default: `80`. * `new_windows_num_rows` — The number of rows for new windows when using a custom size. Type: integer. Default: `40`. * `left_panel_visibility_across_tabs` — Whether the left panel visibility is shared across all tabs. Type: boolean. Default: `true`. ## Terminal [Section titled “Terminal”](#terminal) Settings that control terminal behavior, input, and event handling. **Section**: `[terminal]` * `copy_on_select` — Whether text is automatically copied to the clipboard when selected. Type: boolean. Default: `true`. * `focus_reporting_enabled` — Whether to forward focus and blur events to full-screen terminal applications. Type: boolean. Default: `true`. * `mouse_reporting_enabled` — Whether to forward mouse events to full-screen terminal applications. Type: boolean. Default: `true`. * `scroll_reporting_enabled` — Whether to forward scroll events to full-screen terminal applications. Type: boolean. Default: `true`. * `maximum_grid_size` — The maximum number of rows in the terminal grid. Type: integer. Default: `50000`. * `use_audible_bell` — Whether to play an audible bell sound on terminal bell events. Type: boolean. Default: `false`. * `show_terminal_zero_state_block` — Whether to show the AI zero-state block in new terminal sessions. Type: boolean. Default: `true`. ### Input [Section titled “Input”](#input) **Section**: `[terminal.input]` * `syntax_highlighting` — Whether syntax highlighting is enabled in the terminal input. Type: boolean. Default: `true`. * `honor_ps1` — Whether to use your shell’s PS1 prompt instead of the Warp prompt. Type: boolean. Default: `false`. * `input_box_type_setting` — The terminal input style. Type: string. Default: `"classic"`. Options: `"universal"` (AI-first input), `"classic"` (Terminal-first input). * `alias_expansion_enabled` — Whether shell alias expansion is enabled in the input. Type: boolean. Default: `false`. * `command_corrections` — Whether command corrections are suggested for mistyped commands. Type: boolean. Default: `true`. * `error_underlining_enabled` — Whether command errors are underlined in the input. Type: boolean. Default: `true`. * `completions_open_while_typing` — Whether the completions menu opens automatically while typing. Type: boolean. Default: `false`. * `classic_completions_mode` — Whether classic completions mode is enabled. Type: boolean. Default: `false`. * `show_hint_text` — Whether hint text is shown in the terminal input. Type: boolean. Default: `true`. * `show_terminal_input_message_bar` — Whether the terminal input message bar is shown. Type: boolean. Default: `true`. * `enable_slash_commands_in_terminal` — Whether slash commands are available in the terminal input. Type: boolean. Default: `true`. * `at_context_menu_in_terminal_mode` — Whether the @ context menu is available in terminal mode. Type: boolean. Default: `true`. * `outline_codebase_symbols_for_at_context_menu` — Whether codebase symbols appear in the @ context menu. Type: boolean. Default: `true`. * `middle_click_paste_enabled` — Whether middle-click pastes from the clipboard. Type: boolean. Default: `true`. * `extra_meta_keys` — Controls which additional keys are treated as meta keys. Type: object. Default: `{ left_alt = false, right_alt = false }`. #### Autosuggestions [Section titled “Autosuggestions”](#autosuggestions) **Section**: `[terminal.input.autosuggestions]` * `enabled` — Whether command autosuggestions are shown. Type: boolean. Default: `true`. * `keybinding_hint` — Whether autosuggestion keybinding hints are displayed. Type: boolean. Default: `true`. * `show_ignore_button` — Whether the ignore button is shown for autosuggestions. Type: boolean. Default: `false`. ### Smart select [Section titled “Smart select”](#smart-select) **Section**: `[terminal.smart_select]` * `enabled` — Whether double-click smart selection is enabled for URLs, emails, file paths, and identifiers. Type: boolean. Default: `true`. * `word_char_allowlist` — Characters considered part of a word for double-click selection when smart select is disabled. Type: string. Default: `"-.~/\"`. ## Session [Section titled “Session”](#session) Settings that control shell selection and working directory behavior for new sessions. **Section**: `[session]` * `startup_shell_override` — The shell to use when Warp starts up. Type: string or null. Default: `null` (uses system default). * `new_session_shell_override` — The shell to use when opening a new session. Type: string, object, or null. Default: `null` (uses system default). Options: `"system_default"`, `{ executable = "/path/to/shell" }`, `{ custom = "command" }`. ### Working directory config [Section titled “Working directory config”](#working-directory-config) **Section**: `[session.working_directory_config]` * `advanced_mode` — Whether to use separate settings per session source. Type: boolean. Default: `false`. When `advanced_mode` is `false`, the `[session.working_directory_config.global]` table applies to all session sources. When `true`, you can configure each source independently. **Section**: `[session.working_directory_config.global]` (also `.split_pane`, `.new_tab`, `.new_window`) * `mode` — How the working directory is determined. Type: string. Default: `"previous_dir"`. Options: `"home_dir"`, `"previous_dir"`, `"custom_dir"`. * `custom_dir` — Custom directory path, used when mode is `"custom_dir"`. Type: string. Default: `""`. ```toml # Use a specific directory for split panes, previous directory for everything else [session.working_directory_config] advanced_mode = true [session.working_directory_config.global] mode = "previous_dir" custom_dir = "" [session.working_directory_config.split_pane] mode = "custom_dir" custom_dir = "~/projects" [session.working_directory_config.new_tab] mode = "previous_dir" custom_dir = "" [session.working_directory_config.new_window] mode = "home_dir" custom_dir = "" ``` ## Agents [Section titled “Agents”](#agents) Settings for Warp’s agents, including model behavior, permissions, knowledge, MCP servers, and voice input. **Section**: `[agents]` * `cloud_conversation_storage_enabled` — Whether conversations are stored in the cloud. Type: boolean. Default: `true`. ### Knowledge [Section titled “Knowledge”](#knowledge) **Section**: `[agents.knowledge]` * `rules_enabled` — Whether the agent uses your saved rules during requests. Type: boolean. Default: `true`. * `warp_drive_context_enabled` — Whether Warp Drive context is included in AI requests. Type: boolean. Default: `true`. ### MCP servers [Section titled “MCP servers”](#mcp-servers) **Section**: `[agents.mcp_servers]` * `file_based_mcp_enabled` — Whether global file-based MCP servers from third-party agents are automatically spawned. Warp-managed global MCP servers auto-spawn regardless of this setting, and project-scoped servers must be started manually. Type: boolean. Default: `false`. ### Profiles (permissions) [Section titled “Profiles (permissions)”](#profiles-permissions) **Section**: `[agents.profiles]` * `agent_mode_coding_permissions` — The file read permission level for the agent. Type: string. Default: `"always_ask_before_reading"`. Options: `"always_ask_before_reading"`, `"always_allow_reading"`, `"allow_reading_specific_files"`. * `agent_mode_coding_file_read_allowlist` — File paths the agent can read without asking for permission. Type: array of strings. Default: `[]`. * `agent_mode_execute_readonly_commands` — Whether the agent can auto-execute read-only commands without asking. Type: boolean. Default: `false`. * `agent_mode_command_execution_allowlist` — Commands the agent can execute without explicit permission (regex patterns). Type: array of strings. Default: `["cat(\\s.*)?", "echo(\\s.*)?", "find .*", "grep(\\s.*)?", "ls(\\s.*)?", "which .*"]`. * `agent_mode_command_execution_denylist` — Commands the agent must always ask before executing (regex patterns). Type: array of strings. Default: `["bash(\\s.*)?", "fish(\\s.*)?", "pwsh(\\s.*)?", "sh(\\s.*)?", "zsh(\\s.*)?", "curl(\\s.*)?", "eval(\\s.*)?", "exec(\\s.*)?", "source(\\s.*)?", "wget(\\s.*)?", "dig(\\s.*)?", "nslookup(\\s.*)?", "host(\\s.*)?", "ssh(\\s.*)?", "scp(\\s.*)?", "rsync(\\s.*)?", "telnet(\\s.*)?", "rm(\\s.*)?"]`. ### Warp Agent (AI features) [Section titled “Warp Agent (AI features)”](#warp-agent-ai-features) **Section**: `[agents.warp_agent]` * `is_any_ai_enabled` — Controls whether all AI features are enabled. Type: boolean. Default: `true`. #### Active AI [Section titled “Active AI”](#active-ai) **Section**: `[agents.warp_agent.active_ai]` * `enabled` — Controls whether proactive AI features like suggestions are enabled. Type: boolean. Default: `true`. * `code_suggestions_enabled` — Controls whether AI code suggestions are enabled. Type: boolean. Default: `true`. * `intelligent_autosuggestions_enabled` — Controls whether AI-powered intelligent autosuggestions are enabled. Type: boolean. Default: `true`. * `agent_mode_query_suggestions_enabled` — Controls whether prompt suggestions are shown in Agent Mode. Type: boolean. Default: `true`. * `shared_block_title_generation_enabled` — Controls whether titles are auto-generated when sharing blocks. Type: boolean. Default: `true`. #### Input [Section titled “Input”](#input-1) **Section**: `[agents.warp_agent.input]` * `ai_auto_detection_enabled` — Controls whether AI automatically detects natural language input. Type: boolean. Default: `true`. * `ai_command_denylist` — Commands to exclude from AI natural language autodetection. Type: string. Default: `""`. * `nld_in_terminal_enabled` — Controls whether natural language detection is enabled in the terminal input. Type: boolean. Default: `false`. * `show_model_selectors_in_prompt` — Whether to show AI model selectors in the input prompt. Type: boolean. Default: `true`. * `show_agent_tips` — Whether agent tips are displayed in the input. Type: boolean. Default: `true`. * `include_agent_commands_in_history` — Whether agent-executed commands are included in command history. Type: boolean. Default: `false`. * `agent_toolbar_chip_selection_setting` — Controls the layout of context chips in the Agent Mode toolbar. Type: string or object. Default: `"default"`. #### Other [Section titled “Other”](#other) **Section**: `[agents.warp_agent.other]` * `thinking_display_mode` — Controls how agent thinking traces are displayed after streaming. Type: string. Default: `"show_and_collapse"`. Options: `"show_and_collapse"`, `"always_show"`, `"never_show"`. * `open_conversation_layout_preference` — Whether to open agent conversations in a new tab or a split pane. Type: string. Default: `"new_tab"`. Options: `"new_tab"`, `"split_pane"`. * `show_conversation_history` — Whether conversation history appears in the tools panel. Type: boolean. Default: `true`. * `show_agent_notifications` — Whether agent notifications are shown. Type: boolean. Default: `true`. * `should_show_oz_updates_in_zero_state` — Whether the “What’s new” section is shown in the agent view. Type: boolean. Default: `true`. * `should_render_use_agent_toolbar_for_user_commands` — Whether to show the “Use Agent” footer for terminal commands. Type: boolean. Default: `true`. * `cloud_agent_computer_use_enabled` — Whether computer use is enabled for cloud agent conversations. Type: boolean. Default: `false`. ### Code review autogeneration [Section titled “Code review autogeneration”](#code-review-autogeneration) Controls AI-driven autogeneration in the code review dialogs. This setting currently lives under `[agents.oz.active_ai]` rather than alongside the other `[agents.warp_agent.active_ai]` settings. **Section**: `[agents.oz.active_ai]` * `git_operations_autogen_enabled` — Controls whether AI auto-generates commit messages and PR title and body in the code review dialogs. Type: boolean. Default: `true`. ### Third-party (CLI agents) [Section titled “Third-party (CLI agents)”](#third-party-cli-agents) **Section**: `[agents.third_party]` * `should_render_cli_agent_toolbar` — Whether to show the CLI agent footer for coding agent commands. Type: boolean. Default: `true`. * `auto_toggle_composer` — Whether CLI agent Rich Input automatically closes and reopens based on the agent’s blocked state. Type: boolean. Default: `true`. * `auto_open_composer_on_cli_agent_start` — Whether CLI agent Rich Input automatically opens when a CLI agent session starts. Type: boolean. Default: `false`. * `auto_dismiss_composer_after_submit` — Whether CLI agent Rich Input automatically closes after the user submits a prompt. Type: boolean. Default: `false`. * `cli_agent_toolbar_chip_selection_setting` — Controls the layout of context chips in the CLI Agent toolbar. Type: string or object. Default: `"default"`. * `cli_agent_toolbar_enabled_commands` — Maps custom toolbar command patterns to specific CLI agents. Type: object. Default: `{}`. ### Voice [Section titled “Voice”](#voice) **Section**: `[agents.voice]` * `voice_input_enabled` — Controls whether voice input is enabled for AI interactions. Type: boolean. Default: `true`. * `voice_input_toggle_key` — The key used to toggle voice input. Type: string. Default: `"none"`. Options: `"none"`, `"fn"`, `"alt_left"`, `"alt_right"`, `"control_left"`, `"control_right"`, `"super_left"`, `"super_right"`, `"shift_left"`, `"shift_right"`. ## Code [Section titled “Code”](#code) Settings for Warp’s built-in code editor, file handling, and codebase indexing. **Section**: `[code]` ### Editor [Section titled “Editor”](#editor) **Section**: `[code.editor]` * `open_file_editor` — The editor used to open files. Type: string or object. Default: `"system_default"`. Options: `"system_default"`, `"warp"`, `"env_editor"`, or an external editor object such as `{ external_editor = "v_s_code" }`. Supported external editors: VS Code (`v_s_code`), VS Code Insiders (`v_s_code_insiders`), PyCharm (`py_charm`), IntelliJ IDEA (`intelli_j`), CLion (`c_lion`), RustRover (`rust_rover`), Sublime Text 4 (`sublime4`), Zed (`zed`), Cursor (`cursor`), Windsurf (`windsurf`), and others. * `open_code_panels_file_editor` — The editor used to open files from code panels. Type: string or object. Default: `"warp"`. * `open_file_layout` — The layout used when opening files in the editor. Type: string. Default: `"split_pane"`. Options: `"split_pane"`, `"new_tab"`. * `prefer_markdown_viewer` — Whether to use the Markdown viewer when opening Markdown files. Type: boolean. Default: `true`. * `prefer_tabbed_editor_view` — Whether to prefer opening files in a tabbed editor view. Type: boolean. Default: `true`. * `show_code_review_button` — Whether to show the code review button on tabs. Type: boolean. Default: `true`. * `auto_open_code_review_pane_on_first_agent_change` — Whether to automatically open the code review pane when the agent makes its first change. Type: boolean. Default: `false`. * `show_code_review_diff_stats` — Whether to show lines added/removed counts on the code review button. Type: boolean. Default: `true`. * `show_project_explorer` — Whether the project explorer is shown in the tools panel. Type: boolean. Default: `true`. * `show_global_search` — Whether global file search is shown in the tools panel. Type: boolean. Default: `true`. * `use_warp_as_default_editor` — Whether Warp is used as the default code editor. Type: boolean. Default: `false`. ### Indexing [Section titled “Indexing”](#indexing) **Section**: `[code.indexing]` * `agent_mode_codebase_context` — Whether Codebase Context is provided to the agent. Type: boolean. Default: `true`. * `agent_mode_codebase_context_auto_indexing` — Whether automatic codebase indexing is enabled. Type: boolean. Default: `false`. ## Keys [Section titled “Keys”](#keys) Keyboard behavior settings. **Section**: `[keys]` * `ctrl_tab_behavior_setting` — Controls the behavior of `Ctrl+Tab`. Type: string. Default: `"activate_prev_next_tab"`. Options: `"activate_prev_next_tab"`, `"cycle_most_recent_session"`. ## Notifications [Section titled “Notifications”](#notifications) Settings that control desktop notification behavior. **Section**: `[notifications]` * `toast_duration_secs` — How long notification toasts are displayed, in seconds. Type: integer. Default: `8`. ### Preferences [Section titled “Preferences”](#preferences) **Section**: `[notifications.preferences]` * `mode` — Whether notifications are enabled, disabled, or not yet configured. Type: string. Default: `"unset"`. Options: `"unset"`, `"dismissed"`, `"enabled"`, `"disabled"`. * `is_long_running_enabled` — Whether to notify when a long-running command completes. Type: boolean. Default: `true`. * `long_running_threshold` — Threshold in seconds for long-running command notifications. Type: integer. Default: `30`. * `is_agent_task_completed_enabled` — Whether to notify when an agent task completes. Type: boolean. Default: `true`. * `is_needs_attention_enabled` — Whether to notify when a session needs attention. Type: boolean. Default: `true`. * `is_password_prompt_enabled` — Whether to notify when a password prompt is detected. Type: boolean. Default: `true`. * `play_notification_sound` — Whether to play a sound with notifications. Type: boolean. Default: `true`. ## Privacy [Section titled “Privacy”](#privacy) Settings that control telemetry, crash reporting, and secret redaction. **Section**: `[privacy]` * `telemetry_enabled` — Whether anonymous usage telemetry is collected. Type: boolean. Default: `true`. * `crash_reporting_enabled` — Whether crash reports are sent. Type: boolean. Default: `true`. * `custom_secret_regex_list` — Custom regex patterns for detecting and redacting secrets. Type: array of objects. Default: `[]`. Each item in `custom_secret_regex_list` has the format: ```toml [[privacy.custom_secret_regex_list]] pattern = "sk-[A-Za-z0-9]{48}" name = "OpenAI API key" ``` ### Secret redaction [Section titled “Secret redaction”](#secret-redaction) **Section**: `[privacy.secret_redaction]` * `enabled` — Whether secret redaction is enabled to detect and obscure secrets in terminal output. Type: boolean. Default: `false`. * `hide_secrets_in_block_list` — Whether to hide detected secrets in the block list using asterisks. Type: boolean. Default: `false`. * `secret_display_mode_setting` — Controls how detected secrets are visually displayed. Type: string. Default: `"strikethrough"`. Options: `"asterisks"`, `"strikethrough"`, `"always_show"`. ## System [Section titled “System”](#system) Low-level system and rendering settings. **Section**: `[system]` * `prefer_low_power_gpu` — Whether to prefer the integrated (low-power) GPU. Type: boolean. Default: `false`. * `preferred_graphics_backend` — The preferred graphics backend (Windows). Type: string or null. Default: `null`. Options: `"dx12"`, `"vulkan"`, `"gl"`, `"metal"`, `null`. * `linux_selection_clipboard` — Whether the Linux primary selection clipboard is used. Type: boolean. Default: `true`. ## Text editing [Section titled “Text editing”](#text-editing) Settings that control text editing behavior in the input editor. **Section**: `[text_editing]` * `vim_mode_enabled` — Whether Vim keybindings are enabled. Type: boolean. Default: `false`. * `vim_status_bar` — Whether the Vim status bar is displayed. Type: boolean. Default: `true`. * `vim_unnamed_system_clipboard` — Whether the Vim unnamed register uses the system clipboard. Type: boolean. Default: `false`. * `autocomplete_symbols` — Whether matching symbols like brackets and quotes are auto-completed. Type: boolean. Default: `true`. ## Warp Drive [Section titled “Warp Drive”](#warp-drive) Settings for Warp Drive (shared workflows, notebooks, and prompts). **Section**: `[warp_drive]` * `enabled` — Whether Warp Drive is enabled. Type: boolean. Default: `true`. * `sorting_choice` — The sort order for items in Warp Drive. Type: string. Default: `"by_object_type"`. Options: `"by_timestamp"`, `"alphabetical_descending"`, `"alphabetical_ascending"`, `"by_object_type"`. ## Warpify [Section titled “Warpify”](#warpify) Settings for Warp features in SSH sessions and subshells. ### SSH [Section titled “SSH”](#ssh) **Section**: `[warpify.ssh]` * `enable_ssh_warpification` — Whether to enable Warp features in SSH sessions. Type: boolean. Default: `true`. * `enable_legacy_ssh_wrapper` — Whether the legacy SSH wrapper is enabled for SSH sessions. Type: boolean. Default: `true`. * `use_ssh_tmux_wrapper` — Whether to use a tmux-based wrapper for SSH warpification. Type: boolean. Default: `false`. * `ssh_extension_install_mode` — Controls SSH extension installation behavior. Type: string. Default: `"always_ask"`. Options: `"always_ask"` (always prompt before installing), `"always_install"` (auto-install and connect without prompting), `"never_install"` (fall back to legacy warpification). * `ssh_hosts_denylist` — SSH hosts that should not trigger the warpification prompt. Type: array of strings. Default: `[]`. ### Subshells [Section titled “Subshells”](#subshells) **Section**: `[warpify.subshells]` * `added_subshell_commands` — Additional regex patterns for commands that should be recognized as subshells. Type: array of strings. Default: `[]`. * `subshell_commands_denylist` — Commands that should not trigger the subshell warpification prompt. Type: array of strings. Default: `[]`. ## Workflows [Section titled “Workflows”](#workflows) Settings for workflow behavior. **Section**: `[workflows]` * `show_global_workflows_in_universal_search` — Whether to show global workflows in universal search results. Type: boolean. Default: `false`. ## Accessibility [Section titled “Accessibility”](#accessibility) Settings for screen reader support. **Section**: `[accessibility]` * `accessibility_verbosity` — The verbosity level for screen reader announcements. Type: string. Default: `"verbose"`. Options: `"verbose"` (includes help string), `"concise"` (value only). ## Account [Section titled “Account”](#account) Settings related to your Warp account. **Section**: `[account]` * `is_settings_sync_enabled` — Whether settings are synced across devices via the cloud. Type: boolean. Default: `false`. ## Cloud platform [Section titled “Cloud platform”](#cloud-platform) Settings for third-party API key integration and cloud model configuration. ### Third-party API keys [Section titled “Third-party API keys”](#third-party-api-keys) **Section**: `[cloud_platform.third_party_api_keys]` * `aws_bedrock_credentials_enabled` — Whether Warp should use your local AWS credentials for Bedrock-enabled requests. Type: boolean. Default: `false`. * `aws_bedrock_profile` — The AWS profile name to use for Bedrock credentials. Type: string. Default: `"default"`. * `aws_bedrock_auto_login` — Whether to automatically run the AWS login command when Bedrock credentials expire. Type: boolean. Default: `false`. * `aws_bedrock_auth_refresh_command` — The command to run to refresh AWS credentials for Bedrock. Type: string. Default: `"aws login"`. * `can_use_warp_credits_with_byok` — Whether Warp credits can be used even when providing your own API key. Type: boolean. Default: `false`. ## Global hotkey [Section titled “Global hotkey”](#global-hotkey) Settings for the global activation hotkey and dedicated hotkey window (Quake Mode). ### Toggle all windows [Section titled “Toggle all windows”](#toggle-all-windows) **Section**: `[global_hotkey.toggle_all_windows]` * `enabled` — Whether the hotkey that toggles visibility of all windows is enabled. Mutually exclusive with `global_hotkey.dedicated_window.enabled`. Type: boolean. Default: `false`. * `keybinding` — The keybinding for the global activation hotkey. Format: modifiers and a key joined by `-`, for example `"cmd-shift-a"` or `"alt-enter"`. Type: string or null. Default: `null`. ### Dedicated window (Quake Mode) [Section titled “Dedicated window (Quake Mode)”](#dedicated-window-quake-mode) **Section**: `[global_hotkey.dedicated_window]` * `enabled` — Whether the dedicated hotkey window is enabled. Mutually exclusive with `global_hotkey.toggle_all_windows.enabled`. Type: boolean. Default: `false`. **Section**: `[global_hotkey.dedicated_window.settings]` * `active_pin_position` — Screen edge where the hotkey window is pinned. Type: string. Options: `"top"`, `"bottom"`, `"left"`, `"right"`. * `hide_window_when_unfocused` — Whether to hide the hotkey window when it loses focus. Type: boolean. * `keybinding` — Keyboard shortcut to toggle the hotkey window. Type: string or null. * `pin_screen` — Display to pin the hotkey window to. Type: string or object or null. Options: `"primary"`, `{ external = 1 }`, `null`. Window size percentages are configured per pin position: ```toml [global_hotkey.dedicated_window] enabled = true [global_hotkey.dedicated_window.settings] active_pin_position = "top" hide_window_when_unfocused = true keybinding = "ctrl-`" [global_hotkey.dedicated_window.settings.pin_position_to_size_percentages.top] width = 100 height = 30 [global_hotkey.dedicated_window.settings.pin_position_to_size_percentages.bottom] width = 100 height = 30 [global_hotkey.dedicated_window.settings.pin_position_to_size_percentages.left] width = 40 height = 100 [global_hotkey.dedicated_window.settings.pin_position_to_size_percentages.right] width = 40 height = 100 ``` # Warpify overview > Warp support for Warpifying, or enabling Warp's features, in local or remote sessions. 1. [Subshells](/terminal/warpify/subshells/), Warp supports enabling Warp features in subshells for bash, zsh, and fish. 2. [SSH](/terminal/warpify/ssh/), Warp’s SSH extension brings the file tree, reliable completions, and native code diffs to remote macOS and Linux hosts. Legacy tmux-based Warpification is still available for clients that don’t yet ship the extension. 3. [SSH Legacy](/terminal/warpify/ssh-legacy/), Warp supports a legacy wrapper that enables Warp features in remote (SSH) sessions. ## Subshells [Section titled “Subshells”](#subshells) [![](/assets/terminal/subshells-demo.poster.jpg)](/assets/terminal/subshells-demo.mp4) ## SSH [Section titled “SSH”](#ssh) [![](/assets/terminal/subshell-ssh-demo.poster.jpg)](/assets/terminal/subshell-ssh-demo.mp4) # SSH with Warp features > Use Warp's SSH extension on remote macOS and Linux hosts to get a real file tree, reliable completions, and native code edits over SSH. Warp’s **SSH extension** brings the local Warp experience to remote macOS and Linux hosts. After you opt in on first connect, you get a real file tree backed by the remote filesystem, more reliable completions over a single multiplexed SSH connection, and a coding agent that applies edits with Warp’s native diff tool instead of falling back to `sed`. [SSH extension demo](https://www.loom.com/embed/466d88a1968842c68f66a3b66b94f146) ## What you get over SSH [Section titled “What you get over SSH”](#what-you-get-over-ssh) Once the SSH extension is installed on a remote host, the following features work the same way they do locally: * **File tree (Project Explorer)** - The left panel reflects the remote project’s structure and updates as you `cd` between directories or change files. See [File Tree](/code/code-editor/file-tree/). * **Reliable completions and autosuggestions** - Generators run in parallel over a single multiplexed connection instead of opening a new SSH session per command, so completions stop hitting the remote host’s `MaxSessions` ceiling and stop occasionally injecting errors into your blocks. * **Native file reads and code diffs** - The Agent reads files and applies edits through Warp’s built-in diff tool. Code changes show up as inline diffs you can review and approve, instead of being applied via `sed` or other shell commands. See [Code diffs](/agent-platform/local-agents/code-diffs/). * **All core terminal features** - The input editor, blocks, command history, autosuggestions, and history search behave the same as in a local session. For a full breakdown of what works over SSH and what doesn’t, see [Feature support over SSH](/code/ssh-feature-support/). ![Warp prompting to Warpify a freshly-connected SSH session.](/_astro/warpify_ssh_prompt.BustqpFn_Z20DP5r.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ## Installing the SSH extension [Section titled “Installing the SSH extension”](#installing-the-ssh-extension) On the first SSH connection to a host that doesn’t already have the SSH extension installed, Warp shows an in-block prompt with two options: * **Install Warp’s SSH extension** - Recommended. Warp downloads the matching remote server extension for the remote OS and architecture, installs it under `~/.warp/remote-server` (or `~/.warp-preview/remote-server` on Preview builds), launches it, and completes the handshake. Subsequent connections to the same host skip the prompt and reuse the installed binary. * **Continue without installing** - Skip installing the extension for this connection. The session continues without the SSH extension, so file tree, native file reads, and native code diffs are unavailable until you install. You can reconnect and install at any time. Warp never installs anything on a remote host without your explicit consent, and the install only writes under `~/.warp*/`. Note The extension binary tracks your client’s release channel. Stable Warp installs the extension under `~/.warp/remote-server`, and Preview installs it under `~/.warp-preview/remote-server`, so both channels can coexist on the same remote host. ### Managing the install prompt [Section titled “Managing the install prompt”](#managing-the-install-prompt) In the Warp app, go to **Settings** > **Warpify** to control how the prompt behaves: * **Always ask** (default) - Show the install prompt the first time you connect to each host. * **Always install** - Skip the prompt and install the extension automatically when it’s missing. * **Never install** - Skip the prompt and connect to the host without installing the SSH extension. The same setting can also be changed inline from the install prompt by selecting **Don’t ask me this again** before clicking either button. The underlying TOML key is `warpify.ssh.ssh_extension_install_mode` - see [All settings reference](/terminal/settings/all-settings/#ssh) for the full list of SSH-related settings, including `ssh_hosts_denylist` for hosts you never want to engage Warpification on. ## Legacy: tmux-based Warpification [Section titled “Legacy: tmux-based Warpification”](#legacy-tmux-based-warpification) Caution Tmux-based Warpification is a legacy alternative to the SSH extension and is being deprecated. Use the SSH extension above whenever possible. Tmux-based Warpification remains available today for clients that don’t yet ship the SSH extension (for example, Windows clients). Tmux-based Warpification is an older approach to enabling Warp features in SSH sessions. It uses [`tmux`](#why-do-i-need-tmux-on-the-remote-machine) to multiplex commands over your SSH connection and provides Blocks, completions, the input editor, and history search. ### FAQs [Section titled “FAQs”](#faqs) #### Will Warpifying a remote SSH session make changes to the remote machine? [Section titled “Will Warpifying a remote SSH session make changes to the remote machine?”](#will-warpifying-a-remote-ssh-session-make-changes-to-the-remote-machine) Only with your explicit permission. The SSH extension installs the remote server extension under `~/.warp*/remote-server`. Legacy tmux-based Warpification installs [`tmux`](#why-do-i-need-tmux-on-the-remote-machine) (a popular open source terminal multiplexer) if it isn’t already present. Both flows show you exactly what they’re going to run, and you can always decline and continue using SSH without these features. #### Why do I need `tmux` on the remote machine? [Section titled “Why do I need tmux on the remote machine?”](#why-do-i-need-tmux-on-the-remote-machine) `tmux` is only required by the legacy tmux-based Warpification path; the SSH extension does not need it. [tmux](https://github.com/tmux/tmux/wiki) is a popular open source terminal multiplexer that lets you run multiple sessions within one SSH connection. It requires minimal permissions and is widely adopted (⭐ 35k+ on GitHub). The legacy path uses [tmux Control Mode](https://github.com/tmux/tmux/wiki/Control-Mode) to run ad-hoc background tasks like autocompleting a `cd` command or populating the contents of a custom prompt. The SSH extension supersedes this by speaking a length-delimited protocol over a single SSH connection. #### Can I SSH to remote machines that I don’t want to Warpify? [Section titled “Can I SSH to remote machines that I don’t want to Warpify?”](#can-i-ssh-to-remote-machines-that-i-dont-want-to-warpify) Yes. Cancel the prompt to continue without Warp features, or add the host to the denylist (**Settings** > **Warpify** > **SSH hosts denylist**) so you’re never prompted again. #### Do I have to manually Warpify every time? [Section titled “Do I have to manually Warpify every time?”](#do-i-have-to-manually-warpify-every-time) After you successfully Warpify an SSH connection manually, Warp provides a brief script you can run to append a marker at the end of your shell’s rcfile. This lets Warp know when your remote shell is ready to be Warpified. Place the snippet at the bottom of your rcfile for the best results. ![Setting up Auto-Warpify](/_astro/warpify_ssh_auto_script.X-APJAYD_25jCTB.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) #### What shells and operating systems are supported? [Section titled “What shells and operating systems are supported?”](#what-shells-and-operating-systems-are-supported) Warp supports macOS and most flavors of Linux as remote hosts on both the SSH extension and legacy tmux-based Warpification. Supported shells are `bash` and `zsh`. Windows remote hosts are not yet supported. #### What if Warp fails to detect my SSH session? [Section titled “What if Warp fails to detect my SSH session?”](#what-if-warp-fails-to-detect-my-ssh-session) If you’re in a remote SSH session and Warp didn’t detect it, you can manually Warpify by opening the [Command Palette](/terminal/command-palette/) and searching for “Warpify SSH Session”. #### What triggers SSH session detection for Warpification? [Section titled “What triggers SSH session detection for Warpification?”](#what-triggers-ssh-session-detection-for-warpification) With SSH session detection enabled, Warp watches for `ssh` commands whose arguments suggest an interactive session. If you’ve aliased `ssh` or are running it as part of a script, Warp won’t perform SSH session detection. Once Warp is confident you’ve successfully authenticated (by detecting `Last login:` or something resembling a basic prompt), it prompts you to Warpify the active SSH session. If SSH session detection doesn’t pick up your session, you can still [Warpify manually](#what-if-warp-fails-to-detect-my-ssh-session). # Legacy SSH wrapper > Legacy SSH wrapper that bootstraps Warp features on remote machines without tmux. Note If you are looking to troubleshoot the tmux SSH feature, see the [SSH](/terminal/warpify/ssh/). When you SSH into a remote box, you get all the features of Warp without any configuration on your part. The input editor, auto-completions, and history search work the same, regardless of machine. Caution [Limitations of SSH](https://github.com/warpdotdev/Warp/issues/578) (as of May 2024): * The SSH Wrapper only supports `bash` or `zsh` shells in remote sessions. * If you’re using a different shell, you’ll want to use `command ssh` directly (see below for more details). * For zsh, xxd is required to bootstrap warp. * For Windows, [Cygwin](https://www.cygwin.com/) is required to bootstrap the SSH Wrapper. * RemoteCommand causes the ssh wrapper to fail. * [Tmux is not currently supported.](https://github.com/warpdotdev/Warp/discussions/501) Note If you’re using zsh on the remote host, Warp creates a temp folder to act as the ZDOTDIR during the bootstrapping process and removes it when the shell is set up. ![SSH](/_astro/ssh-1.Ba7RzgnH_Z1ooVYW.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) ## Implementation [Section titled “Implementation”](#implementation) We create a wrapper (around `/usr/bin/ssh`) to set up the shell for Warp’s feature set. We authenticate normally using `/usr/bin/ssh`, and bootstrap the remote shell to work with Warp Blocks and the Input Editor. You can opt out of this functionality by invoking `command ssh` directly. * Warp takes over the prompt which enables us to build a modern input editor. * Warp configures histcontrol to ignore commands with leading spaces. We do this so our bootstrapping code does not clutter the history. You can see the SSH wrapper by using `which warp_ssh_helper` in zsh, `type warp_ssh_helper` in bash. *Note:* The ssh wrapper is only *initialized* on your local machine. We don’t currently support bootstrapping nested ssh sessions. Note Warp [Completions](/terminal/command-completions/completions/) for ssh show entries in `~/.ssh/config` and `~/.ssh/known_hosts` ## Troubleshooting SSH [Section titled “Troubleshooting SSH”](#troubleshooting-ssh) ### channel 2: open failed: connect failed: open failed [Section titled “channel 2: open failed: connect failed: open failed”](#channel-2-open-failed-connect-failed-open-failed) If you’re seeing these errors, you may have some config on your server (usually in `/etc/ssh/sshd_config`) preventing Warp’s ControlMaster connection from working. In this state, completions that require information from your remote host won’t work and your history also won’t work. You should ensure that `MaxSessions` is either commented out or is at least `2`. Write access in `/etc/ssh/` typically requires sudo access. After any edits, you’d also need to restart the `sshd` daemon. ### SSH Wrapper fails [Section titled “SSH Wrapper fails”](#ssh-wrapper-fails) There are several [known issues with SSH Wrapper](https://github.com/warpdotdev/Warp/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-desc+label%3ABugs+label%3ASSH). As a workaround to the SSH Wrapper, you can add `command ssh` to your **Settings** > **Warpify** > **Subshells** > **Added commands**, then run `command ssh <user@server>` to connect to a remote session, this will attempt to enable Warp features as a [subshell](/terminal/warpify/subshells/). Note If the subshell workaround helps, we recommend you disable the SSH Wrapper in **Settings** > **Features** > **Session**. You’ll need to start a new session before a change is reflected or try invoking the SSH binary directly with `command ssh`. [![](/assets/terminal/subshell-ssh-demo.poster.jpg)](/assets/terminal/subshell-ssh-demo.mp4) # Warpify subshells > Warpify subshells in bash, zsh, and fish to get Warp features in nested sessions. ## What is a subshell? [Section titled “What is a subshell?”](#what-is-a-subshell) Within the context of Warp, a “subshell” is defined as any nested interactive shell session that’s spawned and running within the context of an existing, running shell. This can be a nested session running locally on your machine, a shell session running within a Docker container, or a remote server accessed through SSH. [See more on SSH Warpification](/terminal/warpify/ssh/). Note that Warp’s definition of a subshell differs from the more common definition of a Unix subshell, which typically refers to any shell process spawned as a child of the interactive shell. For example, in bash, a command wrapped in parentheses is executed in a subshell with its own PID and addressable memory space. ## How to Warpify the subshell [Section titled “How to Warpify the subshell”](#how-to-warpify-the-subshell) By default, Warp automatically recognizes the following commands as **subshell-compatible**: * bash, fish, zsh * docker exec * gcloud compute ssh * eb ssh * poetry shell When you run a command that’s subshell-compatible, Warp will prompt you and invite you to “Warpify” the subshell which makes all of the modern IDE features of Warp available in that subshell. The list of subshell-compatible commands is configurable in Subshell settings as described [below](/terminal/warpify/subshells/#configuring-subshell-compatible-commands). Note bash, zsh, or fish (3.6 or above) must be set as the default shell within containers and ssh sessions for the Warpification of the subshells to work. [![](/assets/terminal/subshells-demo.poster.jpg)](/assets/terminal/subshells-demo.mp4) ### Configuring subshell-compatible commands [Section titled “Configuring subshell-compatible commands”](#configuring-subshell-compatible-commands) To configure subshell-compatible commands, navigate to **Settings** > **Warpify** > **Subshells**. #### Adding compatible commands [Section titled “Adding compatible commands”](#adding-compatible-commands) You can add any command that spawns a bash, fish, or zsh subshell to ‘Added commands’ to make it eligible for “Warpification.” Furthermore, you can add regular expressions to the Added commands list. Any commands that match an added regex will be eligible for “Warpification.” #### Blocklisting commands [Section titled “Blocklisting commands”](#blocklisting-commands) Some types of subshells are not compatible, and you may also want to control Warp so it never invites you to “Warpify” the subshells for specific commands. When you add commands to the Blocklist, Warp will never invite you to “Warpify” subshells spawned by those commands. ### Automatically “Warpify” subshells [Section titled “Automatically “Warpify” subshells”](#automatically-warpify-subshells) To remember your preferences for a command and bypass the confirmation banner, you can manually paste the appropriate snippet to the end of the RC file corresponding to your subshell (bash, fish, or zsh). ```bash # For zsh subshells, add to ~/.zshrc. printf '\eP$f{"hook": "SourcedRcFileForWarp", "value": { "shell": "zsh"}}\x9c' # For bash subshells, add to ~/.bashrc or ~/.bash_profile. printf '\eP$f{"hook": "SourcedRcFileForWarp", "value": { "shell": "bash"}}\x9c' # For fish subshells, add to ~/.config/fish/config.fish. if status is-interactive printf '\eP$f{"hook": "SourcedRcFileForWarp", "value": { "shell": "fish"}}\x9c' end ``` Once added, Warp will automatically “Warpify” subsequent subshell sessions for the corresponding shell on the machine with the newly updated RC file. Under the hood, this snippet prints a Device Control String ([DCS](https://vt100.net/docs/vt510-rm/chapter4.html)) to be read by Warp, signaling that a subshell session has started and is ready to be “Warpified.” In turn, Warp executes a setup script in the session that enables the full suite of Warp features like blocks, completions, and the input editor. For this reason, it’s best to ensure the snippet is added to the end of the RC file, so Warp does not attempt to execute the setup script before the shell has finished sourcing your RC file. To disable automatic integration, remove the snippet from the corresponding RC file. If you encounter issues in subshell sessions where the RC file is sourced, [file a GitHub issue](https://github.com/warpdotdev/Warp/issues/new/choose). ## Background commands [Section titled “Background commands”](#background-commands) Warp runs background commands to power useful features like completions, syntax highlighting, and command corrections. For example, to provide completions for git checkout, Warp runs a background command that lists all git branches in the current repo. In local subshell sessions, these commands are run in forked shell processes, isolated from your interactive shell session. This is the same implementation used for any non-subshell session. In remote sessions, however, Warp takes a different approach – while a forked shell process is running on your local machine (where the Warp app is running), your remote session might be running on a server elsewhere. In these cases, Warp takes advantage of the session’s “idle time” – when no command is currently running – to run background commands directly in the session itself. These commands are executed in a non-interactive subshell process to prevent modifications to the session state (they cannot modify an environment variable, for instance). ### Show/hide background blocks [Section titled “Show/hide background blocks”](#showhide-background-blocks) By default, blocks for background commands are hidden. To show background command blocks, select ‘Show background blocks’ in the ‘Blocks’ menu of the macOS menu bar. ### Disable background commands in remote sessions [Section titled “Disable background commands in remote sessions”](#disable-background-commands-in-remote-sessions) We understand that some developers may want to disable background commands for certain or all environments. To disable background commands in remote subshell sessions, you can execute the following command in a top-level terminal session: * macOS Update the settings defaults located in `dev.warp.Warp-Stable` to include the following name-value pair: `"DisableInBandCommands": "true"`. ```bash defaults update dev.warp.Warp-Stable DisableInBandCommands true ``` * Windows Update the settings registry located at `HKCU:\Software\Warp.dev\Warp` to include the following name-value pair: `"DisableInBandCommands": "true"`. ```powershell Set-ItemProperty -Path "HKCU:\SOFTWARE\Warp.dev\Warp" -Name DisableInBandCommands -Value true ``` * Linux Update the settings file located at `~/.config/warp-terminal/user_preferences.json` to include the following name-value pair: `"DisableInBandCommands": "true"`. ```bash cd ~/.config/warp-terminal/ jq '.prefs += {"DisableInBandCommands": "true"}' user_preferences.json > tmp.json && mv tmp.json user_preferences.json ``` This will effectively disable tab completions, syntax highlighting, command corrections, and the git status prompt indicator in remote subshells. # Windows and tabs overview > Manage Warp windows, tabs, vertical tabs, split panes, and tab configurations with global hotkeys and reusable layouts. 1. [Tabs](/terminal/windows/tabs/) allow you to organize a window into multiple terminal sessions. 2. [Vertical Tabs](/terminal/windows/vertical-tabs/) replace the horizontal tab bar with a sidebar that shows rich metadata and drag-and-drop management for every tab and pane. 3. [Split Panes](/terminal/windows/split-panes/) allows you to divide a Tab into multiple rectangular *panes*, each of which is a unique terminal session. 4. [Tab Configs](/terminal/windows/tab-configs/) let you define reusable tab setups in a simple TOML file 5. [Global Hotkey](/terminal/windows/global-hotkey/) is a configurable shortcut that can show/hide a dedicated window or all windows on your chosen desktop regardless of whether the app is focused. 6. [Launch Configurations (Legacy)](/terminal/sessions/launch-configurations/) support saving a configuration of windows, tabs, and panes to open later. ## Tabs [Section titled “Tabs”](#tabs) [Tabs Demo](https://www.loom.com/embed/84d15cc7eb5a4a668bb86be9e827f261) ## Split Panes [Section titled “Split Panes”](#split-panes) [Split Panes Demo](https://www.loom.com/embed/c1104b51cab848a9bef6792ec4fd8421) ## Global Hotkey [Section titled “Global Hotkey”](#global-hotkey) [![](/assets/terminal/Dedicated-Window.poster.jpg)](/assets/terminal/Dedicated-Window.mp4) [![](/assets/terminal/Show-Hide-All-Windows.poster.jpg)](/assets/terminal/Show-Hide-All-Windows.mp4) # Configurable toolbar > Reorder, hide, and move panel toggle buttons between the left and right sides of Warp's header toolbar to match your workflow. The header toolbar holds the panel toggle buttons for the tabs panel, tools panel, agent management, Code Review, and notifications mailbox. Instead of a fixed layout, you can rearrange these buttons, move them between the left and right sides of the header, or hide the ones you don’t use. The side a button lives on also determines which side of the window its panel opens on, so you can tune Warp’s layout to match how you work. The configurable toolbar works with both [horizontal tabs](/terminal/windows/tabs/) and [vertical tabs](/terminal/windows/vertical-tabs/). [Configurable toolbar demo](https://www.loom.com/embed/292d126ecf7148f296fc8685e451790f) ## Key features [Section titled “Key features”](#key-features) * **Reorder items within a side** - Drag toolbar chips to change the left-to-right order on either side of the header. * **Move items across sides** - Drag a chip between the left and right drop zones to move its button (and the panel it opens) to the other side of the window. * **Hide items you don’t need** - Remove a chip from both sides to hide the button. Removed items become available again, so you can drop them back in later. * **Side placement drives panel side** - Moving the tools panel, tabs panel, or code review button flips the corresponding panel to open from the same side, with resize handles, borders, and anchored popups following along. * **Persistent across sessions** - Your layout is saved to settings and survives app restarts. ## Configurable items [Section titled “Configurable items”](#configurable-items) The following header buttons can be rearranged or hidden: * **Tabs panel** - Toggles the [vertical tabs](/terminal/windows/vertical-tabs/) sidebar. * **Tools panel** - Toggles the panel that contains the project explorer, global search, [Warp Drive](/knowledge-and-collaboration/warp-drive/), and conversation history. * **Agent management** - Toggles the agent management view for [cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/). * **Code review** - Toggles the [Code Review](/code/code-review/) panel. * **Notifications mailbox** - Toggles the [agent notifications](/agent-platform/capabilities/agent-notifications/) mailbox. The search bar and profile avatar are fixed and can’t be repositioned. An item only appears in the toolbar when its prerequisites are met. For example, the tabs panel button requires [vertical tabs](/terminal/windows/vertical-tabs/) to be enabled, and agent management requires Agent Mode to be enabled. If an item’s prerequisite becomes unavailable later, the button disappears but your saved layout is preserved, so the button reappears once the prerequisite is met again. ## Default layout [Section titled “Default layout”](#default-layout) The default layout matches Warp’s standard header: * **Left** - Tabs panel, tools panel, agent management. * **Right** - Code review, notifications mailbox. ## Editing the toolbar [Section titled “Editing the toolbar”](#editing-the-toolbar) You can open the toolbar editor from the header or from Settings. ### From the header [Section titled “From the header”](#from-the-header) Right-click any toolbar button (or any empty space between the buttons and the search bar) and select **Rearrange toolbar items**. The configurator modal opens. ### From Settings [Section titled “From Settings”](#from-settings) 1. In the Warp app, navigate to **Settings** > **Appearance** > **Tabs**. 2. Click **Edit toolbar**. ## How side placement affects panels [Section titled “How side placement affects panels”](#how-side-placement-affects-panels) Moving a button to the opposite side also moves where its panel opens, and Warp flips associated UI to stay readable: * **Tabs panel** - Opens its sidebar on whichever side its button sits. The hover detail sidecar, action buttons, and right-click menu flip to face the center of the screen. * **Tools panel** - Opens on the side its button sits. Warp Drive hover previews, kebab menus, and dialogs flip toward the center. The resize handle and border switch to the edge facing the main content. * **Code review** - Opens on the side its button sits, with a matching resize handle. * **Agent management** - Replaces the main content area when opened, so side placement only affects the button’s position, not where the view renders. * **Notifications mailbox** - The popover anchors under its button, and notification toasts appear on the same side as the mailbox button. When multiple panels are open on the same side, they render in the order their buttons appear in the toolbar. For example, if the left-side order is code review, tabs panel, tools panel, the panels open in that same order from left to right, with the main content to their right. ## Related pages [Section titled “Related pages”](#related-pages) * [Vertical tabs](/terminal/windows/vertical-tabs/) - The sidebar toggled by the tabs panel button. * [Code Review panel](/code/code-review/) - The panel toggled by the code review button. * [Agent notifications](/agent-platform/capabilities/agent-notifications/) - The mailbox toggled by the notifications button. * [Managing cloud agents](/agent-platform/cloud-agents/managing-cloud-agents/) - The view toggled by the agent management button. * [Warp Drive](/knowledge-and-collaboration/warp-drive/) - One of the views available in the tools panel. # Global Hotkey > Show or hide Warp instantly with a global hotkey, including a dedicated Quake-style drop-down window. Note On macOS, [system keyboard shortcuts](https://support.apple.com/en-us/HT201236) like `CMD-ESC`, `CMD-BACKTICK`, `CMD-TAB`, `CMD-PERIOD`, and `CMD-TILDE` need to be [unbound](https://support.apple.com/guide/mac-help/keyboard-shortcuts-mchlp2262/mac) before you can use them in Warp. Caution On Linux, the Global Hotkey may not work for some X11 window managers that do not implement [Extended Window Manager Hints](https://en.wikipedia.org/wiki/Extended_Window_Manager_Hints). Some examples include: [sowm](https://github.com/dylanaraps/sowm), [catwm](https://github.com/pyknite/catwm), [Fvwm](https://www.fvwm.org/), [dwm](https://dwm.suckless.org/), [2bWM](https://github.com/venam/2bwm), [monsterwm](https://github.com/c00kiemon5ter/monsterwm), [TinyWM](https://github.com/mackstann/tinywm), [x11fs](https://github.com/sdhand/x11fs), [XMonad](https://xmonad.org/) ## How to access it [Section titled “How to access it”](#how-to-access-it) ### Dedicated window [Section titled “Dedicated window”](#dedicated-window) Dedicated Window allows you to customize the windows’ pinned position and its width and height ratio relative to your active screen size (also known as Quake Mode). 1. Open **Settings** > **Features** > **Keys** and select “Dedicated hotkey window” from the Global Hotkey dropdown to enable the feature. 2. Configure the keybinding, the windows position, screen, and relative size or uncheck “Autohides on the loss of keyboard focus” which will cause the dedicated Hotkey Window to stay on top when triggered regardless of mouse or keyboard focus. Caution On Linux and Windows, Warp does not support the “Autohides on the loss of keyboard focus” feature. ### Show/hide all windows [Section titled “Show/hide all windows”](#showhide-all-windows) Show/Hide All Windows allows you to configure a shortcut to show/hide all Warp windows. 1. Open **Settings** > **Features** > **Keys** and select “Show/hide all windows” from the Global Hotkey dropdown to enable the feature. 2. Configure your preferred keybinding. Caution On Linux, hidden windows may not appear in your `ALT-TAB` window switcher menu. Furthermore, the ordering of windows beyond the top window may change after toggling. ## How it works [Section titled “How it works”](#how-it-works) [![](/assets/terminal/Dedicated-Window.poster.jpg)](/assets/terminal/Dedicated-Window.mp4) [![](/assets/terminal/Show-Hide-All-Windows.poster.jpg)](/assets/terminal/Show-Hide-All-Windows.mp4) ## Troubleshooting hotkey dedicated window [Section titled “Troubleshooting hotkey dedicated window”](#troubleshooting-hotkey-dedicated-window) Review platform-specific instructions for troubleshooting the global hotkey below * macOS If the keybinding doesn’t work, check under `System Preferences > Security & Privacy > Accessibility` and tick the checkbox to grant Warp access. * Windows On Windows, there are no known issues with Global Hotkey Dedicated Window. If you find an issue, please [send feedback](/support-and-community/troubleshooting-and-support/sending-us-feedback/) to let us know. * Linux The hotkey window may appear on the incorrect monitor under certain window sizes. For example, with GNOME, if the hotkey window is supposed to show on a monitor having the taskbar (GNOME Panel), and the window height is 100%, causing an overlap, the hotkey window may fallback to showing on an external monitor if you have one. Try working around this by setting a window height to a lesser percentage, e.g. 90%. # Split panes > The split panes feature allows you to divide a tab into multiple rectangular panes, each of which is a unique terminal session. ## How to use split panes [Section titled “How to use split panes”](#how-to-use-split-panes) * macOS * Split panes to the right / down with `CMD-D` / `SHIFT-CMD-D` or in any direction by right-clicking on any Pane. * Activate the Previous / Next Pane with `CMD-[` / `CMD-]` or by clicking a pane. * Navigate among split panes with `OPT-CMD-ARROW`, the active pane will be marked with a triangle in the top corner. * Toggle Maximize Pane with `CMD-SHIFT-ENTER`. * Close the active Pane with `CMD-W`. * You can also drag and drop panes. Click and drag a Pane’s header around a given tab, drag the Pane to the tab bar to move it to another Tab, or make it into a Tab. * Windows * Split Panes to the right / down with `CTRL-SHIFT-D` / `CTRL-SHIFT-E` or in any direction by right-clicking on any Pane. * Activate the Previous / Next Pane with `CTRL-SHIFT-{` / `CTRL-SHIFT-}` or by clicking a pane. * Navigate among Split Panes with `CTRL-ALT-ARROW`, the active pane will be marked with a triangle in the top corner. * Toggle Maximize Pane with `CTRL-SHIFT-ENTER`. * Close the active Pane with `CTRL-SHIFT-W`. * You can also drag and drop panes. Click and drag a Pane’s header around a given tab, drag the Pane to the tab bar to move it to another Tab, or make it into a Tab. * Linux * Split Panes to the right / down with `CTRL-SHIFT-D` / `CTRL-SHIFT-E` or in any direction by right-clicking on any Pane. * Activate the Previous / Next Pane with `CTRL-SHIFT-{` / `CTRL-SHIFT-}` or by clicking a pane. * Navigate among Split Panes with `CTRL-ALT-ARROW`, the active pane will be marked with a triangle in the top corner. * Toggle Maximize Pane with `CTRL-SHIFT-ENTER`. * Close the active Pane with `CTRL-SHIFT-W`. * You can also drag and drop panes. Click and drag a Pane’s header around a given tab, drag the Pane to the tab bar to move it to another Tab, or make it into a Tab. Note You can quickly find all the **pane** shortcuts by using the [Command Palette](/terminal/command-palette/). You can also remap the shortcuts to your liking. See [Custom Keyboard Shortcuts](/getting-started/keyboard-shortcuts/#custom-keyboard-shortcuts) for more details. ### CTRL-TAB behavior [Section titled “CTRL-TAB behavior”](#ctrl-tab-behavior) `CTRL-TAB` shortcut defaults to activate the previous / next [Tabs](/terminal/windows/tabs/). You can configure the shortcut to cycle the most recent session, including any split panes, in **Settings** > **Features** > **Keys** > **Ctrl-Tab behavior** ## How split panes work [Section titled “How split panes work”](#how-split-panes-work) [Split Panes Demo](https://www.loom.com/embed/c1104b51cab848a9bef6792ec4fd8421) [![](/assets/terminal/split-panes-dragging-demo.poster.jpg)](/assets/terminal/split-panes-dragging-demo.mp4) # Tab Configs > Tab Configs let you define reusable tab setups — including directory, startup commands, pane layout, shell, and theme — in a simple TOML file. Tab Configs let you define reusable tab setups — including directory, startup commands, pane layout, shell, and theme — in a simple TOML file. Select a Tab Config from the `+` menu to open a fully configured tab with a single click. ## How Tab Configs work [Section titled “How Tab Configs work”](#how-tab-configs-work) Each Tab Config is a `.toml` file stored in `~/.warp/tab_configs/`. Every file defines a single tab layout with optional pane splits, startup commands, and parameterized inputs. Tab Configs appear in the `+` menu alongside your existing tabs, so you can launch a preconfigured workspace instantly. ## Creating a Tab Config [Section titled “Creating a Tab Config”](#creating-a-tab-config) ### From the UI [Section titled “From the UI”](#from-the-ui) 1. Click the **+** button in the tab bar to open the new-tab menu. 2. Click **+ New tab config**. Warp creates a new `.toml` file in `~/.warp/tab_configs/` and opens it for editing. ### Manually [Section titled “Manually”](#manually) 1. Create a new `.toml` file in `~/.warp/tab_configs/`. Use snake\_case for the file name (e.g., `dev_server.toml`). 2. Define the tab layout using the schema below, then save the file. The new config appears in the `+` menu automatically. ### Save an existing tab as a Tab Config [Section titled “Save an existing tab as a Tab Config”](#save-an-existing-tab-as-a-tab-config) You can also capture a tab’s current state as a reusable Tab Config without writing TOML. Right-click any tab in the [vertical tabs](/terminal/windows/vertical-tabs/) panel or horizontal tab bar to open the context menu, then click **Save as new config**. Warp generates a `.toml` file from the tab’s layout, commands, and directory and adds it to the `+` menu. ![Tab context menu in Warp's vertical tabs panel with Save as new config highlighted](/_astro/save-new-tab-config.Dsmhq0Di_Z6Qgvd.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Saving a tab config. ## Managing Tab Configs [Section titled “Managing Tab Configs”](#managing-tab-configs) Saved Tab Configs appear in the `+` menu for quick access. When you hover a Tab Config in the menu, a **sidecar panel** appears alongside it with options to: * **Edit config** — Open the underlying `.toml` file for manual editing. The editor also shows a footer to invoke the **update tab config** skill, so you can describe changes in natural language and have Warp’s agent apply them. * **Remove** — Remove the Tab Config from the `+` menu. * **Make default** — Assign the Tab Config as the default `Cmd T` action for new tabs. ![Warp's + menu open with a saved screenshots\_tab\_config entry highlighted, and a sidecar panel showing Make default, Edit config, and Remove action buttons](/_astro/saved-tab-config-menu.DEhwYYBm_1kkNMq.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Tab config menu with sidecar options. ## Using skills to manage Tab Configs [Section titled “Using skills to manage Tab Configs”](#using-skills-to-manage-tab-configs) Warp includes built-in skills for creating and modifying Tab Configs through natural language: * **Create Tab Config** — Generate a new Tab Config from a description (e.g., “create a 2x2 grid with one pane running my dev server”). * **Update Tab Config** — Modify an existing Tab Config by describing the changes you want. To use these skills, type `/skills` in Agent Mode and select the tab config skill, or use the footer that appears when editing a Tab Config file. ## Tab Config TOML schema [Section titled “Tab Config TOML schema”](#tab-config-toml-schema) ### Top-level fields [Section titled “Top-level fields”](#top-level-fields) * **`name`** (required, string) — display name shown in the `+` menu. * **`title`** (optional, string) — custom tab title. Supports `{{param}}` template variables. * **`color`** (optional, string) — tab color. One of: `"black"`, `"red"`, `"green"`, `"yellow"`, `"blue"`, `"magenta"`, `"cyan"`, `"white"`. Actual color values are derived from your Warp [Theme](/terminal/appearance/themes/). ### Pane list [Section titled “Pane list”](#pane-list) All panes are defined in a flat `[[panes]]` array. The first entry is the root of the pane tree. Each entry is either a **split node** (branch) or a **leaf node**. #### Leaf node fields [Section titled “Leaf node fields”](#leaf-node-fields) * **`id`** (required, string) — unique identifier for this pane. Use descriptive names like `"editor"` or `"server"`. * **`type`** (required, string) — `"terminal"` (standard shell), `"agent"` (opens in Agent Mode), or `"cloud"` (cloud mode pane, no local shell). * **`directory`** (optional, string) — initial working directory. Supports `~` expansion and `{{param}}` template variables. * **`commands`** (optional, array of strings) — commands to run in sequence when the tab opens. * **`shell`** (optional, string) — shell executable to use for this pane (e.g. `"pwsh"`, `"zsh"`, `"bash"`, `"fish"`). Only applies to `terminal` and `agent` pane types. If omitted or the specified shell is not installed, the user’s default shell is used. * **`is_focused`** (optional, bool) — set to `true` on at most one pane to give it initial focus. #### Split node fields [Section titled “Split node fields”](#split-node-fields) * **`id`** (required, string) — unique identifier for this split. * **`split`** (required, string) — `"horizontal"` (children arranged left-to-right) or `"vertical"` (children arranged top-to-bottom). * **`children`** (required, array of strings) — ordered list of child pane `id` values. Must contain at least 2 entries. Order determines visual order. Note All children within a split are equally sized. There are no flex or proportion values. ### Parameters [Section titled “Parameters”](#parameters) Parameters let users fill in values at open time via a modal prompt. Declare them with `[params.<name>]` tables and reference them in `directory`, `commands`, and `title` using `{{name}}` syntax. Each parameter has: * **`type`** (optional, string) — `"text"` (default, freeform input), `"branch"` (Git branch picker), or `"repo"` (repository picker). * **`description`** (optional, string) — label shown in the fill-in UI. * **`default`** (optional, string) — default value. `{{autogenerated_branch_name}}` is a reserved template variable. If a Tab Config references it, Warp generates a unique worktree branch name on each open instead of prompting the user. ## Examples [Section titled “Examples”](#examples) ### Single pane [Section titled “Single pane”](#single-pane) A simple config that opens a terminal in a project directory and starts a dev server: ```toml name = "Dev Server" [[panes]] id = "main" type = "terminal" directory = "~/code/my-app" commands = ["npm run dev"] ``` ### Two panes side by side [Section titled “Two panes side by side”](#two-panes-side-by-side) An editor and server running in parallel, with the editor focused: ```toml name = "Editor + Server" color = "green" [[panes]] id = "root" split = "horizontal" children = ["editor", "server"] [[panes]] id = "editor" type = "terminal" directory = "~/code/my-app" commands = ["nvim ."] is_focused = true [[panes]] id = "server" type = "terminal" directory = "~/code/my-app" commands = ["npm run dev"] ``` ### Cross-shell development [Section titled “Cross-shell development”](#cross-shell-development) A config that opens two panes side by side, each with a different shell: ```toml name = "Cross Shell" color = "cyan" [[panes]] id = "root" split = "horizontal" children = ["bash_pane", "pwsh_pane"] [[panes]] id = "bash_pane" type = "terminal" shell = "bash" directory = "~/code/my-app" is_focused = true [[panes]] id = "pwsh_pane" type = "terminal" shell = "pwsh" directory = "~/code/my-app" ``` ### Worktree with parameters [Section titled “Worktree with parameters”](#worktree-with-parameters) A parameterized config that creates a new Git worktree on open: ```toml name = "New Worktree" title = "{{branch_name}}" [[panes]] id = "main" type = "terminal" directory = "{{repo}}" commands = [ "git worktree add -b {{branch_name}} ../{{branch_name}} {{base_branch}}", "cd ../{{branch_name}}", ] [params.repo] type = "repo" description = "Repository path" [params.base_branch] type = "branch" description = "Base branch to branch from" [params.branch_name] type = "text" description = "New branch name" default = "my-feature" ``` ### Quick worktree setup [Section titled “Quick worktree setup”](#quick-worktree-setup) You can also create a worktree-based Tab Config directly from the `+` menu by clicking **New worktree config** and selecting the repo you want your worktree to be from. Warp generates the Tab Config automatically and saves it for future use. ## Related pages [Section titled “Related pages”](#related-pages) * [Launch Configurations (Legacy)](/terminal/sessions/launch-configurations/) — the previous session configuration format. Existing configs still work, but Tab Configs are the recommended approach for new setups. * [Tabs](/terminal/windows/tabs/) — tab management, keyboard shortcuts, and behavior settings * [Themes](/terminal/appearance/themes/) — customize the colors used by tab color settings * [Working Directory](/terminal/more-features/working-directory/) — how Warp resolves working directories * [Third-Party CLI Agents](/agent-platform/cli-agents/overview/) — use the `"agent"` pane type to open tabs in Agent Mode # Tabs > Organize your window into multiple terminal sessions with customizable tabs, complete with titles and ANSI colors. Note New Tabs will default to the active Tabs’ current [Working Directory](/terminal/more-features/working-directory/) and the actual color values will be automatically derived from your Warp [Theme](/terminal/appearance/themes/). ## How to use Tabs [Section titled “How to use Tabs”](#how-to-use-tabs) * macOS * Right-click on the new Tab button `+` to make a new tab, restore closed tab, or run a saved [Launch Configuration](/terminal/sessions/launch-configurations/). * Open a new Tab with `CMD-T` or by clicking on the `+` in the top bar. * Close the current Tab with `CMD-W` or by clicking on the `X` on hover over a Tab. * Reopen closed tabs with `SHIFT-CMD-T`. * Move a Tab to the Left / Right with `CTRL-SHIFT-LEFT` / `CTRL-SHIFT-RIGHT` or by clicking and dragging a Tab. * Activate the Previous / Next Tab with `SHIFT-CMD-{` / `SHIFT-CMD-}` or by clicking a Tab. * Activate the first through eighth Tabs with `CMD-1` thru `CMD-8`. * Switch to the last Tab with `CMD-9`. * Double-click a Tab to rename it. * Right-clicking on a Tab reveals more options you can explore within the [Command Palette](/terminal/command-palette/) or [Keyboard Shortcuts](/getting-started/keyboard-shortcuts/#fundamentals). * Windows * Right-click on the new Tab button `+` to make a new tab, restore closed tab, or run a saved [Launch Configuration](/terminal/sessions/launch-configurations/). * Open a new Tab with `CTRL-SHIFT-T` or by clicking on the `+` in the top bar. * Close the current Tab with `CTRL-SHIFT-W` or by clicking on the `x` on hover over a Tab. * Reopen closed tabs with `CTRL-ALT-T`. * Move a Tab to the Left / Right with `CTRL-SHIFT-LEFT` / `CTRL-SHIFT-RIGHT` or by clicking and dragging a Tab. * Activate the Previous / Next Tab with `CTRL-PGUP` / `CTRL-PGDN` or by clicking a Tab. * Activate the first through eighth Tabs with `CTRL-1` thru `CTRL-8`. * Switch to the last Tab with `CTRL-9`. * Double-click a Tab to rename it. * Right-clicking on a Tab reveals more options you can explore within the [Command Palette](/terminal/command-palette/) or [Keyboard Shortcuts](/getting-started/keyboard-shortcuts/#fundamentals). * Linux * Right-click on the new Tab button `+` to make a new tab, restore closed tab, or run a saved [Launch Configuration](/terminal/sessions/launch-configurations/). * Open a new Tab with `CTRL-SHIFT-T` or by clicking on the `+` in the top bar. * Close the current Tab with `CTRL-SHIFT-W` or by clicking on the `x` on hover over a Tab. * Reopen closed tabs with `CTRL-ALT-T`. * Move a Tab to the Left / Right with `CTRL-SHIFT-LEFT` / `CTRL-SHIFT-RIGHT` or by clicking and dragging a Tab. * Activate the Previous / Next Tab with `CTRL-PGUP` / `CTRL-PGDN` or by clicking a Tab. * Activate the first through eighth Tabs with `CTRL-1` thru `CTRL-8`. * Switch to the last Tab with `CTRL-9`. * Double-click a Tab to rename it. * Right-clicking on a Tab reveals more options you can explore within the [Command Palette](/terminal/command-palette/) or [Keyboard Shortcuts](/getting-started/keyboard-shortcuts/#fundamentals). Tip **Terminal Tip**\ Using your `.zshrc` or `.bashrc` files on macOS or Linux, you can set a new Tab name: ```bash # Set name, where MyTabName would be whatever you want to see in the Tab ( either a fixed string, $PWD, or something else ) function set_name () { export WARP_DISABLE_AUTO_TITLE=true echo -ne "\033]0;MyTabName\007" } # Add the function to the environment variable in either Zsh or Bash if [ -n "$ZSH_VERSION" ]; then preexec_functions+=(set_name) elif [ -n "$BASH_VERSION" ]; then PROMPT_COMMAND='set_name' fi ``` Learn more about Tab names [here](https://learn.microsoft.com/en-us/windows/terminal/tutorials/tab-title#set-the-shells-title). ### Tab Restoration [Section titled “Tab Restoration”](#tab-restoration) Tab Restoration enables you to reopen recently closed tabs for up to 60 seconds. Configure this feature in **Settings** > **Features** > **Session** > **Enable reopening of closed sessions** ### CTRL-TAB Behavior [Section titled “CTRL-TAB Behavior”](#ctrl-tab-behavior) `CTRL-TAB` shortcut defaults to activate the previous / next Tab. You can configure the shortcut to cycle the most recent session, including any [Split Panes](/terminal/windows/split-panes/), in **Settings** > **Features** > **Keys** > **Ctrl-Tab behavior** ### Tabs Behavior [Section titled “Tabs Behavior”](#tabs-behavior) Please see our [Appearance > Tabs Behavior](/terminal/appearance/tabs-behavior/) docs for more Tab related settings. ### How Tabs work [Section titled “How Tabs work”](#how-tabs-work) [Tabs Demo](https://www.loom.com/embed/84d15cc7eb5a4a668bb86be9e827f261) # Vertical Tabs > The vertical tabs panel replaces the horizontal tab bar with a sidebar showing rich metadata, drag-and-drop management, and display options for tabs and panes. The vertical tabs panel is a sidebar that replaces the traditional horizontal tab bar with a richer, more powerful tab management surface. Instead of a single row of tab titles, the panel displays every tab and pane with contextual metadata — Git branch, working directory, agent conversation status, diff stats, and more. Scan and switch between workstreams without losing context. Vertical tabs are especially useful when running multiple coding agents side by side, giving you a clear overview of each session’s state without switching tabs. ## Key features [Section titled “Key features”](#key-features) ### Rich metadata and status [Section titled “Rich metadata and status”](#rich-metadata-and-status) * **Pane metadata** - See working directory, Git branch, agent conversation status, diff stats, and PR badges at a glance for every pane. * **Agent status badges** - Pane icons display a colored badge overlay showing agent state (in progress, done, errored, cancelled, or blocked). [Third-party CLI agents](/agent-platform/cli-agents/overview/) like Claude Code, Codex, and Gemini CLI display their brand icon and color alongside badges. * **Notification indicators** - An accent-colored dot appears on pane rows with unread agent activity, so you can spot sessions that need attention without switching tabs. ### Display modes and customization [Section titled “Display modes and customization”](#display-modes-and-customization) * **Pane or tab view** - Display every split pane as its own row (**Panes**) or show only the focused pane per tab (**Tabs**). * **Compact and expanded modes** - Choose between a dense single-line view (default) or a detailed multi-line layout with full metadata. * **Configurable pane titles** - Control which metadata appears first: last command or conversation, working directory, or Git branch. * **Hover detail sidecar** - Hover any pane row to see full, un-clipped metadata in a floating detail card without changing focus. ### Tab management [Section titled “Tab management”](#tab-management) * **Search, drag and drop, and renaming** - Filter panes by title, directory, or branch; reorder tabs or move panes between tabs by dragging; double-click a tab to rename it inline. * **New tab menu** - Create agent tabs, terminal tabs, Oz cloud agent sessions, worktree configs, and [Tab Configs](/terminal/windows/tab-configs/) from a unified **+** menu. ## Enabling vertical tabs [Section titled “Enabling vertical tabs”](#enabling-vertical-tabs) To switch from horizontal tabs to the vertical tabs panel: 1. In the Warp app, navigate to **Settings** > **Appearance** > **Tabs**. 2. Toggle **Use vertical tab layout** on. The vertical tabs panel appears as a resizable sidebar on the left side of the window. The horizontal tab bar is hidden while vertical tabs are active. ![A Warp window with the vertical tabs sidebar on the left listing a Claude Code tab and a codex tab alongside the main terminal pane](/_astro/multi-agents.BnUFIPfc_ZoqSlt.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Vertical tab with agent details. Note You can also toggle vertical tabs from the [Command Palette](/terminal/command-palette/) by searching for “vertical tab layout.” ## View modes [Section titled “View modes”](#view-modes) The vertical tabs panel supports two display densities that you can switch between at any time. ### Compact mode [Section titled “Compact mode”](#compact-mode) Compact mode is the default. Each pane row displays an icon and title on one line, with an optional subtitle below it. The subtitle is configurable via the **Additional metadata** setting in the settings popup. ![Vertical tabs sidebar in compact mode with each pane row showing an icon, title, and a short subtitle below](/_astro/vertical-tabs-condensed.D_7Ir3Kr_Z2dciRF.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Vertical tabs in compact mode. ### Expanded mode [Section titled “Expanded mode”](#expanded-mode) Expanded mode shows each pane row with a title, description (such as the working directory or file path), and metadata (Git branch, diff stats badge, and PR badge when available). ![Vertical tab rows in expanded mode showing titles, working directories, Git branches, diff stats, and agent status badges](/_astro/vertical-tabs-multi-agent.BFeWyl4n_ZJrRky.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Vertical tabs overview. ### Switching view modes [Section titled “Switching view modes”](#switching-view-modes) Click the settings icon (sliders) in the control bar at the top of the vertical tabs panel. In the popup, use the **Density** segmented control to switch between compact and expanded views. The change takes effect immediately. ![The vertical tabs settings popup anchored to the sliders icon, showing View as, Density, Pane title as, Additional metadata, and Show details on hover options](/_astro/vertical-tab-settings.BXRWNhi8_Z1wqe6C.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Vertical tabs settings popup. ## Customizing vertical tabs [Section titled “Customizing vertical tabs”](#customizing-vertical-tabs) When vertical tabs are enabled, configure their appearance and behavior from the settings popup (click the sliders icon in the control bar) or from **Settings** > **Appearance** > **Tabs**. You can also rearrange the panel toggle buttons at the top of the Warp window — including the tabs panel, tools panel, agent management, code review, and notifications mailbox — and move them between the left and right sides of the header. See [Configurable toolbar](/terminal/windows/configurable-toolbar/) for details. | Setting | Availability | Options | Default | | ------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | **View as** | Always | **Panes** — each split pane gets its own row. **Tabs** — only the focused pane per tab is shown. | Panes | | **Density** | Always | **Compact** — smaller rows with title and optional subtitle. **Expanded** — larger rows with title, description, and metadata. | Compact | | **Pane title as** | Always | **Command / Conversation** — last command, conversation title, or CLI agent session name. **Working Directory** — pane’s working directory. **Branch** — checked-out Git branch. | Command / Conversation | | **Additional metadata** | Compact mode only | **Branch** **Working Directory** **Command / Conversation** (options depend on the **Pane title as** setting; duplicates are excluded). | Branch | | **Show** | Expanded mode only | **PR link** — pull request and status for the current branch (requires GitHub CLI). **Diff stats** — lines added/removed. | — | | **Show details on hover** | Always | On / Off — toggles the hover detail sidecar. | On | ### Automatic metadata [Section titled “Automatic metadata”](#automatic-metadata) The following metadata appears automatically and doesn’t require configuration: * **Git branch** - The currently checked-out branch for the pane’s working directory. * **Worktree** - The active [Git worktree](/code/git-worktrees/) path, if applicable. * **Agent status** - A colored badge on the pane icon indicating the agent’s current state (see [Agent status badges](#agent-status-badges) below). * **Notification dot** - An accent-colored dot on the title row when a pane has unread agent activity. ## Agent status badges [Section titled “Agent status badges”](#agent-status-badges) Agent pane icons display a small circular badge overlay in the bottom-right corner that reflects the agent’s current state: | Status | Icon | Meaning | | --------------- | ------------- | -------------------------------------------------- | | **In progress** | Magenta clock | The agent is actively running. | | **Done** | Green check | The agent’s last turn completed successfully. | | **Error** | Red triangle | The agent’s last turn completed with an error. | | **Cancelled** | Gray stop | The user cancelled the agent’s last turn. | | **Blocked** | Yellow stop | The agent is waiting for user approval to proceed. | ![Vertical tabs sidebar with four tab rows showing different agent status badges: a yellow blocked square, a magenta in-progress moon on the Claude Code brand icon, and green completion checks](/_astro/agent-status-badges.BZmH2FMT_200WhP.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Agent status badges on vertical tabs. Third-party CLI agents (Claude Code, Codex, Gemini CLI, and others) display their brand icon and color inside the circular pane icon, with the same status badge overlay. When a pane has unread agent activity, an accent-colored notification dot appears at the right edge of the title row. The dot clears when you focus the pane. ## Managing tabs [Section titled “Managing tabs”](#managing-tabs) ### Search [Section titled “Search”](#search) The control bar at the top of the vertical tabs panel includes a search field. Type to filter the visible tabs and panes by title, working directory, Git branch, PR label, or diff stats. Only matching tabs remain visible while the search query is active. ### New tab menu [Section titled “New tab menu”](#new-tab-menu) Click the **+** button in the control bar to open the new tab menu. The menu includes: * **Agent** - Open a new agent tab. * **Terminal** - Open a new terminal tab. * **Oz cloud agent** - Open a new Oz cloud agent session tab. * **Tab Configs** - Any [Tab Configs](/terminal/windows/tab-configs/) you’ve created appear as menu items for one-click setup. * **New worktree config** - Create a new worktree-based Tab Config. * **New tab config** - Create a new Tab Config from a starter template. ### Drag and drop [Section titled “Drag and drop”](#drag-and-drop) Reorder tabs by dragging tab group headers within the panel. To move a pane from one tab to another, drag the pane header over a different tab group in the panel. Warp switches to that tab so you can place the pane using the standard drop targets. Dropping a pane between tab groups creates a new tab at that position. ### Tab renaming [Section titled “Tab renaming”](#tab-renaming) Double-click a tab row to rename it inline. Press `Enter` to confirm or `Esc` to cancel. Note Renaming applies to tabs only. Individual panes can’t be renamed at this time. ## Hover detail sidecar [Section titled “Hover detail sidecar”](#hover-detail-sidecar) Hover any pane row to open a floating detail card anchored to the right side of the panel. The sidecar shows full, un-clipped metadata (complete directory paths, full branch names, and the full conversation or command title) without changing which pane is focused. ![The vertical tabs panel with a Claude Code tab hovered, showing a floating detail card with the agent's In progress status, working directory, and session title](/_astro/tab-hover-detail-card.mP2qkvae_1G3f2e.webp?dpl=dpl_CYffURFvG3qfYKzeQGW7CFtvMHij) Hover detail card for a vertical tab. The sidecar stays open as you move the cursor from the row into the card. Move away from both the row and the sidecar to dismiss it. Disable this behavior with the **Show details on hover** toggle in the settings popup. ## Keyboard shortcuts [Section titled “Keyboard shortcuts”](#keyboard-shortcuts) All existing tab keyboard shortcuts continue to work with vertical tabs. The sidebar layout changes how tabs are displayed, not how you interact with them. See [Terminal tabs](/terminal/windows/tabs/) for the full list of tab shortcuts. ## Related pages [Section titled “Related pages”](#related-pages) * [Terminal tabs](/terminal/windows/tabs/) - Horizontal tab bar usage and keyboard shortcuts * [Split panes](/terminal/windows/split-panes/) - Divide tabs into multiple terminal panes * [Tab Configs](/terminal/windows/tab-configs/) - Define reusable tab setups in TOML files * [Git Worktrees](/code/git-worktrees/) - Worktree support that surfaces in vertical tab metadata * [Tabs behavior](/terminal/appearance/tabs-behavior/) - Tab bar visibility, indicators, and close button settings * [Third-party CLI agents](/agent-platform/cli-agents/overview/) - Use Claude Code, Codex, Gemini CLI, and other third-party agents with Warp’s utility bar, including brand icons and status badges in the vertical tabs panel