Skip to content
/
Tier A A8 Cross-runtime harness

Mistral Vibe

mistral-vibe · mistralai/mistral-vibe · ★ 4.3k · last commit 2026-05-25

Primitive shape 2 total
Subagents 1 Hooks 1
00

Summary

Mistral Vibe — Summary

Mistral Vibe is Mistral AI's open-source CLI coding assistant (Apache-2.0, 4,284 stars), distributed as vibe binary and installable via pip/uv. It provides a rich interactive terminal UI with autocompletion, persistent history, themes, and a full agent-loop architecture. Key features: 4 built-in agent profiles (default, plan, accept-edits, auto-approve) with distinct tool-approval policies; subagent delegation via task tool; a TOML-based hooks system (PostAgentTurn events); custom skills system (slash commands from .vibe/skills/ SKILL.md files); MCP server integration; and ACP (Agent Client Protocol) support for programmatic control.

Mistral Vibe is differentiated by its first-class "agent profiles" system — different named configurations (default, plan, accept-edits, auto-approve, lean) that change which tools are auto-approved, making safety configurable rather than all-or-nothing. The skills system mirrors Devin's SKILL.md pattern. The ask_user_question tool enables interactive multi-option clarification during agent execution.

Closest seed: spec-driver (skills-first CLI agent with a vibe binary analogous to spec-driver's slash commands), but Mistral Vibe is more feature-complete as a standalone product, includes hooks, subagents, voice mode, and ACP support that spec-driver lacks.

01

Overview

Mistral Vibe — Overview

Origin

Created by Mistral AI. Published as open-source (Apache-2.0) on GitHub at mistralai/mistral-vibe. Version 2.11.0 at analysis time. Available on PyPI. Multiple install paths: one-line curl, uv tool install, pip.

Philosophy

"Minimal CLI coding agent by Mistral" — the package description. The README's tone is pragmatic: ship a professional-grade tool, not a research prototype. The agent profiles system reflects a belief that "safety" is context-dependent: a planning session needs different defaults than an auto-refactoring session.

Key Design Decisions

  1. Agent profiles as first-class config: Not just "safe mode" vs "unsafe mode" — named profiles with different tool-approval policies and system prompts
  2. Trust folder system: Projects must be explicitly trusted before .vibe/ config is honored — prevents malicious directory injection
  3. ACP (Agent Client Protocol): Mistral Vibe implements the agent-client-protocol==0.9.0 standard, making it usable as a programmatic backend for other tools
  4. Voice mode: Integrates audio recording + playback for voice-to-text input
  5. Skills = slash commands: Skills are SKILL.md files that become /skill-name slash commands

Connection to Mistral Models

Defaults to Mistral's own models (via mistral.ai API key), but is provider-agnostic — can use any OpenAI-compatible API via config. The --setup wizard walks users through API key configuration.

Terminal Philosophy

Requires a modern terminal emulator (WezTerm, Alacritty, Ghostty, Kitty). Built with libraries that leverage modern terminal capabilities (Textual/Rich ecosystem). Windows is "supported but not officially targeted."

02

Architecture

Mistral Vibe — Architecture

Distribution

  • Type: Python package (PyPI: mistral-vibe)
  • Binaries: vibe and vibe-acp (two CLI entry points)
  • Stars: 4,284 | License: Apache-2.0

Install

# One-liner (recommended)
curl -LsSf https://mistral.ai/vibe/install.sh | bash
# uv
uv tool install mistral-vibe
# pip
pip install mistral-vibe

Config Files

  • ~/.vibe/config.toml — global config (model, provider, tools, agent, MCP servers)
  • ~/.vibe/.env — API keys
  • ~/.vibe/trusted_folders.toml — trusted project directories
  • .vibe/agents/ — custom agent definitions (project or global)
  • .vibe/skills/ — custom skill definitions (project or global)
  • ~/.vibe/agents/skills/ — global skills
  • TOML hooks file — hook definitions (path in config)

Source Structure

vibe/
├── cli/
│   └── entrypoint.py    — main CLI entry point
├── acp/
│   └── entrypoint.py    — ACP server entry point
├── core/
│   ├── agent_loop.py    — main agent execution loop
│   ├── agents/
│   │   ├── manager.py   — agent profile discovery + selection
│   │   └── models.py    — AgentProfile, AgentType, BuiltinAgentName, BUILTIN_AGENTS
│   ├── hooks/
│   │   ├── config.py    — TOML hook parsing
│   │   ├── executor.py  — hook execution
│   │   ├── manager.py   — hook lifecycle management
│   │   └── models.py    — HookType, HookConfig, HookExecutionResult
│   ├── config/          — VibeConfig, settings
│   └── llm/             — LLM client, providers

Required Runtime

  • Python 3.12+
  • ~/.vibe/config.toml with API key

Supported Providers

Mistral AI (default), any OpenAI-compatible API (via base_url config)

03

Components

Mistral Vibe — Components

Built-in Agent Profiles (6)

Name Type Description
default agent Standard; requires approval for tool executions
plan agent Read-only; auto-approves grep, read_file
accept-edits agent Auto-approves file edits only (write_file, search_replace)
auto-approve agent Auto-approves all tool executions
lean agent Minimal tool set (install_required=True)
explore subagent Read-only subagent for codebase exploration; used by delegation

Built-in Tools

Tool Description
read_file Read file contents
write_file Write/create files
search_replace Patch files via search-replace
bash Execute shell commands (stateful terminal)
grep Code search (ripgrep-backed)
todo Manage a todo list to track agent work
ask_user_question Ask interactive questions with 2-4 options + Other
task Delegate to a subagent

Slash Commands (built-in)

From README reference to "Built-in Slash Commands" — not fully enumerated in public docs, but include:

  • / prefix for all skills (auto-completion available)
  • @ for file path reference auto-completion

Skills System

  • Location: .vibe/skills/<name>/SKILL.md or ~/.vibe/skills/<name>/SKILL.md
  • Format: SKILL.md with TOML frontmatter
  • Discovery: automatic from project + global paths
  • Invocation: as slash command (/<skill-name>) or auto-activated
  • Management: vibe --list-skills (implied by docs)

Custom Agents

  • Location: .vibe/agents/<name>.toml or ~/.vibe/agents/<name>.toml
  • Format: TOML file with display_name, description, safety, agent_type, overrides
  • Types: agent (primary) or subagent (delegation target)
  • Subagent definition: agent_type = "subagent" in TOML

Hooks (PostAgentTurn only)

  • Config: TOML hooks file
  • Events: PostAgentTurn (only documented event type)
  • Format: name, type, command, timeout (30s default)
  • Trigger: shell command executed after each agent response turn

MCP Server Integration

  • Config: ~/.vibe/config.toml under [mcp_servers]
  • Protocol: stdio (standard MCP)

ACP Mode

  • Binary: vibe-acp
  • Purpose: Programmatic control via Agent Client Protocol (agent-client-protocol==0.9.0)
  • Use: Other tools/agents can drive Vibe as a backend

Voice Mode

  • --voice or configured; uses audio recording + playback
  • Requires HTTPS for microphone (platform-dependent)
05

Prompts

Mistral Vibe — Prompts

Note

Mistral Vibe's internal system prompts are not in the public repo (generated at runtime). The following excerpts are from source code for the agent profile and hook systems.

Verbatim: AgentProfile BUILTIN definitions (from vibe/core/agents/models.py)

class BuiltinAgentName(StrEnum):
    DEFAULT = "default"
    CHAT = "chat"
    PLAN = "plan"
    ACCEPT_EDITS = "accept-edits"
    AUTO_APPROVE = "auto-approve"
    EXPLORE = "explore"
    LEAN = "lean"

class AgentSafety(StrEnum):
    SAFE = auto()
    NEUTRAL = auto()
    DESTRUCTIVE = auto()
    YOLO = auto()

class AgentType(StrEnum):
    AGENT = auto()
    SUBAGENT = auto()

Technique: Safety taxonomy encoded as StrEnum — SAFE / NEUTRAL / DESTRUCTIVE / YOLO. This is architectural philosophy as code: safety is a property of the agent profile, not of individual tools. The YOLO safety level is the most permissive.

Verbatim: CHAT_AGENT_TOOLS constant (from vibe/core/agents/models.py)

CHAT_AGENT_TOOLS = ["grep", "read_file", "ask_user_question", "task"]

Technique: Explicit tool whitelist for read-only agents. The chat agent gets exactly these 4 tools — no file-write capability.

Verbatim: HookConfig schema (from vibe/core/hooks/models.py)

class HookType(StrEnum):
    POST_AGENT_TURN = auto()

class HookConfig(BaseModel):
    name: str
    type: HookType
    command: str
    timeout: float = 30.0
    description: str | None = None

    @field_validator("command")
    @classmethod
    def command_not_blank(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("command must not be empty")
        return v

Technique: Pydantic validation as correctness enforcement. The command_not_blank validator prevents silent no-ops. Only POST_AGENT_TURN hook type is currently supported (expandable).

Verbatim: ask_user_question example (from README)

> ask_user_question(questions=[{
    "question": "What's the main goal of this refactoring?",
    "options": [
        {"label": "Performance", "description": "Make it run faster"},
        {"label": "Readability", "description": "Make it easier to understand"},
        {"label": "Maintainability", "description": "Make it easier to modify"}
    ]
}])

Technique: Structured option list with automatic "Other" fallback. The agent can ask multiple questions displayed as tabs. This transforms open-ended clarification into multiple-choice UX.

09

Uniqueness

Mistral Vibe — Uniqueness

Differs From Seeds

Mistral Vibe is closest to spec-driver (CLI coding agent with skills as the primary methodology primitive), but diverges in significant ways: spec-driver has 24 skills as Iron Laws that auto-activate; Vibe has 4 built-in agent profiles + a skills system that maps to slash commands. Vibe's hooks (PostAgentTurn only) are simpler than spec-driver's 2 hooks. Vibe's subagent delegation via task tool parallels BMAD's persona system but uses code-class definitions (TOML files) rather than BMAD's Markdown personas. The ask_user_question tool with structured options is unique in the corpus — no seed framework provides this interactive clarification mechanism.

Distinctive Opinion

Safety should be configurable at the agent profile level, not the individual tool level. The SAFE/NEUTRAL/DESTRUCTIVE/YOLO taxonomy makes risk management explicit and per-workflow rather than a global toggle.

Positioning

  • Mistral's answer to Claude Code and Gemini CLI — a first-party CLI agent for their own models
  • Target: developers who want Mistral's models in a professional CLI experience
  • ACP support makes it composable with other agent systems

Observable Failure Modes

  • PostAgentTurn as the only hook type limits pre-action enforcement (can't block tool calls like Claude Code's PreToolUse)
  • No file-level isolation for subagents — subagent can edit files the user didn't intend
  • Trust folder system requires upfront setup; new repos won't activate .vibe/ skills automatically

Anti-Patterns (from docs)

  • Don't use auto-approve profile in unfamiliar codebases
  • Don't mix default_agent config for programmatic mode (it's ignored in favor of auto-approve)
  • Don't deploy subagents without explicit write scope assignment

Cross-References

  • Agent Client Protocol (agent-client-protocol==0.9.0) — standardized protocol; compatible with other ACP-implementing agents
  • Devin's SKILL.md pattern — Vibe's skills are structurally similar; both use SKILL.md with TOML frontmatter
  • Zed's skills system — similar SKILL.md convention (.agents/skills/ in Zed, .vibe/skills/ in Vibe)
04

Workflow

Mistral Vibe — Workflow

Standard Interactive Workflow

1. cd /path/to/project && vibe
2. Trust folder prompt (first time, if .vibe/ present)
3. Select agent profile (default, plan, accept-edits, auto-approve; Shift+Tab to cycle)
4. Chat input → agent processes
5. Tool calls appear with approval prompts (profile-dependent)
6. Agent reports result; user continues conversation

Programmatic / One-shot Mode

vibe "Refactor the main function in cli/main.py"
# or
vibe -p "Fix the auth bug" --agent auto-approve

In -p/--prompt mode, defaults to auto-approve agent when --agent not set.

Subagent Delegation Workflow

User: "Explore the codebase structure while I work on something else"
→ Agent calls: task(task="Analyze the project structure", agent="explore")
→ explore subagent runs independently in fresh context
→ explore reports back; parent agent resumes

Phases + Artifacts

Phase Artifact
Context scan Project file structure + git status injected
Planning (plan profile) Read-only exploration with grep/read_file
Implementation File edits via write_file / search_replace
Verification bash runs tests/lint
Interactive clarification ask_user_question with 2-4 options
Completion Todo list updated to done

Approval Gates

  • Profile-dependent: default profile asks before every tool; auto-approve skips all
  • Tool execution approval: y/n/always/never per tool call (configurable per session)
  • Trust folder: one-time approval when first opening a project with .vibe/

Hooks Trigger

PostAgentTurn → shell command runs after agent response

Only PostAgentTurn is documented; hooks fire at end of each agent response.

06

Memory Context

Mistral Vibe — Memory & Context

Memory Type

File-based, session-scoped — no persistent memory between sessions.

Context Injection

  • Project file structure: Automatically scanned at session start
  • Git status: Injected as project context
  • Skills: Discovered from .vibe/skills/ and ~/.vibe/skills/
  • Custom agents: Discovered from .vibe/agents/ and ~/.vibe/agents/

Session State

  • Todo list: The todo tool maintains a list during the session (ephemeral)
  • Trusted folders: ~/.vibe/trusted_folders.toml — persists across sessions
  • Command history: Persistent across sessions (~/.vibe/history implied)

Skills as Memory Extension

Skills can include dynamic content (like Devin's !`command` blocks) to inject live context at invocation time. This allows skills to encode "how to work in this repo" knowledge that persists as files.

Cross-Session Handoff

No — no formal handoff mechanism. Conversation history does not persist (implied from stateless design).

Config Persistence

  • ~/.vibe/config.toml — model, provider, tools, hooks, MCP servers
  • ~/.vibe/.env — API keys
  • ~/.vibe/trusted_folders.toml — trusted project directories

Subagent Context Isolation

When task tool is called:

  • Subagent runs in a fresh context window
  • Parent agent's conversation history not shared
  • Subagent reports only final message back to parent
  • Design rationale: "preventing the context from being overloaded"
07

Orchestration

Mistral Vibe — Orchestration

Multi-Agent

Yes — via task tool. Parent agent delegates to subagents running in fresh context.

Orchestration Pattern

Hierarchical — parent agent → subagent delegation. Not peer-to-peer. The explore subagent is built-in; custom subagents can be added via .vibe/agents/ TOML files with agent_type = "subagent".

Subagent Isolation

  • Context isolation: Each subagent starts with a fresh context window
  • No shared memory: Parent's conversation not passed to subagent
  • Task-scoped: Subagent receives only the task description and relevant context passed explicitly
  • No user interaction: Subagents run without prompting the user

Isolation Mechanism

None for file access — subagents have the same file access as parent. Context isolation only (not process isolation, not container isolation).

Execution Mode

Interactive-loop (primary), one-shot via -p/--prompt flag

Hooks Lifecycle

Agent response → PostAgentTurn hook fires → shell command runs

Only PostAgentTurn (a.k.a. post_agent_turn) is currently available.

ACP Mode

vibe-acp binary exposes Vibe as an ACP (Agent Client Protocol) backend, enabling:

  • External orchestrators to drive Vibe as a sub-process
  • Programmatic prompt submission and response streaming
  • Integration with ACP-compatible agent frameworks

Multi-Model

Single model per session — profile overrides can specify different settings but all operate against the same configured provider/model within a session. Different sessions can use different models via CLI flags or config.

Prompt Chaining

Yes — agent can use todo to track steps, then iterate through them in a planning→execution→verification chain.

08

Ui Cli Surface

Mistral Vibe — UI & CLI Surface

CLI Binaries

  • vibe: Primary interactive CLI
  • vibe-acp: ACP server for programmatic access
  • Both installed via uv tool install mistral-vibe or pip

Terminal UI (Full TUI)

  • Library: Textual (Python) — full TUI with keyboard shortcuts and panels
  • Keyboard shortcuts:
    • Ctrl+J / Shift+Enter — multi-line input
    • @ — file path autocompletion
    • ! — run shell command directly (bypass agent)
    • Ctrl+G — open input in external editor
    • Ctrl+O — toggle tool output view
    • Ctrl+T — toggle todo list view
    • Ctrl+\ — toggle debug console
    • Shift+Tab — cycle through agent profiles
  • Features: Autocompletion for / slash commands and @ file paths, persistent command history, themes

Voice Mode

  • Flag: --voice or configured in config.toml
  • Audio recording → STT → chat input
  • Audio playback for TTS output
  • Requires modern terminal + HTTPS for mic

Observability

  • Ctrl+\ — debug console in-terminal
  • Ctrl+O — tool output panel
  • Ctrl+T — todo list panel
  • Hooks stdout visible in terminal

File System

  • ~/.vibe/ — global config, skills, agents, history
  • .vibe/ — project-local config, skills, agents

PyInstaller Distribution

  • pyinstaller/ directory exists → binary builds available
  • vibe-acp.spec for ACP binary build

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k
A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k
A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k
A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k
A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k
A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k
A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.