VibeSmith 🎵

AI Agent Components Manager for Cursor & Claude Code

Manage your AI coding agent's skills, subagents, commands, and hooks like a pro. Beautiful GUI, dependency visualization, team collaboration, and more.

Source Build • Documentation • Community

---

Release Status

• GitHub Releases is the canonical public release channel.
• Latest public installs resolve from the newest non-draft GitHub release, including prereleases.
• Homebrew installs use the GitHub tap at aroido/homebrew-vibesmith.
• GitLab vibesmith-community remains a legacy mirror only.
• The canonical install guide lives on aroido.com/projects/vibesmith.

✨ Features

• 🎯 Unified Management - Skills, Subagents, Commands, Hooks in one place
• 📊 Dependency Graph - Visualize component relationships with interactive graphs
• 🔍 Smart Search - Find components instantly with fuzzy search
• 🎨 Beautiful UI - Modern, intuitive interface built with React & shadcn/ui
• 🔄 Auto Sync - Keep local and global contexts synchronized
• 🤝 Team Collaboration - Share components with your team (planned)
• 🔐 Secure - Local-first architecture, your data stays on your machine
• ⚡ Fast - Instant scanning and real-time updates

🖼️ Screenshots

📸 Screenshots coming soon! The app is currently in active development.

🚀 Quick Start

Choose one of the current public install paths:

• Direct download and release notes: GitHub Releases
• Homebrew:

brew update
brew tap aroido/vibesmith https://github.com/aroido/homebrew-vibesmith.git
brew install --cask aroido/vibesmith/vibesmith

• Source build: follow the repo instructions below

If you previously installed from the legacy GitLab tap, retap before upgrading:

brew untap aroido/vibesmith
brew tap aroido/vibesmith https://github.com/aroido/homebrew-vibesmith.git
brew upgrade --cask --greedy aroido/vibesmith/vibesmith

From Source

To build from source, you need the following tools.

Prerequisites

• Python: 3.11 or higher
• Node.js: 18 or higher
• npm: 8 or higher

Installation

# Clone the repository
git clone https://github.com/aroido/vibesmith.git
cd vibesmith

# Setup (creates venv, installs all dependencies)
make setup

# Start development servers (API + Web)
make dev

Servers will be available at:

• API: http://localhost:8000
• Web: http://localhost:5173
• API Docs: http://localhost:8000/docs

Build Desktop App

make dist-desktop           # All platforms
make dist-desktop-mac       # macOS
make dist-desktop-win       # Windows
make dist-desktop-linux     # Linux

Build artifacts are generated in packages/desktop/release/.

📋 Release Notes

VibeSmith keeps curated English release notes ready for tagged GitHub releases.

• GitHub releases page
• Release notes index
• Public release media assets
• Distribution policy

In-app update prompts and the Settings release notes modal resolve against GitHub Releases.

📋 Project Structure

vibesmith/
├── packages/
│   ├── core/          # Python core engine (scan, parse, DB, dependencies)
│   ├── api/           # FastAPI REST server
│   ├── web/           # React/Vite SPA frontend
│   ├── desktop/       # Electron desktop app
│   └── landing/       # Next.js companion install/docs page
├── docs/              # Project documentation and release notes
├── .github/           # GitHub Actions, issue templates
├── Makefile           # Development automation
└── .venv/             # Python virtual environment (auto-generated)

🛠️ Development

Common Commands

# Development
make dev              # Start API + Web servers
make dev-api          # Start API server only
make dev-web          # Start Web server only

# Testing
make test             # Run Python tests
make test-web         # Run Web tests
make test-all         # Run all tests

# Code Quality
make lint             # Lint all code
make format           # Format all code
./scripts/quality-gate.sh  # Run full quality check (before commit!)

# Cleanup
make clean            # Clean build artifacts
make clean-all        # Clean everything (venv + node_modules)

Development Workflow

# 1. Start dev servers
make dev

# 2. Make changes...

# 3. Run tests
make test-all

# 4. Quality gate (before commit!)
./scripts/quality-gate.sh

# 5. Commit
git add .
git commit -m "feat: add amazing feature"

🔴 Important: Always run ./scripts/quality-gate.sh before committing!

For more details, see CONTRIBUTING.md.

🔧 Tech Stack

Backend

• Python 3.11+ - Core language
• FastAPI - REST API framework
• Pydantic v2 - Data validation
• SQLite - Database
• pytest - Testing

Frontend

• React 18 - UI framework
• TypeScript - Type safety
• Vite - Build tool
• React Query - Server state management
• Zustand - Client state management
• shadcn/ui - Component library
• React Flow - Graph visualization
• Vitest - Testing

Desktop

• Electron 28+ - Cross-platform desktop app
• electron-builder - Packaging
• electron-updater - Auto-updates
• Sentry - Crash reporting (opt-in)
• PostHog - Analytics (opt-in)

📚 Documentation

• Index - Documentation overview
• Architecture - System architecture
• API Spec - REST API specification
• Security Policy - Security & vulnerability reporting

🤝 Contributing

We welcome contributions! Please see:

• Contributing Guide - How to contribute
• Code of Conduct - Community guidelines
• Issue Templates - Bug reports & feature requests

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'feat: add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

🐛 Bug Reports

If you find a bug, please report it on GitHub Issues.

Desktop App Bug Reports

When reporting a desktop app issue, attaching a diagnostic bundle helps us resolve it faster:

1. Go to Settings > Installed App Diagnostics
2. Check Enable Debug Mode (24h) → reproduce the issue
3. Click Export Diagnostic Bundle → save the ZIP file
4. Create an issue using the Bug Report template and attach the ZIP

The bundle includes app logs, system info, and crash dump metadata. No personal data is included.

Crash Reporting

The desktop app supports crash reporting powered by Sentry.

• On first launch, you can choose to enable it in Settings (opt-in)
• Crash Reporting: Automatically sends reports when the app crashes
• Performance Monitoring: Collects app performance metrics
• Usage Analytics: Anonymous usage statistics (disabled by default)
• You can disable it anytime in Settings

🔐 Security

VibeSmith adopts a Local-First architecture:

• All data is stored on your local disk
• No data is transmitted externally without your consent
• Network communication is minimized (the API server is also local)

If you discover a security vulnerability, please report it through the channels below instead of a public Issue:

• GitHub Security Advisories: https://github.com/aroido/vibesmith/security/advisories/new
• Email: admin@aroido.com

For detailed security policies, see SECURITY.md.

📄 License

This project is licensed under the Apache License 2.0.

See LICENSE for full terms.

🌟 Roadmap

Done

• Core scanning engine (multi-platform: Cursor, Claude Code)
• Dependency graph visualization
• Web UI (React + shadcn/ui)
• macOS Desktop app (Electron)
• Component CRUD, toggle, copy
• Context optimization advisor
• Auto-update system

In Progress

• Onboarding tutorial
• Skill conflict detection
• Template system

Planned

• Skill marketplace (local)
• Team collaboration
• Cloud sync

See GitHub Issues for detailed progress.

💡 Tips

Virtual Environment

Makefile automatically uses the virtual environment, but to activate manually:

source .venv/bin/activate

Port Configuration

Default ports:

• API: 8000
• Web: 5173

To change, edit Makefile (API) or packages/web/vite.config.ts (Web).

IDE Setup

• VSCode/Cursor: Standard editor setup, no special configuration needed

🐛 Troubleshooting

Port Already in Use

# Automatic (recommended)
make kill-ports

# Manual
lsof -ti:8000 | xargs kill -9  # Kill API server
lsof -ti:5173 | xargs kill -9  # Kill Web server

Package Installation Failed

# Clean and reinstall
make clean-all
make setup

Virtual Environment Issues

# Recreate venv
make clean-venv
make venv
make install

🌐 Community & Support

Channel	Purpose
GitHub Issues	Bug reports, feature requests
GitHub Discussions	Questions, ideas, usage tips
Discord	Real-time community (TBD)
admin@aroido.com	Email support (TBD)

Docs: SUPPORT.md (FAQ, issue template guide) · Community Channels

📜 Legal

• License: Apache License 2.0
• Privacy Policy: PRIVACY.md
• Terms of Service: TERMS.md
• Third-Party Licenses: THIRD_PARTY_LICENSES.md
• Contributing: CONTRIBUTING.md - Includes CLA

🙏 Acknowledgments

Built with ❤️ by @aroido-bigcat and @aroido-kkachi. All contributors

Special thanks to:

• Cursor - AI-powered code editor
• Claude Code - AI coding assistant
• Raycast - Inspiration for UX design

---

Made with 🎵 by VibeSmith Team

Copyright © 2026 Aroido Team.