A utility for managing Cursor rules, Windsurf rules, and other AI prompts
npm install vibe-rules
A powerful CLI tool for managing and sharing AI rules (prompts, configurations) across different editors and tools.
⨠Supercharge your workflow! āØ
This guide highlights the essential parts of the codebase and how you can quickly start working with vibe-rules.

Quickly save your favorite prompts and apply them to any supported editor:
``bash1. Save your prompt locally
vibe-rules save my-react-helper -f ./prompts/react-helper.md
Or, automatically install shared prompts from your project's NPM packages:
`bash
Find packages with 'llms' exports in node_modules and install for Cursor
vibe-rules install cursor
`(See full command details below.)
Installation
`bash
Install globally (bun recommended, npm/yarn also work)
bun i -g vibe-rules
`Usage
vibe-rules helps you save, list, load, and install AI rules.$3
Store a rule for later use in the common
vibe-rules store (~/.vibe-rules/rules/).`bash
Save from a file (e.g., .mdc, .md, or plain text)
vibe-rules save my-rule-name -f ./path/to/rule-content.mdSave directly from content string
vibe-rules save another-rule -c "This is the rule content."Add/update a description
vibe-rules save my-rule-name -d "A concise description of what this rule does."
`Options:
-
-f, --file : Path to the file containing the rule content.
- -c, --content : Rule content provided as a string. (One of -f or -c is required).
- -d, --description : An optional description for the rule.$3
See all the rules you've saved to the common local store.
`bash
vibe-rules list
`$3
Apply a rule _from your local store_ (
~/.vibe-rules/rules/) to a specific editor's configuration file. vibe-rules handles the formatting.`bash
Load 'my-rule-name' for Cursor (creates/updates .cursor/rules/my-rule-name.mdc)
vibe-rules load my-rule-name cursor
Alias: vibe-rules add my-rule-name cursor
Load 'my-rule-name' for Claude Code IDE globally (updates ~/.claude/CLAUDE.md)
vibe-rules load my-rule-name claude-code --global
Alias: vibe-rules add my-rule-name claude-code -g
Load 'my-rule-name' for Windsurf (appends to ./.windsurfrules)
vibe-rules load my-rule-name windsurfLoad into the project's unified .rules file
vibe-rules load unified my-unified-ruleLoad into a specific custom target path
vibe-rules load my-rule-name cursor -t ./my-project/.cursor-rules/custom-rule.mdc
`Arguments:
-
: The name of the rule saved in the local store (~/.vibe-rules/rules/).
- : The target editor/tool type. Supported: cursor, windsurf, claude-code, gemini, codex, clinerules, roo, vscode.Options:
-
-g, --global: Apply to the editor's global configuration path (if supported, e.g., claude-code, gemini, codex). Defaults to project-local.
- -t, --target : Specify a custom target file path or directory, overriding default/global paths.$3
Convert rules from one editor format to another, supporting both directories and individual files.
`bash
Convert cursor directory to claude-code format
vibe-rules convert cursor claude-code .cursorConvert windsurf file to separate cursor rules
vibe-rules convert windsurf cursor .windsurfrulesConvert single cursor rule to claude-code with custom target
vibe-rules convert cursor claude-code .cursor/rules/my-rule.mdc --target output.mdConvert VSCode directory to unified format with global target
vibe-rules convert vscode unified .github/instructions --global
`Arguments:
-
: Source editor format (cursor, windsurf, claude-code, codex, amp, clinerules, roo, zed, unified, vscode).
- : Target editor format (same options as source).
- : Path to source directory (like .cursor) or file (like CLAUDE.md).Options:
-
-g, --global: Apply to global config path if supported (claude-code, codex, etc.). Defaults to project-local.
- -t, --target : Specify custom target file or directory path.$3
In the evolving AI landscape, prompts and context are becoming increasingly crucial components of development workflows. Just like code libraries, reusable AI rules and prompts are emerging as shareable assets.
We anticipate more NPM packages will begin exporting standardized AI configurations, often via a
llms entry point (e.g., my-package/llms). vibe-rules embraces this trend with the install command.$3
š Seamlessly migrate between editors! š
Convert rules from one editor format to another, supporting both directories and individual files. Perfect for migrating between editors or sharing rules across different development environments.
`bash
Convert cursor rules to claude-code format
vibe-rules convert cursor claude-code .cursorConvert a single windsurf file to separate cursor rules
vibe-rules convert windsurf cursor .windsurfrulesConvert VSCode instructions to unified format
vibe-rules convert vscode unified .github/instructionsConvert with custom target path
vibe-rules convert cursor claude-code .cursor --target my-claude.md
`Supported conversions:
- Directory-based:
cursor ā clinerules ā vscode (individual files)
- File-based: windsurf ā claude-code ā codex ā amp ā zed ā unified (tagged blocks)
- Cross-format: Any format to any other format with automatic metadata preservation$3
ā” The easiest way to integrate shared rule sets! ā”
Install rules _directly from NPM packages_ into an editor's configuration.
vibe-rules automatically scans your project's dependencies or a specified package for compatible rule exports.`bash
Most common: Install rules from ALL dependencies/devDependencies for Cursor
Scans package.json, finds packages with 'llms' export, applies rules.
vibe-rules install cursorInstall rules from a specific package for Cursor
(Assumes 'my-rule-package' is in node_modules)
vibe-rules install cursor my-rule-packageInstall rules from a specific package into a custom target dir for Roo/Cline
vibe-rules install roo my-rule-package -t ./custom-ruleset/Install rules into the project's unified .rules file
vibe-rules install unified my-awesome-prompts
`Add the
--debug global option to any vibe-rules command to enable detailed debug logging during execution. This can be helpful for troubleshooting installation issues.Arguments:
-
: The target editor/tool type (mandatory). Supported: cursor, windsurf, claude-code, gemini, codex, clinerules, roo, vscode.
- [packageName] (Optional): The specific NPM package name to install rules from. If omitted, vibe-rules scans all dependencies and devDependencies in your project's package.json.Options:
-
-g, --global: Apply to the editor's global configuration path (if supported).
- -t, --target : Specify a custom target file path or directory.How
install finds rules:1. Looks for installed NPM packages (either the specified one or all dependencies based on whether
[packageName] is provided).
2. Attempts to dynamically import a module named llms from the package root (e.g., require('my-rule-package/llms') or import('my-rule-package/llms')). Handles both CommonJS and ESM.
3. Examines the default export of the llms module:
- If it's a string: Treats it as a single rule's content.
- If it's an array: Expects an array of rule strings or rule objects.
- Rule Object Shape: { name: string, rule: string, description?: string, alwaysApply?: boolean, globs?: string | string[] } (Validated using Zod). Note the use of rule for content.
4. Uses the appropriate editor provider (cursor, windsurf, etc.) to format and apply each found rule to the correct target path (respecting -g and -t options). Metadata like alwaysApply and globs is passed to the provider if present in a rule object.
5. Important: Rules installed this way are applied _directly_ to the editor configuration; they are not saved to the common local store (~/.vibe-rules/rules/). Use vibe-rules save for that.$3
Remove a previously installed rule from a specific editor configuration.
`bash
Remove a Cursor rule file
vibe-rules uninstall my-package_my-rule cursorRemove from Claude Code (local project)
vibe-rules uninstall my-package_my-rule claude-codeRemove from Codex (global)
vibe-rules uninstall my-package_my-rule codex --globalRemove from Zed / unified .rules file
vibe-rules uninstall my-package_my-rule zedRemove from VSCode instructions directory
vibe-rules uninstall my-package_my-rule vscode
`Arguments:
-
: The fully-qualified rule name as applied (typically )
- : Target editor type. Supported: cursor, windsurf, claude-code, codex, amp, clinerules, roo, zed, unified, vscode.Options:
-
-g, --global: Remove from the editor's global configuration path when supported (claude-code, codex).
- -t, --target : Custom target path overriding default/global paths.Supported Editors & Formats
vibe-rules automatically handles formatting for:- Cursor (
cursor):
- Creates/updates individual .mdc files in ./.cursor/rules/ (local) or ~/.cursor/rules/ (global, if supported via -t).
- Uses frontmatter for metadata (description, alwaysApply, globs).
- Windsurf (windsurf):
- Appends rules wrapped in tags to ./.windsurfrules (local) or a target file specified by -t. Global (- g) is not typically used.
- Claude Code (claude-code):
- Appends/updates rules within XML-like tagged blocks in a section in ./CLAUDE.md (local) or ~/.claude/CLAUDE.md (global).
- Each rule is encapsulated in tags like within the single markdown file.
- Supports metadata formatting for alwaysApply and globs configurations.
- Gemini (gemini):
- Appends/updates rules within XML-like tagged blocks in a section in ./GEMINI.md (local) or ~/.gemini/GEMINI.md (global).
- Each rule is encapsulated in tags like within the single markdown file.
- Supports metadata formatting for alwaysApply and globs configurations.
- Codex (codex):
- Appends/updates rules within XML-like tagged blocks in a section in ./AGENTS.md (local) or ~/.codex/AGENTS.md (global).
- Each rule is encapsulated in tags like within the single markdown file.
- Supports metadata formatting for alwaysApply and globs configurations.
- Codex File Hierarchy: Codex looks for AGENTS.md files in this order: ~/.codex/AGENTS.md (global), AGENTS.md at repo root (default), and AGENTS.md in current working directory (use --target for subdirectories).
- Amp (amp):
- Manages rules within a single AGENT.md file in the project root using XML-like tagged blocks.
- Each rule is encapsulated in tags like without requiring wrapper blocks (similar to ZED).
- Local only: Does not support global files or subdirectory configurations.
- Supports metadata formatting for alwaysApply and globs configurations.
- Cline/Roo (clinerules, roo):
- Creates/updates individual .md files within ./.clinerules/ (local) or a target directory specified by -t. Global (-g) is not typically used.
- ZED (zed):
- Manages rules within a single .rules file in the project root using XML-like tagged blocks.
- Each rule is encapsulated in tags like without requiring wrapper blocks.
- Follows the unified .rules convention and supports metadata formatting for alwaysApply and globs configurations.
- VSCode (vscode):
- Creates/updates individual .instructions.md files within ./.github/instructions/ (project-local).
- Uses YAML frontmatter with applyTo field for file targeting.
- Rule name and description are included in the markdown content, not frontmatter.
- Note: Due to VSCode's limitations with multiple globs in the applyTo field, all rules use applyTo: "**" for universal application and better reliability.
- Unified (unified):
- Manages rules within a single .rules file in the project root.
- Ideal for project-specific, centralized rule management.
- See the Unified .rules File Convention for detailed format and usage.Development
`bash
Clone the repo
git clone https://github.com/your-username/vibe-rules.git
cd vibe-rulesInstall dependencies
bun installRun tests (if any)
bun testBuild the project
bun run buildLink for local development testing
bun link
Now you can use 'vibe-rules' command locally
``MIT