> ## Documentation Index
> Fetch the complete documentation index at: https://hercules.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Modes

> Plan, Debug, and Build modes optimize Hercules for specific tasks. Plan for large features, Debug for bugs, Build for general use.

Agent modes optimize Hercules for completing specific tasks.

1. **Plan mode** is best for building features and making large changes
2. **Debug mode** is best for fixing bugs
3. **Build mode** is the best for small fixes and general use cases

Switch modes by selecting the mode toggle at the bottom of the chat input

<div className="screenshot peach">
  <img src="https://mintcdn.com/zeus-0f6dadbf/kr00GTozD-mEFvWE/images/ai/modes.png?fit=max&auto=format&n=kr00GTozD-mEFvWE&q=85&s=6450cfbb17c480cb44f0cfd89ef0c0d2" alt="Agent mode selector showing Build, Plan, and Debug modes" width="938" height="510" data-path="images/ai/modes.png" />
</div>

### Quick summary

| Mode           | When to use                                                                                  | How it works                                                                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Plan mode**  | <ul><li>Building large/complex features</li><li>Making major app changes</li></ul>           | <ol><li>Interviews you</li><li>Clarifies your goals/intent</li><li>Creates a detailed implementation plan</li></ol>                           |
| **Debug mode** | <ul><li>Part of your app isn't working</li><li>Build mode isn't doing what you ask</li></ul> | <ol><li>Interviews you</li><li>Investigates possible causes</li><li>Proposes hypotheses</li><li>Attempts fixes in most likely order</li></ol> |
| **Build mode** | <ul><li>General use</li><li>Building small features</li></ul>                                | More eager. Prioritises building rather than asking clarifying questions.                                                                     |

## Build Mode

<Tip>**Use for:** small changes / fixes, general Q\&A</Tip>
Build mode is Hercules' default mode. The Agent biases towards making changes immediately. It will
still plan, research, and ask questions if needed, however, less so than the other modes.

**Examples**:

* "Change the button color to blue"
* "Add a loading spinner to the submit button"
* "Remove the subtitle under the 'about us' section"

## Plan Mode

<Tip>**Use for:** Large/complex features, unclear requirements</Tip>

Plan Mode interviews you about your intent and goals, creates product milestones, confirms your approval, and then puts together a detailed engineering implementation plan before writing any code. It then switches back to Build mode to execute the plan.

Plan mode ends up being cheaper and faster than just using Build mode. It plans ahead meaning it gives you a more accurate product result and avoids engineering implementation errors.

**Examples**:

* "Build a CRM for my business"
* "Create an admin dashboard with user management and analytics"
* "Add a booking system with calendar and availability"

<div className="screenshot fire">
  <img src="https://mintcdn.com/zeus-0f6dadbf/kr00GTozD-mEFvWE/images/ai/modes-plan.png?fit=max&auto=format&n=kr00GTozD-mEFvWE&q=85&s=a3c367d04312c94d876b7bfae2e24871" alt="Plan mode for speccing out new features" width="964" height="346" data-path="images/ai/modes-plan.png" />
</div>

## Debug Mode

<Tip>
  **Use when:** app functionality isn't working as expected or Build mode is unable to resolve an
  issue
</Tip>

Debug mode interviews you to understand the bug you are experiencing, clarifies how it should work instead, comes up with hypotheses for what is causing this issue by deeply searching the codebase, then implements a fix for each hypothesis one-by-one until the issue is solved.

Debug mode ends up being cheaper and faster than just using Build mode. It deeply researches the codebase to find the most likely cause for the issue which means its first fix is most likely correct.

**Examples:**

* "The checkout button doesn't open when I click it"
* "The form submits but the data doesn't save"
* "When I try to go to the dashboard it redirects me to the home page"
* "I can't login"
* "Images aren't loading on the /product page"

<div className="screenshot ocean">
  <img src="https://mintcdn.com/zeus-0f6dadbf/kr00GTozD-mEFvWE/images/ai/modes-debug.png?fit=max&auto=format&n=kr00GTozD-mEFvWE&q=85&s=b790383e9d5a3a2460d695b61c70f8d2" alt="Debug mode for fixing issues" width="962" height="340" data-path="images/ai/modes-debug.png" />
</div>

### FAQ

<AccordionGroup>
  <Accordion title="How do I switch modes?">
    Switch modes at any time by clicking the mode selector in the chat interface or by asking the
    Agent to switch modes. Your conversation context is preserved when switching.
  </Accordion>

  <Accordion title="What is the fastest workflow for big features?">
    Start with Plan mode to define requirements and milestones. This approach is faster and more
    accurate than just using build mode then course-correcting later.
  </Accordion>

  <Accordion title="Do I have to use Plan mode to build features?">
    No. Plan mode is optional but recommended for complex features. If your request is
    straightforward, Build mode works well.
  </Accordion>

  <Accordion title="Why is Debug mode cheaper?">
    Debug mode investigates before making changes. This reduces wasted effort from wrong guesses.
  </Accordion>

  <Accordion title="Can the Agent change modes automatically?">
    The Agent may suggest switching modes when it detects a mismatch. For example, if you describe a
    bug while in Build mode, it might recommend switching to Debug mode.
  </Accordion>
</AccordionGroup>