Mistral Vibe - Architecture Overview

What is Mistral Vibe?

Mistral Vibe is an open-source CLI coding assistant developed by Mistral AI. It provides a conversational AI interface for developers to interact with codebases through natural language commands directly from the terminal.

Version: 2.0.2 License: Apache 2.0 Python Requirement: 3.12+

Core Capabilities

• File Operations: Read, write, and modify files with intelligent patching
• Shell Execution: Execute shell commands in a stateful terminal session
• Code Search: Search codebases using ripgrep-powered grep tool
• Task Management: Built-in todo list for tracking work
• Ask User Question: Structured question/answer tool with options, multi-select, and headers
• Task Delegation: Delegate work to subagents for exploration and parallel processing
• Agent Profiles: Switchable behavioral presets (default, plan, accept-edits, auto-approve, explore)
• Skills System: Injectable domain knowledge via SKILL.md files with YAML frontmatter
• Trusted Folders: Security system preventing untrusted project-local config from loading
• MCP Integration: Connect to external tools via Model Context Protocol
• Session Persistence: Save and resume conversations with structured directory format

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        User Interface                            │
│  ┌─────────────────┐              ┌─────────────────────────┐   │
│  │ Interactive TUI │              │   Programmatic Mode     │   │
│  │ (Textual App)   │              │   (--prompt flag)       │   │
│  └────────┬────────┘              └───────────┬─────────────┘   │
└───────────┼───────────────────────────────────┼─────────────────┘
            │                                   │
            └───────────────┬───────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                         Agent Core                               │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                  AgentLoop Orchestrator                  │    │
│  │               (vibe/core/agent_loop.py)                  │    │
│  │  - Conversation state management                         │    │
│  │  - Message history                                       │    │
│  │  - Statistics tracking                                   │    │
│  └─────────────────────────┬───────────────────────────────┘    │
│                            │                                     │
│  ┌──────┬──────┬───────────┼───────┬──────────┬───────────┐     │
│  │      │      │           │       │          │           │     │
│  ▼      ▼      ▼           ▼       ▼          ▼           ▼     │
│ LLM   Tool  Middlew.    System   Session    Agent       Skill   │
│Backend Manager Pipeline  Prompt   Logger   Manager     Manager  │
└─────────────────────────────────────────────────────────────────┘
            │             │
            ▼             ▼
┌───────────────────┐  ┌──────────────────────────────────────────┐
│   LLM Providers   │  │              Tool Ecosystem              │
│  - Mistral API    │  │  ┌─────────┐ ┌─────────┐ ┌───────────┐  │
│  - Generic/OpenAI │  │  │Built-in │ │ Custom  │ │   MCP     │  │
│                   │  │  │ Tools   │ │ Tools   │ │   Tools   │  │
└───────────────────┘  │  └─────────┘ └─────────┘ └───────────┘  │
                       └──────────────────────────────────────────┘

Technology Stack

Directory Structure

mistral-vibe/
├── vibe/                          # Main application package
│   ├── cli/                       # CLI and TUI components
│   │   ├── entrypoint.py         # CLI argument parsing, trust check
│   │   ├── cli.py                # run_cli() orchestrator
│   │   ├── terminal_setup.py     # Terminal keybinding setup
│   │   ├── commands.py           # Slash command registry
│   │   └── textual_ui/           # Textual TUI implementation
│   │       ├── app.py            # Main TUI application
│   │       ├── external_editor.py # External editor integration
│   │       ├── terminal_theme.py # Terminal theme detection
│   │       ├── handlers/         # Event handling
│   │       └── widgets/          # UI components
│   │           ├── question_app.py    # Ask user question UI
│   │           ├── agent_indicator.py # Agent profile display
│   │           ├── spinner.py         # Loading spinners
│   │           ├── status_message.py  # Status messages
│   │           ├── no_markup_static.py # Safe text display
│   │           └── ...
│   │
│   ├── core/                      # Core agent logic
│   │   ├── agent_loop.py         # Main orchestrator (AgentLoop)
│   │   ├── config.py             # Configuration system
│   │   ├── types.py              # Type definitions
│   │   ├── middleware.py         # Conversation middleware
│   │   ├── system_prompt.py      # Prompt construction
│   │   ├── trusted_folders.py    # Trusted folders security
│   │   │
│   │   ├── agents/               # Agent profile system
│   │   │   ├── models.py         # AgentProfile, AgentSafety, AgentType
│   │   │   └── manager.py        # AgentManager discovery & switching
│   │   │
│   │   ├── skills/               # Skills system
│   │   │   ├── models.py         # SkillMetadata, SkillInfo
│   │   │   ├── manager.py        # SkillManager discovery
│   │   │   └── parser.py         # YAML frontmatter parser
│   │   │
│   │   ├── session/              # Session persistence
│   │   │   ├── session_logger.py # Session creation & saving
│   │   │   ├── session_loader.py # Session finding & loading
│   │   │   └── session_migration.py # v1→v2 format migration
│   │   │
│   │   ├── paths/                # Path resolution
│   │   │   ├── global_paths.py   # GlobalPath, VIBE_HOME, etc.
│   │   │   └── config_paths.py   # Trust-aware config resolution
│   │   │
│   │   ├── llm/                  # LLM backend abstraction
│   │   │   └── backend/          # Provider implementations
│   │   │
│   │   └── tools/                # Tool system
│   │       ├── base.py           # Abstract base tool, InvokeContext
│   │       ├── manager.py        # Tool discovery
│   │       ├── ui.py             # ToolUIData protocol
│   │       ├── mcp.py            # MCP integration
│   │       └── builtins/         # Built-in tools
│   │           ├── ask_user_question.py  # Structured Q&A
│   │           ├── task.py              # Subagent delegation
│   │           └── ...
│   │
│   ├── acp/                       # Agent Client Protocol
│   └── setup/                     # Onboarding & trust dialogs
│
├── tests/                         # Test suite
└── docs/                          # Documentation

Key Design Principles

1. Plugin-Based Tool Architecture

Tools are discovered dynamically from multiple paths:

• Built-in: vibe/core/tools/builtins/
• Project-local: ./.vibe/tools/ (if trusted)
• User home: ~/.vibe/tools/
• MCP servers: Remote tools via HTTP/stdio

2. Agent Profile System

Switchable behavioral presets that modify config:

• default: Neutral safety, requires approval
• plan: Safe, read-only exploration
• accept-edits: Auto-approves file writes
• auto-approve: Auto-approves everything
• explore: Read-only subagent for Task tool
• Custom agents via TOML files

3. Skills System

Injectable knowledge via SKILL.md files:

• YAML frontmatter for metadata
• Markdown body injected into system prompt
• Discoverable from project-local, global, and config paths

4. Trusted Folders

Security boundary for project-local content:

• User must explicitly trust a folder before local config/tools/agents/skills are loaded
• Decisions persisted in ~/.vibe/trusted_folders.toml

5. Async-First Design

All I/O operations are async for responsiveness:

• Streaming LLM responses
• Non-blocking file operations
• Proper cancellation handling

6. Middleware Pipeline

Extensible pre/post turn hooks:

• Turn limits
• Price limits
• Auto-compaction
• Context warnings
• Plan agent enforcement

7. Event-Driven Communication

AgentLoop yields events via AsyncGenerator:

• UserMessageEvent - User message echo
• AssistantEvent - LLM responses
• ReasoningEvent - Reasoning content (thinking tokens)
• ToolCallEvent - Tool invocations
• ToolResultEvent - Tool results
• ToolStreamEvent - Streaming tool output
• CompactStartEvent/CompactEndEvent - Compaction

Execution Modes

Interactive Mode (Default)

Full Textual TUI with:

• Real-time streaming
• Tool approval dialogs
• Agent profile switching (Shift+Tab)
• Question app for structured input
• Configuration editor
• Session persistence

Programmatic Mode (--prompt)

Non-interactive execution:

• Auto-approve enabled
• Output formats: text, json, streaming
• Exit on completion

ACP Server Mode (vibe-acp)

Agent Client Protocol server:

• IDE integration
• Multiple client connections
• Remote usage

Configuration Hierarchy

1. Local project: ./.vibe/config.toml (if trusted)
2. User home: ~/.vibe/config.toml
3. Environment variables: VIBE_* prefix
4. API keys: ~/.vibe/.env

Next Steps

For detailed documentation on specific components:

• Entry Points - Application entry points and execution flow
• Agent Loop - Conversation loop mechanics
• Tool System - Tool architecture and execution
• Middleware - Middleware pipeline
• LLM Backends - Backend abstraction
• Configuration - Configuration system
• TUI & Events - TUI architecture and event flow
• Agents & Skills - Agent profiles and skills system
• Session Management - Session persistence and loading
• Trusted Folders - Trusted folders security