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, 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:

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):

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):

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)
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/:

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 for annotated examples; a minimal entry is just a command:

{
  "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.)

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

Customize everything

All non-secret behavior lives in ~/.vibecoders/config.json (git-ignored). Copy config.example.json or use the CLI:

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, and the reference environment it's designed against is the Warp 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 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 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:

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 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 — load owner-local tools from a per-machine dir that never ships in the repo.
• SECURITY.md — threat model and how to report a vulnerability.
• CONTRIBUTING.md — dev loop, layout, and the release runbook.
• CHANGELOG.md — what shipped, per version.

License & attribution

MIT — see LICENSE. Third-party dependencies are attributed in NOTICE.md.