Plan Mode - Autohand Docs

Overview

By default, Autohand interleaves planning and execution. Plan Mode changes this by introducing two distinct phases:

Planning phase — The agent analyzes your codebase with read-only tools (file reads, searches, git status) and produces a step-by-step plan. No files are modified.
Execution phase — After you approve the plan, the agent carries it out using write tools (file edits, commands, patches).

This gives you full visibility and control over what changes will be made before anything happens.

Activation

Toggle Plan Mode using either method:

# Slash command
/plan

# Keyboard shortcut
Shift+Tab

The prompt indicator changes to show the current phase:

[PLAN] — Agent is in the planning phase (read-only)
[EXEC] — Agent is executing the approved plan

Planning phase

During planning, the agent has access to read-only tools:

Allowed tools	Blocked tools
`read_file`	`write_file`
`search`	`apply_patch`
`list_tree`	`run_command`
`git_status`, `git_diff`, `git_log`	`delete_path`
`file_stats`	`rename_path`
`semantic_search`	`custom_command`

The agent produces a structured plan listing each file to modify, the nature of changes, and the reasoning behind them.

Plan acceptance

When the agent presents its plan, you choose how to proceed:

Option	Behavior
Auto-accept	Approve the plan and begin execution immediately
Manual approve	Review and confirm each step individually
Clear context and auto-accept	Reset conversation context and run the plan from a clean state

You can also reject the plan entirely and ask the agent to revise its approach.

When to use Plan Mode

Large refactors — Review the full scope of changes before any files are touched
Unfamiliar codebases — Let the agent explore and explain before making changes
Critical systems — Ensure the approach is sound before modifying production code
Learning — Understand the agent's reasoning process by seeing the plan first
Team review — Share the plan with teammates before execution

Tip: Plan Mode works well with /export — export the plan as markdown to share with your team before approving execution.

Example workflow

# 1. Enable plan mode
/plan
# [PLAN] mode activated

# 2. Give your instruction
"Refactor the authentication module to use JWT tokens"

# 3. Agent creates a plan (read-only):
#    - Reads src/auth/*.ts
#    - Searches for token references
#    - Checks dependencies in package.json
#    - Produces a step-by-step plan

# 4. Review and approve the plan

# 5. [EXEC] Agent executes:
#    - Installs jsonwebtoken package
#    - Modifies auth service
#    - Updates middleware
#    - Adds tests

Frequently asked questions

What is Plan Mode in Autohand?

Plan Mode separates thinking from doing. When activated, the agent explores your codebase using read-only tools and creates a step-by-step plan before making any changes. You review the plan and choose to auto-accept it, approve each step manually, or reject it entirely.

How do I activate Plan Mode?

Type /plan during a session or press Shift+Tab as a keyboard shortcut. The prompt indicator changes to [PLAN] to show the agent is in planning phase. After the plan is ready, you see acceptance options. The indicator changes to [EXEC] during execution.

When should I use Plan Mode?

Plan Mode is best for large refactors, unfamiliar codebases, and tasks where you want to review the approach before any files change. It is also useful for pair programming sessions where you want to guide the agent step by step rather than letting it act freely.