vibecoders-mcp

# Vibecoders MCP **One MCP that turns Claude Code into your whole dev stack.** It swallows every other MCP server, delegates to Codex & Gemini on *your* CLI subscriptions (not a metered API), remembers your projects in a searchable knowledge graph, and carries your setup across sessions — **secret-free by design, and optional all the way down.** > Built to optimize vibecoding with **Claude Code as the driver**. Claude stays > in charge; Vibecoders gives it superpowers: reach any other MCP server, hand > work to Codex/Gemini on the plans you already pay for, remember decisions > across sessions, orient in a repo instantly, design interfaces that escape its own generic defaults, and study any reference on the > web. Nothing is required to start — no keys, no servers, no CLIs. Add only what > you want. **Every key is always yours; Vibecoders ships and bills none.** ## Quick start (~1 minute, zero config) **1. Clone, install, build:** ```bash git clone https://github.com/<you>/vibecoders-mcp cd vibecoders-mcp npm install && npm run build ``` **2. Put the `vibecoders` CLI on your PATH** (used throughout this README): ```bash npm link ``` > Prefer not to link? Skip this step and run every `vibecoders <command>` below > as `node bin/vibecoders.mjs <command>` from the repo instead. **3. Register it with Claude Code** (point at the absolute path): ```bash claude mcp add vibecoders -s user -- node "$(pwd)/dist/index.js" ``` `-s user` registers it once for **every** project (drop it to scope to just this directory). That's it — it runs with **no keys and no setup**. Ask Claude to run `doctor` and it will show you exactly what's available and what's optional. The MCP `doctor` and the `vibecoders doctor` CLI share one renderer, so they report the same sections; pass `{json:true}` (MCP) or `--json` (CLI) for structured, scriptable output. > Config changes and rebuilds take effect on the next Claude Code restart. ## The tool surface at a glance Two **separate** enablement systems gate these (the same split `doctor` shows in its legend): **Capabilities** turn on when you configure a *provider* (a CLI or your own key); **Tool groups** turn on via a `features.*` toggle. Everything else is always on. | Group | Tools | Enablement | | --- | --- | --- | | **Gateway** (swallow other MCPs) | `search_tools` · `load_tool` · `call_tool` | always on | | **Delegate** (other agents, your plan) | `list_providers` · `delegate` (+ `background:true`) | always on (uses CLI auth) | | **Background tasks** (async delegation) | `tasks_list` · `tasks_steer` · `tasks_interrupt` | tool group `features.tasks` (on) | | **Memory graph (RAG)** | `memory_store` · `memory_recall` · `memory_walk` · `memory_forget` | tool group `features.memory` (on); semantic recall is opt-in (your key) | | **Orient** | `project_context` | tool group `features.projectContext` (on) | | **Research — web** | `web_search` | **capability** — configure a provider (gemini CLI, or Gemini/Brave/Tavily key) | | **Research — reference** | `reference_inspect` · `reference_excerpt` · `reference_read_source` | tool group `features.reference` (on) | | **Generate** | `generate_image` | **capability** — configure a provider (codex CLI, or OpenAI/Gemini key) | | **Design RAG** (escape generic defaults) | `design_core` · `design_layer` | tool group `features.rag` (on) | | **Handoffs** (per lane) | `write_handoff` · `recall_handoff` | always on | | **Device** (opt-in · macOS) | `device_search` · `chat_history_search` | tool group `features.device` (off) | | **Notes vault** (opt-in) | `vault_search` · `vault_read` | tool group `features.vault` (off) | | **Status** | `doctor` | always on | ## What you get ### 1. Swallow every other MCP server Instead of every downstream tool flooding context, Claude sees a few meta-tools and pulls the rest in on demand: `search_tools` → `load_tool` → `call_tool`. Mount Playwright, GitHub, Vercel, Supabase, … in `servers.json`; they load **lazily**, so hundreds of tools cost almost no context. **Mount a server.** Copy the template and list the servers you want. `servers.json` is **git-ignored**; put it in the repo root or `~/.vibecoders/`: ```bash cp servers.example.json servers.json # then edit it ``` The server resolves it in this order: **`$VIBECODERS_SERVERS`** → **`~/.vibecoders/servers.json`** → **`./servers.json`** (repo root). See [`servers.example.json`](./servers.example.json) for annotated examples; a minimal entry is just a command: ```json { "servers": { "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@0.0.76"] } } } ``` Reference any secret a server needs by **env-var name** in an `"env": [...]` array — never paste values. `lazy: true` (the default) keeps a server cold until first use; set `lazy: false` on the one or two you reach for every session. **Worked example** — find a tool, load it, call it (Claude does this for you): ``` search_tools { "query": "screenshot" } → playwright.browser_take_screenshot — Take a screenshot of the current page load_tool { "name": "playwright.browser_take_screenshot" } # returns its input schema call_tool { "name": "playwright.browser_take_screenshot", "arguments": { "filename": "home.png" } } ``` ### 2. Delegate to Codex & Gemini — on your subscription, not the API Claude can offload work to another coding agent through its **CLI**, so billing flows through the plan you already pay for: - **CLI, not API, on purpose.** `delegate` runs `codex exec`, `gemini -p`, or `claude -p`. Usage bills through your **Codex/ChatGPT, Gemini, or Claude plan**. - **Read-only by default.** A delegated agent only edits files with `mode: "write"`. - **No keys to leak.** The CLIs hold their own auth. - **Run it in the background.** Pass `background: true` and `delegate` returns a task id immediately instead of blocking — manage it with `tasks_list` / `tasks_steer` / `tasks_interrupt`, so a long codex/gemini run never stalls Claude. **Worked example** — hand a write task to Codex (defaults to read-only; opt into edits): ``` delegate { "provider": "codex", "prompt": "Add a --json flag to the doctor command and update its test", "mode": "write" } ``` ### 3. A memory graph with RAG recall A per-user knowledge graph that survives every session: ``` memory_store remember a decision/fact/gotcha; link it to others (graph edges) memory_recall find memories by meaning (RAG) — global + this project by default memory_walk traverse the links around a node (the context of a decision) memory_forget tombstone a memory ``` - **Works with zero keys.** Recall is BM25 lexical out of the box — no provider, no setup, fully offline. - **Semantic when you want it.** Turn on embeddings (`memory.embeddings: true`) and recall blends in cosine similarity — using **your own** OpenAI/Gemini key. Any failure falls back to lexical, so it never breaks. - **Scoped.** Memories are `project` (this repo+branch) or `global`, so projects don't bleed together. Stored in a plain append-only file — no database engine, trivially portable. **Worked example** — store a decision and link it to the constraint behind it: ``` memory_store { "kind": "decision", "text": "Use BM25 for recall; embeddings stay opt-in", "edges": [{ "rel": "because", "text": "must work offline with zero keys" }] } ``` Later, `memory_recall { "query": "why BM25" }` finds it, and `memory_walk` traverses from that node to the linked constraint. ### 4. Orient instantly — `project_context` One call returns this repo's branch, recent commits, the saved handoff, and the project's most recent memories. Reads git state straight from `.git` (no subprocess), so it's fast even on slow/iCloud-backed dirs. ### 5. Study any reference — `reference_inspect` / `reference_excerpt` / `reference_read_source` Point at a URL to learn how it's built: title, description, **detected frameworks/libraries**, headings, and links — or pull a focused text excerpt. `reference_read_source` is the full-source escape hatch and requires a written `reason`. All three are **SSRF-guarded** (refuse localhost/private/metadata addresses, re-check every redirect hop's resolved IP), size-capped, and timeout-bounded. For learning from a reference, not cloning it. ### 6. Carry work across sessions (lanes) `write_handoff` / `recall_handoff` save and restore where you left off, **isolated per working lane** (cwd + git branch), so two sessions in different repos or branches never clobber each other's notes. ### 7. Opt-in: device search, chat history & a notes vault Off by default — these read personal data, so you enable them explicitly: - **`device_search`** — Spotlight (`mdfind`) file search across your Mac (macOS only). - **`chat_history_search`** — search your *own* past Claude Code sessions (`~/.claude/projects` transcripts) by meaning. - **`vault_search` / `vault_read`** — the **notes vault**: index a local directory of notes with the same BM25 ranker as the memory graph; `vault_read` is path-guarded to that dir. (Distinct from the **secret vault** below, which stores API keys in the OS Keychain.) ```bash vibecoders config set features.device true # device_search + chat_history_search (macOS) vibecoders config set features.vault true vibecoders config set vault.dir ~/notes # your notes directory ``` ### 8. Design like the best: escape Claude's generic defaults `design_core` and `design_layer`: a brand-agnostic design-intelligence layer that lifts Claude's UI, website, and component output above the generic, templated, unmistakably-AI look it reaches for by default. **On by default** (`features.rag`). **How it works.** It is delivered on demand, so it costs almost nothing until a design task needs it: - **`design_core`** loads the lean core: the affirmative standard plus two pre-build gates the model has to pass before it writes any code. The first gate forces every decision to be *derived from the brand* (not an adjective, not a category template). The second, the *aliveness* gate, forces motion and layout to perform the concept instead of decorating it. - **`design_layer`** pulls one deeper layer only when the build needs it: `donts` (the catalogue of AI telltale signs to self-check against before shipping), `craft` (the mechanism-level craft of seamless, bold motion and the pro-look visual finish), `capabilities` (the situational palette: 2.5D photo, shaders, particles, video, 3D), `typography`, `cards` (worked technique exemplars), `image_gen`, and `standard` (the elite bar made legible). - **Imagery composes for free.** The `image_gen` layer points the model straight at `generate_image`, so generated, on-concept imagery is part of the same flow. Always-on cost is one line in the server instructions. The core loads only when a design task starts, and a layer only when it is pulled, so nothing bloats. **How it was built.** The intelligence is distilled from a curated corpus of about 150 elite, award-tier sites into a brand-agnostic rulebook: what good actually is, the telltale signs to never ship, and the craft that makes motion seamless. It is hardened with a **blind test**: a fresh agent, sandboxed to the RAG and given nothing but a vague brand line, has to *derive* the whole design with no access to any answer, then it is judged against a base-Claude control on the identical prompt. **The effect.** Two things change, and neither is subtle. 1. **The AI telltale signs come off.** The reflexive fade-in on every element, the hand-drawn SVG "map", the kicker dot stacked over a heading, the one italicized word, the centered-column template, the punctuation tics. The patterns that make output read as AI-generated at a glance are named and cut. 2. **Creativity moves from the copy into the design.** Base Claude expresses a brand idea in *words*, a headline that puns on the name. The RAG makes the brand idea the *architecture*: structure, motion, type, and imagery all performing the concept. **Concrete before and after.** Given only `make a website for a cafe called the daily press`: - **Base Claude** builds a competent but generic cafe template: fade-in sections, a fake hand-drawn SVG map, product cards, and the press/paper idea stuck in one line of copy. - **The same four-word prompt, through the design RAG,** derives an entire *newspaper*. The site **is** the paper: every section is a printed page, with halftone newsprint photography, editorial columns, a running wire ticker, and motion that performs the concept. Same model, same prompt. The only thing different is the design intelligence in front of it. **Worked example** (load the core, pull a layer, render imagery): ``` design_core # the standard + the two gates; do this first design_layer { "layer": "donts" } # the AI tells to self-check against before shipping design_layer { "layer": "craft" } # seamless-motion + pro-look craft, pulled only when needed generate_image { "prompt": "...", "out_path": "/abs/out/hero.png" } ``` ## Customize everything All non-secret behavior lives in `~/.vibecoders/config.json` (git-ignored). Copy [`config.example.json`](./config.example.json) or use the CLI: ```bash vibecoders config path # where the file lives vibecoders config get # print the whole config vibecoders config set memory.embeddings true # turn on semantic recall (your key) vibecoders config set memory.defaultScope global vibecoders config set reference.allowPrivateHosts false ``` **Feature toggles** (`features.*`) turn whole tool groups on/off. `memory`, `reference`, `projectContext` and `tasks` are **on**; `device` and `vault` are **off** (they read personal data — opt in). **Resolution order:** built-in defaults → `config.json` → environment variables. ## Reference setup (how the author runs it) Vibecoders is built to be driven from **[Claude Code](https://claude.com/claude-code)**, and the reference environment it's designed against is the **[Warp](https://www.warp.dev)** terminal. For a concrete starting point, here's the author's own configuration — every entry is a *tool/provider choice*, **never a secret** (keys, when needed at all, live in the Keychain or `.env`, never in the repo): | Capability | What the author uses | Wire it up | |---|---|---| | `delegate` | `codex` · `gemini` · `claude` CLIs on their **subscriptions** (not metered API) | install the CLI, sign in once via the CLI's own login — nothing for Vibecoders to store | | `image_gen` | **Codex CLI** (ChatGPT / Codex plan) | `vibecoders config set capabilities.image_gen.provider codex-cli` | | `web_search` | **Gemini CLI** (GoogleSearch, OAuth plan) | `vibecoders config set capabilities.web_search.provider gemini-cli` | | memory · reference · project_context · tasks | on by default | — | | device search · notes vault | opt-in (off) | `vibecoders config set features.device true` · `… features.vault true` | The CLI-on-subscription path above needs **zero secrets** — each CLI authenticates itself, and spawned CLIs receive only a non-secret env allowlist by default (`delegation.envMode=minimal`), so an unrelated key in your shell never reaches them. Prefer an API provider instead? Put the key in the Keychain or `.env` per [Bring your own keys](#bring-your-own-keys-never-the-authors) and pin it, e.g. `vibecoders config set capabilities.image_gen.provider openai-api`. ## Bring your own keys (never the author's) Vibecoders bundles **no** keys and bills **nothing**. You provide your own, only for the capability that needs one: - **Secret vault, Keychain-first (recommended, macOS-only):** `vibecoders vault set OPENAI_API_KEY` stores the key in the OS Keychain (the **secret vault**) — never written to disk, redacted from every log line. (This is the key store; the **notes vault** in the opt-in section above is an unrelated text-search feature.) `vault set` writes the macOS Keychain only — on Linux/Windows use `.env` instead. - **Or `.env` (cross-platform):** copy [`.env.example`](./.env.example) and fill it in (git-ignored). - **Delegation CLIs** (`codex`/`gemini`/`claude`) use **their own** sign-in — there's nothing for Vibecoders to store. Recognized keys (all optional): `OPENAI_API_KEY`, `GEMINI_API_KEY`, `BRAVE_API_KEY`, `TAVILY_API_KEY`, `ANTHROPIC_API_KEY`, `GITHUB_TOKEN`, `VERCEL_TOKEN`, `SUPABASE_ACCESS_TOKEN`. ## Install as a plugin (MCP server) This repo is also a Claude Code **plugin**. `.claude-plugin/plugin.json` is the manifest, `.claude-plugin/marketplace.json` lists it as a one-plugin marketplace, and `.mcp.json` registers the MCP server — all auto-discovered on install. Add the marketplace, then install the plugin from inside Claude Code: ```bash claude plugin marketplace add RaedBerjaoui/vibecoders-mcp # or a local path / git URL ``` ``` /plugin # open the plugin browser, pick "vibecoders" → Install ``` `/plugin` (or `claude plugin install vibecoders@vibecoders`) registers the MCP server for you — no separate `claude mcp add` needed. ## Security — tight, not annoying - **No secrets in the repo, ever.** `.env`, `servers.json`, `config.json`, and the memory store are git-ignored; only blank templates ship. - **Keychain-first**, redacted from every log line (live values + known token shapes). - **Fail closed.** A tool that needs a key you haven't set stops with a clear message. - **No shell injection** anywhere: every subprocess is `spawn(cmd, argsArray)` — never a shell string, so delegated CLIs and downstream servers can't be argument-injected. - **SSRF-guarded fetches.** The reference tools refuse private/loopback/metadata targets and re-check every redirect hop's resolved IP. - **Downstream calls are timeout-bounded**; delegation is read-only unless you opt in. See [SECURITY.md](./SECURITY.md) for the full threat model. ## How it compares Vibecoders covers the **developer-productivity** surface of a full agent OS — memory/RAG, multi-agent delegation, web research, reference study, project context, handoffs — as an open, secret-free, self-hostable MCP you run with **your own** accounts. Anything beyond that — browser automation, messaging, calendars — you add yourself by **mounting** the MCP server you trust through the gateway; Vibecoders bundles none of it. ## Commands | Command | What it does | | --- | --- | | `vibecoders init` | Build `dist/index.js` and print status | | `vibecoders register` | Add this server to Claude Code (user scope) | | `vibecoders onboard` | Guided setup + status | | `vibecoders setup [capability]` | Guided, read-only per-capability walkthrough | | `vibecoders doctor [--json]` | Show providers, servers, keys, tool groups, memory, and your lane (same renderer as the MCP `doctor`); `--json` emits structured output for scripts/CI | | `vibecoders config get/set/path` | Customize non-secret behavior (features, memory, reference); `set` warns on an unknown/typo'd key | | `vibecoders vault set <NAME>` | Store a secret in the OS Keychain (the secret vault) — **macOS-only**; on Linux/Windows use `.env` | | `vibecoders vault list` | Show which secrets are set (never the values) | | `vibecoders handoff recall/write` | Print or save this project's `HANDOFF.md` | ## Docs - [Private capability overlay](./docs/private-overlay.md) — load owner-local tools from a per-machine dir that never ships in the repo. - [SECURITY.md](./SECURITY.md) — threat model and how to report a vulnerability. - [CONTRIBUTING.md](./CONTRIBUTING.md) — dev loop, layout, and the release runbook. - [CHANGELOG.md](./CHANGELOG.md) — what shipped, per version. ## License & attribution MIT — see [LICENSE](./LICENSE). Third-party dependencies are attributed in [NOTICE.md](./NOTICE.md).