2.0.0
Co-Authored-By: Quentin Torroba <quentin.torroba@mistral.ai> Co-Authored-By: Michel Thomazo <michel.thomazo@mistral.ai> Co-Authored-By: Clément Drouin <clement.drouin@mistral.ai> Co-Authored-By: Vincent Guilloux <vincent.guilloux@mistral.ai> Co-Authored-By: Clément Siriex <clement.sirieix@mistral.ai> Co-Authored-By: Kim-Adeline Miguel <kimadeline.miguel@mistral.ai> Co-Authored-By: Thaddee Tyl <thaddee.tyl@gmail.com> Co-Authored-By: David Brochart <david.brochart@gmail.com> Co-Authored-By: Joseph Guhlin <joseph.guhlin@gmail.com> Co-Authored-By: Thomas Kenbeek <thomaskenbeek@gmail.com> Co-Authored-By: Remenby31 <baptiste.cruvellier31@gmail.com>
This commit is contained in:
Mathias Gesbert
Mathias Gesbert
parent
79f215d91c
commit
d33db9fff8
217 changed files with 16911 additions and 4305 deletions
328
README.md
328
README.md
|
|
@ -53,6 +53,39 @@ uv tool install mistral-vibe
|
|||
pip install mistral-vibe
|
||||
```
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Features](#features)
|
||||
- [Built-in Agents](#built-in-agents)
|
||||
- [Subagents and Task Delegation](#subagents-and-task-delegation)
|
||||
- [Interactive User Questions](#interactive-user-questions)
|
||||
- [Terminal Requirements](#terminal-requirements)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Usage](#usage)
|
||||
- [Interactive Mode](#interactive-mode)
|
||||
- [Trust Folder System](#trust-folder-system)
|
||||
- [Programmatic Mode](#programmatic-mode)
|
||||
- [Slash Commands](#slash-commands)
|
||||
- [Built-in Slash Commands](#built-in-slash-commands)
|
||||
- [Custom Slash Commands via Skills](#custom-slash-commands-via-skills)
|
||||
- [Skills System](#skills-system)
|
||||
- [Creating Skills](#creating-skills)
|
||||
- [Skill Discovery](#skill-discovery)
|
||||
- [Managing Skills](#managing-skills)
|
||||
- [Configuration](#configuration)
|
||||
- [Configuration File Location](#configuration-file-location)
|
||||
- [API Key Configuration](#api-key-configuration)
|
||||
- [Custom System Prompts](#custom-system-prompts)
|
||||
- [Custom Agent Configurations](#custom-agent-configurations)
|
||||
- [Tool Management](#tool-management)
|
||||
- [MCP Server Configuration](#mcp-server-configuration)
|
||||
- [Session Management](#session-management)
|
||||
- [Update Settings](#update-settings)
|
||||
- [Custom Vibe Home Directory](#custom-vibe-home-directory)
|
||||
- [Editors/IDEs](#editorsides)
|
||||
- [Resources](#resources)
|
||||
- [License](#license)
|
||||
|
||||
## Features
|
||||
|
||||
- **Interactive Chat**: A conversational AI agent that understands your requests and breaks down complex tasks.
|
||||
|
|
@ -61,6 +94,8 @@ pip install mistral-vibe
|
|||
- Execute shell commands in a stateful terminal (`bash`).
|
||||
- Recursively search code with `grep` (with `ripgrep` support).
|
||||
- Manage a `todo` list to track the agent's work.
|
||||
- Ask interactive questions to gather user input (`ask_user_question`).
|
||||
- Delegate tasks to subagents for parallel work (`task`).
|
||||
- **Project-Aware Context**: Vibe automatically scans your project's file structure and Git status to provide relevant context to the agent, improving its understanding of your codebase.
|
||||
- **Advanced CLI Experience**: Built with modern libraries for a smooth and efficient workflow.
|
||||
- Autocompletion for slash commands (`/`) and file paths (`@`).
|
||||
|
|
@ -68,6 +103,70 @@ pip install mistral-vibe
|
|||
- Beautiful Themes.
|
||||
- **Highly Configurable**: Customize models, providers, tool permissions, and UI preferences through a simple `config.toml` file.
|
||||
- **Safety First**: Features tool execution approval.
|
||||
- **Multiple Built-in Agents**: Choose from different agent profiles tailored for specific workflows.
|
||||
|
||||
### Built-in Agents
|
||||
|
||||
Vibe comes with several built-in agent profiles, each designed for different use cases:
|
||||
|
||||
- **`default`**: Standard agent that requires approval for tool executions. Best for general use.
|
||||
- **`plan`**: Read-only agent for exploration and planning. Auto-approves safe tools like `grep` and `read_file`.
|
||||
- **`accept-edits`**: Auto-approves file edits only (`write_file`, `search_replace`). Useful for code refactoring.
|
||||
- **`auto-approve`**: Auto-approves all tool executions. Use with caution.
|
||||
|
||||
Use the `--agent` flag to select a different agent:
|
||||
|
||||
```bash
|
||||
vibe --agent plan
|
||||
```
|
||||
|
||||
### Subagents and Task Delegation
|
||||
|
||||
Vibe supports subagents for delegating tasks. Subagents run independently and can perform specialized work without user interaction, preventing the context from being overloaded.
|
||||
|
||||
The `task` tool allows the agent to delegate work to subagents:
|
||||
|
||||
```
|
||||
> Can you explore the codebase structure while I work on something else?
|
||||
|
||||
🤖 I'll use the task tool to delegate this to the explore subagent.
|
||||
|
||||
> task(task="Analyze the project structure and architecture", agent="explore")
|
||||
```
|
||||
|
||||
Create custom subagents by adding `agent_type = "subagent"` to your agent configuration. Vibe comes with a built-in subagent called `explore`, a read-only subagent for codebase exploration used internally for delegation.
|
||||
|
||||
### Interactive User Questions
|
||||
|
||||
The `ask_user_question` tool allows the agent to ask you clarifying questions during its work. This enables more interactive and collaborative workflows.
|
||||
|
||||
```
|
||||
> Can you help me refactor this function?
|
||||
|
||||
🤖 I need to understand your requirements better before proceeding.
|
||||
|
||||
> 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"}
|
||||
]
|
||||
}])
|
||||
```
|
||||
|
||||
The agent can ask multiple questions at once, displayed as tabs. Each question supports 2-4 options plus an automatic "Other" option for free text responses.
|
||||
|
||||
## Terminal Requirements
|
||||
|
||||
Vibe's interactive interface requires a modern terminal emulator. Recommended terminal emulators include:
|
||||
|
||||
- **WezTerm** (cross-platform)
|
||||
- **Alacritty** (cross-platform)
|
||||
- **Ghostty** (Linux and macOS)
|
||||
- **Kitty** (Linux and macOS)
|
||||
|
||||
Most modern terminals should work, but older or minimal terminal emulators may have display issues.
|
||||
|
||||
## Quick Start
|
||||
|
||||
|
|
@ -89,6 +188,8 @@ pip install mistral-vibe
|
|||
- Prompt you to enter your API key if it's not already configured
|
||||
- Save your API key to `~/.vibe/.env` for future use
|
||||
|
||||
Alternatively, you can configure your API key separately using `vibe --setup`.
|
||||
|
||||
4. Start interacting with the agent!
|
||||
|
||||
```
|
||||
|
|
@ -112,8 +213,12 @@ Simply run `vibe` to enter the interactive chat loop.
|
|||
- **Multi-line Input**: Press `Ctrl+J` or `Shift+Enter` for select terminals to insert a newline.
|
||||
- **File Paths**: Reference files in your prompt using the `@` symbol for smart autocompletion (e.g., `> Read the file @src/agent.py`).
|
||||
- **Shell Commands**: Prefix any command with `!` to execute it directly in your shell, bypassing the agent (e.g., `> !ls -l`).
|
||||
- **External Editor**: Press `Ctrl+G` to edit your current input in an external editor.
|
||||
- **Tool Output Toggle**: Press `Ctrl+O` to toggle the tool output view.
|
||||
- **Todo View Toggle**: Press `Ctrl+T` to toggle the todo list view.
|
||||
- **Auto-Approve Toggle**: Press `Shift+Tab` to toggle auto-approve mode on/off.
|
||||
|
||||
You can start Vibe with a prompt with the following command:
|
||||
You can start Vibe with a prompt using the following command:
|
||||
|
||||
```bash
|
||||
vibe "Refactor the main function in cli/main.py to be more modular."
|
||||
|
|
@ -121,6 +226,14 @@ vibe "Refactor the main function in cli/main.py to be more modular."
|
|||
|
||||
**Note**: The `--auto-approve` flag automatically approves all tool executions without prompting. In interactive mode, you can also toggle auto-approve on/off using `Shift+Tab`.
|
||||
|
||||
### Trust Folder System
|
||||
|
||||
Vibe includes a trust folder system to ensure you only run the agent in directories you trust. When you first run Vibe in a new directory which contains a `.vibe` subfolder, it may ask you to confirm whether you trust the folder.
|
||||
|
||||
Trusted folders are remembered for future sessions. You can manage trusted folders through its configuration file `~/.vibe/trusted_folders.toml`.
|
||||
|
||||
This safety feature helps prevent accidental execution in sensitive directories.
|
||||
|
||||
### Programmatic Mode
|
||||
|
||||
You can run Vibe non-interactively by piping input or using the `--prompt` flag. This is useful for scripting.
|
||||
|
|
@ -129,18 +242,126 @@ You can run Vibe non-interactively by piping input or using the `--prompt` flag.
|
|||
vibe --prompt "Refactor the main function in cli/main.py to be more modular."
|
||||
```
|
||||
|
||||
by default it will use `auto-approve` mode.
|
||||
By default, it uses `auto-approve` mode.
|
||||
|
||||
### Slash Commands
|
||||
#### Programmatic Mode Options
|
||||
|
||||
When using `--prompt`, you can specify additional options:
|
||||
|
||||
- **`--max-turns N`**: Limit the maximum number of assistant turns. The session will stop after N turns.
|
||||
- **`--max-price DOLLARS`**: Set a maximum cost limit in dollars. The session will be interrupted if the cost exceeds this limit.
|
||||
- **`--enabled-tools TOOL`**: Enable specific tools. In programmatic mode, this disables all other tools. Can be specified multiple times. Supports exact names, glob patterns (e.g., `bash*`), or regex with `re:` prefix (e.g., `re:^serena_.*$`).
|
||||
- **`--output FORMAT`**: Set the output format. Options:
|
||||
- `text` (default): Human-readable text output
|
||||
- `json`: All messages as JSON at the end
|
||||
- `streaming`: Newline-delimited JSON per message
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
vibe --prompt "Analyze the codebase" --max-turns 5 --max-price 1.0 --output json
|
||||
```
|
||||
|
||||
## Slash Commands
|
||||
|
||||
Use slash commands for meta-actions and configuration changes during a session.
|
||||
|
||||
### Built-in Slash Commands
|
||||
|
||||
Vibe provides several built-in slash commands. Use slash commands by typing them in the input box:
|
||||
|
||||
```
|
||||
> /help
|
||||
```
|
||||
|
||||
### Custom Slash Commands via Skills
|
||||
|
||||
You can define your own slash commands through the skills system. Skills are reusable components that extend Vibe's functionality.
|
||||
|
||||
To create a custom slash command:
|
||||
|
||||
1. Create a skill directory with a `SKILL.md` file
|
||||
2. Set `user-invocable = true` in the skill metadata
|
||||
3. Define the command logic in your skill
|
||||
|
||||
Example skill metadata:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: my-skill
|
||||
description: My custom skill with slash commands
|
||||
user-invocable: true
|
||||
---
|
||||
```
|
||||
|
||||
Custom slash commands appear in the autocompletion menu alongside built-in commands.
|
||||
|
||||
## Skills System
|
||||
|
||||
Vibe's skills system allows you to extend functionality through reusable components. Skills can add new tools, slash commands, and specialized behaviors.
|
||||
|
||||
Vibe follows the [Agent Skills specification](https://agentskills.io/specification) for skill format and structure.
|
||||
|
||||
### Creating Skills
|
||||
|
||||
Skills are defined in directories with a `SKILL.md` file containing metadata in YAML frontmatter. For example, `~/.vibe/skills/code-review/SKILL.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
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.
|
||||
```
|
||||
|
||||
### Skill Discovery
|
||||
|
||||
Vibe discovers skills from multiple locations:
|
||||
|
||||
1. **Global skills directory**: `~/.vibe/skills/`
|
||||
2. **Local project skills**: `.vibe/skills/` in your project
|
||||
3. **Custom paths**: Configured in `config.toml`
|
||||
|
||||
```toml
|
||||
skill_paths = ["/path/to/custom/skills"]
|
||||
```
|
||||
|
||||
### Managing Skills
|
||||
|
||||
Enable or disable skills using patterns in your configuration:
|
||||
|
||||
```toml
|
||||
# Enable specific skills
|
||||
enabled_skills = ["code-review", "test-*"]
|
||||
|
||||
# Disable specific skills
|
||||
disabled_skills = ["experimental-*"]
|
||||
```
|
||||
|
||||
Skills support the same pattern matching as tools (exact names, glob patterns, and regex).
|
||||
|
||||
## Configuration
|
||||
|
||||
### Configuration File Location
|
||||
|
||||
Vibe is configured via a `config.toml` file. It looks for this file first in `./.vibe/config.toml` and then falls back to `~/.vibe/config.toml`.
|
||||
|
||||
### API Key Configuration
|
||||
|
||||
To use Vibe, you'll need a Mistral API key. You can obtain one by signing up at [https://console.mistral.ai](https://console.mistral.ai).
|
||||
|
||||
You can configure your API key using `vibe --setup`, or through one of the methods below.
|
||||
|
||||
Vibe supports multiple ways to configure your API keys:
|
||||
|
||||
1. **Interactive Setup (Recommended for first-time users)**: When you run Vibe for the first time or if your API key is missing, Vibe will prompt you to enter it. The key will be securely saved to `~/.vibe/.env` for future sessions.
|
||||
|
|
@ -204,7 +425,32 @@ permission = "always"
|
|||
permission = "always"
|
||||
```
|
||||
|
||||
Note: this implies that you have setup a redteam prompt names `~/.vibe/prompts/redteam.md`
|
||||
Note: This implies that you have set up a redteam prompt named `~/.vibe/prompts/redteam.md`.
|
||||
|
||||
### Tool Management
|
||||
|
||||
#### Enable/Disable Tools with Patterns
|
||||
|
||||
You can control which tools are active using `enabled_tools` and `disabled_tools`.
|
||||
These fields support exact names, glob patterns, and regular expressions.
|
||||
|
||||
Examples:
|
||||
|
||||
```toml
|
||||
# Only enable tools that start with "serena_" (glob)
|
||||
enabled_tools = ["serena_*"]
|
||||
|
||||
# Regex (prefix with re:) — matches full tool name (case-insensitive)
|
||||
enabled_tools = ["re:^serena_.*$"]
|
||||
|
||||
# Disable a group with glob; everything else stays enabled
|
||||
disabled_tools = ["mcp_*", "grep"]
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- MCP tool names use underscores, e.g., `serena_list` not `serena.list`.
|
||||
- Regex patterns are matched against the full tool name using fullmatch.
|
||||
|
||||
### MCP Server Configuration
|
||||
|
||||
|
|
@ -232,6 +478,7 @@ name = "fetch_server"
|
|||
transport = "stdio"
|
||||
command = "uvx"
|
||||
args = ["mcp-server-fetch"]
|
||||
env = { "DEBUG" = "1", "LOG_LEVEL" = "info" }
|
||||
```
|
||||
|
||||
Supported transports:
|
||||
|
|
@ -249,6 +496,9 @@ Key fields:
|
|||
- `api_key_env`: Environment variable containing the API key
|
||||
- `command`: Command to run for stdio transport
|
||||
- `args`: Additional arguments for stdio transport
|
||||
- `startup_timeout_sec`: Timeout in seconds for the server to start and initialize (default 10s)
|
||||
- `tool_timeout_sec`: Timeout in seconds for tool execution (default 60s)
|
||||
- `env`: Environment variables to set for the MCP server of transport type stdio
|
||||
|
||||
MCP tools are named using the pattern `{server_name}_{tool_name}` and can be configured with permissions like built-in tools:
|
||||
|
||||
|
|
@ -261,31 +511,63 @@ permission = "always"
|
|||
permission = "ask"
|
||||
```
|
||||
|
||||
### Enable/disable tools with patterns
|
||||
MCP server configurations support additional features:
|
||||
|
||||
You can control which tools are active using `enabled_tools` and `disabled_tools`.
|
||||
These fields support exact names, glob patterns, and regular expressions.
|
||||
- **Environment variables**: Set environment variables for MCP servers
|
||||
- **Custom timeouts**: Configure startup and tool execution timeouts
|
||||
|
||||
Examples:
|
||||
Example with environment variables and timeouts:
|
||||
|
||||
```toml
|
||||
# Only enable tools that start with "serena_" (glob)
|
||||
enabled_tools = ["serena_*"]
|
||||
|
||||
# Regex (prefix with re:) — matches full tool name (case-insensitive)
|
||||
enabled_tools = ["re:^serena_.*$"]
|
||||
|
||||
# Heuristic regex support (patterns like `serena.*` are treated as regex)
|
||||
enabled_tools = ["serena.*"]
|
||||
|
||||
# Disable a group with glob; everything else stays enabled
|
||||
disabled_tools = ["mcp_*", "grep"]
|
||||
[[mcp_servers]]
|
||||
name = "my_server"
|
||||
transport = "http"
|
||||
url = "http://localhost:8000"
|
||||
env = { "DEBUG" = "1", "LOG_LEVEL" = "info" }
|
||||
startup_timeout_sec = 15
|
||||
tool_timeout_sec = 120
|
||||
```
|
||||
|
||||
Notes:
|
||||
### Session Management
|
||||
|
||||
- MCP tool names use underscores, e.g., `serena_list` not `serena.list`.
|
||||
- Regex patterns are matched against the full tool name using fullmatch.
|
||||
#### Session Continuation and Resumption
|
||||
|
||||
Vibe supports continuing from previous sessions:
|
||||
|
||||
- **`--continue`** or **`-c`**: Continue from the most recent saved session
|
||||
- **`--resume SESSION_ID`**: Resume a specific session by ID (supports partial matching)
|
||||
|
||||
```bash
|
||||
# Continue from last session
|
||||
vibe --continue
|
||||
|
||||
# Resume specific session
|
||||
vibe --resume abc123
|
||||
```
|
||||
|
||||
Session logging must be enabled in your configuration for these features to work.
|
||||
|
||||
#### Working Directory Control
|
||||
|
||||
Use the `--workdir` option to specify a working directory:
|
||||
|
||||
```bash
|
||||
vibe --workdir /path/to/project
|
||||
```
|
||||
|
||||
This is useful when you want to run Vibe from a different location than your current directory.
|
||||
|
||||
### Update Settings
|
||||
|
||||
#### Auto-Update
|
||||
|
||||
Vibe includes an automatic update feature that keeps your installation current. This is enabled by default.
|
||||
|
||||
To disable auto-updates, add this to your `config.toml`:
|
||||
|
||||
```toml
|
||||
enable_auto_update = false
|
||||
```
|
||||
|
||||
### Custom Vibe Home Directory
|
||||
|
||||
|
|
@ -302,7 +584,7 @@ This affects where Vibe looks for:
|
|||
- `agents/` - Custom agent configurations
|
||||
- `prompts/` - Custom system prompts
|
||||
- `tools/` - Custom tools
|
||||
- `logs/` - Session logsRetryTo run code, enable code execution and file creation in Settings > Capabilities.
|
||||
- `logs/` - Session logs
|
||||
|
||||
## Editors/IDEs
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue