vibecheqq

Stop re-explaining everything to your AI. Just VibeCheqq it.

Persistent AI memory. 650+ Google Style Guide rules. 21 languages. One command. Zero config.

The Problem

You're vibe coding. The AI writes fast. But:

• It forgets everything. Every new session starts from zero. You re-explain the project, the stack, the conventions. Again.
• It ignores style guides. The code runs, but it's unmaintainable — inconsistent naming, missing docs, broken formatting.
• Nobody catches it. Linters run in terminals. They don't run inside the AI's workflow. Bad code gets committed.
• Every linter is one language. ESLint for JS, ruff for Python, checkstyle for Java, swiftlint for Swift... or vibecheqq for all of them.

The Solution

vibecheqq is an MCP server + agent plugin ecosystem that lives inside your AI agent.

Grade F to Grade A. In milliseconds.

Dev A works Monday. Dev B pulls Tuesday. The AI already knows.

You walked away. It fixed 23 violations.

Quick Start

One command — auto-detects all installed IDEs and wires everything up:

npx -y vibecheqq-mcp@latest install

This detects Cursor, Claude Code, VS Code + GitHub Copilot, Windsurf, Zed, Continue, and OpenCode — writes MCP configs and injects agent plugins for every IDE it finds.

Target a specific IDE:

npx -y vibecheqq-mcp@latest install --cursor
npx -y vibecheqq-mcp@latest install --claude
npx -y vibecheqq-mcp@latest install --vscode     # VS Code + GitHub Copilot
npx -y vibecheqq-mcp@latest install --windsurf

Claude Code only — full global bootstrap:

npx -y vibecheqq-mcp@latest setup-claude

Sets up ~/.claude/ hooks, CLAUDE.md, and .vibecheqq/ in one shot.

Manual — Claude Code:

claude mcp add vibecheqq -- npx -y vibecheqq-mcp@latest

Manual — VS Code / Cursor / Claude Desktop (add to your MCP config):

{
  "mcpServers": {
    "vibecheqq": {
      "command": "npx",
      "args": ["-y", "vibecheqq-mcp@latest"]
    }
  }
}

Then in your AI agent:

Run /vibecheqq-init

That's it. Your AI now has persistent memory and 650+ style rules loaded.

What You Get

Layer 1 — Persistent AI Memory

The killer feature. A .vibecheqq/ directory committed to git that gives your AI long-term memory across sessions, machines, and developers.

.vibecheqq/
├── context.md       ← Project purpose, tech stack, architecture
├── conventions.md   ← Naming, patterns, team rules
├── tasks.md         ← What's done, what's next (compressed format)
├── session-log.md   ← What happened last session (AI handoff)
├── history.json     ← Score tracking over time
└── skills/          ← Targeted architectural rulebooks per tech stack

Dev A works Monday, commits .vibecheqq/. Dev B pulls Tuesday on a different machine. The AI already knows what Dev A did — zero re-explanation.

You switch from Cursor to Claude Code to Copilot. All three read the same .vibecheqq/ files. Your AI never loses context again.

Executable Skills — instead of loading your entire codebase into context:

.vibecheqq/skills/
├── react_ui_guidelines.md      ← Generated if stack includes React/Next.js
├── node_api_routes.md          ← Generated if stack includes Node/Express
├── database_schema_rules.md    ← Generated if stack includes SQL/Postgres
├── authentication_flow.md      ← Generated if features include auth
└── nextjs_community_rules.md   ← Auto-fetched from awesome-cursorrules

The AI loads only the relevant skill for the current task. No context bloat. No hallucinations.

Layer 2 — Smart Stack Detection

vibecheqq auto-detects your tech stack by scanning package.json, go.mod, Cargo.toml, config files, and file extensions — then suggests community best-practice skills from awesome-cursorrules.

[VibeCheqq] Detected stack: Next.js, Tailwind, TypeScript
Community skills available. Want me to fetch them?

• Per-skill decline — say no to one, yes to another. Declined skills are never suggested again.
• Incremental — add a new framework? Only the new one is suggested.
• Zero config — runs at session start via hooks, or on-demand via suggest_skills.

Layer 3 — Rules Engine

Instant regex analysis enforcing every Google Style Guide ever published. Runs locally in <100ms. No API key. No cloud. No configuration.

src/server.ts  →  Score: 94/100  →  Grade: A

  Line 42:  TS-NAM-03 (low)    Use camelCase for variables
  Line 118: TS-DOC-01 (medium) Add JSDoc to exported function

650+ rules across 21 languages:

| Language | Rules | Language | Rules | Language | Rules | |----------|------:|----------|------:|----------|------:| | TypeScript | 74 | Dart | 49 | Shell | 37 | | JavaScript | 49 | Python | 46 | C++ | 44 | | Kotlin | 40 | Objective-C | 42 | C# | 37 | | Java | 39 | Go | 33 | Swift | 35 | | R | 36 | Vimscript | 19 | Lisp | 26 | | HTML | 16 | CSS | 15 | Markdown | 17 | | JSON | 16 | XML | 16 | Angular | 16 |

Every violation comes with a line number, severity, rule ID, and an exact fix suggestion.

Scoring:

| Grade | Score | Meaning | |:-----:|:-----:|---------| | A | 90–100 | Production-ready, Google-grade quality | | B | 80–89 | Good — minor issues only | | C | 70–79 | Needs attention | | D | 60–69 | Significant style violations | | F | 0–59 | Critical structural issues |

Penalties: critical=15, high=10, medium=5, low=2 per violation. Log-normalized dampening for large files.

Layer 4 — AI Deep Review

Catches what 650 rules can't — misleading docstrings, architectural anti-patterns, deeply nested closures, logic that's technically valid but semantically wrong.

Plug in any LLM or run fully local:

| Provider | Environment Variables | |----------|----------------------| | Google Gemini | AI_PROVIDER=gemini + GEMINI_API_KEY + GEMINI_MODEL | | OpenAI | AI_BASE_URL=https://api.openai.com/v1 + AI_API_KEY + AI_MODEL | | Groq | AI_BASE_URL=https://api.groq.com/openai/v1 + AI_API_KEY + AI_MODEL | | Together AI / Fireworks | Same pattern — any OpenAI-compatible API | | Ollama / LM Studio | AI_BASE_URL=http://localhost:PORT/v1 + AI_API_KEY=ollama + AI_MODEL |

No key configured? vibecheqq silently falls back to regex-only. It never crashes, never blocks work.

Want AI deep review? Add env vars to your MCP config:

{
  "mcpServers": {
    "vibecheqq": {
      "command": "npx",
      "args": ["-y", "vibecheqq-mcp@latest"],
      "env": {
        "AI_BASE_URL": "https://api.groq.com/openai/v1",
        "AI_API_KEY": "your-key",
        "AI_MODEL": "llama-3.3-70b-versatile"
      }
    }
  }
}

Layer 5 — Autopilot Mode

/vibecheqq-autopilot

The agent scans your file, picks the worst violation, fixes it, re-verifies, repeats — until Grade A (90+) or 15 iterations max. Uses #rename for naming violations, calls task_complete when done.

Walk away. Come back to Grade A.

Requires VS Code 1.111+ with chat.autopilot.enabled. Also works in Copilot CLI sessions (VS Code 1.112+).

Layer 6 — Lifecycle Hooks

4 hooks that fire automatically — no human remembering required:

| Hook | When | What It Does | |------|------|-------------| | Bootstrap | Session start | "No .vibecheqq/? Run /vibecheqq-init." | | Context Loader | Session start | Reads conventions + loads matching skill | | Skill Suggest | Session start | Auto-detects stack, suggests community skills | | Session Sync | Session end | Updates session-log.md, compresses tasks |

Layer 7 — One Tool, Every IDE

vibecheqq isn't locked to one IDE. One MCP server, every platform:

| Platform | Installation | |----------|-------------| | Claude Code | claude mcp add vibecheqq -- npx -y vibecheqq-mcp@latest | | VS Code + Copilot | Agent plugin with hooks, slash commands, and a custom reviewer agent | | Cursor | MCP server + .cursorrules integration | | Claude Desktop | MCP config in claude_desktop_config.json | | Any MCP client | npx -y vibecheqq-mcp@latest |

MCP Tools

| Tool | What It Does | |------|-------------| | vibecheqq_file | Full review on one file → score, violations, exact fixes | | vibecheqq_workspace | Scan entire directory → heatmap, score trends, README badge | | vibecheqq_pr | PR quality gate — scan git diff, pass/fail against threshold | | list_rules | Browse all 650+ rules, filter by language | | scaffold_vibecheqq | Create .vibecheqq/ ecosystem from guided questions | | suggest_skills | Auto-detect stack, fetch community skills |

Slash Commands (Agent Plugins)

| Command | What It Does | |---------|-------------| | /vibecheqq | Analyze the active file | | /vibecheqq-workspace | Audit the entire project | | /vibecheqq-pr | Quality gate on changed files | | /vibecheqq-init | Set up .vibecheqq/ project memory | | /vibecheqq-autopilot | Autonomous fix-verify loop until Grade A |

The Agent

@vibecheqq-reviewer is a specialized code reviewer persona that:

1. Scans code using vibecheqq_file — gets score, violations, fix suggestions
2. Fixes by severity — critical first, low last
3. Re-verifies after every fix — never assumes fixes are clean
4. Updates .vibecheqq/tasks.md automatically

Plugin Installation

Claude Code Plugin

Copy claude-plugin/ into your project and add to .claude/settings.json:

{
  "plugins": ["./claude-plugin"]
}

VS Code + GitHub Copilot Plugin

Copy awesome-copilot/ into your project as plugin/ and enable in VS Code settings:

{
  "chat.plugins.enabled": true,
  "chat.plugins.paths": ["./plugin"]
}

Cursor Plugin

Copy plugin/ into your project and add to Cursor MCP settings:

{
  "mcpServers": {
    "vibecheqq": {
      "command": "npx",
      "args": ["-y", "vibecheqq-mcp@latest"]
    }
  }
}

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Developer's IDE                               │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐  │
│  │ Claude Code  │  │    Cursor    │  │  VS Code + Copilot    │  │
│  │   Plugin     │  │   Plugin     │  │       Plugin          │  │
│  │              │  │              │  │                       │  │
│  │ /vibecheqq   │  │ /vibecheqq   │  │ /vibecheqq            │  │
│  │ /init        │  │ /init        │  │ /init                 │  │
│  │ /autopilot   │  │ /autopilot   │  │ /autopilot            │  │
│  │ /workspace   │  │ /workspace   │  │ /workspace            │  │
│  │ /pr          │  │ /pr          │  │ /pr                   │  │
│  │              │  │              │  │                       │  │
│  │  4 Hooks:    │  │  4 Hooks:    │  │  4 Hooks:             │  │
│  │  bootstrap   │  │  bootstrap   │  │  bootstrap            │  │
│  │  ctx-loader  │  │  ctx-loader  │  │  ctx-loader           │  │
│  │  skill-sug.  │  │  skill-sug.  │  │  skill-suggest        │  │
│  │  session-end │  │  session-end │  │  session-end          │  │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬────────────┘  │
│         └─────────────────┴──────────────────────┘               │
│                           │  MCP Protocol (stdio)                │
└───────────────────────────┼─────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                   vibecheqq MCP Server                           │
│                                                                  │
│  ┌──────────────────────┐    ┌──────────────────────────────┐   │
│  │    Rules Engine       │    │       AI Deep Review          │   │
│  │  650+ rules, 21 langs │    │  Gemini / OpenAI / Groq /    │   │
│  │  <100ms, no API key   │◄──►│  Ollama — any LLM provider   │   │
│  │  regex + tokenizer    │    │  semantic + architectural     │   │
│  └──────────────────────┘    └──────────────────────────────┘   │
│                   │                        │                     │
│                   └──────── Merged ────────┘                     │
│                                  │                               │
│          score (0-100) · grade (A-F) · violations                │
│          line numbers · rule IDs · exact fix suggestions         │
│                                                                  │
│  ┌──────────────┐  ┌─────────────┐  ┌──────────────────────┐   │
│  │ vibecheqq_   │  │ vibecheqq_  │  │   vibecheqq_pr       │   │
│  │    file      │  │  workspace  │  │  (PR quality gate)    │   │
│  │ (per-file    │  │ (directory  │  │  git diff → pass/fail │   │
│  │  review)     │  │  heatmap)   │  │  against threshold    │   │
│  └──────────────┘  └─────────────┘  └──────────────────────┘   │
│  ┌──────────────┐  ┌─────────────┐  ┌──────────────────────┐   │
│  │ scaffold_    │  │ list_rules  │  │   suggest_skills      │   │
│  │ vibecheqq    │  │ (browse all │  │  stack detect →       │   │
│  │ (.vibecheqq/ │  │  650+ rules │  │  community skills     │   │
│  │  generator)  │  │  by lang)   │  │  from cursorrules     │   │
│  └──────────────┘  └─────────────┘  └──────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                .vibecheqq/ — Persistent AI Memory                │
│                                                                  │
│  context.md      ← project purpose, stack, architecture         │
│  conventions.md  ← naming, patterns, team rules                 │
│  tasks.md        ← compressed task chains (AI-expandable)       │
│  session-log.md  ← what happened last session (AI handoff)      │
│  history.json    ← score trends over time                       │
│  skills/         ← targeted rulebooks per framework             │
│  .declined.json  ← per-skill community suggestions (never re-asks)│
│                                                                  │
│  Committed to git. Cross-IDE. Grows every session.              │
└─────────────────────────────────────────────────────────────────┘

The Compressed Task Protocol

How AI agents hand off work through tasks.md:

[x] Built user auth flow (steps: schema→routes→middleware→tests→docs)
[/] Refactoring payments (done: extract-service→add-types | next: update-routes→tests)
[ ] Add rate limiting to API endpoints

3-5 subtasks compress into 1 line. The next AI expands the step chain back into working memory. Human-scannable. AI-expandable.

Under the Hood

Hardened Tokenizer — getCleanLines strips comments and strings before any regex runs. Eliminates false positives from TODOs in comments, URLs in strings, style violations inside documentation.

Smart Chunking — Files too large for AI context windows are split into semantically meaningful chunks by chunker.ts. Each chunk is analyzed independently, results are merged. No manual splitting.

21 MCP Resources — Every language exposes a vibecheqq://rules/{language} resource endpoint. AI agents can browse rules programmatically without calling a tool.

.vibecheqq/ignore — Like .gitignore for quality scans. Skip generated files, vendored code, or directories you don't control.

Monorepo Support (VS Code 1.112+)

Enable chat.useCustomizationsInParentRepositories. Place vibecheqq at the monorepo root:

monorepo/
├── plugin/          ← vibecheqq hooks, agent, skills, commands
├── .vibecheqq/      ← Shared project memory
├── packages/
│   ├── frontend/    ← Open this folder — hooks still fire
│   ├── backend/     ← Open this folder — hooks still fire
│   └── shared/

Every sub-package gets vibecheqq automatically. No per-package setup.

Building from Source

git clone https://github.com/PralhadYadawad/vibecheqq.git
cd vibecheqq
npm install
npm run build
npm start

Tech stack: Node.js + TypeScript. 3 runtime dependencies — intentionally minimal.

@modelcontextprotocol/sdk  |  @google/generative-ai  |  openai

Troubleshooting

If hooks aren't firing or skills aren't loading:

1. Enable agent debug logging in VS Code settings:

   "github.copilot.chat.agentDebugLog.enabled": true,
   "github.copilot.chat.agentDebugLog.fileLogging.enabled": true

2. Reload VS Code
3. Run /troubleshoot in Copilot Chat — it analyzes the debug logs and explains why hooks/skills/agents were skipped

Common issues:

• No .vibecheqq/ directory — run /vibecheqq-init first
• Plugin not loaded — check chat.plugins.enabled: true and verify chat.plugins.paths
• MCP server not connecting — verify mcp.json config and that node is on your PATH

Design Philosophy

Zero-config to start. No API key, no setup. Run it and get instant value from 650+ rules.

Graceful degradation, always. No API key → regex-only. AI fails → fallback. File too large → auto-chunk. It never crashes, never blocks work.

The user won't remember. Hooks exist because humans forget to check quality, update docs, and hand off context. The AI does it for them.

The linter is the hook. The ecosystem is the moat. Anyone can build a linter. The persistent memory system is what makes developers stay.

One tool, every language, every IDE. MCP protocol = IDE-agnostic. 21 languages in one server = no tool sprawl.

Contributing

See CONTRIBUTING.md. PRs welcome.

Rule IDs follow LANG-CATEGORY-NN (e.g., TS-NAM-03, PY-EXC-01). Imports use .js extensions. Max 1500 lines per file.

License

MIT — see LICENSE