Add Mistral Vibe as coding agent

[dsyme]

After talking with Pini Wietchner at Mistral we will take a look at adding support for Mistral Vibe

@pelikhan is tidying up the internal engineering to make sure adding new coding agents is reasonably straight-forward.

I asked Opus to take a look at the coding agent features needed, download Mistral Vibe CLI and analyze what's what according what's needed. Here's what it came up with

Technical Requirements for Coding Agent CLI Integration with gh-aw

Support Comparison Table

Requirement	Copilot CLI	Claude Code	Codex	Mistral Vibe
P0 - Core CLI
Non-interactive mode	✅ --prompt	✅ --print	✅ exec subcommand	✅ -p (programmatic mode)
Prompt input	✅ --prompt "..."	✅ positional arg	✅ exec "..."	✅ positional or -p "..."
Prompt from file	✅ stdin/shell	✅ stdin/shell	✅ stdin/shell	✅ stdin/shell
Exit codes	✅	✅	✅	✅
Installation method	npm @github/copilot	npm @anthropic-ai/claude-code	npm @openai/codex	curl install script (uv/pip)
P0 - Authentication
API key via env var	✅ COPILOT_GITHUB_TOKEN	✅ ANTHROPIC_API_KEY	✅ OPENAI_API_KEY	✅ MISTRAL_API_KEY
P1 - MCP Integration
MCP config file	✅ --mcp-config	✅ --mcp-config	⚠️ In development	⚠️ config.toml only¹
Tool allow-listing	✅ --allow-tool	✅ --allowed-tools	⚠️ Limited	✅ --enabled-tools²
Granular tool perms	✅ server(tool)	✅ mcp__server__tool	❌	⚠️ glob/regex patterns
P1 - Logging
Structured logs	✅ JSONL session files	✅ --debug-file	⚠️ Text logs	✅ --output json|streaming
Log file output	✅ --log-dir	✅ --debug-file	⚠️ stderr redirect	⚠️ session logs only³
Verbose mode	✅ --log-level all	✅ --verbose	⚠️ Limited	⚠️ config-based
Token usage in logs	✅	✅	⚠️	⚠️ Session summary
Tool calls in logs	✅	✅	⚠️	✅
P2 - Configuration
Custom model	✅ --model	✅ --model	✅ -c model=	⚠️ config.toml only
Max turns/iterations	❌	✅ --max-turns	❌	✅ --max-turns
Max cost limit	❌	❌	❌	✅ --max-price
Custom CLI args	✅	✅	✅	✅
P2 - Security
Directory access control	✅ --add-dir	❌	❌	⚠️ Trust folder system
Network restrictions	⚠️ Via AWF sandbox	⚠️ Via AWF sandbox	⚠️ Via AWF sandbox	❌
Auto-approve mode	❌ (uses sandbox)	✅ --dangerously-skip-permissions	✅ --dangerously-bypass...	✅ -p auto-approves
Disable confirmations	✅ --accept	✅ --disable-slash-commands	✅ (part of bypass)	✅ -p mode
P2 - Advanced
Agent/system prompt files	✅ --agent	❌	❌	✅ --agent NAME⁴
Built-in web-fetch	✅	✅	❌	❌
Built-in web-search	❌	✅	✅ --search	❌
Plugin system	✅ copilot plugin install	❌	❌	✅ Skills system
Session resume	❌	❌	❌	✅ --continue, --resume
Working directory	✅ --workdir (planned)	❌	❌	✅ --workdir

Legend: ✅ Full support | ⚠️ Partial/limited | ❌ Not supported

Footnotes

¹ Mistral Vibe MCP: MCP servers configured via ~/.vibe/config.toml [[mcp_servers]] section, not CLI flag. Supports stdio, http, streamable-http transports.

² Vibe tool patterns: --enabled-tools supports exact names, glob patterns (bash*), and regex (re:^pattern$).

³ Vibe logging: Session logs stored in ~/.vibe/logs/. JSON output via --output json only in programmatic mode.

⁴ Vibe agents: References TOML files in ~/.vibe/agents/NAME.toml, not markdown files.

---

Requirements for gh-aw Integration

1. Core CLI Interface

Essential:

• Non-interactive execution mode: CLI must support fully automated, non-interactive operation (no user prompts/confirmations)
• Prompt/instruction input: Accept multi-line natural language instructions via:
  • Command-line argument (e.g., --prompt "instruction" or positional argument)
  • File input (e.g., --prompt-file /path/to/prompt.txt)
  • Stdin (pipe input)
• Exit codes: Return 0 on success, non-zero on failure
• Installation: Installable via npm (npm install -g @mistral/vibe-cli) or provide equivalent installation method

2. Authentication

Essential:

• Support API key authentication via environment variable (e.g., MISTRAL_API_KEY)
• Document required API key permissions/scopes

3. MCP (Model Context Protocol) Integration

Highly Recommended:

• Support MCP server configuration via JSON config file (e.g., --mcp-config /path/to/config.json)
• Support tool allow-listing to restrict which MCP tools the agent can invoke
  • Granular permissions: --allow-tool server_name(tool_name)
  • Server-wide permissions: --allow-tool server_name
• Standard MCP JSON config format:

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {"GITHUB_TOKEN": "..."}
    }
  }
}

4. Logging & Observability

Essential:

• Structured logs: Output logs in parseable format (JSONL strongly preferred)
• Log file output: Support writing logs to file (e.g., --log-file /path/to/log.txt or --debug-file)
• Verbose mode: Flag for detailed debugging output (e.g., --verbose, --debug)

Log should include:

• Token usage metrics (input/output tokens per turn)
• Tool calls (tool name, input size, output size, call count)
• Number of agent turns/iterations
• Error messages with clear failure reasons

Example JSONL log format:

{"type": "assistant", "message": {"content": [{"type": "tool_use", "name": "bash", "input": {...}}]}}
{"type": "user", "message": {"content": [{"type": "tool_result", "content": "..."}]}}
{"type": "result", "usage": {"input_tokens": 1500, "output_tokens": 300}, "num_turns": 5}

5. Configuration Options

Recommended:

• Custom model selection: --model model-name to override default model
• Max iterations: --max-turns N to limit agent iterations (prevent runaway costs)
• Custom arguments: Support arbitrary CLI flags that can be passed through workflow configuration

6. Sandboxing & Security

Optional but Valuable:

• Directory access control: Ability to restrict file system access (e.g., --add-dir /allowed/path)
• Network restrictions: Support for domain allow-listing or firewall integration
• Command approval bypass: Flag to skip interactive confirmations (e.g., --non-interactive, --auto-approve)

7. Advanced Features

Nice to Have:

• Agent files: Support loading custom system prompts from files (e.g., --agent /path/to/agent.md)
• Built-in tools: Native support for web-fetch, web-search, or other utility tools
• Plugin system: Extensibility via plugins
• Session management: Ability to persist/resume sessions

---

Mistral Vibe: Current Status & Gaps

Based on analysis of Mistral Vibe v2.1.0:

✅ Fully Supported

• Non-interactive mode (-p flag with auto-approve)
• Max turns (--max-turns)
• Max cost limit (--max-price) - unique feature!
• Tool allow-listing (--enabled-tools with glob/regex)
• JSON/streaming output (--output json|streaming)
• Agent profiles (--agent NAME)
• Working directory (--workdir)
• Session resume (--continue, --resume)
• MCP servers (via config.toml)
• API key via MISTRAL_API_KEY

⚠️ Gaps for gh-aw Integration

1. MCP config via CLI flag: Currently requires config.toml, no --mcp-config /path/to/file.json flag

   • Workaround: Generate ~/.vibe/config.toml dynamically or use VIBE_HOME env var

2. Model selection via CLI: No --model flag, requires config.toml

   • Workaround: Generate config.toml with active_model

3. Log file path control: Logs go to ~/.vibe/logs/, no --log-file flag

   • Workaround: Use VIBE_HOME to control log location, or parse --output streaming

4. No --verbose CLI flag: Verbosity controlled via config

   • Workaround: Pre-configure in config.toml

Recommended CLI Additions for gh-aw Compatibility

# Proposed new flags for Vibe CLI:
vibe -p "prompt" \
  --mcp-config /path/to/mcp-servers.json \  # ⭐ NEW: MCP config file path
  --model devstral-2 \                       # ⭐ NEW: Model selection
  --log-file /path/to/output.log \           # ⭐ NEW: Log file path
  --enabled-tools "github_*" "bash" \
  --max-turns 20 \
  --output streaming

---

Example gh-aw Integration Command

With current Vibe capabilities:

# Set Vibe home to control config location
export VIBE_HOME=/tmp/gh-aw/vibe-config

# Pre-generate config.toml with MCP servers
cat > "$VIBE_HOME/config.toml" << 'EOF'
active_model = "devstral-2"

[[mcp_servers]]
name = "github"
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { "GITHUB_TOKEN" = "${GITHUB_TOKEN}" }
EOF

# Execute Vibe in programmatic mode
vibe -p "$(cat /tmp/gh-aw/prompt.txt)" \
  --enabled-tools "github_*" "bash" "read_file" "write_file" \
  --max-turns 20 \
  --max-price 5.00 \
  --output streaming \
  2>&1 | tee /tmp/gh-aw/agent-stdio.log

---

Priority Levels

• P0 (Must Have): Items 1-2 (Core CLI + Authentication) - ✅ Vibe meets these
• P1 (Strongly Recommended): Items 3-4 (MCP + Logging) - ⚠️ Vibe partially meets (workarounds available)
• P2 (Nice to Have): Items 5-7 (Configuration + Security + Advanced) - ✅ Vibe has many advanced features

---

This specification enables gh-aw to compile workflow markdown files into GitHub Actions that install and execute coding agent CLIs in a sandboxed, observable, and controlled manner.

[pelikhan]

/scout use the add custom agentic engine agent.md as a guide to research the docs of mistral and investigate viability.

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan

Executive Summary

Mistral AI is HIGHLY VIABLE as a custom agentic engine for gh-aw. The platform offers:

✅ Strong Agent Framework with Agents & Conversations API
✅ Native MCP Support (Model Context Protocol integration)
✅ Comprehensive Tool Capabilities (function calling, built-in tools, custom tools)
✅ Streaming & Conversation Management built-in
✅ Competitive Pricing ($0.02-$6.00 per million tokens depending on model)

Recommendation: Mistral is a strong candidate for integration with gh-aw's custom engine architecture.

View Detailed Research Findings

Research Findings

Core Capabilities Assessment

1. Agent Architecture ✅

Mistral Agents API provides:

• Persistent conversations with state management across turns
• Streaming output support (token-by-token generation)
• Agent orchestration (multi-agent handoffs and collaboration)
• Conversation branching for exploring alternative paths
• Memory persistence across interactions

Relevance: Maps directly to gh-aw's agentic workflow patterns.

Sources:

• (mistral.ai/redacted)
• (www.datacamp.com/redacted)

2. MCP Integration ⭐ EXCELLENT

Mistral's MCP Support:

• Native Python SDK integration with MCP clients
• Multiple MCP transports: STDIO, SSE, HTTP
• Built-in MCP orchestration for local function calling
• Flexible configuration via JSON config files
• Gateway support for hosted MCP servers

Implementation Pattern:

from mistralai import Mistral
from mistralai.extra.mcp.sse import MCPClientSSE, SSEServerParams
from mistralai.extra.run.context import RunContext

# Initialize with MCP client
run_ctx = RunContext()
mcp_client = MCPClientSTDIO(stdio_params=server_params)
await run_ctx.register_mcp_client(mcp_client=mcp_client)
```

**Relevance**: Mistral's MCP support is MORE comprehensive than many competitors. This is a major advantage for gh-aw integration.

**Sources:**
- (docs.mistral.ai/redacted)
- (platformdocspublic.pages.dev/redacted)

#### 3. Tool Calling & Function Support ✅

**Available Tool Types:**

**Built-in Connectors:**
- `websearch` - Web search capabilities
- `code_interpreter` - Code execution in sandboxed environments
- `image_generation` - Image generation
- `document_library` - RAG functionality with uploaded documents

**Custom Tools:**
- **Standard function calling** via JSON schema definitions
- **Parallel function calling** support
- **Successive function calling** for multi-step operations
- **Tool result handling** with structured responses

**Function Calling Flow:**
```
system → user → assistant function_call → tool_result → assistant → user

Relevance: Comprehensive tool support matches gh-aw's MCP tooling requirements.

Sources:

• (docs.mistral.ai/redacted)
• (docs.mistral.ai/redacted)

4. API Architecture & Integration Points ✅

Key Features:

• Agents API for creating persistent agents with instructions
• Conversations API for managing stateful interactions
• Streaming support via stream: true parameter
• Conversation history automatically managed server-side
• Agent handoffs for multi-agent workflows

API Endpoints:

• POST /v1/agents - Create agent
• POST /v1/conversations - Start conversation
• POST /v1/conversations/{id} - Continue conversation
• Supports both agent-based and direct conversation modes

Relevance: Clean API design aligns well with gh-aw's engine interface patterns.

Sources:

• (docs.mistral.ai/redacted)
• (mistral.ai/redacted)

5. Available Models & Performance

Supported Agent Models:

• mistral-medium-latest (mistral-medium-2505) - Balanced performance
• mistral-large-latest - Flagship model, best reasoning
• mistral-small - Cost-optimized for high-volume tasks
• codestral - Specialized for code generation

Model Characteristics:

• Context windows: 32K-131K tokens depending on model
• Streaming support across all models
• Tool calling supported on medium and large models

Sources:

• (www.datacamp.com/redacted)
• (www.mindstudio.ai/redacted)

Implementation Mapping to gh-aw

Based on the custom-engine-implementation.agent.md guide, here's how Mistral maps to gh-aw's architecture:

Interface Implementation Mapping

gh-aw Interface	Mistral Capability	Implementation Notes
Engine (core)	✅ Agents API	ID: mistral, Display: "Mistral AI"
CapabilityProvider	✅ Full support	Tools allowlist, MCP, firewall, web search
WorkflowExecutor	✅ Via API calls	Installation: npm/pip, Execution: API-based
MCPConfigProvider	⭐ Native	JSON config format, gateway support
LogParser	⚠️ Custom needed	Would need to parse Agents API response logs
SecurityProvider	✅ API key based	Secret: MISTRAL_API_KEY

Installation Steps Pattern

func (e *MistralEngine) GetInstallationSteps(workflowData *WorkflowData) []GitHubActionStep {
    // 1. Secret validation for MISTRAL_API_KEY
    // 2. Python SDK installation (pip install mistralai)
    // 3. MCP gateway setup if MCP servers present
    // 4. AWF firewall installation if enabled
}

Execution Steps Pattern

func (e *MistralEngine) GetExecutionSteps(workflowData *WorkflowData, logFile string) []GitHubActionStep {
    // 1. Create agent via Agents API
    // 2. Start conversation with prompt
    // 3. Stream responses and handle tool calls
    // 4. Manage conversation continuation
    // 5. Write results to safe-outputs
}

MCP Configuration

Mistral supports JSON-based MCP configuration similar to Claude:

{
  "github": {
    "command": "uvx",
    "args": ["mcp-server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "..."
    }
  }
}

Implementation: Can reuse gh-aw's existing RenderJSONMCPConfig helper with Mistral-specific renderer options.

Pricing Analysis

API Pricing (as of 2026):

Model	Input (per 1M tokens)	Output (per 1M tokens)	Context Window
Mistral Small 3.2	$0.06	$0.18	131K
Mistral Medium	$0.30	$1.10	131K
Mistral Large 2	$2.00	$6.00	131K
Mistral Nemo	$0.02	$0.04	131K

Cost Comparison:

• More expensive than: DeepSeek R1 ($0.55/$2.19), Gemini Flash ($0.15/$0.60)
• Less expensive than: Claude Opus 4 ($15), GPT-4 series
• Competitive with: Claude Sonnet, GPT-4 Turbo range

Cost Efficiency for gh-aw:

• Small workflows (~10K tokens): $0.0006 - $0.02 per run
• Medium workflows (~50K tokens): $0.003 - $0.10 per run
• Large workflows (~200K tokens): $0.012 - $0.40 per run

Enterprise Pricing: Custom pricing available for high-volume deployments.

Sources:

• (mistral.ai/redacted)
• (pricepertoken.com/redacted)

Viability Assessment Matrix

Criterion	Score	Notes
Agent Architecture	9/10	Excellent Agents API with stateful conversations
MCP Support	10/10	Native Python SDK integration, multiple transports
Tool Integration	9/10	Built-in + custom tools, parallel execution
Streaming	9/10	Native streaming support via API
Documentation	8/10	Good docs, but some examples dated
API Stability	8/10	Relatively new Agents API (2025), evolving
Cost Efficiency	7/10	Competitive but not cheapest option
Developer Experience	8/10	Python SDK is polished, examples available
gh-aw Integration Complexity	6/10	Moderate - API-based vs CLI-based
Production Readiness	8/10	Stable models, proven at scale

Overall Viability Score: 82/100 - HIGHLY VIABLE

Implementation Challenges & Solutions

Challenge 1: API-Based vs CLI-Based

Issue: Mistral uses API calls rather than CLI commands (unlike Claude Code or Copilot CLI).

Solution: Implement a lightweight Python wrapper script that:

• Takes prompt from /tmp/gh-aw/aw-prompts/prompt.txt
• Manages conversation state
• Handles streaming output
• Writes results in gh-aw's expected format

Precedent: Similar to how Codex engine wraps the codex command.

Challenge 2: Conversation State Management

Issue: Agent conversations need to be persisted across tool calls.

Solution:

• Store conversation_id in workflow environment
• Use Mistral's conversation continuation API
• Implement state recovery for interrupted workflows

Complexity: Medium - requires careful state handling.

Challenge 3: Log Parsing

Issue: Mistral's API responses are JSON-based, not traditional log files.

Solution:

• Implement custom ParseLogMetrics() to extract from API responses
• Parse JSON for turns, token usage, tool calls
• Convert to gh-aw's LogMetrics structure

Complexity: Low - straightforward JSON parsing.

Challenge 4: MCP Gateway Integration

Issue: Mistral's Python SDK expects MCP clients in-process.

Solution:

• Use gh-aw's MCP gateway for remote MCP servers
• Configure Mistral agent to use gateway-exposed tools as function calls
• Map MCP tool calls to Mistral function calling format

Complexity: Medium - requires protocol translation layer.

Comparison with Existing Engines

Feature	Claude	Copilot	Codex	Mistral
CLI Tool	✅	✅	✅	⚠️ API-based
MCP Support	✅	✅	✅	✅ Native
Streaming	✅	✅	✅	✅
Tool Calling	✅	✅	✅	✅ Comprehensive
Conversation State	✅	✅	✅	✅ Server-managed
Agent Handoffs	⚠️ Limited	❌	❌	✅ Built-in
Pricing	$$$ High	$$ Medium	$ Low	$$ Medium
Self-Hosting	❌	❌	❌	⚠️ Models only

Key Differentiators:

• Native MCP orchestration (better than most)
• Multi-agent handoffs (unique feature)
• Conversation branching (useful for exploratory workflows)
• API-first design (different integration pattern)

Recommended Implementation Approach

Phase 1: Core Engine (Week 1-2)

1. Create mistral_engine.go

   • Implement MistralEngine struct embedding BaseEngine
   • Set capability flags (tools allowlist, MCP, firewall, web search)
   • Define required secrets (MISTRAL_API_KEY, MCP_GATEWAY_API_KEY)

2. Create Python wrapper script (mistral-agent-wrapper.py)

   • Read prompt from /tmp/gh-aw/aw-prompts/prompt.txt
   • Initialize Mistral client with API key
   • Create agent with model and instructions
   • Handle streaming output
   • Manage conversation state

3. Installation steps

   • Secret validation for MISTRAL_API_KEY
   • Python + pip installation
   • pip install mistralai (SDK installation)
   • MCP gateway setup if needed

4. Execution steps

   • Run Python wrapper with environment setup
   • Pipe output to log file
   • Handle AWF firewall wrapping if enabled

Phase 2: MCP Integration (Week 2-3)

1. Implement RenderMCPConfig()

   • Use JSON format (like Claude)
   • Leverage RenderJSONMCPConfig helper
   • Support GitHub, Playwright, custom MCP servers
   • Configure safe-outputs and safe-inputs

2. MCP Gateway Integration

   • Configure gateway in Mistral agent context
   • Map MCP tool calls to function calling format
   • Handle tool results and conversation flow

3. Testing

   • Test with GitHub MCP server
   • Test with Playwright MCP server
   • Test custom MCP servers
   • Verify tool calling and results handling

Phase 3: Advanced Features (Week 3-4)

1. Log Parsing

   • Implement ParseLogMetrics() for JSON responses
   • Extract turns, token usage, tool calls from API responses
   • Create JavaScript parser if needed

2. Conversation Management

   • Implement conversation ID persistence
   • Handle conversation continuation
   • Support conversation branching (optional)

3. Agent Handoffs (Optional)

   • Explore multi-agent workflows
   • Implement handoff patterns if beneficial

4. Documentation

   • Add to docs/src/content/docs/reference/engines.md
   • Create example workflows
   • Document setup and configuration

Phase 4: Testing & Refinement (Week 4)

1. Unit Tests (mistral_engine_test.go)
2. Integration Tests (workflow compilation)
3. End-to-End Tests (actual agent execution)
4. Documentation Review
5. Performance Optimization

Estimated Total Effort: 3-4 weeks for full implementation

Recommendations

1. Proceed with Implementation ✅

Mistral AI is a strong candidate for gh-aw integration. The platform's native MCP support, comprehensive tool calling, and agent-first architecture align well with gh-aw's requirements.

2. Use Python SDK Wrapper Approach

Since Mistral is API-based rather than CLI-based, implement a lightweight Python wrapper script to bridge the gap. This is similar to how other API-based tools are integrated in agentic workflows.

3. Leverage Existing gh-aw Infrastructure

• MCP Gateway: Use gh-aw's MCP gateway for remote servers
• JSON MCP Config: Reuse RenderJSONMCPConfig helper
• AWF Firewall: Standard firewall integration patterns
• Safe Outputs: Standard integration via environment variables

4. Start with Basic Implementation

Focus on core functionality first:

• Simple agent creation and execution
• Basic MCP support (GitHub, Playwright)
• Streaming output
• Conversation persistence

Add advanced features (multi-agent, handoffs) in later iterations.

5. Consider Cost Implications

Mistral's pricing is competitive but not the cheapest. Organizations should:

• Start with mistral-small for cost-sensitive workflows
• Use mistral-medium for balanced performance
• Reserve mistral-large for complex reasoning tasks

6. Monitor API Evolution

Mistral's Agents API is relatively new (2025). Stay updated on:

• API stability and changes
• New model releases
• MCP integration improvements
• Pricing adjustments

Key Sources

Official Documentation:

• [Mistral Agents API]((mistral.ai/redacted)
• [Mistral MCP Documentation]((docs.mistral.ai/redacted)
• [Function Calling Guide]((docs.mistral.ai/redacted)
• [Agents API Reference]((docs.mistral.ai/redacted)

Implementation Guides:

• [DataCamp Mistral Agents Tutorial]((www.datacamp.com/redacted)
• [Building Agents with MCP]((grski.pl/redacted)
• GitHub MCP Example

Architecture & Integration:

• [AWS Mistral MCP Integration]((aws.amazon.com/redacted)
• [MindStudio Mistral Guide]((www.mindstudio.ai/redacted)

Pricing & Comparison:

• [Official Pricing]((mistral.ai/redacted)
• [Price Per Token Comparison]((pricepertoken.com/redacted)
• [2026 LLM Provider Comparison]((futureagi.substack.com/redacted)

---

Next Steps: If proceeding with implementation, I recommend starting with the Phase 1 approach outlined above and referencing the comprehensive guides in scratchpad/adding-new-engines.md and .github/agents/custom-engine-implementation.agent.md.

🔭 Intelligence gathered by Scout for issue #16145

[pelikhan]

Use https://github.com/github/gh-aw/blob/main/.github/agents/custom-engine-implementation.agent.md , mark it experimental.
Use port 10004

[dsyme]

Should we be integrating SDK or Mistral Vibe CLI?

[pelikhan]

Always cli. No sdk. It is stabler.