Unified Modes: Combine Tools, Permissions, and Behaviors

Lesson updated November 2, 2026. Example agent files now use keys documented by Vibe: instructions (not system_prompt), active_model (not model), [tools.<tool>] blocks for approvals (the auto_approve key does not exist in an agent file), and real tool names (edit, not edit_file; no list_dir tool). Reminder from Lesson 3: safety is a visual indicator, not a permission. Source: Configuration reference.

The concept of unified modes

The custom agents we covered in previous lessons define a static profile: a model, a set of tools, and a safety level. Unified modes go further by combining multiple dimensions into a single, coherent configuration that you can activate with one gesture. A unified mode bundles authorized tools, specific permissions, system-prompt-driven behavior, auto-approval rules, and contextual restrictions.

The value becomes obvious when your work shifts several times in a day. Without unified modes, you juggle multiple settings every time your context changes: you move from code review to deployment, and you have to swap agents, adjust permissions, and tweak the prompt. A unified mode encapsulates all of that in one profile, which you activate at launch or mid-session.

# Enable "deploy" mode
vibe --agent deploy-mode

# Switch to "review" mode
# Shift+Tab → select review-mode

Structure of a unified mode

Technically, a unified mode is a custom agent; the difference from a classic agent is conceptual. You no longer design the .toml file as “an assistant that can do X,” but as a complete work context: what you are allowed to do during this phase of the project, with what level of caution, and in what form results come back to you.

The review mode below illustrates this most clearly. It is read-only, so it is auto-approved without risk, and its prompt enforces a report format you can drop directly into a pull request.

# ~/.vibe/agents/review-mode.toml
display_name = "Review Mode"
description = "Code review mode: read-only, deep analysis, suggestions."

safety = "safe"
active_model = "mistral-medium-3.5"  # model built into Vibe

instructions = """
You are in code review mode.
Goal: analyze code quality, security, and maintainability.
Rules:
- Never modify files
- Produce a structured report (critical issues, warnings, suggestions)
- Cite affected code lines with their line numbers
- Propose fixes as diffs
Output format: Markdown with Critical / Warning / Suggestion sections
"""

enabled_tools = [
  "read_file",
  "grep",
]

[tools.read_file]
permission = "always"

[tools.grep]
permission = "always"

Deploy mode is its exact opposite, and that contrast is intentional. It has bash, so it can break things, but its ask permissions on write_file and bash keep you in the loop, and its prompt describes a strict sequence the agent must follow from start to finish.

# ~/.vibe/agents/deploy-mode.toml
display_name = "Deploy Mode"
description = "Deploy mode: build, test, deploy with validation at each step."

safety = "destructive"
active_model = "codestral"  # alias declared in config.toml (Lesson 2)

instructions = """
You are in deploy mode.
Mandatory sequence:
1. Verify that all tests pass
2. Build the project
3. Validate the build (no errors, no warnings)
4. Request confirmation before actual deployment
5. Deploy
6. Verify that the service responds
Never deploy if tests fail.
"""

enabled_tools = [
  "read_file",
  "write_file",
  "bash",
  "grep",
  "ask_user_question"
]

[tools.write_file]
permission = "ask"

[tools.bash]
permission = "ask"

Designing complementary modes

The idea is to create a set of modes that cover your development cycle, from discovery to fixing. Exploration mode leads the way: read-only and auto-approved, it helps you understand a repository before you touch it.

display_name = "Explore Mode"
safety = "safe"
instructions = """Explore the codebase, identify the architecture, patterns, and dependencies."""
enabled_tools = ["read_file", "grep",]

[tools.read_file]
permission = "always"

[tools.grep]
permission = "always"

Next comes Dev mode, where you will spend most of your time. It writes and runs commands—to run tests, for example—but it asks for your approval, and its prompt ties every change to writing tests.

display_name = "Dev Mode"
safety = "neutral"
instructions = """Implement the requested features. Write tests for every change."""
enabled_tools = ["read_file", "write_file", "edit", "bash", "grep",]

[tools.write_file]
permission = "ask"

[tools.edit]
permission = "ask"

[tools.bash]
permission = "ask"

Finally, Fix mode is deliberately narrow. No write_file, only edit: the agent modifies existing code without creating new files, which prevents it from “refactoring along the way” a bug you simply asked it to fix. Because it is this constrained, we can safely auto-approve it.

display_name = "Fix Mode"
safety = "neutral"
instructions = """Fix reported bugs. Minimize changes. Touch only the affected code."""
enabled_tools = ["read_file", "edit", "grep"]

[tools.read_file]
permission = "always"

[tools.edit]
permission = "always"

[tools.grep]
permission = "always"

Switching between modes and organizing them

In an interactive session, Shift+Tab cycles through modes: Vibe displays the list of all your agents, built-in and custom, with their descriptions—this is where the careful descriptions from the previous lesson pay off. From the command line, you start directly in a mode, or you inspect the contents of the agents directory.

# Start directly in a mode
vibe --agent review-mode

# List available agents
ls ~/.vibe/agents/

Finally, adopt a clear naming convention. The -mode suffix immediately distinguishes your work contexts from more ad hoc utility agents, and the alphabetical order of the directory stays readable even after a dozen files.

~/.vibe/agents/
├── review-mode.toml      # Code review
├── deploy-mode.toml      # Deployment
├── dev-mode.toml         # Development
├── fix-mode.toml         # Fixes
├── explore-mode.toml     # Exploration
└── doc-mode.toml         # Documentation

Key takeaways

• A unified mode is a custom agent designed as a complete work context
• It combines tools, permissions, system prompt, and model in a single configuration
• Create complementary modes to cover your development cycle
• Shift+Tab lets you switch between modes in real time
• Name your files consistently so you can find them easily
• Each mode must have a clear goal and appropriate permissions