Agents

Agents are configuration overrides applied on top of the global config. They bundle a system prompt, a compaction prompt, an active model, an available tool set, and approval rules.

The CLI ships with several built-in agents, and you can define your own.

Built-in agents

Agent	Behavior
`ask`	Asks for approval before running tools. Formerly named `default`.
`accept-edits`	Default agent. Auto-approves file edits in the working directory. Still asks for approval for other actions (for example, shell commands).
`smart-approve`	Classifies each tool call, runs the ones it judges safe, and asks for approval before risky ones. See Smart approve.
`auto-approve`	Auto-approves all tool execution. Use only in a trusted, sandboxed environment: this agent can run arbitrary commands such as `rm -rf` against any path Vibe can reach. Unavailable when your administrator sets `enable_auto_approve = false`.
`lean`	Specialized agent for the Lean 4 proof assistant. Install with `/leanstall` from inside the CLI, and remove it with `/unleanstall`.

Note

Vibe 3.0 removes the plan agent. If your config still sets default_agent = "plan" and you don't have a custom agent named plan, Vibe shows a warning and starts sessions with ask instead. To keep a planning workflow, create your own plan agent.

The agent can also delegate work to subagents, for example to explore a large codebase without filling its own context. You can't select subagents with --agent. See Custom subagents.

Select an agent

Pick an agent at launch:

vibe --agent ask
vibe --agent auto-approve

vibe --agent ask
vibe --agent auto-approve

In interactive sessions, switch agents on the fly with Shift+Tab.

Set the default agent in config.toml:

default_agent = "ask"

default_agent = "ask"

default_agent applies to both interactive and programmatic (--prompt) sessions. To approve every tool call for one run, whatever the agent, pass --auto-approve (or its alias --yolo). Vibe ignores these flags when your administrator sets enable_auto_approve = false.

Custom agents

Create custom agents in ~/.vibe/agents/ (user-level) or ./.vibe/agents/ (project-level) by adding a .toml file. Set the agent's kind with agent_type:

agent_type = "agent" (default): user-facing. Selectable via vibe --agent <name> or Shift+Tab.
agent_type = "subagent": delegation-only. Spawned by the agent when it delegates work. Not selectable by the user.

Run a custom agent with its filename:

vibe --agent redteam

vibe --agent redteam

The CLI looks for redteam.toml in the agents directory and applies its configuration.

Example: a read-only red-team review agent.

# ~/.vibe/agents/redteam.toml
agent_type = "agent"
display_name = "Red team"
description = "Read-only audit agent for security review."
safety = "safe"
active_model = "mistral-medium-3.5"
system_prompt_id = "redteam"
disabled_tools = ["edit", "write_file"]

[tools.bash]
permission = "ask"

[tools.read_file]
permission = "always"

# ~/.vibe/agents/redteam.toml
agent_type = "agent"
display_name = "Red team"
description = "Read-only audit agent for security review."
safety = "safe"
active_model = "mistral-medium-3.5"
system_prompt_id = "redteam"
disabled_tools = ["edit", "write_file"]

[tools.bash]
permission = "ask"

[tools.read_file]
permission = "always"

Note

The safety field changes the input border color in the CLI to signal the agent's safety level. Options are safe, neutral, destructive, smart, and yolo. It is a visual hint only and does not enforce permissions, so pair it with appropriate enabled_tools, disabled_tools, and per-tool permissions. The one exception: when enable_auto_approve is false, Vibe hides every agent with safety = "yolo".

The system_prompt_id value names a Markdown file in ./.vibe/prompts/ (trusted folders only) or ~/.vibe/prompts/. The example above expects redteam.md.

A custom agent's prompt applies only if you select the agent before your first message, with --agent or Shift+Tab. If you switch agents later, the new agent's tools, permissions, and model apply, but the prompt changes only after /clear.

Create a plan agent

To explore a codebase and agree on a plan before any file changes, define a read-only agent named plan:

# ~/.vibe/agents/plan.toml
display_name = "Plan"
description = "Explores the codebase and proposes a plan before any change."
safety = "safe"
disabled_tools = ["edit", "write_file"]
instructions = """
Explore the codebase and propose a step-by-step implementation plan.
Don't modify any file until the user approves the plan.
"""

[tools.bash]
permission = "ask"

# ~/.vibe/agents/plan.toml
display_name = "Plan"
description = "Explores the codebase and proposes a plan before any change."
safety = "safe"
disabled_tools = ["edit", "write_file"]
instructions = """
Explore the codebase and propose a step-by-step implementation plan.
Don't modify any file until the user approves the plan.
"""

[tools.bash]
permission = "ask"

Start with vibe --agent plan, or set default_agent = "plan". The agent can read files and run read-only shell commands, and asks before any other command. Once you approve the plan, press Shift+Tab to switch to accept-edits and ask the agent to implement it. The instructions above stay in the conversation and allow the change once you approve.

Custom subagents

Subagents run independently and return text-only results to the parent agent. The agent spawns them when it wants to delegate exploration or background work. Without a custom subagent, it can spawn a generic subagent that uses the same instructions and tools as itself.

Create a custom subagent by setting agent_type = "subagent". The description tells the agent when to use it:

# ~/.vibe/agents/research.toml
agent_type = "subagent"
display_name = "Research"
description = "Read-only subagent for research tasks."
safety = "safe"
enabled_tools = ["read_file", "skill"]

# ~/.vibe/agents/research.toml
agent_type = "subagent"
display_name = "Research"
description = "Read-only subagent for research tasks."
safety = "safe"
enabled_tools = ["read_file", "skill"]

Subagents can't ask the user questions. A subagent can use only the built-in tools its file allows, not MCP, connector, or plugin tools, and never with broader permissions than the parent agent. Subagents always run on the session's model and ignore active_model. If Vibe can't load a subagent file, for example because its description is empty, it reports the issue instead of skipping the file silently.

To stop the agent from spawning subagents, set enable_subagents = false in config.toml.

AGENTS.md support

The CLI loads AGENTS.md files into context to follow user and project-specific agent instructions:

User-level: ~/.vibe/AGENTS.md (or in $VIBE_HOME if you set it).
Project-level: every AGENTS.md from the current working directory up to the root of the trusted folder. When instructions conflict, the file closest to the working directory wins.

For example:

/
  dir_1/
    AGENTS.md      <- never loaded: location is not trusted
    dir_2/         <- trusted
      AGENTS.md    <- loaded
      dir_3/
        AGENTS.md  <- loaded, takes priority over dir_2/AGENTS.md
        project/   <- cwd (no AGENTS.md here)

/
  dir_1/
    AGENTS.md      <- never loaded: location is not trusted
    dir_2/         <- trusted
      AGENTS.md    <- loaded
      dir_3/
        AGENTS.md  <- loaded, takes priority over dir_2/AGENTS.md
        project/   <- cwd (no AGENTS.md here)

Additionally, the CLI will auto-discover new AGENTS.md files when reading files in sub-directories.