Agent - Modes

Modes define how the AI assistant behaves and what capabilities it has. Each mode is configured with its own system instructions, tools, and optional file system.

Understanding Modes

A mode tells the AI:

What its purpose is (via system instructions)
Whether it has access to a virtual file system
Whether it can execute JavaScript
What custom tools are available
What category it belongs to

Different modes are suited for different tasks. You select a mode from the dropdown at the top of the Agent panel before starting a conversation.

Virtual File Systems

Some modes provide the AI with a virtual file system. This is not a real file system on your server. It is an abstraction that represents your content as files, because LLMs work well with file-based logic.

Different modes map different things to their virtual file systems:

Block Editor mode: WordPress blocks become virtual JSON files
Plugin mode: Plugin files in a staging area (saved to disk when you deploy)
Custom modes with properties: Form fields become virtual text files

When a mode provides a virtual file system, the AI uses these tools to interact with it:

read_file / read_files / read_all_files - Read file contents
write_file - Create or update a file
list_files - List all file paths
rename_file - Rename or move a file
create_folder - Create an empty folder
delete_path - Delete a file or folder
search_in_files - Search across files
find_and_replace - Find and replace text across files

The AI reads and writes to these virtual files, and the mode translates those changes into actual updates to your content (blocks, form fields, etc.).

JavaScript Execution

Some modes enable JavaScript execution. When enabled, the AI can run arbitrary JavaScript code directly in the browser using a special code block syntax:

            // This syntax tells the AI to execute the code
    ```js execute
    return { success: true, data: "result" };
    ```
  
                    
                Copy

JavaScript execution is useful for operations that cannot be represented as file changes, such as inserting new WordPress blocks or calling browser APIs.

Built-in Modes

Agent mode ships with several pre-configured modes:

Chat

A general AI assistant without any special capabilities. Good for brainstorming, writing, and conversations that do not need to modify anything.

No file system access
No JavaScript execution
No custom tools

Block Editor

An AI assistant specifically tuned for the WordPress block editor.

File system: Each block is a block.json file with its attributes and children
JavaScript execution: For inserting, deleting, and moving blocks
Custom tool: get_selected_block returns the currently selected block
Auto-detection: Automatically selected when in the block editor

The Block Editor mode allows the AI to read block content, modify attributes, and restructure your content while you see the changes in real-time.

Plugin Mode

Create, edit, and manage WordPress plugins through conversation.

File system: Real files in a staging directory (not live plugins)
Plugin toolbar: File browser, code editor, and deploy button
No JavaScript execution: All changes happen through file edits
Capability requirement: Requires usePluginMode permission

Changes made in Plugin Mode are stored in a staging area. You must explicitly deploy plugins for them to become active.

Custom Modes

Beyond the built-in modes, you can create your own through the UI or programmatically via the SDK.

Creating a Custom Mode (UI)

To create a custom mode:

Open Agent mode
Click the mode dropdown at the top
Click "+ Create Mode"
Configure your mode settings
Save the mode

Mode Configuration Options

Name and Description

Give your mode a clear name and description so you (and others, if shared) know what it is for.

System Instructions

Tell the AI what it should do and how it should behave in this mode. Be specific about the AI's role, tone, and any constraints.

For example, a content editing mode might have:

            You are a content editor helping improve blog posts.

    Guidelines:
    - Focus on clarity and readability
    - Maintain the author's voice
    - Suggest improvements rather than rewriting entirely
    - Point out grammar and spelling issues
    - Keep paragraphs concise
  
                    
                Copy

Properties (Form Field Mapping)

Properties allow your custom mode to interact with form fields on the current page. Each property maps a form field to a virtual file:

Name: Display name for the property
Description: Helps the AI understand what the field is for
Selector: CSS selector to find the form field (e.g., #post-title or textarea[name="content"])

When you add properties, the AI gains access to a file system. Each property becomes a file like properties/post_title.txt. The AI reads these files to see current values and writes to them to update the form fields.

If you have the "Share Modes" permission, you can share your custom modes with other users. Shared modes appear in the mode dropdown for all users who have Agent access.

To share a mode, open the mode settings and enable the share toggle.

Mode Best Practices

Be specific: Clear system instructions lead to better results
Start simple: Begin without properties and add them only if needed
Use properties wisely: Only map fields the AI actually needs to interact with
Test thoroughly: Try your mode with various scenarios before relying on it
Iterate: Refine your modes based on actual usage

Programmatic Mode Registration

For developers who want to register modes via code, see the Modes API documentation. Programmatic registration allows:

Shipping modes with your plugin
Auto-detection based on context
Custom file systems that map any data structure
Custom tools for specialized operations
JavaScript execution for DOM manipulation

Agent - Modes

Understanding Modes

Virtual File Systems

JavaScript Execution

Built-in Modes