vibe-xp

CLI tool for managing AI collaboration assets (skills, agents, rules, MCP servers) across Claude Code, Cursor, Codex, Gemini CLI, Windsurf, and GitHub Copilot.

This project reproduces project-owned delta only — it syncs project-specific assets to your AI infrastructure, not your entire ~/.claude directory.

Quick Start

# 1. Clone & build
git clone <repo-url> && cd vibe-experience
npm install && npm run build

# 2. Initialize project
vibe-xp init

# 3. Install assets
vibe-xp install

# 4. Check environment health
vibe-xp doctor

# 5. Auto-fix issues
vibe-xp doctor --fix

# 6. Mirror instructions to other tools
vibe-xp bridge

Commands (33)

All commands support --json for machine-readable output.

Core Asset Management

| Command | Description | |---------|-------------| | vibe-xp init | Initialize project scaffolding (--template minimal\|standard\|team) | | vibe-xp create <type> <name> | Scaffold a new asset (skill/rule/agent/mcp) | | vibe-xp install [type] [name] | Install assets (internal/external/remote) | | vibe-xp remove <type> <name> | Remove an installed asset | | vibe-xp sync | Detect and repair drifted assets | | vibe-xp sync --watch | Watch asset directories and auto-sync on changes | | vibe-xp upgrade | Update outdated external assets | | vibe-xp pin <type> <name> | Pin an asset to prevent upgrades | | vibe-xp unpin <type> <name> | Unpin an asset to allow upgrades | | vibe-xp hooks <action> | Install/uninstall git hooks for auto-sync |

Status & Diagnostics

| Command | Description | |---------|-------------| | vibe-xp status | Show installed asset status with size and estimated tokens | | vibe-xp doctor | Diagnose AI environment issues | | vibe-xp doctor --fix | Auto-fix fixable issues (unmanaged, orphaned, missing instructions) | | vibe-xp doctor --dry-run | Preview what --fix would do without applying | | vibe-xp check | Run all health checks with health score (A-F grade) | | vibe-xp check --fix | Auto-fix: doctor fix + sync repair + bridge mirror | | vibe-xp why <type> <name> | Show detailed info about an installed asset | | vibe-xp env | Display environment info + detect installed AI CLI tools | | vibe-xp list [type] | List all available and installed assets | | vibe-xp search <query> | Search installed assets by keyword (name + content) | | vibe-xp validate <name> | Validate a skill for distribution | | vibe-xp audit | Security audit (secrets detection, MCP command check, provenance) | | vibe-xp stats | Asset analytics (type/scope distribution, token usage) | | vibe-xp report | Generate comprehensive markdown report |

Profiles

| Command | Description | |---------|-------------| | vibe-xp profile list | List defined profiles | | vibe-xp profile apply <name> | Install all assets in a profile | | vibe-xp profile apply <name> --clean | Switch to profile, removing extras | | vibe-xp profile capture <name> | Save current state as a profile | | vibe-xp profile diff <name> | Show what would change |

Cross-Tool Bridge

| Command | Description | |---------|-------------| | vibe-xp bridge | Mirror AGENTS.md to CLAUDE.md, .cursor/rules, .windsurfrules, GEMINI.md, copilot-instructions.md | | vibe-xp bridge --check | Check for drift without writing | | vibe-xp bridge --watch | Auto-mirror on file changes | | vibe-xp translate --to <format> | Convert AI tool settings (claude/cursor/codex/windsurf/gemini/copilot) |

Environment Snapshots

| Command | Description | |---------|-------------| | vibe-xp lock | Capture environment snapshot for reproducibility | | vibe-xp replay [snapshot] | Compare current state against a snapshot | | vibe-xp diff <snap1> <snap2> | Compare two environment snapshots |

Import & Config

| Command | Description | |---------|-------------| | vibe-xp import mcp <url> | Import MCP descriptor from URL/registry | | vibe-xp import bundle <file> | Restore environment from export bundle | | vibe-xp export | Export AI environment as a portable bundle | | vibe-xp mcp ls | List configured MCP servers | | vibe-xp mcp validate | Validate MCP server configurations | | vibe-xp config [action] [key] [value] | Manage vibe-xp.json settings | | vibe-xp completions <shell> | Generate shell completion script (bash/zsh/fish/powershell) | | vibe-xp ci generate | Generate GitHub Actions workflow for environment health checks |

Context Budget

Set contextBudget in vibe-xp.json to get warnings when total estimated tokens exceed the limit:

{
  "contextBudget": 50000
}

vibe-xp status will show estimated tokens per asset and warn when the budget is exceeded (4 bytes ≈ 1 token heuristic).

Asset Structure

| Directory | Asset Type | Description | |-----------|-----------|-------------| | packages/skills/ | skill | Project-specific skills (source) | | .agents/skills/ | skill | Built skills (synced from packages/skills) | | .agents/agents/ | agent | Project-specific agents | | rules/ | rule | Project-specific rules | | mcp/ | mcp | MCP server descriptors | | vibe-xp.json | manifest | External skills, profiles, context budget | | .vibe-xp/policy.json | policy | MCP allowlist policy | | .vibe-xp/state.json | state | Local asset tracking |

Global Options

| Option | Description | |--------|-------------| | --json | Output as JSON (all commands) | | --verbose | Enable detailed output | | --quiet | Suppress non-error output | | --version | Show version | | --help | Show help |

Shell Completions

# Bash — add to ~/.bashrc
eval "$(vibe-xp completions bash)"

# Zsh — add to ~/.zshrc
eval "$(vibe-xp completions zsh)"

# Fish — add to ~/.config/fish/config.fish
vibe-xp completions fish | source

# PowerShell — add to $PROFILE
vibe-xp completions powershell | Out-String | Invoke-Expression

Quick Reference

vibe-xp init [--template]      Initialize project
vibe-xp create <type> <name>   Scaffold asset
vibe-xp install [type] [name]  Install assets
vibe-xp remove <type> <name>   Remove asset
vibe-xp sync [--watch]         Sync/watch assets
vibe-xp upgrade                Update external assets
vibe-xp pin/unpin <type> <n>   Pin/unpin version
vibe-xp status                 Asset status + tokens
vibe-xp doctor [--fix]         Diagnose/fix issues
vibe-xp check [--fix]          Full health check (A-F)
vibe-xp audit                  Security audit
vibe-xp search <query>         Search by keyword
vibe-xp why <type> <name>      Asset details
vibe-xp env                    Environment + CLI tools
vibe-xp list [type]            List assets
vibe-xp validate <name>        Validate for deploy
vibe-xp bridge [--watch]       Mirror to AI tools
vibe-xp translate --to <fmt>   Convert between tools
vibe-xp lock                   Capture snapshot
vibe-xp replay [snapshot]      Compare vs snapshot
vibe-xp diff <s1> <s2>         Compare two snapshots
vibe-xp export                 Export env bundle
vibe-xp import bundle <file>   Import env bundle
vibe-xp import mcp <url>       Import MCP server
vibe-xp mcp ls                 List MCP servers
vibe-xp mcp validate           Validate MCP config
vibe-xp ci generate            Generate CI workflow
vibe-xp config [get|set]       Manage settings
vibe-xp completions <shell>    Shell completions
vibe-xp hooks <install|...>    Git auto-sync hooks
vibe-xp report [--output]      Generate markdown report
vibe-xp stats                  Asset analytics dashboard
vibe-xp profile [action]       Manage profiles

Development

npm test          # Run tests (821+)
npm run build     # Compile TypeScript
npm run lint      # ESLint
npm run format    # Prettier