🤖 feat: refactor Plan Mode with external file change detection (#977)

## Summary

- **Plan Mode workflow**: Toggle between Plan/Exec modes (Cmd+Shift+M).
In Plan mode, file edits restricted to `~/.mux/plans/<workspace-id>.md`.
Agent proposes plans via `propose_plan` tool for user review before
implementation.
- **External file change detection**: Timestamp-based polling detects
external edits to plan files, computes unified diffs, injects as
synthetic user messages to keep agent aware without breaking prompt
cache.
- **ProposePlan UI**: Markdown rendering, edit-in-editor button, "Start
Here" context reset, fresh content on window focus.
- **File edit refactoring**: Extracted shared execution pipeline,
runtime-aware path validation, custom diff utility replacing external
dependency.

## Test plan

- [ ]  Toggle Plan/Exec mode with keyboard shortcut
- [ ]  Verify file edits blocked for non-plan files in Plan mode
- [ ]  Edit plan externally, confirm agent sees changes on next query
- [ ]  Run make test for unit test coverage
- [ ] Run TEST_INTEGRATION=1 bun x jest
tests/ipc/fileChangeNotification.test.ts for integration tests

_Generated with `mux`_

Author: ThomasK33

docs/cli.mdx

@@ -102,3 +102,25 @@ Print the version and git commit:
 mux --version
 # v0.8.4 (abc123)
 ```
+
+## Debug Environment Variables
+
+These environment variables help diagnose issues with LLM requests and responses.
+
+| Variable                | Purpose                                                                                                                                                                 |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MUX_DEBUG_LLM_REQUEST` | Set to `1` to log the complete LLM request (system prompt, messages, tools, provider options) as formatted JSON to the debug logs. Useful for diagnosing prompt issues. |
+
+Example usage:
+
+```bash
+MUX_DEBUG_LLM_REQUEST=1 mux run "Hello world"
+```
+
+The output includes:
+
+- `systemMessage`: The full system prompt sent to the model
+- `messages`: All conversation messages in the request
+- `tools`: Tool definitions with descriptions and input schemas
+- `providerOptions`: Provider-specific options (thinking level, etc.)
+- `mode`, `thinkingLevel`, `maxOutputTokens`, `toolPolicy`

docs/docs.json

@@ -46,6 +46,7 @@
                   "init-hooks"
                 ]
               },
+              "plan-mode",
               "vscode-extension",
               "models",
               {

docs/plan-mode.mdx

@@ -0,0 +1,124 @@
+---
+title: Plan Mode
+description: Review and collaborate on plans before execution
+---
+
+Plan mode lets you review and refine the agent's approach before any code changes happen. Instead of diving straight into implementation, the agent writes a plan to a file, proposes it for your review, and waits for approval.
+
+## How It Works
+
+1. **Toggle to Plan Mode**: Press `Cmd+Shift+M` (Mac) or `Ctrl+Shift+M` (Windows/Linux), or use the mode switcher in the UI.
+
+2. **Agent Writes Plan**: In plan mode, all file edit tools (`file_edit_*`) are restricted to only modify the plan file. The agent can still read any file in the workspace to gather context.
+
+3. **Propose for Review**: When ready, the agent calls `propose_plan` to present the plan in the chat UI with rendered markdown.
+
+4. **Edit Externally**: Click the **Edit** button on the latest plan to open it in your preferred editor (nvim, VS Code, etc.). Your changes are automatically detected.
+
+5. **Iterate or Execute**: Provide feedback in chat, or switch to Exec mode (`Cmd+Shift+M`) to implement the plan.
+
+## External Edit Detection
+
+When you edit the plan file externally and send a message, mux automatically detects the changes and informs the agent with a diff. This uses a timestamp-based polling approach:
+
+1. **State Tracking**: When `propose_plan` runs, it records the plan file's content and modification time.
+2. **Change Detection**: Before each LLM query, mux checks if the file's mtime has changed.
+3. **Diff Injection**: If modified, mux computes a diff and injects it into the context so the agent sees exactly what changed.
+
+This means you can make edits in your preferred editor, return to mux, send a message, and the agent will incorporate your changes.
+
+## Plan File Location
+
+Plans are stored in a dedicated directory:
+
+```
+~/.mux/plans/<workspace-id>.md
+```
+
+The file is created when the agent first writes a plan and persists across sessions.
+
+## UI Features
+
+The `propose_plan` tool call in chat includes:
+
+- **Rendered Markdown**: View the plan with proper formatting.
+- **Edit Button**: Opens the plan file in your external editor (latest plan only).
+- **Copy Button**: Copy plan content to clipboard.
+- **Show Text/Markdown Toggle**: Switch between rendered and raw views.
+- **Start Here**: Replace chat history with this plan as context (useful for long sessions).
+
+## Workflow Example
+
+```
+User: "Add user authentication to the app"
+         │
+         ▼
+┌─────────────────────────────────────┐
+│  Agent reads codebase, writes plan  │
+│  to ~/.mux/plans/<id>.md            │
+└─────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────┐
+│  Agent calls propose_plan           │
+│  (plan displayed in chat)           │
+└─────────────────────────────────────┘
+         │
+         ├─────────────────────────────────┐
+         │                                 │
+         ▼                                 ▼
+┌─────────────────────┐       ┌─────────────────────────┐
+│  User provides      │       │  User clicks "Edit"     │
+│  feedback in chat   │       │  → edits in nvim/vscode │
+└─────────────────────┘       └─────────────────────────┘
+         │                                 │
+         │                                 │ (external edits)
+         │                                 ▼
+         │                    ┌─────────────────────────┐
+         │                    │  User sends message     │
+         │                    │  → mux detects changes  │
+         │                    │  → diff injected        │
+         │                    └─────────────────────────┘
+         │                                 │
+         ▼                                 ▼
+┌─────────────────────────────────────────────────────────┐
+│  Agent revises plan based on feedback                   │
+│  (cycles back to propose_plan)                          │
+└─────────────────────────────────────────────────────────┘
+         │
+         │  (when satisfied)
+         ▼
+┌─────────────────────────────────────┐
+│  User switches to Exec mode         │
+│  (Cmd+Shift+M)                      │
+└─────────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────┐
+│  Agent implements the plan          │
+└─────────────────────────────────────┘
+```
+
+## Customizing Plan Mode Behavior
+
+Use [scoped instructions](/instruction-files) to customize how the agent behaves in plan mode:
+
+```markdown
+## Mode: Plan
+
+When planning:
+
+- Focus on goals and trade-offs
+- Propose alternatives with pros/cons
+- Attach LoC estimates to each approach
+```
+
+## CLI Usage
+
+Plan mode is also available via the CLI:
+
+```bash
+mux run --mode plan "Design a caching strategy for the API"
+```
+
+See [CLI documentation](/cli) for more options.

src/browser/components/AIView.tsx

@@ -445,6 +445,17 @@ const AIViewInner: React.FC<AIViewProps> = ({
       )?.historyId
     : undefined;
 
+  // Find the ID of the latest propose_plan tool call for external edit detection
+  // Only the latest plan should fetch fresh content from disk
+  let latestProposePlanId: string | null = null;
+  for (let i = mergedMessages.length - 1; i >= 0; i--) {
+    const msg = mergedMessages[i];
+    if (msg.type === "tool" && msg.toolName === "propose_plan") {
+      latestProposePlanId = msg.id;
+      break;
+    }
+  }
+
   if (loading) {
     return (
       <div
@@ -557,6 +568,11 @@ const AIViewInner: React.FC<AIViewProps> = ({
                             workspaceId={workspaceId}
                             isCompacting={isCompacting}
                             onReviewNote={handleReviewNote}
+                            isLatestProposePlan={
+                              msg.type === "tool" &&
+                              msg.toolName === "propose_plan" &&
+                              msg.id === latestProposePlanId
+                            }
                           />
                         </div>
                         {isAtCutoff && (

src/browser/components/ChatInput/index.tsx

@@ -31,6 +31,8 @@ import {
 import {
   handleNewCommand,
   handleCompactCommand,
+  handlePlanShowCommand,
+  handlePlanOpenCommand,
   forkWorkspace,
   prepareCompactionMessage,
   executeCompaction,
@@ -933,6 +935,35 @@ export const ChatInput: React.FC<ChatInputProps> = (props) => {
           return;
         }
 
+        // Handle /plan command
+        if (parsed.type === "plan-show" || parsed.type === "plan-open") {
+          if (!api) {
+            setToast({
+              id: Date.now().toString(),
+              type: "error",
+              message: "Not connected to server",
+            });
+            return;
+          }
+          const context: CommandHandlerContext = {
+            api: api,
+            workspaceId: props.workspaceId,
+            sendMessageOptions,
+            setInput,
+            setImageAttachments,
+            setIsSending,
+            setToast,
+          };
+
+          const handler =
+            parsed.type === "plan-show" ? handlePlanShowCommand : handlePlanOpenCommand;
+          const result = await handler(context);
+          if (!result.clearInput) {
+            setInput(messageText); // Restore input on error
+          }
+          return;
+        }
+
         // Handle all other commands - show display toast
         const commandToast = createCommandToast(parsed);
         if (commandToast) {

src/browser/components/ChatInput/useCreationWorkspace.test.tsx

@@ -527,8 +527,8 @@ function createDraftSettingsHarness(
   }>
 ) {
   const state = {
-    runtimeMode: initial?.runtimeMode ?? ("local" as RuntimeMode),
-    defaultRuntimeMode: initial?.defaultRuntimeMode ?? ("worktree" as RuntimeMode),
+    runtimeMode: initial?.runtimeMode ?? "local",
+    defaultRuntimeMode: initial?.defaultRuntimeMode ?? "worktree",
     sshHost: initial?.sshHost ?? "",
     trunkBranch: initial?.trunkBranch ?? "main",
     runtimeString: initial?.runtimeString,

src/browser/components/Messages/MessageRenderer.tsx

@@ -8,6 +8,8 @@ import { ReasoningMessage } from "./ReasoningMessage";
 import { StreamErrorMessage } from "./StreamErrorMessage";
 import { HistoryHiddenMessage } from "./HistoryHiddenMessage";
 import { InitMessage } from "./InitMessage";
+import { ProposePlanToolCall } from "../tools/ProposePlanToolCall";
+import { removeEphemeralMessage } from "@/browser/stores/WorkspaceStore";
 
 interface MessageRendererProps {
   message: DisplayedMessage;
@@ -18,11 +20,21 @@ interface MessageRendererProps {
   isCompacting?: boolean;
   /** Handler for adding review notes from inline diffs */
   onReviewNote?: (data: ReviewNoteData) => void;
+  /** Whether this message is the latest propose_plan tool call (for external edit detection) */
+  isLatestProposePlan?: boolean;
 }
 
 // Memoized to prevent unnecessary re-renders when parent (AIView) updates
 export const MessageRenderer = React.memo<MessageRendererProps>(
-  ({ message, className, onEditUserMessage, workspaceId, isCompacting, onReviewNote }) => {
+  ({
+    message,
+    className,
+    onEditUserMessage,
+    workspaceId,
+    isCompacting,
+    onReviewNote,
+    isLatestProposePlan,
+  }) => {
     // Route based on message type
     switch (message.type) {
       case "user":
@@ -50,6 +62,7 @@ export const MessageRenderer = React.memo<MessageRendererProps>(
             className={className}
             workspaceId={workspaceId}
             onReviewNote={onReviewNote}
+            isLatestProposePlan={isLatestProposePlan}
           />
         );
       case "reasoning":
@@ -60,6 +73,22 @@ export const MessageRenderer = React.memo<MessageRendererProps>(
         return <HistoryHiddenMessage message={message} className={className} />;
       case "workspace-init":
         return <InitMessage message={message} className={className} />;
+      case "plan-display":
+        return (
+          <ProposePlanToolCall
+            args={{}}
+            isEphemeralPreview={true}
+            content={message.content}
+            path={message.path}
+            workspaceId={workspaceId}
+            onClose={() => {
+              if (workspaceId) {
+                removeEphemeralMessage(workspaceId, message.historyId);
+              }
+            }}
+            className={className}
+          />
+        );
       default:
         console.error("don't know how to render message", message);
         return null;

src/browser/components/Messages/ToolMessage.tsx

@@ -43,6 +43,8 @@ interface ToolMessageProps {
   workspaceId?: string;
   /** Handler for adding review notes from inline diffs */
   onReviewNote?: (data: ReviewNoteData) => void;
+  /** Whether this is the latest propose_plan in the conversation */
+  isLatestProposePlan?: boolean;
 }
 
 // Type guards using Zod schemas for single source of truth
@@ -116,6 +118,7 @@ export const ToolMessage: React.FC<ToolMessageProps> = ({
   className,
   workspaceId,
   onReviewNote,
+  isLatestProposePlan,
 }) => {
   // Route to specialized components based on tool name
   if (isBashTool(message.toolName, message.args)) {
@@ -193,6 +196,7 @@ export const ToolMessage: React.FC<ToolMessageProps> = ({
           result={message.result as ProposePlanToolResult | undefined}
           status={message.status}
           workspaceId={workspaceId}
+          isLatest={isLatestProposePlan}
         />
       </div>
     );