About AI Modes
Cheetah AI offers four distinct modes, each designed for specific types of development tasks. Understanding when to use each mode is key to getting the most out of the AI assistant. The modes differ in their capabilities, autonomy level, and the types of actions they can perform.
Choosing the right mode for your task ensures you get the best results while maintaining the level of control you need. Some tasks benefit from the AI’s full autonomy, while others require a more collaborative approach where you review each step before it’s executed.
Normal Mode
Normal mode is the simplest and most constrained mode, designed for quick questions, explanations, and lightweight assistance. In this mode, the AI answers based on the context of your open files and conversation history without making any changes to your codebase.
When to use Normal mode:
Normal mode is ideal when you need quick answers without the overhead of file operations or searches. Use it for conceptual questions about programming, explanations of code you’re looking at, syntax questions, or general development guidance. Since the AI doesn’t perform any actions in this mode, responses are fast and focused.
Capabilities:
In Normal mode, the AI can see your currently open files and any code you’ve selected or referenced in the conversation. It uses this context to answer questions and provide suggestions. However, it cannot read other files in your workspace, search your codebase, or make any modifications.
The AI will suggest code changes in the chat, but you’ll need to manually copy and apply them. This gives you complete control over what changes are made to your codebase.
Example prompts for Normal mode:
"What does this useEffect hook do?"
"Explain the difference between useMemo and useCallback"
"How should I structure this API response?"
"What's the best way to handle errors in async functions?"
Gather Mode
Gather mode extends Normal mode with powerful search and research capabilities. The AI can read files throughout your workspace, perform semantic code searches, and look up information on the web. This makes it ideal for exploring unfamiliar codebases and researching implementation approaches.
When to use Gather mode:
Use Gather mode when you need to understand how something works in your codebase before making changes. It’s particularly useful when onboarding to a new project, investigating bugs, or researching how to implement a feature. The AI can trace code paths, find related implementations, and gather context from multiple files.
Capabilities:
Gather mode gives the AI read access to your entire workspace. It can open and read any file, search for code using semantic understanding, and perform web searches to find documentation and solutions. However, it cannot modify files or run commands - it’s strictly read-only.
This read-only constraint makes Gather mode safe for exploration. You can ask the AI to investigate anything without worrying about unintended changes to your code.
Example prompts for Gather mode:
"Find all places where user authentication is handled"
"How does the payment flow work in this application?"
"Where is the database connection configured?"
"Search for how other projects implement rate limiting"
Plan Mode
Plan mode is designed for complex tasks that benefit from upfront planning and review. When you describe what you want to accomplish, the AI creates a detailed task list with specific implementation steps. You can review, modify, and approve the plan before any code is changed.
When to use Plan mode:
Use Plan mode for significant features, refactoring efforts, or any task that touches multiple files. The planning step helps ensure the AI understands your requirements correctly and gives you visibility into the implementation approach before any code is written.
Plan mode is also valuable when you want to learn from the AI’s approach. By reviewing the plan, you can understand how an experienced developer would break down the problem and implement each piece.
Capabilities:
In Plan mode, the AI first gathers context about your codebase and requirements, then generates a structured task list. Each task includes a description of what will be done and which files will be affected. You can edit tasks, reorder them, add new ones, or remove tasks you don’t want.
Once you approve the plan, you can execute tasks one at a time or let the AI run through them sequentially. After each task completes, you can review the changes before moving to the next step.
The planning workflow:
- Describe what you want to accomplish in natural language
- The AI analyzes your codebase and creates a task list
- Review the plan and make any adjustments
- Execute tasks individually or sequentially
- Review changes after each task completes
Example prompts for Plan mode:
"Plan how to add dark mode support to this application"
"Create a plan for migrating from REST to GraphQL"
"Plan the implementation of user role-based permissions"
"Plan how to add comprehensive error handling throughout the app"
Plan mode creates a checklist in the .cheetah/ folder that persists across sessions. You can return to a plan later and continue where you left off.
Agent Mode
Agent mode is the most powerful mode, giving the AI full autonomy to implement your requests end-to-end. The Agent can read and write files, run terminal commands, and iterate on solutions based on results. It breaks down complex requests into steps and implements each one while keeping you informed.
When to use Agent mode:
Use Agent mode for any task that requires multiple coordinated actions. This includes implementing features, fixing bugs, setting up new projects, running tests and fixing failures, and any workflow that would normally require you to perform multiple steps manually.
Agent mode excels at tasks where the AI needs to see the results of one action before deciding what to do next. For example, when fixing a bug, the Agent might read the error, examine the relevant code, make a fix, run tests to verify, and iterate if the tests still fail.
Capabilities:
Agent mode has full access to your workspace and development environment. It can:
- Read and write any file in your workspace
- Create new files and directories
- Delete files (with confirmation for important files)
- Run terminal commands and read their output
- Manage background processes like development servers
- Search your codebase semantically and by content
- Search the web for documentation and solutions
- Remember context and preferences across the conversation
How Agent mode works:
When you submit a request, the Agent analyzes what needs to be done and begins implementing it step by step. You’ll see each action as it happens - file reads, edits, command executions, and search results. The Agent explains its reasoning and keeps you informed about progress.
If something goes wrong, the Agent can recognize errors and attempt to fix them. For example, if a code change introduces a syntax error, the Agent will see the error when it runs or compiles the code and can automatically correct it.
Example prompts for Agent mode:
"Add a contact form with email validation and submit to our API"
"Create a user authentication system with JWT tokens"
"Fix all TypeScript errors in the project and run the tests"
"Set up ESLint and Prettier with our team's configuration"
Agent mode can modify your files and execute commands. Always review changes in your git diff before committing. The AI creates checkpoints so you can revert if needed.
Switching Modes
You can switch modes at any time using the mode selector dropdown in the chat panel or with keyboard shortcuts. Switching modes doesn’t clear your conversation history, so you can start in Gather mode to understand a problem, then switch to Agent mode to implement the solution.
| Mode | macOS | Windows/Linux |
|---|
| Normal | Cmd+1 | Ctrl+1 |
| Gather | Cmd+2 | Ctrl+2 |
| Plan | Cmd+3 | Ctrl+3 |
| Agent | Cmd+4 | Ctrl+4 |
Mode Comparison
This table summarizes the capabilities available in each mode:
| Feature | Normal | Gather | Plan | Agent |
|---|
| Read open files | Yes | Yes | Yes | Yes |
| Read any file | - | Yes | Yes | Yes |
| Search codebase | - | Yes | Yes | Yes |
| Web search | - | Yes | Yes | Yes |
| Edit files | - | - | Yes | Yes |
| Run commands | - | - | Yes | Yes |
| Create task lists | - | - | Yes | Yes |
| Autonomous execution | - | - | - | Yes |
Best Practices
Start with Gather for unfamiliar code - When working with a new codebase or unfamiliar area, use Gather mode first to understand the architecture and existing patterns. This context helps you write better prompts when you switch to Agent mode.
Use Plan for complex features - For features that touch multiple files or require careful coordination, Plan mode helps you think through the implementation before committing to changes. You can catch potential issues in the planning phase.
Agent mode for iterative tasks - Agent mode excels at tasks that require running commands, checking results, and iterating. Let it handle the feedback loop of make change, test, fix, repeat.
Normal mode for quick answers - Don’t overcomplicate simple questions. Normal mode is fast and efficient for explanations and quick guidance when you don’t need file access or search capabilities.
