Overview

Roo Code (open-source, Apache 2.0, ~13k stars) implements a Custom Modes system that lets users switch the AI agent between named profiles, each combining a persona/role definition, tool access restrictions, file access restrictions, and custom instructions. This is one of their most differentiated features and directly applicable to Hermes Agent.

Currently, Hermes has personality switching (/personality), per-project SOUL.md, and platform-based toolsets — but these are disconnected. A mode system would unify them: one switch changes the agent's persona, what tools it can use, what files it can touch, and what instructions it follows.

Source: Roo Code Custom Modes docs · GitHub repo · Mode marketplace

Research Findings

How Roo Code Modes Work

Each mode in Roo Code is defined by a ModeConfig structure:

customModes:
  - slug: docs-writer          # unique identifier
    name: "📝 Documentation Writer"
    description: "Specialized for technical documentation"
    roleDefinition: "You are a technical writer specializing in clear documentation..."
    groups:                     # tool access restrictions
      - read                    # full read access
      - - edit                  # edit restricted to...
        - fileRegex: \.(md|mdx)$  # ...only markdown files
          description: Markdown files only
    whenToUse: "Use for documentation tasks"  # guidance for orchestrator
    customInstructions: "Always use active voice..."

Tool Groups restrict which tools the agent can access:

• read: read_file, search_files, list_files, codebase_search
• edit: apply_diff, write_to_file
• command: execute_command
• mcp: MCP server tools
• modes: switch_mode, new_task

5 Built-in Modes:

1. Architect — read everything, edit only .md files, no terminal commands. Plans without modifying code.
2. Code — full access to all tool groups. Implements, refactors, optimizes.
3. Ask — read-only + MCP. Explains code, answers questions. Cannot modify anything.
4. Debug — full access. Diagnoses failures, adds logging, proposes fixes.
5. Orchestrator — NO tool groups (only always-available tools like new_task, attempt_completion). Decomposes complex tasks and delegates to specialized modes.

Key Design Decisions:

• File regex restrictions: The edit group can include a fileRegex that restricts what files the mode can modify (e.g., architect can only edit .md files). Violations are caught by a validation layer before tool execution.
• Always-available tools: Some tools bypass mode restrictions entirely (e.g., attempt_completion, switch_mode, todo list).
• Per-project modes: A .roomodes file in the workspace root defines project-specific modes that override global ones.
• Mode rules files: Each mode can have detailed instruction files in .roo/rules-{slug}/ directories, loaded recursively.
• Sticky models: Each mode remembers its last-used LLM model, enabling automatic model switching per task type.
• Tool validation: A validateToolUse() function checks mode permissions before every tool call, throwing FileRestrictionError for violations.

How Mode Switching Works

Roo Code offers two switching mechanisms:

1. switch_mode — Changes mode in-place within the same conversation. The task continues with new tool restrictions and persona.
2. new_task — Creates a child task in a different mode with context isolation (the "Boomerang" pattern — covered in Feature: Multi-Agent Architecture — Orchestration, Cooperation, Specialized Roles & Resilient Workflows #344).

The switch_mode tool calls handleModeSwitch() which updates the system prompt, tool filtering, and task metadata. There's a 500ms delay after switch for changes to take effect.

Tool filtering happens via filterNativeToolsForMode() which:

1. Gets all tools for the mode's groups
2. Applies model-specific customization (some models don't support certain tools)
3. Removes disabled tools from settings
4. Only sends the filtered tool definitions to the LLM API

Current State in Hermes Agent

Hermes has several related but disconnected mechanisms:

The gap: These exist as independent systems. There is no way to say "switch to Architect mode" and have the agent simultaneously adopt a planning-focused persona, lose access to file editing (except .md), and gain architecture-specific instructions — all as one atomic switch.

Relevant files:

• cli.py lines 176-191, 1545-1575 — personality system
• prompt_builder.py lines 309-333 — SOUL.md loading
• toolsets.py — tool group definitions and resolution
• run_agent.py — ephemeral system prompts

Implementation Plan

Skill vs. Tool Classification

This should be a core codebase change, not a skill or a tool. It requires:

• Modifying the prompt construction pipeline (prompt_builder.py) to inject mode-specific personas and instructions
• Modifying the tool registration system (toolsets.py, tools/registry.py) to filter tools based on active mode
• Adding tool validation to enforce restrictions before tool execution
• Extending the config system for mode definitions
• Adding CLI commands (/mode) for switching
• Per-project mode config file support

What We'd Need

1. Mode definition schema — YAML config format for defining modes (persona, tool groups, file restrictions, instructions)
2. Mode registry — Load modes from global config + per-project .hermes-modes.yaml
3. Tool filtering layer — Filter available tools based on active mode before API calls
4. Tool validation layer — Validate tool calls against mode restrictions before execution
5. Mode switching command — /mode <name> CLI command + switch_mode tool for agent self-switching
6. Prompt injection — Mode's roleDefinition and customInstructions injected into system prompt

Phased Rollout

Phase 1: Core Mode System

• Mode definition schema in YAML (slug, name, roleDefinition, toolGroups, customInstructions)
• Global mode config in ~/.hermes/config.yaml under agent.modes
• /mode CLI command to list and switch modes
• 4 built-in modes: Code (full access), Architect (read + md-only edit), Ask (read-only), Debug (full + debug instructions)
• Tool filtering in model_tools.py / run_agent.py based on active mode
• System prompt modification to include mode roleDefinition

Phase 2: Advanced Restrictions & Per-Project

• File regex restrictions (e.g., mode can only edit *.md files)
• Tool validation layer with clear error messages when mode restricts an action
• Per-project .hermes-modes.yaml file support (overrides global)
• Mode-specific instruction files (.hermes/rules-{mode}/)
• Mode persistence per session (remember active mode across restarts)
• Per-mode model preferences (e.g., Architect uses a reasoning model, Code uses a fast model)

Phase 3: Mode Ecosystem

• switch_mode tool so the agent can switch its own mode mid-conversation
• Mode export/import for sharing
• Community modes in the Skills Hub
• Gateway platform support (mode switching via Telegram/Discord commands)
• Mode-aware sub-agent delegation (delegate_task inherits or overrides mode)

Pros & Cons

Pros

• Safety — Read-only or restricted modes prevent accidental destructive changes during planning/review
• Focus — Restricting tools reduces hallucination and off-task behavior (Roo Code's primary motivation for modes)
• Token efficiency — Fewer tool definitions in the system prompt = more context for actual work
• Workflow flexibility — Users can define project-specific modes (e.g., "frontend-only" mode that can't touch backend code)
• Composability — Unifies existing disconnected systems (personality + toolsets + SOUL.md) into one coherent concept
• Already proven — Roo Code's implementation is battle-tested with a large community

Cons / Risks

• Complexity — Adds a new abstraction layer that all tool calls must pass through
• Discovery — Users need to know modes exist and when to use them; poor defaults could frustrate
• Override friction — If the agent needs a tool its mode doesn't allow, the user must manually switch modes (unlike just approving a tool call)
• Maintenance — Every new tool added to Hermes must also be categorized into mode groups
• Scope creep — Risk of the mode system becoming too complex if we try to match Roo Code's full feature set immediately

Open Questions

• Should built-in modes be hardcoded or configurable? (Roo Code makes even built-in modes overridable via same-slug custom modes)
• How should modes interact with existing personalities? Replace them, or be orthogonal? (Suggested: modes supersede personalities — a mode includes a persona)
• Should the agent be able to switch its own mode, or only the user? (Roo Code allows both via switch_mode tool)
• File regex restrictions: essential for Phase 1 or can we defer to Phase 2?
• How do modes interact with delegate_task? Should child agents inherit the parent's mode?
• Should mode definitions support referencing skills (e.g., "in Architect mode, auto-load the excalidraw skill")?

References

• Roo Code homepage
• Custom Modes documentation
• Roo Code GitHub (Apache 2.0)
• Mode marketplace
• Roo Code source: packages/types/src/mode.ts, src/core/tools/validateToolUse.ts, src/core/prompts/tools/filter-tools-for-mode.ts, src/core/tools/SwitchModeTool.ts
• Related Hermes issues: Feature: Multi-Agent Architecture — Orchestration, Cooperation, Specialized Roles & Resilient Workflows #344 (Multi-Agent Architecture), Feature: PAHF Personalization Loop — Pre-Action Clarification, Preference Grounding & Post-Action Feedback Integration #362 (PAHF Personalization)