Frequently Asked Questions

Common questions and answers about VDK CLI usage, configuration, and troubleshooting.

General Questions

What is VDK CLI?

Q: What does VDK stand for and what does it do?

A: VDK stands for "Vibe Development Kit" - it's the world's first AI assistant enhancement tool that makes your coding environment project-aware. VDK analyzes your codebase to understand its architecture, patterns, and conventions, then generates intelligent rules that enhance AI assistants like Claude Code, Cursor, Windsurf, and GitHub Copilot with deep project understanding.

How is VDK different from other AI tools?

Q: How does VDK differ from existing AI coding assistants?

A: VDK doesn't replace your AI assistant - it enhances it. While AI assistants like Claude Code or Cursor provide general coding help, VDK teaches them about your specific project:

Before VDK: Generic suggestions that may not fit your project
After VDK: Context-aware suggestions that follow your patterns, conventions, and architecture

VDK bridges the gap between general AI knowledge and project-specific intelligence.

Native ES modules support
Advanced file system watching
Better memory management
Modern crypto APIs for secure rule generation

Solution: Update Node.js using nvm:

nvm install 22
nvm use 22

Permission Issues

Q: I get permission errors when installing VDK globally. What should I do?

A: This is common on macOS/Linux. Try these solutions:

# Option 1: Configure npm to use a different directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Option 2: Use pnpm (recommended)
npm install -g pnpm
pnpm add -g @vibe-dev-kit/cli

# Option 3: Use sudo (less secure)
sudo npm install -g @vibe-dev-kit/cli --unsafe-perm

Command Not Found

Q: After installation, vdk command is not found. How do I fix this?

A: The issue is usually with your PATH configuration:

# Check if VDK is installed
npm list -g @vibe-dev-kit/cli

# Find npm global bin directory
npm config get prefix

# Add to PATH temporarily
export PATH=$(npm config get prefix)/bin:$PATH

# Make permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.bashrc

Project Analysis

Large Project Performance

Q: VDK is slow on my large codebase. How can I improve performance?

A: Large projects require optimization:

# Use more aggressive ignore patterns
vdk init --ignorePattern "**/node_modules/**" "**/dist/**" "**/.git/**" "**/coverage/**"

# Disable deep scanning for initial setup
vdk init --no-deep

# Increase memory limit
export NODE_OPTIONS="--max-old-space-size=4096"

# Use streaming processing
vdk init --stream-processing

# Scan specific directories only
vdk init --projectPath ./src

Memory Issues

Q: VDK runs out of memory during scanning. What can I do?

A: Memory issues are common with large projects:

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=8192"

# Use batch processing
export VDK_BATCH_SIZE=50

# Enable streaming mode
vdk init --stream

# Reduce concurrent operations
export VDK_MAX_CONCURRENCY=2

# Clear caches
vdk cache clear

No Patterns Detected

Q: VDK says "No frameworks detected" even though I'm using React/Next.js. Why?

A: This usually indicates missing or incorrectly structured files:

# Ensure package.json exists and is valid
cat package.json

# Check for framework-specific files
ls -la src/          # React components
ls -la app/          # Next.js App Router
ls -la pages/        # Next.js Pages Router

# Use deep scanning
vdk init --deep

# Check if files are being ignored
vdk init --verbose --ignorePattern "**/node_modules/**" --use-gitignore false

# Manually specify framework
vdk config set project.framework nextjs
vdk init --overwrite

IDE Integration

Claude Code Not Detected

Q: VDK can't detect Claude Code even though it's installed. How do I fix this?

A: Detection issues are usually PATH-related:

# Check if Claude Code is in PATH
which claude
claude --version

# If not found, install Claude Code
npm install -g @anthropic/claude-code

# Verify installation
claude --version

# Force VDK to detect again
vdk integrations --scan

# Manual setup if detection fails
vdk integrations --setup claude-code

Multiple IDEs Setup

Q: Can I use VDK with multiple IDEs simultaneously?

A: Yes! VDK supports multiple IDE integrations:

# Setup multiple IDEs
vdk integrations --setup claude-code
vdk integrations --setup cursor
vdk integrations --setup windsurf

# Check all integrations
vdk integrations --list

# Or setup all detected IDEs
vdk integrations --setup-all

Each IDE gets its own configuration format:

Claude Code: CLAUDE.md + .claude/
Cursor: .cursor/rules/ (MDC format)
Windsurf: .windsurf/rules/ (XML-enhanced Markdown)
GitHub Copilot: .github/copilot/ (JSON format)

Rules Not Updating

Q: My IDE doesn't seem to use the updated VDK rules. What's wrong?

A: This can have several causes:

# Force rule regeneration
vdk init --overwrite

# Update IDE memory
vdk claude-code --update-memory

# Check integration status
vdk integrations --scan
vdk claude-code --check

# Restart your IDE
# (Rules may be cached in IDE memory)

# Verify rule files exist
ls -la .ai/rules/
ls -la CLAUDE.md
ls -la .cursor/rules/

# Check file permissions
chmod -R u+w .ai/ .claude/ .cursor/

VDK Hub

Authentication Issues

Q: I can't connect to VDK Hub. How do I authenticate?

A: Hub authentication requires proper token setup:

# Set authentication token
export VDK_HUB_TOKEN=your_token_here

# Test connectivity
vdk hub ping

# Check current authentication
vdk whoami

# Interactive login (if available)
vdk login

# Verify hub configuration
vdk config get hub.endpoint

Team Collaboration

Q: How do I share VDK rules with my team?

A: Use VDK Hub for team collaboration:

# Deploy rules to team space
vdk deploy --team "frontend-team"

# Team members can sync with:
vdk update --team "frontend-team"

# Or include team in configuration
vdk config set hub.team "frontend-team"
vdk config set hub.autoSync true

# Then regular updates work
vdk update

Deployment Failures

Q: Rule deployment to hub fails. What should I check?

A: Deployment issues are usually network or authentication related:

# Check internet connectivity
ping vdk.tools

# Verify authentication
echo $VDK_HUB_TOKEN
vdk whoami

# Test with dry run
vdk deploy --dry-run

# Check file sizes (hub has limits)
du -sh .ai/rules/

# Try deploying specific rules
vdk deploy --rules "react-patterns,typescript-base"

# Check hub status
vdk hub status

Configuration

Configuration File Errors

Q: VDK says my configuration is invalid. How do I fix it?

A: Configuration validation errors:

# Validate configuration
vdk config validate

# Check JSON syntax
cat vdk.config.json | jq .

# Fix common issues
vdk config fix

# Reset to defaults if corrupted
cp vdk.config.json vdk.config.json.backup
vdk config reset

# Recreate configuration
vdk init --overwrite

Environment Variables

Q: What environment variables does VDK use?

A: Key environment variables:

# Debug mode
export VDK_DEBUG=true

# Hub configuration
export VDK_HUB_URL=https://vdk.tools
export VDK_HUB_TOKEN=your_token

# Performance tuning
export NODE_OPTIONS="--max-old-space-size=4096"
export VDK_SCAN_TIMEOUT=300000
export VDK_MEMORY_LIMIT=2048

# Feature flags
export VDK_TELEMETRY=false
export VDK_WATCH_ENABLED=true

# Custom paths
export VDK_TEMPLATES_DIR=/path/to/templates
export VDK_CONFIG_DIR=/path/to/config

Development Workflow

Watch Mode Issues

Q: Watch mode is consuming too much CPU/memory. How do I optimize it?

A: Watch mode optimization:

# Reduce monitoring scope
vdk watch --ignorePattern "**/node_modules/**" "**/dist/**" "**/*.log"

# Increase debounce time
vdk watch --debounce 10000

# Set memory limits
export VDK_WATCH_MEMORY_LIMIT=256

# Check active watchers
vdk watch list

# Restart watch mode
vdk watch restart

# Monitor performance
vdk watch stats

Git Integration

Q: Should I commit VDK files to git?

A: Yes, but selectively:

# Include in git
git add .ai/rules/ vdk.config.json CLAUDE.md .cursor/rules/

# Exclude cache and logs
echo ".ai/cache/" >> .gitignore
echo ".claude/logs/" >> .gitignore
echo ".cursor/cache/" >> .gitignore

# Optional: exclude local configurations
echo "vdk.config.local.json" >> .gitignore

Updates and Maintenance

Q: How often should I update VDK rules?

A: Update frequency depends on project activity:

# After major changes (recommended)
npm install new-package
vdk init --overwrite

# Weekly maintenance
vdk update                        # Get hub updates
vdk init --overwrite            # Refresh analysis
vdk claude-code --update-memory # Update IDE memory

# Automated updates (optional)
# Add to package.json scripts:
"postinstall": "vdk init --overwrite"

Error Messages

Common Error Solutions

Q: What do these common VDK errors mean?

"Scanner timeout after 120000ms"

# Increase timeout
export VDK_SCAN_TIMEOUT=300000
vdk init

"EACCES: permission denied"

# Fix file permissions
chmod -R u+w .ai/ .claude/ .cursor/
sudo chown -R $USER:$USER .ai/

"Module not found"

# Clear npm cache and reinstall
npm cache clean --force
npm uninstall -g @vibe-dev-kit/cli
npm install -g @vibe-dev-kit/cli

"Invalid JSON in configuration"

# Validate and fix JSON
cat vdk.config.json | jq .
vdk config fix

"Hub connection failed"

# Check internet and authentication
ping vdk.tools
echo $VDK_HUB_TOKEN
vdk hub ping

Performance & Optimization

Slow Performance

Q: VDK is running slowly. How can I improve performance?

A: Performance optimization strategies:

# Profile performance
VDK_PROFILE=true vdk init

# Use incremental scanning
vdk init --incremental

# Optimize ignore patterns
vdk init --ignorePattern "**/node_modules/**" "**/dist/**" "**/coverage/**"

# Disable expensive analyzers
export VDK_DISABLE_ANALYZERS=typescript-ast,dependency-graph

# Use streaming for large projects
vdk init --stream-processing

# Increase memory limit
export NODE_OPTIONS="--max-old-space-size=4096"

# Clear caches
vdk cache clear

Memory Optimization

Q: How can I reduce VDK's memory usage?

A: Memory optimization techniques:

# Set memory limits
export VDK_MEMORY_LIMIT=1024
export NODE_OPTIONS="--max-old-space-size=2048"

# Use batch processing
export VDK_BATCH_SIZE=50

# Reduce concurrency
export VDK_MAX_CONCURRENCY=2

# Enable garbage collection
export NODE_OPTIONS="--expose-gc"

# Monitor memory usage
VDK_MEMORY_PROFILE=true vdk init

Troubleshooting Tools

Debug Mode

Q: How do I enable debug mode for troubleshooting?

A: Comprehensive debugging:

# Full debug mode
export VDK_DEBUG=true
vdk init --verbose

# Component-specific debugging
export VDK_DEBUG_SCANNER=true
export VDK_DEBUG_INTEGRATIONS=true
export VDK_DEBUG_HUB=true

# Save debug output
VDK_DEBUG=true vdk init 2>&1 | tee debug.log

# Debug specific integration
VDK_DEBUG=true vdk claude-code --setup

Diagnostic Commands

Q: What diagnostic commands are available?

A: Built-in diagnostic tools:

# System information
vdk doctor

# Configuration status
vdk config dump
vdk config validate

# Integration status
vdk integrations --scan
vdk claude-code --check

# Hub connectivity
vdk hub status
vdk hub ping

# Rule validation
vdk validate
vdk validate --file .ai/rules/specific-rule.md

# Performance stats
vdk stats
vdk cache stats

Getting Help

Community Support

Q: Where can I get help with VDK?

A: Multiple support channels:

GitHub Issues: Report bugs
GitHub Discussions: Community Q&A
Documentation: Complete docs
Examples: Check examples repository

Reporting Issues

Q: How should I report a bug or issue?

A: Include diagnostic information:

# Gather diagnostic info
vdk doctor > diagnostics.txt
vdk config dump >> diagnostics.txt
vdk --version >> diagnostics.txt
node --version >> diagnostics.txt

# Run with debug mode
VDK_DEBUG=true vdk init 2>&1 > debug.log

# Include in your issue:
# 1. VDK version
# 2. Node.js version
# 3. Operating system
# 4. Project type
# 5. Exact command run
# 6. Error message
# 7. Debug output
# 8. Configuration file

Best Practices

Project Setup

Q: What are the best practices for VDK setup?

A: Recommended practices:

Use gitignore: vdk init --use-gitignore
Appropriate ignore patterns: Don't scan unnecessary files
Regular updates: Keep rules current with project changes
Team synchronization: Use VDK Hub for collaboration
Configuration backup: Version control vdk.config.json
Performance monitoring: Regular performance checks
Documentation: Document team conventions

Development Workflow

Q: How should VDK fit into my development workflow?

A: Recommended workflow:

# Daily workflow
morning: vdk update && vdk claude-code --update-memory
coding: (VDK watch mode runs automatically)
evening: vdk status && git add .ai/ && git commit

# Weekly maintenance
vdk update
vdk init --overwrite
vdk validate
vdk deploy --team our-team

# After major changes
new dependency: vdk init --overwrite
architecture change: vdk init --deep --overwrite
team member onboarding: vdk update && vdk integrations --setup

Still have questions? Check the Common Issues guide or open an issue on GitHub.

FAQ

On this page