Mistral Vibe (mistralai/mistral-vibe)

Mistral Vibe

https://github.com/mistralai/mistral-vibe
Admin
Mistral Vibe is an open-source command-line coding assistant powered by Mistral's models, offering a...

Tokens:21,932
Snippets:117
Trust Score:8.9
Update:4 days ago
Show doc for...
Context Summary (auto-generated)
Raw
# Mistral Vibe

Mistral Vibe is an open-source command-line coding assistant powered by Mistral's large language models. It provides a conversational interface to your codebase, allowing you to use natural language to explore, modify, and interact with your projects through a powerful set of built-in tools. The assistant can read files, write code, execute shell commands, search codebases, and delegate tasks to specialized subagents for parallel work.

The tool is designed for developers who want AI-assisted coding directly in their terminal. It features project-aware context that automatically scans your file structure and Git status, a trust folder system for security, support for MCP (Model Context Protocol) servers to extend functionality, voice mode for hands-free interaction, and a skills system for creating reusable workflow components. Vibe can be used standalone in the CLI or integrated into editors like Zed, JetBrains IDEs, and Neovim via the Agent Client Protocol (ACP).

## Installation

### One-line Install (Linux/macOS)

```bash
curl -LsSf https://mistral.ai/vibe/install.sh | bash
```

### Using uv Package Manager

```bash
uv tool install mistral-vibe
```

### Using pip

```bash
pip install mistral-vibe
```

## CLI Usage

### Start Interactive Session

```bash
# Basic usage - start in current directory
vibe

# Start with an initial prompt
vibe "Refactor the main function in cli/main.py to be more modular."

# Use a specific agent profile
vibe --agent plan

# Continue from last session
vibe --continue

# Resume a specific session
vibe --resume abc123

# Run in a specific directory
vibe --workdir /path/to/project
```

### Programmatic Mode

```bash
# Run non-interactively with auto-approve
vibe --prompt "Analyze the codebase"

# With cost and turn limits
vibe --prompt "Analyze the codebase" --max-turns 5 --max-price 1.0

# JSON output for scripting
vibe --prompt "Find all TODO comments" --output json

# Streaming JSON output
vibe --prompt "Analyze code" --output streaming

# Enable only specific tools
vibe --prompt "Read the README" --enabled-tools "read_file" --enabled-tools "grep"
```

## Built-in Tools

### read_file - Read File Contents

Reads text files with automatic encoding detection, supporting line ranges and byte limits for safety.

```python
# Tool schema
read_file(
    path: str,           # File path to read
    offset: int = 0,     # Line number to start from (0-indexed)
    limit: int | None = None  # Maximum lines to read
)

# Example usage in conversation:
> Read the first 50 lines of src/main.py

# Agent calls:
read_file(path="src/main.py", limit=50)

# Returns:
{
    "path": "/project/src/main.py",
    "content": "import sys\n...",
    "lines_read": 50,
    "was_truncated": false
}
```

### write_file - Create or Overwrite Files

Creates new files or overwrites existing ones with UTF-8 content.

```python
# Tool schema
write_file(
    path: str,           # File path to write
    content: str,        # Content to write
    overwrite: bool = False  # Must be true to overwrite existing files
)

# Example usage:
> Create a new Python file called utils.py with a helper function

# Agent calls:
write_file(
    path="utils.py",
    content="def greet(name: str) -> str:\n    return f'Hello, {name}!'\n",
    overwrite=False
)

# Returns:
{
    "path": "/project/utils.py",
    "bytes_written": 58,
    "file_existed": false,
    "content": "def greet(name: str) -> str:\n    return f'Hello, {name}!'\n"
}
```

### search_replace - Patch Files with SEARCH/REPLACE Blocks

Replaces sections of files using precise SEARCH/REPLACE blocks with fuzzy matching support.

```python
# Tool schema
search_replace(
    file_path: str,   # File to patch
    content: str      # SEARCH/REPLACE blocks
)

# Example usage:
> Update the greet function to include a greeting prefix

# Agent calls:
search_replace(
    file_path="utils.py",
    content="""
<<<<<<< SEARCH
def greet(name: str) -> str:
    return f'Hello, {name}!'
=======
def greet(name: str, prefix: str = "Hello") -> str:
    return f'{prefix}, {name}!'
>>>>>>> REPLACE
"""
)

# Returns:
{
    "file": "/project/utils.py",
    "blocks_applied": 1,
    "lines_changed": 1,
    "content": "...",
    "warnings": []
}
```

### bash - Execute Shell Commands

Runs shell commands with configurable timeouts, allowlists, and denylists for security.

```python
# Tool schema
bash(
    command: str,           # Shell command to execute
    timeout: int | None = None  # Timeout in seconds (default 300)
)

# Example usage:
> Run the test suite

# Agent calls:
bash(command="pytest tests/ -v")

# Returns:
{
    "command": "pytest tests/ -v",
    "stdout": "===== test session starts =====\n...",
    "stderr": "",
    "returncode": 0
}

# Configuration in config.toml:
[tools.bash]
permission = "ask"
default_timeout = 300
allowlist = ["git status", "git diff", "git log", "ls", "cat"]
denylist = ["rm -rf", "sudo"]
```

### grep - Search Files with Regex

Recursively searches files using ripgrep or grep with smart defaults and exclusion patterns.

```python
# Tool schema
grep(
    pattern: str,               # Regex pattern to search
    path: str = ".",            # Directory or file to search
    max_matches: int | None = None,  # Override default max matches (100)
    use_default_ignore: bool = True  # Respect .gitignore files
)

# Example usage:
> Find all TODO comments in the codebase

# Agent calls:
grep(pattern="TODO", path=".")

# Returns:
{
    "matches": "src/main.py:42:    # TODO: Implement error handling\n...",
    "match_count": 15,
    "was_truncated": false
}

# Configuration in config.toml:
[tools.grep]
permission = "always"
default_max_matches = 100
exclude_patterns = [".venv/", "node_modules/", ".git/", "__pycache__/"]
```

### task - Delegate to Subagents

Delegates work to specialized subagents for parallel execution without user interaction.

```python
# Tool schema
task(
    task: str,           # Task description for the subagent
    agent: str = "explore"  # Subagent profile to use
)

# Example usage:
> Explore the codebase structure while I work on something else

# Agent calls:
task(task="Analyze the project structure and identify key components", agent="explore")

# Returns:
{
    "response": "The project is organized into...",
    "turns_used": 3,
    "completed": true
}
```

### ask_user_question - Interactive Questions

Asks the user clarifying questions during execution with multiple-choice options.

```python
# Tool schema
ask_user_question(
    questions: list[Question],     # 1-4 questions to ask
    content_preview: str | None = None  # Optional content to display
)

# Question structure:
{
    "question": str,        # The question text
    "header": str,          # Short header (max 12 chars)
    "options": [            # 2-4 choices
        {"label": str, "description": str}
    ],
    "multi_select": bool,   # Allow multiple selections
    "hide_other": bool      # Hide free-text "Other" option
}

# Example usage:
> Help me refactor this function

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

# Returns:
{
    "answers": [{"question": "...", "answer": "Performance", "is_other": false}],
    "cancelled": false
}
```

### todo - Manage Task Lists

Maintains a todo list to track the agent's progress on complex tasks.

```python
# Tool schema
todo(
    action: str,                    # "read" or "write"
    todos: list[TodoItem] | None = None  # Complete list when writing
)

# TodoItem structure:
{
    "id": str,
    "content": str,
    "status": "pending" | "in_progress" | "completed" | "cancelled",
    "priority": "low" | "medium" | "high"
}

# Example: Agent managing a multi-step task
todo(action="write", todos=[
    {"id": "1", "content": "Read existing code", "status": "completed", "priority": "high"},
    {"id": "2", "content": "Implement new feature", "status": "in_progress", "priority": "high"},
    {"id": "3", "content": "Write tests", "status": "pending", "priority": "medium"}
])

# Returns:
{
    "message": "Updated 3 todos",
    "todos": [...],
    "total_count": 3
}
```

### web_fetch - Fetch URL Content

Fetches content from URLs and converts HTML to markdown for readability.

```python
# Tool schema
web_fetch(
    url: str,              # URL to fetch (http/https)
    timeout: int | None = None  # Timeout in seconds (max 120)
)

# Example usage:
> Fetch the documentation from that API endpoint

# Agent calls:
web_fetch(url="https://api.example.com/docs")

# Returns:
{
    "url": "https://api.example.com/docs",
    "content": "# API Documentation\n\n## Endpoints\n...",
    "content_type": "text/html; charset=utf-8",
    "was_truncated": false
}
```

### web_search - Search the Web

Searches the web for current information using Mistral's web search capability.

```python
# Tool schema
web_search(
    query: str  # Search query
)

# Example usage:
> Search for the latest Python 3.13 release notes

# Agent calls:
web_search(query="Python 3.13 release notes")

# Returns:
{
    "answer": "Python 3.13 was released on...",
    "sources": [
        {"title": "What's New In Python 3.13", "url": "https://docs.python.org/..."},
        {"title": "Python Release Python 3.13.0", "url": "https://www.python.org/..."}
    ]
}
```

### skill - Load Specialized Skills

Loads specialized skills that provide domain-specific instructions and workflows.

```python
# Tool schema
skill(
    name: str  # Name of the skill to load
)

# Example: Loading a code review skill
skill(name="code-review")

# Returns:
{
    "name": "code-review",
    "content": "<skill_content name=\"code-review\">\n# Skill: code-review\n...",
    "skill_dir": "/home/user/.vibe/skills/code-review"
}
```

## Configuration

### Configuration File (config.toml)

```toml
# ~/.vibe/config.toml

# Active model selection
active_model = "devstral-2"

# General settings
vim_keybindings = false
autocopy_to_clipboard = true
enable_telemetry = true
enable_auto_update = true
enable_notifications = true
api_timeout = 720.0
auto_compact_threshold = 200000

# Custom system prompt
system_prompt_id = "cli"

# Provider configuration
[[providers]]
name = "mistral"
api_base = "https://api.mistral.ai/v1"
api_key_env_var = "MISTRAL_API_KEY"
backend = "mistral"

[[providers]]
name = "llamacpp"
api_base = "http://127.0.0.1:8080/v1"
api_key_env_var = ""

# Model configuration
[[models]]
name = "mistral-vibe-cli-latest"
provider = "mistral"
alias = "devstral-2"
temperature = 0.2
input_price = 0.4
output_price = 2.0
thinking = "off"

[[models]]
name = "devstral"
provider = "llamacpp"
alias = "local"
input_price = 0.0
output_price = 0.0

# Tool configuration
[tools.bash]
permission = "ask"
default_timeout = 300
allowlist = ["git status", "git diff", "git log", "ls"]

[tools.read_file]
permission = "always"
sensitive_patterns = ["**/.env", "**/.env.*"]

[tools.write_file]
permission = "ask"

# Tool enable/disable patterns
enabled_tools = []  # Empty means all enabled
disabled_tools = ["mcp_*"]  # Disable all MCP tools

# MCP Server configuration
[[mcp_servers]]
name = "fetch_server"
transport = "stdio"
command = "uvx"
args = ["mcp-server-fetch"]
env = { "DEBUG" = "1" }
startup_timeout_sec = 10.0
tool_timeout_sec = 60.0

[[mcp_servers]]
name = "my_http_server"
transport = "http"
url = "http://localhost:8000"
headers = { "Authorization" = "Bearer token" }

# Session logging
[session_logging]
save_dir = "~/.vibe/logs"
session_prefix = "session"
enabled = true

# Skills configuration
skill_paths = ["/path/to/custom/skills"]
enabled_skills = ["code-review", "test-*"]
disabled_skills = ["experimental-*"]
```

### API Key Configuration

```bash
# Environment variable
export MISTRAL_API_KEY="your_api_key_here"

# Or in ~/.vibe/.env
MISTRAL_API_KEY=your_api_key_here

# Interactive setup
vibe --setup
```

## Agent Client Protocol (ACP) Integration

### Zed Editor Configuration

```json
// ~/.config/zed/settings.json
{
   "agent_servers": {
      "Mistral Vibe": {
         "type": "custom",
         "command": "vibe-acp",
         "args": [],
         "env": {}
      }
   }
}
```

### JetBrains IDE Configuration

```json
// acp.json
{
  "agent_servers": {
    "Mistral Vibe": {
      "command": "vibe-acp"
    }
  }
}
```

### Neovim (avante.nvim) Configuration

```lua
{
  acp_providers = {
    ["mistral-vibe"] = {
      command = "vibe-acp",
      env = {
         MISTRAL_API_KEY = os.getenv("MISTRAL_API_KEY"),
      },
    }
  }
}
```

## Skills System

### Creating a Custom Skill

```markdown
<!-- ~/.vibe/skills/code-review/SKILL.md -->
---
name: code-review
description: Perform automated code reviews
license: MIT
compatibility: Python 3.12+
user-invocable: true
allowed-tools:
  - read_file
  - grep
  - ask_user_question
---

# Code Review Skill

This skill helps analyze code quality and suggest improvements.

## Workflow

1. Identify files to review
2. Analyze code patterns
3. Check for common issues
4. Provide actionable feedback
```

### Skill Directory Structure

```
~/.vibe/skills/
└── code-review/
    ├── SKILL.md          # Skill definition
    ├── templates/        # Reference templates
    │   └── review.md
    └── scripts/          # Helper scripts
        └── lint.sh
```

## Built-in Agent Profiles

```bash
# Default agent - requires approval for tool executions
vibe --agent default

# Plan mode - read-only exploration, auto-approves safe tools
vibe --agent plan

# Accept edits - auto-approves file edits only
vibe --agent accept-edits

# Auto-approve - auto-approves all tools (use with caution)
vibe --agent auto-approve
```

### Custom Agent Configuration

```toml
# ~/.vibe/agents/redteam.toml
active_model = "devstral-2"
system_prompt_id = "redteam"

disabled_tools = ["search_replace", "write_file"]

[tools.bash]
permission = "always"

[tools.read_file]
permission = "always"
```

## Summary

Mistral Vibe serves as a comprehensive AI coding assistant for developers who prefer working in the terminal. Its primary use cases include interactive code exploration and modification, automated refactoring with precise SEARCH/REPLACE operations, codebase analysis through grep and file reading, shell command execution for build and test workflows, and task delegation to specialized subagents. The tool integrates seamlessly with version control via Git commands and supports extending functionality through MCP servers and custom skills.

For integration patterns, Vibe can be used standalone via the CLI for ad-hoc tasks, in programmatic mode for CI/CD pipelines and scripting, or through the ACP protocol for IDE integration with Zed, JetBrains, and Neovim. The configuration system allows fine-grained control over tool permissions, model selection, and behavior customization through TOML files. The trust folder mechanism ensures security when working with projects containing local configurations, while the session system enables resuming conversations and maintaining context across multiple interactions.