›_ Codex Issues
Codex Issues / #4897

Feature Request: Implement a "Plan Mode" for Complex Tasks

Resolved 💬 7 comments Opened Oct 7, 2025 by coygeek Closed Nov 15, 2025
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

What feature would you like to see?

I would like to propose the addition of a "Plan Mode" to the codex-cli. This mode would be designed to handle complex, multi-step coding tasks by first generating a comprehensive implementation plan for user review before any code is modified or commands are executed.

This feature is inspired by the highly effective "Plan Mode" in tools like Cursor and Claude Code.

The proposed workflow would be as follows:

  1. Initiation: The user provides a complex prompt (e.g., "Build a dashboard on the /agents page where I can see and comment on my teammates' background agents") and activates Plan Mode, perhaps with a flag like codex --mode plan.
  1. Analysis Phase (Read-Only): The agent uses read-only tools to analyze the existing codebase. It identifies relevant files, understands existing patterns (authentication, UI components, API routes), and determines the scope of the required changes. During this phase, it might ask the user clarifying questions to resolve ambiguities.
  1. Plan Generation: After its analysis, the agent generates a detailed, multi-step implementation plan. This plan should be presented to the user in a clear, reviewable format (e.g., as a temporary Markdown file). The plan would outline:
  • An overview of the approach.
  • Database schema changes and API endpoints to be created/modified.
  • Frontend components to be built or altered.
  • A to-do list of sequential tasks it will perform.
  1. User Review & Approval: The user can review this entire plan. They should have the ability to suggest edits or approve the plan as-is. This gives the user high-level control over the agent's strategy before any changes are committed.
  1. Autonomous Execution: Once the user approves the plan, codex-cli seamlessly transitions into an execution phase. It then autonomously works through the to-do list from the approved plan, creating files, applying edits, and running commands without requiring per-action approval for each step.

This creates a powerful "plan and execute" workflow, which is a significant improvement over the current, more granular interactive approval model for large-scale tasks.

Additional information

Motivation:
Currently, for complex tasks, the combination of --sandbox read-only and --ask-for-approval is the safest way to operate. However, this requires the user to approve every single file modification and command execution one-by-one. This can be tedious and doesn't give the user a holistic view of the agent's strategy. A Plan Mode would solve this by front-loading the strategic decisions and approvals, allowing for much smoother execution afterward.

Key Differentiator:
The most critical aspect of this feature is the seamless transition from an approved plan to autonomous execution. This is the primary functional gap between codex-cli's current capabilities and the workflow offered by competitors. The goal is to approve a strategy, not just individual actions.

Bonus Feature Idea:
Following Cursor's implementation, the generated plan files could optionally be saved to the workspace (e.g., in a .codex/plans/ directory). This would serve as excellent documentation of the changes made and could be used for team collaboration.

View original on GitHub ↗

7 Comments

github-actions[bot] contributor · 9 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #3268
  • #4118
  • #3869
  • #3599

Powered by Codex Action

coygeek · 9 months ago

Here is a potential high-level architectural plan to implement the "Plan Mode" feature.

***

1. Guiding Principles & Philosophy

The core idea is not to create an entirely new execution engine but to introduce a state machine within the existing codex-core::Session that orchestrates the agent's behavior through distinct phases. The approved plan will act as a "contract" that justifies a temporary, task-specific elevation of autonomy.

This approach leverages existing components (sandboxing, tool routing, TUI overlays) but reconfigures them dynamically based on the current phase of the Plan Mode workflow.

2. Architectural Phases

The workflow will be managed by a state machine within the Session struct, transitioning through the following phases:

  1. Analyzing: A read-only phase where the agent explores the codebase and formulates a plan.
  2. ReviewingPlan: The agent has submitted a plan, and the UI is awaiting user approval. The agent is idle.
  3. Executing: The user has approved the plan. The agent is granted more permissive settings to carry out the plan autonomously.

3. Component-Level Implementation Plan

Phase 1: Analysis & Plan Generation (Read-Only)
  1. Initiation (codex-tui):
  • A new flag, --plan, will be added to the codex CLI.
  • When present, the Tui will initialize the codex-core::Config to signal the start of a Plan Mode session.
  1. Core Session Configuration (codex-core):
  • The Session will enter the Analyzing state.
  • The initial TurnContext will be hardcoded with restrictive, safe settings:
  • sandbox_policy: SandboxPolicy::ReadOnly
  • approval_policy: AskForApproval::OnRequest (to allow clarifying questions if the agent gets stuck).
  1. Prompt Engineering (codex-core):
  • A new, dedicated prompt template will be used for the analysis phase. It will instruct the model to:
  • Operate in a read-only environment.
  • Thoroughly analyze the codebase using tools like read_file and list_dir.
  • Formulate a comprehensive, step-by-step implementation plan in Markdown.
  • Signal completion by calling a new, special tool: submit_plan_for_review(plan: string).
  1. New Tool for Plan Submission (codex-core):
  • A new internal tool, submit_plan_for_review, will be added to the tool registry.
  • Its handler will not execute a command but will instead emit a new EventMsg to the TUI: EventMsg::PlanReadyForReview { plan: String }. This serves as a robust, unambiguous signal to transition to the next phase.
Phase 2: User Review & Approval (TUI)
  1. TUI Plan Review Overlay (codex-tui):
  • The ChatWidget will listen for the PlanReadyForReview event.
  • Upon receiving it, it will open a full-screen modal overlay using the existing pager_overlay.rs.
  • The overlay will render the Markdown plan and present the user with approval options via a custom BottomPaneView with keybindings:
  • [Y]es, proceed: Approves the plan.
  • [N]o, cancel: Aborts the plan entirely.
  • [E]dit instructions: (Post-MVP) Denies the current plan and drops the user back to the composer to provide feedback for regeneration.
  1. Sending the Decision (codex-tui -> codex-core):
  • The user's choice will be sent back to the core as a new Op: Op::ApprovePlan { plan: String, decision: ReviewDecision }.
Phase 3: Autonomous Execution
  1. Core State Transition (codex-core):
  • The submission_loop in codex.rs will handle the Op::ApprovePlan.
  • If the decision is Approved, a crucial state transition occurs:
  1. The Session state transitions to Executing.
  2. The active TurnContext is updated with more permissive settings (e.g., sandbox_policy: WorkspaceWrite, approval_policy: Never). This dynamically grants the agent autonomy.
  1. Re-Prompting for Execution (codex-core):
  • The agent is re-prompted with a new set of instructions, including:
  • The user-approved plan.
  • A directive: "Your plan has been approved. You are now in execution mode with write access. Proceed to execute the plan step-by-step without further approval."
  • This kicks off the autonomous execution phase. The agent will now use tools like apply_patch and shell with its elevated permissions.
  1. Monitoring and Completion:
  • The TUI will continue to stream all events from the execution phase, allowing the user to monitor progress.
  • The task concludes when the agent emits TaskComplete, and the session state returns to normal.

---

Bonus Feature: Saving Plans

This can be implemented cleanly within the existing flow. When codex-core receives the Op::ApprovePlan, it will save the plan string to a file in a .codex/plans/ directory within the user's workspace before transitioning to the Executing state. This requires no new protocol additions.

Risks and Considerations

  • Model Deviation: The execution prompt must strongly instruct the agent to adhere strictly to the approved plan.
  • Error Handling: If a step fails during execution, the agent needs a robust strategy to self-correct. The on-failure approval policy might be a good model for this, even within the broader never approval context of the execution phase.
  • Plan Editing: A full interactive editor for the plan is complex. V1 will focus on the approve/deny cycle.
  • Context Window: Long plans and extensive code analysis could strain the context window. Existing compaction and context management strategies will be important.
coygeek · 9 months ago

@thomast8 I see you're working on the plan mode already.

Please review my proposed plan above and see if it helps.

bhack · 9 months ago

I think it will be also useful if for some planning bootstrap codex could really cooperate with PRO
https://github.com/openai/codex/issues/4863

rapind · 9 months ago

When I'm in plan mode (read-only in codex) I'm always making sure everything is recorded to a markdown document with checklists to mark progress during the implementation phase. It would be awesome if this sort of thing was automatically done (maybe with a confirmation to opt-in/out). It really helps when breaking up larger tasks that will span multiple sessions / contexts.

Maybe even consider using something like sqlite to persist plans to memory between sessions.

thomast8 · 9 months ago
When I'm in plan mode (read-only in codex) I'm always making sure everything is recorded to a markdown document with checklists to mark progress during the implementation phase. It would be awesome if this sort of thing was automatically done (maybe with a confirmation to opt-in/out). It really helps when breaking up larger tasks that will span multiple sessions / contexts. Maybe even consider using something like sqlite to persist plans to memory between sessions.

That seems like quite a big change. Ho w I did it, is I used the built-in todo tool to track the plan within the conversation

etraut-openai contributor · 8 months ago

I'm going to close this in favor of #2101