Skip to content

docs: fine-tune migration guides #96

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rachaelrenk wants to merge 5 commits into
base: main
Choose a base branch
from
Open

docs: fine-tune migration guides #96

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
33733e9
docs: fine-tune migration guides
rachaelrenk May 19, 2026
0880224
Merge branch 'main' into rachael/migration-guides-fine-tuning
rachaelrenk May 19, 2026
d66dc33
Merge branch 'main' into rachael/migration-guides-fine-tuning
rachaelrenk May 19, 2026
fcac325
Merge branch 'main' into rachael/migration-guides-fine-tuning
rachaelrenk May 20, 2026
15b7827
Merge branch 'main' into rachael/migration-guides-fine-tuning
rachaelrenk May 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions ...ntent/docs/getting-started/migrate-to-warp/migrate-to-warp-from-claude-code.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,32 +43,32 @@ Claude Code's authentication (API key or Anthropic account) is handled by Claude

## 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:
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`)
2. From terminal mode, press `⌘+Enter` (macOS) or `Ctrl+Shift+Enter` (Linux/Windows) to switch to [Agent Mode](/agent-platform/local-agents/overview/).
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.
Warp's Agent reads your codebase, runs commands, and edits files the same way Claude Code does.

### 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.
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:
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.
* **[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.
* **[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

* **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.
* **Configure [agent profiles and permissions](/agent-platform/capabilities/agent-profiles-permissions/)** for what the Agent can auto-execute.

### Key differences from Claude Code

Expand All @@ -79,7 +79,7 @@ Warp's agent also pulls context from several other explicit sources:

## Warp-native equivalents

Claude Code concepts and their closest Warp analog:
Use this table to find the closest Warp equivalent for Claude Code concepts:

| From Claude Code | In Warp |
| --- | --- |
Expand Down
30 changes: 15 additions & 15 deletions src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-cursor.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,42 +5,42 @@ description: >-
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.
Warp gives Cursor users two 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
## What Warp can help transfer

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.
Warp doesn't have a one-click 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.*`. Because that file is readable, Warp's Agent can translate matching terminal values into Warp's `settings.toml`. In Cursor, open the Command Palette and select **Preferences: Open User Settings (JSON)** to reference your settings while you reconfigure Warp.

## Use Warp's agent to migrate your settings (recommended)
## Use Warp's 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.
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:
1. In the Warp app, open a new tab and switch to [Agent Mode](/agent-platform/local-agents/overview/) with `⌘+I` (macOS) or `Ctrl+I` (Linux/Windows).
2. Paste this prompt into Agent Mode, then press `Enter`.

> 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.
3. Review the proposed diff, then approve the changes. 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

### 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.
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

Cursor's Composer and Agent features don't have a one-to-one migration path - they map to different Warp concepts.
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.
* **Composer / Agent** - In Cursor, these features map to Warp's [Agent Mode](/agent-platform/local-agents/overview/). Start an Agent conversation in any tab.
* **Rules files** - 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

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/).
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

Expand All @@ -63,11 +63,11 @@ Warp's built-in [code editor](/code/code-editor/) supports Language Server Proto

## Warp-native equivalents

Cursor features and their Warp counterparts:
Use this table to find Warp equivalents for Cursor features you might look for after switching:

| From Cursor | In Warp |
| --- | --- |
| Composer / Agent panel | [Agent Mode](/agent-platform/local-agents/overview/) in any tab (toggle with `⌘+I`) |
| Composer / Agent panel | [Agent Mode](/agent-platform/local-agents/overview/) in any tab (toggle with `⌘+I` on macOS or `Ctrl+I` on Linux/Windows) |
| 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/) |
Expand Down
36 changes: 18 additions & 18 deletions src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-ghostty.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,61 +6,61 @@ description: >-
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.
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
## What Warp can help transfer

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`.
Warp doesn't have a one-click Ghostty importer. Because Ghostty stores its configuration in a plain-text key-value file at `~/.config/ghostty/config`, Warp's Agent can read that file and translate matching values into Warp's `settings.toml`.

## Use Warp's agent to migrate your settings (recommended)
## Use Warp's 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/).
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:
1. In the Warp app, open a new tab and switch to [Agent Mode](/agent-platform/local-agents/overview/) with `⌘+I` (macOS) or `Ctrl+I` (Linux/Windows).
2. Paste this prompt into Agent Mode, then press `Enter`.

> 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.
3. Review the proposed diff, then approve the changes. 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

### 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.
1. In the Warp app, open **Settings** > **Appearance** > **Themes**.
2. Choose 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. If your Ghostty config references a custom theme, open the matching file in `~/.config/ghostty/themes/` and copy the foreground, background, and 16 ANSI color values.

### 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.
1. In the Warp app, open **Settings** > **Appearance** > **Text, fonts, & cursor** and match your Ghostty `font-family` and `font-size` values.
2. If you use font ligatures, toggle **Ligatures** on.

### 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.
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** in the Warp app and add them manually.

### 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**.
Warp detects your login shell automatically. To override it, open **Settings** > **Features** > **Session** in the Warp app and choose 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)

Configure Warp's equivalent via **Settings** > **Features** > **Window** > **Global hotkey**. See [global hotkey](/terminal/windows/global-hotkey/) for the full configuration.
In the Warp app, configure Warp's equivalent from **Settings** > **Features** > **Window** > **Global hotkey**. See [global hotkey](/terminal/windows/global-hotkey/) for the full configuration.

## Warp-native equivalents

Features Ghostty users commonly miss, and where they live in Warp:
Use this table to find the closest Warp equivalent for Ghostty features you might look for after switching:

| 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) |
| Command palette | [Command Palette](/terminal/command-palette/) (`⌘+P` on macOS, `Ctrl+Shift+P` on Linux/Windows) |
| 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/) |
Expand Down
12 changes: 6 additions & 6 deletions src/content/docs/getting-started/migrate-to-warp/migrate-to-warp-from-iterm2.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,16 +32,16 @@ To run the importer:
<figcaption>Select a settings profile to import.</figcaption>
</figure>

## Use Warp's agent for follow-up settings
## Use Warp's 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.
If the importer doesn't pick up something you care about, such as a non-default profile, an unusual keybinding, or 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:
1. In the Warp app, switch to [Agent Mode](/agent-platform/local-agents/overview/) with `⌘+I`.
2. Paste this prompt into Agent Mode, then press `Enter`.

> 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`.
3. Review the proposed diff, then approve the changes. Warp hot-reloads `settings.toml`.

## What to reconfigure manually

Expand All @@ -61,7 +61,7 @@ After the import, choose which [prompt](/terminal/appearance/prompt/) to use:

## Warp-native equivalents

Features switchers commonly look for after leaving iTerm2, and where they live in Warp:
Use this table to find Warp equivalents for iTerm2 features you might look for after switching:

| From iTerm2 | In Warp |
| --- | --- |
Expand Down
Loading
Loading