Skip to content
Back to search

vibec

MCP server that delegates coding subtasks from Claude Code to Mistral Vibe: headless, budget-capped, every run logged.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nemois-git--vibec/badge.svg)](/listings/nemois-git--vibec)

HTML

<a href="/listings/nemois-git--vibec"><img src="/api/listings/nemois-git--vibec/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Project level (default): nothing to do.** Clone the repo and open it in Claude Code. `.mcp.json` registers the `delegate` MCP server, `.claude/settings.json` auto-enables project MCP servers (`enableAllProjectMcpServers`) and pre-approves the three `mcp__delegate__*` tools, and `.claude/commands/delegate.md` adds the `/delegate` slash command.

**User level (optional, every project):**

./install.sh            # installs /delegate and the MCP server into ~/.claude and registers "delegate" (user scope)
./install.sh --dry-run  # prints what would change; touches nothing

Re-running `install.sh` updates the installed copy. It also migrates an earlier install under the name `vibe`: the old command and server files move to `~/.claude/migrated/vibe-<timestamp>/`, the user-scope `vibe` server is removed, and `delegate` is registered in its place. `install.sh` warns about `mcp__vibe__*` permission rules in `~/.claude/settings.json` but does not edit them; replace them with `mcp__delegate__delegate_run`, `mcp__delegate__delegate_wait`, `mcp__delegate__delegate_status`, `mcp__delegate__delegate_interrupt`, and `mcp__delegate__delegate_doctor`. `--skip-existing` keeps files that already exist.

Projects that used the earlier version rename `.claude/vibe-delegate.env` to `.claude/delegate.env` and the `VIBE_DELEGATE_*` keys to `DELEGATE_*`. Run logs move from `.vibe-delegate/` to `.delegate/`; old logs are not migrated.

The CLI path named in tool descriptions and instructions is the `delegate_mcp.py` that is running, so it fits either scope: `scripts/delegate_mcp.py` (project, via `.mcp.json`) or `~/.claude/mcp/delegate_mcp.py` (user, via `claude mcp add`).

**Verify the setup** (either in chat as a tool call, or in a shell):

mcp__delegate__delegate_doctor
# or
bash scripts/delegate.sh --doctor

`--doctor` checks: `vibe` on PATH + version, `claude` on PATH, MCP files present, config file parseable, log dir writable, `jq`. One `PASS`/`WARN`/`FAIL` line per check; exit code is non-zero on any `FAIL`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 236 lines
  1. # vibec
  2. Delegate implementation and review work from **Claude Code** to **Mistral Vibe** (`mistral-vibe` CLI) over **MCP**.
  3. Claude Code stays the orchestrator for long-horizon work. Self-contained subtasks -- simple file edits, implementation, review passes, test/fix loops -- are delegated through the `vibe` MCP server, which runs headless (`vibe -p`) inside the repo with Vibe's own tools and model, then returns a structured result. Every run is logged, so status and cost are auditable afterwards.
  4. This repo is MCP-based on purpose: a Claude Code *subagent* always inherits the session's model (e.g. Sonnet), so a "vibe" subagent would still run on Sonnet. An MCP *tool* is deterministic: the Claude side only calls `mcp__delegate__delegate_run`, and the actual work runs on Mistral via `vibe -p`.
  5. ## How it works
  6. ```
  7. Claude Code (main agent -- orchestration stays here)
  8. | MCP tool call: mcp__delegate__delegate_run(task, mode?, model?, budgets?)
  9. v
  10. scripts/delegate_mcp.py (MCP stdio server, registered via .mcp.json)
  11. | executes
  12. v
  13. scripts/delegate.sh (single source of config/args/logging)
  14. | builds: vibe -p "<task>" --workdir <repo> --trust --<mode flag>
  15. | [--model A] [--max-turns T] [--max-price P] [--max-tokens K]
  16. | [--time-limit S] --output text --output-dir runs/<ts>/
  17. v
  18. vibe -p (headless: own context, own model, own tool loop; edits/tests run in the repo)
  19. |
  20. v
  21. .delegate/runs.log + .delegate/runs/<ts>/
  22. (stdout.txt, stderr.txt, export.json, session journal)
  23. |
  24. +-- structured result back to Claude Code:
  25. answer, exit_code, run, run_dir, session_id, cost_usd, usage, outcome
  26. ```
  27. ## Requirements
  28. - Claude Code (CLI, Desktop, or VS Code extension -- all load project `.mcp.json`).
  29. - Mistral Vibe CLI (`vibe`, developed against 3.1.2): `uv tool install mistral-vibe`
  30. - `python3` (stdlib only; the MCP server has no pip dependencies)
  31. - A Mistral API key in `~/.vibe/.env` (`MISTRAL_API_KEY=...`), or run `vibe --setup` once.
  32. - `jq` (optional) -- for ad-hoc pretty-printing of `export.json`.
  33. Note for **Claude Code Desktop on macOS**: it is a GUI app with a minimal PATH, so `~/.local/bin` (the `uv tool` location) may not be visible. If `vibe` is not found there, symlink it into a GUI-visible dir, e.g. `sudo ln -s ~/.local/bin/vibe /opt/homebrew/bin/vibe`.
  34. ## Install
  35. **Project level (default): nothing to do.** Clone the repo and open it in Claude Code. `.mcp.json` registers the `delegate` MCP server, `.claude/settings.json` auto-enables project MCP servers (`enableAllProjectMcpServers`) and pre-approves the three `mcp__delegate__*` tools, and `.claude/commands/delegate.md` adds the `/delegate` slash command.
  36. **User level (optional, every project):**
  37. ```bash
  38. ./install.sh # installs /delegate and the MCP server into ~/.claude and registers "delegate" (user scope)
  39. ./install.sh --dry-run # prints what would change; touches nothing
  40. ```
  41. Re-running `install.sh` updates the installed copy. It also migrates an earlier install under the name `vibe`: the old command and server files move to `~/.claude/migrated/vibe-<timestamp>/`, the user-scope `vibe` server is removed, and `delegate` is registered in its place. `install.sh` warns about `mcp__vibe__*` permission rules in `~/.claude/settings.json` but does not edit them; replace them with `mcp__delegate__delegate_run`, `mcp__delegate__delegate_wait`, `mcp__delegate__delegate_status`, `mcp__delegate__delegate_interrupt`, and `mcp__delegate__delegate_doctor`. `--skip-existing` keeps files that already exist.
  42. Projects that used the earlier version rename `.claude/vibe-delegate.env` to `.claude/delegate.env` and the `VIBE_DELEGATE_*` keys to `DELEGATE_*`. Run logs move from `.vibe-delegate/` to `.delegate/`; old logs are not migrated.
  43. The CLI path named in tool descriptions and instructions is the `delegate_mcp.py` that is running, so it fits either scope: `scripts/delegate_mcp.py` (project, via `.mcp.json`) or `~/.claude/mcp/delegate_mcp.py` (user, via `claude mcp add`).
  44. **Verify the setup** (either in chat as a tool call, or in a shell):
  45. ```text
  46. mcp__delegate__delegate_doctor
  47. # or
  48. bash scripts/delegate.sh --doctor
  49. ```
  50. `--doctor` checks: `vibe` on PATH + version, `claude` on PATH, MCP files present, config file parseable, log dir writable, `jq`. One `PASS`/`WARN`/`FAIL` line per check; exit code is non-zero on any `FAIL`.
  51. ## Quick start
  52. ```text
  53. /delegate "Add input validation to every CLI flag in scripts/ and make bash -n pass"
  54. mcp__delegate__delegate_status # recent runs + newest export.json
  55. mcp__delegate__delegate_doctor # health check
  56. ```
  57. Or call the tool directly with arguments:
  58. ```text
  59. mcp__delegate__delegate_run(task="Summarize README.md", mode="smart", model="my-fast-model", max_price=2)
  60. ```
  61. Suggested line for an org-level system prompt (so delegation is deterministic):
  62. > If the delegate MCP server is connected, call mcp__delegate__delegate_run for simple file edits, implementation, and review work. Orchestration, planning, and final integration decisions stay with you -- never delegate those.
  63. ## Background runs (detached; collect with wait)
  64. Every MCP tool call blocks until it returns, so long delegations should be started detached to keep the orchestrator free. Start detached, keep working, then collect the result (wake-on-finish):
  65. ```text
  66. mcp__delegate__delegate_run(task="...", background=true, alias="auth-refactor")
  67. # returns immediately: alias, run (timestamp), run_dir, pid -- registered in .delegate/aliases.json
  68. mcp__delegate__delegate_status # shows running + finished runs + aliases
  69. mcp__delegate__delegate_wait(alias="auth-refactor") # block until done; returns answer + export fields
  70. mcp__delegate__delegate_interrupt(alias="auth-refactor") # graceful stop mid-run (SIGTERM, exit 3)
  71. mcp__delegate__delegate_run(task="follow-up...", session_id="<id>") # resume the same run with a small follow-up (--resume); new tasks get a new delegation
  72. ```
  73. Runs are addressable by the returned `pid`/`run` timestamp or by a caller-chosen `alias` (stored in `.delegate/aliases.json`); `delegate_interrupt` and `delegate_wait` find a run's processes through the alias registry, the run's `dispatch.pid`, or `pgrep -f` on its command line.
  74. ## Direct CLI (same file as the MCP server, no MCP needed)
  75. The installed server file is also a standalone CLI: `python3 <delegate_mcp.py> <command>` prints the same JSON result object the corresponding MCP tool returns. Every MCP tool call blocks until it returns; the CLI equivalents of the reading tools (wait = wake-on-finish, status = monitor) are the ones to use outside MCP. If you attach an external monitor or async watcher (harness tooling that polls runs), drive it through this CLI -- MCP calls block, so they are not suitable for watch loops:
  76. ```bash
  77. # user-level install (install.sh):
  78. PY="$HOME/.claude/mcp/delegate_mcp.py"
  79. # project scope, from the repo root:
  80. # PY="$PWD/scripts/delegate_mcp.py"
  81. python3 "$PY" delegate "Summarize README.md" --mode smart --max-price 2
  82. python3 "$PY" delegate "Refactor the arg parsing..." --background --alias auth-refactor # returns run/run_dir/pid immediately
  83. python3 "$PY" status # running + finished runs + aliases
  84. python3 "$PY" wait auth-refactor --timeout 600 # wake-on-finish: blocks until .delegate/runs/<run>/meta.json appears
  85. python3 "$PY" interrupt auth-refactor # graceful stop; resume the same run later via session_id (small follow-up)
  86. python3 "$PY" doctor # health check
  87. ```
  88. Run it with the target project as the working directory (or `CLAUDE_PROJECT_DIR` set). Run log paths: `.delegate/runs/<run>/{started.json,meta.json,export.json,stdout.txt,stderr.txt}`, `.delegate/runs.log`, `.delegate/aliases.json`.
  89. ## Tools
  90. | Tool | Purpose | Key arguments |
  91. |---|---|---|
  92. | `mcp__delegate__delegate_run` | Delegate one self-contained task to the Vibe agent; blocks until done, or returns immediately with `background=true` | `task` (required), `background`, `alias`, `session_id`, `mode`, `model`, `agent`, `max_turns`, `max_price`, `max_tokens`, `time_limit`, `output` |
  93. | `mcp__delegate__delegate_wait` | Block until a background run finishes, then return the full result | `run` or `alias`, `timeout_s` (default 600) |
  94. | `mcp__delegate__delegate_status` | Running + recent finished runs, newest `export.json`, and the alias registry | `count` (default 10) |
  95. | `mcp__delegate__delegate_interrupt` | SIGTERM a running delegation (export written, exit 3); resume the same run afterwards via `session_id` (small follow-up only) | `run` or `alias`, `wait_s` (default 30) |
  96. | `mcp__delegate__delegate_doctor` | Integration health check | -- |
  97. `session_id` is for resuming a run or making a small follow-up on it, not for handing new tasks to the same agent. Each new task starts a new delegation without `session_id`.
  98. `delegate_run` returns `structuredContent` with: `answer` (Vibe's final report), `exit_code`, `duration_s`, `run`, `run_dir`, `mode`, `model`, `session_id`, `cost_usd`, `usage`, `outcome`, `stop_reason`, `vibe_version`, `stderr_tail`.
  99. ## Configuration
  100. All defaults live in `.claude/delegate.env` (shared by the team). Precedence:
  101. ```
  102. tool arguments / CLI flags > environment variables > .claude/delegate.env > built-in defaults
  103. ```
  104. | Key | Default | Meaning |
  105. |---|---|---|
  106. | `DELEGATE_MODEL` | (empty) | Model alias passed to `vibe --model`. Define aliases in your own `~/.vibe/config.toml` (`[[models]]`); empty = Vibe's default routing. The repo never overrides your providers. |
  107. | `DELEGATE_MODE` | `smart` | Approve mode: `smart` or `auto`, see below. |
  108. | `DELEGATE_AGENT` | (empty) | Optional Vibe agent profile (`--agent`), e.g. a bounded profile in `~/.vibe/agents/`. |
  109. | `DELEGATE_MAX_TURNS` | `200` | Max assistant turns of the run (root + subagents). |
  110. | `DELEGATE_MAX_PRICE` | `10` | Max cumulative cost in USD. Note: `0` does **not** mean unlimited -- it stops the run before the next call once anything has cost money. Leave empty to omit the flag. |
  111. | `DELEGATE_MAX_TOKENS` | (empty) | Max cumulative prompt+completion tokens. |
  112. | `DELEGATE_TIME_LIMIT` | `3600` | Wall-clock interrupt after this many seconds. |
  113. | `DELEGATE_OUTPUT` | `text` | `vibe -p` output: `text` (final answer), `json`, or `streaming`. |
  114. | `DELEGATE_LOG_DIR` | `.delegate` | Run log dir, relative to the project root unless absolute. |
  115. The config file is parsed line-by-line (`KEY=VALUE`, `#` comments); it is never sourced or evaluated.
  116. ## Approve modes (headless semantics)
  117. Headless mode (`vibe -p`) never prompts. The mode decides which tool calls run; denied calls are printed on stderr and recorded in `export.json`.
  118. | Mode | Flag passed to vibe | Behavior |
  119. |---|---|---|
  120. | `smart` (default) | `--smart-approve` | A classifier auto-runs the tool calls it judges safe; risky ones are denied and listed. Classifier model configurable via `[utility_models] smart_approve` in `~/.vibe/config.toml`. |
  121. | `auto` | `--auto-approve` (alias `--yolo`) | Approves every tool call. Allowlists are bypassed under auto-approve, so use it only for trusted tasks. |
  122. ## Monitoring and status
  123. Every run appends one TSV line to `.delegate/runs.log`:
  124. ```
  125. timestamp exit_code duration_s mode model agent max_turns max_price task_preview
  126. ```
  127. and writes `.delegate/runs/<timestamp>/` containing:
  128. - `stdout.txt` -- Vibe's final answer
  129. - `stderr.txt` -- warnings and denied tool calls
  130. - `export.json` -- written by `vibe --output-dir`: `vibe_version`, `usage` (input/output/cached/total tokens), `cost_usd`, `stop_reason`, `outcome`, `exit_code`, `session_id`, `limits`, `config`, `steps`, `journal_dir`
  131. - `session/` -- a copy of the session journal
  132. ```text
  133. mcp__delegate__delegate_status [count] # table of recent runs + newest export summary
  134. vibe -c # in the project dir: resume the latest Vibe session
  135. vibe --resume <id> # <id> = session_id from export.json
  136. ```
  137. Logs stay on the machine (`.delegate/` is gitignored) and never enter version control.
  138. ## Security notes
  139. - Headless runs never prompt. `smart` auto-approves only what its classifier judges safe; `auto` is a deliberate opt-in per run.
  140. - The repo's `.mcp.json` / `.claude/` files are trusted code once you open the repo in Claude Code -- review them like any other repo config. `enableAllProjectMcpServers` in `.claude/settings.json` auto-enables project MCP servers; drop it if you prefer approving each server manually.
  141. - The delegate config is parsed, never executed; the wrapper runs `vibe` with `--workdir` pinned to the repo and `--trust` scoped to that single invocation.
  142. - Budget guards (`--max-turns/--max-price/--max-tokens/--time-limit`) bound every run, root and subagents included.
  143. ## Troubleshooting
  144. | Symptom | Fix |
  145. |---|---|
  146. | `vibe` tool not found / `vibe: command not found` | `uv tool install mistral-vibe`; on Desktop (macOS) also symlink into `/opt/homebrew/bin`; then `mcp__delegate__delegate_doctor` |
  147. | `delegate` MCP server not listed | Open the repo root; check `.mcp.json`; remove `enableAllProjectMcpServers` if you want a manual approval prompt instead |
  148. | Tool call needs approval every time | Keep `.claude/settings.json` permissions for `mcp__delegate__*` |
  149. | Auth errors from vibe | Put `MISTRAL_API_KEY` in `~/.vibe/.env` or run `vibe --setup` |
  150. | `Tool call denied: ...` in the run's `stderr.txt` | The smart classifier judged the call risky. Re-run with `mode=auto` only for a trusted task, or narrow the task |
  151. | Empty answer | A text run that ends without an answer says so on stderr -- read `stderr.txt` in the run dir |
  152. | Cost/turn overruns | Lower `DELEGATE_MAX_PRICE` / `DELEGATE_MAX_TURNS` in `.claude/delegate.env` |
  153. ## File map
  154. ```
  155. .mcp.json # registers the "delegate" MCP server (python3 scripts/delegate_mcp.py)
  156. .claude/
  157. +-- commands/delegate.md # /delegate <task> -- delegates via mcp__delegate__delegate_run
  158. +-- delegate.env # shared defaults (model, approve mode, budgets, log dir)
  159. +-- settings.json # enableAllProjectMcpServers + pre-approved mcp__delegate__* tools
  160. scripts/
  161. +-- delegate_mcp.py # MCP stdio server: delegate_run / delegate_status / delegate_doctor
  162. +-- delegate.sh # wrapper: config resolution, headless vibe -p, logging, --doctor
  163. install.sh # optional user-level install into ~/.claude
  164. docs/delegate.md # detailed reference (MCP protocol notes, schemas, extension points)
  165. ```
  166. See [docs/delegate.md](docs/delegate.md) for the full reference.
  167. ## License
  168. MIT. See [LICENSE](LICENSE). Each source file carries the same copyright and SPDX header.
  169. ## Trademarks and affiliation
  170. This project is independent. It is not affiliated with, endorsed by, or sponsored by Anthropic or Mistral AI.
  171. "Claude", "Claude Code" and "Anthropic" belong to Anthropic, PBC. "Mistral", "Mistral AI" and "Mistral Vibe" belong to Mistral AI.
  172. They appear here only to describe what this project works with. Claude Code and Mistral Vibe are not included in this repository;
  173. install them separately and follow their own terms.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.