# Custom Modes in Cursor IDE ## Summary Custom modes extend Cursor's AI-powered IDE capabilities from general coding assistance to highly specialised workflow-optimised development tools. This beta feature allows developers to create tailored AI modes with specific tool combinations, behavioural instructions, and integration capabilities that extend far beyond the built-in Agent, Ask, and Manual modes. ## Details ## Understanding Custom Modes Custom modes represent a fundamental shift in how AI-assisted development works. Rather than using a one-size-fits-all approach, custom modes allow you to create specialised AI assistants that understand specific contexts, use only relevant tools, and follow particular behavioural patterns suited to different development tasks. Think of custom modes as creating different "personalities" for your AI assistant - each one trained for specific scenarios. You might have a cautious "Learning" mode that explains everything thoroughly, an aggressive "YOLO" mode that makes bold changes quickly, or a focused "Refactor" mode that only improves existing code structure without adding new functionality. ### How Custom Modes Work Technically Custom modes operate as specialised interfaces that combine Cursor's existing tools with custom behavioural instructions. The underlying architecture leverages Cursor's unified chat system with context management, codebase indexing, and rule integration, but adds a layer of specialisation through several key mechanisms. The system works by creating task-specific AI assistants that inherit all core Cursor capabilities while adding focused behavioural guidance. Unlike built-in modes with fixed configurations, custom modes offer granular control over tool permissions, behaviour patterns, and integration capabilities. ### Architecture and Integration Custom modes demonstrate deep integration with Cursor's broader ecosystem, functioning as specialised interfaces that can access and coordinate all platform capabilities while maintaining focused behaviour patterns. They leverage the same sophisticated context management system that powers all of Cursor's features, including full access to codebase indexing, semantic search, and the @-symbol functionality for precise code referencing. Importantly, Cursor rules apply comprehensively to custom modes through multiple layers. Project rules stored in the `.cursor/rules` directory, user rules as global settings, automatically generated memories from chat conversations, and legacy `.cursorrules` files all work together with custom mode instructions. Rules are automatically injected at the prompt level when custom modes activate, creating consistent guidance that combines with mode-specific instructions. ## Available Tools and Configuration Custom modes can selectively enable tools from Cursor's comprehensive toolkit, allowing you to create focused environments that only provide relevant capabilities for specific tasks. ### Search and Navigation Tools The search and navigation tools help custom modes understand and explore your codebase effectively. Codebase Search provides semantic search within indexed codebases, allowing the AI to find relevant code based on meaning rather than just keywords. Read File enables content reading with different limits depending on the mode (up to 750 lines in Max mode, 250 in standard), while List Directory explores directory structure without reading file contents. Grep offers exact keyword and pattern searches for precise text matching, Search Files provides fuzzy file name matching when you know roughly what you're looking for, and Web Search capabilities allow the AI to research external information when needed. ### Editing and Modification Tools The editing capabilities determine how actively a custom mode can modify your codebase. Edit & Reapply provides file modification with automatic application options, allowing modes to make changes with varying degrees of automation. Delete File capabilities can be enabled or disabled based on the mode's intended purpose and safety requirements. ### Execution and Automation Tools Terminal access enables command execution with monitoring and auto-run options, allowing modes to interact with build systems, run tests, or execute development workflows. MCP (Model Context Protocol) Servers provide external tool integration, enabling connections to databases, APIs, and third-party services through standardised protocols. ### Advanced Configuration Features Custom modes support sophisticated automation and integration patterns that extend beyond basic prompt engineering into enterprise-grade development environments. Auto-apply edits can automatically apply code changes without manual confirmation, while auto-run commands execute terminal commands automatically with customizable allow and deny lists. Guardrails provide protective measures for destructive operations, including delete file protection, MCP tools protection, and restrictions on operations outside the workspace. Per-mode model selection allows you to assign specific AI models based on the task requirements - you might use Claude 3.7 Sonnet for general reasoning tasks and o1 for complex planning scenarios. ## Practical Examples and Use Cases Understanding custom modes becomes much clearer when you see practical examples of how they solve real development challenges. ### Official Examples from Cursor The Cursor team provides several examples that demonstrate different approaches to tool selection and instruction crafting. Learn Mode focuses on detailed explanations with all search tools enabled but no automatic edit application, encouraging thorough understanding before code changes. This mode helps when you're exploring unfamiliar codebases or learning new technologies. Refactor Mode uses only the Edit & Reapply tool for focused code structure improvements without introducing new functionality or external file access. This creates a safe environment for improving existing code quality without the risk of unintended changes. Plan Mode combines Codebase Search, Read File, and Terminal tools to generate comprehensive implementation plans written to `plan.md` files without direct code modification. This mode excels at breaking down complex tasks into manageable steps before implementation begins. Debug Mode employs all search tools plus Terminal and Edit & Reapply for thorough issue investigation and targeted fixes with extensive context gathering. The comprehensive tool access allows for deep problem analysis and systematic resolution. ### Advanced Community Implementations The community has developed sophisticated implementations that demonstrate custom modes' full potential. The Memory Bank System creates a graph-based workflow architecture with four interconnected modes that work together as a coordinated development team. VAN mode handles project initialisation and complexity analysis, examining codebases to understand their structure and identifying potential challenges. PLAN mode focuses on task breakdown and strategic planning, creating detailed roadmaps for implementation. CREATIVE mode explores design possibilities using structured thinking methodologies, while IMPLEMENT mode systematically builds components with validation checkpoints. This system transforms custom modes from isolated tools into coordinated development workflow components with persistent state management and just-in-time rule loading. The modes maintain project-specific memory files and document design decisions in dedicated files, creating a comprehensive development environment. ### Creating an Effective Edit Mode One particularly useful example comes from the egghead.io tutorial, which demonstrates creating a custom "Edit" mode designed to overcome limitations of the standard inline edit functionality. This mode addresses a common frustration where Command+K can only edit code within its selection, while Command+I opens the full chat interface which can be overly conversational for simple refactors. The Edit mode configuration includes a custom keybinding (Command+E), enables Edit tools while disabling Run and MCP to maintain focus, activates auto-run for seamless operation, and uses specific instructions to minimise unnecessary conversation. The key instruction is: "You are strictly an editing tool. Do not explain anything, avoid all conversation. Your only task is to make the requested modifications to the code." This creates a more direct, less "chatty" AI editing experience that can perform refactors beyond the scope of the initial selection, such as hoisting variables to module scope or extracting constants, while maintaining focus on the editing task. ## Integration with MCP Servers Model Context Protocol servers provide plugin-like extensibility for custom modes, allowing them to interact with external systems through standardised protocols while maintaining security and performance boundaries. MCP servers are configured through global (`~/.cursor/mcp.json`) or project-specific (`.cursor/mcp.json`) files, support both stdio and SSE transport types, and provide access to up to 40 MCP tools simultaneously per session. Popular integrations include GitHub for repository management, Slack for team communication, various databases for data access, Notion for documentation, and browser automation for testing workflows. This integration capability transforms custom modes from internal development tools into comprehensive workflow orchestrators that can coordinate with your entire development ecosystem. ## Best Practices for Creation and Configuration Effective custom mode design requires strategic thinking about tool selection, focused instructions, and clear purpose definition based on community experience and technical constraints. ### Tool Selection Guidelines When configuring tools for your custom modes, consider the mode's primary purpose and potential safety implications. Planning modes should enable search and analysis tools like Codebase Search, Read File, Terminal, and List Directory while disabling editing capabilities to maintain focus on analysis rather than implementation. Implementation modes benefit from comprehensive tool access for maximum flexibility, allowing them to both understand the codebase and make necessary changes. Teaching modes should disable Edit & Reapply to prevent unwanted code changes while focusing on explanation and understanding. Security-focused modes typically need all tools enabled for thorough analysis capabilities. ### Instruction Crafting Principles Creating effective instructions for custom modes requires balancing specificity with flexibility. Start with clear role definition and expertise areas, helping the AI understand its primary function and domain knowledge. Specify constraints and behavioural limitations to prevent unwanted actions or responses that don't align with the mode's purpose. Include concrete examples of desired interactions to help the AI understand the expected communication style and response format. Keep instructions focused and specific rather than overly complex - verbose instructions can sometimes confuse the AI or lead to inconsistent behaviour. Use structured formats with sections for role definition, core principles, specific constraints, and practical examples. This organisation helps the AI parse and apply the instructions more effectively. ### Workflow Integration Strategies Successful custom mode implementation often involves thinking about how different modes work together in your development workflow. Consider implementing mode sequencing approaches that begin with analysis and initialisation phases, progress through structured planning stages, move to creative exploration and design, and conclude with systematic implementation phases. Context management becomes crucial for maintaining state across mode transitions. Maintain project-specific memory files such as `tasks.md`, `progress.md`, and `activeContext.md` to preserve important information. Document design decisions in dedicated creative files and use strategic file organisation to optimise context usage. Implement regular session resets to prevent performance degradation from accumulated context, and consider how different modes will hand off work to each other in your typical development process. ## Technical Limitations and Considerations Understanding custom modes' technical constraints and performance characteristics helps set realistic expectations and guides effective implementation strategies. ### Performance Considerations Custom modes inherit some performance challenges from Cursor's underlying architecture. Context management can be particularly challenging because standard models receive heavily pruned context, sometimes reducing 1000-line files to just 15 lines of relevant content, while Max models bypass these limitations but consume more resources. Memory consumption can become significant, with Cursor using approximately 4.3GB plus 6GB for helper processes, which can cause performance issues on systems with 16GB RAM or less. Long chat histories cause IDE sluggishness, requiring fresh session management to maintain optimal performance. File handling also presents some limitations. The apply-model becomes slow and error-prone with files exceeding 500 lines, agents sometimes fail to locate explicitly referenced files even when paths are provided clearly, and context windows grow over time requiring manual management to prevent degradation. ### Current Technical Limitations Custom modes are currently in beta, which means they have some configuration constraints and stability considerations. Mode creation must be done through the GUI interface, which has character limits on instruction text that can restrict complex configurations. Visual customisation options are limited to basic predefined icons, requiring emoji workarounds for better visual distinction between modes. There are practical limits on the number of modes you can create effectively - typically a maximum of 8 total modes including the 3 built-in modes and 5 custom ones. MCP tool integration has a maximum of 40 tools per session with some functionality limitations over SSH or remote environments. The rule system also has practical boundaries before the AI begins ignoring portions of extensive rule sets, and beta stability means features are subject to change with potential instability and version-specific issues. ### Future Development The roadmap for custom modes includes several confirmed upcoming features that will address current limitations and expand capabilities. Official `.cursor/modes.json` file support will enable project-level mode configuration and sharing, making it easier for teams to collaborate on standardised workflows. Enhanced sharing mechanisms will improve distribution and team collaboration capabilities, while performance optimisations promise better context management and resource utilisation. Improved user interfaces will enhance mode creation and management tools, making the system more accessible to a broader range of developers. ## Community Resources and Ecosystem The custom modes ecosystem benefits from active community development with comprehensive resources, templates, and collaborative frameworks that accelerate adoption and improve effectiveness. ### Major Community Repositories Several significant community projects provide frameworks and examples for custom mode implementation. The Cursor Memory Bank offers a modular development framework with specialised modes and workflow integration, demonstrating how custom modes can function as components of larger development systems rather than isolated tools. The BMad Cursor Master Workflow provides templates for automated rule generation and custom agent creation with support for `modes.json` configuration and character personality-based agents. This repository shows how to create sophisticated AI personalities that maintain consistent behaviour across different development scenarios. Community collections like "50+ Custom Modes" include ready-to-use configurations for diverse scenarios including system architecture analysis, bug hunting, security auditing, API development, and performance optimisation, providing proven starting points for common development tasks. ### Documentation and Learning Resources The ecosystem includes comprehensive documentation and tutorials ranging from official Cursor documentation with setup guides and examples to community-curated collections with practical implementations. Video tutorials and interactive walkthroughs help developers understand complex configuration scenarios, while blog posts share individual developer experiences and lessons learned. Collaborative development happens through GitHub repositories with custom mode examples and frameworks, community forums for discussion and troubleshooting, template libraries for reusable configurations, and best practices documentation based on collective experience from the broader community. ## Differences from Built-in Modes Understanding how custom modes differ from Agent, Ask, and Manual modes helps clarify when and why to create custom configurations versus using the built-in options. ### Functional Distinctions Built-in modes operate with fixed configurations that serve general purposes. Agent mode provides autonomous exploration with predetermined tool access and behaviour patterns suitable for general development tasks. Ask mode offers read-only codebase exploration with search-focused functionality, ideal for understanding and learning about code without making changes. Manual mode provides user-controlled editing with basic tool assistance for situations where you want full control over AI actions. Custom modes provide configurable specialisation that goes far beyond these fixed patterns. They offer selective tool access with granular control over which capabilities are available, behavioural customisation through specific instructions that override default AI behaviour, integration flexibility with configurable connections to external systems and workflows, and workflow optimisation through task-specific configurations that enhance productivity for particular scenarios. ### Technical Implementation Differences While custom modes leverage the same underlying chat system as built-in modes, they add specialised layers that enable more sophisticated workflows. Rule integration automatically applies project and user rules alongside mode-specific instructions, creating consistent guidance that combines multiple sources of behavioural direction. Context optimisation intelligently manages context based on the mode's specific purpose, tool orchestration provides sophisticated coordination of available tools based on mode configuration, and persistent specialisation maintains behavioural patterns across session boundaries. This technical foundation enables custom modes to function as true workflow optimisation tools rather than simple variations on existing functionality. ## 🔗 Related Resources ### Official Documentation - [Cursor Custom Modes](https://docs.cursor.com/chat/custom-modes) - Official documentation for creating and configuring custom modes - [Cursor Tools](https://docs.cursor.com/chat/tools) - Complete reference for all available tools that can be used in custom modes - [Model Context Protocol](https://docs.cursor.com/context/model-context-protocol) - Documentation for MCP server integration ### Community Collections - [50 Cursor Custom Modes for Various Development Scenarios](https://onedollarvps.com/blogs/cursor-custom-mode-settings) - Comprehensive collection of ready-to-use custom mode configurations - [Playbooks.com Cursor Modes](https://playbooks.com/modes) - Community-submitted custom modes and examples - [Cursor Custom Agents Rules Generator](https://github.com/bmadcode/cursor-custom-agents-rules-generator) - Framework for automated rule and agent generation ### Advanced Implementations - [Cursor Memory Bank](https://github.com/vanzan01/cursor-memory-bank) - Sophisticated workflow framework using custom modes for structured development - [Build a Better Edit Tool with Custom Modes](https://egghead.io/build-a-better-edit-tool-in-cursor-with-custom-agent-modes~21rr0) - Tutorial for creating focused editing workflows ### Related Cursor Features - [Agent Mode](https://docs.cursor.com/chat/agent) - Built-in autonomous development mode - [Ask Mode](https://docs.cursor.com/chat/ask) - Built-in read-only exploration mode - [Manual Mode](https://docs.cursor.com/chat/manual) - Built-in user-controlled mode - [Codebase Indexing](https://docs.cursor.com/chat/codebase) - Context system that powers custom mode search capabilities