Add warp://settings deeplink entrypoints (open, search, scroll-to-widget) (#13232)

Demo: https://www.loom.com/share/d26cdf004faa4aee9c128f77dc0b2af8

## Description
Adds a `warp://settings` deep link family so settings can be opened
directly from a URL:
- `warp://settings` - opens a settings tab on the default page.
- `warp://settings?q=<query>` - opens settings with the search bar
pre-filled and the page list filtered.
- `warp://settings?widget=<widget_id>` - opens settings scrolled to (and
highlighting) a specific widget.

**Why:** lets external surfaces (docs, in-app links, support flows)
deep-link users straight to the relevant setting.

**How:** the existing `UriHost::Settings` handler now treats an empty
trailing path segment as "no sub-page" and routes the bare host plus the
`q`/`widget` query params (precedence: `widget` > `q` > existing simple
sub-pages > bare default). A new `OpenSettingsArgs` enum maps to the
existing workspace actions (`ShowSettings`,
`ShowSettingsPageWithSearch`, `ScrollToSettingsWidget`) via two new
`root_view` actions. `?widget=` resolves through an allowlist
(`settings_widget_deeplink_target`) of stable slugs to
`(SettingsSection, &'static str)` so internal Rust type names aren't
exposed as the public URL contract; seeded with `global_hotkey`,
`cli_agents`, and `custom_router`. Also fixed `open_settings_pane` so a
`?q=` search applies even when a settings tab is already open.

## Linked Issue
N/A - no linked issue.

## Testing
Added unit tests in `app/src/uri/uri_tests.rs`:
- `parse_settings_search_query` - present / empty / URL-encoded /
missing `q`
- `settings_widget_deeplink_target` - known slugs (incl.
`custom_router`) and unknown/empty
- `settings_section_for_simple_subpage` - regression for existing
sub-pages

Ran `./script/format` and `cargo clippy -p warp --all-targets --tests --
-D warnings` (clean), plus the new unit tests.

- [ ] I have manually tested my changes locally with `./script/run`

> Not manually run via `./script/run`; covered by unit tests.
Routing-only change with no new UI layout, so no screenshots.

## Agent Mode
- [x] Warp Agent Mode - This PR was created via Warp's AI Agent Mode

## Warp artifacts
- Conversation:
https://app.warp.dev/conversation/3d208974-67e1-44da-8157-12a7e7e2ef55
- Plan: https://app.warp.dev/drive/notebook/1soy0YOddbTETZH4fg3IV3

CHANGELOG-IMPROVEMENT: Added `warp://settings` deep links - open
settings, pre-fill the search bar with `?q=`, or jump to a specific
setting with `?widget=`.

Co-Authored-By: Oz <oz-agent@warp.dev>

---------

Co-authored-by: Oz <oz-agent@warp.dev>
Co-authored-by: Andy <8334252+acarl005@users.noreply.github.com>

Author: 3 people

app/src/root_view.rs

@@ -86,7 +86,7 @@ use crate::terminal::shell::ShellType;
 use crate::terminal::view::{cell_size_and_padding, TerminalAction};
 use crate::themes::onboarding_theme_picker_themes;
 use crate::themes::theme::{AnsiColorIdentifier, Blend, Fill, ThemeKind, WarpThemeConfig};
-use crate::uri::OpenMCPSettingsArgs;
+use crate::uri::{OpenMCPSettingsArgs, OpenSettingsArgs};
 use crate::util::bindings::{self, is_binding_pty_compliant};
 use crate::util::traffic_lights::{traffic_light_data, TrafficLightData, TrafficLightMouseStates};
 use crate::view_components::DismissibleToast;
@@ -387,6 +387,15 @@ pub fn init(app: &mut AppContext) {
         RootView::open_settings_page_in_existing_window,
     );
 
+    app.add_global_action(
+        "root_view:open_settings_in_new_window",
+        open_settings_in_new_window,
+    );
+    app.add_action(
+        "root_view:open_settings_in_existing_window",
+        RootView::open_settings_in_existing_window,
+    );
+
     app.add_global_action(
         "root_view:open_mcp_settings_in_new_window",
         open_mcp_settings_in_new_window,
@@ -980,6 +989,34 @@ fn open_settings_page_in_new_window(section: &SettingsSection, ctx: &mut AppCont
     });
 }
 
+/// Maps a `warp://settings` deeplink to the workspace action that opens it.
+fn workspace_action_for_open_settings(args: &OpenSettingsArgs) -> WorkspaceAction {
+    match args {
+        OpenSettingsArgs::Default => WorkspaceAction::ShowSettings,
+        OpenSettingsArgs::Search { query } => WorkspaceAction::ShowSettingsPageWithSearch {
+            search_query: query.clone(),
+            section: None,
+        },
+        OpenSettingsArgs::Widget { page, widget_id } => WorkspaceAction::ScrollToSettingsWidget {
+            page: *page,
+            widget_id,
+        },
+    }
+}
+
+fn open_settings_in_new_window(args: &OpenSettingsArgs, ctx: &mut AppContext) {
+    let action = workspace_action_for_open_settings(args);
+    let root_handle = open_new_window_get_handles(None, ctx).1;
+    root_handle.update(ctx, |root_view, ctx| {
+        if let AuthOnboardingState::Terminal(workspace_view_handle) =
+            &root_view.auth_onboarding_state
+        {
+            let window_id = ctx.window_id();
+            ctx.dispatch_typed_action_for_view(window_id, workspace_view_handle.id(), &action);
+        }
+    });
+}
+
 /// MCP servers need to wait for initial load to complete, so we have this action in addition
 /// to the general-purpose [`open_settings_page_in_new_window`].
 fn open_mcp_settings_in_new_window(args: &OpenMCPSettingsArgs, ctx: &mut AppContext) {
@@ -2803,6 +2840,22 @@ impl RootView {
         true
     }
 
+    pub fn open_settings_in_existing_window(
+        &mut self,
+        args: &OpenSettingsArgs,
+        ctx: &mut ViewContext<Self>,
+    ) -> bool {
+        let window_id = ctx.window_id();
+        if let AuthOnboardingState::Terminal(handle) = &self.auth_onboarding_state {
+            let action = workspace_action_for_open_settings(args);
+            ctx.dispatch_typed_action_for_view(window_id, handle.id(), &action);
+            ctx.windows().show_window_and_focus_app(window_id);
+        } else {
+            log::error!("Auth not complete before trying to open settings");
+        }
+        true
+    }
+
     /// Opens the MCP servers settings page in an existing window, optionally triggering auto-install.
     /// Waits for `initial_load_complete` before opening so gallery data is available for autoinstall.
     pub fn open_mcp_settings_in_existing_window(

app/src/settings_view/ai_page.rs

@@ -9389,6 +9389,13 @@ impl SettingsWidget for AwsBedrockWidget {
     }
 }
 
+/// Stable `&'static str` id for the custom model routers settings widget,
+/// exposed for the `warp://settings?widget=custom_router` deeplink (see
+/// `settings_widget_deeplink_target`).
+pub(crate) fn custom_model_routers_widget_id() -> &'static str {
+    CustomModelRoutersWidget::static_widget_id()
+}
+
 #[derive(Default)]
 struct CustomModelRoutersWidget;
 

app/src/settings_view/features_page.rs

@@ -5587,6 +5587,13 @@ impl SettingsWidget for ExtraMetaKeysWidget {
     }
 }
 
+/// Stable `&'static str` id for the global-hotkey settings widget, exposed for
+/// the `warp://settings?widget=global_hotkey` deeplink (see
+/// `settings_widget_deeplink_target`).
+pub(crate) fn global_hotkey_widget_id() -> &'static str {
+    GlobalHotkeyWidget::static_widget_id()
+}
+
 #[derive(Default)]
 struct GlobalHotkeyWidget {}
 

app/src/settings_view/mod.rs

@@ -118,6 +118,7 @@ mod warpify_page;
 
 #[cfg(not(target_family = "wasm"))]
 pub(crate) use ai_page::cli_agent_settings_widget_id;
+pub(crate) use ai_page::custom_model_routers_widget_id;
 pub use billing_and_usage_page::create_discount_badge;
 pub use code_page::CodeSettingsPageView;
 pub use features_page::FeaturesPageAction;
@@ -411,6 +412,29 @@ impl FromStr for SettingsSection {
     }
 }
 
+/// Resolves a stable, friendly deeplink slug (used by
+/// `warp://settings?widget=<slug>`) to the settings page and `&'static str`
+/// widget id it should scroll to.
+///
+/// Only allowlisted widgets are linkable, so the public URL contract stays
+/// stable and internal widget identifiers (Rust type names) are not exposed.
+/// Add an entry here to make a new widget deep-linkable.
+pub fn settings_widget_deeplink_target(slug: &str) -> Option<(SettingsSection, &'static str)> {
+    match slug {
+        "global_hotkey" => Some((
+            SettingsSection::Features,
+            features_page::global_hotkey_widget_id(),
+        )),
+        "custom_router" => Some((SettingsSection::WarpAgent, custom_model_routers_widget_id())),
+        #[cfg(not(target_family = "wasm"))]
+        "cli_agents" => Some((
+            SettingsSection::ThirdPartyCLIAgents,
+            cli_agent_settings_widget_id(),
+        )),
+        _ => None,
+    }
+}
+
 pub struct DisplayCount(pub usize);
 
 impl Entity for DisplayCount {

app/src/uri/mod.rs

@@ -33,7 +33,9 @@ use crate::root_view::{
 };
 use crate::server::ids::ServerId;
 use crate::server::telemetry::{LaunchConfigUiLocation, TelemetryEvent};
-use crate::settings_view::{OpenTeamsSettingsModalArgs, SettingsSection};
+use crate::settings_view::{
+    settings_widget_deeplink_target, OpenTeamsSettingsModalArgs, SettingsSection,
+};
 use crate::tab_configs::TabConfig;
 use crate::user_config::{load_launch_configs, load_tab_configs, tab_configs_dir};
 use crate::util::openable_file_type::{
@@ -60,6 +62,20 @@ pub struct OpenMCPSettingsArgs {
     pub autoinstall: Option<String>,
 }
 
+/// Args for the `warp://settings` deeplink family, dispatched to the
+/// `root_view:open_settings_in_{existing,new}_window` actions.
+pub enum OpenSettingsArgs {
+    /// `warp://settings` — open a settings tab on the default page.
+    Default,
+    /// `warp://settings?q=<query>` — open settings with the search bar pre-filled.
+    Search { query: String },
+    /// `warp://settings?widget=<widget_id>` — open settings scrolled to a widget.
+    Widget {
+        page: SettingsSection,
+        widget_id: &'static str,
+    },
+}
+
 /// Source query parameter value indicating auth was initiated from cloud agent setup.
 /// Used to skip opening settings page after GitHub auth completes.
 pub const CLOUD_SETUP_SOURCE: &str = "cloud_setup";
@@ -337,87 +353,133 @@ impl UriHost {
             }
             UriHost::Settings => {
                 // We support opening different settings pages through URI:
+                // - warp://settings - opens a settings tab on the default page
+                // - warp://settings?q={query} - opens settings with the search bar pre-filled
+                // - warp://settings?widget={widget_id} - opens settings scrolled to a widget
                 // - warp://settings/teams?invite={email} - opens team settings with invite modal
                 // - warp://settings/billing_and_usage - opens billing and usage settings page
                 // - warp://settings/environments - opens environments settings page
                 // - warp://settings/mcp - opens MCP servers settings page
                 // - warp://settings/platform - opens platform settings page
                 // - warp://settings/appearance - opens appearance settings page (themes, fonts, etc.)
                 // - warp://settings/warp_agent - opens the Warp Agent settings page (inference / API keys)
+                let query_string: HashMap<_, _> = url.query_pairs().collect();
+                // A bare `warp://settings` (or a trailing slash) yields an empty path
+                // segment; treat that as "no sub-page" so the query-param routing below
+                // handles it.
                 let settings_sub_page: Option<String> = url
                     .path_segments()
                     .into_iter()
                     .flatten()
                     .last()
+                    .filter(|s| !s.is_empty())
                     .map(|s| s.to_string());
-                let query_string: HashMap<_, _> = url.query_pairs().collect();
 
-                if let Some(settings_sub_page) = settings_sub_page {
-                    match settings_sub_page.as_str() {
-                        "teams" => {
-                            let invite_email = query_string.get("invite").map(|s| s.to_string());
-                            let args = OpenTeamsSettingsModalArgs { invite_email };
+                match settings_sub_page.as_deref() {
+                    Some("teams") => {
+                        let invite_email = query_string.get("invite").map(|s| s.to_string());
+                        let args = OpenTeamsSettingsModalArgs { invite_email };
+                        dispatch_action_in_new_or_existing_window(
+                            primary_window_id,
+                            "root_view:open_team_settings_with_email_invite_in_existing_window",
+                            "root_view:open_team_settings_with_email_invite_in_new_window",
+                            &args,
+                            ctx,
+                        );
+                    }
+                    Some("environments") => {
+                        // Notify that GitHub auth completed so views can refresh
+                        GitHubAuthNotifier::handle(ctx).update(ctx, |notifier, ctx| {
+                            notifier.notify_auth_completed(ctx);
+                        });
+
+                        // Open settings page unless auth was initiated from cloud setup
+                        // (cloud setup users should stay on their current page)
+                        let source = query_string.get("source").map(|s| s.as_ref());
+                        let skip_settings = source == Some(CLOUD_SETUP_SOURCE);
+                        if !skip_settings {
                             dispatch_action_in_new_or_existing_window(
                                 primary_window_id,
-                                "root_view:open_team_settings_with_email_invite_in_existing_window",
-                                "root_view:open_team_settings_with_email_invite_in_new_window",
-                                &args,
+                                "root_view:open_settings_page_in_existing_window",
+                                "root_view:open_settings_page_in_new_window",
+                                &SettingsSection::CloudEnvironments,
                                 ctx,
                             );
                         }
-                        "environments" => {
-                            // Notify that GitHub auth completed so views can refresh
-                            GitHubAuthNotifier::handle(ctx).update(ctx, |notifier, ctx| {
-                                notifier.notify_auth_completed(ctx);
-                            });
-
-                            // Open settings page unless auth was initiated from cloud setup
-                            // (cloud setup users should stay on their current page)
-                            let source = query_string.get("source").map(|s| s.as_ref());
-                            let skip_settings = source == Some(CLOUD_SETUP_SOURCE);
-                            if !skip_settings {
-                                dispatch_action_in_new_or_existing_window(
-                                    primary_window_id,
-                                    "root_view:open_settings_page_in_existing_window",
-                                    "root_view:open_settings_page_in_new_window",
-                                    &SettingsSection::CloudEnvironments,
-                                    ctx,
-                                );
-                            }
-                        }
-                        "mcp" => {
-                            // warp://settings/mcp?autoinstall=<name> auto-installs a gallery MCP server.
-                            // The value is matched case-insensitively against gallery titles.
-                            let autoinstall =
-                                query_string.get("autoinstall").map(|v| v.to_string());
-                            let args = OpenMCPSettingsArgs { autoinstall };
+                    }
+                    Some("mcp") => {
+                        // warp://settings/mcp?autoinstall=<name> auto-installs a gallery MCP server.
+                        // The value is matched case-insensitively against gallery titles.
+                        let autoinstall = query_string.get("autoinstall").map(|v| v.to_string());
+                        let args = OpenMCPSettingsArgs { autoinstall };
+                        dispatch_action_in_new_or_existing_window(
+                            primary_window_id,
+                            "root_view:open_mcp_settings_in_existing_window",
+                            "root_view:open_mcp_settings_in_new_window",
+                            &args,
+                            ctx,
+                        );
+                    }
+                    // No special sub-page: route the bare host, the `q` (search) and
+                    // `widget` (scroll-to) query params, and the simple section
+                    // sub-pages (e.g. billing_and_usage, platform, appearance,
+                    // warp_agent) resolved via `settings_section_for_simple_subpage`.
+                    maybe_simple_subpage => {
+                        let simple_section =
+                            maybe_simple_subpage.and_then(settings_section_for_simple_subpage);
+                        // Pull the non-empty `q` search query out of the already
+                        // parsed pairs to pre-fill the settings search bar.
+                        let search_query = query_string
+                            .get("q")
+                            .map(|query| query.to_string())
+                            .filter(|query| !query.is_empty());
+                        let widget_target = query_string
+                            .get("widget")
+                            .and_then(|slug| settings_widget_deeplink_target(slug));
+
+                        if let Some((page, widget_id)) = widget_target {
+                            // `?widget=` scrolls to a specific widget; it takes
+                            // precedence over `?q=` since searching would filter the
+                            // target widget out of view.
+                            let args = OpenSettingsArgs::Widget { page, widget_id };
                             dispatch_action_in_new_or_existing_window(
                                 primary_window_id,
-                                "root_view:open_mcp_settings_in_existing_window",
-                                "root_view:open_mcp_settings_in_new_window",
+                                "root_view:open_settings_in_existing_window",
+                                "root_view:open_settings_in_new_window",
                                 &args,
                                 ctx,
                             );
-                        }
-                        // Subpages that open a settings section directly with no extra
-                        // parameters (e.g. billing_and_usage, platform, appearance,
-                        // warp_agent) are resolved via `settings_section_for_simple_subpage`.
-                        other => {
-                            if let Some(section) = settings_section_for_simple_subpage(other) {
-                                dispatch_action_in_new_or_existing_window(
-                                    primary_window_id,
-                                    "root_view:open_settings_page_in_existing_window",
-                                    "root_view:open_settings_page_in_new_window",
-                                    &section,
-                                    ctx,
-                                );
-                            } else {
-                                log::warn!("Failed to open settings pane with uri={url}");
-                            }
+                        } else if let Some(query) = search_query {
+                            let args = OpenSettingsArgs::Search { query };
+                            dispatch_action_in_new_or_existing_window(
+                                primary_window_id,
+                                "root_view:open_settings_in_existing_window",
+                                "root_view:open_settings_in_new_window",
+                                &args,
+                                ctx,
+                            );
+                        } else if let Some(section) = simple_section {
+                            dispatch_action_in_new_or_existing_window(
+                                primary_window_id,
+                                "root_view:open_settings_page_in_existing_window",
+                                "root_view:open_settings_page_in_new_window",
+                                &section,
+                                ctx,
+                            );
+                        } else if maybe_simple_subpage.is_none() {
+                            // Bare `warp://settings` opens the default settings page.
+                            let args = OpenSettingsArgs::Default;
+                            dispatch_action_in_new_or_existing_window(
+                                primary_window_id,
+                                "root_view:open_settings_in_existing_window",
+                                "root_view:open_settings_in_new_window",
+                                &args,
+                                ctx,
+                            );
+                        } else {
+                            log::warn!("Failed to open settings pane: unrecognized sub-page");
                         }
                     }
-                } else {
-                    log::warn!("Failed to open settings pane with uri={url}");
                 }
             }
             UriHost::Home => {