**The Autonomous Architect for the Vibe Coding Era.**
npm install @getvibeguard/cliThe Autonomous Architect for the Vibe Coding Era.
Stop reminding Cursor what you're building. VibeGuard is an AI-powered governance engine that watches your code, maintains your project's "Soul," and proactively alerts you when you drift from your architectural intent.
---
In the age of AI-driven development, context is everything. But as projects grow, context windows get cluttered, AI becomes forgetful, and architectural drift sets in. VibeGuard solves this by maintaining a stateful, high-density memory of your project. It doesn't just store files; it synthesizes your intent.
- 📚 The Librarian: Watches your Git commits and automatically synthesizes changes into PROJECT_MEMORY.md. It prunes noise and keeps the most important architectural decisions front-and-center.
- 🔮 The Oracle: Proactively scans for "Drift." It identifies when new code violates your core rules or tech-stack constraints before you even open a PR.
- 🎨 The Visual Soul: Generates and maintains a real-time DIAGRAM.md using Mermaid, ensuring you always have a "Skeleton View" of your system.
---
| Feature | Description |
|---------|-------------|
| Atomic Memory | High-density context management that saves up to 80% on token usage. |
| Drift Detection | Proactive alerts when your code deviates from the project's "Soul." |
| Auto-Fix | One-click branch generation and refactoring to realign with architectural rules. |
| Visual Architecture | Auto-generated Mermaid diagrams that evolve with every commit. |
| Token Analytics | Real-time dashboard showing your AI spend vs. savings using smart model routing. |
| Universal LLM | Use your own keys. Supports Gemini 3, GPT-5, and Claude 4.5. |
---
Get VibeGuard up and running in your project in under 60 seconds.
``bash`
npm install -g @getvibeguard/cli
Run the setup wizard in your project root. This will configure your API keys, model profiles, and generate your custom Cursor .mdc rules.
`bash`
vibeguard init
VibeGuard will now monitor your changes and manage your project memory in the background.
`bash`
vibeguard watch
---
VibeGuard provides a comprehensive CLI for managing your project's context and architecture.
| Command | Description |
|---------|-------------|
| vibeguard init | Run the interactive setup wizard to configure API keys, select your LLM provider (Google/OpenAI/Anthropic), choose a model profile (Economy/Balanced/High-IQ), and generate custom Cursor .mdc rules. Also creates PROJECT_MEMORY.md with your project's "Soul" description. |vibeguard watch
| | Start the background watcher that monitors Git commits and automatically updates PROJECT_MEMORY.md. The watcher also runs the Oracle service for drift detection and tracks token usage. Press Ctrl+C to stop. |vibeguard sync
| | Manually process the latest commit(s) and update project memory. Useful for one-off synchronization without starting the watcher. |vibeguard sync --deep
| | Process the full Git history (up to 1000 commits) to build comprehensive project memory from scratch. Use this for initial setup on existing projects. |vibeguard check
| | Run a health check that validates your environment setup, API key validity, Git repository status, and PROJECT_MEMORY.md existence. Displays a status report with colored indicators. |vibeguard visualize
| | Generate or regenerate the architecture diagram (DIAGRAM.md) using Mermaid.js. Scans your src/ directory and uses AI to create a visual representation of your project structure with color-coded components. |vibeguard dashboard
| | Start the local web dashboard server (default port 3000). Provides interactive views for "The Soul" (PROJECT_MEMORY.md), "The Map" (DIAGRAM.md), and "The Pulse" (token analytics and Oracle insights). Opens automatically in your browser. |
`bashFirst-time setup
vibeguard init
---
🛠️ How it Works
VibeGuard operates as a "Shadow Architect" alongside your IDE (Cursor/VS Code):
1. The Hook: Every time you commit or save, the Watcher captures the diff.
2. The Synthesis: The Librarian uses a "Flash" model to update the
, ensuring the AI always has the latest "state."
3. The Governance: When you start a new feature, the Oracle (using .mdc rules) forces the AI to check the Memory and Diagram before writing a single line of code.
4. The Dashboard: Monitor your project's health, architectural map, and token savings via the local VibeGuard Dashboard.---
📉 Token Economics
VibeGuard is built to be "Financially Intelligent." By intelligently routing background tasks (like summarization) to Gemini Flash or GPT-Mini and reserving "Pro" models for complex reasoning, VibeGuard effectively pays for itself.
---
🤝 Community & Feedback
VibeGuard is in Open Beta. We move fast and break things—help us fix them.
- Discord: Join the VibeGuard Tribe (Real-time support & Vibe checks)
- GitHub Issues: Found a bug? Open an issue.
---
❓ Troubleshooting & FAQ
$3
VibeGuard stores keys globally in
~/.vibeguard/config.json.Fix: Run
vibeguard init --reconfigure to re-enter your keys.Pro-Tip: If you prefer environment variables, VibeGuard will prioritize
GOOGLE_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY if they are set in your shell.$3
If
DIAGRAM.md shows raw text instead of a chart:- VS Code: Ensure you have the Markdown Preview Mermaid Support extension installed.
- Cursor: The built-in preview supports Mermaid by default. If it fails, check for syntax errors at the top of the file—VibeGuard usually auto-fixes these on the next
visualize run.$3
If your "Pulse" dashboard shows a spike in spend:
- Check your Profile: You may be on "High-IQ" mode. Switch to "Balanced" or "Economy" using
vibeguard init to use Flash models for routine summaries.
- Large Commits: Avoid staging massive binary files or node_modules. VibeGuard respects .gitignore, but heavy text files can still consume tokens.$3
If you see
command not found: vibeguard:- Ensure you installed it globally:
npm install -g @getvibeguard/cli.
- If using npx, run npx @getvibeguard/cli ---
MIT © 2026 VibeGuard Team.