diff --git a/src/content/docs/agent-platform/capabilities/codebase-context.mdx b/src/content/docs/agent-platform/capabilities/codebase-context.mdx index 2bd8488..56d3621 100644 --- a/src/content/docs/agent-platform/capabilities/codebase-context.mdx +++ b/src/content/docs/agent-platform/capabilities/codebase-context.mdx @@ -38,12 +38,13 @@ When you open a directory in Warp, we check if it is part of a Git repository. I 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. ::: -:::danger -**Codebase Context doesn't work within SSH or WSL sessions.** \ -\ -Feature requests for support are being tracked in the following GitHub issues: \ -\- SSH: [https://github.com/warpdotdev/Warp/issues/6831](https://github.com/warpdotdev/Warp/issues/6831)\ -\- WSL: [https://github.com/warpdotdev/Warp/issues/6744](https://github.com/warpdotdev/Warp/issues/6744) +:::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.](../../../../assets/agent-platform/codebase-context-main.png) diff --git a/src/content/docs/code/code-editor/file-tree.mdx b/src/content/docs/code/code-editor/file-tree.mdx index 263d4d1..6ebcf5f 100644 --- a/src/content/docs/code/code-editor/file-tree.mdx +++ b/src/content/docs/code/code-editor/file-tree.mdx @@ -9,6 +9,10 @@ description: >- 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 You can open the file tree from the tools panel on the left hand side: diff --git a/src/content/docs/code/overview.mdx b/src/content/docs/code/overview.mdx index 3b93faf..04ca6ff 100644 --- a/src/content/docs/code/overview.mdx +++ b/src/content/docs/code/overview.mdx @@ -7,7 +7,7 @@ description: >- import VideoEmbed from '@components/VideoEmbed.astro'; :::note -Several coding features — including Codebase Context, code diffs, the code editor, and the file tree — are not yet available in SSH or WSL sessions. +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 @@ -34,7 +34,7 @@ Warp’s coding agent is designed to help you generate, edit, and manage code di :::note -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. +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 diff --git a/src/content/docs/code/ssh-feature-support.mdx b/src/content/docs/code/ssh-feature-support.mdx index 9d704d8..5e7a75f 100644 --- a/src/content/docs/code/ssh-feature-support.mdx +++ b/src/content/docs/code/ssh-feature-support.mdx @@ -5,34 +5,41 @@ description: >- 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. However, several coding-specific features are **not yet available** in remote sessions because the Agent cannot directly access the remote filesystem. +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 is unavailable, the Agent automatically falls back to terminal commands (e.g. `cat`, `sed`, `grep`) to read and edit files. You can still accomplish most coding tasks over SSH, but the experience may be less seamless than working locally. +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 -The following features are fully available in Warpified remote sessions: +The following features work in Warpified remote sessions on both paths: -* **Agent Mode conversations** — You can chat with the Agent, ask questions, and request code changes. The Agent will use terminal commands to interact with the remote filesystem. +* **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 -The following features require local filesystem access and are not yet available in Warpified remote (SSH) sessions: +The following features require local filesystem access and are not yet available in Warpified remote (SSH) sessions on either path: -* **Codebase Context (indexing and search)** — Warp cannot index or semantically search a remote codebase. The Agent will not have access to your full project context when generating responses. Feature request: [GitHub #6831](https://github.com/warpdotdev/Warp/issues/6831) -* **Native file reading** — The Agent cannot read files through Warp's built-in file reading tool. It falls back to terminal commands like `cat` to read file contents. -* **Code diffs** — The Agent cannot apply code diffs natively. It falls back to terminal commands like `sed` to make file edits. -* **Code editor** — Warp's [native code editor](/code/code-editor/) is not yet available in remote sessions. You cannot open, view, or edit files in Warp's built-in editor over SSH. -* **File tree (Project Explorer)** — The [file tree sidebar](/code/code-editor/file-tree/) is not yet available in remote sessions. -* **Code review panel** — The [Code Review](/code/code-review/) panel for reviewing Git diffs is not yet available for remote repos. +* **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. Feature request for WSL support: [GitHub #6744](https://github.com/warpdotdev/Warp/issues/6744) +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). ::: diff --git a/src/content/docs/terminal/warpify/index.mdx b/src/content/docs/terminal/warpify/index.mdx index 946321e..5c5e50d 100644 --- a/src/content/docs/terminal/warpify/index.mdx +++ b/src/content/docs/terminal/warpify/index.mdx @@ -7,7 +7,7 @@ description: >- import DemoVideo from '@components/DemoVideo.astro'; 1. [Subshells](/terminal/warpify/subshells/), Warp supports enabling Warp features in subshells for bash, zsh, and fish. -2. [SSH](/terminal/warpify/ssh/), Warp supports a tmux powered wrapper that enables Warp features in remote (SSH) sessions. +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 diff --git a/src/content/docs/terminal/warpify/ssh.mdx b/src/content/docs/terminal/warpify/ssh.mdx index 16316f3..576f841 100644 --- a/src/content/docs/terminal/warpify/ssh.mdx +++ b/src/content/docs/terminal/warpify/ssh.mdx @@ -1,61 +1,91 @@ --- title: SSH with Warp features description: >- - Warpify SSH sessions with tmux to get Blocks, completions, and the input - editor on remote machines. + 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. --- import VideoEmbed from '@components/VideoEmbed.astro'; +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`. + + + +## 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.](../../../../assets/terminal/warpify_ssh_prompt.png) + +## 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 -Some coding features — including Codebase Context, code diffs, the code editor, and the file tree — are not yet available over SSH. See [Feature support over SSH](/code/ssh-feature-support/) for the full list. +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. ::: -:::caution -This page is dedicated to the SSH features powered by `tmux`. +### Managing the install prompt -If you are looking to troubleshoot the legacy SSH implementation, see the [SSH (Legacy)](/terminal/warpify/ssh-legacy/). -::: +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. -Warpifying your SSH session gives you all the features of Warp while connected to a remote machine: the input editor, auto-completions, history search, and more. We achieve this by running commands like `ls` on the remote machine on your behalf. +## Legacy: tmux-based Warpification -**Warpifying a remote SSH Session** [**will never make lasting changes to the remote machine without your explicit consent**](/terminal/warpify/ssh/#will-warpifying-a-remote-ssh-session-make-changes-to-the-remote-machine)**.** +:::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). +::: -![SSH](../../../../assets/terminal/warpify_ssh_prompt.png) +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 +### FAQs #### Will Warpifying a remote SSH session make changes to the remote machine? -Only to install [`tmux`](/terminal/warpify/ssh/#why-do-i-need-tmux-on-the-remote-machine) (a popular open source terminal multiplexer) and only with your explicit permission. If `tmux` is not installed, Warp will offer to install it for you and will show you the list of commands that will be run. You can always decline and continue to use your ssh session without some of Warp's features (or install `tmux` yourself and re-run Warpification [via the Command Palette](/terminal/warpify/ssh/#what-if-warp-fails-to-detect-my-ssh-session)). +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? -`tmux` is used to asynchronously run commands on the remote machine without disrupting your interactive session. [tmux](https://github.com/tmux/tmux/wiki) is a popular open source terminal multiplexer, which lets you run multiple sessions within one ssh connection. It requires minimal permissions and is widely adopted (⭐ 35k+ on GitHub). Warpifying a remote SSH session uses [tmux Control Mode](https://github.com/tmux/tmux/wiki/Control-Mode) to run adhoc background tasks (like those required to autocomplete a `cd` command, or populate the contents of a custom prompt). +`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? +#### Can I SSH to remote machines that I don't want to Warpify? -Yes! You can always cancel Warpification and continue to use SSH, just without some of Warp's additional features. You can also explicitly add hosts to the Denylist to ensure you’re never asked to Warpify that host again. +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? +#### Do I have to manually Warpify every time? -After you successfully Warpify an SSH connection manually, we provide a brief script you can run to append a message at the end of your shell's rcfile. This allows us to know when your shell is ready to be Warpified, and be found at the bottom of your rcfile for the best results. +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](../../../../assets/terminal/warpify_ssh_auto_script.png) #### What shells and operating systems are supported? -At the time of writing, we support macOS and most flavors of Linux as remote hosts. Supported shells are `bash` and `zsh`. +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? -If you are ever in a remote SSH Session and would like to manually Warpify, you can do so by using the [Command Palette](/terminal/command-palette/) and searching for "Warpify 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? -If SSH Session Detection is enabled, Warp will detect when you run an `ssh` command with arguments that suggest it's starting an interactive session. If you've aliased `ssh` or are running it as part of a script, we will not perform SSH Session Detection. +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 we have confidence you have successfully authenticated (by detecting `Last login:` or something resembling a basic prompt) we will prompt you to Warpify your active SSH session. +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 does not detect your session, you can still [Warpify manually](/terminal/warpify/ssh/#what-if-warp-fails-to-detect-my-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).