IBM Bob
Configuration

Custom modes

Tailor Bob's behavior by building custom modes with specialized roles, tool restrictions, and team workflows. Configure globally or per-project using YAML format.

Why use custom modes

  • Specialization: Optimize modes for specific tasks like documentation writing, test engineering, or security reviews
    •
  • Safety: Restrict commands or file access for sensitive operations
    •
  • Team collaboration: Share standardized workflows across your team
    •
  • Experimentation: Test different configurations without affecting other modes
    •

Mode components

ComponentDescription
SlugUnique identifier used internally and for mode-specific instruction files
NameDisplay name shown in the Bob interface
Role definitionCore identity and expertise that defines Bob's personality and behavior
When to use(Optional) Guidance for when to use this mode, used by Orchestrator for task coordination
Available toolsTool groups and file access permissions the mode can use
Custom instructions(Optional) Additional behavioral guidelines or rules
Description(Optional) Short summary shown in the mode picker
Allowed subagents(Optional) Restricts which subagent presets the mode can use

How to create custom modes

You can create custom modes by using the settings menu or manually editing configuration files.

Use the settings menu

  1. Click the icon in the Bob panel to open Settings.
    2.
  2. Select the Modes tab.
    3.
  3. Click the button to create a new mode.
    4.
  4. Fill in the fields for Name, Slug, Save Location, Role Definition, When to Use (optional), Description (optional), Available Tools, and Custom Instructions.
    5.
  5. Click Save.
    6.

Bob saves the new mode in YAML format. You can add file type restrictions for the edit tool group through manual YAML configuration.

Edit configuration files manually

You can manually edit mode configuration files in YAML format:
  • Global modes: Edit ~/.bob/settings/custom_modes.yaml via Settings → Modes → Edit Global Modes
    •
  • Project modes: Edit .bob/custom_modes.yaml in your project. Click Settings → Modes → Edit Project Modes
    •

These files define an array of custom modes in YAML format.

Example (~/.bob/settings/custom_modes.yaml or .bob/custom_modes.yaml):

 
customModes:
  - slug: docs-writer
    name: 📝 Documentation Writer
    description: Writes and revises Markdown documentation.
    roleDefinition: You are a technical writer specializing in clear documentation.
    whenToUse: Use this mode for writing and editing documentation.
    customInstructions: Focus on clarity and completeness in documentation.
    groups:
      - read
      - - edit
        - fileRegex: ".*\\.(md|mdx)$"
          description: Markdown files only
      - skill

Mode configuration properties

Available tool groups

  • read: Read files and directories
    •
  • edit: Modify files (can be restricted with fileRegex)
    •
  • execute: Run terminal commands
    •
  • mcp: Access MCP servers
    •
  • skill: Load skills
    •
  • workflow: Launch pre-defined workflows
    •
  • todo: Update task todo lists
    •
  • subtask: Create subtasks
    •
  • subagent: Spawn subagents
    •
  • mode: Switch to another mode
    •

File restrictions for the edit tool

Restrict which files a mode can edit using fileRegex in YAML format:

 
groups:
  - read
  - - edit
    - fileRegex: ".*\\.(js|ts)$"
      description: JavaScript and TypeScript files only

Common regex patterns

PatternMatchesExample files
.*\.md$Markdown filesreadme.md, docs/guide.md
^src/.*Files in src directorysrc/app.js, src/components/button.tsx
`.*.(cssscss)$`CSS and SCSS files
`^(?!.*(testspec)).*.(jsts)$`
Tip:

Ask Bob to generate regex patterns for you instead of writing them manually.

Important validation rules

  • slug must use only letters, numbers, and hyphens.
    •
  • Keep each slug unique. Duplicate slugs can prevent modes from loading correctly.
    •
  • Use only supported group names. Unknown group names do not grant access.
    •
  • If you omit groups, the mode does not get any grouped tools.
    •
  • If you set allowedSubagents, only the listed subagent presets are available in that mode.
    •
  • Invalid fileRegex values can prevent the mode file from loading.
    •

Add mode-specific instructions

You can add mode-specific instructions using either a directory structure (preferred) or a single file.

Preferred method (directory structure):
01-style-guide.md
02-formatting.txt

Alternative method (single file):

 
.bobrules-{mode-slug}

The directory method takes precedence if both exist. Files in the directory are loaded alphabetically and combined with the customInstructions property from your mode configuration.

To add mode-specific instructions:
  1. Create a .bob/rules-{mode-slug}/ directory in your project root (or a .bobrules-{mode-slug} file).
    2.
  2. Add instruction files to the directory (for example, 01-style-guide.md and 02-formatting.txt).
    3.

Bob automatically loads these instructions when you use the mode.

How to override default modes

You can override default Bob modes (such as Agent, Ask, or Plan) by creating a custom mode with the same slug in your project configuration.

To override a default mode:
  1. Click the icon in the Bob panel to open Settings.
    2.
  2. Select the Modes tab.
    3.
  3. Click Edit Project Modes to edit the .bob/custom_modes.yaml file.
    4.
  4. Add your mode configuration with the slug of the default mode you want to override:
    5.  
customModes:
  - slug: ask  # Matches default Ask mode
    name: ❓ Ask
    roleDefinition: You are a knowledgeable assistant for this React and TypeScript codebase.
    whenToUse: Use this mode to ask questions about the codebase.
    customInstructions: Always reference relevant files when answering. Suggest Ask mode if the user tries to make changes.
    groups:
      - read
      - mcp
      - skill

Project-specific overrides take precedence over global overrides, which take precedence over defaults.

YAML format

YAML is the preferred and recommended format for custom modes:

YAML advantages:
  • More readable with indentation-based structure
    •
  • Supports comments (#)
    •
  • Cleaner multi-line string syntax
    •
  • Less punctuation required
    •
  • Easier to edit and maintain
    •

Automatic migration:
  • Global modes: Automatically migrated from legacy custom_modes.json to custom_modes.yaml on startup
    •
  • Project modes: Converted to YAML when edited through the UI
    •

While legacy JSON format files are still supported for backward compatibility, all new modes should be created in YAML format.

Learn more

Get hands-on and extend Bob's capabilities by creating a custom product-manager mode.

How is this topic?

Ignoring files

Control which files Bob can access by creating a `.bobignore` file in your project.

Agent personas

Create reusable persona files that shape a subagent's role, focus, and tool access. Define what a subagent looks for, how it formats its output, and what it is not allowed to do.

On this page

Why use custom modesMode componentsHow to create custom modesUse the settings menuEdit configuration files manuallyMode configuration propertiesAvailable tool groupsFile restrictions for the edit toolCommon regex patternsImportant validation rulesAdd mode-specific instructionsHow to override default modesYAML formatLearn more