diff --git a/docs/resources/agent.md b/docs/resources/agent.md
index 87ab4239..1f4dcd27 100644
--- a/docs/resources/agent.md
+++ b/docs/resources/agent.md
@@ -76,6 +76,8 @@ resource "kubernetes_pod" "dev" {
 - `auth` (String) The authentication type the agent will use. Must be one of: `"token"`, `"google-instance-identity"`, `"aws-instance-identity"`, `"azure-instance-identity"`.
 - `connection_timeout` (Number) Time in seconds until the agent is marked as timed out when a connection with the server cannot be established. A value of zero never marks the agent as timed out.
 - `dir` (String) The starting directory when a user creates a shell session. Defaults to `"$HOME"`.
+
+~> **Warning:** Setting `dir` to a value other than `$HOME` will break [Coder Desktop file sync](https://coder.com/docs/user-guides/desktop/desktop-connect-sync).
 - `display_apps` (Block Set, Max: 1) The list of built-in apps to display in the agent bar. (see [below for nested schema](#nestedblock--display_apps))
 - `env` (Map of String) A mapping of environment variables to set inside the workspace.
 - `metadata` (Block List) Each `metadata` block defines a single item consisting of a key/value pair. This feature is in alpha and may break in future releases. (see [below for nested schema](#nestedblock--metadata))
diff --git a/provider/agent.go b/provider/agent.go
index b9f8a6d3..81043370 100644
--- a/provider/agent.go
+++ b/provider/agent.go
@@ -49,9 +49,19 @@ func agentResource() *schema.Resource {
 					return diag.FromErr(err)
 				}
 			}
-
-			return updateInitScript(resourceData, i)
+			diags := updateInitScript(resourceData, i)
+			if dir, ok := resourceData.GetOk("dir"); ok {
+				if d, _ := dir.(string); d != "" && d != "$HOME" && d != "~" {
+					diags = append(diags, diag.Diagnostic{
+						Severity: diag.Warning,
+						Summary:  `"dir" is not set to $HOME`,
+						Detail:   `Setting "dir" to a value other than $HOME will break Coder Desktop file sync.`,
+					})
+				}
+			}
+			return diags
 		},
+
 		ReadWithoutTimeout: func(ctx context.Context, resourceData *schema.ResourceData, i interface{}) diag.Diagnostics {
 			token := agentAuthToken(ctx, "")
 			err := resourceData.Set("token", token)
@@ -74,8 +84,19 @@ func agentResource() *schema.Resource {
 				}
 			}
 
-			return updateInitScript(resourceData, i)
+			diags := updateInitScript(resourceData, i)
+			if dir, ok := resourceData.GetOk("dir"); ok {
+				if d, _ := dir.(string); d != "" && d != "$HOME" && d != "~" {
+					diags = append(diags, diag.Diagnostic{
+						Severity: diag.Warning,
+						Summary:  `"dir" is not set to $HOME`,
+						Detail:   `Setting "dir" to a value other than $HOME will break Coder Desktop file sync.`,
+					})
+				}
+			}
+			return diags
 		},
+
 		DeleteContext: func(ctx context.Context, resourceData *schema.ResourceData, i interface{}) diag.Diagnostics {
 			return nil
 		},
@@ -115,7 +136,9 @@ func agentResource() *schema.Resource {
 				Type:        schema.TypeString,
 				ForceNew:    true,
 				Optional:    true,
-				Description: "The starting directory when a user creates a shell session. Defaults to `\"$HOME\"`.",
+				Description: "The starting directory when a user creates a shell session. Defaults to `\"$HOME\"`." +
+					"\n\n~> **Warning:** Setting `dir` to a value other than `$HOME` will break " +
+					"[Coder Desktop file sync](https://coder.com/docs/user-guides/desktop/desktop-connect-sync).",
 			},
 			"env": {
 				ForceNew:    true,