Custom modes

You can create custom modes to tailor Bob's behavior to specific tasks or workflows. Custom modes in Bob Shell work similarly to Bob IDE modes.

Why use custom modes in Bob Shell

  • Shell-optimized workflows: Create modes designed specifically for terminal-based development tasks
  • Command-line safety: Restrict modes to safe operations when working in production environments
  • Environment-specific behavior: Configure modes that adapt to different shell environments
  • Automation-friendly: Design modes that work seamlessly in both interactive and non-interactive sessions
  • Team standardization: Share shell-specific modes across your team for consistent workflows

What's included in a custom mode

Custom modes in Bob Shell use the same core structure as Bob IDE modes:

PropertyDescriptionShell-Specific Considerations
slugUnique internal identifierUsed in command-line arguments:
bob --chat-mode=my-mode
nameDisplay name in the UIShown in interactive mode's mode selector
descriptionShort description shown in the mode selectorBriefly explain your mode's purpose
roleDefinitionCore identity and expertiseShould consider shell context and command-line workflows
groupsAllowed toolsets and file accessCommand running permissions are critical in shell environments
whenToUseMode selection guidanceHelps Bob Shell choose appropriate modes for tasks
customInstructionsSpecific behavioral guidelines, or rules for the modeCan reference Bob Shell development patterns

Available tools

Available tool groups

  • read: Read files and directories
  • edit: Modify files (can be restricted with fileRegex)
  • browser: Use browser automation
  • command: Execute terminal commands
  • mcp: Access MCP servers

Creating custom modes

Configuration files

Bob Shell uses the same configuration format as Bob IDE, supporting both YAML (preferred) and JSON formats.

Global modes

Create or edit ~/.bob/custom_modes.yaml for modes available across all projects:

customModes:
  - slug: shell-debug
    name: 🐛 Shell Debugger
    roleDefinition: >-
      You are a debugging specialist focused on command-line troubleshooting.
      You excel at analyzing shell output, environment variables, and system logs.
    whenToUse: Use for debugging shell scripts, command failures, and environment issues.
    customInstructions: |-
      When debugging:
      - Always check environment variables first
      - Examine command exit codes
      - Review relevant log files
      - Test commands in isolation before suggesting fixes
    groups:
      - read
      - command
      - browser

Project-specific modes

Create or edit .bob/custom_modes.yaml in your project root:

customModes:
  - slug: deploy-helper
    name: 🚀 Deployment Assistant
    roleDefinition: You are a deployment specialist for this project's infrastructure.
    whenToUse: Use for deployment tasks, infrastructure changes, and release management.
    customInstructions: |-
      Deployment guidelines:
      - Always verify the target environment before running commands
      - Check for running processes that might be affected
      - Validate configuration files before applying changes
      - Create backups before destructive operations
    groups:
      - read
      - - edit
        - fileRegex: \.(yaml|yml|sh|env)$
          description: Configuration and script files only
      - command

Command-line mode selection

Specify a mode when starting Bob Shell:

# Start Bob Shell in a specific mode
bob --chat-mode=shell-debug

# Combine with other options
bob --chat-mode=deploy-helper --sandbox

Interactive mode switching

In interactive mode, switch modes using slash commands:

# Switch to a custom mode
/mode shell-debug

# Or use the mode's slug directly
/shell-debug

Shell-specific configurations

Production safety mode

Create a safety-focused mode for production environments:

customModes:
  - slug: prod-ops
    name: 🔒 Production Operations
    roleDefinition: >-
      You are a production operations specialist with a strong focus on safety.
      You never run destructive commands without explicit confirmation.
    whenToUse: Use when working with production systems or sensitive environments.
    customInstructions: |-
      Production safety rules:
      - NEVER run destructive commands without explicit user confirmation
      - Always verify the target environment before any operation
      - Suggest dry-run options when available
      - Check for active connections or processes before changes
      - Recommend backup procedures before modifications
    groups:
      - read
      - browser
      # Note: No edit or command groups for maximum safety

Script development mode

Create a mode for shell script development:

customModes:
  - slug: script-dev
    name: 📜 Script Developer
    roleDefinition: >-
      You are a shell scripting expert specializing in bash, zsh, and POSIX-compliant scripts.
    whenToUse: Use for creating, debugging, or improving shell scripts.
    customInstructions: |-
      Shell scripting best practices:
      - Use shellcheck-compliant syntax
      - Include proper error handling with set -e and set -u
      - Add usage documentation at the top of scripts
      - Quote variables to prevent word splitting
      - Provide exit codes for different error conditions
    groups:
      - read
      - - edit
        - fileRegex: \.(sh|bash|zsh)$
          description: Shell script files only
      - command

Command running permissions

Restricting command access

Control which commands a mode can run by omitting the command group:

customModes:
  - slug: safe-reviewer
    name: 👀 Safe Code Reviewer
    roleDefinition: You are a code reviewer focused on analysis, not modification.
    whenToUse: Use for code reviews and analysis without making changes.
    groups:
      - read
      - browser
      # No command or edit groups - read-only mode

Allowing specific commands

Use Bob Shell's allowed tools configuration with custom modes in your settings file:

{
  "tools": {
    "allowed": [
      "run_shell_command(git status)",
      "run_shell_command(git log)",
      "run_shell_command(git diff)"
    ]
  }
}

Interactive vs non-interactive behavior

Designing for both modes

Create modes that work well in both interactive and non-interactive sessions:

customModes:
  - slug: test-runner
    name: 🧪 Test Runner
    roleDefinition: >-
      You are a testing specialist who runs and analyzes test suites.
      You adapt your output based on the running context.
    whenToUse: Use for running tests, analyzing test results, and debugging test failures.
    customInstructions: |-
      Testing guidelines:
      - In interactive mode: Provide detailed explanations and suggestions
      - In non-interactive mode: Focus on concise, actionable output
      - Always report test results clearly
      - Suggest fixes for failing tests
    groups:
      - read
      - command

Non-interactive usage

Use modes in non-interactive mode:

# Use a mode designed for automation
bob --chat-mode=test-runner -p "Run the test suite and report failures"

# Combine with output processing
bob --chat-mode=test-runner -p "Run tests" --hide-intermediary-output > results.txt

Mode-specific instructions via files

Directory-based instructions

Create mode-specific instruction files in .bob/rules-{mode-slug}/:

01-environment-checks.md
02-common-issues.md
03-debugging-steps.md
custom_modes.yaml

Example instruction file (.bob/rules-shell-debug/01-environment-checks.md):

# Environment Debugging Checklist

When debugging shell issues, always check:

1. **Environment Variables**: PATH, SHELL, TERM, and application-specific variables
2. **Shell Configuration**: .bashrc, .zshrc, .profile files
3. **System State**: Current working directory, file permissions, disk space
4. **Command Availability**: Use `command -v <cmd>` to verify commands exist

Single file instructions (fallback)

Alternatively, use a single file .bobrules-{mode-slug} in your workspace root.

Configuration precedence

Mode configurations are applied in this order:

  1. Command-line arguments (--chat-mode=mode-slug)
  2. Project-level modes (.bob/custom_modes.yaml
  3. User-level modes (~/.bob/custom_modes.yaml)
  4. System-level modes (platform-specific locations)
  5. Default modes

Sandboxing with custom modes

Combine custom modes with Bob Shell's sandbox feature for safe experimentation:

# Start a custom mode in sandbox
bob --chat-mode=script-dev --sandbox

# Use with Docker sandbox
bob --chat-mode=deploy-helper --sandbox

Migrating modes from Bob IDE

Key differences

When migrating custom modes from Bob IDE to Bob Shell:

AspectBob IDEBob Shell
UI interactionVisual interface with panelsTerminal-based interface
File editingIn-editor diffs and previewsCLI diff view or external editor
Command runningIntegrated terminalDirect shell running
Mode switchingUI dropdown or slash commandsSlash commands or CLI arguments
ConfigurationSettings UI + filesConfiguration files only

Adaptation checklist

When adapting Bob IDE modes for Bob Shell:

  • Review roleDefinition for shell-specific context
  • Update customInstructions to reference command-line workflows
  • Consider command running safety in groups configuration
  • Test mode in both interactive and non-interactive sessions
  • Verify file path handling works in shell context
  • Test with sandbox mode if applicable

Example migration

Original Bob IDE mode:

customModes:
  - slug: code-reviewer
    name: 👀 Code Reviewer
    roleDefinition: You are a code reviewer who provides detailed feedback.
    groups:
      - read
      - browser

Adapted for Bob Shell:

customModes:
  - slug: code-reviewer
    name: 👀 Code Reviewer
    roleDefinition: >-
      You are a code reviewer who provides detailed feedback.
      You work efficiently in terminal environments and provide clear, actionable suggestions.
    whenToUse: Use for code reviews, pull request analysis, and code quality checks.
    customInstructions: |-
      Code review guidelines:
      - Provide feedback in a structured format suitable for terminal output
      - Reference specific line numbers and file paths
      - Suggest concrete improvements with examples
      - Format output for easy parsing if used in non-interactive mode
    groups:
      - read
      - command  # Added for git operations
      - browser
How is this topic?