From 71bbcffd060ca75aacb5cf45a7ce5f26f4666f5c Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Thu, 17 Sep 2026 08:47:43 -0400 Subject: [PATCH 1/4] docs: clarify auto-background does not happen on Windows When an AI agent is detected, astro dev and astro preview auto-background on macOS and Linux only. On Windows the server stays in the foreground so the agent can manage the process directly; --background remains the explicit opt-in. See withastro/astro#18029. --- src/content/docs/en/guides/build-with-ai.mdx | 4 +++- src/content/docs/en/reference/cli-reference.mdx | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/build-with-ai.mdx b/src/content/docs/en/guides/build-with-ai.mdx index caa15ed7bdd35..5171529cd6ff6 100644 --- a/src/content/docs/en/guides/build-with-ai.mdx +++ b/src/content/docs/en/guides/build-with-ai.mdx @@ -362,7 +362,9 @@ The same technology that powers Astro's MCP server is also available as a chatbo

-When an AI coding agent is detected, `astro dev` and, since v7.2.0, `astro preview` automatically start the server as a detached background process. This prevents the server from blocking the agent's terminal and allows it to continue working while the server runs. +When an AI coding agent is detected, `astro dev` and, since v7.2.0, `astro preview` automatically start the server as a detached background process on macOS and Linux. This prevents the server from blocking the agent's terminal and allows it to continue working while the server runs. + +On Windows, automatic background mode is disabled: when an AI coding agent is detected, the server stays in the foreground so the agent can manage the process directly, because Windows Job Objects can terminate detached child processes when the agent command exits. You can still opt in explicitly by passing the [`--background` flag](/en/reference/cli-reference/#--background). A lock file (`.astro/dev.json` or `.astro/preview.json`) is written when the server starts, recording the server's URL, port, and PID. This prevents duplicate servers from being started for the same project. diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index 98442f1ecac00..085ee7132bb0a 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -540,7 +540,7 @@ Starts the dev server, or the preview server since v7.2.0, as a detached backgro When the server starts, Astro writes a lock file (`.astro/dev.json` or `.astro/preview.json`) to record the server's URL, port, and PID. This avoids launching many instances of the server for the same project. -This flag is provided automatically when an AI agent is detected. You can also use it manually: +This flag is provided automatically when an AI agent is detected on macOS and Linux. On Windows, automatic backgrounding does not happen: when an AI agent is detected, the server stays in the foreground so the agent can manage the process directly. On all platforms, you can also use the flag manually: ```shell astro dev --background From d356158a267e13d7456457b74616818031404d16 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Thu, 17 Sep 2026 08:53:03 -0400 Subject: [PATCH 2/4] docs: drop Windows Job Objects implementation detail from background mode --- src/content/docs/en/guides/build-with-ai.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/build-with-ai.mdx b/src/content/docs/en/guides/build-with-ai.mdx index 5171529cd6ff6..86e21f3e19121 100644 --- a/src/content/docs/en/guides/build-with-ai.mdx +++ b/src/content/docs/en/guides/build-with-ai.mdx @@ -364,7 +364,7 @@ The same technology that powers Astro's MCP server is also available as a chatbo When an AI coding agent is detected, `astro dev` and, since v7.2.0, `astro preview` automatically start the server as a detached background process on macOS and Linux. This prevents the server from blocking the agent's terminal and allows it to continue working while the server runs. -On Windows, automatic background mode is disabled: when an AI coding agent is detected, the server stays in the foreground so the agent can manage the process directly, because Windows Job Objects can terminate detached child processes when the agent command exits. You can still opt in explicitly by passing the [`--background` flag](/en/reference/cli-reference/#--background). +On Windows, automatic background mode is disabled: when an AI coding agent is detected, the server stays in the foreground so the agent can manage the process directly. You can still opt in explicitly by passing the [`--background` flag](/en/reference/cli-reference/#--background). A lock file (`.astro/dev.json` or `.astro/preview.json`) is written when the server starts, recording the server's URL, port, and PID. This prevents duplicate servers from being started for the same project. From b62b74f9c9aec9a2f33c3f9370be245a03b6ccdf Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Thu, 17 Sep 2026 10:49:25 -0400 Subject: [PATCH 3/4] Update src/content/docs/en/guides/build-with-ai.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/guides/build-with-ai.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/build-with-ai.mdx b/src/content/docs/en/guides/build-with-ai.mdx index 86e21f3e19121..2d53715d3d534 100644 --- a/src/content/docs/en/guides/build-with-ai.mdx +++ b/src/content/docs/en/guides/build-with-ai.mdx @@ -364,7 +364,7 @@ The same technology that powers Astro's MCP server is also available as a chatbo When an AI coding agent is detected, `astro dev` and, since v7.2.0, `astro preview` automatically start the server as a detached background process on macOS and Linux. This prevents the server from blocking the agent's terminal and allows it to continue working while the server runs. -On Windows, automatic background mode is disabled: when an AI coding agent is detected, the server stays in the foreground so the agent can manage the process directly. You can still opt in explicitly by passing the [`--background` flag](/en/reference/cli-reference/#--background). +On Windows, or without an AI coding agent, the server starts in the foreground and logs to the terminal. You can still opt in explicitly by passing the [`--background` flag](/en/reference/cli-reference/#--background). A lock file (`.astro/dev.json` or `.astro/preview.json`) is written when the server starts, recording the server's URL, port, and PID. This prevents duplicate servers from being started for the same project. From e564aeaddf0cabf26ca7b15a7321f1c19a63b88c Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Thu, 17 Sep 2026 10:49:37 -0400 Subject: [PATCH 4/4] Update src/content/docs/en/guides/build-with-ai.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/guides/build-with-ai.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/build-with-ai.mdx b/src/content/docs/en/guides/build-with-ai.mdx index 2d53715d3d534..2806bdfb0970d 100644 --- a/src/content/docs/en/guides/build-with-ai.mdx +++ b/src/content/docs/en/guides/build-with-ai.mdx @@ -362,7 +362,7 @@ The same technology that powers Astro's MCP server is also available as a chatbo

-When an AI coding agent is detected, `astro dev` and, since v7.2.0, `astro preview` automatically start the server as a detached background process on macOS and Linux. This prevents the server from blocking the agent's terminal and allows it to continue working while the server runs. +When an AI coding agent is detected on macOS and Linux, `astro dev` and, since v7.2.0, `astro preview` automatically start the server as a detached background process. This prevents the server from blocking the agent's terminal and allows it to continue working while the server runs. On Windows, or without an AI coding agent, the server starts in the foreground and logs to the terminal. You can still opt in explicitly by passing the [`--background` flag](/en/reference/cli-reference/#--background).