Skip to content
Back to search

vibe

Delegate a coding task to Mistral Vibe and supervise the result via git diff. Trigger: /vibe <instruction>. Claude orchestrates, Vibe codes.

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/pcx-wave--vibe-skill/badge.svg)](/listings/pcx-wave--vibe-skill)

HTML

<a href="/listings/pcx-wave--vibe-skill"><img src="/api/listings/pcx-wave--vibe-skill/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.

git clone https://github.com/pcx-wave/vibe-skill.git && cd vibe-skill && mkdir -p ~/tools ~/.claude/skills/vibe ~/.claude/skills/vibeon ~/.claude/skills/vibeoff ~/.claude/skills/vibestatus ~/.claude/skills/vibe-model-pick ~/.claude/skills/vibe-model-clear ~/.claude/skills/vibe-report && ln -sf "$(pwd)/tools/vibe-delegate" ~/tools/vibe-delegate && ln -sf "$(pwd)/tools/delegate-report" ~/tools/delegate-report && chmod +x ~/tools/vibe-delegate ~/tools/delegate-report && ln -sf "$(pwd)/SKILL.md" ~/.claude/skills/vibe/SKILL.md && ln -sf "$(pwd)/SKILL-reference.md" ~/.claude/skills/vibe/SKILL-reference.md && ln -sf "$(pwd)/VIBEON.md" ~/.claude/skills/vibeon/SKILL.md && ln -sf "$(pwd)/VIBEOFF.md" ~/.claude/skills/vibeoff/SKILL.md && ln -sf "$(pwd)/VIBESTATUS.md" ~/.claude/skills/vibestatus/SKILL.md && ln -sf "$(pwd)/VIBE-MODEL-PICK.md" ~/.claude/skills/vibe-model-pick/SKILL.md && ln -sf "$(pwd)/VIBE-MODEL-CLEAR.md" ~/.claude/skills/vibe-model-clear/SKILL.md && ln -sf "$(pwd)/VIBE-REPORT.md" ~/.claude/skills/vibe-report/SKILL.md

Step-by-step

# 1. Clone this repo
git clone https://github.com/pcx-wave/vibe-skill.git
cd vibe-skill

# 2. Install the scripts (symlinks — stay in sync with git pull)
mkdir -p ~/tools
ln -sf "$(pwd)/tools/vibe-delegate" ~/tools/vibe-delegate
ln -sf "$(pwd)/tools/delegate-report" ~/tools/delegate-report
chmod +x ~/tools/vibe-delegate ~/tools/delegate-report

# 3. Install the skills for Claude Code
mkdir -p ~/.claude/skills/vibe ~/.claude/skills/vibeon ~/.claude/skills/vibeoff ~/.claude/skills/vibestatus \
         ~/.claude/skills/vibe-model-pick ~/.claude/skills/vibe-model-clear ~/.claude/skills/vibe-report
ln -sf "$(pwd)/SKILL.md" ~/.claude/skills/vibe/SKILL.md
ln -sf "$(pwd)/SKILL-reference.md" ~/.claude/skills/vibe/SKILL-reference.md
ln -sf "$(pwd)/VIBEON.md" ~/.claude/skills/vibeon/SKILL.md
ln -sf "$(pwd)/VIBEOFF.md" ~/.claude/skills/vibeoff/SKILL.md
ln -sf "$(pwd)/VIBESTATUS.md" ~/.claude/skills/vibestatus/SKILL.md
ln -sf "$(pwd)/VIBE-MODEL-PICK.md" ~/.claude/skills/vibe-model-pick/SKILL.md
ln -sf "$(pwd)/VIBE-MODEL-CLEAR.md" ~/.claude/skills/vibe-model-clear/SKILL.md
ln -sf "$(pwd)/VIBE-REPORT.md" ~/.claude/skills/vibe-report/SKILL.md

# 4. (Optional) Enable auto-mode — Claude delegates all code tasks automatically
#    without requiring /vibe each time. Toggle with /vibeon and /vibeoff.
grep -q "vibe auto-mode" ~/.claude/CLAUDE.md 2>/dev/null || cat >> ~/.claude/CLAUDE.md << 'EOF'

# vibe auto-mode
At the start of every user request that involves writing, editing, or fixing code:
1. Run `test -f ~/.local/share/vibe-auto.flag` (silent, no output to user).
2. If the flag exists → automatically invoke the `vibe` skill exactly as if the user had typed `/vibe <their full instruction>`. Do NOT ask first, do NOT explain — just delegate.
3. If the flag is absent → proceed normally.

The flag is toggled by `/vibeon` and `/vibeoff`.
EOF

Verify with a read-only run (it must not write anything):

mkdir -p /tmp/vibe-check && ~/tools/vibe-delegate /tmp/vibe-check "Say hello in one sentence." 3 plan
# last line: === RESULT: READ-ONLY run (no writes expected) ===

Updating

Because both installs use symlinks, a `git pull` is all you need:

cd ~/vibe-skill && git pull

`~/tools/vibe-delegate` and `~/.claude/skills/vibe/SKILL.md` are automatically up to date — no re-copy needed.

> **Migrating from a previous `cp`-based install?** Replace the copies with symlinks: > ```bash > cd ~/vibe-skill > ln -sf "$(pwd)/tools/vibe-delegate" ~/tools/vibe-delegate > ln -sf "$(pwd)/SKILL.md" ~/.claude/skills/vibe/SKILL.md > ```

---

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.

SKILL.md · Manifest · 164 lines
  1. ---
  2. name: vibe
  3. description: >
  4. Delegate a coding task to Mistral Vibe and supervise the result via git diff.
  5. Trigger: /vibe <instruction>. Claude orchestrates, Vibe codes.
  6. license: MIT
  7. user-invocable: true
  8. allowed-tools:
  9. - Bash
  10. - Read
  11. - Grep
  12. ---
  13. # Vibe Orchestrator
  14. `/vibe <instruction>`: Claude writes a prompt, `~/tools/vibe-delegate` runs Mistral
  15. Vibe on it, Claude checks the result and reports. Details, edge cases and the
  16. `--with-review` procedure are in `SKILL-reference.md` (same directory): read only
  17. the section you need. Toggles, model choice and reports are separate skills
  18. (`/vibeon`, `/vibeoff`, `/vibestatus`, `/vibe-model-pick`, `/vibe-model-clear`,
  19. `/vibe-report`).
  20. ## 0. Delegate or not
  21. Delegation has a fixed cost in Claude's own context (this skill plus the run
  22. report). It pays only when Vibe does the reading and the thinking.
  23. | Task | Action |
  24. |---|---|
  25. | 1 file, ≤10 lines, location known | Edit directly |
  26. | You could do it in 1-2 turns yourself | Edit directly: a delegation costs a prompt, a run and a review, and a failed one costs double |
  27. | You could paste the final code into the prompt | Edit directly (you already did the work) |
  28. | Location unknown, logic to write, several files, much code to read | Delegate |
  29. ## 1. Workdir and decomposition
  30. - Workdir = `git rev-parse --show-toplevel`; ask if ambiguous.
  31. - One objective per run. 1 file: 5-8 turns. 2-3 files: 8-12 turns. Several
  32. distinct objectives or business logic: split into sequential runs and check
  33. `git diff` between them. Never more than 12 turns. A turn costs ~60–90 s wall
  34. clock under a thinking model: at 300–480 s only ~4–6 turns run, so keep one
  35. run to ONE new file at that budget.
  36. - Split by objective, not by file: the same mechanical change across 10 files
  37. is ONE run (each run costs you a prompt, a report and extra turns; a
  38. 10-module change split into 8 runs cost 35 % more than the same change in 4).
  39. ## 2. Write the prompt (English, self-contained)
  40. ```
  41. Stack: <languages, frameworks> # optional
  42. TASK: <one imperative>
  43. MODIFY: a.py, b.py # files to change; read-only agents omit this line
  44. CONSTRAINTS: <what must not break; exact signatures; data field paths> # optional
  45. ```
  46. - **Write your acceptance check before launching, and keep it out of the
  47. prompt.** One shell command, a few seconds, exit 0 = the TASK is done; test
  48. behaviour, not text (`python3 -c "import calc; assert calc.neg(3) == -3"`
  49. beats `grep -q 'def neg'`). Run it yourself after `RESULT: OK`. Vibe never
  50. sees it, so it cannot code toward it. Cannot write one command? The TASK is
  51. too vague or too big: split it.
  52. - **Never write the code or the final text for Vibe**: not in the prompt, and
  53. not in a spec/staging file you ask it to apply "exactly". That pays for the
  54. work twice (21 % of past delegations did it). Describe the goal, the files,
  55. the constraints; Vibe writes the code. An exact signature or a
  56. one-line anchor is fine. If you already have the code, apply it yourself.
  57. The script refuses prompts with 10+ lines of code (`--allow-code` overrides).
  58. - **Keep the prompt short** (≈1,500 characters at most): you pay it at output
  59. price. Goal, files, constraints. Do not explain what Vibe can read
  60. in the files itself. (Past prompts: 3,000 characters median.)
  61. - **Cap the reading**: ≤ 4 reference files in total (inline mentions in
  62. TASK count). Say: "grep -n for the anchors, read only those regions,
  63. never re-read". Never write "read X first" in the prompt; cap `file:line`
  64. comments to "the 3–5 main formulas". Reading burns the budget (one 2026-11-10
  65. run: 485 s, 128k tokens, 0 files, all reads).
  66. - Name the exact files to modify. Say "the edit tool", not "search_replace".
  67. - **Give the regions, don't make Vibe grep them**: when you already know the
  68. lines, `sed -n 'A,Bp' file` yourself and pass `--include file:A-B` (repeatable)
  69. — the harness injects the verbatim region as a REFERENCE block and Vibe uses
  70. it directly. The launch preflight refuses (exit 2, nothing launched) a prompt
  71. that misses a `TASK:`/`MODIFY:` header (MODIFY optional for
  72. read-only agents), names > 4 files, or says "read … first".
  73. - Files Vibe must read have to be **inside the workdir** (outside paths are
  74. denied silently).
  75. - Never ask for one single write of a big new file: let it write in parts.
  76. - Accented characters or emoji in the text to replace: tell Vibe to use
  77. `python3` with `pathlib` read/write (utf-8) for that change.
  78. - Input data Vibe must use (HTML, a sample, a reference file you did not
  79. write): put it in a file inside the workdir and point to it.
  80. - Before an edit prompt, `grep -n` the anchor yourself and pass it as `--require`.
  81. ## 3. Launch
  82. ```bash
  83. ~/tools/vibe-delegate "<workdir>" "<prompt>" [max-turns=10] [agent] [timeout-secs=300] [--require "<anchor>"]
  84. ```
  85. - `agent`: none for edits; `plan` for read-only review/analysis (writes disabled).
  86. - Resume: same feature / fix-up after `PARTIAL` → `--resume-last`; unrelated
  87. task → `--no-resume`. By default the harness **auto-resumes** the last
  88. same-workdir session when the previous run was limit-stopped (last run < 24 h,
  89. resume chain < 3) — printed as `[auto-resume] …` and logged. Resuming is cheap
  90. (measured 77–88 % of re-sent input is cache hits, median 87 %, n=3 runs with
  91. cache data); a fresh session re-reads all. On a limit stop, orphaned writes are
  92. saved to `.vibe-recovery/` (not applied).
  93. - `timeout-secs` is the total budget — count `max-turns × 80 s` (a turn is
  94. ~60–90 s with a thinking model): 12 turns ≈ 600–960 s. The script clamps
  95. max-turns to `timeout/80` itself (warning printed), so the budget told to
  96. Vibe is always spendable. Out of turns → same session resumed up to 2 rounds.
  97. - `--resume <id>` continues a partial run (the id is printed on failure).
  98. - Foreground or background both work. In the foreground, set the Bash tool
  99. timeout to `(timeout-secs + 120) × 1000` ms (max 600000). In the background,
  100. **do not poll its output**: wait for the completion notification. Each poll
  101. is a full turn of your context (16 % of past background runs polled).
  102. ## 4. Read the result
  103. The **last line** is the verdict; trust it over anything Vibe narrated.
  104. | Last line | Do |
  105. |---|---|
  106. | `RESULT: OK — N file(s) changed` | Writes landed. Run your acceptance check, and review the `DIFF` block printed just above, in this same turn: the harness checks writes, not correctness. Check fails → step 5 (a wrong check: fix it, do not relaunch). Run an extra `git diff`, grep or Read only for what that block truncated or what looks wrong |
  107. | `RESULT: READ-ONLY run` | Use the `VIBE FINAL ANSWER` block |
  108. | `RESULT: PARTIAL [reason]` | Files landed despite the limit: review the DIFF, finish with the printed `--resume` — never a fresh run for the rest of this task |
  109. | `FAILED [turn_cap]` / `[timeout]` / `[budget_limit]` | Maybe partial: FIRST `git status --short` + read the diff (a write in flight at the limit can land late), then the printed `--resume <id>` — never a fresh session for the remainder. Or split |
  110. | `FAILED [usage_error]` | Bad agent, flag or model setting: fix it, never retry verbatim |
  111. | `FAILED [infra_error]` | Model API down: retry later or resume |
  112. | `FAILED [wrote_nothing]`, `[write_mismatch]`, `[syntax_error]`, others | Read the `WRITE AUDIT` block, then step 5 |
  113. Just above the verdict, `=== DELEGATION REPORT ===` is built from disk, not narration:
  114. STATUS, FILES (vs `MODIFY:`: `declared, not written` / `written, not declared`),
  115. RUN, VIBE (its DONE / NOT DONE / ASSUMED / BLOCKED / CHECK lines), RECOVER, NEXT.
  116. A `CONTRADICTION:` line (Vibe says DONE on a file it did not write) overrides
  117. `RESULT: OK`: resume the session asking for that file.
  118. `VIBE FINAL ANSWER` is Vibe's own summary; quote it, not the cut `[vibe]` lines.
  119. Vibe must not commit; if a `COMMITS CREATED` block appears, review those commits.
  120. ## 5. When a run fails
  121. - Read the diff before relaunching, so you do not redo partial work.
  122. - Your acceptance check failed on an OK run: `--resume <id>` with one sentence
  123. naming the wrong behaviour (not your command). Counts as an attempt.
  124. - Revise the prompt (smaller scope, exact file, exact anchor) and retry. At most
  125. 3 attempts per sub-task.
  126. - After 3 failures, finish the task yourself and list those files as
  127. "ghostwritten" in the report. With `--no-ghostwrite`, stop and ask instead.
  128. - Unusual flags (`[DENIED]`, `[ERROR]`, garbled tool names): see
  129. "Step 5" in `SKILL-reference.md`.
  130. ## 6. Report
  131. ```
  132. ✓ Vibe finished — <one line>
  133. Files modified:
  134. - <path> (+X / -Y)
  135. [Files ghostwritten: ...]
  136. [⚠ problem — what you did about it]
  137. Ready to commit?
  138. ```
  139. With `--verbose`, quote the script's token/cost block verbatim. With
  140. `--with-review N`, follow "Step 8" in `SKILL-reference.md`.
README.md · README · 431 lines
  1. <!-- Suggested GitHub topics: claude-code, llm-tools, mistral, gemini-cli, ai-coding, shell, developer-tools, vibe-coding -->
  2. # vibe-skill
  3. ![MIT License](https://img.shields.io/badge/license-MIT-blue.svg) ![Shell](https://img.shields.io/badge/language-Shell-green.svg) ![GitHub stars](https://img.shields.io/github/stars/pcx-wave/vibe-skill?style=social) ![Claude Code skill](https://img.shields.io/badge/-Claude%20Code%20skill-CC785C)
  4. **Claude orchestrates. Vibe does the heavy lifting. You review the diff, save tokens, costs and avoid hitting limits!**
  5. Claude only reads the script's summary (≈700–1,100 tokens per run), however many files Vibe reads internally (a median Vibe 3 run processes ≈215k tokens). Delegation still has a fixed cost on Claude's side, so it pays on tasks that would make Claude read or iterate a lot, not on small targeted edits: see the measurements below.
  6. Note that Vibe works natively with Mistral models which are capable and significantly cheaper than Claude, but Vibe can also be configured to use any other provider/model instead. Eg you can use a deepseek model with vibe tooling.
  7. Summary:
  8. 1. User types `/vibe <instruction>` in Claude Code
  9. 2. Claude decomposes the task and writes a prompt
  10. 3. `vibe-delegate` runs Mistral Vibe in a pseudo-TTY, within a turn and time budget
  11. 4. If Vibe runs out of turns, the same session is resumed automatically (it keeps its context)
  12. 5. The delegate checks every write against Vibe's session journal and prints one verdict line: `RESULT: OK` or `RESULT: FAILED [reason]`
  13. 6. Claude reviews the diff and summarizes the result
  14. ---
  15. ## Why
  16. **Cost savings** — Vibe's file reads and edits consume delegate tokens (or whatever model you configure), not Claude tokens. Most of a run's input is the conversation re-sent on every model call, and about 92 % of it is served from the provider's cache. Measured on 4 benchmark tasks with `glm-5-3` (2026-11-09; cost as billed by Vibe's own run export):
  17. | Per run | Range over 4 tasks |
  18. |---|---|
  19. | Tokens processed by Vibe | 59k – 108k (90 – 94 % of input cached) |
  20. | Delegate cost (cache-aware) | $0.028 – $0.041 |
  21. | Same tokens and cache share at Claude Sonnet 4.6 rates ($3 in, $0.30 cached, $15 out per M) | $0.055 – $0.072 (≈1.9× more) |
  22. | Wall time | 52 – 60 s |
  23. > Production runs are larger: the median Vibe 3 run (28 runs, 2026-10-29 → 2026-11-09) processed 215k tokens. Their cost was logged before the harness read the cache split, at list price with no cache discount ($0.35 median; Claude equivalent $0.88). On the benchmark runs that method overstated the delegate cost 3.1 – 3.8× and the Claude equivalent 3.5 – 4.8×. Since 2026-11-09 each run logs `cost_usd` from Vibe's export (`cost_source: vibe_export`) and a cache-aware `cost_claude_eq`. The "same tokens" comparison is only indicative: Claude doing the task itself would make a different number of calls. On a Mistral Pro subscription, usage inside the plan's limits costs no API fee. List prices checked on 2026-11-09: Mistral Medium 3.5 $1.50/$7.50, DeepSeek V4 Flash $0.14/$0.28 per M tokens.
  24. > **Delegation does cost Claude tokens, and on small tasks it costs more than doing the work.** Measured on 2026-11-10 with headless `claude -p` (Sonnet 5.5, same tool set in both arms, delegation forced in the Vibe arm, hidden acceptance tests passed in every run):
  25. >
  26. > | Session | Claude does it | Claude delegates to Vibe |
  27. > |---|---|---|
  28. > | 1 task, same change in 10 modules | $0.20 | $0.24–0.32 (4–8 delegations) |
  29. > | 3 tasks in a row, 10 modules each | $0.19 | $0.25–0.26 (3 delegations) |
  30. >
  31. > About $0.14 of every session is Claude Code's fixed context (system prompt, tools, skill list), paid either way. On top of it, a delegation costs Claude ≈$0.03 (writing the prompt, extra turns, reading the report) plus ≈5,300 tokens once per session to load this skill (it was ≈12,900 before SKILL.md was cut on 2026-11-10). These grep-able edits cost Claude only ≈$0.02 each when done directly: it finds the lines and edits them without reading whole files, whatever the file size (2.9 to 26 KB per module made no difference). **Delegating pays when doing it yourself would cost Claude more than ≈$0.03 per task: roughly when it would have to read more than ≈7k tokens (≈25 KB) of code in full, or iterate (debugging, exploration, several failed attempts).** Small samples (2 runs per cell): treat the figures as orders of magnitude. The earlier modelled claim (savings from ≈4 files touched, see [handoff-probe/ECONOMICS.md](https://github.com/pcx-wave/handoff-probe/blob/main/ECONOMICS.md)) is not supported for targeted edits.
  32. > **Pro plan users:** Mistral Vibe (CLI included) is part of Mistral's [Pro plan](https://mistral.ai/pricing), $14.99/mo excluding tax as of 2026-11-09. The pricing page shows only a small API-credit figure and "fair usage" wording for Vibe; the Vibe Code allowance actually included is much larger than that figure but is not published, so check your own account. Beyond it, usage stops or continues pay-as-you-go at API rates (off by default). Inside it, delegations cost no API fee: in practice the Vibe side is free, and the real cost of a delegation is on Claude's side (above). The free plan also includes limited Vibe CLI use.
  33. ### Delegation synthesis — as of 2026-06-08 (Vibe 2.x, historical)
  34. > **These numbers predate Vibe 3** (released 2026-10-29), which changed the CLI's exit codes, agents and session format. Right after the upgrade, 12 of 31 delegations failed (39 %) and the harness misread most of them. The 2026-11-09 audit ([`docs/harness-audit-2026-11-09.md`](docs/harness-audit-2026-11-09.md)) has the causes, the fixes and a 24-run benchmark with hidden acceptance tests: the verdict was correct on 23 of 24 runs. Fresh Vibe 3 production numbers will replace this section once enough runs exist.
  35. Snapshot over **2,450 vibe delegations**, 2026-05-12 → 2026-06-08 (28 days). Pulled from the shared run log via `delegate-report` (vibe scope).
  36. **Performance & savings**
  37. | Metric | Value |
  38. |---|---|
  39. | Delegations | 2,450 |
  40. | Tokens delegated | 155.2M |
  41. | Exit-success rate | 79% |
  42. | Avg run duration | 32s |
  43. | **Real cost (with sub)** | **$0 Mistral (inside the Pro subscription) + $0.67 DeepSeek** |
  44. | Mistral at API rate (no sub) | ~$37 cache-aware estimate ($151 at list price without cache, as logged) |
  45. | Same workload on Claude Sonnet 4.6 | ~$139 (cache-aware, 90.5% hit rate) |
  46. **By model**
  47. | Model | Runs | Exit-ok | Tokens | With sub | API ref (no sub) | vs Claude |
  48. |---|---|---|---|---|---|---|
  49. | mistral (Le Chat Pro) | 1,911 | 78% | 111.9M | $0 | ~$37 | ~$101 |
  50. | deepseek-flash | 369 | 88% | 35.5M | $0.67 | $0.67 | ~$32 |
  51. > Real cost methodology: All Mistral runs (mistral-medium-3.5 + Le Chat interface) covered by Le Chat Pro subscription — $0 marginal cost. DeepSeek $0.67 is actual spend (from logs). Hit rate of 90.5% back-calculated from that spend. Claude equivalent applies the same hit rate with Claude's cache pricing ($0.30/M hits, $3/M misses, $15/M output), assuming 97.6% input / 2.4% output split.
  52. `deepseek-flash` was the value pick (88% exit-ok at ≈$0.002/run: $0.67 over 369 runs).
  53. **Error rate** (earlier snapshot of 2026-05-30: real projects, 1,964 runs, synthetic test scaffolds excluded)
  54. | Class | Rate | What it is |
  55. |---|---|---|
  56. | clean ok | 67.1% | completed and wrote files |
  57. | `exit_error` | 18.7% | engaged (≈7 tool calls) then exited non-zero, **95% wrote nothing** |
  58. | `wrote_nothing` | 7.1% | tool calls but 0 files, exit 0 |
  59. | `warn_only` | 2.5% | non-fatal warnings, usually fine |
  60. | `sr_fail` | 2.4% | `search_replace` byte-match miss (accents, backticks) |
  61. | `near_empty` | 1.6% | <50 tokens out, nothing written |
  62. | `syntax_error` | 0.4% | wrote invalid code (caught by post-run gate) |
  63. | `timeout` | 0.3% | task too large / context saturated |
  64. At the time, the ≈26 % `exit_error` + `wrote_nothing` was attributed to Vibe engaging but landing no edit: multi-edit context drift, or a first `search_replace` anchor not found byte-for-byte. That diagnosis was not re-verified per run. The `--require` gate added then aborts the anchor-not-found case before launch.
  65. **Versus the other delegate (`opencode`)**
  66. | | vibe | opencode |
  67. |---|---|---|
  68. | Runs | 2,450 | 254 |
  69. | Tokens | 155.2M | 8.5M |
  70. | Exit-ok | 79% | 81% |
  71. | Real cost | $0.67 + Pro subscription | $0 (free tiers) |
  72. | Models | mistral-medium, deepseek-flash (paid, capable) | free deepseek / mimo / nemotron tiers |
  73. Same headline exit-rate, very different profile: `opencode` runs free tiers at zero cost, but 25 % of its runs produced nothing and 19 % timed out over the same period (vibe: 5 % and 0.2 %). Use it for cheap exploration; vibe's paid models are the choice when the edit has to land. Both write to the same log — `/vibe-report --all` compares them.
  74. ---
  75. ## Prerequisites
  76. - [Mistral Vibe](https://vibe.mistral.ai/) CLI **3.x**, installed and authenticated (`vibe --version`; tested with 3.0.3). Vibe 2.x is no longer supported: the harness reads Vibe 3's run export and session journal.
  77. - [Claude Code](https://claude.ai/code) with skills enabled
  78. - `python3` (pseudo-TTY via `pty.spawn`, stream parsing, audits) and optionally `node` for JS syntax checks
  79. - `timeout` on your `PATH` (GNU coreutils; on macOS, `brew install coreutils` installs it as `gtimeout`, so add coreutils' `gnubin` directory to `PATH`). It is only a backstop: Vibe's own `--time-limit` stops the run first
  80. - A git repository to work in
  81. ---
  82. ## Installation
  83. ```bash
  84. git clone https://github.com/pcx-wave/vibe-skill.git && cd vibe-skill && mkdir -p ~/tools ~/.claude/skills/vibe ~/.claude/skills/vibeon ~/.claude/skills/vibeoff ~/.claude/skills/vibestatus ~/.claude/skills/vibe-model-pick ~/.claude/skills/vibe-model-clear ~/.claude/skills/vibe-report && ln -sf "$(pwd)/tools/vibe-delegate" ~/tools/vibe-delegate && ln -sf "$(pwd)/tools/delegate-report" ~/tools/delegate-report && chmod +x ~/tools/vibe-delegate ~/tools/delegate-report && ln -sf "$(pwd)/SKILL.md" ~/.claude/skills/vibe/SKILL.md && ln -sf "$(pwd)/SKILL-reference.md" ~/.claude/skills/vibe/SKILL-reference.md && ln -sf "$(pwd)/VIBEON.md" ~/.claude/skills/vibeon/SKILL.md && ln -sf "$(pwd)/VIBEOFF.md" ~/.claude/skills/vibeoff/SKILL.md && ln -sf "$(pwd)/VIBESTATUS.md" ~/.claude/skills/vibestatus/SKILL.md && ln -sf "$(pwd)/VIBE-MODEL-PICK.md" ~/.claude/skills/vibe-model-pick/SKILL.md && ln -sf "$(pwd)/VIBE-MODEL-CLEAR.md" ~/.claude/skills/vibe-model-clear/SKILL.md && ln -sf "$(pwd)/VIBE-REPORT.md" ~/.claude/skills/vibe-report/SKILL.md
  85. ```
  86. ### Step-by-step
  87. ```bash
  88. # 1. Clone this repo
  89. git clone https://github.com/pcx-wave/vibe-skill.git
  90. cd vibe-skill
  91. # 2. Install the scripts (symlinks — stay in sync with git pull)
  92. mkdir -p ~/tools
  93. ln -sf "$(pwd)/tools/vibe-delegate" ~/tools/vibe-delegate
  94. ln -sf "$(pwd)/tools/delegate-report" ~/tools/delegate-report
  95. chmod +x ~/tools/vibe-delegate ~/tools/delegate-report
  96. # 3. Install the skills for Claude Code
  97. mkdir -p ~/.claude/skills/vibe ~/.claude/skills/vibeon ~/.claude/skills/vibeoff ~/.claude/skills/vibestatus \
  98. ~/.claude/skills/vibe-model-pick ~/.claude/skills/vibe-model-clear ~/.claude/skills/vibe-report
  99. ln -sf "$(pwd)/SKILL.md" ~/.claude/skills/vibe/SKILL.md
  100. ln -sf "$(pwd)/SKILL-reference.md" ~/.claude/skills/vibe/SKILL-reference.md
  101. ln -sf "$(pwd)/VIBEON.md" ~/.claude/skills/vibeon/SKILL.md
  102. ln -sf "$(pwd)/VIBEOFF.md" ~/.claude/skills/vibeoff/SKILL.md
  103. ln -sf "$(pwd)/VIBESTATUS.md" ~/.claude/skills/vibestatus/SKILL.md
  104. ln -sf "$(pwd)/VIBE-MODEL-PICK.md" ~/.claude/skills/vibe-model-pick/SKILL.md
  105. ln -sf "$(pwd)/VIBE-MODEL-CLEAR.md" ~/.claude/skills/vibe-model-clear/SKILL.md
  106. ln -sf "$(pwd)/VIBE-REPORT.md" ~/.claude/skills/vibe-report/SKILL.md
  107. # 4. (Optional) Enable auto-mode — Claude delegates all code tasks automatically
  108. # without requiring /vibe each time. Toggle with /vibeon and /vibeoff.
  109. grep -q "vibe auto-mode" ~/.claude/CLAUDE.md 2>/dev/null || cat >> ~/.claude/CLAUDE.md << 'EOF'
  110. # vibe auto-mode
  111. At the start of every user request that involves writing, editing, or fixing code:
  112. 1. Run `test -f ~/.local/share/vibe-auto.flag` (silent, no output to user).
  113. 2. If the flag exists → automatically invoke the `vibe` skill exactly as if the user had typed `/vibe <their full instruction>`. Do NOT ask first, do NOT explain — just delegate.
  114. 3. If the flag is absent → proceed normally.
  115. The flag is toggled by `/vibeon` and `/vibeoff`.
  116. EOF
  117. ```
  118. Verify with a read-only run (it must not write anything):
  119. ```bash
  120. mkdir -p /tmp/vibe-check && ~/tools/vibe-delegate /tmp/vibe-check "Say hello in one sentence." 3 plan
  121. # last line: === RESULT: READ-ONLY run (no writes expected) ===
  122. ```
  123. ### Updating
  124. Because both installs use symlinks, a `git pull` is all you need:
  125. ```bash
  126. cd ~/vibe-skill && git pull
  127. ```
  128. `~/tools/vibe-delegate` and `~/.claude/skills/vibe/SKILL.md` are automatically up to date — no re-copy needed.
  129. > **Migrating from a previous `cp`-based install?** Replace the copies with symlinks:
  130. > ```bash
  131. > cd ~/vibe-skill
  132. > ln -sf "$(pwd)/tools/vibe-delegate" ~/tools/vibe-delegate
  133. > ln -sf "$(pwd)/SKILL.md" ~/.claude/skills/vibe/SKILL.md
  134. > ```
  135. ---
  136. ## Usage
  137. In a Claude Code session:
  138. ```
  139. /vibe add a dark mode toggle to the settings page
  140. ```
  141. ```
  142. /vibe the login form is not validating the email field — fix it
  143. ```
  144. ```
  145. /vibe add pagination to the GET /posts route, 20 items per page
  146. ```
  147. Claude decomposes the task, writes the Vibe prompt, supervises execution, and reports the diff.
  148. ### Flags
  149. All optional — the no-flag path stays the default and lightest:
  150. ```
  151. /vibe --with-review N <instruction> — Claude reviews Vibe's diff and re-delegates fixes up to N times
  152. /vibe --verbose <instruction> — print per-model token/cost breakdown when done
  153. /vibe --no-ghostwrite <instruction> — halt on repeated Vibe write failures instead of finishing
  154. ```
  155. - **`--with-review N`** — after Vibe finishes, Claude takes a reviewer pass over the changes and re-delegates a fix for each fundamental issue (logic/crash/contract/scope/security only — not style), up to N iterations. Trades Claude tokens for less manual review.
  156. - **`--verbose`** — prints the token/cost block per model: I/O with the coder model (e.g. Mistral), the total, and the projected Claude-token cost it spared.
  157. - **`--no-ghostwrite`** — by default, if Vibe writes nothing after 3 retries, Claude finishes the task itself (ghostwrite fallback) so the run never strands — ghostwritten files are reported separately. `--no-ghostwrite` disables that fallback: after 3 failed attempts Claude halts and asks you (retry / abort) instead.
  158. ### Calling the script directly
  159. Claude calls this for you, but it works on its own:
  160. ```bash
  161. ~/tools/vibe-delegate <workdir> "<prompt>" [max-turns] [agent] [timeout-secs] [options]
  162. ```
  163. | Argument / option | Default | What it does |
  164. |---|---|---|
  165. | `max-turns` | `10` | Model calls per round, hard cap 12. Decompose rather than raise it |
  166. | `agent` | `auto-approve` | `plan` (also `explore`, `code-reviewer`, …) = **read-only**: write tools disabled. `default`/`lean` map to `auto-approve` (Vibe 3 removed them) |
  167. | `timeout-secs` | `300` | **Total** wall-clock budget, auto-continue rounds included. Never raised by the script |
  168. | `--continue-rounds N` / `--no-continue` | `2` | Extra rounds on the **same session** when Vibe stops on its turn limit |
  169. | `--resume <session-id>` | — | Continue an earlier session; the id is printed on every partial run |
  170. | `--require "<string>"` | — | Repeatable. Abort before launching if the string is not in the workdir (pass your edit anchor) |
  171. | env `DELEGATE_MODEL=<alias>` | flag file | Model alias for this run only |
  172. | env `DELEGATE_RUN_LOG=<path>` | `~/.local/share/delegate-runs.jsonl` | Write the run log elsewhere: use it for tests so they never pollute your real log |
  173. ### Model selection
  174. By default, Vibe uses whatever `active_model` is set in `~/.vibe/config.toml`. You can override it per-session without touching that file:
  175. ```
  176. /vibe-model-pick — interactive menu built from your config.toml models
  177. /vibe-model-pick devstral-small — switch directly by alias
  178. /vibe-model-clear — remove the override, return to config default
  179. /vibestatus — shows both auto-mode state and active model override
  180. ```
  181. `/vibe-model-pick` only lists models that already exist in `~/.vibe/config.toml`. To use a model that isn't there yet, you have to add it first — e.g. to add DeepSeek:
  182. 1. Add a `[[providers]]` block with the API endpoint and the env var holding the key (never put the key itself in the file):
  183. ```toml
  184. [[providers]]
  185. name = "deepseek"
  186. api_key_env_var = "DEEPSEEK_API_KEY"
  187. api_base = "https://api.deepseek.com"
  188. api_style = "openai"
  189. backend = "generic"
  190. ```
  191. 2. Add a `[[models]]` block pointing at that provider, with an `alias` you'll use to select it:
  192. ```toml
  193. [[models]]
  194. name = "deepseek-v4-flash"
  195. provider = "deepseek"
  196. alias = "deepseek-flash"
  197. temperature = 0.7
  198. input_price = 0.14
  199. output_price = 0.28
  200. ```
  201. 3. Export the key in your shell env: `export DEEPSEEK_API_KEY=sk-...`
  202. 4. Either set `active_model = "deepseek-flash"` at the top of `config.toml` to make it the permanent default, or run `/vibe-model-pick deepseek-flash` to use it for the current session only.
  203. `input_price`/`output_price` are only used for Vibe's own cost-tracking display — they're optional and don't affect functionality.
  204. The override is stored in `~/.local/share/vibe-model.flag` and is picked up by `vibe-delegate` on every run. It persists across sessions until you clear it.
  205. **Reasoning effort.** A model's `thinking` level in `config.toml` drives most of a run's duration: in the Vibe 3 sessions of 2026-10-29 → 2026-11-09 (mostly `glm-5-3` at `high`), 72 % of everything the model generated was hidden reasoning. You can define a second alias of the same model with a lower level and pick it with `/vibe-model-pick`. In the 2026-11-09 benchmark, `low` vs `high` on `glm-5-3` gave 12/12 vs 11/12 tasks passed and 79 s vs 93 s mean, which is within noise on small tasks. Not every level is accepted: `glm-5-3` rejects `off` with an API 400, which the script reports as `FAILED [usage_error]`.
  206. ### Vibe-auto mode
  207. For frictionless delegation, enable auto-mode once in your Claude Code session:
  208. ```
  209. /vibeon — every code request is automatically delegated to Vibe, no /vibe prefix needed
  210. /vibeoff — return to normal Claude behaviour
  211. /vibestatus — auto-mode state + active model override
  212. ```
  213. With `vibeon` active, just talk to Claude normally:
  214. ```
  215. add pagination to the /posts route
  216. fix the broken email validation
  217. refactor the auth middleware into its own module
  218. ```
  219. Claude intercepts code requests and applies a pre-filter before delegating:
  220. | Task | Action |
  221. |---|---|
  222. | 1 file, ≤10 lines, exact location known | Claude edits directly — no delegation overhead |
  223. | The code to insert is already written out | Claude edits directly — delegating would pay for it twice |
  224. | Everything else | Delegated to Vibe |
  225. Pure questions and conversations always go directly to Claude.
  226. ---
  227. ## Terminal output
  228. Sample output from a real run (benchmark task; abridged, path shortened):
  229. ```
  230. === VIBE START ===
  231. Workdir : /path/to/project
  232. Agent : auto-approve
  233. Model : glm-5-3
  234. Turns : 10
  235. Timeout : 300s total (all rounds)
  236. Prompt : Bug: an Order with discount_percent=10 ... gives total() == 3868 cents, but the...
  237. ===================
  238. [vibe] The bug is in `discount_amount`: it rounds per unit instead of once on the subtotal. Fixing it now.
  239. [tool] file: /path/to/project/shop/orders.py
  240. [vibe] Now adding the regression test:
  241. [tool] file_system.bash: cat >> tests/test_basic.py ...
  242. Tool calls: 5 | warns: 0 | sr_fails: 0
  243. Model : glm-5-3
  244. Delegate tokens (run): 69,531 | cost ~$0.1007
  245. === VIBE FINAL ANSWER (full, last model message from the session journal) ===
  246. All 3 tests pass. Changes: shop/orders.py discount_amount now applies the
  247. discount once to the subtotal ... tests/test_basic.py adds a regression test ...
  248. === VIBE DONE (exit: 0, outcome: finished, rounds: finished) ===
  249. === SYNTAX OK (2 check(s)) ===
  250. === WRITE AUDIT (journal vs disk) ===
  251. edit shop/orders.py call: ok disk: CHANGED
  252. [note] tests/test_basic.py changed on disk without a write call (bash/run_typescript, or a generated file)
  253. === UNCOMMITTED CHANGES ===
  254. shop/orders.py | 6 +-----
  255. tests/test_basic.py | 13 ++++++++++++-
  256. [log] → ~/.local/share/delegate-runs.jsonl (69531 tokens, exit 0, 95.7s)
  257. === RESULT: OK — 2 file(s) changed, verified against the session journal ===
  258. ```
  259. ### Reading the verdict
  260. The **last line** is the verdict. Read it before anything Vibe narrated:
  261. | Last line | Meaning | What to do |
  262. |---|---|---|
  263. | `RESULT: OK — N file(s) changed` | Every write call Vibe journaled landed on disk | Review `git diff`: the harness checks writes, not correctness |
  264. | `RESULT: OK (UNVERIFIED)` | Files changed but no session journal was found to check them against | Review `git diff` |
  265. | `RESULT: OK — resumed session finished with nothing left to write` | A `--resume` whose earlier run had already done the work | Read the final answer |
  266. | `RESULT: READ-ONLY run` | `plan`-type run, nothing written by design | Read the final answer |
  267. | `RESULT: FAILED [turn_cap]` | Still out of turns after the auto-continue rounds | Split the task, or run the printed `--resume <id>` command |
  268. | `RESULT: FAILED [timeout]` | Total time budget used up; Vibe stopped cleanly | Same: resume or split |
  269. | `RESULT: FAILED [infra_error]` | Model API failed again after one automatic resume | Retry later, or resume |
  270. | `RESULT: FAILED [usage_error]` | Vibe or the provider rejected the request (bad agent, flag, model setting) | Fix it; never retry verbatim |
  271. | `RESULT: FAILED [wrote_nothing]` and others | Vibe explored but wrote nothing, a write did not land, syntax error, … | Inspect the WRITE AUDIT block |
  272. The script's exit code is non-zero on every `FAILED`, so `vibe-delegate ... && next-step` stops there. Vibe must not commit: the prompt tells it to leave every change uncommitted, so `git checkout .` reverts a run. In the 520 delegated sessions on record it never committed in the project (once, in a throwaway test repo under `/tmp`). If it ever does, the script prints a `COMMITS CREATED` block.
  273. ---
  274. ## How vibe-delegate works
  275. ```
  276. Claude Code
  277. └─ /vibe <instruction>
  278. └─ SKILL.md logic
  279. └─ ~/tools/vibe-delegate <workdir> <prompt> [turns] [agent] [timeout]
  280. ├─ writes prompt to temp file (avoids shell injection with UTF-8/emoji)
  281. │ + appends the turn budget and a "quick checks only" rule
  282. ├─ runs: python3 -c 'pty.spawn(<vibe-script>)' (vibe hangs without a TTY)
  283. │ vibe -p ... --max-turns N --time-limit T --output-dir <round dir>
  284. ├─ streams JSON output through a parser → [read] / [tool] / [WARN] / [vibe] lines
  285. ├─ reads Vibe's export.json: outcome, session id, exact token usage
  286. │ └─ turn limit hit? resume the same session (up to 2 more rounds,
  287. │ within the remaining time budget)
  288. ├─ prints Vibe's final answer, from the session journal
  289. ├─ runs syntax checks on modified .py and .js files
  290. ├─ WRITE AUDIT: every edit/write call in the journal vs files changed on disk
  291. ├─ prints git diff --stat
  292. ├─ appends JSON entry to ~/.local/share/delegate-runs.jsonl
  293. └─ prints the RESULT verdict line
  294. ```
  295. > Cost figures are estimates. See [`SKILL-reference.md`](SKILL-reference.md#cost-estimate-methodology) for methodology.
  296. ---
  297. ## Examples
  298. - `examples/good-prompts.md` — prompt patterns that reliably work
  299. - `examples/anti-patterns.md` — what fails and why, with fixes
  300. ---
  301. ## Sister projects
  302. Parallel delegates using the same orchestration pattern and run log format — different models and trade-offs:
  303. - [pcx-wave/gemini-skill](https://github.com/pcx-wave/gemini-skill) — delegate to **Gemini CLI**
  304. - [pcx-wave/opencode-skill](https://github.com/pcx-wave/opencode-skill) — delegate to **OpenCode CLI**
  305. ## Reporting
  306. Every run is logged to `~/.local/share/delegate-runs.jsonl` with tokens, cost, model, and failure details. Query it with `~/tools/delegate-report [--since N] [--project NAME] [--fails]` or from Claude Code: `/vibe-report [args]`.
  307. The log is shared with sister delegates (gemini-skill, opencode-skill), so the report defaults to **vibe runs only**. Use `--all` for the cross-delegate comparison, or `--delegate NAME` to scope to another tool.
  308. ---
  309. ## Feedback
  310. See [`docs/feedback-claude-sonnet.md`](docs/feedback-claude-sonnet.md) for original feedback from Claude after hours of practice that drove the iterations on `vibe-delegate` — real bugs hit, root causes, and the fixes applied. Harness audits: [`docs/harness-audit-2026-10-01.md`](docs/harness-audit-2026-10-01.md) (Vibe 2.x) and [`docs/harness-audit-2026-11-09.md`](docs/harness-audit-2026-11-09.md) (Vibe 3).
  311. ---
  312. ## License
  313. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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