Plan mode

Plan mode lets the model think and propose changes WITHOUT being able to write files, run shell commands, or modify state. When you're confident in the plan, switch to act mode to execute. It's the pre-flight checklist for anything you'd hate to undo.

Two modes, one toggle: plan (read-only) and act (default, full registry). The model can read code, grep, glob, and look at the repo map — but the write tools (str_replace, create_file, bash) are gated off until you're back in act.

When to use plan mode

• Risky migrations. Database schema changes, cross-cutting renames, anything where one bad str_replace ruins your afternoon.
• Unfamiliar codebases. First day on a repo? Let Fred read it cold and write you the map. You read the plan, ask follow-ups, then unleash.
• Large refactors you want a step-by-step for. Splitting a file into three? Extracting a module? The plan is the contract you both sign before any keystrokes hit disk.
• Auditing what an agent would do before letting it loose. Plan mode is the closest thing to a dry-run.

How to enter

At startup, pass --plan:

fred --plan

Mid-session, use the slash command or the keybinding:

> /mode plan
> /mode act
> /mode toggle    # flip whichever way

Or just press Shift+Tab at the prompt — it cycles plan ↔ act. Same key both directions; the status line tells you where you landed.

What changes in plan mode

• Write tools (str_replace, create_file, bash) are disabled. The dispatcher rejects them with a model-readable error: Error: tool bash not available in plan mode. Use ExitPlanMode to continue.
• Read tools (view, grep, glob, repo_map) work normally. The model has the same visibility into your codebase it always has.
• The todo_write tool stays on so the model can sketch a plan as a todo list while it thinks.
• The system prompt steers the model toward writing a plan, not executing it. You'll see prose, file lists, and proposed diffs — not actions.
• The agent uses a scratch path at .dsc/.plan_<uuid> to draft the plan. It's safe to inspect but Fred manages it.

Exiting plan mode

The model has a special tool — exit_plan_mode — it can invoke when it's done planning. It takes a one-line summary of the plan it's committing to and flips the session back to act on its own. You'll see a confirmation:

Plan accepted; switching to act mode.

Refactor auth.py: extract token-refresh into helpers.refresh_token, add
unit tests, update callers in api/views.py.

You can also flip manually with /mode act or another tap of Shift+Tab. Either way, the next tool call runs against the full registry.

Status indicator

The status line shows [plan] when plan mode is active. The startup banner prints PLAN MODE — Shift+Tab cycles in red so you don't forget which seat you're in. If you see neither, you're in act.

Related

Slash commands — the full command list including /mode and /think. Permissions & --yolo — the other orthogonal axis for managing risk.