Skip to content
Back to search

claude-vibe-squad

SkillWorks with Claude CodeGitHub

Vibe Squad multi-model agent harness with vendored runtime MCP plugins.

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/mtarcure--claude-vibe-squad/badge.svg)](/listings/mtarcure--claude-vibe-squad)

HTML

<a href="/listings/mtarcure--claude-vibe-squad"><img src="/api/listings/mtarcure--claude-vibe-squad/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.

macOS, for now. You need `tmux`, `fswatch`, `jq`, `curl`, Python 3.13, `uv`, and authenticated native CLIs for Claude, Codex, Gemini (`agy`), and Grok.

Memory lives outside the public repository. Create a private vault once:

mkdir -p "$HOME/Obsidian-Chrono"
printf '%s\n' '{"vault_id":"my-private-vault","schema_version":1}' \
  > "$HOME/Obsidian-Chrono/.chrono-vault"
export CHRONO_VAULT_ROOT="$HOME/Obsidian-Chrono"

Then clone and launch:

git clone https://github.com/mtarcure/claude-vibe-squad.git
cd claude-vibe-squad
uv sync                                # create the pinned Python 3.13 environment
bash docs/install/install-pre-commit-hook.sh  # install the reviewed local guards
bin/squad doctor
bin/squad up

The installer copies the private-memory leak guard and a reviewed validator bundle into Git's private hooks directory. It does not point `core.hooksPath` at tracked files, so checking out another branch cannot replace the code Git runs on your next commit. The installed hook also checks release versions, specialists, and capability homes, with additional checks triggered by the staged paths; CI runs repository-wide validation too. If an older clone has `core.hooksPath=.githooks`, migrate it by running the installer. The installer clears the local value and refuses success if a global or system value still overrides the private hooks directory, reporting the origin that must be removed. See the [install guide](docs/install/README.md#5-install-the-local-leak-guard).

That is the whole required path. There is **no background daemon to install first**. `bin/squad up` runs on a fresh clone, notices once that the optional launchd daemon is absent, and continues.

**Optional: the launchd routines.** `bash bin/install-routines.sh --daemon-only` installs a background daemon; `bash bin/install-routines.sh` adds the optional routine agents too. The daemon buys exactly two things: the live `● daemon` segment in the tmux status bar, and the documented `POST /mcp/<server>/<tool>` HTTP bridge. Without it the status bar reads `● daemon offline` and that `curl` path is unavailable; the MCP servers themselves are unaffected. Dispatch, worktree isolation, review, memory, and the coordinator are untouched, because none of them talk to it. See [the daemon guide](docs/install/daemon.md).

**Before you install them, know what they run.** Each agent executes code from your checkout on every launch, with no immutable snapshot — so checking out a branch you have not reviewed (a fork's pull request above all) in a clone where they are loaded runs that branch's code as your user, within about two minutes for the fastest agent. The daemon and nightly agents source your shell secrets, and `com.vibesquad.chrome` owns your authenticated browser, so that execution carries real authority. The installer manages four of these agents (`com.vibesquad.daemon`, plus the optional `com.claudevibesquad.nightly`, `com.vibesquad.dream`, and `com.chrono.squad-monitor`); the fifth, `com.vibesquad.chrome`, is installed by no repository command, and `bin/install-routines.sh --status` only reports it as `operator-managed`. Unload the agents before checking out an unreviewed branch and reload afterwards; [the daemon guide](docs/install/daemon.md#security-every-listed-agent-runs-code-from-your-checkout) lists every label and its exact `launchctl` commands. A fix separating the installed code root from the live data root is planned.

`bin/squad up` opens a tmux control room with Chrono and a status window. Each specialist starts as a fresh native CLI process for its task; there are no permanent per-model panes. Detach with `Ctrl-b d`, return with `bin/squad attach`.

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.

.claude-plugin/marketplace.json · Manifest · 38 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "claude-vibe-squad",
  4. "description": "Vibe Squad multi-model agent harness with vendored runtime MCP plugins.",
  5. "owner": {
  6. "name": "mtarcure"
  7. },
  8. "plugins": [
  9. {
  10. "name": "chrono-vault",
  11. "description": "KG state machine + Obsidian REST + auto-capture. Includes namespace aliases for chrono-kg / chrono-obsidian / chrono-catalog so legacy archive role plugins keep working.",
  12. "category": "memory",
  13. "source": "./plugins/chrono-vault",
  14. "homepage": "https://github.com/mtarcure/claude-vibe-squad"
  15. },
  16. {
  17. "name": "chrono-research-arsenal",
  18. "description": "Academic research arsenal: arxiv_search with an OpenAlex fallback.",
  19. "category": "research",
  20. "source": "./plugins/chrono-research-arsenal",
  21. "homepage": "https://github.com/mtarcure/claude-vibe-squad"
  22. },
  23. {
  24. "name": "chrono-media-studio",
  25. "description": "Image/video/audio generation. Wired today: OpenAI image+video, Gemini audio. Sibling MCPs declared: Higgsfield (HTTP), ElevenLabs (uvx). Owner roles: content media specialists (image-designer, video-director, music-composer, sound-designer, voice-narrator, voice-agent-builder).",
  26. "category": "content",
  27. "source": "./plugins/chrono-media-studio",
  28. "homepage": "https://github.com/mtarcure/claude-vibe-squad"
  29. },
  30. {
  31. "name": "chrono-recon",
  32. "description": "OSINT recon tools for Vibe Squad specialists (dns, whois, crt.sh, wayback, github leaked-secrets). Owner roles: scout, security-analyst, exploit-developer.",
  33. "category": "recon",
  34. "source": "./plugins/chrono-recon",
  35. "homepage": "https://github.com/mtarcure/claude-vibe-squad"
  36. }
  37. ]
  38. }
README.md · README · 271 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # Vibe Squad
  3. **One coordinator. Four model families. Seventy-one specialists, all written in Markdown you can read and edit.**
  4. ![models](https://img.shields.io/badge/models-Codex%20%C2%B7%20Claude%20%C2%B7%20Gemini%20%C2%B7%20Grok-informational)
  5. ![license](https://img.shields.io/badge/license-MIT-blue)
  6. ![orchestration](https://img.shields.io/badge/orchestration-native%20CLIs%20%C2%B7%20isolated%20worktrees-success)
  7. ![version](https://img.shields.io/badge/version-v2.0.0-blue)
  8. <br>
  9. ![One operator talks to Chrono, which routes a Markdown task to one of 71 model-bound specialists in its own git worktree; risky work receives cross-family review, and a Markdown result returns to Chrono.](assets/hero/vibe-squad-hero.svg)
  10. *One task, one specialist, one fresh CLI in its own git worktree; cross-family review when risky.*
  11. </div>
  12. ---
  13. Vibe Squad is for people who like **vibe coding** but want more structure than one enormous chat. You talk to **Chrono**, the coordinator. Chrono turns your goal into a plan, picks the specialist and model that fit each part, runs workers in isolated git worktrees, and calls for independent review when the risk warrants it.
  14. You can ask it to:
  15. - "Build a polished landing page, test it in the browser, and show me the result."
  16. - "Research this product idea, compare the competitors, and turn it into a cited brief."
  17. - "Audit this authorized smart-contract target, keep every test in scope, and package only reproduced findings."
  18. **What's underneath**
  19. - **The right model for each job** — every specialist is tied to the model that suits its work, not
  20. to whichever one you happen to be chatting with.
  21. - **Each task runs in its own worktree** — a copy of the repo, with a written list of the files it
  22. may change, and nothing merges until its checks pass. That list is enforced when changes are
  23. integrated, not while the worker runs: a worker executes on your host with your permissions, so
  24. treat this as an autonomy tool, not a containment boundary. See the note under Quickstart.
  25. - **A different model checks work that triggers review** — the reviewer comes from another family.
  26. - **It remembers** — what a run learns is written down and read back before the next one, so a
  27. lesson paid for once isn't paid for twice.
  28. The product is the instruction layer, and it is Markdown all the way down. Modes, specialist briefs, capability cards, and skills are files you can open and change. Code handles only what must not be guessed: launching, worktree isolation, identity checks, atomic publication, admission control, and Git-integration boundaries. Judgment stays with the models.
  29. ## Quickstart
  30. macOS, for now. You need `tmux`, `fswatch`, `jq`, `curl`, Python 3.13, `uv`, and authenticated native CLIs for Claude, Codex, Gemini (`agy`), and Grok.
  31. Memory lives outside the public repository. Create a private vault once:
  32. ```bash
  33. mkdir -p "$HOME/Obsidian-Chrono"
  34. printf '%s\n' '{"vault_id":"my-private-vault","schema_version":1}' \
  35. > "$HOME/Obsidian-Chrono/.chrono-vault"
  36. export CHRONO_VAULT_ROOT="$HOME/Obsidian-Chrono"
  37. ```
  38. Then clone and launch:
  39. ```bash
  40. git clone https://github.com/mtarcure/claude-vibe-squad.git
  41. cd claude-vibe-squad
  42. uv sync # create the pinned Python 3.13 environment
  43. bash docs/install/install-pre-commit-hook.sh # install the reviewed local guards
  44. bin/squad doctor
  45. bin/squad up
  46. ```
  47. The installer copies the private-memory leak guard and a reviewed validator bundle into Git's
  48. private hooks directory. It does not point `core.hooksPath` at tracked files, so checking out another
  49. branch cannot replace the code Git runs on your next commit. The installed hook also checks release
  50. versions, specialists, and capability homes, with additional checks triggered by the staged paths;
  51. CI runs repository-wide validation too. If an older clone has `core.hooksPath=.githooks`, migrate it
  52. by running the installer. The installer clears the local value and refuses success if a global or
  53. system value still overrides the private hooks directory, reporting the origin that must be
  54. removed. See the [install guide](docs/install/README.md#5-install-the-local-leak-guard).
  55. That is the whole required path. There is **no background daemon to install first**. `bin/squad up` runs on a fresh clone, notices once that the optional launchd daemon is absent, and continues.
  56. **Optional: the launchd routines.** `bash bin/install-routines.sh --daemon-only` installs a background daemon; `bash bin/install-routines.sh` adds the optional routine agents too. The daemon buys exactly two things: the live `● daemon` segment in the tmux status bar, and the documented `POST /mcp/<server>/<tool>` HTTP bridge. Without it the status bar reads `● daemon offline` and that `curl` path is unavailable; the MCP servers themselves are unaffected. Dispatch, worktree isolation, review, memory, and the coordinator are untouched, because none of them talk to it. See [the daemon guide](docs/install/daemon.md).
  57. **Before you install them, know what they run.** Each agent executes code from your
  58. checkout on every launch, with no immutable snapshot — so checking out a branch you
  59. have not reviewed (a fork's pull request above all) in a clone where they are loaded
  60. runs that branch's code as your user, within about two minutes for the fastest agent.
  61. The daemon and nightly agents source your shell secrets, and `com.vibesquad.chrome`
  62. owns your authenticated browser, so that execution carries real authority. The
  63. installer manages four of these agents (`com.vibesquad.daemon`, plus the optional
  64. `com.claudevibesquad.nightly`, `com.vibesquad.dream`, and `com.chrono.squad-monitor`);
  65. the fifth, `com.vibesquad.chrome`, is installed by no repository command, and
  66. `bin/install-routines.sh --status` only reports it as `operator-managed`. Unload the agents before checking out an
  67. unreviewed branch and reload afterwards; [the daemon guide](docs/install/daemon.md#security-every-listed-agent-runs-code-from-your-checkout)
  68. lists every label and its exact `launchctl` commands. A fix separating the installed
  69. code root from the live data root is planned.
  70. `bin/squad up` opens a tmux control room with Chrono and a status window. Each specialist starts as a fresh native CLI process for its task; there are no permanent per-model panes. Detach with `Ctrl-b d`, return with `bin/squad attach`.
  71. `--safe` is not a permission mode. It suppresses the first-run autonomy warning and skips the pre-flight `doctor` check, and that is all. The coordinator and board-spawned workers run with the same permissions either way, because worker launch flags are a fixed controller ABI the supervisor re-derives and refuses to launch on mismatch. Nothing in either path sandboxes later agent actions. A task's `read_scope` and `write_scope` are declarations: `write_scope` is enforced when committed changes are integrated, not while the worker acts, and `read_scope` is not an action-time read barrier. Review the isolated worktree, verification contract, and held-category policy before enabling broader autonomy.
  72. See [Getting started](docs/getting-started.md) for provider authentication, vault setup, and your first request.
  73. ## Three engagement states, one conversation
  74. You ask in plain language. Chrono always names the mode and asks for your approval before starting.
  75. **`modeless` is the default for ordinary work**, such as routine changes and simple research.
  76. It needs no mode setup. It follows the stricter of Project and Bounty's permissions and limits,
  77. including a shorter time limit of 90 minutes per task. Choose Project or Bounty deliberately
  78. when you need one of their workflows:
  79. - **[Project](shared/modes/project.md)** covers software, research, content and media, operations, and learning. Its lifecycle is scope → plan → build → verify → review when required → deliver → remember.
  80. - **[Bounty](shared/modes/bounty.md)** covers authorized offensive-security work: confirm what is in scope before testing, then reproduce the impact and run controls to rule out false positives before calling it a finding. Chrono and the specialists must follow these rules, but the rules do not automatically block a task from starting. At the end, a verifier requires the run record to declare a scope check, an exact list of allowed targets covering every declared target, and reproduction by a different model family with an evidence file for each finding. It checks those declarations and the files' hashes, not whether the evidence proves the findings.
  81. A task file with no `mode:` defaults to `modeless` (empty or unknown values are rejected), while `scripts/send-task.sh` requires an explicit `--mode modeless`, `--mode project`, or `--mode bounty`.
  82. Project and Bounty are the two defined modes; `modeless` needs no mode file. Triage means deciding how to assign work, not choosing another mode; parallel work means running several independently assigned tasks, with no special "panel" or "swarm" system.
  83. ## Dispatch, settlement, and the board
  84. ```mermaid
  85. flowchart LR
  86. OP([You]) --> CO[Chrono]
  87. CO --> PLAN[Markdown task<br/>and optional capability]
  88. PLAN --> RUN[Fresh native CLI<br/>in isolated worktree]
  89. RUN --> CHECK[Tests, plus cross-family<br/>review when triggered]
  90. CHECK --> RESULT[Atomic result<br/>back to Chrono]
  91. RESULT --> OP
  92. ```
  93. **A task is a Markdown file, and that file is the contract.** Which specialist, which model, what it
  94. may read, what it may change, and what counts as done:
  95. ```yaml
  96. ---
  97. specialist: security-analyst # the role, chosen for the job
  98. to_model: gpt-codex # the model bound to that role
  99. mode: project
  100. write_scope: [src/auth] # the only files it may change
  101. read_scope: [src, docs/auth.md]
  102. reviews: none # or the task id this reviews
  103. review_triggers: [blast_radius] # what forces a second opinion
  104. ---
  105. Audit the session-handling path and report anything exploitable.
  106. Do not change behaviour; findings only.
  107. ```
  108. Everything the worker may do is on that page. Workers never talk to each other or to you — each
  109. writes one result and Chrono integrates it.
  110. Four things hold that together:
  111. 1. **Chrono is the only operator-facing voice.** Specialists report to Chrono, not to you.
  112. 2. **Routing is by fit, not preference.** Each specialist is bound to the model that suits its work,
  113. with a different-family backup and review route, all in one file:
  114. [`shared/specialist-runtime-map.tsv`](shared/specialist-runtime-map.tsv).
  115. 3. **Workers are isolated and results settle atomically.** Each mutating attempt gets its own git
  116. worktree and a narrow write scope; artifacts are written before their completion envelope, so
  117. partially published work never reads as done.
  118. 4. **Dangerous actions are refused before a worker starts, not asked about later.** Deleting files,
  119. changing credentials, publishing — withheld at launch, and deletion refused again at merge unless
  120. an exact pre-approved file list allows it.
  121. **Review is part of settling, not a separate ceremony.** Every specialist has a route to a reviewer
  122. from another model family. Review is mandatory only when the packet carries one of the four
  123. [change-level triggers](shared/protocol.md#mandatory-review-behavior); otherwise Chrono verifies
  124. and closes the task. The reviewer's job is to find a concrete reason the work is wrong; `REJECT`
  125. is a useful result, not a failed run. The machine checks reviewer independence and evidence
  126. identity — it does not vote on whether the work is any good. Which of those rules are actually under
  127. test is written down in a tracked census that names the untested ones too.
  128. **The board carries work across conversations.** Every run leaves its task file and receipt behind,
  129. so a failure is diagnosed from those rather than from a chat log, and something raised but not
  130. finished is picked up next session instead of dying with the thread.
  131. ![A live Vibe Squad board: Chrono working in the left pane while seven specialists run in parallel on the right](assets/demo/phase3-swarm.gif)
  132. *A live board: seven specialists running in parallel across Claude and Codex.*
  133. ## Memory that compounds
  134. Durable memory is private Markdown outside the repository. Chrono records what a run learned and
  135. recalls it before the next one, so a lesson paid for once is not paid for twice.
  136. Each note carries where it came from and how sensitive it is. There is no automatic contradiction
  137. flag: recall does not mark a note "contested," and a newer note does not silently win. Conflicts are
  138. resolved by explicit supersession links and human curation, and recall ranks on recorded usage
  139. feedback and provenance. Obsidian is an optional way to read the same files by hand.
  140. There is no graph database here, and no fashionable label applied for its own sake.
  141. ## Specialists, skills, and tools
  142. **71 specialist briefs** live under `departments/` and `shared/specialists/`, each validated on every
  143. push by CI. The installed local pre-commit hook also validates specialists and capability homes
  144. and blocks private-memory artifacts before they enter history. A brief is prose: what the role is
  145. for, how it should think, what it must refuse. Adding one means writing Markdown, not registering a class.
  146. ```text
  147. 71 specialists claude ██████████████████████████████ 30
  148. codex ██████████████████████ 22
  149. gemini ██████████████████ 18
  150. grok █ 1
  151. ```
  152. The `gemini` row is a lane name, not a binary. That lane runs on the **agy** CLI, which fronts Gemini and Google's other products; the standalone `gemini` CLI is retired.
  153. Around them sit **94 skills** (methodology documents that Chrono or a specialist reads when the
  154. work calls for it), **four catalogued plugins**, and **8 MCP servers** covering memory, research,
  155. recon, and media tooling. The skill count is unique skill names: 91 under `.claude/skills/` (86
  156. for specialists, 5 for Chrono) plus 3 bundled with the `chrono-vault` plugin. The per-runtime
  157. mirror copies under `.agents/skills/` and `model-lanes/gemini/.agents/skills/` are collapsed.
  158. The guarded security MCPs (`guarded-semgrep`, `guarded-slither`, `guarded-solodit`) were retired
  159. on 2026-10-27. Security audits run the Semgrep and Slither CLIs directly.
  160. The public `plugins/` tree has five directories: the four catalogued plugins, and
  161. `security-mcp-stack`, which has no marketplace manifest and now only records that retirement.
  162. `chrono-dedup` exists in the private source and is not distributed here because the
  163. [export path policy](tools/export/policy/path-policy.json) withholds its tree. Like the four
  164. catalogued plugins, it declares AGPL-3.0-or-later separately from the root MIT licence; see
  165. [the plugin licence register](THIRD_PARTY.md#plugins). The licence alone is not the withholding rule.
  166. This checkout supplies no download or installation source for it. Ask the maintainer for a
  167. separately distributed source release, or build a replacement prior-art service against your own
  168. corpus; neither is installed by cloning this repository.
  169. References to `chrono-dedup` in workflow cards, specialist methods, tool recommendations, and
  170. expected host-tool descriptions describe an optional private setup. Those steps require a
  171. separately provisioned service; use manual searches of public disclosures and your own prior
  172. findings when it is absent. The shipped capability source records it as `needs-operator-install`,
  173. and the generated adapters do not advertise it as available. Even a private checkout must
  174. explicitly configure and verify the service before changing that declaration locally.
  175. All four families run through their providers' **native CLIs** — never swapped for an MCP relay or a
  176. direct API fallback. Three authenticate on subscription or managed-login paths; the Grok board lane is
  177. the exception and requires an xAI API key (`model-lanes/lane-capabilities.tsv` declares
  178. `xai-api-key-only`). Utility services are separate.
  179. One rule governs all of it: **a configured tool is not a working tool until a live probe says so.**
  180. Declared, delivered, and actual are three different things, and only actual counts. That probe is
  181. [`bin/canary.sh`](bin/canary.sh), which reports **PASS**, **FAIL**, or **NOT MEASURED** — it never
  182. lets "did not run" pass for "works".
  183. The rule earns its keep. A model id can be accepted by the CLI, self-report correctly, and still be
  184. served by a different model; only the usage record shows it. Findings like that are recorded as
  185. dated probes, each with the literal command and its literal result.
  186. ## Design principles
  187. - Change behaviour by editing Markdown, not by writing code.
  188. - Ask in ordinary language. You never pick a model by hand.
  189. - Use code only for what must not be guessed: identity, ordering, hashes, what a
  190. worker may change, and what may be deleted.
  191. - Prefer deleting an unused framework to wiring it in because it exists.
  192. - Keep private memory, credentials, and target data out of the public repository.
  193. ## Status
  194. **v2.0.0** is the current release; **v1.1.1** was the first public one. It runs as the maintainer's
  195. daily driver rather than as a demo. [CHANGELOG.md](CHANGELOG.md) records what each release changed,
  196. including the parts that are still rough.
  197. Start with the [documentation index](docs/README.md), the
  198. [architecture](docs/architecture.md), or [how to add a specialist](docs/adding-a-specialist.md).
  199. ## Contributing and license
  200. Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md). Keep generated state, mailbox traffic, credentials, private memory, and authorized-target evidence out of commits.
  201. Except where a file or an accompanying third-party notice says otherwise, the original contents of this repository are Copyright (c) 2026 Matthew A. and licensed under the **MIT License**. See [LICENSE](LICENSE) and [THIRD_PARTY.md](THIRD_PARTY.md).

Ratings and comments

Sign in to rate this skill.

Sign in

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